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 c8ea831
Browse filesBrowse the repository at this point in the historyBrowse files
✨ Select managed repositories and worktrees in the REPL (#181, 2/6)
A REPL entry can now write `<Repository name=".." url={..}>` and
`<Worktree name=".." branch={..}>`, work in the checkout it selected, leave at
a question and continue from what it recorded. The selector is the ordinary
managed one `xmd run` already uses, with its own creation, compatible-reuse,
conflict and interrupted-adoption policy; what this adds is a small routing
record of what the selector answered.
A completed selection is answered from that record: no selector call, no clone,
no `worktree add`, no sidecar read, no credential and no lock. It says where the
entry was working and nothing about what the checkout now holds, so continuing
works after somebody has edited or deleted it, while genuinely new work meets
today's filesystem and gets today's answer.
Two holds answer two questions. One entry at a time *owns* a managed slot, held
until teardown and reacquired lazily by the first new operation inside a
restored placement; separately, one entry at a time *changes* one repository,
which a new `<Worktree>` selector and a new mutation take and a read never
does.
Files routing gains managed coverage beside PR 1's ambient route, most specific
first, with the managed checkout root itself covered so a self-closing
`<Worktree>` and a sibling `<Dir>` are retained. Two bounded ownership
corrections arm cleanup before the native acquisition it releases:
`writeMetadata`'s exclusive sibling and `denoRepositoryHost.useDirectory`'s
temporary directory.
Local Git, publication and issues remain unavailable in an entry, generated
`<Repository>`, `<Worktree>` and `<Dir>` still refuse preflight, and nothing
inventories, snapshots, restores or deletes a managed checkout.
Copy file name to clipboardExpand all lines: architecture.md
+76-17Lines changed: 76 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6450,13 +6450,40 @@ printed location, those four answer from what they produced, and the write after
6450
6450
the question happens for the first time.
6451
6451
6452
6452
Four operations are retained and no others: a `<File>` text read, a `<File>`
6453
-
write, a `<File.Delete />`, and the directory a `<Dir>` ensures, each in the
6454
-
ambient checkout the entry was started in. A read is retained because a document
6455
-
binds its text and a continuation has to offer the same binding; a glob, a path
6456
-
check and a temporary directory bind nothing a continuation must answer again,
6457
-
and are left alone. A call outside that checkout is ordinary filesystem
6458
-
behavior, recorded by nothing — a record would place the call in a checkout it
6459
-
is not in — so it runs again during a partial continuation.
6453
+
write, a `<File.Delete />`, and the directory a `<Dir>` ensures, each in a
6454
+
checkout this entry is working in — the ambient one it was started in, or a
6455
+
managed one it selected. A read is retained because a document binds its text
6456
+
and a continuation has to offer the same binding; a glob, a path check and a
6457
+
temporary directory bind nothing a continuation must answer again, and are left
6458
+
alone. A call outside every such checkout is ordinary filesystem behavior,
6459
+
recorded by nothing — a record would place the call in a checkout it is not in —
6460
+
so it runs again during a partial continuation. A managed placement is looked
6461
+
for first and the most specific one wins; the ambient route answers everything no
6462
+
placement covers, so an entry that selects nothing works exactly as it did
6463
+
before.
6464
+
6465
+
Selection is retained on the same terms. `<Repository>` and `<Worktree>` call
6466
+
the *ordinary* managed selector — the same creation, compatible-reuse, conflict
6467
+
and interrupted-adoption policy `xmd run` gets — and what the selector answered
6468
+
is recorded as a small routing record: the canonical managed root, the checkout
6469
+
root, the common Git directory, the credential-free repository identity, the
6470
+
display name and the owner checkout. A root-level `<Worktree>` records the
6471
+
Repository it belongs to as its own answer, so a continuation learns that
6472
+
without asking Git. Nothing else is retained: no origin, no publication
6473
+
evidence, no object source, no Git session, no authentication, no lock and no
6474
+
opaque selection identifier.
6475
+
6476
+
Answering a completed selection calls no selector, clones nothing, adds no
6477
+
worktree, reads no sidecar, opens no credential and takes no lock. The parsed
6478
+
facts are held to the call they stand at with pure arithmetic — the result
6479
+
describes the request it is named by, and the checkout it names is the one this
6480
+
request's own slot would hold under the root the result itself records — and the
6481
+
root is never recanonicalized against today's disk to check a historical answer.
6482
+
The entry then registers the placement privately and mints a fresh selection for
6483
+
this execution; rebuilding that membership is passive and acquires nothing, and
6484
+
an editable Repository context cannot redirect native work because every
6485
+
operation authenticates the selection it was handed against that private state
6486
+
first.
6460
6487
6461
6488
Only live new work needs the environment. Answering a completed operation
6462
6489
performs no path canonicalization, no ambient discovery, no lease acquisition,
@@ -6471,11 +6498,15 @@ an entry was working is not permission to work there.
6471
6498
What does the retaining is established by core initialization, once per
6472
6499
executing entry, inside the scope the invocation already owns — registered by
6473
6500
the selected REPL host rather than by the ordinary run Plugin, because an entry
6474
-
installs no managed root, credential helper or Git host. Everything it acquires
6475
-
belongs to that execution: the Git session, its isolation directory, the ambient
6476
-
discovery and the lease all end when the entry does. A passive view — a settled
6477
-
history, a frozen position, a refused route — initializes nothing, discovers no
6478
-
checkout and takes no lease.
6501
+
installs the Repository selection handlers and the file recorder and nothing
6502
+
else the ordinary provider would bring with it. The managed root and the
6503
+
credential-helper assembly are copied where that host is installed, before any
6504
+
entry runs, so what an entry initializes with is what the command selected
6505
+
rather than a field somebody changed afterwards. Everything it acquires belongs
6506
+
to that execution: the Git session, its isolation directory, the managed root,
6507
+
the ambient discovery and every hold all end when the entry does. A passive view
6508
+
— a settled history, a frozen position, a refused route — initializes nothing,
6509
+
discovers no checkout, creates no managed root and takes no hold.
6479
6510
6480
6511
Recording is ordinary ancestor-max `Files` middleware over the one document
6481
6512
filesystem, so what is kept is the result the whole composition answered with,
@@ -6533,10 +6564,37 @@ and that refusal is never saved as a completed result: a lease is busy only
6533
6564
while somebody else is working, and recording "refused" would make a temporary
6534
6565
condition the permanent answer every later continuation replays.
6535
6566
6536
-
There is no managed checkout here, no `<Repository>` or `<Worktree>` selection,
6537
-
no local Git operation and nothing external: those components stay declared
6538
-
where they already are and refuse through their own unchanged missing-provider
6539
-
defaults.
6567
+
A managed slot has its own hold, and the two answer different questions. The
6568
+
**placement** hold says one entry at a time owns a managed checkout: a live
6569
+
selection takes it before it inspects or creates anything, and it lasts until
6570
+
the entry is torn down so a later `<Dir>` inside the same entry is still
6571
+
protected. A completed replay takes none, and the first genuinely new file
6572
+
operation inside a restored placement — a read included — reacquires that slot
6573
+
then, without rerunning the selector or looking at what the checkout holds. A
6574
+
fresh selection of a slot another entry holds keeps the ordinary immediate
6575
+
refusal, and that refusal is never written down: contention is decided before
6576
+
the recorded selection begins. Where the reacquisition happens inside a file
6577
+
operation, the condition travels as a fatal stale-state failure rather than as
6578
+
that operation's recorded outcome. The **mutation** hold above is the other one:
6579
+
only a new `<Worktree>` selector and a new write, deletion or directory take it,
6580
+
the Worktree before its selector because a linked checkout writes administration
6581
+
every checkout of that repository shares, and when both are needed the slot
6582
+
comes first.
6583
+
6584
+
A selection's durable append completes before its path is bound or its body
6585
+
expands. Native work may finish without being acknowledged: on cancellation
6586
+
before the append no completion is manufactured, and the continuation runs that
6587
+
selection live, where the existing partial-creation policy decides what the slot
6588
+
now holds — adoption only under the stricter proof, refusal otherwise, and never
6589
+
deletion or repair. An acknowledged placement never enters that path again. A
6590
+
failed append fences later work with the first persistence failure, with no
6591
+
success result and no compensating Close.
6592
+
6593
+
There is no local Git operation here and nothing external: `<Git.Add>`,
6594
+
`<Git.Switch>`, `<Git.Commit>`, `<Git.Push>`, `<Issue>` and `<PullRequest>` stay
6595
+
declared where they already are and refuse through their own unchanged
6596
+
missing-provider defaults. Nothing inventories the managed root, snapshots a
6597
+
checkout's contents or restores one.
6540
6598
6541
6599
### What the screen teaches, and what leaving it costs
6542
6600
@@ -6912,7 +6970,8 @@ Status is measured against main.
6912
6970
|`GitQuery.resolve()`| verifies and resolves one Git revision expression contextually [Interface and evidence](specs/workflow-spec.md#7-the-git-capability--moved). | built on main |
6913
6971
| workflow run storage | creates or compatibly finds one run by public run ID, retains its identity, state, document executions and filtered journal, and validates immutable Workspace roots through one provider-owned connection entry [Invariant](#workflow-run-storage); [Interface and evidence](specs/workflow-spec.md#9-retained-run-storage). | built on the #365 stack; the CLI lifecycle reaches it on the #366 stack |
6914
6972
| caller-owned storage transaction | publishes several changes, including journal events, in one transaction nothing else enlists in [Invariant](#one-database-at-a-time-and-a-transaction-a-caller-can-hold). | built on main |
6915
-
| REPL entry retained file work | one executing REPL entry's own recording, established by core initialization in the scope the invocation owns and ending with it: it retains the `<File>` reads, `<File>` writes, `<File.Delete />` deletions and `<Dir>` ensures that land inside the ambient checkout the entry was started in, authored and admitted-generated alike, because both cross the one document filesystem. A completed operation answers from its saved result without live path canonicalization, ambient discovery, a lease, a permission lookup or a filesystem call — so only *new* work needs the environment, a continuation still binds the text its read answered with while the file says something else, and a new entry reading that path sees what is there now. A record's name is the digest of the record version, the operation kind and the complete received request, so two equal requests in one entry are one name at two ordered positions and the durable engine's positional matching tells them apart; equal work in two entries is the same name, and each entry executing against its own stream segment is what keeps those apart. Recording is ordinary ancestor-max `Files` middleware, so a provider beneath that answers directly or transforms and delegates is kept as provider behavior while the received request stays the operation's identity. A shared Git directory admits one live *mutating* entry at a time, held lazily for as long as the execution lasts and refused rather than queued; no read acquires it, so a new read proceeds while another entry holds it. There is no managed checkout, no `<Repository>` or `<Worktree>` selection, no local Git operation and nothing external here; work outside the checkout stays ordinary and unrecorded, and a passive reading initializes nothing [Reference](#what-one-entry-retains-about-the-checkout-it-is-standing-in). | built on the #181 stack |
6973
+
| REPL entry retained file work | one executing REPL entry's own recording, established by core initialization in the scope the invocation owns and ending with it: it retains the `<File>` reads, `<File>` writes, `<File.Delete />` deletions and `<Dir>` ensures that land inside a checkout the entry is working in — the ambient one it was started in, or a managed one it selected — authored and admitted-generated alike, because both cross the one document filesystem. A completed operation answers from its saved result without live path canonicalization, ambient discovery, a lease, a permission lookup or a filesystem call — so only *new* work needs the environment, a continuation still binds the text its read answered with while the file says something else, and a new entry reading that path sees what is there now. A record's name is the digest of the record version, the operation kind and the complete received request, so two equal requests in one entry are one name at two ordered positions and the durable engine's positional matching tells them apart; equal work in two entries is the same name, and each entry executing against its own stream segment is what keeps those apart. Recording is ordinary ancestor-max `Files` middleware, so a provider beneath that answers directly or transforms and delegates is kept as provider behavior while the received request stays the operation's identity. A shared Git directory admits one live *mutating* entry at a time, held lazily for as long as the execution lasts and refused rather than queued; no read acquires it, so a new read proceeds while another entry holds it. There is no local Git operation and nothing external here; work outside every checkout the entry is working in stays ordinary and unrecorded, and a passive reading initializes nothing [Reference](#what-one-entry-retains-about-the-checkout-it-is-standing-in). | built on the #181 stack |
6974
+
| REPL entry retained selection | one executing REPL entry's own `<Repository>` and `<Worktree>` selections, recorded beside its file work as small routing records: the canonical managed root, the checkout root, the common Git directory, the credential-free repository identity, the display name and the owner checkout, with a root-level `<Worktree>`'s ambient owner recorded as its own answer. The selector is the ordinary managed one, with its own creation, compatible-reuse, conflict and interrupted-adoption policy; what this adds is that a completed selection answers from its record, calling no selector and reaching no clone, `worktree add`, sidecar, credential or lock — so a continuation works in a checkout somebody has since changed or removed, while only new work meets today's filesystem. Parsed facts are held to the call they stand at with pure slot arithmetic against the root the record itself carries, registered in entry-private state and minted as a fresh selection, so a copied or edited Repository value can misname a target and never reach one. One entry at a time *owns* a managed slot, held until teardown and reacquired lazily by the first new operation inside a restored placement; that is a different hold from the shared Git directory's mutation lease, which only a new `<Worktree>` selector and a new mutation take. A selection is acknowledged before its path is bound, and native work that was never acknowledged runs live again under the ordinary partial-creation policy [Reference](#what-one-entry-retains-about-the-checkout-it-is-standing-in). | built on the #181 stack |
6916
6975
| live durable-operation coordinator | explicitly coordinates structured live execution with existing Yield publication while leaving replay and callback effects unchanged [Invariant](#live-effect-coordination). | built on the #365 stack |
6917
6976
| 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 [Invariant](#live-effect-coordination). | built on the #365 stack; the Deno provider installs an adapter-private atomic handler |
6918
6977
| shared Git-host reconciliation | Reconciles Git push and pull-request upsert through one request-only boundary whose private terminal alone settles the retained outcome. [Invariant](#external-effects-and-git-host-mutations); [Invariant](#issue-effects). | Built on #297; Push (#370) and PullRequest (#295) consume it. Issue (#296) has its own middleware boundary. |
0 commit comments