@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/substrate/runtime/cross-process/roster.mjs

@@ -1,11 +1,10 @@
-import { SpanAttr } from "../observability/spans.mjs";
-import { versionedDocSchema } from "../../versioned-doc-schema.mjs";
-import { selfPid } from "./self-pid.mjs";
 import { DEFAULT_SWEEP_POLICY, RosterDocumentSchema } from "../../cross-process.mjs";
+import { selfPid } from "./self-pid.mjs";
 import { readVersionedDocumentSync, writeVersionedDocumentSync } from "../../versioned-doc-sync.mjs";
-import { LivenessProbeScope, isPidAlive, layerLivenessProbeScope, ownHolder, processStartTime } from "./liveness.mjs";
+import { LivenessProbeScope, layerLivenessProbeScope, ownHolder, processStartTime } from "./liveness.mjs";
 import { acquireStackLock } from "./stack-lock.mjs";
-import { Data, Effect, Schema } from "effect";
+import { LogAttr } from "../observability/log-attrs.mjs";
+import { Data, Effect } from "effect";
 import { hostname } from "node:os";
 //#region src/substrate/runtime/cross-process/roster.ts
 var RosterCorruptError = class extends Data.TaggedError("RosterCorruptError") {};
@@ -29,11 +28,11 @@ const ROSTER_DOC_ERRORS = {
 *  Tolerates a missing file but NOT a malformed file (a malformed
 *  roster surfaces a typed error so callers can decide whether to
 *  abandon or rewrite). */
-const readRoster = (path) => readVersionedDocumentSync(path, RosterDocumentSchema, ROSTER_DOC_ERRORS, EMPTY_ROSTER).pipe(Effect.withSpan("cross-process.roster.read"));
+const readRoster = (path) => readVersionedDocumentSync(path, RosterDocumentSchema, ROSTER_DOC_ERRORS, EMPTY_ROSTER);
 /** Atomic write: route through the canonical sync primitive. The
 *  roster's mutations are all under `stack.lock`, so the non-yielding
 *  sync surface is correct here — and it shares ONE owner of the
-*  tempfile dance with state-store, cache, and manifest. */
+*  tempfile dance with cache and manifest. */
 const atomicWriteRoster = (path, doc) => writeVersionedDocumentSync(path, doc, ROSTER_DOC_ERRORS);
 /** Walk the roster's holders and drop those that fail the liveness
 *  test AND whose heartbeats are older than `staleAfterMillis`.
@@ -48,13 +47,12 @@ const sweepStaleHolders = Effect.fn("cross-process.roster.sweep")(function* (doc
 	const probe = yield* LivenessProbeScope;
 	const survivors = [];
 	const evicted = [];
-	const ownHost = hostname();
 	for (const holder of doc.holders) {
 		if (!(now - holder.heartbeatAt > policy.staleAfterMillis)) {
 			survivors.push(holder);
 			continue;
 		}
-		if ((yield* probe.probeHolderLiveness(holder, ownHost).pipe(Effect.catch(() => Effect.succeed("alive")))) === "dead") evicted.push(holder);
+		if ((yield* probe.probeHolderLiveness(holder).pipe(Effect.catch(() => Effect.succeed("alive")))) === "dead") evicted.push(holder);
 		else survivors.push(holder);
 	}
 	return {
@@ -65,22 +63,10 @@ const sweepStaleHolders = Effect.fn("cross-process.roster.sweep")(function* (doc
 		evicted
 	};
 }, Effect.provide(layerLivenessProbeScope));
-/** Materialize the ledger path from `RosterPaths`. Callers that
-*  invoke any of the claim-ledger APIs (`readClaims`,
-*  `pruneStaleClaims`, `addClaim`, `removeClaim`) MUST construct
-*  `RosterPaths` with `containerClaimsFile` populated from
-*  `StackPathsService.containerClaimsFile`. The previous behavior of
-*  reconstructing `dirname(rosterFile) + '/container-claims.json'`
-*  internally has been removed so nothing in the runtime tree builds
-*  cross-process paths outside the substrate path resolver. */
-const requireClaimsPath = (paths) => {
-	if (paths.containerClaimsFile === void 0) throw new Error("cross-process.roster: container-claim API called without `containerClaimsFile` on the RosterPaths bundle. Source this from StackPathsService.containerClaimsFile.");
-	return paths.containerClaimsFile;
-};
 /** Match a roster holder against THIS process's identity.
 *
-*  Liveness elsewhere (`checkHolderLiveness`, `isContainerClaimLive`)
-*  uses `(pid, hostname, startTime)` — PID alone is insufficient on
+*  Liveness elsewhere (`checkHolderLiveness`) uses
+*  `(pid, hostname, startTime)` — PID alone is insufficient on
 *  long-uptime hosts where the kernel can recycle PIDs. The roster
 *  mutators (`heartbeat`, `release`, `setIntent`) must apply the same
 *  triple match so a recycled-PID peer's entry is never silently
@@ -88,8 +74,8 @@ const requireClaimsPath = (paths) => {
 *
 *  `startTime` is the FNV-1a hash of `ps -o lstart` (see
 *  `liveness.processStartTime`). A `null` probe (process gone, or
-*  exotic platform) skips the start-time check — same conservative
-*  policy as `isContainerClaimLive`. */
+*  exotic platform) skips the start-time check — the same conservative
+*  policy `checkHolderLiveness` applies. */
 const isOwnEntry = (h, ownPid, ownHost, ownStartTime) => {
 	if (h.pid !== ownPid || h.hostname !== ownHost) return false;
 	if (ownStartTime === null || h.startTime === null) return true;
@@ -111,10 +97,6 @@ const withStackLock = (paths, body) => Effect.scoped(Effect.gen(function* () {
 * Returns the swept document, our holder entry, and any evicted peers.
 */
 const claim = (paths, intent = "normal", policy = DEFAULT_SWEEP_POLICY) => withStackLock(paths, Effect.gen(function* () {
-	yield* Effect.annotateCurrentSpan({
-		"devstack.roster.path": paths.rosterFile,
-		"devstack.roster.intent": intent
-	});
 	const { swept, evicted } = yield* sweepStaleHolders(yield* readRoster(paths.rosterFile).pipe(Effect.catchTag("RosterCorruptError", () => Effect.succeed(EMPTY_ROSTER))), policy);
 	const self = { ...ownHolder(intent) };
 	const next = {
@@ -128,7 +110,7 @@ const claim = (paths, intent = "normal", policy = DEFAULT_SWEEP_POLICY) => withS
 		evicted,
 		soleHolder: swept.holders.length === 0
 	};
-})).pipe(Effect.withSpan("cross-process.roster.claim"));
+}));
 /**
 * Heartbeat protocol — refresh this process's `heartbeatAt`. Under the
 * stack lock to keep mutation atomic. Architecture § Heartbeat
@@ -154,7 +136,7 @@ const heartbeat = (paths, ownPid = selfPid()) => withStackLock(paths, Effect.gen
 		})
 	};
 	if (touched) yield* atomicWriteRoster(paths.rosterFile, next);
-})).pipe(Effect.withSpan("cross-process.roster.heartbeat"));
+}));
 /**
 * Release protocol — architecture § Release protocol.
 *
@@ -175,7 +157,7 @@ const release = (paths, ownPid = selfPid()) => withStackLock(paths, Effect.gen(f
 		roster: next,
 		lastLeaver: remaining.length === 0
 	};
-})).pipe(Effect.withSpan("cross-process.roster.release"));
+}));
 /** Background heartbeat fiber. Wakes every `intervalMillis` (default
 *  matches `DEFAULT_SWEEP_POLICY.heartbeatIntervalMillis`) and refreshes
 *  this process's `heartbeatAt`.
@@ -186,104 +168,12 @@ const heartbeatFiber = (paths, intervalMillis = DEFAULT_SWEEP_POLICY.heartbeatIn
 	while (true) {
 		yield* Effect.sleep(`${intervalMillis} millis`);
 		yield* heartbeat(paths).pipe(Effect.catch((err) => Effect.logWarning("roster heartbeat failed").pipe(Effect.annotateLogs({
-			[SpanAttr.rosterHeartbeatIntervalMs]: intervalMillis,
-			[SpanAttr.errorCause]: String(err)
+			[LogAttr.rosterHeartbeatIntervalMs]: intervalMillis,
+			[LogAttr.errorCause]: String(err)
 		}))));
 	}
-}).pipe(Effect.withSpan("cross-process.roster.heartbeatFiber"));
-const ContainerClaimSchema = Schema.Struct({
-	containerKey: Schema.String,
-	pid: Schema.Number,
-	startTime: Schema.optional(Schema.Number),
-	hostname: Schema.String,
-	claimedAt: Schema.Number
 });
-const ContainerClaimDocumentSchema = versionedDocSchema(1, { claims: Schema.Array(ContainerClaimSchema) });
-const EMPTY_CLAIMS = {
-	version: 1,
-	claims: []
-};
-/** Match a container claim against THIS process's identity using the
-*  same `(pid, hostname, startTime)` triple that `isOwnEntry` /
-*  `isContainerClaimLive` apply to roster holders — PID alone is
-*  insufficient on long-uptime hosts where the kernel recycles PIDs.
-*  A null/undefined start-time on either side falls back to
-*  `(pid, hostname)`, matching the conservative policy elsewhere
-*  (avoids orphaning our own entry when the probe failed). */
-const isOwnContainerClaim = (c, containerKey, ownPid, ownHost, ownStartTime) => {
-	if (c.containerKey !== containerKey || c.pid !== ownPid || c.hostname !== ownHost) return false;
-	if (ownStartTime === void 0 || c.startTime === void 0) return true;
-	return c.startTime === ownStartTime;
-};
-const isContainerClaimLive = (claim, probeStartTime, ownHost = hostname()) => {
-	if (claim.hostname !== ownHost) return true;
-	if (!isPidAlive(claim.pid)) return false;
-	if (claim.startTime === void 0) return true;
-	const probedStart = probeStartTime(claim.pid);
-	if (probedStart === null) return true;
-	return probedStart === claim.startTime;
-};
-/** Effect-flavored filter that yields a fresh `LivenessProbeScope` so
-*  the same pid is probed at most once across this pass — even when
-*  multiple claims by the same pid sit in the ledger. The scope's
-*  cache is private to this call (provided via `Effect.provide`). */
-const liveContainerClaims = (doc) => Effect.gen(function* () {
-	const probe = yield* LivenessProbeScope;
-	const ownHost = hostname();
-	return {
-		version: 1,
-		claims: doc.claims.filter((claim) => isContainerClaimLive(claim, probe.probeStartTime, ownHost))
-	};
-}).pipe(Effect.provide(layerLivenessProbeScope));
-const writeClaims = (path, doc) => writeVersionedDocumentSync(path, doc, ROSTER_DOC_ERRORS);
-/** Read the container-claim ledger. */
-const readClaims = (paths) => Effect.suspend(() => readVersionedDocumentSync(requireClaimsPath(paths), ContainerClaimDocumentSchema, ROSTER_DOC_ERRORS, EMPTY_CLAIMS)).pipe(Effect.withSpan("cross-process.roster.readClaims"));
-/** Record that this process now claims `containerKey`. No-op if
-*  already claimed by this process. */
-const addClaim = (paths, containerKey) => withStackLock(paths, Effect.gen(function* () {
-	const path = requireClaimsPath(paths);
-	const current = yield* readClaims(paths).pipe(Effect.catchTag("RosterCorruptError", () => Effect.succeed(EMPTY_CLAIMS)));
-	const live = yield* liveContainerClaims(current);
-	const ownPid = selfPid();
-	const ownStartTime = processStartTime(ownPid) ?? void 0;
-	const ownHost = hostname();
-	if (live.claims.some((c) => isOwnContainerClaim(c, containerKey, ownPid, ownHost, ownStartTime))) {
-		if (live.claims.length !== current.claims.length) yield* writeClaims(path, live);
-		return;
-	}
-	yield* writeClaims(path, {
-		version: 1,
-		claims: [...live.claims, {
-			containerKey,
-			pid: ownPid,
-			...ownStartTime === void 0 ? {} : { startTime: ownStartTime },
-			hostname: ownHost,
-			claimedAt: Date.now()
-		}]
-	});
-})).pipe(Effect.withSpan("cross-process.roster.addClaim"));
-/** Release this process's claim on `containerKey`. Returns whether
-*  the container has zero remaining claims AFTER this release — the
-*  "last-leaver" signal that authorizes a teardown.
-*
-*  Architecture § Cross-process safety protocol: "when a process
-*  releases its last claim and confirms no other process holds the
-*  container, it may tear down." */
-const removeClaim = (paths, containerKey) => withStackLock(paths, Effect.gen(function* () {
-	const path = requireClaimsPath(paths);
-	const live = yield* liveContainerClaims(yield* readClaims(paths).pipe(Effect.catchTag("RosterCorruptError", () => Effect.succeed(EMPTY_CLAIMS))));
-	const ownPid = selfPid();
-	const ownStartTime = processStartTime(ownPid) ?? void 0;
-	const ownHost = hostname();
-	const remaining = live.claims.filter((c) => !isOwnContainerClaim(c, containerKey, ownPid, ownHost, ownStartTime));
-	const stillClaimedByPeer = remaining.some((c) => c.containerKey === containerKey);
-	yield* writeClaims(path, {
-		version: 1,
-		claims: remaining
-	});
-	return { lastClaimReleased: !stillClaimedByPeer };
-})).pipe(Effect.withSpan("cross-process.roster.removeClaim"));
 //#endregion
-export { RosterCorruptError, RosterIoError, addClaim, claim, heartbeat, heartbeatFiber, readClaims, readRoster, release, removeClaim, sweepStaleHolders };
+export { RosterCorruptError, RosterIoError, claim, heartbeat, heartbeatFiber, readRoster, release, sweepStaleHolders };
 
 //# sourceMappingURL=roster.mjs.map

package/dist/substrate/runtime/cross-process/roster.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"roster.mjs","names":["nodeHostname"],"sources":["../../../../src/substrate/runtime/cross-process/roster.ts"],"sourcesContent":["// `roster.json` — authoritative cross-process holder record.\n//\n// Architecture § Cross-process safety protocol § Roster:\n//   \"the authoritative cross-process record of which OS processes are\n//    currently 'in' this stack.\"\n//\n// Mutated only under `stack.lock`. Schema-validated on every read so a\n// truncated/forward-version write never corrupts a peer's view. Stale\n// entries reaped during step-3 sweep on the next claim.\n\nimport { hostname as nodeHostname } from 'node:os';\n\nimport { Data, Effect, Schema } from 'effect';\n\nimport {\n\tDEFAULT_SWEEP_POLICY,\n\ttype RosterDocument,\n\tRosterDocumentSchema,\n\ttype RosterHolder,\n\ttype RosterSweepPolicy,\n} from '../../cross-process.ts';\nimport { SpanAttr } from '../observability/spans.ts';\nimport { versionedDocSchema } from '../../versioned-doc-schema.ts';\nimport {\n\treadVersionedDocumentSync,\n\twriteVersionedDocumentSync,\n} from '../../versioned-doc-sync.ts';\nimport { selfPid } from './self-pid.ts';\nimport { acquireStackLock } from './stack-lock.ts';\nimport {\n\tisPidAlive,\n\tlayerLivenessProbeScope,\n\tLivenessProbeScope,\n\townHolder,\n\tprocessStartTime,\n} from './liveness.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\nexport class RosterCorruptError extends Data.TaggedError('RosterCorruptError')<{\n\treadonly path: string;\n\treadonly raw: string;\n\treadonly cause: unknown;\n}> {}\n\nexport class RosterIoError extends Data.TaggedError('RosterIoError')<{\n\treadonly path: string;\n\treadonly cause: unknown;\n}> {}\n\nexport type RosterError = RosterCorruptError | RosterIoError;\n\n// -----------------------------------------------------------------------------\n// Read / write\n// -----------------------------------------------------------------------------\n\nconst EMPTY_ROSTER: RosterDocument = { version: 1, holders: [] };\n\nconst ROSTER_DOC_ERRORS = {\n\tmkIo: ({ path, cause }: { path: string; cause: unknown }) => new RosterIoError({ path, cause }),\n\tmkCorrupt: ({ path, raw, cause }: { path: string; raw: string; cause: unknown }) =>\n\t\tnew RosterCorruptError({ path, raw, cause }),\n} as const;\n\n/** Read the roster from disk. Returns the empty document if absent.\n *  Tolerates a missing file but NOT a malformed file (a malformed\n *  roster surfaces a typed error so callers can decide whether to\n *  abandon or rewrite). */\nexport const readRoster = (path: string): Effect.Effect<RosterDocument, RosterError> =>\n\treadVersionedDocumentSync(path, RosterDocumentSchema, ROSTER_DOC_ERRORS, EMPTY_ROSTER).pipe(\n\t\tEffect.withSpan('cross-process.roster.read'),\n\t);\n\n/** Atomic write: route through the canonical sync primitive. The\n *  roster's mutations are all under `stack.lock`, so the non-yielding\n *  sync surface is correct here — and it shares ONE owner of the\n *  tempfile dance with state-store, cache, and manifest. */\nconst atomicWriteRoster = (path: string, doc: RosterDocument): Effect.Effect<void, RosterIoError> =>\n\twriteVersionedDocumentSync(path, doc, ROSTER_DOC_ERRORS);\n\n// -----------------------------------------------------------------------------\n// Sweep\n// -----------------------------------------------------------------------------\n\n/** Walk the roster's holders and drop those that fail the liveness\n *  test AND whose heartbeats are older than `staleAfterMillis`.\n *\n *  Architecture § Claim protocol step 3 — \"Holders whose\n *  `heartbeatAt` is older than 3× the heartbeat interval AND who fail\n *  the PID liveness check are evicted.\"\n *\n *  A live holder with a stale heartbeat is NOT evicted — heartbeat\n *  staleness alone is allowed (slow peer). The conjunction matters. */\nexport const sweepStaleHolders = Effect.fn('cross-process.roster.sweep')(function* (\n\tdoc: RosterDocument,\n\tpolicy: RosterSweepPolicy = DEFAULT_SWEEP_POLICY,\n\tnow: number = Date.now(),\n) {\n\t// Yield a fresh per-sweep liveness scope so the same pid is probed\n\t// AT MOST once across all holders in this pass — two holders sharing\n\t// a pid (corrupted-roster edge case) collapse to one fork. The\n\t// `Layer.provide` below scopes the cache to THIS sweep only.\n\tconst probe = yield* LivenessProbeScope;\n\tconst survivors: RosterHolder[] = [];\n\tconst evicted: RosterHolder[] = [];\n\tconst ownHost = nodeHostname();\n\tfor (const holder of doc.holders) {\n\t\tconst heartbeatStale = now - holder.heartbeatAt > policy.staleAfterMillis;\n\t\tif (!heartbeatStale) {\n\t\t\tsurvivors.push(holder);\n\t\t\tcontinue;\n\t\t}\n\t\tconst liveness = yield* probe\n\t\t\t.probeHolderLiveness(holder, ownHost)\n\t\t\t.pipe(Effect.catch(() => Effect.succeed('alive' as const)));\n\t\tif (liveness === 'dead') {\n\t\t\tevicted.push(holder);\n\t\t} else {\n\t\t\tsurvivors.push(holder);\n\t\t}\n\t}\n\treturn {\n\t\tswept: { version: doc.version, holders: survivors } satisfies RosterDocument,\n\t\tevicted: evicted as ReadonlyArray<RosterHolder>,\n\t};\n}, Effect.provide(layerLivenessProbeScope));\n\n// -----------------------------------------------------------------------------\n// Claim / release / heartbeat\n// -----------------------------------------------------------------------------\n\n/** Outcome of a claim: the holder this process registered, the swept\n *  document, and whether this process is now the sole holder. */\nexport interface ClaimResult {\n\treadonly self: RosterHolder;\n\treadonly roster: RosterDocument;\n\treadonly evicted: ReadonlyArray<RosterHolder>;\n\treadonly soleHolder: boolean;\n}\n\n/** Outcome of a release: the swept document and whether this process\n *  was the last leaver (no peers remain after removal). Architecture §\n *  Release protocol step 4. */\nexport interface ReleaseResult {\n\treadonly roster: RosterDocument;\n\treadonly lastLeaver: boolean;\n}\n\ninterface RosterPaths {\n\treadonly stackLockFile: string;\n\treadonly rosterFile: string;\n\t/** Sibling-file path for the container-claim ledger. Optional\n\t *  because the roster's holder mutations (`claim` / `release` /\n\t *  `heartbeat` / `setIntent`) never touch the ledger; only the\n\t *  `addClaim` / `removeClaim` / `readClaims` / `pruneStaleClaims`\n\t *  entry points require it, and they assert presence at the call\n\t *  site. Sourced from `StackPathsService.containerClaimsFile` —\n\t *  see `substrate/runtime/paths.ts` for the policy rationale\n\t *  (closed L0 path resolver). */\n\treadonly containerClaimsFile?: string;\n}\n\n/** Materialize the ledger path from `RosterPaths`. Callers that\n *  invoke any of the claim-ledger APIs (`readClaims`,\n *  `pruneStaleClaims`, `addClaim`, `removeClaim`) MUST construct\n *  `RosterPaths` with `containerClaimsFile` populated from\n *  `StackPathsService.containerClaimsFile`. The previous behavior of\n *  reconstructing `dirname(rosterFile) + '/container-claims.json'`\n *  internally has been removed so nothing in the runtime tree builds\n *  cross-process paths outside the substrate path resolver. */\nconst requireClaimsPath = (paths: RosterPaths): string => {\n\tif (paths.containerClaimsFile === undefined) {\n\t\tthrow new Error(\n\t\t\t'cross-process.roster: container-claim API called without `containerClaimsFile` ' +\n\t\t\t\t'on the RosterPaths bundle. Source this from StackPathsService.containerClaimsFile.',\n\t\t);\n\t}\n\treturn paths.containerClaimsFile;\n};\n\n/** Match a roster holder against THIS process's identity.\n *\n *  Liveness elsewhere (`checkHolderLiveness`, `isContainerClaimLive`)\n *  uses `(pid, hostname, startTime)` — PID alone is insufficient on\n *  long-uptime hosts where the kernel can recycle PIDs. The roster\n *  mutators (`heartbeat`, `release`, `setIntent`) must apply the same\n *  triple match so a recycled-PID peer's entry is never silently\n *  overwritten/removed by this process.\n *\n *  `startTime` is the FNV-1a hash of `ps -o lstart` (see\n *  `liveness.processStartTime`). A `null` probe (process gone, or\n *  exotic platform) skips the start-time check — same conservative\n *  policy as `isContainerClaimLive`. */\nconst isOwnEntry = (\n\th: RosterHolder,\n\townPid: number,\n\townHost: string,\n\townStartTime: number | null,\n): boolean => {\n\tif (h.pid !== ownPid || h.hostname !== ownHost) return false;\n\t// Either side null → fall back to (pid, hostname). The roster's\n\t// own-entry test must symmetrically accept a null recorded stamp:\n\t// the writer's probe failed (exotic platform / transient `ps`\n\t// error) but the entry IS ours. Mismatching a probed `ownStartTime`\n\t// against a recorded `null` would orphan our own entry — peers\n\t// would then harvest it as \"dead\" on the next sweep.\n\tif (ownStartTime === null || h.startTime === null) return true;\n\treturn h.startTime === ownStartTime;\n};\n\nconst withStackLock = <A, E, R>(\n\tpaths: RosterPaths,\n\tbody: Effect.Effect<A, E, R>,\n): Effect.Effect<A, E | import('./stack-lock.ts').StackLockError, R> =>\n\tEffect.scoped(\n\t\tEffect.gen(function* () {\n\t\t\tyield* acquireStackLock(paths.stackLockFile);\n\t\t\treturn yield* body;\n\t\t}),\n\t);\n\n/**\n * Claim protocol — architecture § Claim protocol.\n *\n * Under the exclusive lock:\n *  1. Read the roster (or initialize empty if missing).\n *  2. Sweep stale holders (PID liveness + heartbeat age).\n *  3. Append this process's entry.\n *  4. Atomic write the result.\n *\n * Returns the swept document, our holder entry, and any evicted peers.\n */\nexport const claim = (\n\tpaths: RosterPaths,\n\tintent: 'normal' | 'snapshot' = 'normal',\n\tpolicy: RosterSweepPolicy = DEFAULT_SWEEP_POLICY,\n): Effect.Effect<ClaimResult, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t'devstack.roster.path': paths.rosterFile,\n\t\t\t\t'devstack.roster.intent': intent,\n\t\t\t});\n\t\t\tconst initial = yield* readRoster(paths.rosterFile).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_ROSTER)),\n\t\t\t);\n\t\t\tconst { swept, evicted } = yield* sweepStaleHolders(initial, policy);\n\t\t\tconst self: RosterHolder = { ...ownHolder(intent) };\n\t\t\tconst next: RosterDocument = {\n\t\t\t\tversion: 1,\n\t\t\t\tholders: [...swept.holders, self],\n\t\t\t};\n\t\t\tyield* atomicWriteRoster(paths.rosterFile, next);\n\t\t\treturn {\n\t\t\t\tself,\n\t\t\t\troster: next,\n\t\t\t\tevicted,\n\t\t\t\tsoleHolder: swept.holders.length === 0,\n\t\t\t};\n\t\t}),\n\t).pipe(Effect.withSpan('cross-process.roster.claim'));\n\n/**\n * Heartbeat protocol — refresh this process's `heartbeatAt`. Under the\n * stack lock to keep mutation atomic. Architecture § Heartbeat\n * protocol.\n */\nexport const heartbeat = (\n\tpaths: RosterPaths,\n\townPid: number = selfPid(),\n): Effect.Effect<void, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst current = yield* readRoster(paths.rosterFile).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_ROSTER)),\n\t\t\t);\n\t\t\tconst now = Date.now();\n\t\t\tconst ownHost = nodeHostname();\n\t\t\tconst ownStartTime = processStartTime(ownPid);\n\t\t\tlet touched = false;\n\t\t\tconst next: RosterDocument = {\n\t\t\t\tversion: 1,\n\t\t\t\tholders: current.holders.map((h) => {\n\t\t\t\t\tif (isOwnEntry(h, ownPid, ownHost, ownStartTime)) {\n\t\t\t\t\t\ttouched = true;\n\t\t\t\t\t\treturn { ...h, heartbeatAt: now };\n\t\t\t\t\t}\n\t\t\t\t\treturn h;\n\t\t\t\t}),\n\t\t\t};\n\t\t\tif (touched) yield* atomicWriteRoster(paths.rosterFile, next);\n\t\t}),\n\t).pipe(Effect.withSpan('cross-process.roster.heartbeat'));\n\n/**\n * Release protocol — architecture § Release protocol.\n *\n * Removes this process's holder. Returns whether this was the\n * last-leaver (caller runs the stop finalizer if so).\n */\nexport const release = (\n\tpaths: RosterPaths,\n\townPid: number = selfPid(),\n): Effect.Effect<ReleaseResult, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst current = yield* readRoster(paths.rosterFile).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_ROSTER)),\n\t\t\t);\n\t\t\tconst ownHost = nodeHostname();\n\t\t\tconst ownStartTime = processStartTime(ownPid);\n\t\t\tconst remaining = current.holders.filter(\n\t\t\t\t(h) => !isOwnEntry(h, ownPid, ownHost, ownStartTime),\n\t\t\t);\n\t\t\tconst next: RosterDocument = { version: 1, holders: remaining };\n\t\t\tyield* atomicWriteRoster(paths.rosterFile, next);\n\t\t\treturn {\n\t\t\t\troster: next,\n\t\t\t\tlastLeaver: remaining.length === 0,\n\t\t\t};\n\t\t}),\n\t).pipe(Effect.withSpan('cross-process.roster.release'));\n\n/**\n * Set this process's `intent` (`normal` ↔ `snapshot`) under the\n * exclusive lock. Architecture § Concurrent snapshot step 2 / 5.\n */\nexport const setIntent = (\n\tpaths: RosterPaths,\n\tintent: 'normal' | 'snapshot',\n\townPid: number = selfPid(),\n): Effect.Effect<void, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst current = yield* readRoster(paths.rosterFile).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_ROSTER)),\n\t\t\t);\n\t\t\tconst ownHost = nodeHostname();\n\t\t\tconst ownStartTime = processStartTime(ownPid);\n\t\t\tconst next: RosterDocument = {\n\t\t\t\tversion: 1,\n\t\t\t\tholders: current.holders.map((h) =>\n\t\t\t\t\tisOwnEntry(h, ownPid, ownHost, ownStartTime) ? { ...h, intent } : h,\n\t\t\t\t),\n\t\t\t};\n\t\t\tyield* atomicWriteRoster(paths.rosterFile, next);\n\t\t}),\n\t).pipe(Effect.withSpan('cross-process.roster.setIntent'));\n\n/** Background heartbeat fiber. Wakes every `intervalMillis` (default\n *  matches `DEFAULT_SWEEP_POLICY.heartbeatIntervalMillis`) and refreshes\n *  this process's `heartbeatAt`.\n *\n *  Returns an Effect that runs forever in its Scope — the supervisor\n *  forks it via `Effect.forkScoped` so it tears down with the stack. */\nexport const heartbeatFiber = (\n\tpaths: RosterPaths,\n\tintervalMillis: number = DEFAULT_SWEEP_POLICY.heartbeatIntervalMillis,\n): Effect.Effect<never> =>\n\tEffect.gen(function* () {\n\t\twhile (true) {\n\t\t\tyield* Effect.sleep(`${intervalMillis} millis`);\n\t\t\tyield* heartbeat(paths).pipe(\n\t\t\t\t// A heartbeat failure is non-fatal — the next peer's sweep\n\t\t\t\t// would otherwise evict us, but the architecture treats this\n\t\t\t\t// as \"the dev didn't get to flush a heartbeat in time;\n\t\t\t\t// recover by retrying next interval.\" Log via Effect's\n\t\t\t\t// logger; do not propagate.\n\t\t\t\tEffect.catch((err) =>\n\t\t\t\t\tEffect.logWarning('roster heartbeat failed').pipe(\n\t\t\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t\t\t[SpanAttr.rosterHeartbeatIntervalMs]: intervalMillis,\n\t\t\t\t\t\t\t[SpanAttr.errorCause]: String(err),\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t}).pipe(Effect.withSpan('cross-process.roster.heartbeatFiber'));\n\n// -----------------------------------------------------------------------------\n// Container-claim ledger\n// -----------------------------------------------------------------------------\n//\n// Architecture § Cross-process safety protocol: roster \"Records claimed\n// containers per process. Last-leaver semantics: when a process\n// releases its last claim and confirms no other process holds the\n// container, it may tear down.\"\n//\n// The roster document carries holders only — the per-container claim\n// ledger lives in an EXTENSION file at `<stackRoot>/container-claims.json`\n// so the architecture-mandated `RosterDocument` shape doesn't widen.\n// Same atomicity discipline: mutate under `stack.lock`.\n\nexport interface ContainerClaim {\n\treadonly containerKey: string;\n\treadonly pid: number;\n\treadonly startTime?: number;\n\treadonly hostname: string;\n\treadonly claimedAt: number;\n}\n\nexport interface ContainerClaimDocument {\n\treadonly version: 1;\n\treadonly claims: ReadonlyArray<ContainerClaim>;\n}\n\nconst ContainerClaimSchema = Schema.Struct({\n\tcontainerKey: Schema.String,\n\tpid: Schema.Number,\n\tstartTime: Schema.optional(Schema.Number),\n\thostname: Schema.String,\n\tclaimedAt: Schema.Number,\n});\n\nconst ContainerClaimDocumentSchema = versionedDocSchema(1, {\n\tclaims: Schema.Array(ContainerClaimSchema),\n});\n\nconst EMPTY_CLAIMS: ContainerClaimDocument = { version: 1, claims: [] };\n\n/** Match a container claim against THIS process's identity using the\n *  same `(pid, hostname, startTime)` triple that `isOwnEntry` /\n *  `isContainerClaimLive` apply to roster holders — PID alone is\n *  insufficient on long-uptime hosts where the kernel recycles PIDs.\n *  A null/undefined start-time on either side falls back to\n *  `(pid, hostname)`, matching the conservative policy elsewhere\n *  (avoids orphaning our own entry when the probe failed). */\nconst isOwnContainerClaim = (\n\tc: ContainerClaim,\n\tcontainerKey: string,\n\townPid: number,\n\townHost: string,\n\townStartTime: number | undefined,\n): boolean => {\n\tif (c.containerKey !== containerKey || c.pid !== ownPid || c.hostname !== ownHost) return false;\n\tif (ownStartTime === undefined || c.startTime === undefined) return true;\n\treturn c.startTime === ownStartTime;\n};\n\nconst isContainerClaimLive = (\n\tclaim: ContainerClaim,\n\tprobeStartTime: (pid: number) => number | null,\n\townHost: string = nodeHostname(),\n): boolean => {\n\tif (claim.hostname !== ownHost) return true;\n\tif (!isPidAlive(claim.pid)) return false;\n\tif (claim.startTime === undefined) return true;\n\tconst probedStart = probeStartTime(claim.pid);\n\tif (probedStart === null) return true;\n\treturn probedStart === claim.startTime;\n};\n\n/** Effect-flavored filter that yields a fresh `LivenessProbeScope` so\n *  the same pid is probed at most once across this pass — even when\n *  multiple claims by the same pid sit in the ledger. The scope's\n *  cache is private to this call (provided via `Effect.provide`). */\nconst liveContainerClaims = (\n\tdoc: ContainerClaimDocument,\n): Effect.Effect<ContainerClaimDocument> =>\n\tEffect.gen(function* () {\n\t\tconst probe = yield* LivenessProbeScope;\n\t\tconst ownHost = nodeHostname();\n\t\tconst filtered: ContainerClaimDocument = {\n\t\t\tversion: 1,\n\t\t\tclaims: doc.claims.filter((claim) =>\n\t\t\t\tisContainerClaimLive(claim, probe.probeStartTime, ownHost),\n\t\t\t),\n\t\t};\n\t\treturn filtered;\n\t}).pipe(Effect.provide(layerLivenessProbeScope));\n\nconst writeClaims = (\n\tpath: string,\n\tdoc: ContainerClaimDocument,\n): Effect.Effect<void, RosterIoError> => writeVersionedDocumentSync(path, doc, ROSTER_DOC_ERRORS);\n\n/** Read the container-claim ledger. */\nexport const readClaims = (\n\tpaths: RosterPaths,\n): Effect.Effect<ContainerClaimDocument, RosterError> =>\n\tEffect.suspend(() =>\n\t\treadVersionedDocumentSync(\n\t\t\trequireClaimsPath(paths),\n\t\t\tContainerClaimDocumentSchema,\n\t\t\tROSTER_DOC_ERRORS,\n\t\t\tEMPTY_CLAIMS,\n\t\t),\n\t).pipe(Effect.withSpan('cross-process.roster.readClaims'));\n\n/** Prune stale same-host claims. This is the recovery path for an\n *  interrupted process that could not run its scope finalizer. */\nexport const pruneStaleClaims = (\n\tpaths: RosterPaths,\n): Effect.Effect<ContainerClaimDocument, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst path = requireClaimsPath(paths);\n\t\t\tconst current = yield* readClaims(paths).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_CLAIMS)),\n\t\t\t);\n\t\t\tconst next = yield* liveContainerClaims(current);\n\t\t\tif (next.claims.length !== current.claims.length) {\n\t\t\t\tyield* writeClaims(path, next);\n\t\t\t}\n\t\t\treturn next;\n\t\t}),\n\t).pipe(Effect.withSpan('cross-process.roster.pruneStaleClaims'));\n\n/** Record that this process now claims `containerKey`. No-op if\n *  already claimed by this process. */\nexport const addClaim = (\n\tpaths: RosterPaths,\n\tcontainerKey: string,\n): Effect.Effect<void, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst path = requireClaimsPath(paths);\n\t\t\tconst current = yield* readClaims(paths).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_CLAIMS)),\n\t\t\t);\n\t\t\t// `liveContainerClaims` pre-filter must run BEFORE the own-claim\n\t\t\t// scan below: it drops dead peers so a recycled-PID peer can't\n\t\t\t// shadow our own (pid, hostname, startTime) identity. Ordering\n\t\t\t// here is load-bearing.\n\t\t\tconst live = yield* liveContainerClaims(current);\n\t\t\tconst ownPid = selfPid();\n\t\t\tconst ownStartTime = processStartTime(ownPid) ?? undefined;\n\t\t\tconst ownHost = nodeHostname();\n\t\t\tif (\n\t\t\t\tlive.claims.some((c) =>\n\t\t\t\t\tisOwnContainerClaim(c, containerKey, ownPid, ownHost, ownStartTime),\n\t\t\t\t)\n\t\t\t) {\n\t\t\t\tif (live.claims.length !== current.claims.length) yield* writeClaims(path, live);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst next: ContainerClaimDocument = {\n\t\t\t\tversion: 1,\n\t\t\t\tclaims: [\n\t\t\t\t\t...live.claims,\n\t\t\t\t\t{\n\t\t\t\t\t\tcontainerKey,\n\t\t\t\t\t\tpid: ownPid,\n\t\t\t\t\t\t...(ownStartTime === undefined ? {} : { startTime: ownStartTime }),\n\t\t\t\t\t\thostname: ownHost,\n\t\t\t\t\t\tclaimedAt: Date.now(),\n\t\t\t\t\t},\n\t\t\t\t],\n\t\t\t};\n\t\t\tyield* writeClaims(path, next);\n\t\t}),\n\t).pipe(Effect.withSpan('cross-process.roster.addClaim'));\n\n/** Release this process's claim on `containerKey`. Returns whether\n *  the container has zero remaining claims AFTER this release — the\n *  \"last-leaver\" signal that authorizes a teardown.\n *\n *  Architecture § Cross-process safety protocol: \"when a process\n *  releases its last claim and confirms no other process holds the\n *  container, it may tear down.\" */\nexport const removeClaim = (\n\tpaths: RosterPaths,\n\tcontainerKey: string,\n): Effect.Effect<\n\t{ readonly lastClaimReleased: boolean },\n\tRosterError | import('./stack-lock.ts').StackLockError\n> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst path = requireClaimsPath(paths);\n\t\t\tconst current = yield* readClaims(paths).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_CLAIMS)),\n\t\t\t);\n\t\t\t// `liveContainerClaims` pre-filter must run BEFORE the own-claim\n\t\t\t// scan below: it drops dead peers so a recycled-PID peer can't\n\t\t\t// shadow our own (pid, hostname, startTime) identity. Ordering\n\t\t\t// here is load-bearing.\n\t\t\tconst live = yield* liveContainerClaims(current);\n\t\t\tconst ownPid = selfPid();\n\t\t\tconst ownStartTime = processStartTime(ownPid) ?? undefined;\n\t\t\tconst ownHost = nodeHostname();\n\t\t\tconst remaining = live.claims.filter(\n\t\t\t\t(c) => !isOwnContainerClaim(c, containerKey, ownPid, ownHost, ownStartTime),\n\t\t\t);\n\t\t\tconst stillClaimedByPeer = remaining.some((c) => c.containerKey === containerKey);\n\t\t\tconst next: ContainerClaimDocument = { version: 1, claims: remaining };\n\t\t\tyield* writeClaims(path, next);\n\t\t\treturn { lastClaimReleased: !stillClaimedByPeer };\n\t\t}),\n\t).pipe(Effect.withSpan('cross-process.roster.removeClaim'));\n"],"mappings":"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"}
+{"version":3,"file":"roster.mjs","names":["nodeHostname"],"sources":["../../../../src/substrate/runtime/cross-process/roster.ts"],"sourcesContent":["// `roster.json` — authoritative cross-process holder record.\n//\n// Architecture § Cross-process safety protocol § Roster:\n//   \"the authoritative cross-process record of which OS processes are\n//    currently 'in' this stack.\"\n//\n// Mutated only under `stack.lock`. Schema-validated on every read so a\n// truncated/forward-version write never corrupts a peer's view. Stale\n// entries reaped during step-3 sweep on the next claim.\n\nimport { hostname as nodeHostname } from 'node:os';\n\nimport { Data, Effect } from 'effect';\n\nimport {\n\tDEFAULT_SWEEP_POLICY,\n\ttype RosterDocument,\n\tRosterDocumentSchema,\n\ttype RosterHolder,\n\ttype RosterSweepPolicy,\n} from '../../cross-process.ts';\nimport { LogAttr } from '../observability/log-attrs.ts';\nimport { readVersionedDocumentSync, writeVersionedDocumentSync } from '../../versioned-doc-sync.ts';\nimport { selfPid } from './self-pid.ts';\nimport { acquireStackLock } from './stack-lock.ts';\nimport {\n\tlayerLivenessProbeScope,\n\tLivenessProbeScope,\n\townHolder,\n\tprocessStartTime,\n} from './liveness.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\nexport class RosterCorruptError extends Data.TaggedError('RosterCorruptError')<{\n\treadonly path: string;\n\treadonly raw: string;\n\treadonly cause: unknown;\n}> {}\n\nexport class RosterIoError extends Data.TaggedError('RosterIoError')<{\n\treadonly path: string;\n\treadonly cause: unknown;\n}> {}\n\nexport type RosterError = RosterCorruptError | RosterIoError;\n\n// -----------------------------------------------------------------------------\n// Read / write\n// -----------------------------------------------------------------------------\n\nconst EMPTY_ROSTER: RosterDocument = { version: 1, holders: [] };\n\nconst ROSTER_DOC_ERRORS = {\n\tmkIo: ({ path, cause }: { path: string; cause: unknown }) => new RosterIoError({ path, cause }),\n\tmkCorrupt: ({ path, raw, cause }: { path: string; raw: string; cause: unknown }) =>\n\t\tnew RosterCorruptError({ path, raw, cause }),\n} as const;\n\n/** Read the roster from disk. Returns the empty document if absent.\n *  Tolerates a missing file but NOT a malformed file (a malformed\n *  roster surfaces a typed error so callers can decide whether to\n *  abandon or rewrite). */\nexport const readRoster = (path: string): Effect.Effect<RosterDocument, RosterError> =>\n\treadVersionedDocumentSync(path, RosterDocumentSchema, ROSTER_DOC_ERRORS, EMPTY_ROSTER);\n\n/** Atomic write: route through the canonical sync primitive. The\n *  roster's mutations are all under `stack.lock`, so the non-yielding\n *  sync surface is correct here — and it shares ONE owner of the\n *  tempfile dance with cache and manifest. */\nconst atomicWriteRoster = (path: string, doc: RosterDocument): Effect.Effect<void, RosterIoError> =>\n\twriteVersionedDocumentSync(path, doc, ROSTER_DOC_ERRORS);\n\n// -----------------------------------------------------------------------------\n// Sweep\n// -----------------------------------------------------------------------------\n\n/** Walk the roster's holders and drop those that fail the liveness\n *  test AND whose heartbeats are older than `staleAfterMillis`.\n *\n *  Architecture § Claim protocol step 3 — \"Holders whose\n *  `heartbeatAt` is older than 3× the heartbeat interval AND who fail\n *  the PID liveness check are evicted.\"\n *\n *  A live holder with a stale heartbeat is NOT evicted — heartbeat\n *  staleness alone is allowed (slow peer). The conjunction matters. */\nexport const sweepStaleHolders = Effect.fn('cross-process.roster.sweep')(function* (\n\tdoc: RosterDocument,\n\tpolicy: RosterSweepPolicy = DEFAULT_SWEEP_POLICY,\n\tnow: number = Date.now(),\n) {\n\t// Yield a fresh per-sweep liveness scope so the same pid is probed\n\t// AT MOST once across all holders in this pass — two holders sharing\n\t// a pid (corrupted-roster edge case) collapse to one fork. The\n\t// `Layer.provide` below scopes the cache to THIS sweep only.\n\tconst probe = yield* LivenessProbeScope;\n\tconst survivors: RosterHolder[] = [];\n\tconst evicted: RosterHolder[] = [];\n\tfor (const holder of doc.holders) {\n\t\tconst heartbeatStale = now - holder.heartbeatAt > policy.staleAfterMillis;\n\t\tif (!heartbeatStale) {\n\t\t\tsurvivors.push(holder);\n\t\t\tcontinue;\n\t\t}\n\t\tconst liveness = yield* probe\n\t\t\t.probeHolderLiveness(holder)\n\t\t\t.pipe(Effect.catch(() => Effect.succeed('alive' as const)));\n\t\tif (liveness === 'dead') {\n\t\t\tevicted.push(holder);\n\t\t} else {\n\t\t\tsurvivors.push(holder);\n\t\t}\n\t}\n\treturn {\n\t\tswept: { version: doc.version, holders: survivors } satisfies RosterDocument,\n\t\tevicted: evicted as ReadonlyArray<RosterHolder>,\n\t};\n}, Effect.provide(layerLivenessProbeScope));\n\n// -----------------------------------------------------------------------------\n// Claim / release / heartbeat\n// -----------------------------------------------------------------------------\n\n/** Outcome of a claim: the holder this process registered, the swept\n *  document, and whether this process is now the sole holder. */\nexport interface ClaimResult {\n\treadonly self: RosterHolder;\n\treadonly roster: RosterDocument;\n\treadonly evicted: ReadonlyArray<RosterHolder>;\n\treadonly soleHolder: boolean;\n}\n\n/** Outcome of a release: the swept document and whether this process\n *  was the last leaver (no peers remain after removal). Architecture §\n *  Release protocol step 4. */\nexport interface ReleaseResult {\n\treadonly roster: RosterDocument;\n\treadonly lastLeaver: boolean;\n}\n\ninterface RosterPaths {\n\treadonly stackLockFile: string;\n\treadonly rosterFile: string;\n}\n\n/** Match a roster holder against THIS process's identity.\n *\n *  Liveness elsewhere (`checkHolderLiveness`) uses\n *  `(pid, hostname, startTime)` — PID alone is insufficient on\n *  long-uptime hosts where the kernel can recycle PIDs. The roster\n *  mutators (`heartbeat`, `release`, `setIntent`) must apply the same\n *  triple match so a recycled-PID peer's entry is never silently\n *  overwritten/removed by this process.\n *\n *  `startTime` is the FNV-1a hash of `ps -o lstart` (see\n *  `liveness.processStartTime`). A `null` probe (process gone, or\n *  exotic platform) skips the start-time check — the same conservative\n *  policy `checkHolderLiveness` applies. */\nconst isOwnEntry = (\n\th: RosterHolder,\n\townPid: number,\n\townHost: string,\n\townStartTime: number | null,\n): boolean => {\n\tif (h.pid !== ownPid || h.hostname !== ownHost) return false;\n\t// Either side null → fall back to (pid, hostname). The roster's\n\t// own-entry test must symmetrically accept a null recorded stamp:\n\t// the writer's probe failed (exotic platform / transient `ps`\n\t// error) but the entry IS ours. Mismatching a probed `ownStartTime`\n\t// against a recorded `null` would orphan our own entry — peers\n\t// would then harvest it as \"dead\" on the next sweep.\n\tif (ownStartTime === null || h.startTime === null) return true;\n\treturn h.startTime === ownStartTime;\n};\n\nconst withStackLock = <A, E, R>(\n\tpaths: RosterPaths,\n\tbody: Effect.Effect<A, E, R>,\n): Effect.Effect<A, E | import('./stack-lock.ts').StackLockError, R> =>\n\tEffect.scoped(\n\t\tEffect.gen(function* () {\n\t\t\tyield* acquireStackLock(paths.stackLockFile);\n\t\t\treturn yield* body;\n\t\t}),\n\t);\n\n/**\n * Claim protocol — architecture § Claim protocol.\n *\n * Under the exclusive lock:\n *  1. Read the roster (or initialize empty if missing).\n *  2. Sweep stale holders (PID liveness + heartbeat age).\n *  3. Append this process's entry.\n *  4. Atomic write the result.\n *\n * Returns the swept document, our holder entry, and any evicted peers.\n */\nexport const claim = (\n\tpaths: RosterPaths,\n\tintent: 'normal' | 'snapshot' = 'normal',\n\tpolicy: RosterSweepPolicy = DEFAULT_SWEEP_POLICY,\n): Effect.Effect<ClaimResult, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst initial = yield* readRoster(paths.rosterFile).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_ROSTER)),\n\t\t\t);\n\t\t\tconst { swept, evicted } = yield* sweepStaleHolders(initial, policy);\n\t\t\tconst self: RosterHolder = { ...ownHolder(intent) };\n\t\t\tconst next: RosterDocument = {\n\t\t\t\tversion: 1,\n\t\t\t\tholders: [...swept.holders, self],\n\t\t\t};\n\t\t\tyield* atomicWriteRoster(paths.rosterFile, next);\n\t\t\treturn {\n\t\t\t\tself,\n\t\t\t\troster: next,\n\t\t\t\tevicted,\n\t\t\t\tsoleHolder: swept.holders.length === 0,\n\t\t\t};\n\t\t}),\n\t);\n\n/**\n * Heartbeat protocol — refresh this process's `heartbeatAt`. Under the\n * stack lock to keep mutation atomic. Architecture § Heartbeat\n * protocol.\n */\nexport const heartbeat = (\n\tpaths: RosterPaths,\n\townPid: number = selfPid(),\n): Effect.Effect<void, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst current = yield* readRoster(paths.rosterFile).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_ROSTER)),\n\t\t\t);\n\t\t\tconst now = Date.now();\n\t\t\tconst ownHost = nodeHostname();\n\t\t\tconst ownStartTime = processStartTime(ownPid);\n\t\t\tlet touched = false;\n\t\t\tconst next: RosterDocument = {\n\t\t\t\tversion: 1,\n\t\t\t\tholders: current.holders.map((h) => {\n\t\t\t\t\tif (isOwnEntry(h, ownPid, ownHost, ownStartTime)) {\n\t\t\t\t\t\ttouched = true;\n\t\t\t\t\t\treturn { ...h, heartbeatAt: now };\n\t\t\t\t\t}\n\t\t\t\t\treturn h;\n\t\t\t\t}),\n\t\t\t};\n\t\t\tif (touched) yield* atomicWriteRoster(paths.rosterFile, next);\n\t\t}),\n\t);\n\n/**\n * Release protocol — architecture § Release protocol.\n *\n * Removes this process's holder. Returns whether this was the\n * last-leaver (caller runs the stop finalizer if so).\n */\nexport const release = (\n\tpaths: RosterPaths,\n\townPid: number = selfPid(),\n): Effect.Effect<ReleaseResult, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst current = yield* readRoster(paths.rosterFile).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_ROSTER)),\n\t\t\t);\n\t\t\tconst ownHost = nodeHostname();\n\t\t\tconst ownStartTime = processStartTime(ownPid);\n\t\t\tconst remaining = current.holders.filter(\n\t\t\t\t(h) => !isOwnEntry(h, ownPid, ownHost, ownStartTime),\n\t\t\t);\n\t\t\tconst next: RosterDocument = { version: 1, holders: remaining };\n\t\t\tyield* atomicWriteRoster(paths.rosterFile, next);\n\t\t\treturn {\n\t\t\t\troster: next,\n\t\t\t\tlastLeaver: remaining.length === 0,\n\t\t\t};\n\t\t}),\n\t);\n\n/**\n * Set this process's `intent` (`normal` ↔ `snapshot`) under the\n * exclusive lock. Architecture § Concurrent snapshot step 2 / 5.\n */\nexport const setIntent = (\n\tpaths: RosterPaths,\n\tintent: 'normal' | 'snapshot',\n\townPid: number = selfPid(),\n): Effect.Effect<void, RosterError | import('./stack-lock.ts').StackLockError> =>\n\twithStackLock(\n\t\tpaths,\n\t\tEffect.gen(function* () {\n\t\t\tconst current = yield* readRoster(paths.rosterFile).pipe(\n\t\t\t\tEffect.catchTag('RosterCorruptError', () => Effect.succeed(EMPTY_ROSTER)),\n\t\t\t);\n\t\t\tconst ownHost = nodeHostname();\n\t\t\tconst ownStartTime = processStartTime(ownPid);\n\t\t\tconst next: RosterDocument = {\n\t\t\t\tversion: 1,\n\t\t\t\tholders: current.holders.map((h) =>\n\t\t\t\t\tisOwnEntry(h, ownPid, ownHost, ownStartTime) ? { ...h, intent } : h,\n\t\t\t\t),\n\t\t\t};\n\t\t\tyield* atomicWriteRoster(paths.rosterFile, next);\n\t\t}),\n\t);\n\n/** Background heartbeat fiber. Wakes every `intervalMillis` (default\n *  matches `DEFAULT_SWEEP_POLICY.heartbeatIntervalMillis`) and refreshes\n *  this process's `heartbeatAt`.\n *\n *  Returns an Effect that runs forever in its Scope — the supervisor\n *  forks it via `Effect.forkScoped` so it tears down with the stack. */\nexport const heartbeatFiber = (\n\tpaths: RosterPaths,\n\tintervalMillis: number = DEFAULT_SWEEP_POLICY.heartbeatIntervalMillis,\n): Effect.Effect<never> =>\n\tEffect.gen(function* () {\n\t\twhile (true) {\n\t\t\tyield* Effect.sleep(`${intervalMillis} millis`);\n\t\t\tyield* heartbeat(paths).pipe(\n\t\t\t\t// A heartbeat failure is non-fatal — the next peer's sweep\n\t\t\t\t// would otherwise evict us, but the architecture treats this\n\t\t\t\t// as \"the dev didn't get to flush a heartbeat in time;\n\t\t\t\t// recover by retrying next interval.\" Log via Effect's\n\t\t\t\t// logger; do not propagate.\n\t\t\t\tEffect.catch((err) =>\n\t\t\t\t\tEffect.logWarning('roster heartbeat failed').pipe(\n\t\t\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t\t\t[LogAttr.rosterHeartbeatIntervalMs]: intervalMillis,\n\t\t\t\t\t\t\t[LogAttr.errorCause]: String(err),\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t});\n"],"mappings":"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"}

