Skip to content

Commit c8ea831

Browse files
committed
✨ 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.
1 parent 6071547 commit c8ea831

27 files changed

Lines changed: 3923 additions & 148 deletions

‎architecture.md‎

Lines changed: 76 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6450,13 +6450,40 @@ printed location, those four answer from what they produced, and the write after
64506450
the question happens for the first time.
64516451

64526452
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.
64606487

64616488
Only live new work needs the environment. Answering a completed operation
64626489
performs no path canonicalization, no ambient discovery, no lease acquisition,
@@ -6471,11 +6498,15 @@ an entry was working is not permission to work there.
64716498
What does the retaining is established by core initialization, once per
64726499
executing entry, inside the scope the invocation already owns — registered by
64736500
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.
64796510

64806511
Recording is ordinary ancestor-max `Files` middleware over the one document
64816512
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
65336564
while somebody else is working, and recording "refused" would make a temporary
65346565
condition the permanent answer every later continuation replays.
65356566

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.
65406598

65416599
### What the screen teaches, and what leaving it costs
65426600

@@ -6912,7 +6970,8 @@ Status is measured against main.
69126970
| `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 |
69136971
| 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 |
69146972
| 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 |
69166975
| 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 |
69176976
| 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 |
69186977
| 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. |

‎packages/cli/src/compiled-repl.ts‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,12 @@ import { homedir } from "node:os";
1414
import { sep } from "node:path";
1515
import process from "node:process";
1616
import type { Operation } from "effection";
17+
import type { HelperAssembly } from "@executablemd/git/credential-helper";
1718
import { installReplHost, platformDataRoot } from "./repl-assembly.ts";
1819
import { useCompiledReplTerminal } from "./compiled-repl-terminal.ts";
1920
import { useDenoReplRepositories } from "./deno-repositories.ts";
2021

21-
export function* useCompiledRepl(): Operation<void> {
22+
export function* useCompiledRepl(helper: HelperAssembly): Operation<void> {
2223
yield* installReplHost({
2324
dataRoot: () => platformDataRoot(process.platform, homedir(), process.env, sep),
2425
// Sixteen random bytes as hex: URL-safe, opaque, and not derived from a
@@ -28,11 +29,12 @@ export function* useCompiledRepl(): Operation<void> {
2829
appendRecord: (path, record) => appendFile(path, record),
2930
});
3031
// What an entry's execution initializes: the recording of the File and Dir
31-
// work it does in the checkout the person opened the session in. Registered
32-
// here, in the runtime scope the selected REPL host owns, because only a
33-
// runtime-named module may name the native adapter — and registering it
34-
// acquires nothing, so a session that only reads history discovers no
35-
// checkout and takes no lease.
36-
yield* useDenoReplRepositories();
32+
// work it does, and of the managed Repository and Worktree selections that
33+
// say where it does it. Registered here, in the runtime scope the selected
34+
// REPL host owns, because only a runtime-named module may name the native
35+
// adapter and this runtime's own credential-helper assembly — and registering
36+
// it acquires nothing, so a session that only reads history discovers no
37+
// checkout, creates no managed root and takes no lease.
38+
yield* useDenoReplRepositories(helper);
3739
yield* useCompiledReplTerminal();
3840
}

‎packages/cli/src/compiled.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ if (isCredentialHelperMode(process.argv.slice(2))) {
9898
importPluginModule,
9999
() => useDenoWorkflowHost(HELPER),
100100
useMachineSessions(),
101-
useCompiledRepl,
101+
() => useCompiledRepl(HELPER),
102102
);
103103
});
104104
}

‎packages/cli/src/deno-repl.ts‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,12 @@ import { homedir } from "node:os";
1414
import { sep } from "node:path";
1515
import process from "node:process";
1616
import type { Operation } from "effection";
17+
import type { HelperAssembly } from "@executablemd/git/credential-helper";
1718
import { installReplHost, platformDataRoot } from "./repl-assembly.ts";
1819
import { useDenoReplTerminal } from "./deno-repl-terminal.ts";
1920
import { useDenoReplRepositories } from "./deno-repositories.ts";
2021

21-
export function* useDenoRepl(): Operation<void> {
22+
export function* useDenoRepl(helper: HelperAssembly): Operation<void> {
2223
yield* installReplHost({
2324
dataRoot: () => platformDataRoot(process.platform, homedir(), process.env, sep),
2425
// Sixteen random bytes as hex: URL-safe, opaque, and not derived from a
@@ -28,11 +29,12 @@ export function* useDenoRepl(): Operation<void> {
2829
appendRecord: (path, record) => appendFile(path, record),
2930
});
3031
// What an entry's execution initializes: the recording of the File and Dir
31-
// work it does in the checkout the person opened the session in. Registered
32-
// here, in the runtime scope the selected REPL host owns, because only a
33-
// runtime-named module may name the native adapter — and registering it
34-
// acquires nothing, so a session that only reads history discovers no
35-
// checkout and takes no lease.
36-
yield* useDenoReplRepositories();
32+
// work it does, and of the managed Repository and Worktree selections that
33+
// say where it does it. Registered here, in the runtime scope the selected
34+
// REPL host owns, because only a runtime-named module may name the native
35+
// adapter and this runtime's own credential-helper assembly — and registering
36+
// it acquires nothing, so a session that only reads history discovers no
37+
// checkout, creates no managed root and takes no lease.
38+
yield* useDenoReplRepositories(helper);
3739
yield* useDenoReplTerminal();
3840
}

0 commit comments

Comments
 (0)