@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/substrate/runtime/cross-process/snapshot-reservation.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot-reservation.mjs","names":[],"sources":["../../../../src/substrate/runtime/cross-process/snapshot-reservation.ts"],"sourcesContent":["// `snapshot.reservation` — presence-or-absence semaphore.\n//\n// Architecture § Cross-process safety protocol § Concurrent snapshot:\n//   \"Snapshot requires exclusive control of the stack's container set\n//   (pause-around-commit means peer processes' ready-probes would fail\n//   if uncoordinated). The snapshotting process acquires\n//   `snapshot.reservation` via O_EXCL create. If creation fails (peer\n//   holds it), the snapshot refuses with a structured 'snapshot in\n//   progress by peer pid X' error.\"\n//\n// Discipline:\n//   - Acquire is atomic O_EXCL create with a JSON body carrying\n//     `{ creatorPid, creatorStartTime, createdAt }`.\n//   - Release is `unlink`.\n//   - Orphan sweep: on the next claim, if the body's creator pid is\n//     dead (PID + start-time check), the reservation is unlinked. This\n//     mirrors the roster's stale-PID reclaim.\n//   - Acquire DOES NOT retry — snapshot is a one-shot intent; the\n//     caller surfaces the structured error to the user immediately.\n\nimport { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';\n\nimport { Data, Effect, Scope } from 'effect';\n\nimport { type SnapshotReservation, SnapshotReservationSchema } from '../../cross-process.ts';\nimport { decodeJsonTextSync } from '../runtime-decode.ts';\nimport { checkHolderLiveness } from './liveness.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\nexport class SnapshotReservationHeldError extends Data.TaggedError('SnapshotReservationHeldError')<{\n\treadonly path: string;\n\treadonly holder: SnapshotReservation | null;\n}> {}\n\nexport class SnapshotReservationIoError extends Data.TaggedError('SnapshotReservationIoError')<{\n\treadonly path: string;\n\treadonly cause: unknown;\n}> {}\n\nexport type SnapshotReservationError = SnapshotReservationHeldError | SnapshotReservationIoError;\n\n// -----------------------------------------------------------------------------\n// Codec\n// -----------------------------------------------------------------------------\n\nconst parseReservation = (raw: string): SnapshotReservation | null => {\n\ttry {\n\t\treturn decodeJsonTextSync(SnapshotReservationSchema, raw, {\n\t\t\tsource: 'snapshot.reservation',\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Acquire / release\n// -----------------------------------------------------------------------------\n\nconst ownReservation = (startTime: number): SnapshotReservation => ({\n\tcreatorPid: process.pid,\n\tcreatorStartTime: startTime,\n\tcreatedAt: Date.now(),\n});\n\n/**\n * Sweep an orphaned reservation. If the file exists AND its creator is\n * dead, unlink it. Returns whether a sweep happened so callers can\n * observe / report.\n *\n * Architecture § Concurrent snapshot last paragraph:\n *   \"If the snapshotting process crashes mid-snapshot, the reservation\n *    file persists. The next process's claim-protocol sweep detects an\n *    orphan reservation (the holder whose pid matches the\n *    reservation's creator entry is dead) and unlinks it.\"\n */\nexport const sweepOrphan = (\n\tpath: string,\n): Effect.Effect<{ readonly swept: boolean }, SnapshotReservationError> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({ 'devstack.snapshot-reservation.path': path });\n\t\tif (!existsSync(path)) return { swept: false };\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t});\n\t\tconst reservation = parseReservation(raw);\n\t\tif (reservation === null) {\n\t\t\t// Malformed body — the creator wrote a half-written file then\n\t\t\t// died. Treat as orphan: unlink it so future acquires don't\n\t\t\t// fail forever.\n\t\t\tyield* Effect.try({\n\t\t\t\ttry: () => unlinkSync(path),\n\t\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t\t});\n\t\t\treturn { swept: true };\n\t\t}\n\t\t// PID-liveness check: synthesize a roster-shaped holder so the\n\t\t// shared liveness predicate applies.\n\t\tconst liveness = yield* checkHolderLiveness(\n\t\t\t{\n\t\t\t\tpid: reservation.creatorPid,\n\t\t\t\tstartTime: reservation.creatorStartTime,\n\t\t\t\thostname: '',\n\t\t\t\tclaimedAt: reservation.createdAt,\n\t\t\t\theartbeatAt: reservation.createdAt,\n\t\t\t\tintent: 'snapshot',\n\t\t\t},\n\t\t\t'',\n\t\t).pipe(Effect.catch(() => Effect.succeed('alive' as const)));\n\t\tif (liveness === 'alive') return { swept: false };\n\t\tyield* Effect.try({\n\t\t\ttry: () => unlinkSync(path),\n\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t});\n\t\treturn { swept: true };\n\t}).pipe(Effect.withSpan('cross-process.snapshot-reservation.sweepOrphan'));\n\n/**\n * Acquire the snapshot reservation as a scoped resource. The\n * reservation is unlinked when the surrounding Scope closes.\n *\n * Architecture § Concurrent snapshot step 1: O_EXCL create, no retry.\n * Callers that fail with `SnapshotReservationHeldError` propagate the\n * structured \"snapshot in progress\" error to the user — the typical\n * `Effect.catchTag` shape.\n *\n * `startTime` is the same value the roster carries for THIS process so\n * the orphan sweep's pid-startTime check resolves identically.\n */\nexport const acquireReservation = (\n\tpath: string,\n\tstartTime: number,\n): Effect.Effect<SnapshotReservation, SnapshotReservationError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({ 'devstack.snapshot-reservation.path': path });\n\t\t// One-shot orphan sweep before our O_EXCL attempt. The sweep is\n\t\t// idempotent: if a peer just wrote the reservation while we ran\n\t\t// the sweep, the O_EXCL create fails below and we surface the\n\t\t// structured \"held\" error.\n\t\tyield* sweepOrphan(path);\n\t\tconst body = ownReservation(startTime);\n\t\tyield* Effect.try({\n\t\t\ttry: () => writeFileSync(path, JSON.stringify(body), { flag: 'wx' }),\n\t\t\tcatch: (cause) => {\n\t\t\t\tconst code = (cause as NodeJS.ErrnoException).code;\n\t\t\t\tif (code === 'EEXIST') {\n\t\t\t\t\tlet holder: SnapshotReservation | null = null;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tholder = parseReservation(readFileSync(path, 'utf8'));\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Body unreadable; leave holder as null.\n\t\t\t\t\t}\n\t\t\t\t\treturn new SnapshotReservationHeldError({ path, holder });\n\t\t\t\t}\n\t\t\t\treturn new SnapshotReservationIoError({ path, cause });\n\t\t\t},\n\t\t});\n\t\t// Finalizer: best-effort unlink on scope close. Architecture §\n\t\t// Concurrent snapshot step 5: \"It unlinks `snapshot.reservation`.\"\n\t\tyield* Effect.addFinalizer(() =>\n\t\t\tEffect.sync(() => {\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(path);\n\t\t\t\t} catch {\n\t\t\t\t\t// Already gone — ok. A peer's sweep may have unlinked our\n\t\t\t\t\t// stale reservation if we somehow lost the process between\n\t\t\t\t\t// acquire and the finalizer fire.\n\t\t\t\t}\n\t\t\t}),\n\t\t);\n\t\treturn body;\n\t}).pipe(Effect.withSpan('cross-process.snapshot-reservation.acquire'));\n\n/** Inspect (without acquiring) the current reservation. Returns the\n *  parsed body or `null` if absent / malformed. Used by the supervisor\n *  to decide whether to apply the \"snapshot-in-progress\" tolerance\n *  window to ready probes. Architecture § Concurrent snapshot step 3. */\nexport const peekReservation = (\n\tpath: string,\n): Effect.Effect<SnapshotReservation | null, SnapshotReservationError> =>\n\tEffect.gen(function* () {\n\t\tif (!existsSync(path)) return null;\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t});\n\t\treturn parseReservation(raw);\n\t}).pipe(Effect.withSpan('cross-process.snapshot-reservation.peek'));\n"],"mappings":";;;;;;AAgCA,IAAa,+BAAb,cAAkD,KAAK,YAAY,+BAA+B,CAG/F;AAEH,IAAa,6BAAb,cAAgD,KAAK,YAAY,6BAA6B,CAG3F;AAQH,MAAM,oBAAoB,QAA4C;AACrE,KAAI;AACH,SAAO,mBAAmB,2BAA2B,KAAK;GACzD,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC;SACK;AACP,SAAO;;;AAQT,MAAM,kBAAkB,eAA4C;CACnE,YAAY,QAAQ;CACpB,kBAAkB;CAClB,WAAW,KAAK,KAAK;CACrB;;;;;;;;;;;;AAaD,MAAa,eACZ,SAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB,EAAE,sCAAsC,MAAM,CAAC;AACjF,KAAI,CAAC,WAAW,KAAK,CAAE,QAAO,EAAE,OAAO,OAAO;CAK9C,MAAM,cAAc,iBAAiB,OAJlB,OAAO,IAAI;EAC7B,WAAW,aAAa,MAAM,OAAO;EACrC,QAAQ,UAAU,IAAI,2BAA2B;GAAE;GAAM;GAAO,CAAC;EACjE,CAAC,CACuC;AACzC,KAAI,gBAAgB,MAAM;AAIzB,SAAO,OAAO,IAAI;GACjB,WAAW,WAAW,KAAK;GAC3B,QAAQ,UAAU,IAAI,2BAA2B;IAAE;IAAM;IAAO,CAAC;GACjE,CAAC;AACF,SAAO,EAAE,OAAO,MAAM;;AAevB,MAAI,OAXoB,oBACvB;EACC,KAAK,YAAY;EACjB,WAAW,YAAY;EACvB,UAAU;EACV,WAAW,YAAY;EACvB,aAAa,YAAY;EACzB,QAAQ;EACR,EACD,GACA,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,QAAiB,CAAC,CAAC,MAC3C,QAAS,QAAO,EAAE,OAAO,OAAO;AACjD,QAAO,OAAO,IAAI;EACjB,WAAW,WAAW,KAAK;EAC3B,QAAQ,UAAU,IAAI,2BAA2B;GAAE;GAAM;GAAO,CAAC;EACjE,CAAC;AACF,QAAO,EAAE,OAAO,MAAM;EACrB,CAAC,KAAK,OAAO,SAAS,iDAAiD,CAAC;;;;;;;;;;;;;AAc3E,MAAa,sBACZ,MACA,cAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB,EAAE,sCAAsC,MAAM,CAAC;AAKjF,QAAO,YAAY,KAAK;CACxB,MAAM,OAAO,eAAe,UAAU;AACtC,QAAO,OAAO,IAAI;EACjB,WAAW,cAAc,MAAM,KAAK,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,CAAC;EACpE,QAAQ,UAAU;AAEjB,OADc,MAAgC,SACjC,UAAU;IACtB,IAAI,SAAqC;AACzC,QAAI;AACH,cAAS,iBAAiB,aAAa,MAAM,OAAO,CAAC;YAC9C;AAGR,WAAO,IAAI,6BAA6B;KAAE;KAAM;KAAQ,CAAC;;AAE1D,UAAO,IAAI,2BAA2B;IAAE;IAAM;IAAO,CAAC;;EAEvD,CAAC;AAGF,QAAO,OAAO,mBACb,OAAO,WAAW;AACjB,MAAI;AACH,cAAW,KAAK;UACT;GAKP,CACF;AACD,QAAO;EACN,CAAC,KAAK,OAAO,SAAS,6CAA6C,CAAC"}
+{"version":3,"file":"snapshot-reservation.mjs","names":["nodeHostname"],"sources":["../../../../src/substrate/runtime/cross-process/snapshot-reservation.ts"],"sourcesContent":["// `snapshot.reservation` — presence-or-absence semaphore.\n//\n// Architecture § Cross-process safety protocol § Concurrent snapshot:\n//   \"Snapshot requires exclusive control of the stack's container set\n//   (pause-around-commit means peer processes' ready-probes would fail\n//   if uncoordinated). The snapshotting process acquires\n//   `snapshot.reservation` via O_EXCL create. If creation fails (peer\n//   holds it), the snapshot refuses with a structured 'snapshot in\n//   progress by peer pid X' error.\"\n//\n// Discipline:\n//   - Acquire is atomic O_EXCL create with a JSON body carrying\n//     `{ version: 1, creatorPid, creatorStartTime, createdAt, hostname }`.\n//   - Release is `unlink`.\n//   - Orphan sweep: on the next claim, the body's `hostname` is checked\n//     first. Foreign-host reservations short-circuit as alive (NFS-safe\n//     conservative default — `kill(pid, 0)` is meaningless on a remote\n//     kernel). Same-host reservations fall through to the PID +\n//     start-time check, which mirrors the roster's stale-PID reclaim.\n//   - Acquire DOES NOT retry — snapshot is a one-shot intent; the\n//     caller surfaces the structured error to the user immediately.\n\nimport { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';\nimport { hostname as nodeHostname } from 'node:os';\n\nimport { Data, Effect, Scope } from 'effect';\n\nimport { type SnapshotReservation, SnapshotReservationSchema } from '../../cross-process.ts';\nimport { parseVersionedDocumentBodyOrNull } from '../../versioned-doc-sync.ts';\nimport { SpanAttr } from '../observability/spans.ts';\nimport { checkHolderLiveness } from './liveness.ts';\nimport { reclaimUnparseableStaleFile } from './reclaim-stale-file.ts';\nimport { selfPid } from './self-pid.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\nexport class SnapshotReservationHeldError extends Data.TaggedError('SnapshotReservationHeldError')<{\n\treadonly path: string;\n\treadonly holder: SnapshotReservation | null;\n}> {}\n\nexport class SnapshotReservationIoError extends Data.TaggedError('SnapshotReservationIoError')<{\n\treadonly path: string;\n\treadonly cause: unknown;\n}> {}\n\nexport type SnapshotReservationError = SnapshotReservationHeldError | SnapshotReservationIoError;\n\n// -----------------------------------------------------------------------------\n// Codec\n// -----------------------------------------------------------------------------\n\nconst parseReservation = (raw: string): SnapshotReservation | null =>\n\tparseVersionedDocumentBodyOrNull(raw, SnapshotReservationSchema, 'snapshot.reservation');\n\n// -----------------------------------------------------------------------------\n// Acquire / release\n// -----------------------------------------------------------------------------\n\nconst ownReservation = (startTime: number | null): SnapshotReservation => ({\n\tversion: 1,\n\tcreatorPid: selfPid(),\n\tcreatorStartTime: startTime,\n\tcreatedAt: Date.now(),\n\thostname: nodeHostname(),\n});\n\n/**\n * Sweep an orphaned reservation. If the file exists AND its creator is\n * dead, unlink it. Returns whether a sweep happened so callers can\n * observe / report.\n *\n * Architecture § Concurrent snapshot last paragraph:\n *   \"If the snapshotting process crashes mid-snapshot, the reservation\n *    file persists. The next process's claim-protocol sweep detects an\n *    orphan reservation (the holder whose pid matches the\n *    reservation's creator entry is dead) and unlinks it.\"\n */\nexport const sweepOrphan = (\n\tpath: string,\n): Effect.Effect<{ readonly swept: boolean }, SnapshotReservationError> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({ [SpanAttr.snapshotReservationPath]: path });\n\t\tif (!existsSync(path)) return { swept: false };\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t});\n\t\tconst reservation = parseReservation(raw);\n\t\tif (reservation === null) {\n\t\t\t// Malformed body — the creator may have written a half-written\n\t\t\t// file. Reclaim ONLY through the shared re-stat guard: gating a\n\t\t\t// bare mtime read + unlink races a competitor who legitimately\n\t\t\t// reclaims the garbage and writes a fresh valid O_EXCL body in\n\t\t\t// the window — the unlink would clobber that LIVE reservation.\n\t\t\t// `reclaimUnparseableStaleFile` honors the SAME mtime staleness\n\t\t\t// window stack-lock uses (a body younger than the window is\n\t\t\t// presumed mid-write and left alone) AND re-confirms the file\n\t\t\t// is still the same stale, unparseable inode immediately before\n\t\t\t// unlinking.\n\t\t\tconst outcome = yield* Effect.try({\n\t\t\t\ttry: () => reclaimUnparseableStaleFile(path, parseReservation),\n\t\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t\t});\n\t\t\treturn { swept: outcome === 'reclaimed' };\n\t\t}\n\t\t// Foreign-host reservation: NFS-safe — we cannot probe a remote\n\t\t// kernel for pid liveness, so treat the peer as alive (matches\n\t\t// the roster's `trustForeignHosts` policy). Before adding the\n\t\t// `hostname` field we synthesized a holder with hostname='' and\n\t\t// passed ownHost='', which bypassed the foreign-host fast-path\n\t\t// in `checkHolderLiveness` and probed PID/startTime locally — a\n\t\t// live remote process could be declared dead and its reservation\n\t\t// unlinked. The fix is to short-circuit here.\n\t\tconst ownHost = nodeHostname();\n\t\tif (reservation.hostname !== ownHost) return { swept: false };\n\t\t// PID-liveness check: synthesize a roster-shaped holder so the\n\t\t// shared liveness predicate applies.\n\t\tconst liveness = yield* checkHolderLiveness(\n\t\t\t{\n\t\t\t\tpid: reservation.creatorPid,\n\t\t\t\tstartTime: reservation.creatorStartTime,\n\t\t\t\thostname: reservation.hostname,\n\t\t\t\tclaimedAt: reservation.createdAt,\n\t\t\t\theartbeatAt: reservation.createdAt,\n\t\t\t\tintent: 'snapshot',\n\t\t\t},\n\t\t\townHost,\n\t\t).pipe(Effect.catch(() => Effect.succeed('alive' as const)));\n\t\tif (liveness === 'alive') return { swept: false };\n\t\tyield* Effect.try({\n\t\t\ttry: () => unlinkSync(path),\n\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t});\n\t\treturn { swept: true };\n\t}).pipe(Effect.withSpan('cross-process.snapshot-reservation.sweepOrphan'));\n\n/**\n * Acquire the snapshot reservation as a scoped resource. The\n * reservation is unlinked when the surrounding Scope closes.\n *\n * Architecture § Concurrent snapshot step 1: O_EXCL create, no retry.\n * Callers that fail with `SnapshotReservationHeldError` propagate the\n * structured \"snapshot in progress\" error to the user — the typical\n * `Effect.catchTag` shape.\n *\n * `startTime` is the same value the roster carries for THIS process so\n * the orphan sweep's pid-startTime check resolves identically.\n */\nexport const acquireReservation = (\n\tpath: string,\n\tstartTime: number | null,\n): Effect.Effect<SnapshotReservation, SnapshotReservationError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({ [SpanAttr.snapshotReservationPath]: path });\n\t\t// One-shot orphan sweep before our O_EXCL attempt. The sweep is\n\t\t// idempotent: if a peer just wrote the reservation while we ran\n\t\t// the sweep, the O_EXCL create fails below and we surface the\n\t\t// structured \"held\" error.\n\t\tyield* sweepOrphan(path);\n\t\tconst body = ownReservation(startTime);\n\t\tyield* Effect.try({\n\t\t\ttry: () => writeFileSync(path, JSON.stringify(body), { flag: 'wx' }),\n\t\t\tcatch: (cause) => {\n\t\t\t\tconst code = (cause as NodeJS.ErrnoException).code;\n\t\t\t\tif (code === 'EEXIST') {\n\t\t\t\t\tlet holder: SnapshotReservation | null = null;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tholder = parseReservation(readFileSync(path, 'utf8'));\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Body unreadable; leave holder as null.\n\t\t\t\t\t}\n\t\t\t\t\treturn new SnapshotReservationHeldError({ path, holder });\n\t\t\t\t}\n\t\t\t\treturn new SnapshotReservationIoError({ path, cause });\n\t\t\t},\n\t\t});\n\t\t// Finalizer: best-effort unlink on scope close. Architecture §\n\t\t// Concurrent snapshot step 5: \"It unlinks `snapshot.reservation`.\"\n\t\tyield* Effect.addFinalizer(() =>\n\t\t\tEffect.sync(() => {\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(path);\n\t\t\t\t} catch {\n\t\t\t\t\t// Already gone — ok. A peer's sweep may have unlinked our\n\t\t\t\t\t// stale reservation if we somehow lost the process between\n\t\t\t\t\t// acquire and the finalizer fire.\n\t\t\t\t}\n\t\t\t}),\n\t\t);\n\t\treturn body;\n\t}).pipe(Effect.withSpan('cross-process.snapshot-reservation.acquire'));\n\n/** Inspect (without acquiring) the current reservation. Returns the\n *  parsed body or `null` if absent / malformed. Used by the supervisor\n *  to decide whether to apply the \"snapshot-in-progress\" tolerance\n *  window to ready probes. Architecture § Concurrent snapshot step 3. */\nexport const peekReservation = (\n\tpath: string,\n): Effect.Effect<SnapshotReservation | null, SnapshotReservationError> =>\n\tEffect.gen(function* () {\n\t\tif (!existsSync(path)) return null;\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t});\n\t\treturn parseReservation(raw);\n\t}).pipe(Effect.withSpan('cross-process.snapshot-reservation.peek'));\n"],"mappings":";;;;;;;;;;AAsCA,IAAa,+BAAb,cAAkD,KAAK,YAAY,+BAA+B,CAG/F;AAEH,IAAa,6BAAb,cAAgD,KAAK,YAAY,6BAA6B,CAG3F;AAQH,MAAM,oBAAoB,QACzB,iCAAiC,KAAK,2BAA2B,uBAAuB;AAMzF,MAAM,kBAAkB,eAAmD;CAC1E,SAAS;CACT,YAAY,SAAS;CACrB,kBAAkB;CAClB,WAAW,KAAK,KAAK;CACrB,UAAUA,UAAc;CACxB;;;;;;;;;;;;AAaD,MAAa,eACZ,SAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB,GAAG,SAAS,0BAA0B,MAAM,CAAC;AAC/E,KAAI,CAAC,WAAW,KAAK,CAAE,QAAO,EAAE,OAAO,OAAO;CAK9C,MAAM,cAAc,iBAAiB,OAJlB,OAAO,IAAI;EAC7B,WAAW,aAAa,MAAM,OAAO;EACrC,QAAQ,UAAU,IAAI,2BAA2B;GAAE;GAAM;GAAO,CAAC;EACjE,CAAC,CACuC;AACzC,KAAI,gBAAgB,KAenB,QAAO,EAAE,QAAO,OAJO,OAAO,IAAI;EACjC,WAAW,4BAA4B,MAAM,iBAAiB;EAC9D,QAAQ,UAAU,IAAI,2BAA2B;GAAE;GAAM;GAAO,CAAC;EACjE,CAAC,MAC0B,aAAa;CAU1C,MAAM,UAAUA,UAAc;AAC9B,KAAI,YAAY,aAAa,QAAS,QAAO,EAAE,OAAO,OAAO;AAc7D,MAAI,OAXoB,oBACvB;EACC,KAAK,YAAY;EACjB,WAAW,YAAY;EACvB,UAAU,YAAY;EACtB,WAAW,YAAY;EACvB,aAAa,YAAY;EACzB,QAAQ;EACR,EACD,QACA,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,QAAiB,CAAC,CAAC,MAC3C,QAAS,QAAO,EAAE,OAAO,OAAO;AACjD,QAAO,OAAO,IAAI;EACjB,WAAW,WAAW,KAAK;EAC3B,QAAQ,UAAU,IAAI,2BAA2B;GAAE;GAAM;GAAO,CAAC;EACjE,CAAC;AACF,QAAO,EAAE,OAAO,MAAM;EACrB,CAAC,KAAK,OAAO,SAAS,iDAAiD,CAAC;;;;;;;;;;;;;AAc3E,MAAa,sBACZ,MACA,cAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB,GAAG,SAAS,0BAA0B,MAAM,CAAC;AAK/E,QAAO,YAAY,KAAK;CACxB,MAAM,OAAO,eAAe,UAAU;AACtC,QAAO,OAAO,IAAI;EACjB,WAAW,cAAc,MAAM,KAAK,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,CAAC;EACpE,QAAQ,UAAU;AAEjB,OADc,MAAgC,SACjC,UAAU;IACtB,IAAI,SAAqC;AACzC,QAAI;AACH,cAAS,iBAAiB,aAAa,MAAM,OAAO,CAAC;YAC9C;AAGR,WAAO,IAAI,6BAA6B;KAAE;KAAM;KAAQ,CAAC;;AAE1D,UAAO,IAAI,2BAA2B;IAAE;IAAM;IAAO,CAAC;;EAEvD,CAAC;AAGF,QAAO,OAAO,mBACb,OAAO,WAAW;AACjB,MAAI;AACH,cAAW,KAAK;UACT;GAKP,CACF;AACD,QAAO;EACN,CAAC,KAAK,OAAO,SAAS,6CAA6C,CAAC"}