package/dist/substrate/runtime/cross-process/self-pid.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"self-pid.mjs","names":[],"sources":["../../../../src/substrate/runtime/cross-process/self-pid.ts"],"sourcesContent":["// Own-process PID accessor.\n//\n// Centralizes `process.pid` reads so:\n//   1. The cross-process protocol modules (roster, snapshot-reservation,\n//      liveness, atomic-write tempfiles, port-broker owner ids) have a\n//      single named entry point instead of scattering the global read.\n//   2. Tests that want to simulate a peer can swap this module in a\n//      vitest mock without monkey-patching `process` globally.\n//\n// The implementation is intentionally trivial — `() => process.pid` —\n// and lives in its own module so call sites read with a meaningful name\n// rather than a raw global.\n\n/** This process's PID. Module-level indirection so cross-process\n *  protocol modules read through one named entry point. */\nexport const selfPid = (): number => process.pid;\n"],"mappings":";;;AAeA,MAAa,gBAAwB,QAAQ"}
+{"version":3,"file":"self-pid.mjs","names":[],"sources":["../../../../src/substrate/runtime/cross-process/self-pid.ts"],"sourcesContent":["// Own-process PID accessor.\n//\n// Centralizes `process.pid` reads so:\n//   1. The cross-process protocol modules (roster, stack-lock,\n//      liveness, atomic-write tempfiles, port-broker owner ids) have a\n//      single named entry point instead of scattering the global read.\n//   2. Tests that want to simulate a peer can swap this module in a\n//      vitest mock without monkey-patching `process` globally.\n//\n// The implementation is intentionally trivial — `() => process.pid` —\n// and lives in its own module so call sites read with a meaningful name\n// rather than a raw global.\n\n/** This process's PID. Module-level indirection so cross-process\n *  protocol modules read through one named entry point. */\nexport const selfPid = (): number => process.pid;\n"],"mappings":";;;AAeA,MAAa,gBAAwB,QAAQ"}

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

