You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c21e598
Browse filesBrowse the repository at this point in the historyBrowse files
🚀 Publish the current branch to its origin with <Git.Push> (#495)
* 🚀 Publish the current branch to its origin with <Git.Push>
`<Git.Push />` is the first concrete consumer of the shared Git-host
reconciliation engine. It takes no props: the remote is the Repository's own
`origin`, the branch is the one the selected checkout is on, and the commit is
the one that branch points at. Which checkout that is, is decided the way every
other Git operation's place is decided, so the same element inside a `<Dir>` at
a linked worktree publishes that worktree's branch.
The branch it publishes to belongs to a Git host, which no local transaction can
enclose, so it observes before it mutates: a destination already holding this
exact commit is adopted with nothing performed, a destination proven absent is
published to once, and a destination holding another commit is refused. It never
force-pushes and never touches upstream tracking.
The Workspace transaction is opened for the export and closed before the remote
is observed, so a network round trip never holds the run's database, and nothing
is imported or published back — a Push changes the Git host and, locally, only
the journal.
The transport never runs through the selected checkout's own `.git/config`: that
file is retained document data, and a push URL, a URL rewrite, a hook or a
signing program written into it would otherwise choose where this run publishes
and what else runs while it happens. It runs instead in a disposable repository
this provider created, reading the checkout's object database through a
read-only alternate, aimed at the exact private retained locator.
Durable JSON carries the Repository's filtered identity without its checkout
path, the remote, the branch, the full destination ref, the refspec, the local
commit and the observed remote commit. The natural key is that identity with the
remote and the destination ref: the external resource is the origin branch,
while the complete request's fingerprint still discriminates a changed commit.
A checkout whose HEAD names no branch is the one refusal of its own, decided
before a durable effect exists and before anything is contacted.
Refs #370.
* 🔒 Prove the push object graph is contained before it is read
Pointing the control repository's alternate at the checkout's object database
said where native Git starts reading, not where it stops. An object database
names further ones in `objects/info/alternates` and Git follows that chain
transitively, and a symbolic link under `objects/` redirects a read before Git
reports anything about it — both are files inside the Workspace, so a document
could write either and choose which objects a push publishes.
Everything Git may traverse is now proven to resolve inside the object database
this run authenticated. The graph is rejected rather than repaired: deleting an
authored alternate would publish from a database the run edited on the author's
behalf, and ignoring one would publish from a database that is not the one it
verified.
The proof is the live provider's first act — after every local authority check
and before the first remote observation — and it happens on no other path. A
completed replay reaches no provider, so it derives and parses its retained
record without walking a graph, building a control repository or running Git for
the push. Deriving the object database is now lazy for the same reason.
A containment failure is a provider-boundary failure: nothing is observed,
nothing is performed, no `git_host_effect` outcome is published, the run
fail-stops, and no path an author wrote is repeated.
Both regressions are proven discriminating by a mutation run: with the two walks
removed, each fails while the other eighteen steps in the suite still pass. The
alternates regression additionally proves the escape was reachable — an ordinary
`git` in the same export resolves the foreign commit through the planted file.
Refs #370.
* 🔒 Read the alternates chain in Git's grammar, not as literal lines
`objects/info/alternates` is not a list of literal lines. Git's
`parse_alt_odb_entry()` recognizes a C-style quoted entry and unquotes it
before it resolves an object directory, and the containment proof added
alongside Push read every non-comment line verbatim.
The two readings can be made to disagree on purpose. `"/elsewhere/objects"` is
an external database to Git and a *relative* path whose first segment is a quote
character to anything comparing spellings — so a real directory of that literal
name, planted inside the authenticated object database, satisfies a literal
reading while Git unquotes the entry and traverses the external database. A
document can write both halves, because both are files inside the Workspace.
Entries are now scanned the way Git scans them: a `#` entry is a comment, an
entry beginning with `"` is unquoted first, and everything else is ordinary
text. Unquoting assembles bytes rather than characters, because an octal escape
names a byte and three of them can name one character, so the path this produces
is the path Git would open. Quoting Git's own reader rejects — unterminated, an
unknown escape, a short octal — is ordinary text to Git and stays ordinary text
here, which keeps a broken-looking entry safely classified instead of quietly
resolved as something it is not. An entry whose exact path cannot be named — a
closing quote with more text after it, bytes that name no path — is refused
rather than approximated, because a path that cannot be named cannot be proven
contained.
Nothing is repaired. The graph is still rejected whole, still before `ls-remote`
and after every local authority check, and still as a provider-boundary failure
that publishes no outcome, repeats no authored path and fail-stops the run.
Completed replay is untouched: it reaches no provider, so it validates no graph,
builds no control repository and runs no Git for the push.
The regression plants the quoted entry *and* the literal decoy that makes the
previous reading accept, and proves the escape is real by resolving the foreign
commit through that entry with an ordinary `git` in the same export. Restoring
the literal-line parser fails that test alone, with the other twenty steps in
the suite still passing.
Refs #370.
* 🔒 Hold the octal escape to Git's grammar, which stops at 3
Git's `unquote_c_style()` cases an octal escape's leading digit as `0`-`3` and
nothing else, because an escape names one byte and `\400` is already 256. So
`\4` through `\7` are escapes Git does not have: the quoting fails and
`parse_alt_odb_entry()` reads the whole entry as ordinary literal text.
The containment scanner accepted any leading octal digit and then assembled the
value through a typed array, so `\457` became 303 truncated to 47 — a `/`. It
saw a path separator where Git sees no escape at all, and one alternates entry
then named two different object directories: extra segments the invented
separator created, which a decoy inside the authenticated database answers for,
and the literal fallback Git actually traverses.
The grammar now stops at 3, and the byte a valid escape names is range-checked
on the way in rather than assumed, so no value can reach a typed array and come
back out as a different character. Everything Git rejects stays on the same
literal fallback Git uses, and an entry whose exact path still cannot be named
fails closed. Quoted entries, the transitive chain, symlink escapes, lazy
completed replay and the withheld failure text are unchanged.
The regression plants both readings of one entry: the decoy chain the
truncating reading resolves, and a database outside the materialization that
only Git's literal fallback reaches. Ordinary Git in the same export resolves a
commit this run never held through it. Widening the leading digit back to `0-7`
fails that test alone, with the other twenty-one steps in the suite still
passing.
Refs #370.
---------
Co-authored-by: Taras Mankovski <[email protected]>
Copy file name to clipboardExpand all lines: architecture.md
+40-1Lines changed: 40 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -62,6 +62,7 @@ Existing documents and code get aligned to this section retroactively.
62
62
| effect transaction | the single atomic SQLite transaction that publishes one Workspace-local mutation together with that effect's journal result |
63
63
| external effect | an effect whose provider-owned outcome cannot participate in the Workspace SQLite transaction and therefore requires a stable identity and provider reconciliation |
64
64
| XMD-mediated HTTP read | one bounded, non-mutating HTTP request an authored document performs through the contextual Fetch capability, whose detached response is retained as an ordinary durable observation. It is distinct from an Agent's own network authority, which it does not grant, and from a reconciled mutating external effect, which it does not claim: an interruption before its record commits may repeat the read |
65
+
| object-source attachment | adapter-private composition data the trusted host builds for exactly one external-effect reconciliation, giving the selected provider authorized live access to local state the frozen request cannot describe — the Git objects a push publishes, and the retained locator it is authorized to reach. It is authenticated against the durable identity it belongs to and proven contained before its first use — the local state behind one can name further state, so the graph a provider could traverse through it is validated rather than assumed — held in that provider's own closure, disposed with the invocation, and is never durable, never part of a natural key and never visible to routing middleware |
65
66
| checkpoint | a completed journal boundary associated with the logical Workspace root visible after that effect |
66
67
| history fork | a new workflow run that replays a compatible journal prefix and continues from its checkpoint and Workspace root under a new immutable document definition |
67
68
| loaded copy | one independently evaluated instance of a package, such as the copy bundled into the binary or a separately installed dependency |
@@ -1026,6 +1027,43 @@ the result retained at the same position, and the provider's answer is parsed at
1026
1027
the terminal before the durable executor returns, so a raw payload becomes a
1027
1028
fixed protocol failure rather than journal content.
1028
1029
1030
+
Some effects need live local state the frozen request cannot describe, and that
1031
+
travels as an object-source attachment rather than as an input. A push needs the
1032
+
Git objects its commit is made of and the destination it may reach; both are
1033
+
built by the trusted host for one reconciliation, authenticated against the
1034
+
retained identity they belong to, and held in the selected provider's closure.
1035
+
Nothing about an attachment reaches the durable request, the natural key or the
1036
+
routing surface, so what discriminates the effect stays the filtered identity a
1037
+
journal may hold while what performs it stays where no replaceable code can
1038
+
address it.
1039
+
1040
+
What an attachment grants access to is authenticated separately from where it
1041
+
came from, because local state can name further local state: a Git object
1042
+
database names further ones through its alternates chain, and a symbolic link
1043
+
under it redirects a read before Git reports anything about it. Such a graph is
1044
+
read in the consuming tool's own grammar rather than as text: Git unquotes a
1045
+
C-style quoted alternates entry before resolving it, so a containment proof that
1046
+
compared spellings could be satisfied by a decoy of that literal name while the
1047
+
traversal went elsewhere. The graph a
1048
+
provider could traverse is therefore proven contained on the live provider's
1049
+
first use of the attachment — before any external observation, and on no other
1050
+
path, so a completed replay reaches no provider and performs no such proof. A
1051
+
graph that leaves what the run authenticated is a boundary failure: it publishes
1052
+
no outcome, repeats no authored path, and activates fail-stop. It is rejected
1053
+
rather than repaired, because editing authored state to make it acceptable would
1054
+
publish from state the run wrote on the author's behalf. The Workspace transaction such an effect opens is read-only and is
1055
+
closed before the host is observed: no transaction is claimed across the
1056
+
Workspace and the external service, and reconciliation rather than a distributed
1057
+
transaction is what makes an interrupted attempt reach the host once.
1058
+
1059
+
A provider that needs a program must also not inherit configuration the run
1060
+
merely stores. A checkout's `.git/config` is retained document data, and several
1061
+
ordinary settings in one name a destination or a program — a push URL, a URL
1062
+
rewrite, a hook, a credential helper, a signing program. The Deno push provider
1063
+
therefore runs its transport in a disposable repository of its own that reads
1064
+
the selected checkout's object database through a read-only alternate, and aims
1065
+
it at the exact private retained locator rather than at a configured remote.
1066
+
1029
1067
Only an answer the terminal accepted decides the effect. A conflict, a permanent
1030
1068
ambiguity and a temporary unavailability so accepted publish the effect's failed
1031
1069
result and replay as the same fixed local failure, rebuilt from its closed name
@@ -2225,7 +2263,7 @@ Status is measured against main.
2225
2263
| caller-owned storage transaction | publishes several changes, including journal events, in one transaction nothing else enlists in | built on main |
2226
2264
| live durable-operation coordinator | explicitly coordinates structured live execution with existing Yield publication while leaving replay and callback effects unchanged | built on the #365 stack |
2227
2265
| Workspace coordination API | fails closed by default; replaceable context routes only a one-use provider selection, while the selected provider directly invokes an execution-owned credentialed capability for execution, publication and failure activation | built on the #365 stack; the Deno provider installs an adapter-private atomic handler |
2228
-
| shared Git-host reconciliation | reconciles Git push, pull-request creation and issue creation through one provider-neutral state machine journaled as `git_host_effect` — Prompt is not a consumer and keeps its own Agent-provider contract: run and expansion identity derived by the engine, observation before mutation, adoption of a proven compatible completion, one performance of a proven absence, refusal of conflict and permanent ambiguity, temporary unavailability as its own ordinary failure, and a provider free to support only some kinds; routing is one request-only contextual operation carrying no completion authority, and only an answer the invocation's own terminal accepted can author a journaled outcome | built on the #297 stack; `Git.Push`, pull request and issue components are its consumers, unbuilt (#370, #295, #296) |
2266
+
| shared Git-host reconciliation | reconciles Git push, pull-request creation and issue creation through one provider-neutral state machine journaled as `git_host_effect` — Prompt is not a consumer and keeps its own Agent-provider contract: run and expansion identity derived by the engine, observation before mutation, adoption of a proven compatible completion, one performance of a proven absence, refusal of conflict and permanent ambiguity, temporary unavailability as its own ordinary failure, and a provider free to support only some kinds; routing is one request-only contextual operation carrying no completion authority, and only an answer the invocation's own terminal accepted can author a journaled outcome | built on the #297 stack; `Git.Push` is its first consumer, built on the #370 stack, while pull request and issue components remain unbuilt (#295, #296) |
2229
2267
| explicit WorkflowRun journal route | binds one already-filtered publication to one exact active transaction and otherwise uses ordinary serialized journal storage | built on the #365 stack |
2230
2268
|`API.Service` / `startService()`| creates an authenticated, supervised loopback service attachment through a provider-neutral operation | built on main |
2231
2269
| foreground command routing and retention | forwards a child's channels live, captures stdout for a `<Capture as>` region, and retains output only when the host asked for a record | built on the #441 stack |
@@ -2242,6 +2280,7 @@ Status is measured against main.
2242
2280
| implicit workflow Workspace | retains provider-neutral filesystem, repository and attachment state by run ID | document filesystem built on the #366 stack and Repository/Worktree composition on the #293 stack; process capabilities unbuilt (#218) |
2243
2281
|`<Repository>` / `<Worktree>` / `<Dir>` composition | names a Git repository and its linked checkouts inside the run-owned Workspace, installs each as contextual working directory, and retains creation identity beside the retained Git bytes | built on the #293 stack, Deno provider only |
2244
2282
| transactional Git effects (`Git.Switch` / `Git.Add` / `Git.Commit`) | publish local Git mutations with their journal result; the enclosing Repository and the contextual working directory select which retained checkout one runs in, and neither observation carries authority — the observed record is compared with the retained row and the directory with the checkouts that row holds, so a failure of authority, of retained state or of an unrecognized native condition fails the run instead of publishing a result | built on the #294 stack, Deno provider only |
2283
+
|`Git.Push`| publishes the selected checkout's exact current named branch and commit to the same branch on the retained Repository's canonical `origin`, reconciled through the shared Git-host state machine rather than through a Workspace transaction: no props and no component result, no force, no upstream mutation and no implicit staging or committing; the durable request and record carry the Repository's filtered identity without its checkout path, and the transport runs in a provider-owned isolated control repository reading the checkout's objects through an object-source attachment whose alternates chain and object tree are proven contained before the first remote observation, aimed at the exact private retained locator | built on the #370 stack, Deno provider only |
2245
2284
| workflow lifecycle inspection and control | reads status/list/history without advancing a run, enforces the executor lock, refuses live cancellation, cancels non-live runs under that lock and deletes retained state | built on the #367 stack |
2246
2285
| historical authored source | retains an authored durable operation's normalized `SourcePosition` beside its identity, and history parses it or refuses the entry | built on the #367 stack |
2247
2286
| history fork | creates a new run from one compatible checkpoint and retained Workspace root | defined in `specs/workflow-workspace-spec.md`, unbuilt (#368) |
0 commit comments