@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/substrate/runtime/cross-process/reclaim-stale-file.mjs

@@ -0,0 +1,64 @@
+import { DEFAULT_SWEEP_POLICY } from "../../cross-process.mjs";
+import { readFileSync, statSync, unlinkSync } from "node:fs";
+//#region src/substrate/runtime/cross-process/reclaim-stale-file.ts
+const identityOf = (path) => {
+	try {
+		const s = statSync(path);
+		return {
+			mtimeMs: s.mtimeMs,
+			ino: s.ino,
+			dev: s.dev
+		};
+	} catch {
+		return null;
+	}
+};
+const sameIdentity = (a, b) => a.mtimeMs === b.mtimeMs && a.ino === b.ino && a.dev === b.dev;
+const readOrNull = (path) => {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+};
+/** Reclaim `path` IFF it is an aged, unparseable orphan — with a re-stat
+*  guard that NARROWS (not closes) the TOCTOU window between the
+*  staleness check and the unlink. See the module header for the
+*  deliberately-accepted sub-microsecond residual between the final
+*  re-read and the path-based unlink.
+*
+*  `parse` is the caller's body decoder; it returns a non-null value for
+*  a well-formed body and `null` for an unparseable one. We never look
+*  at the decoded value — only at whether it parsed — so the lock and
+*  the reservation can share one guard despite carrying different
+*  schemas.
+*
+*  The staleness threshold is `DEFAULT_SWEEP_POLICY.staleAfterMillis`
+*  (30s), matching the roster's eviction window: anything that crashed
+*  mid-write at least 30s ago is presumed abandoned.
+*
+*  Never throws. Any I/O failure resolves to a conservative non-
+*  reclaiming outcome so a transient stat/read hiccup never triggers a
+*  spurious unlink — the caller's backoff loop retries on the next pass. */
+const reclaimUnparseableStaleFile = (path, parse, staleAfterMillis = DEFAULT_SWEEP_POLICY.staleAfterMillis) => {
+	const before = identityOf(path);
+	if (before === null) return "absent";
+	const rawBefore = readOrNull(path);
+	if (rawBefore === null) return "absent";
+	if (parse(rawBefore) !== null) return "parseable";
+	if (!(Date.now() - before.mtimeMs > staleAfterMillis)) return "fresh";
+	const after = identityOf(path);
+	if (after === null) return "reclaimed";
+	if (!sameIdentity(before, after)) return "changed";
+	const rawAfter = readOrNull(path);
+	if (rawAfter === null) return "reclaimed";
+	if (parse(rawAfter) !== null) return "changed";
+	try {
+		unlinkSync(path);
+	} catch {}
+	return "reclaimed";
+};
+//#endregion
+export { reclaimUnparseableStaleFile };
+
+//# sourceMappingURL=reclaim-stale-file.mjs.map