@@ -1,4 +1,3 @@
-import { SpanAttr } from "../observability/spans.mjs";
 import "../../cross-process.mjs";
 import { parseVersionedDocumentBodyOrNull } from "../../versioned-doc-sync.mjs";
 import { underLiveClock } from "./live-clock.mjs";
@@ -41,15 +40,16 @@ const DEFAULT_ACQUIRE_TIMEOUT_MILLIS = 5e3;
 const INITIAL_BACKOFF_MILLIS = 25;
 const MAX_BACKOFF_MILLIS = 200;
 /**
-* Sync attempt at O_EXCL-create. Returns whether we own the lock now.
+* Sync attempt at O_EXCL-create with the lock's JSON body. Returns
+* whether we own the file now; on EEXIST it probes the existing body
+* through `parseLockBody`.
 *
 * Effect-platform's FileSystem doesn't expose a sync `open` shape, but
 * the critical-section discipline says we need a non-blocking attempt
 * inside a retry loop. Falling through to Node sync APIs here is the
 * cleanest path; the rest of the substrate stays Effect-native.
 */
-const tryAcquireSync = (path) => {
-	const body = ownHolder();
+const tryAcquireSync = (path, body) => {
 	mkdirSync(dirname(path), { recursive: true });
 	try {
 		writeFileSync(path, JSON.stringify(body), { flag: "wx" });
@@ -74,25 +74,30 @@ const tryAcquireSync = (path) => {
 	}
 };
 /**
-* Acquire `stack.lock` as a scoped resource. The lock is released
-* when the surrounding Scope closes.
+* Acquire `stack.lock` as a scoped resource. The lock is released when
+* the surrounding Scope closes (the unlink finalizer is registered INSIDE
+* this scope, so every caller — roster claim/release/heartbeat, the
+* snapshot bounce, command-channel append — releases on scope close,
+* never bypassed). Yields a `void` resource — the caller MUST keep its
+* Scope tight; the architecture forbids holding the lock across long
+* operations.
 *
-* Retry loop: exponential backoff up to `timeoutMillis` (default 5s).
-* On every miss, probe the holder's liveness — if it's dead, reclaim
-* by unlinking and looping. The reclaim path is the architecture's
-* "stale lock" handling — same PID + start-time semantics as the
-* roster sweep, so a process that crashed under the lock never blocks
-* the next peer indefinitely.
-*
-* IMPORTANT: this primitive yields a `void` resource. The caller MUST
-* keep its Scope tight — the architecture forbids holding the lock
-* across long operations.
+* The O_EXCL retry loop: exponential backoff up to `timeoutMillis`
+* (default 5s). On every miss, probe the holder's liveness — dead holders
+* are reclaimed (unlink + loop); an unparseable body is reclaimed only
+* through the shared re-stat guard once it ages past
+* `DEFAULT_SWEEP_POLICY.staleAfterMillis`. Backoff resets on holder
+* change and on reclaim. The reclaim path is the architecture's "stale
+* lock" handling — same PID + start-time semantics as the roster sweep,
+* so a process that crashed under the lock never blocks the next peer
+* indefinitely.
 */
 const acquireStackLock = (path, timeoutMillis = DEFAULT_ACQUIRE_TIMEOUT_MILLIS) => Effect.gen(function* () {
-	yield* Effect.annotateCurrentSpan({
-		[SpanAttr.stackLockPath]: path,
-		[SpanAttr.stackLockTimeoutMillis]: timeoutMillis
-	});
+	const addUnlinkFinalizer = Effect.addFinalizer(() => Effect.sync(() => {
+		try {
+			unlinkSync(path);
+		} catch {}
+	}));
 	const startedAt = Date.now();
 	let backoff = INITIAL_BACKOFF_MILLIS;
 	let lastHolder = null;
@@ -105,22 +110,18 @@ const acquireStackLock = (path, timeoutMillis = DEFAULT_ACQUIRE_TIMEOUT_MILLIS)
 			holder: lastHolder
 		}));
 		const attempt = yield* Effect.try({
-			try: () => tryAcquireSync(path),
+			try: () => tryAcquireSync(path, ownHolder()),
 			catch: (cause) => new StackLockIoError({
 				path,
 				cause
 			})
 		});
 		if (attempt.ok) {
-			yield* Effect.addFinalizer(() => Effect.sync(() => {
-				try {
-					unlinkSync(path);
-				} catch {}
-			}));
+			yield* addUnlinkFinalizer;
 			return;
 		}
 		lastHolder = attempt.holder;
-		const currentHolderPid = lastHolder?.pid ?? null;
+		const currentHolderPid = lastHolder !== null ? lastHolder.pid : null;
 		if (currentHolderPid !== prevHolderPid) {
 			backoff = INITIAL_BACKOFF_MILLIS;
 			prevHolderPid = currentHolderPid;
@@ -156,7 +157,7 @@ const acquireStackLock = (path, timeoutMillis = DEFAULT_ACQUIRE_TIMEOUT_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 { DEFAULT_ACQUIRE_TIMEOUT_MILLIS, StackLockIoError, StackLockTimeoutError, acquireStackLock };
 

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 { 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"}
+{"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, the snapshot bounce).\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 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 spans the snapshot bounce.\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 { 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 with the lock's JSON body. Returns\n * whether we own the file now; on EEXIST it probes the existing body\n * through `parseLockBody`.\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\tbody: RosterHolder,\n): { readonly ok: true } | { readonly ok: false; readonly holder: RosterHolder | null } => {\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 when\n * the surrounding Scope closes (the unlink finalizer is registered INSIDE\n * this scope, so every caller — roster claim/release/heartbeat, the\n * snapshot bounce, command-channel append — releases on scope close,\n * never bypassed). Yields a `void` resource — the caller MUST keep its\n * Scope tight; the architecture forbids holding the lock across long\n * operations.\n *\n * The O_EXCL retry loop: exponential backoff up to `timeoutMillis`\n * (default 5s). On every miss, probe the holder's liveness — dead holders\n * are reclaimed (unlink + loop); an unparseable body is reclaimed only\n * through the shared re-stat guard once it ages past\n * `DEFAULT_SWEEP_POLICY.staleAfterMillis`. Backoff resets on holder\n * change and on reclaim. The reclaim path is the architecture's \"stale\n * lock\" handling — same PID + start-time semantics as the roster sweep,\n * so a process that crashed under the lock never blocks the next peer\n * indefinitely.\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\tconst addUnlinkFinalizer = 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. Crash-during-release is handled by\n\t\t\t\t\t// the next peer's stale-PID reclaim.\n\t\t\t\t}\n\t\t\t}),\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, ownHolder()),\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* addUnlinkFinalizer;\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 !== null ? 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});\n"],"mappings":"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"}

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/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"}
+{"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,QAAiD,CAAC,CAC/F,sCACD,CAAC,CAAC,CAAC;AAMH,IAAa,wBAAb,cAA2C,QAAQ,QAGjD,CAAC,CAAC,2CAA2C,CAAC,CAAC,CAAC;;;;AAKlD,MAAa,yBAAyB,UACrC,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,OAAO,cAAc,qBAAqB;CAClE,IAAI,OAAO,OAAO,QAAQ,GACzB,OAAO,SAAS,MAAM,SAAS,KAAK;AAEtC,CAAC"}

package/dist/substrate/runtime/errors.mjs

@@ -15,18 +15,6 @@ var AtomicWriteFailed = class extends Schema.TaggedErrorClass()("AtomicWriteFail
 	]),
 	cause: Schema.optional(Schema.Defect)
 }) {};