package/dist/substrate/runtime/cross-process/stack-lock.mjs

@@ -1,5 +1,9 @@
+import { SpanAttr } from "../observability/spans.mjs";
+import "../../cross-process.mjs";
+import { parseVersionedDocumentBodyOrNull } from "../../versioned-doc-sync.mjs";
+import { underLiveClock } from "./live-clock.mjs";
 import { checkHolderLiveness, ownHolder } from "./liveness.mjs";
-import { decodeJsonTextSync } from "../runtime-decode.mjs";
+import { reclaimUnparseableStaleFile } from "./reclaim-stale-file.mjs";
 import { Data, Effect, Schema } from "effect";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
@@ -11,31 +15,31 @@ var StackLockTimeoutError = class extends Data.TaggedError("StackLockTimeoutErro
 /** Tagged failure: I/O error other than EEXIST during acquire. */
 var StackLockIoError = class extends Data.TaggedError("StackLockIoError") {};
 /** The on-disk body is the same `RosterHolder` shape — re-using the schema
-*  means roster sweep + stack-lock reclaim see the same fields. */
+*  means roster sweep + stack-lock reclaim see the same fields.
+*
+*  `startTime` mirrors `RosterHolderSchema`: `number | null` so an
+*  unprobable platform's lock body round-trips cleanly through the
+*  decoder. The shared liveness predicate honors null conservatively. */
 const StackLockBodySchema = Schema.Struct({
 	pid: Schema.Number,
-	startTime: Schema.Number,
+	startTime: Schema.NullOr(Schema.Number),
 	hostname: Schema.String,
 	claimedAt: Schema.Number,
 	heartbeatAt: Schema.Number,
 	intent: Schema.Literals(["normal", "snapshot"])
 });
-const parseLockBody = (raw) => {
-	try {
-		return decodeJsonTextSync(StackLockBodySchema, raw, {
-			source: "stack.lock",
-			mkError: (issue) => issue
-		});
-	} catch {
-		return null;
-	}
-};
+const parseLockBody = (raw) => parseVersionedDocumentBodyOrNull(raw, StackLockBodySchema, "stack.lock");
 /** Default acquire timeout — architecture § Claim protocol step 1
 *  ("Block up to 5 seconds; if unavailable, retry with backoff"). */
 const DEFAULT_ACQUIRE_TIMEOUT_MILLIS = 5e3;
-/** Per-attempt initial wait. Doubles each retry up to the cap. */
+/** Per-attempt initial wait. Doubles each retry up to the cap. The
+*  backoff also resets whenever the holder identity changes — see the
+*  reclaim loop comment for the contention story (review fix phase
+*  22f). The cap is intentionally tight (200ms) so peers react quickly
+*  to a release; combined with the O_EXCL-arbitrated retry on reclaim,
+*  no staggering jitter is needed. */
 const INITIAL_BACKOFF_MILLIS = 25;
-const MAX_BACKOFF_MILLIS = 500;
+const MAX_BACKOFF_MILLIS = 200;
 /**
 * Sync attempt at O_EXCL-create. Returns whether we own the lock now.
 *
@@ -86,12 +90,13 @@ const tryAcquireSync = (path) => {
 */
 const acquireStackLock = (path, timeoutMillis = DEFAULT_ACQUIRE_TIMEOUT_MILLIS) => Effect.gen(function* () {
 	yield* Effect.annotateCurrentSpan({
-		"devstack.stack-lock.path": path,
-		"devstack.stack-lock.timeoutMillis": timeoutMillis
+		[SpanAttr.stackLockPath]: path,
+		[SpanAttr.stackLockTimeoutMillis]: timeoutMillis
 	});
 	const startedAt = Date.now();
 	let backoff = INITIAL_BACKOFF_MILLIS;
 	let lastHolder = null;
+	let prevHolderPid = null;
 	while (true) {
 		const elapsed = Date.now() - startedAt;
 		if (elapsed > timeoutMillis) return yield* Effect.fail(new StackLockTimeoutError({
@@ -115,6 +120,12 @@ const acquireStackLock = (path, timeoutMillis = DEFAULT_ACQUIRE_TIMEOUT_MILLIS)
 			return;
 		}
 		lastHolder = attempt.holder;
+		const currentHolderPid = lastHolder?.pid ?? null;
+		if (currentHolderPid !== prevHolderPid) {
+			backoff = INITIAL_BACKOFF_MILLIS;
+			prevHolderPid = currentHolderPid;
+		}
+		let reclaimed = false;
 		if (lastHolder !== null) {
 			if ((yield* checkHolderLiveness(lastHolder).pipe(Effect.catch(() => Effect.succeed("alive")))) === "dead") {
 				yield* Effect.try({
@@ -129,14 +140,24 @@ const acquireStackLock = (path, timeoutMillis = DEFAULT_ACQUIRE_TIMEOUT_MILLIS)
 						cause
 					})
 				});
-				continue;
+				reclaimed = true;
 			}
+		} else reclaimed = (yield* Effect.try({
+			try: () => reclaimUnparseableStaleFile(path, parseLockBody),
+			catch: (cause) => new StackLockIoError({
+				path,
+				cause
+			})
+		})) === "reclaimed";
+		if (reclaimed) {
+			backoff = INITIAL_BACKOFF_MILLIS;
+			continue;
 		}
-		yield* Effect.sleep(`${backoff} millis`);
+		yield* underLiveClock(Effect.sleep(`${backoff} millis`));
 		backoff = Math.min(backoff * 2, MAX_BACKOFF_MILLIS);
 	}
 }).pipe(Effect.withSpan("cross-process.stack-lock.acquire"));
 //#endregion
-export { acquireStackLock };
+export { DEFAULT_ACQUIRE_TIMEOUT_MILLIS, StackLockIoError, StackLockTimeoutError, acquireStackLock };
 
 //# sourceMappingURL=stack-lock.mjs.map

package/dist/substrate/runtime/cross-process/stack-lock.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"stack-lock.mjs","names":[],"sources":["../../../../src/substrate/runtime/cross-process/stack-lock.ts"],"sourcesContent":["// `stack.lock` — O_EXCL exclusive lock for short critical sections.\n//\n// Architecture § Cross-process safety protocol § \"What is locked\":\n//   - `stack.lock` — OS-advisory exclusive lock file. Used only for\n//     short critical sections (roster mutations, snapshot reservation).\n//     Acquired via `flock(LOCK_EX)` on Unix and `LockFileEx` on Windows;\n//     never held across a long operation.\n//\n// The implementation here uses a portable O_EXCL-create dance — the\n// same approach the legacy `engine/file-lock.ts` proved out — because\n// `flock` isn't available cross-platform out of `node:fs`. The\n// architecture's wording (\"OS-advisory exclusive lock file\") covers\n// both `flock` and `O_EXCL`-with-pid-body; the latter is what every\n// portable POSIX tool reaches for when `flock` isn't on the table.\n//\n// Discipline:\n//   - The lock is held BRIEFLY — within a single Effect.scoped block\n//     that mutates the roster or the snapshot reservation.\n//   - Stale locks (owner crashed under the lock) are reclaimed via the\n//     PID + start-time liveness check before the acquire reattempts.\n//   - Acquire retries with exponential backoff up to 5 seconds total\n//     (architecture § Claim protocol step 1).\n\nimport { mkdirSync, unlinkSync, readFileSync, writeFileSync, existsSync } from 'node:fs';\nimport { dirname } from 'node:path';\n\nimport { Data, Effect, Schema, Scope } from 'effect';\n\nimport { decodeJsonTextSync } from '../runtime-decode.ts';\nimport { checkHolderLiveness, ownHolder } from './liveness.ts';\nimport type { RosterHolder } from '../../cross-process.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** Tagged failure: acquire window elapsed and the lock is still held.\n *  Carries the in-disk body (if parseable) so the caller can name the\n *  blocking peer in user-facing error reporting. */\nexport class StackLockTimeoutError extends Data.TaggedError('StackLockTimeoutError')<{\n\treadonly path: string;\n\treadonly waitedMillis: number;\n\treadonly holder: RosterHolder | null;\n}> {}\n\n/** Tagged failure: I/O error other than EEXIST during acquire. */\nexport class StackLockIoError extends Data.TaggedError('StackLockIoError')<{\n\treadonly path: string;\n\treadonly cause: unknown;\n}> {}\n\nexport type StackLockError = StackLockTimeoutError | StackLockIoError;\n\n// -----------------------------------------------------------------------------\n// Codec\n// -----------------------------------------------------------------------------\n\n/** The on-disk body is the same `RosterHolder` shape — re-using the schema\n *  means roster sweep + stack-lock reclaim see the same fields. */\nconst StackLockBodySchema = Schema.Struct({\n\tpid: Schema.Number,\n\tstartTime: Schema.Number,\n\thostname: Schema.String,\n\tclaimedAt: Schema.Number,\n\theartbeatAt: Schema.Number,\n\tintent: Schema.Literals(['normal', 'snapshot']),\n});\n\nconst parseLockBody = (raw: string): RosterHolder | null => {\n\ttry {\n\t\treturn decodeJsonTextSync(StackLockBodySchema, raw, {\n\t\t\tsource: 'stack.lock',\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Acquire / release\n// -----------------------------------------------------------------------------\n\n/** Default acquire timeout — architecture § Claim protocol step 1\n *  (\"Block up to 5 seconds; if unavailable, retry with backoff\"). */\nexport const DEFAULT_ACQUIRE_TIMEOUT_MILLIS = 5_000;\n\n/** Per-attempt initial wait. Doubles each retry up to the cap. */\nconst INITIAL_BACKOFF_MILLIS = 25;\nconst MAX_BACKOFF_MILLIS = 500;\n\n/**\n * Sync attempt at O_EXCL-create. Returns whether we own the lock now.\n *\n * Effect-platform's FileSystem doesn't expose a sync `open` shape, but\n * the critical-section discipline says we need a non-blocking attempt\n * inside a retry loop. Falling through to Node sync APIs here is the\n * cleanest path; the rest of the substrate stays Effect-native.\n */\nconst tryAcquireSync = (\n\tpath: string,\n): { readonly ok: true } | { readonly ok: false; readonly holder: RosterHolder | null } => {\n\tconst body = ownHolder();\n\t// The lock's parent directory may not exist on first-claim of a\n\t// fresh runtime root — devstack's `<runtimeRoot>/stacks/<stack>/` is\n\t// the substrate's responsibility to bring into being, but no other\n\t// L0 subsystem touches the disk until the first claim. `mkdir -p`\n\t// here is idempotent and harmless on the warm path; it transforms\n\t// the otherwise-fatal ENOENT-during-write into a clean acquire.\n\t// Architecture § Cross-process safety protocol: stack root is\n\t// created by whichever subsystem first reaches for a path under it.\n\tmkdirSync(dirname(path), { recursive: true });\n\ttry {\n\t\twriteFileSync(path, JSON.stringify(body), { flag: 'wx' });\n\t\treturn { ok: true };\n\t} catch (err) {\n\t\tconst code = (err as NodeJS.ErrnoException).code;\n\t\tif (code !== 'EEXIST') {\n\t\t\tthrow err;\n\t\t}\n\t\t// Peer holds it (or stale). Probe the existing body.\n\t\tif (!existsSync(path)) {\n\t\t\t// Race: holder unlinked between our EEXIST and the existsSync.\n\t\t\t// Retry on the next loop iteration.\n\t\t\treturn { ok: false, holder: null };\n\t\t}\n\t\ttry {\n\t\t\tconst raw = readFileSync(path, 'utf8');\n\t\t\treturn { ok: false, holder: parseLockBody(raw) };\n\t\t} catch {\n\t\t\treturn { ok: false, holder: null };\n\t\t}\n\t}\n};\n\n/**\n * Acquire `stack.lock` as a scoped resource. The lock is released\n * when the surrounding Scope closes.\n *\n * Retry loop: exponential backoff up to `timeoutMillis` (default 5s).\n * On every miss, probe the holder's liveness — if it's dead, reclaim\n * by unlinking and looping. The reclaim path is the architecture's\n * \"stale lock\" handling — same PID + start-time semantics as the\n * roster sweep, so a process that crashed under the lock never blocks\n * the next peer indefinitely.\n *\n * IMPORTANT: this primitive yields a `void` resource. The caller MUST\n * keep its Scope tight — the architecture forbids holding the lock\n * across long operations.\n */\nexport const acquireStackLock = (\n\tpath: string,\n\ttimeoutMillis: number = DEFAULT_ACQUIRE_TIMEOUT_MILLIS,\n): Effect.Effect<void, StackLockError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.stack-lock.path': path,\n\t\t\t'devstack.stack-lock.timeoutMillis': timeoutMillis,\n\t\t});\n\t\tconst startedAt = Date.now();\n\t\tlet backoff = INITIAL_BACKOFF_MILLIS;\n\t\tlet lastHolder: RosterHolder | null = null;\n\t\twhile (true) {\n\t\t\tconst elapsed = Date.now() - startedAt;\n\t\t\tif (elapsed > timeoutMillis) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew StackLockTimeoutError({ path, waitedMillis: elapsed, holder: lastHolder }),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst attempt = yield* Effect.try({\n\t\t\t\ttry: () => tryAcquireSync(path),\n\t\t\t\tcatch: (cause) => new StackLockIoError({ path, cause }),\n\t\t\t});\n\t\t\tif (attempt.ok) {\n\t\t\t\t// Register a finalizer that unlinks the lock on scope close.\n\t\t\t\tyield* Effect.addFinalizer(() =>\n\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tunlinkSync(path);\n\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t// Already gone — ok. Crash-during-release is handled\n\t\t\t\t\t\t\t// by the next peer's stale-PID reclaim.\n\t\t\t\t\t\t}\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tlastHolder = attempt.holder;\n\t\t\t// Reclaim if the holder is dead.\n\t\t\tif (lastHolder !== null) {\n\t\t\t\tconst status = yield* checkHolderLiveness(lastHolder).pipe(\n\t\t\t\t\tEffect.catch(() => Effect.succeed('alive' as const)),\n\t\t\t\t);\n\t\t\t\tif (status === 'dead') {\n\t\t\t\t\tyield* Effect.try({\n\t\t\t\t\t\ttry: () => {\n\t\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t\tunlinkSync(path);\n\t\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t\t// Race with another reclaimer — ok.\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\treturn null;\n\t\t\t\t\t\t},\n\t\t\t\t\t\tcatch: (cause) => new StackLockIoError({ path, cause }),\n\t\t\t\t\t});\n\t\t\t\t\t// Loop again immediately; don't sleep for a reclaim.\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t}\n\t\t\tyield* Effect.sleep(`${backoff} millis`);\n\t\t\tbackoff = Math.min(backoff * 2, MAX_BACKOFF_MILLIS);\n\t\t}\n\t}).pipe(Effect.withSpan('cross-process.stack-lock.acquire'));\n"],"mappings":";;;;;;;;;AAuCA,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAIjF;;AAGH,IAAa,mBAAb,cAAsC,KAAK,YAAY,mBAAmB,CAGvE;;;AAUH,MAAM,sBAAsB,OAAO,OAAO;CACzC,KAAK,OAAO;CACZ,WAAW,OAAO;CAClB,UAAU,OAAO;CACjB,WAAW,OAAO;CAClB,aAAa,OAAO;CACpB,QAAQ,OAAO,SAAS,CAAC,UAAU,WAAW,CAAC;CAC/C,CAAC;AAEF,MAAM,iBAAiB,QAAqC;AAC3D,KAAI;AACH,SAAO,mBAAmB,qBAAqB,KAAK;GACnD,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC;SACK;AACP,SAAO;;;;;AAUT,MAAa,iCAAiC;;AAG9C,MAAM,yBAAyB;AAC/B,MAAM,qBAAqB;;;;;;;;;AAU3B,MAAM,kBACL,SAC0F;CAC1F,MAAM,OAAO,WAAW;AASxB,WAAU,QAAQ,KAAK,EAAE,EAAE,WAAW,MAAM,CAAC;AAC7C,KAAI;AACH,gBAAc,MAAM,KAAK,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,CAAC;AACzD,SAAO,EAAE,IAAI,MAAM;UACX,KAAK;AAEb,MADc,IAA8B,SAC/B,SACZ,OAAM;AAGP,MAAI,CAAC,WAAW,KAAK,CAGpB,QAAO;GAAE,IAAI;GAAO,QAAQ;GAAM;AAEnC,MAAI;AAEH,UAAO;IAAE,IAAI;IAAO,QAAQ,cADhB,aAAa,MAAM,OACc,CAAC;IAAE;UACzC;AACP,UAAO;IAAE,IAAI;IAAO,QAAQ;IAAM;;;;;;;;;;;;;;;;;;;AAoBrC,MAAa,oBACZ,MACA,gBAAwB,mCAExB,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB;EACjC,4BAA4B;EAC5B,qCAAqC;EACrC,CAAC;CACF,MAAM,YAAY,KAAK,KAAK;CAC5B,IAAI,UAAU;CACd,IAAI,aAAkC;AACtC,QAAO,MAAM;EACZ,MAAM,UAAU,KAAK,KAAK,GAAG;AAC7B,MAAI,UAAU,cACb,QAAO,OAAO,OAAO,KACpB,IAAI,sBAAsB;GAAE;GAAM,cAAc;GAAS,QAAQ;GAAY,CAAC,CAC9E;EAEF,MAAM,UAAU,OAAO,OAAO,IAAI;GACjC,WAAW,eAAe,KAAK;GAC/B,QAAQ,UAAU,IAAI,iBAAiB;IAAE;IAAM;IAAO,CAAC;GACvD,CAAC;AACF,MAAI,QAAQ,IAAI;AAEf,UAAO,OAAO,mBACb,OAAO,WAAW;AACjB,QAAI;AACH,gBAAW,KAAK;YACT;KAIP,CACF;AACD;;AAED,eAAa,QAAQ;AAErB,MAAI,eAAe;QAId,OAHkB,oBAAoB,WAAW,CAAC,KACrD,OAAO,YAAY,OAAO,QAAQ,QAAiB,CAAC,CACpD,MACc,QAAQ;AACtB,WAAO,OAAO,IAAI;KACjB,WAAW;AACV,UAAI;AACH,kBAAW,KAAK;cACT;AAGR,aAAO;;KAER,QAAQ,UAAU,IAAI,iBAAiB;MAAE;MAAM;MAAO,CAAC;KACvD,CAAC;AAEF;;;AAGF,SAAO,OAAO,MAAM,GAAG,QAAQ,SAAS;AACxC,YAAU,KAAK,IAAI,UAAU,GAAG,mBAAmB;;EAEnD,CAAC,KAAK,OAAO,SAAS,mCAAmC,CAAC"}
+{"version":3,"file":"stack-lock.mjs","names":[],"sources":["../../../../src/substrate/runtime/cross-process/stack-lock.ts"],"sourcesContent":["// `stack.lock` — O_EXCL exclusive lock for short critical sections.\n//\n// Architecture § Cross-process safety protocol § \"What is locked\":\n//   - `stack.lock` — OS-advisory exclusive lock file. Used only for\n//     short critical sections (roster mutations, snapshot reservation).\n//     Acquired via `flock(LOCK_EX)` on Unix and `LockFileEx` on Windows;\n//     never held across a long operation.\n//\n// The implementation here uses a portable O_EXCL-create dance — the\n// same approach the legacy `engine/file-lock.ts` proved out — because\n// `flock` isn't available cross-platform out of `node:fs`. The\n// architecture's wording (\"OS-advisory exclusive lock file\") covers\n// both `flock` and `O_EXCL`-with-pid-body; the latter is what every\n// portable POSIX tool reaches for when `flock` isn't on the table.\n//\n// Discipline:\n//   - The lock is held BRIEFLY — within a single Effect.scoped block\n//     that mutates the roster or the snapshot reservation.\n//   - Stale locks (owner crashed under the lock) are reclaimed via the\n//     PID + start-time liveness check before the acquire reattempts.\n//   - Acquire retries with exponential backoff up to 5 seconds total\n//     (architecture § Claim protocol step 1).\n\nimport { mkdirSync, unlinkSync, readFileSync, writeFileSync, existsSync } from 'node:fs';\nimport { dirname } from 'node:path';\n\nimport { Data, Effect, Schema, Scope } from 'effect';\n\nimport { type RosterHolder } from '../../cross-process.ts';\nimport { parseVersionedDocumentBodyOrNull } from '../../versioned-doc-sync.ts';\nimport { SpanAttr } from '../observability/spans.ts';\nimport { underLiveClock } from './live-clock.ts';\nimport { checkHolderLiveness, ownHolder } from './liveness.ts';\nimport { reclaimUnparseableStaleFile } from './reclaim-stale-file.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** Tagged failure: acquire window elapsed and the lock is still held.\n *  Carries the in-disk body (if parseable) so the caller can name the\n *  blocking peer in user-facing error reporting. */\nexport class StackLockTimeoutError extends Data.TaggedError('StackLockTimeoutError')<{\n\treadonly path: string;\n\treadonly waitedMillis: number;\n\treadonly holder: RosterHolder | null;\n}> {}\n\n/** Tagged failure: I/O error other than EEXIST during acquire. */\nexport class StackLockIoError extends Data.TaggedError('StackLockIoError')<{\n\treadonly path: string;\n\treadonly cause: unknown;\n}> {}\n\nexport type StackLockError = StackLockTimeoutError | StackLockIoError;\n\n// -----------------------------------------------------------------------------\n// Codec\n// -----------------------------------------------------------------------------\n\n/** The on-disk body is the same `RosterHolder` shape — re-using the schema\n *  means roster sweep + stack-lock reclaim see the same fields.\n *\n *  `startTime` mirrors `RosterHolderSchema`: `number | null` so an\n *  unprobable platform's lock body round-trips cleanly through the\n *  decoder. The shared liveness predicate honors null conservatively. */\nconst StackLockBodySchema = Schema.Struct({\n\tpid: Schema.Number,\n\tstartTime: Schema.NullOr(Schema.Number),\n\thostname: Schema.String,\n\tclaimedAt: Schema.Number,\n\theartbeatAt: Schema.Number,\n\tintent: Schema.Literals(['normal', 'snapshot']),\n});\n\nconst parseLockBody = (raw: string): RosterHolder | null =>\n\tparseVersionedDocumentBodyOrNull(raw, StackLockBodySchema, 'stack.lock');\n\n// -----------------------------------------------------------------------------\n// Acquire / release\n// -----------------------------------------------------------------------------\n\n/** Default acquire timeout — architecture § Claim protocol step 1\n *  (\"Block up to 5 seconds; if unavailable, retry with backoff\"). */\nexport const DEFAULT_ACQUIRE_TIMEOUT_MILLIS = 5_000;\n\n/** Per-attempt initial wait. Doubles each retry up to the cap. The\n *  backoff also resets whenever the holder identity changes — see the\n *  reclaim loop comment for the contention story (review fix phase\n *  22f). The cap is intentionally tight (200ms) so peers react quickly\n *  to a release; combined with the O_EXCL-arbitrated retry on reclaim,\n *  no staggering jitter is needed. */\nconst INITIAL_BACKOFF_MILLIS = 25;\nconst MAX_BACKOFF_MILLIS = 200;\n\n/**\n * Sync attempt at O_EXCL-create. Returns whether we own the lock now.\n *\n * Effect-platform's FileSystem doesn't expose a sync `open` shape, but\n * the critical-section discipline says we need a non-blocking attempt\n * inside a retry loop. Falling through to Node sync APIs here is the\n * cleanest path; the rest of the substrate stays Effect-native.\n */\nconst tryAcquireSync = (\n\tpath: string,\n): { readonly ok: true } | { readonly ok: false; readonly holder: RosterHolder | null } => {\n\tconst body = ownHolder();\n\t// The lock's parent directory may not exist on first-claim of a\n\t// fresh runtime root — devstack's `<runtimeRoot>/stacks/<stack>/` is\n\t// the substrate's responsibility to bring into being, but no other\n\t// L0 subsystem touches the disk until the first claim. `mkdir -p`\n\t// here is idempotent and harmless on the warm path; it transforms\n\t// the otherwise-fatal ENOENT-during-write into a clean acquire.\n\t// Architecture § Cross-process safety protocol: stack root is\n\t// created by whichever subsystem first reaches for a path under it.\n\tmkdirSync(dirname(path), { recursive: true });\n\ttry {\n\t\twriteFileSync(path, JSON.stringify(body), { flag: 'wx' });\n\t\treturn { ok: true };\n\t} catch (err) {\n\t\tconst code = (err as NodeJS.ErrnoException).code;\n\t\tif (code !== 'EEXIST') {\n\t\t\tthrow err;\n\t\t}\n\t\t// Peer holds it (or stale). Probe the existing body.\n\t\tif (!existsSync(path)) {\n\t\t\t// Race: holder unlinked between our EEXIST and the existsSync.\n\t\t\t// Retry on the next loop iteration.\n\t\t\treturn { ok: false, holder: null };\n\t\t}\n\t\ttry {\n\t\t\tconst raw = readFileSync(path, 'utf8');\n\t\t\treturn { ok: false, holder: parseLockBody(raw) };\n\t\t} catch {\n\t\t\treturn { ok: false, holder: null };\n\t\t}\n\t}\n};\n\n/**\n * Acquire `stack.lock` as a scoped resource. The lock is released\n * when the surrounding Scope closes.\n *\n * Retry loop: exponential backoff up to `timeoutMillis` (default 5s).\n * On every miss, probe the holder's liveness — if it's dead, reclaim\n * by unlinking and looping. The reclaim path is the architecture's\n * \"stale lock\" handling — same PID + start-time semantics as the\n * roster sweep, so a process that crashed under the lock never blocks\n * the next peer indefinitely.\n *\n * IMPORTANT: this primitive yields a `void` resource. The caller MUST\n * keep its Scope tight — the architecture forbids holding the lock\n * across long operations.\n */\nexport const acquireStackLock = (\n\tpath: string,\n\ttimeoutMillis: number = DEFAULT_ACQUIRE_TIMEOUT_MILLIS,\n): Effect.Effect<void, StackLockError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t[SpanAttr.stackLockPath]: path,\n\t\t\t[SpanAttr.stackLockTimeoutMillis]: timeoutMillis,\n\t\t});\n\t\tconst startedAt = Date.now();\n\t\tlet backoff = INITIAL_BACKOFF_MILLIS;\n\t\tlet lastHolder: RosterHolder | null = null;\n\t\tlet prevHolderPid: number | null = null;\n\t\twhile (true) {\n\t\t\tconst elapsed = Date.now() - startedAt;\n\t\t\tif (elapsed > timeoutMillis) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew StackLockTimeoutError({ path, waitedMillis: elapsed, holder: lastHolder }),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst attempt = yield* Effect.try({\n\t\t\t\ttry: () => tryAcquireSync(path),\n\t\t\t\tcatch: (cause) => new StackLockIoError({ path, cause }),\n\t\t\t});\n\t\t\tif (attempt.ok) {\n\t\t\t\t// Register a finalizer that unlinks the lock on scope close.\n\t\t\t\tyield* Effect.addFinalizer(() =>\n\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tunlinkSync(path);\n\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t// Already gone — ok. Crash-during-release is handled\n\t\t\t\t\t\t\t// by the next peer's stale-PID reclaim.\n\t\t\t\t\t\t}\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tlastHolder = attempt.holder;\n\t\t\t// Reset the backoff whenever the holder identity changes —\n\t\t\t// a new holder means the previous one released, and our\n\t\t\t// long-saturated backoff (driven by waiting on the prior\n\t\t\t// holder) is now stale. Without this, late waiters under\n\t\t\t// heavy contention saturate at MAX_BACKOFF_MILLIS while\n\t\t\t// each peer holds the lock only briefly, exhausting the\n\t\t\t// claim budget before they can win (review fix phase 22f\n\t\t\t// reclaim-stress reproducer caught the case).\n\t\t\tconst currentHolderPid = lastHolder?.pid ?? null;\n\t\t\tif (currentHolderPid !== prevHolderPid) {\n\t\t\t\tbackoff = INITIAL_BACKOFF_MILLIS;\n\t\t\t\tprevHolderPid = currentHolderPid;\n\t\t\t}\n\t\t\t// Reclaim if the holder is dead OR the lock body is\n\t\t\t// unparseable AND old enough to be presumed-abandoned. The\n\t\t\t// unparseable case covers a peer that died mid-write: the\n\t\t\t// PID liveness check has nothing to consult, so the only\n\t\t\t// signal is the file's mtime falling outside the staleness\n\t\t\t// window (`DEFAULT_SWEEP_POLICY.staleAfterMillis`, shared\n\t\t\t// with the roster sweep). Without this branch, a mid-write\n\t\t\t// crash keeps every peer blocked for the full 5s claim\n\t\t\t// window — see review fix phase 22f (cross-process).\n\t\t\tlet reclaimed = false;\n\t\t\tif (lastHolder !== null) {\n\t\t\t\t// Dead-PID reclaim: gated on a liveness probe, so the\n\t\t\t\t// holder cannot have written a fresh body — a plain\n\t\t\t\t// unlink is safe here (no TOCTOU). An alive holder falls\n\t\t\t\t// through to the backoff below.\n\t\t\t\tconst status = yield* checkHolderLiveness(lastHolder).pipe(\n\t\t\t\t\tEffect.catch(() => Effect.succeed('alive' as const)),\n\t\t\t\t);\n\t\t\t\tif (status === 'dead') {\n\t\t\t\t\tyield* Effect.try({\n\t\t\t\t\t\ttry: () => {\n\t\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t\tunlinkSync(path);\n\t\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t\t// Race with another reclaimer — ok.\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\treturn null;\n\t\t\t\t\t\t},\n\t\t\t\t\t\tcatch: (cause) => new StackLockIoError({ path, cause }),\n\t\t\t\t\t});\n\t\t\t\t\treclaimed = true;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\t// Unparseable body: reclaim ONLY through the re-stat\n\t\t\t\t// guard. A bare mtime read + unlink races a competitor\n\t\t\t\t// who legitimately reclaims the garbage and writes a\n\t\t\t\t// fresh valid O_EXCL body in the window — the unlink\n\t\t\t\t// would clobber that LIVE lock (two simultaneous\n\t\t\t\t// holders). `reclaimUnparseableStaleFile` re-confirms the\n\t\t\t\t// file is still the same stale, unparseable inode\n\t\t\t\t// immediately before unlinking; any other outcome leaves\n\t\t\t\t// the file untouched and we fall through to back off.\n\t\t\t\tconst outcome = yield* Effect.try({\n\t\t\t\t\ttry: () => reclaimUnparseableStaleFile(path, parseLockBody),\n\t\t\t\t\tcatch: (cause) => new StackLockIoError({ path, cause }),\n\t\t\t\t});\n\t\t\t\treclaimed = outcome === 'reclaimed';\n\t\t\t}\n\t\t\tif (reclaimed) {\n\t\t\t\t// O_EXCL atomicity alone arbitrates the post-reclaim\n\t\t\t\t// race; reset the backoff so the contest starts fresh\n\t\t\t\t// (the prior growth was driven by a now-evicted dead\n\t\t\t\t// holder).\n\t\t\t\tbackoff = INITIAL_BACKOFF_MILLIS;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\t// Peer holds an alive lock — back off exponentially.\n\t\t\tyield* underLiveClock(Effect.sleep(`${backoff} millis`));\n\t\t\tbackoff = Math.min(backoff * 2, MAX_BACKOFF_MILLIS);\n\t\t}\n\t}).pipe(Effect.withSpan('cross-process.stack-lock.acquire'));\n"],"mappings":";;;;;;;;;;;;;AA0CA,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAIjF;;AAGH,IAAa,mBAAb,cAAsC,KAAK,YAAY,mBAAmB,CAGvE;;;;;;;AAcH,MAAM,sBAAsB,OAAO,OAAO;CACzC,KAAK,OAAO;CACZ,WAAW,OAAO,OAAO,OAAO,OAAO;CACvC,UAAU,OAAO;CACjB,WAAW,OAAO;CAClB,aAAa,OAAO;CACpB,QAAQ,OAAO,SAAS,CAAC,UAAU,WAAW,CAAC;CAC/C,CAAC;AAEF,MAAM,iBAAiB,QACtB,iCAAiC,KAAK,qBAAqB,aAAa;;;AAQzE,MAAa,iCAAiC;;;;;;;AAQ9C,MAAM,yBAAyB;AAC/B,MAAM,qBAAqB;;;;;;;;;AAU3B,MAAM,kBACL,SAC0F;CAC1F,MAAM,OAAO,WAAW;AASxB,WAAU,QAAQ,KAAK,EAAE,EAAE,WAAW,MAAM,CAAC;AAC7C,KAAI;AACH,gBAAc,MAAM,KAAK,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,CAAC;AACzD,SAAO,EAAE,IAAI,MAAM;UACX,KAAK;AAEb,MADc,IAA8B,SAC/B,SACZ,OAAM;AAGP,MAAI,CAAC,WAAW,KAAK,CAGpB,QAAO;GAAE,IAAI;GAAO,QAAQ;GAAM;AAEnC,MAAI;AAEH,UAAO;IAAE,IAAI;IAAO,QAAQ,cADhB,aAAa,MAAM,OACc,CAAC;IAAE;UACzC;AACP,UAAO;IAAE,IAAI;IAAO,QAAQ;IAAM;;;;;;;;;;;;;;;;;;;AAoBrC,MAAa,oBACZ,MACA,gBAAwB,mCAExB,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB;GAChC,SAAS,gBAAgB;GACzB,SAAS,yBAAyB;EACnC,CAAC;CACF,MAAM,YAAY,KAAK,KAAK;CAC5B,IAAI,UAAU;CACd,IAAI,aAAkC;CACtC,IAAI,gBAA+B;AACnC,QAAO,MAAM;EACZ,MAAM,UAAU,KAAK,KAAK,GAAG;AAC7B,MAAI,UAAU,cACb,QAAO,OAAO,OAAO,KACpB,IAAI,sBAAsB;GAAE;GAAM,cAAc;GAAS,QAAQ;GAAY,CAAC,CAC9E;EAEF,MAAM,UAAU,OAAO,OAAO,IAAI;GACjC,WAAW,eAAe,KAAK;GAC/B,QAAQ,UAAU,IAAI,iBAAiB;IAAE;IAAM;IAAO,CAAC;GACvD,CAAC;AACF,MAAI,QAAQ,IAAI;AAEf,UAAO,OAAO,mBACb,OAAO,WAAW;AACjB,QAAI;AACH,gBAAW,KAAK;YACT;KAIP,CACF;AACD;;AAED,eAAa,QAAQ;EASrB,MAAM,mBAAmB,YAAY,OAAO;AAC5C,MAAI,qBAAqB,eAAe;AACvC,aAAU;AACV,mBAAgB;;EAWjB,IAAI,YAAY;AAChB,MAAI,eAAe;QAQd,OAHkB,oBAAoB,WAAW,CAAC,KACrD,OAAO,YAAY,OAAO,QAAQ,QAAiB,CAAC,CACpD,MACc,QAAQ;AACtB,WAAO,OAAO,IAAI;KACjB,WAAW;AACV,UAAI;AACH,kBAAW,KAAK;cACT;AAGR,aAAO;;KAER,QAAQ,UAAU,IAAI,iBAAiB;MAAE;MAAM;MAAO,CAAC;KACvD,CAAC;AACF,gBAAY;;QAgBb,cAAY,OAJW,OAAO,IAAI;GACjC,WAAW,4BAA4B,MAAM,cAAc;GAC3D,QAAQ,UAAU,IAAI,iBAAiB;IAAE;IAAM;IAAO,CAAC;GACvD,CAAC,MACsB;AAEzB,MAAI,WAAW;AAKd,aAAU;AACV;;AAGD,SAAO,eAAe,OAAO,MAAM,GAAG,QAAQ,SAAS,CAAC;AACxD,YAAU,KAAK,IAAI,UAAU,GAAG,mBAAmB;;EAEnD,CAAC,KAAK,OAAO,SAAS,mCAAmC,CAAC"}