package/dist/substrate/runtime/cross-process/reclaim-stale-file.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"reclaim-stale-file.mjs","names":[],"sources":["../../../../src/substrate/runtime/cross-process/reclaim-stale-file.ts"],"sourcesContent":["// Shared reclaim guard for unparseable/orphaned coordination files.\n//\n// Both `stack.lock` (stack-lock.ts) and `snapshot.reservation`\n// (snapshot-reservation.ts) reclaim a file whose on-disk body fails to\n// parse (a peer that crashed mid-write) once it ages past the roster\n// sweep's staleness window. The PID liveness check has nothing to\n// consult when the body won't parse, so mtime + the shared staleness\n// budget is the only abandonment signal.\n//\n// The naive shape — `statSync` for the mtime, then `unlinkSync` — has a\n// TOCTOU window: between reading the mtime and unlinking, a competing\n// process can legitimately reclaim the garbage lock and write a FRESH,\n// VALID O_EXCL body. The unconditional `unlinkSync` would then clobber\n// that live lock, producing two simultaneous holders (a mutual-\n// exclusion break). This module NARROWS the window — it does not fully\n// eliminate it — by RE-STATTING the file immediately before the unlink\n// and confirming it is STILL the same stale inode (same mtime + ino +\n// dev) AND still unparseable. If anything changed, the reclaim bails\n// and the caller falls back to its normal backoff/retry path so the\n// competitor's fresh body survives.\n//\n// Residual race (deliberately accepted): the final `unlinkSync` is\n// path-based and UNCONDITIONAL, so between the re-stat/re-read and the\n// syscall a competing reclaimer can still unlink+O_EXCL-create a fresh\n// body that this unlink then deletes. Closing it fully would need an\n// atomic, inode-pinned delete (`renameat2(RENAME_EXCHANGE)` or an fd\n// held across the check) that `node:fs` does not portably expose — a\n// plain `rename(path, …)` is itself path-based and would relocate the\n// competitor's fresh body just as readily, so it buys nothing. The\n// re-stat shrinks the window from \"mtime read → unlink\" (a parse +\n// staleness comparison wide) to \"re-read → unlink\" (a couple of\n// syscalls), making a real collision require both racers mid-reclaim of\n// the SAME file with sub-microsecond timing. Given that, the residual\n// is left open rather than papered over with an equally-racy rename.\n//\n// The dead-PID liveness reclaim path is NOT routed through here: that\n// branch is gated on a holder-liveness probe (see liveness.ts) and is\n// already safe — a dead holder cannot have written a fresh body. Only\n// the unparseable/mtime-stale branch carries the TOCTOU, so only it\n// needs this guard.\n//\n// Sync `node:fs` by design — the call sites are inside `Effect.try`\n// critical sections that need a non-blocking attempt; the rest of the\n// substrate stays Effect-native.\n\nimport { readFileSync, statSync, unlinkSync } from 'node:fs';\n\nimport { DEFAULT_SWEEP_POLICY } from '../../cross-process.ts';\n\n/** Outcome of a reclaim attempt.\n *\n *  - `reclaimed` — the file was an aged, unparseable orphan and we\n *    unlinked it (or it vanished from under us mid-reclaim, which is the\n *    same observable end state: the slot is free for the next O_EXCL).\n *  - `parseable` — the body parsed, so it is NOT an orphan; a live peer\n *    holds it (possibly one that just reclaimed the garbage ahead of\n *    us). Do not touch it.\n *  - `fresh` — the body is unparseable but its mtime is inside the\n *    staleness window; a writer is presumed mid-flush. Respect the\n *    budget and leave it.\n *  - `changed` — the re-stat guard fired: the file's identity (mtime /\n *    ino / dev) or parse-state changed between the staleness check and\n *    the unlink, meaning a competitor reclaimed the slot and wrote a\n *    fresh body in the window. We bailed to avoid clobbering it.\n *  - `absent` — the file was already gone when we looked. */\nexport type ReclaimOutcome = 'reclaimed' | 'parseable' | 'fresh' | 'changed' | 'absent';\n\n/** A minimal, comparable identity for a file on disk. Two reads of the\n *  same untouched inode produce equal triples; any rewrite (O_EXCL\n *  unlink+create, or an in-place touch) perturbs at least one field. */\ninterface FileIdentity {\n\treadonly mtimeMs: number;\n\treadonly ino: number;\n\treadonly dev: number;\n}\n\nconst identityOf = (path: string): FileIdentity | null => {\n\ttry {\n\t\tconst s = statSync(path);\n\t\treturn { mtimeMs: s.mtimeMs, ino: s.ino, dev: s.dev };\n\t} catch {\n\t\t// ENOENT (gone) or any transient stat failure — treat as absent.\n\t\treturn null;\n\t}\n};\n\nconst sameIdentity = (a: FileIdentity, b: FileIdentity): boolean =>\n\ta.mtimeMs === b.mtimeMs && a.ino === b.ino && a.dev === b.dev;\n\nconst readOrNull = (path: string): string | null => {\n\ttry {\n\t\treturn readFileSync(path, 'utf8');\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n/** Reclaim `path` IFF it is an aged, unparseable orphan — with a re-stat\n *  guard that NARROWS (not closes) the TOCTOU window between the\n *  staleness check and the unlink. See the module header for the\n *  deliberately-accepted sub-microsecond residual between the final\n *  re-read and the path-based unlink.\n *\n *  `parse` is the caller's body decoder; it returns a non-null value for\n *  a well-formed body and `null` for an unparseable one. We never look\n *  at the decoded value — only at whether it parsed — so the lock and\n *  the reservation can share one guard despite carrying different\n *  schemas.\n *\n *  The staleness threshold is `DEFAULT_SWEEP_POLICY.staleAfterMillis`\n *  (30s), matching the roster's eviction window: anything that crashed\n *  mid-write at least 30s ago is presumed abandoned.\n *\n *  Never throws. Any I/O failure resolves to a conservative non-\n *  reclaiming outcome so a transient stat/read hiccup never triggers a\n *  spurious unlink — the caller's backoff loop retries on the next pass. */\nexport const reclaimUnparseableStaleFile = (\n\tpath: string,\n\tparse: (raw: string) => unknown,\n\tstaleAfterMillis: number = DEFAULT_SWEEP_POLICY.staleAfterMillis,\n): ReclaimOutcome => {\n\t// 1. Initial identity + staleness.\n\tconst before = identityOf(path);\n\tif (before === null) return 'absent';\n\n\tconst rawBefore = readOrNull(path);\n\tif (rawBefore === null) return 'absent';\n\tif (parse(rawBefore) !== null) return 'parseable';\n\n\tconst isStale = Date.now() - before.mtimeMs > staleAfterMillis;\n\tif (!isStale) return 'fresh';\n\n\t// 2. Re-stat guard — NARROWS (does not close) the TOCTOU. Between the\n\t//    read above and the unlink below, a competitor may have reclaimed\n\t//    the garbage and written a FRESH valid O_EXCL body. Re-confirm the\n\t//    file is STILL the same stale inode AND still unparseable before\n\t//    unlinking. A sub-microsecond residual remains between this\n\t//    re-read and the path-based unlink (see header) — accepted.\n\tconst after = identityOf(path);\n\tif (after === null) {\n\t\t// Vanished from under us — a sibling reclaimer won the unlink. The\n\t\t// slot is free; report it as reclaimed (same observable result).\n\t\treturn 'reclaimed';\n\t}\n\tif (!sameIdentity(before, after)) return 'changed';\n\n\tconst rawAfter = readOrNull(path);\n\tif (rawAfter === null) return 'reclaimed';\n\tif (parse(rawAfter) !== null) return 'changed';\n\n\t// 3. Still the same stale, unparseable orphan — safe to unlink.\n\ttry {\n\t\tunlinkSync(path);\n\t} catch {\n\t\t// Race with another reclaimer that unlinked first — harmless; the\n\t\t// slot is free either way.\n\t}\n\treturn 'reclaimed';\n};\n"],"mappings":";;;AA4EA,MAAM,cAAc,SAAsC;AACzD,KAAI;EACH,MAAM,IAAI,SAAS,KAAK;AACxB,SAAO;GAAE,SAAS,EAAE;GAAS,KAAK,EAAE;GAAK,KAAK,EAAE;GAAK;SAC9C;AAEP,SAAO;;;AAIT,MAAM,gBAAgB,GAAiB,MACtC,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE;AAE3D,MAAM,cAAc,SAAgC;AACnD,KAAI;AACH,SAAO,aAAa,MAAM,OAAO;SAC1B;AACP,SAAO;;;;;;;;;;;;;;;;;;;;;;AAuBT,MAAa,+BACZ,MACA,OACA,mBAA2B,qBAAqB,qBAC5B;CAEpB,MAAM,SAAS,WAAW,KAAK;AAC/B,KAAI,WAAW,KAAM,QAAO;CAE5B,MAAM,YAAY,WAAW,KAAK;AAClC,KAAI,cAAc,KAAM,QAAO;AAC/B,KAAI,MAAM,UAAU,KAAK,KAAM,QAAO;AAGtC,KAAI,EADY,KAAK,KAAK,GAAG,OAAO,UAAU,kBAChC,QAAO;CAQrB,MAAM,QAAQ,WAAW,KAAK;AAC9B,KAAI,UAAU,KAGb,QAAO;AAER,KAAI,CAAC,aAAa,QAAQ,MAAM,CAAE,QAAO;CAEzC,MAAM,WAAW,WAAW,KAAK;AACjC,KAAI,aAAa,KAAM,QAAO;AAC9B,KAAI,MAAM,SAAS,KAAK,KAAM,QAAO;AAGrC,KAAI;AACH,aAAW,KAAK;SACT;AAIR,QAAO"}

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

