@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1,119 @@
+import { Data, Effect } from "effect";
+import { execFileSync } from "node:child_process";
+import { hostname } from "node:os";
+Data.TaggedError("StartTimeProbeError");
+/** Cheap "send signal 0" pid liveness. ESRCH → dead; EPERM → alive
+*  (foreign-user pid on shared dev hosts). Any other errno is
+*  conservatively treated as dead so we don't refuse cleanup on exotic
+*  platforms. */
+const isPidAlive = (pid) => {
+	if (!Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err.code === "EPERM";
+	}
+};
+/** Best-effort start-time stamp for `pid`. Returns `null` when the
+*  process is gone OR the platform can't produce a time. The stamp
+*  itself is opaque text — its only contract is bytewise equality with
+*  a previously-recorded sibling stamp.
+*
+*  Architecture § Cross-process safety protocol §3 — `ps -o lstart` on
+*  macOS/Linux, `tasklist` confirmation on Windows. */
+const processStartTime = (pid) => {
+	if (!Number.isFinite(pid) || pid <= 0) return null;
+	if (process.platform === "win32") try {
+		const out = execFileSync("tasklist", [
+			"/fi",
+			`PID eq ${pid}`,
+			"/fo",
+			"csv",
+			"/nh"
+		], {
+			encoding: "utf8",
+			timeout: 2e3,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		return out.trim().startsWith("\"") ? hashStartTimeStamp(out.trim()) : null;
+	} catch {
+		return null;
+	}
+	try {
+		const trimmed = execFileSync("ps", [
+			"-o",
+			"lstart=",
+			"-p",
+			String(pid)
+		], {
+			encoding: "utf8",
+			timeout: 2e3,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+		return trimmed.length > 0 ? hashStartTimeStamp(trimmed) : null;
+	} catch {
+		return null;
+	}
+};
+/** Stable hash of a start-time string. Reduces the textual `ps -o
+*  lstart=` output to a single number so the roster carries a fixed-
+*  width integer (the architecture's `startTime` field is `number`).
+*
+*  FNV-1a 32-bit; collisions are negligible at the (pid, host, second)
+*  granularity we ever compare. */
+const hashStartTimeStamp = (stamp) => {
+	let h = 2166136261;
+	for (let i = 0; i < stamp.length; i++) {
+		h ^= stamp.charCodeAt(i);
+		h = h * 16777619 >>> 0;
+	}
+	return h >>> 0;
+};
+/** Liveness probe for a roster holder. Used by the claim-protocol
+*  sweep AND the snapshot-reservation orphan check.
+*
+*  Discipline:
+*   - Foreign-host (`hostname` differs from our own) → ALWAYS alive
+*     (NFS-safe default; cross-host pid comparisons are meaningless).
+*   - Same-host: pid must be live AND start-time must match.
+*
+*  Returns `'alive' | 'dead'`. Never throws. Effect-wrapped so callers
+*  compose under spans. */
+const checkHolderLiveness = Effect.fn("cross-process.liveness.checkHolderLiveness")(function* (holder, ownHost = hostname()) {
+	if (holder.hostname !== ownHost) return "alive";
+	yield* Effect.annotateCurrentSpan({
+		"devstack.holder.pid": holder.pid,
+		"devstack.holder.host": holder.hostname
+	});
+	if (!isPidAlive(holder.pid)) return "dead";
+	const probedStart = processStartTime(holder.pid);
+	if (probedStart === null) return "alive";
+	return probedStart === holder.startTime ? "alive" : "dead";
+});
+/** Build a holder snapshot for THIS process. The intent defaults to
+*  `'normal'`; the snapshot-reservation flow flips it to `'snapshot'`
+*  under the stack lock and back when the reservation releases. */
+const ownHolder = (intent = "normal") => {
+	const pid = process.pid;
+	return {
+		pid,
+		startTime: processStartTime(pid) ?? 0,
+		hostname: hostname(),
+		claimedAt: Date.now(),
+		heartbeatAt: Date.now(),
+		intent
+	};
+};
+//#endregion
+export { checkHolderLiveness, isPidAlive, ownHolder, processStartTime };
+
+//# sourceMappingURL=liveness.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"liveness.mjs","names":["nodeHostname"],"sources":["../../../../src/substrate/runtime/cross-process/liveness.ts"],"sourcesContent":["// PID + start-time liveness check.\n//\n// Architecture § Cross-process safety protocol § Claim protocol step 3:\n// \"process exists AND its start-time (as read from `/proc/<pid>/stat` on\n// Linux, `ps -o lstart` on macOS, or equivalent) matches the recorded\n// `startTime`.\"\n//\n// Foreign-host entries are treated as alive (NFS-safe conservative\n// default). On the same host, two checks combine: `kill(pid, 0)`\n// determines pid-in-use; `ps -o lstart` confirms it's the SAME process\n// (defending against pid reuse on long-uptime machines).\n//\n// This module is the ONLY place in the substrate that calls into\n// `process.kill` and shells out for start times. Roster/snapshot\n// reservation/stack-lock all consult it through the typed predicates.\n\nimport { execFileSync } from 'node:child_process';\nimport { hostname as nodeHostname } from 'node:os';\n\nimport { Data, Effect } from 'effect';\n\nimport type { RosterHolder } from '../../cross-process.ts';\n\n/** Tagged failure when the start-time probe itself errored unexpectedly\n *  (timeout, missing utility, etc.). Distinguished from \"pid absent\",\n *  which is signaled by `processStartTime` returning `null`. */\nexport class StartTimeProbeError extends Data.TaggedError('StartTimeProbeError')<{\n\treadonly pid: number;\n\treadonly cause: unknown;\n}> {}\n\n/** Cheap \"send signal 0\" pid liveness. ESRCH → dead; EPERM → alive\n *  (foreign-user pid on shared dev hosts). Any other errno is\n *  conservatively treated as dead so we don't refuse cleanup on exotic\n *  platforms. */\nexport const isPidAlive = (pid: number): boolean => {\n\tif (!Number.isFinite(pid) || pid <= 0) return false;\n\ttry {\n\t\tprocess.kill(pid, 0);\n\t\treturn true;\n\t} catch (err) {\n\t\tconst code = (err as NodeJS.ErrnoException).code;\n\t\treturn code === 'EPERM';\n\t}\n};\n\n/** Best-effort start-time stamp for `pid`. Returns `null` when the\n *  process is gone OR the platform can't produce a time. The stamp\n *  itself is opaque text — its only contract is bytewise equality with\n *  a previously-recorded sibling stamp.\n *\n *  Architecture § Cross-process safety protocol §3 — `ps -o lstart` on\n *  macOS/Linux, `tasklist` confirmation on Windows. */\nexport const processStartTime = (pid: number): number | null => {\n\tif (!Number.isFinite(pid) || pid <= 0) return null;\n\tif (process.platform === 'win32') {\n\t\ttry {\n\t\t\tconst out = execFileSync('tasklist', ['/fi', `PID eq ${pid}`, '/fo', 'csv', '/nh'], {\n\t\t\t\tencoding: 'utf8',\n\t\t\t\ttimeout: 2000,\n\t\t\t\tstdio: ['ignore', 'pipe', 'ignore'],\n\t\t\t});\n\t\t\t// Windows path: just hash the line. Windows PID reuse on uptime\n\t\t\t// is a known v1 trade-off; the architecture says the protocol\n\t\t\t// stays POSIX-first.\n\t\t\treturn out.trim().startsWith('\"') ? hashStartTimeStamp(out.trim()) : null;\n\t\t} catch {\n\t\t\treturn null;\n\t\t}\n\t}\n\ttry {\n\t\tconst out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {\n\t\t\tencoding: 'utf8',\n\t\t\ttimeout: 2000,\n\t\t\tstdio: ['ignore', 'pipe', 'ignore'],\n\t\t});\n\t\tconst trimmed = out.trim();\n\t\treturn trimmed.length > 0 ? hashStartTimeStamp(trimmed) : null;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n/** Stable hash of a start-time string. Reduces the textual `ps -o\n *  lstart=` output to a single number so the roster carries a fixed-\n *  width integer (the architecture's `startTime` field is `number`).\n *\n *  FNV-1a 32-bit; collisions are negligible at the (pid, host, second)\n *  granularity we ever compare. */\nconst hashStartTimeStamp = (stamp: string): number => {\n\tlet h = 2166136261;\n\tfor (let i = 0; i < stamp.length; i++) {\n\t\th ^= stamp.charCodeAt(i);\n\t\th = (h * 16777619) >>> 0;\n\t}\n\t// Stay inside Number.MAX_SAFE_INTEGER's positive 32-bit range so the\n\t// number round-trips through JSON without precision loss.\n\treturn h >>> 0;\n};\n\n/** Liveness probe for a roster holder. Used by the claim-protocol\n *  sweep AND the snapshot-reservation orphan check.\n *\n *  Discipline:\n *   - Foreign-host (`hostname` differs from our own) → ALWAYS alive\n *     (NFS-safe default; cross-host pid comparisons are meaningless).\n *   - Same-host: pid must be live AND start-time must match.\n *\n *  Returns `'alive' | 'dead'`. Never throws. Effect-wrapped so callers\n *  compose under spans. */\nexport const checkHolderLiveness = Effect.fn('cross-process.liveness.checkHolderLiveness')(\n\tfunction* (holder: RosterHolder, ownHost: string = nodeHostname()) {\n\t\t// Foreign-host: NFS-safe — we can't verify, assume alive.\n\t\tif (holder.hostname !== ownHost) {\n\t\t\treturn 'alive' as const;\n\t\t}\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.holder.pid': holder.pid,\n\t\t\t'devstack.holder.host': holder.hostname,\n\t\t});\n\t\tif (!isPidAlive(holder.pid)) return 'dead' as const;\n\t\tconst probedStart = processStartTime(holder.pid);\n\t\t// pid alive but no stamp probable → conservative: ALIVE\n\t\t// (we have nothing to dispute the recorded startTime with).\n\t\tif (probedStart === null) return 'alive' as const;\n\t\treturn probedStart === holder.startTime ? ('alive' as const) : ('dead' as const);\n\t},\n);\n\n/** Build a holder snapshot for THIS process. The intent defaults to\n *  `'normal'`; the snapshot-reservation flow flips it to `'snapshot'`\n *  under the stack lock and back when the reservation releases. */\nexport const ownHolder = (intent: 'normal' | 'snapshot' = 'normal'): RosterHolder => {\n\tconst pid = process.pid;\n\tconst startTime = processStartTime(pid) ?? 0;\n\treturn {\n\t\tpid,\n\t\tstartTime,\n\t\thostname: nodeHostname(),\n\t\tclaimedAt: Date.now(),\n\t\theartbeatAt: Date.now(),\n\t\tintent,\n\t};\n};\n"],"mappings":";;;AA0ByC,KAAK,YAAY,sBAAsB;;;;;AAShF,MAAa,cAAc,QAAyB;AACnD,KAAI,CAAC,OAAO,SAAS,IAAI,IAAI,OAAO,EAAG,QAAO;AAC9C,KAAI;AACH,UAAQ,KAAK,KAAK,EAAE;AACpB,SAAO;UACC,KAAK;AAEb,SADc,IAA8B,SAC5B;;;;;;;;;;AAWlB,MAAa,oBAAoB,QAA+B;AAC/D,KAAI,CAAC,OAAO,SAAS,IAAI,IAAI,OAAO,EAAG,QAAO;AAC9C,KAAI,QAAQ,aAAa,QACxB,KAAI;EACH,MAAM,MAAM,aAAa,YAAY;GAAC;GAAO,UAAU;GAAO;GAAO;GAAO;GAAM,EAAE;GACnF,UAAU;GACV,SAAS;GACT,OAAO;IAAC;IAAU;IAAQ;IAAS;GACnC,CAAC;AAIF,SAAO,IAAI,MAAM,CAAC,WAAW,KAAI,GAAG,mBAAmB,IAAI,MAAM,CAAC,GAAG;SAC9D;AACP,SAAO;;AAGT,KAAI;EAMH,MAAM,UALM,aAAa,MAAM;GAAC;GAAM;GAAW;GAAM,OAAO,IAAI;GAAC,EAAE;GACpE,UAAU;GACV,SAAS;GACT,OAAO;IAAC;IAAU;IAAQ;IAAS;GACnC,CACkB,CAAC,MAAM;AAC1B,SAAO,QAAQ,SAAS,IAAI,mBAAmB,QAAQ,GAAG;SACnD;AACP,SAAO;;;;;;;;;AAUT,MAAM,sBAAsB,UAA0B;CACrD,IAAI,IAAI;AACR,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACtC,OAAK,MAAM,WAAW,EAAE;AACxB,MAAK,IAAI,aAAc;;AAIxB,QAAO,MAAM;;;;;;;;;;;;AAad,MAAa,sBAAsB,OAAO,GAAG,6CAA6C,CACzF,WAAW,QAAsB,UAAkBA,UAAc,EAAE;AAElE,KAAI,OAAO,aAAa,QACvB,QAAO;AAER,QAAO,OAAO,oBAAoB;EACjC,uBAAuB,OAAO;EAC9B,wBAAwB,OAAO;EAC/B,CAAC;AACF,KAAI,CAAC,WAAW,OAAO,IAAI,CAAE,QAAO;CACpC,MAAM,cAAc,iBAAiB,OAAO,IAAI;AAGhD,KAAI,gBAAgB,KAAM,QAAO;AACjC,QAAO,gBAAgB,OAAO,YAAa,UAAqB;EAEjE;;;;AAKD,MAAa,aAAa,SAAgC,aAA2B;CACpF,MAAM,MAAM,QAAQ;AAEpB,QAAO;EACN;EACA,WAHiB,iBAAiB,IAAI,IAAI;EAI1C,UAAUA,UAAc;EACxB,WAAW,KAAK,KAAK;EACrB,aAAa,KAAK,KAAK;EACvB;EACA"}

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

@@ -0,0 +1,275 @@
+import { DEFAULT_SWEEP_POLICY, RosterDocumentSchema } from "../../cross-process.mjs";
+import { checkHolderLiveness, isPidAlive, ownHolder, processStartTime } from "./liveness.mjs";
+import { decodeJsonText } from "../runtime-decode.mjs";
+import { atomicWriteJsonSync } from "../atomic-write.mjs";
+import { SpanAttr } from "../observability/spans.mjs";
+import { acquireStackLock } from "./stack-lock.mjs";
+import { Data, Effect, Schema } from "effect";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { hostname } from "node:os";
+//#region src/substrate/runtime/cross-process/roster.ts
+var RosterCorruptError = class extends Data.TaggedError("RosterCorruptError") {};
+var RosterIoError = class extends Data.TaggedError("RosterIoError") {};
+const EMPTY_ROSTER = {
+	version: 1,
+	holders: []
+};
+/** Read the roster from disk. Returns the empty document if absent.
+*  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) => Effect.gen(function* () {
+	if (!existsSync(path)) return EMPTY_ROSTER;
+	const raw = yield* Effect.try({
+		try: () => readFileSync(path, "utf8"),
+		catch: (cause) => new RosterIoError({
+			path,
+			cause
+		})
+	});
+	return yield* decodeJsonText(RosterDocumentSchema, raw, {
+		source: path,
+		mkError: (issue) => new RosterCorruptError({
+			path,
+			raw,
+			cause: issue.cause ?? issue
+		})
+	});
+}).pipe(Effect.withSpan("cross-process.roster.read"));
+/** 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. */
+const atomicWriteRoster = (path, doc) => Effect.try({
+	try: () => atomicWriteJsonSync(path, doc),
+	catch: (cause) => new RosterIoError({
+		path,
+		cause
+	})
+});
+/** Walk the roster's holders and drop those that fail the liveness
+*  test AND whose heartbeats are older than `staleAfterMillis`.
+*
+*  Architecture § Claim protocol step 3 — "Holders whose
+*  `heartbeatAt` is older than 3× the heartbeat interval AND who fail
+*  the PID liveness check are evicted."
+*
+*  A live holder with a stale heartbeat is NOT evicted — heartbeat
+*  staleness alone is allowed (slow peer). The conjunction matters. */
+const sweepStaleHolders = Effect.fn("cross-process.roster.sweep")(function* (doc, policy = DEFAULT_SWEEP_POLICY, now = Date.now()) {
+	const survivors = [];
+	const evicted = [];
+	for (const holder of doc.holders) {
+		if (!(now - holder.heartbeatAt > policy.staleAfterMillis)) {
+			survivors.push(holder);
+			continue;
+		}
+		if ((yield* checkHolderLiveness(holder).pipe(Effect.catch(() => Effect.succeed("alive")))) === "dead") evicted.push(holder);
+		else survivors.push(holder);
+	}
+	return {
+		swept: {
+			version: doc.version,
+			holders: survivors
+		},
+		evicted
+	};
+});
+const withStackLock = (paths, body) => Effect.scoped(Effect.gen(function* () {
+	yield* acquireStackLock(paths.stackLockFile);
+	return yield* body;
+}));
+/**
+* Claim protocol — architecture § Claim protocol.
+*
+* Under the exclusive lock:
+*  1. Read the roster (or initialize empty if missing).
+*  2. Sweep stale holders (PID liveness + heartbeat age).
+*  3. Append this process's entry.
+*  4. Atomic write the result.
+*
+* 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 = {
+		version: 1,
+		holders: [...swept.holders, self]
+	};
+	yield* atomicWriteRoster(paths.rosterFile, next);
+	return {
+		self,
+		roster: next,
+		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
+* protocol.
+*/
+const heartbeat = (paths, ownPid = process.pid) => withStackLock(paths, Effect.gen(function* () {
+	const current = yield* readRoster(paths.rosterFile).pipe(Effect.catchTag("RosterCorruptError", () => Effect.succeed(EMPTY_ROSTER)));
+	const now = Date.now();
+	const ownHost = hostname();
+	let touched = false;
+	const next = {
+		version: 1,
+		holders: current.holders.map((h) => {
+			if (h.pid === ownPid && h.hostname === ownHost) {
+				touched = true;
+				return {
+					...h,
+					heartbeatAt: now
+				};
+			}
+			return h;
+		})
+	};
+	if (touched) yield* atomicWriteRoster(paths.rosterFile, next);
+})).pipe(Effect.withSpan("cross-process.roster.heartbeat"));
+/**
+* Release protocol — architecture § Release protocol.
+*
+* Removes this process's holder. Returns whether this was the
+* last-leaver (caller runs the stop finalizer if so).
+*/
+const release = (paths, ownPid = process.pid) => withStackLock(paths, Effect.gen(function* () {
+	const current = yield* readRoster(paths.rosterFile).pipe(Effect.catchTag("RosterCorruptError", () => Effect.succeed(EMPTY_ROSTER)));
+	const ownHost = hostname();
+	const remaining = current.holders.filter((h) => !(h.pid === ownPid && h.hostname === ownHost));
+	const next = {
+		version: 1,
+		holders: remaining
+	};
+	yield* atomicWriteRoster(paths.rosterFile, next);
+	return {
+		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`.
+*
+*  Returns an Effect that runs forever in its Scope — the supervisor
+*  forks it via `Effect.forkScoped` so it tears down with the stack. */
+const heartbeatFiber = (paths, intervalMillis = DEFAULT_SWEEP_POLICY.heartbeatIntervalMillis) => Effect.gen(function* () {
+	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)
+		}))));
+	}
+}).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 = Schema.Struct({
+	version: Schema.Literal(1),
+	claims: Schema.Array(ContainerClaimSchema)
+});
+const EMPTY_CLAIMS = {
+	version: 1,
+	claims: []
+};
+const claimsPath = (rosterFile) => `${dirname(rosterFile)}/container-claims.json`;
+const isContainerClaimLive = (claim, ownHost = hostname()) => {
+	if (claim.hostname !== ownHost) return true;
+	if (!isPidAlive(claim.pid)) return false;
+	if (claim.startTime === void 0) return true;
+	const probedStart = processStartTime(claim.pid);
+	if (probedStart === null) return true;
+	return probedStart === claim.startTime;
+};
+const liveContainerClaims = (doc) => ({
+	version: 1,
+	claims: doc.claims.filter((claim) => isContainerClaimLive(claim))
+});
+const writeClaims = (path, doc) => Effect.try({
+	try: () => atomicWriteJsonSync(path, doc),
+	catch: (cause) => new RosterIoError({
+		path,
+		cause
+	})
+});
+/** Read the container-claim ledger. */
+const readClaims = (paths) => Effect.gen(function* () {
+	const path = claimsPath(paths.rosterFile);
+	if (!existsSync(path)) return EMPTY_CLAIMS;
+	const raw = yield* Effect.try({
+		try: () => readFileSync(path, "utf8"),
+		catch: (cause) => new RosterIoError({
+			path,
+			cause
+		})
+	});
+	return yield* decodeJsonText(ContainerClaimDocumentSchema, raw, {
+		source: path,
+		mkError: (issue) => new RosterCorruptError({
+			path,
+			raw,
+			cause: issue.cause ?? issue
+		})
+	});
+}).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 = claimsPath(paths.rosterFile);
+	const current = yield* readClaims(paths).pipe(Effect.catchTag("RosterCorruptError", () => Effect.succeed(EMPTY_CLAIMS)));
+	const live = liveContainerClaims(current);
+	const ownPid = process.pid;
+	const ownStartTime = processStartTime(ownPid) ?? void 0;
+	const ownHost = hostname();
+	if (live.claims.some((c) => c.containerKey === containerKey && c.pid === ownPid && c.hostname === ownHost)) {
+		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 = claimsPath(paths.rosterFile);
+	const live = liveContainerClaims(yield* readClaims(paths).pipe(Effect.catchTag("RosterCorruptError", () => Effect.succeed(EMPTY_CLAIMS))));
+	const ownPid = process.pid;
+	const ownHost = hostname();
+	const remaining = live.claims.filter((c) => !(c.containerKey === containerKey && c.pid === ownPid && c.hostname === ownHost));
+	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 { addClaim, claim, heartbeatFiber, readClaims, readRoster, release, removeClaim };
+
+//# sourceMappingURL=roster.mjs.map

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

@@ -0,0 +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 { existsSync, readFileSync } from 'node:fs';\nimport { hostname as nodeHostname } from 'node:os';\nimport { dirname } from 'node:path';\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 { atomicWriteJsonSync } from '../atomic-write.ts';\nimport { SpanAttr } from '../observability/spans.ts';\nimport { decodeJsonText } from '../runtime-decode.ts';\nimport { acquireStackLock } from './stack-lock.ts';\nimport { checkHolderLiveness, isPidAlive, ownHolder, processStartTime } 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\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\tEffect.gen(function* () {\n\t\tif (!existsSync(path)) return EMPTY_ROSTER;\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => new RosterIoError({ path, cause }),\n\t\t});\n\t\tconst decoded = yield* decodeJsonText(RosterDocumentSchema, raw, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) => new RosterCorruptError({ path, raw, cause: issue.cause ?? issue }),\n\t\t});\n\t\treturn decoded;\n\t}).pipe(Effect.withSpan('cross-process.roster.read'));\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\tEffect.try({\n\t\ttry: () => atomicWriteJsonSync(path, doc),\n\t\tcatch: (cause) => new RosterIoError({ path, cause }),\n\t});\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\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* checkHolderLiveness(holder).pipe(\n\t\t\tEffect.catch(() => Effect.succeed('alive' as const)),\n\t\t);\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});\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\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 = process.pid,\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\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 (h.pid === ownPid && h.hostname === ownHost) {\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 = process.pid,\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 remaining = current.holders.filter(\n\t\t\t\t(h) => !(h.pid === ownPid && h.hostname === ownHost),\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 = process.pid,\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 next: RosterDocument = {\n\t\t\t\tversion: 1,\n\t\t\t\tholders: current.holders.map((h) =>\n\t\t\t\t\th.pid === ownPid && h.hostname === ownHost ? { ...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 = Schema.Struct({\n\tversion: Schema.Literal(1),\n\tclaims: Schema.Array(ContainerClaimSchema),\n});\n\nconst EMPTY_CLAIMS: ContainerClaimDocument = { version: 1, claims: [] };\n\nconst claimsPath = (rosterFile: string): string => `${dirname(rosterFile)}/container-claims.json`;\n\nconst isContainerClaimLive = (claim: ContainerClaim, ownHost: string = nodeHostname()): 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 = processStartTime(claim.pid);\n\tif (probedStart === null) return true;\n\treturn probedStart === claim.startTime;\n};\n\nconst liveContainerClaims = (doc: ContainerClaimDocument): ContainerClaimDocument => ({\n\tversion: 1,\n\tclaims: doc.claims.filter((claim) => isContainerClaimLive(claim)),\n});\n\nconst writeClaims = (\n\tpath: string,\n\tdoc: ContainerClaimDocument,\n): Effect.Effect<void, RosterIoError> =>\n\tEffect.try({\n\t\ttry: () => atomicWriteJsonSync(path, doc),\n\t\tcatch: (cause) => new RosterIoError({ path, cause }),\n\t});\n\n/** Read the container-claim ledger. */\nexport const readClaims = (\n\tpaths: RosterPaths,\n): Effect.Effect<ContainerClaimDocument, RosterError> =>\n\tEffect.gen(function* () {\n\t\tconst path = claimsPath(paths.rosterFile);\n\t\tif (!existsSync(path)) return EMPTY_CLAIMS;\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => new RosterIoError({ path, cause }),\n\t\t});\n\t\treturn yield* decodeJsonText(ContainerClaimDocumentSchema, raw, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) => new RosterCorruptError({ path, raw, cause: issue.cause ?? issue }),\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 = claimsPath(paths.rosterFile);\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 = 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 = claimsPath(paths.rosterFile);\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 live = liveContainerClaims(current);\n\t\t\tconst ownPid = process.pid;\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(\n\t\t\t\t\t(c) => c.containerKey === containerKey && c.pid === ownPid && c.hostname === ownHost,\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 = claimsPath(paths.rosterFile);\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 live = liveContainerClaims(current);\n\t\t\tconst ownPid = process.pid;\n\t\t\tconst ownHost = nodeHostname();\n\t\t\tconst remaining = live.claims.filter(\n\t\t\t\t(c) => !(c.containerKey === containerKey && c.pid === ownPid && c.hostname === ownHost),\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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"}

package/dist/substrate/runtime/cross-process/snapshot-reservation.d.mts

@@ -0,0 +1 @@
+import { Effect, Scope } from "effect";

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

@@ -0,0 +1,117 @@
+import { SnapshotReservationSchema } from "../../cross-process.mjs";
+import { checkHolderLiveness } from "./liveness.mjs";
+import { decodeJsonTextSync } from "../runtime-decode.mjs";
+import { Data, Effect } from "effect";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+//#region src/substrate/runtime/cross-process/snapshot-reservation.ts
+var SnapshotReservationHeldError = class extends Data.TaggedError("SnapshotReservationHeldError") {};
+var SnapshotReservationIoError = class extends Data.TaggedError("SnapshotReservationIoError") {};
+const parseReservation = (raw) => {
+	try {
+		return decodeJsonTextSync(SnapshotReservationSchema, raw, {
+			source: "snapshot.reservation",
+			mkError: (issue) => issue
+		});
+	} catch {
+		return null;
+	}
+};
+const ownReservation = (startTime) => ({
+	creatorPid: process.pid,
+	creatorStartTime: startTime,
+	createdAt: Date.now()
+});
+/**
+* Sweep an orphaned reservation. If the file exists AND its creator is
+* dead, unlink it. Returns whether a sweep happened so callers can
+* observe / report.
+*
+* Architecture § Concurrent snapshot last paragraph:
+*   "If the snapshotting process crashes mid-snapshot, the reservation
+*    file persists. The next process's claim-protocol sweep detects an
+*    orphan reservation (the holder whose pid matches the
+*    reservation's creator entry is dead) and unlinks it."
+*/
+const sweepOrphan = (path) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({ "devstack.snapshot-reservation.path": path });
+	if (!existsSync(path)) return { swept: false };
+	const reservation = parseReservation(yield* Effect.try({
+		try: () => readFileSync(path, "utf8"),
+		catch: (cause) => new SnapshotReservationIoError({
+			path,
+			cause
+		})
+	}));
+	if (reservation === null) {
+		yield* Effect.try({
+			try: () => unlinkSync(path),
+			catch: (cause) => new SnapshotReservationIoError({
+				path,
+				cause
+			})
+		});
+		return { swept: true };
+	}
+	if ((yield* checkHolderLiveness({
+		pid: reservation.creatorPid,
+		startTime: reservation.creatorStartTime,
+		hostname: "",
+		claimedAt: reservation.createdAt,
+		heartbeatAt: reservation.createdAt,
+		intent: "snapshot"
+	}, "").pipe(Effect.catch(() => Effect.succeed("alive")))) === "alive") return { swept: false };
+	yield* Effect.try({
+		try: () => unlinkSync(path),
+		catch: (cause) => new SnapshotReservationIoError({
+			path,
+			cause
+		})
+	});
+	return { swept: true };
+}).pipe(Effect.withSpan("cross-process.snapshot-reservation.sweepOrphan"));
+/**
+* Acquire the snapshot reservation as a scoped resource. The
+* reservation is unlinked when the surrounding Scope closes.
+*
+* Architecture § Concurrent snapshot step 1: O_EXCL create, no retry.
+* Callers that fail with `SnapshotReservationHeldError` propagate the
+* structured "snapshot in progress" error to the user — the typical
+* `Effect.catchTag` shape.
+*
+* `startTime` is the same value the roster carries for THIS process so
+* the orphan sweep's pid-startTime check resolves identically.
+*/
+const acquireReservation = (path, startTime) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({ "devstack.snapshot-reservation.path": path });
+	yield* sweepOrphan(path);
+	const body = ownReservation(startTime);
+	yield* Effect.try({
+		try: () => writeFileSync(path, JSON.stringify(body), { flag: "wx" }),
+		catch: (cause) => {
+			if (cause.code === "EEXIST") {
+				let holder = null;
+				try {
+					holder = parseReservation(readFileSync(path, "utf8"));
+				} catch {}
+				return new SnapshotReservationHeldError({
+					path,
+					holder
+				});
+			}
+			return new SnapshotReservationIoError({
+				path,
+				cause
+			});
+		}
+	});
+	yield* Effect.addFinalizer(() => Effect.sync(() => {
+		try {
+			unlinkSync(path);
+		} catch {}
+	}));
+	return body;
+}).pipe(Effect.withSpan("cross-process.snapshot-reservation.acquire"));
+//#endregion
+export { acquireReservation };
+
+//# sourceMappingURL=snapshot-reservation.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-reservation.mjs","names":[],"sources":["../../../../src/substrate/runtime/cross-process/snapshot-reservation.ts"],"sourcesContent":["// `snapshot.reservation` — presence-or-absence semaphore.\n//\n// Architecture § Cross-process safety protocol § Concurrent snapshot:\n//   \"Snapshot requires exclusive control of the stack's container set\n//   (pause-around-commit means peer processes' ready-probes would fail\n//   if uncoordinated). The snapshotting process acquires\n//   `snapshot.reservation` via O_EXCL create. If creation fails (peer\n//   holds it), the snapshot refuses with a structured 'snapshot in\n//   progress by peer pid X' error.\"\n//\n// Discipline:\n//   - Acquire is atomic O_EXCL create with a JSON body carrying\n//     `{ creatorPid, creatorStartTime, createdAt }`.\n//   - Release is `unlink`.\n//   - Orphan sweep: on the next claim, if the body's creator pid is\n//     dead (PID + start-time check), the reservation is unlinked. This\n//     mirrors the roster's stale-PID reclaim.\n//   - Acquire DOES NOT retry — snapshot is a one-shot intent; the\n//     caller surfaces the structured error to the user immediately.\n\nimport { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';\n\nimport { Data, Effect, Scope } from 'effect';\n\nimport { type SnapshotReservation, SnapshotReservationSchema } from '../../cross-process.ts';\nimport { decodeJsonTextSync } from '../runtime-decode.ts';\nimport { checkHolderLiveness } from './liveness.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\nexport class SnapshotReservationHeldError extends Data.TaggedError('SnapshotReservationHeldError')<{\n\treadonly path: string;\n\treadonly holder: SnapshotReservation | null;\n}> {}\n\nexport class SnapshotReservationIoError extends Data.TaggedError('SnapshotReservationIoError')<{\n\treadonly path: string;\n\treadonly cause: unknown;\n}> {}\n\nexport type SnapshotReservationError = SnapshotReservationHeldError | SnapshotReservationIoError;\n\n// -----------------------------------------------------------------------------\n// Codec\n// -----------------------------------------------------------------------------\n\nconst parseReservation = (raw: string): SnapshotReservation | null => {\n\ttry {\n\t\treturn decodeJsonTextSync(SnapshotReservationSchema, raw, {\n\t\t\tsource: 'snapshot.reservation',\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Acquire / release\n// -----------------------------------------------------------------------------\n\nconst ownReservation = (startTime: number): SnapshotReservation => ({\n\tcreatorPid: process.pid,\n\tcreatorStartTime: startTime,\n\tcreatedAt: Date.now(),\n});\n\n/**\n * Sweep an orphaned reservation. If the file exists AND its creator is\n * dead, unlink it. Returns whether a sweep happened so callers can\n * observe / report.\n *\n * Architecture § Concurrent snapshot last paragraph:\n *   \"If the snapshotting process crashes mid-snapshot, the reservation\n *    file persists. The next process's claim-protocol sweep detects an\n *    orphan reservation (the holder whose pid matches the\n *    reservation's creator entry is dead) and unlinks it.\"\n */\nexport const sweepOrphan = (\n\tpath: string,\n): Effect.Effect<{ readonly swept: boolean }, SnapshotReservationError> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({ 'devstack.snapshot-reservation.path': path });\n\t\tif (!existsSync(path)) return { swept: false };\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t});\n\t\tconst reservation = parseReservation(raw);\n\t\tif (reservation === null) {\n\t\t\t// Malformed body — the creator wrote a half-written file then\n\t\t\t// died. Treat as orphan: unlink it so future acquires don't\n\t\t\t// fail forever.\n\t\t\tyield* Effect.try({\n\t\t\t\ttry: () => unlinkSync(path),\n\t\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t\t});\n\t\t\treturn { swept: true };\n\t\t}\n\t\t// PID-liveness check: synthesize a roster-shaped holder so the\n\t\t// shared liveness predicate applies.\n\t\tconst liveness = yield* checkHolderLiveness(\n\t\t\t{\n\t\t\t\tpid: reservation.creatorPid,\n\t\t\t\tstartTime: reservation.creatorStartTime,\n\t\t\t\thostname: '',\n\t\t\t\tclaimedAt: reservation.createdAt,\n\t\t\t\theartbeatAt: reservation.createdAt,\n\t\t\t\tintent: 'snapshot',\n\t\t\t},\n\t\t\t'',\n\t\t).pipe(Effect.catch(() => Effect.succeed('alive' as const)));\n\t\tif (liveness === 'alive') return { swept: false };\n\t\tyield* Effect.try({\n\t\t\ttry: () => unlinkSync(path),\n\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t});\n\t\treturn { swept: true };\n\t}).pipe(Effect.withSpan('cross-process.snapshot-reservation.sweepOrphan'));\n\n/**\n * Acquire the snapshot reservation as a scoped resource. The\n * reservation is unlinked when the surrounding Scope closes.\n *\n * Architecture § Concurrent snapshot step 1: O_EXCL create, no retry.\n * Callers that fail with `SnapshotReservationHeldError` propagate the\n * structured \"snapshot in progress\" error to the user — the typical\n * `Effect.catchTag` shape.\n *\n * `startTime` is the same value the roster carries for THIS process so\n * the orphan sweep's pid-startTime check resolves identically.\n */\nexport const acquireReservation = (\n\tpath: string,\n\tstartTime: number,\n): Effect.Effect<SnapshotReservation, SnapshotReservationError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({ 'devstack.snapshot-reservation.path': path });\n\t\t// One-shot orphan sweep before our O_EXCL attempt. The sweep is\n\t\t// idempotent: if a peer just wrote the reservation while we ran\n\t\t// the sweep, the O_EXCL create fails below and we surface the\n\t\t// structured \"held\" error.\n\t\tyield* sweepOrphan(path);\n\t\tconst body = ownReservation(startTime);\n\t\tyield* Effect.try({\n\t\t\ttry: () => writeFileSync(path, JSON.stringify(body), { flag: 'wx' }),\n\t\t\tcatch: (cause) => {\n\t\t\t\tconst code = (cause as NodeJS.ErrnoException).code;\n\t\t\t\tif (code === 'EEXIST') {\n\t\t\t\t\tlet holder: SnapshotReservation | null = null;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tholder = parseReservation(readFileSync(path, 'utf8'));\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Body unreadable; leave holder as null.\n\t\t\t\t\t}\n\t\t\t\t\treturn new SnapshotReservationHeldError({ path, holder });\n\t\t\t\t}\n\t\t\t\treturn new SnapshotReservationIoError({ path, cause });\n\t\t\t},\n\t\t});\n\t\t// Finalizer: best-effort unlink on scope close. Architecture §\n\t\t// Concurrent snapshot step 5: \"It unlinks `snapshot.reservation`.\"\n\t\tyield* Effect.addFinalizer(() =>\n\t\t\tEffect.sync(() => {\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(path);\n\t\t\t\t} catch {\n\t\t\t\t\t// Already gone — ok. A peer's sweep may have unlinked our\n\t\t\t\t\t// stale reservation if we somehow lost the process between\n\t\t\t\t\t// acquire and the finalizer fire.\n\t\t\t\t}\n\t\t\t}),\n\t\t);\n\t\treturn body;\n\t}).pipe(Effect.withSpan('cross-process.snapshot-reservation.acquire'));\n\n/** Inspect (without acquiring) the current reservation. Returns the\n *  parsed body or `null` if absent / malformed. Used by the supervisor\n *  to decide whether to apply the \"snapshot-in-progress\" tolerance\n *  window to ready probes. Architecture § Concurrent snapshot step 3. */\nexport const peekReservation = (\n\tpath: string,\n): Effect.Effect<SnapshotReservation | null, SnapshotReservationError> =>\n\tEffect.gen(function* () {\n\t\tif (!existsSync(path)) return null;\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => new SnapshotReservationIoError({ path, cause }),\n\t\t});\n\t\treturn parseReservation(raw);\n\t}).pipe(Effect.withSpan('cross-process.snapshot-reservation.peek'));\n"],"mappings":";;;;;;AAgCA,IAAa,+BAAb,cAAkD,KAAK,YAAY,+BAA+B,CAG/F;AAEH,IAAa,6BAAb,cAAgD,KAAK,YAAY,6BAA6B,CAG3F;AAQH,MAAM,oBAAoB,QAA4C;AACrE,KAAI;AACH,SAAO,mBAAmB,2BAA2B,KAAK;GACzD,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC;SACK;AACP,SAAO;;;AAQT,MAAM,kBAAkB,eAA4C;CACnE,YAAY,QAAQ;CACpB,kBAAkB;CAClB,WAAW,KAAK,KAAK;CACrB;;;;;;;;;;;;AAaD,MAAa,eACZ,SAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB,EAAE,sCAAsC,MAAM,CAAC;AACjF,KAAI,CAAC,WAAW,KAAK,CAAE,QAAO,EAAE,OAAO,OAAO;CAK9C,MAAM,cAAc,iBAAiB,OAJlB,OAAO,IAAI;EAC7B,WAAW,aAAa,MAAM,OAAO;EACrC,QAAQ,UAAU,IAAI,2BAA2B;GAAE;GAAM;GAAO,CAAC;EACjE,CAAC,CACuC;AACzC,KAAI,gBAAgB,MAAM;AAIzB,SAAO,OAAO,IAAI;GACjB,WAAW,WAAW,KAAK;GAC3B,QAAQ,UAAU,IAAI,2BAA2B;IAAE;IAAM;IAAO,CAAC;GACjE,CAAC;AACF,SAAO,EAAE,OAAO,MAAM;;AAevB,MAAI,OAXoB,oBACvB;EACC,KAAK,YAAY;EACjB,WAAW,YAAY;EACvB,UAAU;EACV,WAAW,YAAY;EACvB,aAAa,YAAY;EACzB,QAAQ;EACR,EACD,GACA,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,QAAiB,CAAC,CAAC,MAC3C,QAAS,QAAO,EAAE,OAAO,OAAO;AACjD,QAAO,OAAO,IAAI;EACjB,WAAW,WAAW,KAAK;EAC3B,QAAQ,UAAU,IAAI,2BAA2B;GAAE;GAAM;GAAO,CAAC;EACjE,CAAC;AACF,QAAO,EAAE,OAAO,MAAM;EACrB,CAAC,KAAK,OAAO,SAAS,iDAAiD,CAAC;;;;;;;;;;;;;AAc3E,MAAa,sBACZ,MACA,cAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB,EAAE,sCAAsC,MAAM,CAAC;AAKjF,QAAO,YAAY,KAAK;CACxB,MAAM,OAAO,eAAe,UAAU;AACtC,QAAO,OAAO,IAAI;EACjB,WAAW,cAAc,MAAM,KAAK,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,CAAC;EACpE,QAAQ,UAAU;AAEjB,OADc,MAAgC,SACjC,UAAU;IACtB,IAAI,SAAqC;AACzC,QAAI;AACH,cAAS,iBAAiB,aAAa,MAAM,OAAO,CAAC;YAC9C;AAGR,WAAO,IAAI,6BAA6B;KAAE;KAAM;KAAQ,CAAC;;AAE1D,UAAO,IAAI,2BAA2B;IAAE;IAAM;IAAO,CAAC;;EAEvD,CAAC;AAGF,QAAO,OAAO,mBACb,OAAO,WAAW;AACjB,MAAI;AACH,cAAW,KAAK;UACT;GAKP,CACF;AACD,QAAO;EACN,CAAC,KAAK,OAAO,SAAS,6CAA6C,CAAC"}

package/dist/substrate/runtime/cross-process/stack-lock.d.mts

@@ -0,0 +1 @@
+import { Effect, Scope } from "effect";