-/** 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",
-		"lock-contention"
-	]),
-	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([
@@ -77,6 +65,6 @@ var PortBrokerError = class extends Schema.TaggedErrorClass()("PortBrokerError",
 	cause: Schema.optional(Schema.Defect)
 }) {};
 //#endregion
-export { AtomicWriteFailed, CacheError, PortBrokerError, StateStoreError, StrategyNotFoundError };
+export { AtomicWriteFailed, CacheError, PortBrokerError, 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. 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"}
+{"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 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/** 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,iBAAoC,CAAC,CAClF,qBACA;CACC,MAAM,OAAO;CACb,OAAO,OAAO,SAAS;EAAC;EAAgB;EAAa;EAAS;EAAS;EAAU;CAAQ,CAAC;CAC1F,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;AAGH,IAAa,aAAb,cAAgC,OAAO,iBAA6B,CAAC,CAAC,cAAc;CACnF,QAAQ,OAAO,SAAS;EAAC;EAAa;EAAc;CAAiB,CAAC;CACtE,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CAAC,CAAC,CAAC,CAAC;;;;;;;AAQJ,IAAa,wBAAb,cAA2C,OAAO,iBAAwC,CAAC,CAC1F,yBACA;CACC,eAAe,OAAO;CACtB,gBAAgB,OAAO,MAAM,OAAO,MAAM;AAC3C,CACD,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;AAqBH,IAAa,kBAAb,cAAqC,OAAO,iBAAkC,CAAC,CAAC,mBAAmB;CAClG,QAAQ,OAAO,SAAS;EACvB;EACA;EACA;EACA;CACD,CAAC;CACD,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CAAC,CAAC,CAAC,CAAC"}

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

@@ -1 +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"}
+{"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) ? `${message} [cause: ${nested}]` : 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;CAC5E,IAAI,iBAAiB,OAAO,OAAO,QAAQ,OAAO,KAAK;CACvD,IAAI,OAAO,UAAU,UAAU,OAAO,MAAM,SAAS,IAAI,QAAQ;CACjE,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM;EAChD,MAAM,UAAW,MAAyC;EAC1D,IAAI,OAAO,YAAY,YAAY,QAAQ,SAAS,GACnD,OAAO,QAAQ,OAAO,KAAK;CAE7B;CACA,OAAO;AACR;AAEA,MAAM,WAAW,OAAgB,UAA0B;CAC1D,IAAI,OAAO,UAAU,UAAU,OAAO;CAQtC,MAAM,SAAS;CACf,MAAM,UACL,iBAAiB,QACd,MAAM,UACN,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAO,OAAO,YAAY,WACxE,OAAO,UACP,KAAA;CACL,IAAI,YAAY,KAAA,KAAa,QAAQ,SAAS,GAAG;EAChD,MAAM,SAAS,QAAQ,kBAAkB,mBAAmB,OAAO,OAAO,QAAQ,CAAC,IAAI;EACvF,OAAO,WAAW,QAAQ,CAAC,QAAQ,SAAS,MAAM,IAAI,GAAG,QAAQ,WAAW,OAAO,KAAK;CACzF;CACA,IAAI;EACH,OAAO,KAAK,UAAU,KAAK;CAC5B,QAAQ;EACP,OAAO,OAAO,KAAK;CACpB;AACD;AAEA,MAAa,sBAAsB,UAA2B,QAAQ,OAAO,CAAC"}