@@ -1,12 +1,11 @@
-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 { versionedDocSchema } from "../../versioned-doc-schema.mjs";
+import { selfPid } from "./self-pid.mjs";
+import { DEFAULT_SWEEP_POLICY, RosterDocumentSchema } from "../../cross-process.mjs";
+import { readVersionedDocumentSync, writeVersionedDocumentSync } from "../../versioned-doc-sync.mjs";
+import { LivenessProbeScope, isPidAlive, layerLivenessProbeScope, ownHolder, processStartTime } from "./liveness.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") {};
@@ -15,39 +14,27 @@ const EMPTY_ROSTER = {
 	version: 1,
 	holders: []
 };
+const ROSTER_DOC_ERRORS = {
+	mkIo: ({ path, cause }) => new RosterIoError({
+		path,
+		cause
+	}),
+	mkCorrupt: ({ path, raw, cause }) => new RosterCorruptError({
+		path,
+		raw,
+		cause
+	})
+};
 /** 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"));
+const readRoster = (path) => readVersionedDocumentSync(path, RosterDocumentSchema, ROSTER_DOC_ERRORS, EMPTY_ROSTER).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
-	})
-});
+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`.
 *
@@ -58,14 +45,16 @@ const atomicWriteRoster = (path, doc) => Effect.try({
 *  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 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* checkHolderLiveness(holder).pipe(Effect.catch(() => Effect.succeed("alive")))) === "dead") evicted.push(holder);
+		if ((yield* probe.probeHolderLiveness(holder, ownHost).pipe(Effect.catch(() => Effect.succeed("alive")))) === "dead") evicted.push(holder);
 		else survivors.push(holder);
 	}
 	return {
@@ -75,7 +64,37 @@ 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
+*  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
+*  overwritten/removed by this process.
+*
+*  `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`. */
+const isOwnEntry = (h, ownPid, ownHost, ownStartTime) => {
+	if (h.pid !== ownPid || h.hostname !== ownHost) return false;
+	if (ownStartTime === null || h.startTime === null) return true;
+	return h.startTime === ownStartTime;
+};
 const withStackLock = (paths, body) => Effect.scoped(Effect.gen(function* () {
 	yield* acquireStackLock(paths.stackLockFile);
 	return yield* body;
@@ -115,15 +134,16 @@ const claim = (paths, intent = "normal", policy = DEFAULT_SWEEP_POLICY) => withS
 * stack lock to keep mutation atomic. Architecture § Heartbeat
 * protocol.
 */
-const heartbeat = (paths, ownPid = process.pid) => withStackLock(paths, Effect.gen(function* () {
+const heartbeat = (paths, ownPid = selfPid()) => 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();
+	const ownStartTime = processStartTime(ownPid);
 	let touched = false;
 	const next = {
 		version: 1,
 		holders: current.holders.map((h) => {
-			if (h.pid === ownPid && h.hostname === ownHost) {
+			if (isOwnEntry(h, ownPid, ownHost, ownStartTime)) {
 				touched = true;
 				return {
 					...h,
@@ -141,10 +161,11 @@ const heartbeat = (paths, ownPid = process.pid) => withStackLock(paths, Effect.g
 * 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 release = (paths, ownPid = selfPid()) => 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 ownStartTime = processStartTime(ownPid);
+	const remaining = current.holders.filter((h) => !isOwnEntry(h, ownPid, ownHost, ownStartTime));
 	const next = {
 		version: 1,
 		holders: remaining
@@ -177,64 +198,56 @@ const ContainerClaimSchema = Schema.Struct({
 	hostname: Schema.String,
 	claimedAt: Schema.Number
 });
-const ContainerClaimDocumentSchema = Schema.Struct({
-	version: Schema.Literal(1),
-	claims: Schema.Array(ContainerClaimSchema)
-});
+const ContainerClaimDocumentSchema = versionedDocSchema(1, { claims: Schema.Array(ContainerClaimSchema) });
 const EMPTY_CLAIMS = {
 	version: 1,
 	claims: []
 };
-const claimsPath = (rosterFile) => `${dirname(rosterFile)}/container-claims.json`;
-const isContainerClaimLive = (claim, ownHost = hostname()) => {
+/** 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 = processStartTime(claim.pid);
+	const probedStart = probeStartTime(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
-	})
-});
+/** 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.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"));
+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 = claimsPath(paths.rosterFile);
+	const path = requireClaimsPath(paths);
 	const current = yield* readClaims(paths).pipe(Effect.catchTag("RosterCorruptError", () => Effect.succeed(EMPTY_CLAIMS)));
-	const live = liveContainerClaims(current);
-	const ownPid = process.pid;
+	const live = yield* liveContainerClaims(current);
+	const ownPid = selfPid();
 	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.some((c) => isOwnContainerClaim(c, containerKey, ownPid, ownHost, ownStartTime))) {
 		if (live.claims.length !== current.claims.length) yield* writeClaims(path, live);
 		return;
 	}
@@ -257,11 +270,12 @@ const addClaim = (paths, containerKey) => withStackLock(paths, Effect.gen(functi
 *  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 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) => !(c.containerKey === containerKey && c.pid === ownPid && c.hostname === ownHost));
+	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,
@@ -270,6 +284,6 @@ const removeClaim = (paths, containerKey) => withStackLock(paths, Effect.gen(fun
 	return { lastClaimReleased: !stillClaimedByPeer };
 })).pipe(Effect.withSpan("cross-process.roster.removeClaim"));
 //#endregion
-export { addClaim, claim, heartbeatFiber, readClaims, readRoster, release, removeClaim };
+export { RosterCorruptError, RosterIoError, addClaim, claim, heartbeat, heartbeatFiber, readClaims, readRoster, release, removeClaim, 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 { 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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"}
+{"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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"}

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

@@ -0,0 +1,8 @@
+//#region src/substrate/runtime/cross-process/self-pid.ts
+/** This process's PID. Module-level indirection so cross-process
+*  protocol modules read through one named entry point. */
+const selfPid = () => process.pid;
+//#endregion
+export { selfPid };
+
+//# sourceMappingURL=self-pid.mjs.map

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

@@ -0,0 +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"}

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

@@ -1,25 +1,22 @@
+import { SpanAttr } from "../observability/spans.mjs";
+import { selfPid } from "./self-pid.mjs";
 import { SnapshotReservationSchema } from "../../cross-process.mjs";
+import { parseVersionedDocumentBodyOrNull } from "../../versioned-doc-sync.mjs";
 import { checkHolderLiveness } from "./liveness.mjs";
-import { decodeJsonTextSync } from "../runtime-decode.mjs";
+import { reclaimUnparseableStaleFile } from "./reclaim-stale-file.mjs";
 import { Data, Effect } from "effect";
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
 //#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 parseReservation = (raw) => parseVersionedDocumentBodyOrNull(raw, SnapshotReservationSchema, "snapshot.reservation");
 const ownReservation = (startTime) => ({
-	creatorPid: process.pid,
+	version: 1,
+	creatorPid: selfPid(),
 	creatorStartTime: startTime,
-	createdAt: Date.now()
+	createdAt: Date.now(),
+	hostname: hostname()
 });
 /**
 * Sweep an orphaned reservation. If the file exists AND its creator is
@@ -33,7 +30,7 @@ const ownReservation = (startTime) => ({
 *    reservation's creator entry is dead) and unlinks it."
 */
 const sweepOrphan = (path) => Effect.gen(function* () {
-	yield* Effect.annotateCurrentSpan({ "devstack.snapshot-reservation.path": path });
+	yield* Effect.annotateCurrentSpan({ [SpanAttr.snapshotReservationPath]: path });
 	if (!existsSync(path)) return { swept: false };
 	const reservation = parseReservation(yield* Effect.try({
 		try: () => readFileSync(path, "utf8"),
@@ -42,24 +39,23 @@ const sweepOrphan = (path) => Effect.gen(function* () {
 			cause
 		})
 	}));
-	if (reservation === null) {
-		yield* Effect.try({
-			try: () => unlinkSync(path),
-			catch: (cause) => new SnapshotReservationIoError({
-				path,
-				cause
-			})
-		});
-		return { swept: true };
-	}
+	if (reservation === null) return { swept: (yield* Effect.try({
+		try: () => reclaimUnparseableStaleFile(path, parseReservation),
+		catch: (cause) => new SnapshotReservationIoError({
+			path,
+			cause
+		})
+	})) === "reclaimed" };
+	const ownHost = hostname();
+	if (reservation.hostname !== ownHost) return { swept: false };
 	if ((yield* checkHolderLiveness({
 		pid: reservation.creatorPid,
 		startTime: reservation.creatorStartTime,
-		hostname: "",
+		hostname: reservation.hostname,
 		claimedAt: reservation.createdAt,
 		heartbeatAt: reservation.createdAt,
 		intent: "snapshot"
-	}, "").pipe(Effect.catch(() => Effect.succeed("alive")))) === "alive") return { swept: false };
+	}, ownHost).pipe(Effect.catch(() => Effect.succeed("alive")))) === "alive") return { swept: false };
 	yield* Effect.try({
 		try: () => unlinkSync(path),
 		catch: (cause) => new SnapshotReservationIoError({
@@ -82,7 +78,7 @@ const sweepOrphan = (path) => Effect.gen(function* () {
 * 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* Effect.annotateCurrentSpan({ [SpanAttr.snapshotReservationPath]: path });
 	yield* sweepOrphan(path);
 	const body = ownReservation(startTime);
 	yield* Effect.try({
@@ -112,6 +108,6 @@ const acquireReservation = (path, startTime) => Effect.gen(function* () {
 	return body;
 }).pipe(Effect.withSpan("cross-process.snapshot-reservation.acquire"));
 //#endregion
-export { acquireReservation };
+export { SnapshotReservationHeldError, SnapshotReservationIoError, acquireReservation, sweepOrphan };
 
 //# sourceMappingURL=snapshot-reservation.mjs.map