11/**
2- * The ACP adapters a workflow run executes, and how they reach the disk
3- * (`packages/acp/vendor/adapters/PROVENANCE.md`).
4- *
5- * A workflow Prompt needs an adapter that names the turn it just completed, on
6- * `_meta`. No published adapter does yet, so this repository carries one npm
7- * tarball per provider — packed from an exact patched upstream commit by that
8- * project's own build — and runs those instead of whatever `npx` would resolve.
9- *
10- * ## Why the bytes travel in the module graph
11- *
12- * A tarball on disk is unreachable from a compiled binary and from the npm
13- * artifact. The same bytes are therefore carried as a generated module, which
14- * every distribution inlines identically, and this module writes them out. One
15- * mechanism, so "the source tree, the npm package and the binary all run the
16- * same adapter" is a fact rather than three arrangements that happen to agree.
17- *
18- * ## Content-addressed, so identity is the location
19- *
20- * A snapshot materializes under its own SHA-256. Two runs asking for the same
21- * adapter name the same directory, a changed snapshot names a different one,
22- * and nothing has to decide whether an existing directory is current — the
23- * question does not arise.
24- *
25- * ## Identity is not the launch path
26- *
27- * Two different things are needed, and conflating them was a defect: an adapter
28- * has a **stable identity** — its provider, package, version and snapshot
29- * digest — and a **host-local launch path** under whatever root this machine
30- * materialized into.
31- *
32- * Only the identity is durable. It is what a retained Agent session records and
33- * what a sealed artifact carries, so two machines running the same snapshot
34- * agree, and a run exported from one is readable on the other. The path appears
35- * nowhere durable: it names a directory that exists on one host, and putting it
36- * in an artifact would make where a file happened to live a compatibility term.
37- *
38- * The launch path is quoted, because a root containing a space is an ordinary
39- * thing on a developer's machine and an unquoted command would split there.
40- *
41- * ## Published atomically, verified before use
42- *
43- * Materialization happens in a private temporary directory and is published by
44- * one rename. A concurrent run either wins that rename or finds the directory
45- * already there — both then verify before using it, so nobody executes a tree
46- * another process is still filling.
47- *
48- * Replacing an *abandoned* tree is the one step that cannot be done by rename
49- * alone, because a rename will not overwrite a non-empty directory. Removing it
50- * first is a decision that goes stale: another attempt may publish a valid tree
51- * between the observation and the removal, and deleting that would pull the
52- * files out from under an adapter already running. So recovery is serialized on
53- * an exclusive claim, and the holder re-checks under it before removing
54- * anything.
55- *
56- * The claim is a ticket: the directory `claims/<n>`, taken by renaming a
57- * prepared directory onto that name, which only one attempt can win and which
58- * is never handed out a second time.
59- *
60- * Two properties come from that, and the claim needs both. Because numbers are
61- * never reissued, finishing a dead holder's ticket can only ever act on the
62- * exact ticket that was inspected. Because they are taken in ascending order,
63- * an attempt arriving later cannot obtain a lower number, so it cannot come to
64- * precede a holder that has already been elected.
65- *
66- * The holder is the lowest ticket still outstanding. Releasing is marking one
67- * finished, and a process killed mid-recovery leaves a ticket whose owner a
68- * later attempt reads as dead and finishes on its behalf.
69- *
70- * ## It refuses; it never falls back
71- *
72- * A digest that does not match, an extraction that fails, a dependency install
73- * that fails, a missing entry file: each raises. Running the published adapter
74- * instead would be running one that emits no token, which is the state this
75- * exists to leave — silently, and after the run had already been told it was
76- * continuing an exact conversation.
2+ * Materialize the patched ACP adapters that report completed-turn `_meta`
3+ * (`packages/acp/vendor/adapters/PROVENANCE.md`). Their npm tarballs come from
4+ * exact patched upstream commits and travel as a generated module so source, npm
5+ * and compiled distributions execute identical bytes.
6+ *
7+ * A snapshot materializes under its SHA-256. Durable identity is provider, package,
8+ * version and digest; the quoted host-local launch path is never retained in a
9+ * session or sealed artifact.
10+ *
11+ * Stage privately, publish by one rename and verify the published tree before
12+ * use, including when another attempt won. Recovery of an abandoned non-empty
13+ * tree requires exclusive ownership of recovery and a fresh check before
14+ * removal, otherwise a stale observation could delete another process's newly
15+ * published valid adapter.
16+ *
17+ * Recovery tickets are prepared directories atomically renamed to `claims/<n>`.
18+ * Tickets increase monotonically and are never reused: late arrivals cannot
19+ * precede an elected holder, and finishing a dead holder cannot affect a later
20+ * ticket. The lowest unfinished ticket owns recovery; release marks it
21+ * finished, and a later attempt may finish a dead owner's ticket.
22+ *
23+ * Digest, extraction, installation or missing-entry failures raise. Falling back
24+ * to a published adapter would lose the turn identity continuation depends on.
7725 */
7826
7927import { ensureDir , exists , readTextFile , rm , writeTextFile } from "@effectionx/fs" ;
@@ -120,10 +68,10 @@ const RECOVERY_ATTEMPTS = 400;
12068const OWNER = "owner" ;
12169const DONE = "done" ;
12270
123- /** A ceiling on ticket numbers, so a pathological claims directory cannot spin. */
71+ /** A ceiling on ticket numbers, so a pathological recovery-ticket directory cannot spin. */
12472const MAX_TICKETS = 10_000 ;
12573
126- /** Who holds a recovery claim , so a later attempt can tell live from dead. */
74+ /** Who holds a recovery ticket , so a later attempt can tell live from dead. */
12775interface RecoveryOwner {
12876 readonly pid : number ;
12977 readonly host : string ;
@@ -150,7 +98,7 @@ function parseOwner(raw: string): RecoveryOwner | undefined {
15098 * Signal 0 asks without delivering anything. `EPERM` means it exists and
15199 * belongs to somebody else, which is still alive; only `ESRCH` means gone. An
152100 * answer this cannot interpret is treated as alive, so an unreadable state
153- * never becomes a reason to take somebody's claim .
101+ * never becomes a reason to take somebody's recovery ownership .
154102 */
155103function alive ( pid : number ) : boolean {
156104 try {
@@ -431,10 +379,10 @@ export function createEmbeddedAdapters(
431379 * on. An attempt arriving later cannot obtain a number below one already
432380 * taken, so it cannot come to sit ahead of a holder.
433381 *
434- * Ordering names by time could not offer that. Two claims made in the same
435- * millisecond were separated only by the random part of their names, and a
436- * clock adjustment could hand a later arrival an earlier name — either way an
437- * elected holder could be preceded after the fact.
382+ * Ordering names by time could not offer that. Two recovery tickets issued in
383+ * the same millisecond were separated only by the random part of their names,
384+ * and a clock adjustment could hand a later arrival an earlier name — either
385+ * way an elected holder could be preceded after the fact.
438386 */
439387 function * takeTicket ( claims : string ) : Operation < number > {
440388 yield * ensureDir ( claims ) ;
@@ -465,15 +413,15 @@ export function createEmbeddedAdapters(
465413 }
466414
467415 /**
468- * Whether this attempt now holds the claim .
416+ * Whether this attempt now owns recovery .
469417 *
470418 * The holder is the lowest ticket still outstanding, so every number below
471- * this attempt's own is examined in order: a finished ticket is passed over, a
472- * ticket whose owner is a dead process on this host is finished here, and a
419+ * this attempt's own is examined in order: a finished ticket is passed over,
420+ * a ticket whose owner is a dead process on this host is finished here, and a
473421 * live owner, an owner on another machine, or a record that cannot be read
474422 * each stop the election where it stands. The last one says so, because
475423 * refusing to act on what it cannot read is the only safe reading of somebody
476- * else's claim .
424+ * else's recovery ticket .
477425 *
478426 * Finishing a dead holder's ticket is safe for the reason the election is:
479427 * the number is never reissued, so this can only ever act on the exact ticket
@@ -518,17 +466,18 @@ export function createEmbeddedAdapters(
518466 }
519467
520468 /**
521- * Replace an abandoned tree at the target, holding an exclusive claim.
469+ * Replace an abandoned tree at the target, under exclusive ownership of
470+ * recovery.
522471 *
523- * Reached only when the rename failed and what is there does not verify. The
524- * claim makes "check, then remove" one decision instead of two: without it, a
525- * second attempt could publish a valid tree in the gap and this one would
526- * delete it, taking the files out from under an adapter that had already
527- * resolved and might already be running.
472+ * Reached only when the rename failed and what is there does not verify.
473+ * Exclusive recovery ownership makes "check, then remove" one decision
474+ * instead of two: without it, a second attempt could publish a valid tree in
475+ * the gap and this one would delete it, taking the files out from under an
476+ * adapter that had already resolved and might already be running.
528477 *
529- * An attempt that does not hold the claim never removes anything. It waits
530- * and answers from what the holder published — including when the wait ends
531- * with this attempt elected, because a holder finishes its ticket only after
478+ * An attempt that does not own recovery never removes anything. It waits and
479+ * answers from what the holder published — including when the wait ends with
480+ * this attempt elected, because a holder finishes its ticket only after
532481 * publishing.
533482 */
534483 function * recover (
@@ -690,9 +639,9 @@ export function createEmbeddedAdapters(
690639 *
691640 * A closed registry was the wrong shape for the same reason. It made "this
692641 * build has no Codex snapshot problem to solve for Gemini" into "this build
693- * refuses Gemini", which is a much larger claim than the one being made, and it
694- * would have changed the retained identity of agents the checkpoint work has
695- * nothing to say about.
642+ * refuses Gemini", which is a much broader restriction than the one being made,
643+ * and it would have changed the retained identity of agents the checkpoint work
644+ * has nothing to say about.
696645 *
697646 * The overlay is *qualified*: an embedded provider never falls through. A
698647 * snapshot that cannot be verified or materialized refuses the agent, and does
0 commit comments