package/dist/substrate/runtime/current-plugin.mjs

@@ -1,7 +1,7 @@
 import { Context, Effect, Option } from "effect";
 //#region src/substrate/runtime/current-plugin.ts
-var CurrentPluginKey = class extends Context.Service()("@devstack-rewrite/substrate/CurrentPluginKey") {};
-var CurrentPluginProgress = class extends Context.Service()("@devstack-rewrite/substrate/CurrentPluginProgress") {};
+var CurrentPluginKey = class extends Context.Service()("@devstack/substrate/CurrentPluginKey") {};
+var CurrentPluginProgress = class extends Context.Service()("@devstack/substrate/CurrentPluginProgress") {};
 /** Publish acquire-time row narration for the currently supervised
 * plugin. Safe to call from plugin code: if the caller is running
 * outside a supervisor, the helper is a no-op. */

package/dist/substrate/runtime/current-plugin.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"current-plugin.mjs","names":[],"sources":["../../../src/substrate/runtime/current-plugin.ts"],"sourcesContent":["import { Context, Effect, Option } from 'effect';\n\nimport type { PluginKey } from '../brand.ts';\nimport type { PhaseNarration } from '../lifecycle.ts';\n\n/** Acquire-time identity for the plugin currently being supervised.\n *\n * Plugins that stream host-process output need the supervisor-minted\n * row key so logger lines publish as `log.appended` events for the\n * correct projection row. */\nexport interface CurrentPluginKeyShape {\n\treadonly key: PluginKey;\n}\n\nexport class CurrentPluginKey extends Context.Service<CurrentPluginKey, CurrentPluginKeyShape>()(\n\t'@devstack-rewrite/substrate/CurrentPluginKey',\n) {}\n\nexport interface CurrentPluginProgressShape {\n\treadonly setPhase: (phase: PhaseNarration | null) => Effect.Effect<void>;\n}\n\nexport class CurrentPluginProgress extends Context.Service<\n\tCurrentPluginProgress,\n\tCurrentPluginProgressShape\n>()('@devstack-rewrite/substrate/CurrentPluginProgress') {}\n\n/** Publish acquire-time row narration for the currently supervised\n * plugin. Safe to call from plugin code: if the caller is running\n * outside a supervisor, the helper is a no-op. */\nexport const setCurrentPluginPhase = (phase: PhaseNarration | null): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst progress = yield* Effect.serviceOption(CurrentPluginProgress);\n\t\tif (Option.isSome(progress)) {\n\t\t\tyield* progress.value.setPhase(phase);\n\t\t}\n\t});\n"],"mappings":";;AAcA,IAAa,mBAAb,cAAsC,QAAQ,SAAkD,CAC/F,+CACA,CAAC;AAMF,IAAa,wBAAb,cAA2C,QAAQ,SAGhD,CAAC,oDAAoD,CAAC;;;;AAKzD,MAAa,yBAAyB,UACrC,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,OAAO,cAAc,sBAAsB;AACnE,KAAI,OAAO,OAAO,SAAS,CAC1B,QAAO,SAAS,MAAM,SAAS,MAAM;EAErC"}
+{"version":3,"file":"current-plugin.mjs","names":[],"sources":["../../../src/substrate/runtime/current-plugin.ts"],"sourcesContent":["import { Context, Effect, Option } from 'effect';\n\nimport type { PluginKey } from '../brand.ts';\nimport type { PhaseNarration } from '../lifecycle.ts';\n\n/** Acquire-time identity for the plugin currently being supervised.\n *\n * Plugins that stream host-process output need the supervisor-minted\n * row key so logger lines publish as `log.appended` events for the\n * correct projection row. */\nexport interface CurrentPluginKeyShape {\n\treadonly key: PluginKey;\n}\n\nexport class CurrentPluginKey extends Context.Service<CurrentPluginKey, CurrentPluginKeyShape>()(\n\t'@devstack/substrate/CurrentPluginKey',\n) {}\n\nexport interface CurrentPluginProgressShape {\n\treadonly setPhase: (phase: PhaseNarration | null) => Effect.Effect<void>;\n}\n\nexport class CurrentPluginProgress extends Context.Service<\n\tCurrentPluginProgress,\n\tCurrentPluginProgressShape\n>()('@devstack/substrate/CurrentPluginProgress') {}\n\n/** Publish acquire-time row narration for the currently supervised\n * plugin. Safe to call from plugin code: if the caller is running\n * outside a supervisor, the helper is a no-op. */\nexport const setCurrentPluginPhase = (phase: PhaseNarration | null): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst progress = yield* Effect.serviceOption(CurrentPluginProgress);\n\t\tif (Option.isSome(progress)) {\n\t\t\tyield* progress.value.setPhase(phase);\n\t\t}\n\t});\n"],"mappings":";;AAcA,IAAa,mBAAb,cAAsC,QAAQ,SAAkD,CAC/F,uCACA,CAAC;AAMF,IAAa,wBAAb,cAA2C,QAAQ,SAGhD,CAAC,4CAA4C,CAAC;;;;AAKjD,MAAa,yBAAyB,UACrC,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,OAAO,cAAc,sBAAsB;AACnE,KAAI,OAAO,OAAO,SAAS,CAC1B,QAAO,SAAS,MAAM,SAAS,MAAM;EAErC"}

package/dist/substrate/runtime/errors.mjs

@@ -15,7 +15,10 @@ var AtomicWriteFailed = class extends Schema.TaggedErrorClass()("AtomicWriteFail
 	]),
 	cause: Schema.optional(Schema.Defect)
 }) {};
-Schema.TaggedErrorClass()("StateStoreError", {
+/** State-store I/O / corruption surface. Distinct from
+*  `AtomicWriteFailed` so consumers can recover ("re-init on
+*  corruption") without catching write errors. */
+var StateStoreError = class extends Schema.TaggedErrorClass()("StateStoreError", {
 	reason: Schema.Literals([
 		"io-failed",
 		"corruption",
@@ -23,7 +26,7 @@ Schema.TaggedErrorClass()("StateStoreError", {
 	]),
 	detail: Schema.String,
 	cause: Schema.optional(Schema.Defect)
-});
+}) {};
 /** Cache surface — same tri-state as the L0 cache contract. */
 var CacheError = class extends Schema.TaggedErrorClass()("CacheError", {
 	reason: Schema.Literals([
@@ -34,9 +37,12 @@ var CacheError = class extends Schema.TaggedErrorClass()("CacheError", {
 	detail: Schema.String,
 	cause: Schema.optional(Schema.Defect)
 }) {};
-/** Strategy registry missing-key surface — mirrors
-*  `StrategyNotFoundError` from `contracts/strategy-contributor.ts`
-*  as a yieldable. */
+/** Strategy registry missing-key surface. Canonical tagged error
+*  yielded from `StrategyRegistry.get` when no contributor is
+*  registered under the requested capability key. The
+*  `contracts/strategy-contributor.ts` `StrategyRegistry` interface
+*  imports this class as its `E` channel — one `_tag` literal,
+*  one class, package-wide. */
 var StrategyNotFoundError = class extends Schema.TaggedErrorClass()("StrategyNotFoundError", {
 	capabilityKey: Schema.String,
 	registeredKeys: Schema.Array(Schema.String)
@@ -71,6 +77,6 @@ var PortBrokerError = class extends Schema.TaggedErrorClass()("PortBrokerError",
 	cause: Schema.optional(Schema.Defect)
 }) {};
 //#endregion
-export { AtomicWriteFailed, CacheError, PortBrokerError, StrategyNotFoundError };
+export { AtomicWriteFailed, CacheError, PortBrokerError, StateStoreError, StrategyNotFoundError };
 
 //# sourceMappingURL=errors.mjs.map

package/dist/substrate/runtime/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/substrate/runtime/errors.ts"],"sourcesContent":["// Shared tagged errors for the runtime persistence layer.\n//\n// Per-subsystem tags so `Effect.catchTags({ ... })` reads at the call\n// site as \"what did the state-store / cache / registry just fail with\".\n\nimport { Schema } from 'effect';\n\n/** Atomic-write failure — one tag covers every stage. The `stage`\n *  field discriminates inside renderer messages without\n *  proliferating tag types. */\nexport class AtomicWriteFailed extends Schema.TaggedErrorClass<AtomicWriteFailed>()(\n\t'AtomicWriteFailed',\n\t{\n\t\tpath: Schema.String,\n\t\tstage: Schema.Literals(['mkdir-parent', 'open-temp', 'write', 'fsync', 'rename', 'encode']),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** State-store I/O / corruption surface. Distinct from\n *  `AtomicWriteFailed` so consumers can recover (\"re-init on\n *  corruption\") without catching write errors. */\nexport class StateStoreError extends Schema.TaggedErrorClass<StateStoreError>()('StateStoreError', {\n\treason: Schema.Literals(['io-failed', 'corruption', 'lock-contention']),\n\tdetail: Schema.String,\n\tcause: Schema.optional(Schema.Defect),\n}) {}\n\n/** Cache surface — same tri-state as the L0 cache contract. */\nexport class CacheError extends Schema.TaggedErrorClass<CacheError>()('CacheError', {\n\treason: Schema.Literals(['io-failed', 'corruption', 'lock-contention']),\n\tdetail: Schema.String,\n\tcause: Schema.optional(Schema.Defect),\n}) {}\n\n/** Strategy registry missing-key surface — mirrors\n *  `StrategyNotFoundError` from `contracts/strategy-contributor.ts`\n *  as a yieldable. */\nexport class StrategyNotFoundError extends Schema.TaggedErrorClass<StrategyNotFoundError>()(\n\t'StrategyNotFoundError',\n\t{\n\t\tcapabilityKey: Schema.String,\n\t\tregisteredKeys: Schema.Array(Schema.String),\n\t},\n) {}\n\n/** Port-broker allocation failure — surfaced when no free port could be\n *  found in the configured range, when a caller-supplied `preferredPort`\n *  is already taken by another in-process allocation, or when the bind-\n *  probe rejected every candidate.\n *\n *  `reason` discriminates the failure mode for renderer mapping:\n *    - `no-free-port`  : scanned the whole window for `kind`, every\n *                        candidate failed the bind-probe (EADDRINUSE) or\n *                        was already held by a sibling allocation in\n *                        this process.\n *    - `preferred-busy`: caller supplied a `preferredPort` and the\n *                        port is currently held by another in-process\n *                        allocation (refused per architecture §6).\n *    - `bind-probe-failed`: the OS-level bind probe surfaced an error\n *                          OTHER than `EADDRINUSE` (e.g. EACCES on a\n *                          privileged port, EPERM under jail). Caller\n *                          should fall back to user opt-in / docs.\n *    - `reservation-failed`: the runtime-root scoped port reservation\n *                            file could not be created/read/reclaimed. */\nexport class PortBrokerError extends Schema.TaggedErrorClass<PortBrokerError>()('PortBrokerError', {\n\treason: Schema.Literals([\n\t\t'no-free-port',\n\t\t'preferred-busy',\n\t\t'bind-probe-failed',\n\t\t'reservation-failed',\n\t]),\n\tdetail: Schema.String,\n\tcause: Schema.optional(Schema.Defect),\n}) {}\n"],"mappings":";;;;;AAUA,IAAa,oBAAb,cAAuC,OAAO,kBAAqC,CAClF,qBACA;CACC,MAAM,OAAO;CACb,OAAO,OAAO,SAAS;EAAC;EAAgB;EAAa;EAAS;EAAS;EAAU;EAAS,CAAC;CAC3F,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CACD,CAAC;AAKmC,OAAO,kBAAmC,CAAC,mBAAmB;CAClG,QAAQ,OAAO,SAAS;EAAC;EAAa;EAAc;EAAkB,CAAC;CACvE,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CAAC;;AAGF,IAAa,aAAb,cAAgC,OAAO,kBAA8B,CAAC,cAAc;CACnF,QAAQ,OAAO,SAAS;EAAC;EAAa;EAAc;EAAkB,CAAC;CACvE,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CAAC,CAAC;;;;AAKH,IAAa,wBAAb,cAA2C,OAAO,kBAAyC,CAC1F,yBACA;CACC,eAAe,OAAO;CACtB,gBAAgB,OAAO,MAAM,OAAO,OAAO;CAC3C,CACD,CAAC;;;;;;;;;;;;;;;;;;;;AAqBF,IAAa,kBAAb,cAAqC,OAAO,kBAAmC,CAAC,mBAAmB;CAClG,QAAQ,OAAO,SAAS;EACvB;EACA;EACA;EACA;EACA,CAAC;CACF,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CAAC,CAAC"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/substrate/runtime/errors.ts"],"sourcesContent":["// Shared tagged errors for the runtime persistence layer.\n//\n// Per-subsystem tags so `Effect.catchTags({ ... })` reads at the call\n// site as \"what did the state-store / cache / registry just fail with\".\n\nimport { Schema } from 'effect';\n\n/** Atomic-write failure — one tag covers every stage. The `stage`\n *  field discriminates inside renderer messages without\n *  proliferating tag types. */\nexport class AtomicWriteFailed extends Schema.TaggedErrorClass<AtomicWriteFailed>()(\n\t'AtomicWriteFailed',\n\t{\n\t\tpath: Schema.String,\n\t\tstage: Schema.Literals(['mkdir-parent', 'open-temp', 'write', 'fsync', 'rename', 'encode']),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** State-store I/O / corruption surface. Distinct from\n *  `AtomicWriteFailed` so consumers can recover (\"re-init on\n *  corruption\") without catching write errors. */\nexport class StateStoreError extends Schema.TaggedErrorClass<StateStoreError>()('StateStoreError', {\n\treason: Schema.Literals(['io-failed', 'corruption', 'lock-contention']),\n\tdetail: Schema.String,\n\tcause: Schema.optional(Schema.Defect),\n}) {}\n\n/** Cache surface — same tri-state as the L0 cache contract. */\nexport class CacheError extends Schema.TaggedErrorClass<CacheError>()('CacheError', {\n\treason: Schema.Literals(['io-failed', 'corruption', 'lock-contention']),\n\tdetail: Schema.String,\n\tcause: Schema.optional(Schema.Defect),\n}) {}\n\n/** Strategy registry missing-key surface. Canonical tagged error\n *  yielded from `StrategyRegistry.get` when no contributor is\n *  registered under the requested capability key. The\n *  `contracts/strategy-contributor.ts` `StrategyRegistry` interface\n *  imports this class as its `E` channel — one `_tag` literal,\n *  one class, package-wide. */\nexport class StrategyNotFoundError extends Schema.TaggedErrorClass<StrategyNotFoundError>()(\n\t'StrategyNotFoundError',\n\t{\n\t\tcapabilityKey: Schema.String,\n\t\tregisteredKeys: Schema.Array(Schema.String),\n\t},\n) {}\n\n/** Port-broker allocation failure — surfaced when no free port could be\n *  found in the configured range, when a caller-supplied `preferredPort`\n *  is already taken by another in-process allocation, or when the bind-\n *  probe rejected every candidate.\n *\n *  `reason` discriminates the failure mode for renderer mapping:\n *    - `no-free-port`  : scanned the whole window for `kind`, every\n *                        candidate failed the bind-probe (EADDRINUSE) or\n *                        was already held by a sibling allocation in\n *                        this process.\n *    - `preferred-busy`: caller supplied a `preferredPort` and the\n *                        port is currently held by another in-process\n *                        allocation (refused per architecture §6).\n *    - `bind-probe-failed`: the OS-level bind probe surfaced an error\n *                          OTHER than `EADDRINUSE` (e.g. EACCES on a\n *                          privileged port, EPERM under jail). Caller\n *                          should fall back to user opt-in / docs.\n *    - `reservation-failed`: the runtime-root scoped port reservation\n *                            file could not be created/read/reclaimed. */\nexport class PortBrokerError extends Schema.TaggedErrorClass<PortBrokerError>()('PortBrokerError', {\n\treason: Schema.Literals([\n\t\t'no-free-port',\n\t\t'preferred-busy',\n\t\t'bind-probe-failed',\n\t\t'reservation-failed',\n\t]),\n\tdetail: Schema.String,\n\tcause: Schema.optional(Schema.Defect),\n}) {}\n"],"mappings":";;;;;AAUA,IAAa,oBAAb,cAAuC,OAAO,kBAAqC,CAClF,qBACA;CACC,MAAM,OAAO;CACb,OAAO,OAAO,SAAS;EAAC;EAAgB;EAAa;EAAS;EAAS;EAAU;EAAS,CAAC;CAC3F,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CACD,CAAC;;;;AAKF,IAAa,kBAAb,cAAqC,OAAO,kBAAmC,CAAC,mBAAmB;CAClG,QAAQ,OAAO,SAAS;EAAC;EAAa;EAAc;EAAkB,CAAC;CACvE,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CAAC,CAAC;;AAGH,IAAa,aAAb,cAAgC,OAAO,kBAA8B,CAAC,cAAc;CACnF,QAAQ,OAAO,SAAS;EAAC;EAAa;EAAc;EAAkB,CAAC;CACvE,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CAAC,CAAC;;;;;;;AAQH,IAAa,wBAAb,cAA2C,OAAO,kBAAyC,CAC1F,yBACA;CACC,eAAe,OAAO;CACtB,gBAAgB,OAAO,MAAM,OAAO,OAAO;CAC3C,CACD,CAAC;;;;;;;;;;;;;;;;;;;;AAqBF,IAAa,kBAAb,cAAqC,OAAO,kBAAmC,CAAC,mBAAmB;CAClG,QAAQ,OAAO,SAAS;EACvB;EACA;EACA;EACA;EACA,CAAC;CACF,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CAAC,CAAC"}

package/dist/substrate/runtime/format-unknown-error.mjs

@@ -0,0 +1,30 @@
+//#region src/substrate/runtime/format-unknown-error.ts
+const MAX_CAUSE_DEPTH = 5;
+const nestedCauseMessage = (cause, depth) => {
+	if (cause instanceof Error) return project(cause, depth);
+	if (typeof cause === "string") return cause.length > 0 ? cause : null;
+	if (typeof cause === "object" && cause !== null) {
+		const message = cause.message;
+		if (typeof message === "string" && message.length > 0) return project(cause, depth);
+	}
+	return null;
+};
+const project = (cause, depth) => {
+	if (typeof cause === "string") return cause;
+	const tagged = cause;
+	const message = cause instanceof Error ? cause.message : typeof cause === "object" && cause !== null && typeof tagged.message === "string" ? tagged.message : void 0;
+	if (message !== void 0 && message.length > 0) {
+		const nested = depth < MAX_CAUSE_DEPTH ? nestedCauseMessage(tagged.cause, depth + 1) : null;
+		return nested !== null && !message.includes(nested) ? `${message} [cause: ${nested}]` : message;
+	}
+	try {
+		return JSON.stringify(cause);
+	} catch {
+		return String(cause);
+	}
+};
+const formatUnknownError = (cause) => project(cause, 0);
+//#endregion
+export { formatUnknownError };
+
+//# sourceMappingURL=format-unknown-error.mjs.map

package/dist/substrate/runtime/format-unknown-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-unknown-error.mjs","names":[],"sources":["../../../src/substrate/runtime/format-unknown-error.ts"],"sourcesContent":["// Shared `unknown → string` projector for plugin error messages.\n//\n// Lifted from 5 identical local definitions across mode/local.ts,\n// mode/shared-boot.ts, mode/fork.ts, mode/external.ts, chain-probe.ts,\n// fork-transaction.ts. Callers concatenate this into plugin-tagged\n// error `message` fields; cascade-formatter walks the actual `cause`\n// separately for structured rendering.\n//\n// NB: this does NOT stringify Effect's `Cause` type — it projects an\n// arbitrary `unknown` (typically a caught throwable) to a short\n// string suitable for splicing into a human-readable error message.\n\n// Bounds the `.cause` walk so a self-referential or pathologically deep\n// chain can't produce a runaway string (or loop forever).\nconst MAX_CAUSE_DEPTH = 5;\n\n// A nested `.cause` only earns a place in the spliced message when it\n// carries a human-readable string of its own — an `Error`, a string, or\n// a tagged object with a `.message`. Raw detail bags (e.g. `{ sender,\n// objectCount }`) are skipped here so they don't dump JSON into the\n// headline message; the structured cascade-formatter still renders them.\nconst nestedCauseMessage = (cause: unknown, depth: number): string | null => {\n\tif (cause instanceof Error) return project(cause, depth);\n\tif (typeof cause === 'string') return cause.length > 0 ? cause : null;\n\tif (typeof cause === 'object' && cause !== null) {\n\t\tconst message = (cause as { readonly message?: unknown }).message;\n\t\tif (typeof message === 'string' && message.length > 0) {\n\t\t\treturn project(cause, depth);\n\t\t}\n\t}\n\treturn null;\n};\n\nconst project = (cause: unknown, depth: number): string => {\n\tif (typeof cause === 'string') return cause;\n\t// `Error` instances AND tagged devstack errors (`AccountSignError`,\n\t// `SuiPluginError`, … — plain objects, NOT `Error`s, so `String(obj)`\n\t// yields `[object Object]`) both carry a string `.message` and may carry\n\t// a `.cause`. Prefer the message, then chain the `.cause` so a generic\n\t// wrapper (\"… submit failed.\") still surfaces the actionable root\n\t// (\"… no SUI gas coins found for 0x…\"). `Error.cause` is read the same\n\t// way, so a thrown `new Error(msg, { cause })` chain is walked too.\n\tconst tagged = cause as { readonly message?: unknown; readonly cause?: unknown };\n\tconst message =\n\t\tcause instanceof Error\n\t\t\t? cause.message\n\t\t\t: typeof cause === 'object' && cause !== null && typeof tagged.message === 'string'\n\t\t\t\t? tagged.message\n\t\t\t\t: undefined;\n\tif (message !== undefined && message.length > 0) {\n\t\tconst nested = depth < MAX_CAUSE_DEPTH ? nestedCauseMessage(tagged.cause, depth + 1) : null;\n\t\treturn nested !== null && !message.includes(nested)\n\t\t\t? `${message} [cause: ${nested}]`\n\t\t\t: message;\n\t}\n\ttry {\n\t\treturn JSON.stringify(cause);\n\t} catch {\n\t\treturn String(cause);\n\t}\n};\n\nexport const formatUnknownError = (cause: unknown): string => project(cause, 0);\n"],"mappings":";AAcA,MAAM,kBAAkB;AAOxB,MAAM,sBAAsB,OAAgB,UAAiC;AAC5E,KAAI,iBAAiB,MAAO,QAAO,QAAQ,OAAO,MAAM;AACxD,KAAI,OAAO,UAAU,SAAU,QAAO,MAAM,SAAS,IAAI,QAAQ;AACjE,KAAI,OAAO,UAAU,YAAY,UAAU,MAAM;EAChD,MAAM,UAAW,MAAyC;AAC1D,MAAI,OAAO,YAAY,YAAY,QAAQ,SAAS,EACnD,QAAO,QAAQ,OAAO,MAAM;;AAG9B,QAAO;;AAGR,MAAM,WAAW,OAAgB,UAA0B;AAC1D,KAAI,OAAO,UAAU,SAAU,QAAO;CAQtC,MAAM,SAAS;CACf,MAAM,UACL,iBAAiB,QACd,MAAM,UACN,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAO,OAAO,YAAY,WACxE,OAAO,UACP,KAAA;AACL,KAAI,YAAY,KAAA,KAAa,QAAQ,SAAS,GAAG;EAChD,MAAM,SAAS,QAAQ,kBAAkB,mBAAmB,OAAO,OAAO,QAAQ,EAAE,GAAG;AACvF,SAAO,WAAW,QAAQ,CAAC,QAAQ,SAAS,OAAO,GAChD,GAAG,QAAQ,WAAW,OAAO,KAC7B;;AAEJ,KAAI;AACH,SAAO,KAAK,UAAU,MAAM;SACrB;AACP,SAAO,OAAO,MAAM;;;AAItB,MAAa,sBAAsB,UAA2B,QAAQ,OAAO,EAAE"}

package/dist/substrate/runtime/host-bind-mount-owner.mjs

@@ -0,0 +1,10 @@
+//#region src/substrate/runtime/host-bind-mount-owner.ts
+const hostBindMountOwner = () => {
+	const process = globalThis.process;
+	if (typeof process?.getuid !== "function" || typeof process.getgid !== "function") return;
+	return `${process.getuid()}:${process.getgid()}`;
+};
+//#endregion
+export { hostBindMountOwner };
+
+//# sourceMappingURL=host-bind-mount-owner.mjs.map

package/dist/substrate/runtime/host-bind-mount-owner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-bind-mount-owner.mjs","names":[],"sources":["../../../src/substrate/runtime/host-bind-mount-owner.ts"],"sourcesContent":["// Host UID:GID accessor for bind-mount ownership.\n//\n// When the substrate runs a container with a host bind mount, the\n// container's writes land on the host filesystem as the container's\n// effective UID. On native Linux Docker that defaults to root, which\n// makes the resulting files un-deletable from the developer's shell\n// without `sudo`. Plugins thread `${UID}:${GID}` into the container's\n// `--user` flag (or via `DEVSTACK_HOST_UID_GID` for entrypoints that\n// re-exec) so the writes land owned by the invoking user.\n//\n// Returns `undefined` on platforms where `process.getuid/getgid` are\n// not available (Windows, browser). Callers omit the user/env stamp in\n// that case — Docker Desktop handles the ownership mapping itself.\n\nexport const hostBindMountOwner = (): string | undefined => {\n\tconst process = (\n\t\tglobalThis as {\n\t\t\tprocess?: { getuid?: () => number; getgid?: () => number };\n\t\t}\n\t).process;\n\tif (typeof process?.getuid !== 'function' || typeof process.getgid !== 'function') {\n\t\treturn undefined;\n\t}\n\treturn `${process.getuid()}:${process.getgid()}`;\n};\n"],"mappings":";AAcA,MAAa,2BAA+C;CAC3D,MAAM,UACL,WAGC;AACF,KAAI,OAAO,SAAS,WAAW,cAAc,OAAO,QAAQ,WAAW,WACtE;AAED,QAAO,GAAG,QAAQ,QAAQ,CAAC,GAAG,QAAQ,QAAQ"}

package/dist/substrate/runtime/host-gateway.mjs

@@ -0,0 +1,20 @@
+//#region src/substrate/runtime/host-gateway.ts
+/** Container `extraHosts` mapping that resolves
+*  `host.docker.internal` to the host gateway on native Linux
+*  Docker. Pass as `extraHosts:` on container specs that need to
+*  dial host-bound services. */
+const HOST_GATEWAY_EXTRA_HOSTS = { "host.docker.internal": "host-gateway" };
+/** Same fact as `HOST_GATEWAY_EXTRA_HOSTS`, encoded for the
+*  `docker run --add-host <host>:<gateway>` CLI flag (the value
+*  passed as the argv after `--add-host`). Derived from the record
+*  so a future change to the alias set lives in one place.
+*
+*  If the record ever grows past one entry, the router's traefik
+*  bootstrap will need to emit one `--add-host <pair>` per entry;
+*  today it stamps exactly one pair, matching this record's single
+*  member. */
+const HOST_GATEWAY_ADD_HOST_FLAGS = Object.entries(HOST_GATEWAY_EXTRA_HOSTS).map(([host, gateway]) => `${host}:${gateway}`);
+//#endregion
+export { HOST_GATEWAY_ADD_HOST_FLAGS, HOST_GATEWAY_EXTRA_HOSTS };
+
+//# sourceMappingURL=host-gateway.mjs.map

package/dist/substrate/runtime/host-gateway.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-gateway.mjs","names":[],"sources":["../../../src/substrate/runtime/host-gateway.ts"],"sourcesContent":["// Host-gateway `extraHosts` — ONE canonical constant.\n//\n// A container that needs to reach a service on the host's loopback\n// (e.g. Docker-published ports from a sibling container, or a host\n// process bound to `127.0.0.1`) does it by name via\n// `host.docker.internal`. Docker Desktop on macOS/Windows wires this\n// automatically; native Linux Docker does NOT and requires an\n// explicit `--add-host host.docker.internal:host-gateway` per\n// container (the literal string `host-gateway` is a Docker token\n// that resolves to the gateway IP of the container's network).\n//\n// This constant is the `extraHosts:` value passed to\n// `EnsureContainerSpec` / `runOneShot`. Use it instead of inlining\n// `{ 'host.docker.internal': 'host-gateway' }` at every dial-host\n// container site so a future change (e.g. additional aliases, or\n// platform-conditional mapping) lives in one place.\n\n/** Container `extraHosts` mapping that resolves\n *  `host.docker.internal` to the host gateway on native Linux\n *  Docker. Pass as `extraHosts:` on container specs that need to\n *  dial host-bound services. */\nexport const HOST_GATEWAY_EXTRA_HOSTS: Readonly<Record<string, string>> = {\n\t'host.docker.internal': 'host-gateway',\n};\n\n/** Same fact as `HOST_GATEWAY_EXTRA_HOSTS`, encoded for the\n *  `docker run --add-host <host>:<gateway>` CLI flag (the value\n *  passed as the argv after `--add-host`). Derived from the record\n *  so a future change to the alias set lives in one place.\n *\n *  If the record ever grows past one entry, the router's traefik\n *  bootstrap will need to emit one `--add-host <pair>` per entry;\n *  today it stamps exactly one pair, matching this record's single\n *  member. */\nexport const HOST_GATEWAY_ADD_HOST_FLAGS: ReadonlyArray<string> = Object.entries(\n\tHOST_GATEWAY_EXTRA_HOSTS,\n).map(([host, gateway]) => `${host}:${gateway}`);\n"],"mappings":";;;;;AAqBA,MAAa,2BAA6D,EACzE,wBAAwB,gBACxB;;;;;;;;;;AAWD,MAAa,8BAAqD,OAAO,QACxE,yBACA,CAAC,KAAK,CAAC,MAAM,aAAa,GAAG,KAAK,GAAG,UAAU"}

package/dist/substrate/runtime/host-tree-tar/index.mjs

@@ -41,6 +41,42 @@ const tarExitError = (operation, status, stderrChunks) => new HostTreeTarError({
 	detail: `'tar' exited with ${describeProcessExitStatus(status)}`,
 	stderrTail: collectStderrTail(stderrChunks)
 });
+/** Spawn `tar` with a bounded stderr ring buffer and a SIGKILL-on-
+*  scope-close finalizer. Both `tarHostTree` and `untarHostTree` share
+*  this body verbatim — only the args, stdio direction (which pipe is
+*  the data channel), and the `operation` tag differ. The data pipe
+*  (`stdout` for tar, `stdin` for untar) is read off the returned
+*  `child` by the caller; stderr is always piped so the exit-code
+*  failure can carry the captured tail.
+*
+*  The stderr listener is removed and a live child is killed on scope
+*  close — the finalizer binds to the surrounding Scope (the stream's
+*  lifecycle for tar, the consuming Effect's for untar). */
+const spawnTar = (operation, args, stdio) => Effect.gen(function* () {
+	const child = yield* Effect.try({
+		try: () => spawn("tar", [...args], { stdio }),
+		catch: (cause) => new HostTreeTarError({
+			stage: "spawn",
+			operation,
+			detail: `failed to spawn 'tar ${args.join(" ")}'`,
+			cause
+		})
+	});
+	const stderrChunks = [];
+	const onStderr = (chunk) => {
+		stderrChunks.push(chunk);
+		if (stderrChunks.length > 256) stderrChunks.splice(0, stderrChunks.length - 256);
+	};
+	child.stderr?.on("data", onStderr);
+	yield* Effect.addFinalizer(() => Effect.sync(() => {
+		child.stderr?.off("data", onStderr);
+		if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+	}));
+	return {
+		child,
+		stderrChunks
+	};
+});
 const TAR_BLOCK_SIZE = 512;
 const MAX_TAR_EXTENDED_PATH_BYTES = 1024 * 1024;
 const bytesToString = (bytes) => {
@@ -123,6 +159,10 @@ const applyExtendedContent = (state, content) => {
 	return null;
 };
 const processTarValidationChunk = (state, chunk) => {
+	if (state.content === null && state.skipRemaining >= chunk.length && state.buffer.length === 0) {
+		state.skipRemaining -= chunk.length;
+		return null;
+	}
 	state.buffer = concatBytes(state.buffer, chunk);
 	while (state.buffer.length > 0) {
 		if (state.content !== null) {
@@ -220,7 +260,13 @@ const tarHostTree = (spec) => Stream.unwrap(Effect.gen(function* () {
 		operation: "tar",
 		detail: "tarHostTree called with empty relPaths list"
 	}));
-	const args = [
+	const unsafe = spec.relPaths.find((relPath) => !isSafeArchivePath(relPath));
+	if (unsafe !== void 0) return Stream.fail(new HostTreeTarError({
+		stage: "entry-validation",
+		operation: "tar",
+		detail: `unsafe tar relPath (absolute or contains '..'): ${unsafe}`
+	}));
+	const { child, stderrChunks } = yield* spawnTar("tar", [
 		"-c",
 		"-f",
 		"-",
@@ -228,30 +274,11 @@ const tarHostTree = (spec) => Stream.unwrap(Effect.gen(function* () {
 		spec.parentDir,
 		"-p",
 		...spec.relPaths
-	];
-	const child = yield* Effect.try({
-		try: () => spawn("tar", args, { stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		] }),
-		catch: (cause) => new HostTreeTarError({
-			stage: "spawn",
-			operation: "tar",
-			detail: `failed to spawn 'tar ${args.join(" ")}'`,
-			cause
-		})
-	});
-	const stderrChunks = [];
-	const onStderr = (chunk) => {
-		stderrChunks.push(chunk);
-		if (stderrChunks.length > 256) stderrChunks.splice(0, stderrChunks.length - 256);
-	};
-	child.stderr?.on("data", onStderr);
-	yield* Effect.addFinalizer(() => Effect.sync(() => {
-		child.stderr?.off("data", onStderr);
-		if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
-	}));
+	], [
+		"ignore",
+		"pipe",
+		"pipe"
+	]);
 	const stdout = child.stdout;
 	if (stdout === null) return Stream.fail(new HostTreeTarError({
 		stage: "spawn",
@@ -278,37 +305,18 @@ const tarHostTree = (spec) => Stream.unwrap(Effect.gen(function* () {
 * exits cleanly (code 0).
 */
 const untarHostTree = (stream, spec) => Effect.gen(function* () {
-	const args = [
+	const { child, stderrChunks } = yield* spawnTar("untar", [
 		"-x",
 		"-f",
 		"-",
 		"-C",
 		spec.target,
 		"-p"
-	];
-	const child = yield* Effect.try({
-		try: () => spawn("tar", args, { stdio: [
-			"pipe",
-			"ignore",
-			"pipe"
-		] }),
-		catch: (cause) => new HostTreeTarError({
-			stage: "spawn",
-			operation: "untar",
-			detail: `failed to spawn 'tar ${args.join(" ")}'`,
-			cause
-		})
-	});
-	const stderrChunks = [];
-	const onStderr = (chunk) => {
-		stderrChunks.push(chunk);
-		if (stderrChunks.length > 256) stderrChunks.splice(0, stderrChunks.length - 256);
-	};
-	child.stderr?.on("data", onStderr);
-	yield* Effect.addFinalizer(() => Effect.sync(() => {
-		child.stderr?.off("data", onStderr);
-		if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
-	}));
+	], [
+		"pipe",
+		"ignore",
+		"pipe"
+	]);
 	const stdin = child.stdin;
 	if (stdin === null) return yield* Effect.fail(new HostTreeTarError({
 		stage: "spawn",
@@ -341,6 +349,9 @@ const untarHostTree = (stream, spec) => Effect.gen(function* () {
 			})));
 			else settle(Effect.void);
 		})) stdin.once("drain", onDrain);
+		return Effect.sync(() => {
+			stdin.off("drain", onDrain);
+		});
 	});
 	yield* Stream.runForEach(stream, (chunk) => Effect.gen(function* () {
 		const validationError = processTarValidationChunk(validationState, chunk);