@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1,142 @@
+import { checkHolderLiveness, ownHolder } from "./liveness.mjs";
+import { decodeJsonTextSync } from "../runtime-decode.mjs";
+import { Data, Effect, Schema } from "effect";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+//#region src/substrate/runtime/cross-process/stack-lock.ts
+/** Tagged failure: acquire window elapsed and the lock is still held.
+*  Carries the in-disk body (if parseable) so the caller can name the
+*  blocking peer in user-facing error reporting. */
+var StackLockTimeoutError = class extends Data.TaggedError("StackLockTimeoutError") {};
+/** Tagged failure: I/O error other than EEXIST during acquire. */
+var StackLockIoError = class extends Data.TaggedError("StackLockIoError") {};
+/** The on-disk body is the same `RosterHolder` shape — re-using the schema
+*  means roster sweep + stack-lock reclaim see the same fields. */
+const StackLockBodySchema = Schema.Struct({
+	pid: Schema.Number,
+	startTime: Schema.Number,
+	hostname: Schema.String,
+	claimedAt: Schema.Number,
+	heartbeatAt: Schema.Number,
+	intent: Schema.Literals(["normal", "snapshot"])
+});
+const parseLockBody = (raw) => {
+	try {
+		return decodeJsonTextSync(StackLockBodySchema, raw, {
+			source: "stack.lock",
+			mkError: (issue) => issue
+		});
+	} catch {
+		return null;
+	}
+};
+/** Default acquire timeout — architecture § Claim protocol step 1
+*  ("Block up to 5 seconds; if unavailable, retry with backoff"). */
+const DEFAULT_ACQUIRE_TIMEOUT_MILLIS = 5e3;
+/** Per-attempt initial wait. Doubles each retry up to the cap. */
+const INITIAL_BACKOFF_MILLIS = 25;
+const MAX_BACKOFF_MILLIS = 500;
+/**
+* Sync attempt at O_EXCL-create. Returns whether we own the lock now.
+*
+* Effect-platform's FileSystem doesn't expose a sync `open` shape, but
+* the critical-section discipline says we need a non-blocking attempt
+* inside a retry loop. Falling through to Node sync APIs here is the
+* cleanest path; the rest of the substrate stays Effect-native.
+*/
+const tryAcquireSync = (path) => {
+	const body = ownHolder();
+	mkdirSync(dirname(path), { recursive: true });
+	try {
+		writeFileSync(path, JSON.stringify(body), { flag: "wx" });
+		return { ok: true };
+	} catch (err) {
+		if (err.code !== "EEXIST") throw err;
+		if (!existsSync(path)) return {
+			ok: false,
+			holder: null
+		};
+		try {
+			return {
+				ok: false,
+				holder: parseLockBody(readFileSync(path, "utf8"))
+			};
+		} catch {
+			return {
+				ok: false,
+				holder: null
+			};
+		}
+	}
+};
+/**
+* Acquire `stack.lock` as a scoped resource. The lock is released
+* when the surrounding Scope closes.
+*
+* Retry loop: exponential backoff up to `timeoutMillis` (default 5s).
+* On every miss, probe the holder's liveness — if it's dead, reclaim
+* by unlinking and looping. The reclaim path is the architecture's
+* "stale lock" handling — same PID + start-time semantics as the
+* roster sweep, so a process that crashed under the lock never blocks
+* the next peer indefinitely.
+*
+* IMPORTANT: this primitive yields a `void` resource. The caller MUST
+* keep its Scope tight — the architecture forbids holding the lock
+* across long operations.
+*/
+const acquireStackLock = (path, timeoutMillis = DEFAULT_ACQUIRE_TIMEOUT_MILLIS) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({
+		"devstack.stack-lock.path": path,
+		"devstack.stack-lock.timeoutMillis": timeoutMillis
+	});
+	const startedAt = Date.now();
+	let backoff = INITIAL_BACKOFF_MILLIS;
+	let lastHolder = null;
+	while (true) {
+		const elapsed = Date.now() - startedAt;
+		if (elapsed > timeoutMillis) return yield* Effect.fail(new StackLockTimeoutError({
+			path,
+			waitedMillis: elapsed,
+			holder: lastHolder
+		}));
+		const attempt = yield* Effect.try({
+			try: () => tryAcquireSync(path),
+			catch: (cause) => new StackLockIoError({
+				path,
+				cause
+			})
+		});
+		if (attempt.ok) {
+			yield* Effect.addFinalizer(() => Effect.sync(() => {
+				try {
+					unlinkSync(path);
+				} catch {}
+			}));
+			return;
+		}
+		lastHolder = attempt.holder;
+		if (lastHolder !== null) {
+			if ((yield* checkHolderLiveness(lastHolder).pipe(Effect.catch(() => Effect.succeed("alive")))) === "dead") {
+				yield* Effect.try({
+					try: () => {
+						try {
+							unlinkSync(path);
+						} catch {}
+						return null;
+					},
+					catch: (cause) => new StackLockIoError({
+						path,
+						cause
+					})
+				});
+				continue;
+			}
+		}
+		yield* Effect.sleep(`${backoff} millis`);
+		backoff = Math.min(backoff * 2, MAX_BACKOFF_MILLIS);
+	}
+}).pipe(Effect.withSpan("cross-process.stack-lock.acquire"));
+//#endregion
+export { acquireStackLock };
+
+//# sourceMappingURL=stack-lock.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stack-lock.mjs","names":[],"sources":["../../../../src/substrate/runtime/cross-process/stack-lock.ts"],"sourcesContent":["// `stack.lock` — O_EXCL exclusive lock for short critical sections.\n//\n// Architecture § Cross-process safety protocol § \"What is locked\":\n//   - `stack.lock` — OS-advisory exclusive lock file. Used only for\n//     short critical sections (roster mutations, snapshot reservation).\n//     Acquired via `flock(LOCK_EX)` on Unix and `LockFileEx` on Windows;\n//     never held across a long operation.\n//\n// The implementation here uses a portable O_EXCL-create dance — the\n// same approach the legacy `engine/file-lock.ts` proved out — because\n// `flock` isn't available cross-platform out of `node:fs`. The\n// architecture's wording (\"OS-advisory exclusive lock file\") covers\n// both `flock` and `O_EXCL`-with-pid-body; the latter is what every\n// portable POSIX tool reaches for when `flock` isn't on the table.\n//\n// Discipline:\n//   - The lock is held BRIEFLY — within a single Effect.scoped block\n//     that mutates the roster or the snapshot reservation.\n//   - Stale locks (owner crashed under the lock) are reclaimed via the\n//     PID + start-time liveness check before the acquire reattempts.\n//   - Acquire retries with exponential backoff up to 5 seconds total\n//     (architecture § Claim protocol step 1).\n\nimport { mkdirSync, unlinkSync, readFileSync, writeFileSync, existsSync } from 'node:fs';\nimport { dirname } from 'node:path';\n\nimport { Data, Effect, Schema, Scope } from 'effect';\n\nimport { decodeJsonTextSync } from '../runtime-decode.ts';\nimport { checkHolderLiveness, ownHolder } from './liveness.ts';\nimport type { RosterHolder } from '../../cross-process.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** Tagged failure: acquire window elapsed and the lock is still held.\n *  Carries the in-disk body (if parseable) so the caller can name the\n *  blocking peer in user-facing error reporting. */\nexport class StackLockTimeoutError extends Data.TaggedError('StackLockTimeoutError')<{\n\treadonly path: string;\n\treadonly waitedMillis: number;\n\treadonly holder: RosterHolder | null;\n}> {}\n\n/** Tagged failure: I/O error other than EEXIST during acquire. */\nexport class StackLockIoError extends Data.TaggedError('StackLockIoError')<{\n\treadonly path: string;\n\treadonly cause: unknown;\n}> {}\n\nexport type StackLockError = StackLockTimeoutError | StackLockIoError;\n\n// -----------------------------------------------------------------------------\n// Codec\n// -----------------------------------------------------------------------------\n\n/** The on-disk body is the same `RosterHolder` shape — re-using the schema\n *  means roster sweep + stack-lock reclaim see the same fields. */\nconst StackLockBodySchema = Schema.Struct({\n\tpid: Schema.Number,\n\tstartTime: Schema.Number,\n\thostname: Schema.String,\n\tclaimedAt: Schema.Number,\n\theartbeatAt: Schema.Number,\n\tintent: Schema.Literals(['normal', 'snapshot']),\n});\n\nconst parseLockBody = (raw: string): RosterHolder | null => {\n\ttry {\n\t\treturn decodeJsonTextSync(StackLockBodySchema, raw, {\n\t\t\tsource: 'stack.lock',\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Acquire / release\n// -----------------------------------------------------------------------------\n\n/** Default acquire timeout — architecture § Claim protocol step 1\n *  (\"Block up to 5 seconds; if unavailable, retry with backoff\"). */\nexport const DEFAULT_ACQUIRE_TIMEOUT_MILLIS = 5_000;\n\n/** Per-attempt initial wait. Doubles each retry up to the cap. */\nconst INITIAL_BACKOFF_MILLIS = 25;\nconst MAX_BACKOFF_MILLIS = 500;\n\n/**\n * Sync attempt at O_EXCL-create. Returns whether we own the lock now.\n *\n * Effect-platform's FileSystem doesn't expose a sync `open` shape, but\n * the critical-section discipline says we need a non-blocking attempt\n * inside a retry loop. Falling through to Node sync APIs here is the\n * cleanest path; the rest of the substrate stays Effect-native.\n */\nconst tryAcquireSync = (\n\tpath: string,\n): { readonly ok: true } | { readonly ok: false; readonly holder: RosterHolder | null } => {\n\tconst body = ownHolder();\n\t// The lock's parent directory may not exist on first-claim of a\n\t// fresh runtime root — devstack's `<runtimeRoot>/stacks/<stack>/` is\n\t// the substrate's responsibility to bring into being, but no other\n\t// L0 subsystem touches the disk until the first claim. `mkdir -p`\n\t// here is idempotent and harmless on the warm path; it transforms\n\t// the otherwise-fatal ENOENT-during-write into a clean acquire.\n\t// Architecture § Cross-process safety protocol: stack root is\n\t// created by whichever subsystem first reaches for a path under it.\n\tmkdirSync(dirname(path), { recursive: true });\n\ttry {\n\t\twriteFileSync(path, JSON.stringify(body), { flag: 'wx' });\n\t\treturn { ok: true };\n\t} catch (err) {\n\t\tconst code = (err as NodeJS.ErrnoException).code;\n\t\tif (code !== 'EEXIST') {\n\t\t\tthrow err;\n\t\t}\n\t\t// Peer holds it (or stale). Probe the existing body.\n\t\tif (!existsSync(path)) {\n\t\t\t// Race: holder unlinked between our EEXIST and the existsSync.\n\t\t\t// Retry on the next loop iteration.\n\t\t\treturn { ok: false, holder: null };\n\t\t}\n\t\ttry {\n\t\t\tconst raw = readFileSync(path, 'utf8');\n\t\t\treturn { ok: false, holder: parseLockBody(raw) };\n\t\t} catch {\n\t\t\treturn { ok: false, holder: null };\n\t\t}\n\t}\n};\n\n/**\n * Acquire `stack.lock` as a scoped resource. The lock is released\n * when the surrounding Scope closes.\n *\n * Retry loop: exponential backoff up to `timeoutMillis` (default 5s).\n * On every miss, probe the holder's liveness — if it's dead, reclaim\n * by unlinking and looping. The reclaim path is the architecture's\n * \"stale lock\" handling — same PID + start-time semantics as the\n * roster sweep, so a process that crashed under the lock never blocks\n * the next peer indefinitely.\n *\n * IMPORTANT: this primitive yields a `void` resource. The caller MUST\n * keep its Scope tight — the architecture forbids holding the lock\n * across long operations.\n */\nexport const acquireStackLock = (\n\tpath: string,\n\ttimeoutMillis: number = DEFAULT_ACQUIRE_TIMEOUT_MILLIS,\n): Effect.Effect<void, StackLockError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.stack-lock.path': path,\n\t\t\t'devstack.stack-lock.timeoutMillis': timeoutMillis,\n\t\t});\n\t\tconst startedAt = Date.now();\n\t\tlet backoff = INITIAL_BACKOFF_MILLIS;\n\t\tlet lastHolder: RosterHolder | null = null;\n\t\twhile (true) {\n\t\t\tconst elapsed = Date.now() - startedAt;\n\t\t\tif (elapsed > timeoutMillis) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew StackLockTimeoutError({ path, waitedMillis: elapsed, holder: lastHolder }),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst attempt = yield* Effect.try({\n\t\t\t\ttry: () => tryAcquireSync(path),\n\t\t\t\tcatch: (cause) => new StackLockIoError({ path, cause }),\n\t\t\t});\n\t\t\tif (attempt.ok) {\n\t\t\t\t// Register a finalizer that unlinks the lock on scope close.\n\t\t\t\tyield* Effect.addFinalizer(() =>\n\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tunlinkSync(path);\n\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t// Already gone — ok. Crash-during-release is handled\n\t\t\t\t\t\t\t// by the next peer's stale-PID reclaim.\n\t\t\t\t\t\t}\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tlastHolder = attempt.holder;\n\t\t\t// Reclaim if the holder is dead.\n\t\t\tif (lastHolder !== null) {\n\t\t\t\tconst status = yield* checkHolderLiveness(lastHolder).pipe(\n\t\t\t\t\tEffect.catch(() => Effect.succeed('alive' as const)),\n\t\t\t\t);\n\t\t\t\tif (status === 'dead') {\n\t\t\t\t\tyield* Effect.try({\n\t\t\t\t\t\ttry: () => {\n\t\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t\tunlinkSync(path);\n\t\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t\t// Race with another reclaimer — ok.\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\treturn null;\n\t\t\t\t\t\t},\n\t\t\t\t\t\tcatch: (cause) => new StackLockIoError({ path, cause }),\n\t\t\t\t\t});\n\t\t\t\t\t// Loop again immediately; don't sleep for a reclaim.\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t}\n\t\t\tyield* Effect.sleep(`${backoff} millis`);\n\t\t\tbackoff = Math.min(backoff * 2, MAX_BACKOFF_MILLIS);\n\t\t}\n\t}).pipe(Effect.withSpan('cross-process.stack-lock.acquire'));\n"],"mappings":";;;;;;;;;AAuCA,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAIjF;;AAGH,IAAa,mBAAb,cAAsC,KAAK,YAAY,mBAAmB,CAGvE;;;AAUH,MAAM,sBAAsB,OAAO,OAAO;CACzC,KAAK,OAAO;CACZ,WAAW,OAAO;CAClB,UAAU,OAAO;CACjB,WAAW,OAAO;CAClB,aAAa,OAAO;CACpB,QAAQ,OAAO,SAAS,CAAC,UAAU,WAAW,CAAC;CAC/C,CAAC;AAEF,MAAM,iBAAiB,QAAqC;AAC3D,KAAI;AACH,SAAO,mBAAmB,qBAAqB,KAAK;GACnD,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC;SACK;AACP,SAAO;;;;;AAUT,MAAa,iCAAiC;;AAG9C,MAAM,yBAAyB;AAC/B,MAAM,qBAAqB;;;;;;;;;AAU3B,MAAM,kBACL,SAC0F;CAC1F,MAAM,OAAO,WAAW;AASxB,WAAU,QAAQ,KAAK,EAAE,EAAE,WAAW,MAAM,CAAC;AAC7C,KAAI;AACH,gBAAc,MAAM,KAAK,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,CAAC;AACzD,SAAO,EAAE,IAAI,MAAM;UACX,KAAK;AAEb,MADc,IAA8B,SAC/B,SACZ,OAAM;AAGP,MAAI,CAAC,WAAW,KAAK,CAGpB,QAAO;GAAE,IAAI;GAAO,QAAQ;GAAM;AAEnC,MAAI;AAEH,UAAO;IAAE,IAAI;IAAO,QAAQ,cADhB,aAAa,MAAM,OACc,CAAC;IAAE;UACzC;AACP,UAAO;IAAE,IAAI;IAAO,QAAQ;IAAM;;;;;;;;;;;;;;;;;;;AAoBrC,MAAa,oBACZ,MACA,gBAAwB,mCAExB,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB;EACjC,4BAA4B;EAC5B,qCAAqC;EACrC,CAAC;CACF,MAAM,YAAY,KAAK,KAAK;CAC5B,IAAI,UAAU;CACd,IAAI,aAAkC;AACtC,QAAO,MAAM;EACZ,MAAM,UAAU,KAAK,KAAK,GAAG;AAC7B,MAAI,UAAU,cACb,QAAO,OAAO,OAAO,KACpB,IAAI,sBAAsB;GAAE;GAAM,cAAc;GAAS,QAAQ;GAAY,CAAC,CAC9E;EAEF,MAAM,UAAU,OAAO,OAAO,IAAI;GACjC,WAAW,eAAe,KAAK;GAC/B,QAAQ,UAAU,IAAI,iBAAiB;IAAE;IAAM;IAAO,CAAC;GACvD,CAAC;AACF,MAAI,QAAQ,IAAI;AAEf,UAAO,OAAO,mBACb,OAAO,WAAW;AACjB,QAAI;AACH,gBAAW,KAAK;YACT;KAIP,CACF;AACD;;AAED,eAAa,QAAQ;AAErB,MAAI,eAAe;QAId,OAHkB,oBAAoB,WAAW,CAAC,KACrD,OAAO,YAAY,OAAO,QAAQ,QAAiB,CAAC,CACpD,MACc,QAAQ;AACtB,WAAO,OAAO,IAAI;KACjB,WAAW;AACV,UAAI;AACH,kBAAW,KAAK;cACT;AAGR,aAAO;;KAER,QAAQ,UAAU,IAAI,iBAAiB;MAAE;MAAM;MAAO,CAAC;KACvD,CAAC;AAEF;;;AAGF,SAAO,OAAO,MAAM,GAAG,QAAQ,SAAS;AACxC,YAAU,KAAK,IAAI,UAAU,GAAG,mBAAmB;;EAEnD,CAAC,KAAK,OAAO,SAAS,mCAAmC,CAAC"}

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

@@ -0,0 +1,15 @@
+import { Context, Effect, Option } from "effect";
+//#region src/substrate/runtime/current-plugin.ts
+var CurrentPluginKey = class extends Context.Service()("@devstack-rewrite/substrate/CurrentPluginKey") {};
+var CurrentPluginProgress = class extends Context.Service()("@devstack-rewrite/substrate/CurrentPluginProgress") {};
+/** Publish acquire-time row narration for the currently supervised
+* plugin. Safe to call from plugin code: if the caller is running
+* outside a supervisor, the helper is a no-op. */
+const setCurrentPluginPhase = (phase) => Effect.gen(function* () {
+	const progress = yield* Effect.serviceOption(CurrentPluginProgress);
+	if (Option.isSome(progress)) yield* progress.value.setPhase(phase);
+});
+//#endregion
+export { CurrentPluginKey, CurrentPluginProgress, setCurrentPluginPhase };
+
+//# sourceMappingURL=current-plugin.mjs.map

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

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

package/dist/substrate/runtime/errors.d.mts

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

package/dist/substrate/runtime/errors.mjs

@@ -0,0 +1,76 @@
+import { Schema } from "effect";
+//#region src/substrate/runtime/errors.ts
+/** Atomic-write failure — one tag covers every stage. The `stage`
+*  field discriminates inside renderer messages without
+*  proliferating tag types. */
+var AtomicWriteFailed = class extends Schema.TaggedErrorClass()("AtomicWriteFailed", {
+	path: Schema.String,
+	stage: Schema.Literals([
+		"mkdir-parent",
+		"open-temp",
+		"write",
+		"fsync",
+		"rename",
+		"encode"
+	]),
+	cause: Schema.optional(Schema.Defect)
+}) {};
+Schema.TaggedErrorClass()("StateStoreError", {
+	reason: Schema.Literals([
+		"io-failed",
+		"corruption",
+		"lock-contention"
+	]),
+	detail: Schema.String,
+	cause: Schema.optional(Schema.Defect)
+});
+/** Cache surface — same tri-state as the L0 cache contract. */
+var CacheError = class extends Schema.TaggedErrorClass()("CacheError", {
+	reason: Schema.Literals([
+		"io-failed",
+		"corruption",
+		"lock-contention"
+	]),
+	detail: Schema.String,
+	cause: Schema.optional(Schema.Defect)
+}) {};
+/** Strategy registry missing-key surface — mirrors
+*  `StrategyNotFoundError` from `contracts/strategy-contributor.ts`
+*  as a yieldable. */
+var StrategyNotFoundError = class extends Schema.TaggedErrorClass()("StrategyNotFoundError", {
+	capabilityKey: Schema.String,
+	registeredKeys: Schema.Array(Schema.String)
+}) {};
+/** Port-broker allocation failure — surfaced when no free port could be
+*  found in the configured range, when a caller-supplied `preferredPort`
+*  is already taken by another in-process allocation, or when the bind-
+*  probe rejected every candidate.
+*
+*  `reason` discriminates the failure mode for renderer mapping:
+*    - `no-free-port`  : scanned the whole window for `kind`, every
+*                        candidate failed the bind-probe (EADDRINUSE) or
+*                        was already held by a sibling allocation in
+*                        this process.
+*    - `preferred-busy`: caller supplied a `preferredPort` and the
+*                        port is currently held by another in-process
+*                        allocation (refused per architecture §6).
+*    - `bind-probe-failed`: the OS-level bind probe surfaced an error
+*                          OTHER than `EADDRINUSE` (e.g. EACCES on a
+*                          privileged port, EPERM under jail). Caller
+*                          should fall back to user opt-in / docs.
+*    - `reservation-failed`: the runtime-root scoped port reservation
+*                            file could not be created/read/reclaimed. */
+var PortBrokerError = class extends Schema.TaggedErrorClass()("PortBrokerError", {
+	reason: Schema.Literals([
+		"no-free-port",
+		"preferred-busy",
+		"bind-probe-failed",
+		"reservation-failed"
+	]),
+	detail: Schema.String,
+	cause: Schema.optional(Schema.Defect)
+}) {};
+//#endregion
+export { AtomicWriteFailed, CacheError, PortBrokerError, StrategyNotFoundError };
+
+//# sourceMappingURL=errors.mjs.map

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

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

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

@@ -0,0 +1,364 @@
+import { awaitProcessExit, describeProcessExitStatus } from "../process-supervisor.mjs";
+import { Effect, Schema, Stream } from "effect";
+import { spawn } from "node:child_process";
+//#region src/substrate/runtime/host-tree-tar/index.ts
+/** Tagged failure during tar / untar. `stage` discriminates the
+*  precise step (spawn vs stream-read vs exit-code).
+*
+*  `cause` carries the underlying error verbatim; the cascade
+*  formatter walks it. */
+var HostTreeTarError = class extends Schema.TaggedErrorClass()("HostTreeTarError", {
+	stage: Schema.Literals([
+		"spawn",
+		"stream-stdout",
+		"stream-stdin",
+		"exit-code",
+		"entry-validation",
+		"no-subtrees"
+	]),
+	operation: Schema.Literals(["tar", "untar"]),
+	detail: Schema.String,
+	/** Captured stderr from the `tar` subprocess (last ~4 KB). */
+	stderrTail: Schema.optional(Schema.String),
+	exitCode: Schema.optional(Schema.Number),
+	cause: Schema.optional(Schema.Defect)
+}) {};
+const TAR_STDERR_TAIL_BYTES = 4096;
+const collectStderrTail = (chunks) => {
+	if (chunks.length === 0) return "";
+	let total = 0;
+	for (let i = chunks.length - 1; i >= 0; i--) {
+		total += chunks[i].length;
+		if (total >= TAR_STDERR_TAIL_BYTES) break;
+	}
+	const bytes = Buffer.concat(chunks);
+	return bytes.subarray(Math.max(0, bytes.length - TAR_STDERR_TAIL_BYTES)).toString("utf8");
+};
+const tarExitError = (operation, status, stderrChunks) => new HostTreeTarError({
+	stage: "exit-code",
+	operation,
+	exitCode: status.code ?? -1,
+	detail: `'tar' exited with ${describeProcessExitStatus(status)}`,
+	stderrTail: collectStderrTail(stderrChunks)
+});
+const TAR_BLOCK_SIZE = 512;
+const MAX_TAR_EXTENDED_PATH_BYTES = 1024 * 1024;
+const bytesToString = (bytes) => {
+	const nul = bytes.indexOf(0);
+	const end = nul === -1 ? bytes.length : nul;
+	return Buffer.from(bytes.subarray(0, end)).toString("utf8");
+};
+const concatBytes = (a, b) => {
+	if (a.length === 0) return b;
+	if (b.length === 0) return a;
+	const out = new Uint8Array(a.length + b.length);
+	out.set(a, 0);
+	out.set(b, a.length);
+	return out;
+};
+const consumeBytes = (buffer, count) => buffer.subarray(count);
+const isZeroBlock = (block) => block.every((byte) => byte === 0);
+const parseTarSize = (header) => {
+	const raw = bytesToString(header.subarray(124, 136)).trim();
+	if (raw === "") return 0;
+	if (!/^[0-7]+$/.test(raw)) return null;
+	const parsed = Number.parseInt(raw, 8);
+	return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
+};
+const tarPathFromHeader = (header) => {
+	const name = bytesToString(header.subarray(0, 100));
+	const prefix = bytesToString(header.subarray(345, 500));
+	return prefix === "" ? name : `${prefix}/${name}`;
+};
+const tarLinkPathFromHeader = (header) => bytesToString(header.subarray(157, 257));
+const trimExtendedPath = (bytes) => {
+	const value = Buffer.from(bytes).toString("utf8").replace(/\n$/g, "");
+	let end = value.length;
+	while (end > 0 && value.charCodeAt(end - 1) === 0) end -= 1;
+	return value.slice(0, end);
+};
+const isSafeArchivePath = (entryPath) => {
+	if (entryPath === "" || entryPath === "." || entryPath.includes("\0") || entryPath.includes("\\") || entryPath.startsWith("/") || /^[A-Za-z]:/.test(entryPath)) return false;
+	const meaningfulSegments = entryPath.split("/").filter((segment) => segment !== "" && segment !== ".");
+	return meaningfulSegments.length > 0 && !meaningfulSegments.includes("..");
+};
+const parsePaxRecords = (bytes) => {
+	const text = Buffer.from(bytes).toString("utf8");
+	const records = {};
+	let offset = 0;
+	while (offset < text.length) {
+		const space = text.indexOf(" ", offset);
+		if (space === -1) break;
+		const lengthText = text.slice(offset, space);
+		const recordLength = Number.parseInt(lengthText, 10);
+		if (!Number.isSafeInteger(recordLength) || recordLength <= 0) break;
+		const record = text.slice(space + 1, offset + recordLength).replace(/\n$/g, "");
+		const eq = record.indexOf("=");
+		if (eq > 0) records[record.slice(0, eq)] = record.slice(eq + 1);
+		offset += recordLength;
+	}
+	return records;
+};
+const tarValidationError = (detail) => new HostTreeTarError({
+	stage: "entry-validation",
+	operation: "untar",
+	detail
+});
+const applyExtendedContent = (state, content) => {
+	const bytes = content.chunks.length === 1 ? content.chunks[0] : Buffer.concat(content.chunks.map((chunk) => Buffer.from(chunk)));
+	if (content.kind === "gnu-path") {
+		state.pendingPath = trimExtendedPath(bytes);
+		return null;
+	}
+	if (content.kind === "gnu-link") {
+		state.pendingLinkPath = trimExtendedPath(bytes);
+		return null;
+	}
+	const records = parsePaxRecords(bytes);
+	if (content.kind === "pax-global" && (records.path !== void 0 || records.linkpath !== void 0)) return tarValidationError("global pax path/linkpath records are not supported in snapshots");
+	if (content.kind === "pax-local") {
+		if (records.path !== void 0) state.pendingPath = records.path;
+		if (records.linkpath !== void 0) state.pendingLinkPath = records.linkpath;
+	}
+	return null;
+};
+const processTarValidationChunk = (state, chunk) => {
+	state.buffer = concatBytes(state.buffer, chunk);
+	while (state.buffer.length > 0) {
+		if (state.content !== null) {
+			const content = state.content;
+			const remaining = content.paddedSize - content.totalBytesRead;
+			const take = Math.min(remaining, state.buffer.length);
+			const contentTake = Math.max(0, Math.min(take, content.size - content.contentBytesRead));
+			if (contentTake > 0) content.chunks.push(state.buffer.subarray(0, contentTake));
+			state.content = {
+				...content,
+				contentBytesRead: content.contentBytesRead + contentTake,
+				totalBytesRead: content.totalBytesRead + take
+			};
+			state.buffer = consumeBytes(state.buffer, take);
+			if (state.content.totalBytesRead === state.content.paddedSize) {
+				const completed = state.content;
+				state.content = null;
+				const error = applyExtendedContent(state, completed);
+				if (error !== null) return error;
+			}
+			continue;
+		}
+		if (state.skipRemaining > 0) {
+			const take = Math.min(state.skipRemaining, state.buffer.length);
+			state.skipRemaining -= take;
+			state.buffer = consumeBytes(state.buffer, take);
+			continue;
+		}
+		if (state.buffer.length < TAR_BLOCK_SIZE) return null;
+		const header = state.buffer.subarray(0, TAR_BLOCK_SIZE);
+		state.buffer = consumeBytes(state.buffer, TAR_BLOCK_SIZE);
+		if (isZeroBlock(header)) continue;
+		const size = parseTarSize(header);
+		if (size === null) return tarValidationError("tar entry has an invalid size header");
+		const paddedSize = Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;
+		const typeflag = String.fromCharCode(header[156] ?? 0).replace("\0", "");
+		if (typeflag === "x" || typeflag === "g" || typeflag === "L" || typeflag === "K") {
+			if (size > MAX_TAR_EXTENDED_PATH_BYTES) return tarValidationError("tar extended path record is too large");
+			state.content = {
+				kind: typeflag === "x" ? "pax-local" : typeflag === "g" ? "pax-global" : typeflag === "L" ? "gnu-path" : "gnu-link",
+				size,
+				paddedSize,
+				chunks: [],
+				contentBytesRead: 0,
+				totalBytesRead: 0
+			};
+			continue;
+		}
+		const entryPath = state.pendingPath ?? tarPathFromHeader(header);
+		state.pendingPath = null;
+		if (!isSafeArchivePath(entryPath)) return tarValidationError(`unsafe tar entry path: ${entryPath}`);
+		const linkPath = state.pendingLinkPath ?? tarLinkPathFromHeader(header);
+		state.pendingLinkPath = null;
+		if ((typeflag === "1" || typeflag === "2") && !isSafeArchivePath(linkPath)) return tarValidationError(`unsafe tar link target: ${linkPath}`);
+		state.skipRemaining = paddedSize;
+	}
+	return null;
+};
+const finishTarValidation = (state) => {
+	if (state.content !== null) return tarValidationError("tar ended inside an extended header");
+	if (state.skipRemaining !== 0) return tarValidationError("tar ended inside file content");
+	if (state.buffer.length !== 0 && !isZeroBlock(state.buffer)) return tarValidationError("tar ended with a partial header");
+	return null;
+};
+const validateHostTreeTarEntries = (stream) => Effect.gen(function* () {
+	const state = {
+		buffer: new Uint8Array(0),
+		skipRemaining: 0,
+		content: null,
+		pendingPath: null,
+		pendingLinkPath: null
+	};
+	yield* Stream.runForEach(stream, (chunk) => {
+		const error = processTarValidationChunk(state, chunk);
+		return error === null ? Effect.void : Effect.fail(error);
+	});
+	const finalError = finishTarValidation(state);
+	if (finalError !== null) return yield* Effect.fail(finalError);
+});
+/**
+* Stream the tar archive of `relPaths` (relative to `parentDir`) as a
+* `Stream<Uint8Array>`. Mode bits are preserved.
+*
+* The subprocess is bound to the consuming Scope: closing the scope
+* before the stream finishes kills the subprocess and surfaces
+* `stream-stdout` if the consumer was mid-read.
+*
+* Caller consumes via `Stream.run(...)` — e.g. pipe to a file via
+* `Stream.run(stream, Sink.fromWritable(() => createWriteStream(...)))`
+* or to an in-memory chunk array for the integrity hash.
+*/
+const tarHostTree = (spec) => Stream.unwrap(Effect.gen(function* () {
+	if (spec.relPaths.length === 0) return Stream.fail(new HostTreeTarError({
+		stage: "no-subtrees",
+		operation: "tar",
+		detail: "tarHostTree called with empty relPaths list"
+	}));
+	const args = [
+		"-c",
+		"-f",
+		"-",
+		"-C",
+		spec.parentDir,
+		"-p",
+		...spec.relPaths
+	];
+	const child = yield* Effect.try({
+		try: () => spawn("tar", args, { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] }),
+		catch: (cause) => new HostTreeTarError({
+			stage: "spawn",
+			operation: "tar",
+			detail: `failed to spawn 'tar ${args.join(" ")}'`,
+			cause
+		})
+	});
+	const stderrChunks = [];
+	const onStderr = (chunk) => {
+		stderrChunks.push(chunk);
+		if (stderrChunks.length > 256) stderrChunks.splice(0, stderrChunks.length - 256);
+	};
+	child.stderr?.on("data", onStderr);
+	yield* Effect.addFinalizer(() => Effect.sync(() => {
+		child.stderr?.off("data", onStderr);
+		if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+	}));
+	const stdout = child.stdout;
+	if (stdout === null) return Stream.fail(new HostTreeTarError({
+		stage: "spawn",
+		operation: "tar",
+		detail: `'tar' subprocess produced no stdout pipe`
+	}));
+	const dataStream = Stream.fromAsyncIterable(stdout, (cause) => new HostTreeTarError({
+		stage: "stream-stdout",
+		operation: "tar",
+		detail: `read from tar stdout failed`,
+		cause
+	}));
+	const exitGate = Stream.fromEffect(Effect.promise(() => awaitProcessExit(child)).pipe(Effect.flatMap((status) => status.code === 0 && status.signal === null ? Effect.succeed(new Uint8Array(0)) : Effect.fail(tarExitError("tar", status, stderrChunks))))).pipe(Stream.filter((bytes) => bytes.length > 0));
+	return Stream.concat(dataStream, exitGate);
+}));
+/**
+* Extract a tar `Stream<Uint8Array>` into `target`, preserving mode
+* bits. The target directory MUST already exist; the caller is
+* responsible (stage-and-swap creates the staging directory before
+* calling).
+*
+* The subprocess consumes from the stream and writes into `target`;
+* scope close kills the subprocess. The Effect resolves when `tar`
+* exits cleanly (code 0).
+*/
+const untarHostTree = (stream, spec) => Effect.gen(function* () {
+	const args = [
+		"-x",
+		"-f",
+		"-",
+		"-C",
+		spec.target,
+		"-p"
+	];
+	const child = yield* Effect.try({
+		try: () => spawn("tar", args, { stdio: [
+			"pipe",
+			"ignore",
+			"pipe"
+		] }),
+		catch: (cause) => new HostTreeTarError({
+			stage: "spawn",
+			operation: "untar",
+			detail: `failed to spawn 'tar ${args.join(" ")}'`,
+			cause
+		})
+	});
+	const stderrChunks = [];
+	const onStderr = (chunk) => {
+		stderrChunks.push(chunk);
+		if (stderrChunks.length > 256) stderrChunks.splice(0, stderrChunks.length - 256);
+	};
+	child.stderr?.on("data", onStderr);
+	yield* Effect.addFinalizer(() => Effect.sync(() => {
+		child.stderr?.off("data", onStderr);
+		if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+	}));
+	const stdin = child.stdin;
+	if (stdin === null) return yield* Effect.fail(new HostTreeTarError({
+		stage: "spawn",
+		operation: "untar",
+		detail: `'tar' subprocess produced no stdin pipe`
+	}));
+	const validationState = {
+		buffer: new Uint8Array(0),
+		skipRemaining: 0,
+		content: null,
+		pendingPath: null,
+		pendingLinkPath: null
+	};
+	const writeChunk = (chunk) => Effect.callback((resume) => {
+		let settled = false;
+		const settle = (effect) => {
+			if (!settled) {
+				settled = true;
+				resume(effect);
+			}
+		};
+		const onDrain = () => settle(Effect.void);
+		if (!stdin.write(chunk, (cause) => {
+			stdin.off("drain", onDrain);
+			if (cause) settle(Effect.fail(new HostTreeTarError({
+				stage: "stream-stdin",
+				operation: "untar",
+				detail: `write to tar stdin failed`,
+				cause
+			})));
+			else settle(Effect.void);
+		})) stdin.once("drain", onDrain);
+	});
+	yield* Stream.runForEach(stream, (chunk) => Effect.gen(function* () {
+		const validationError = processTarValidationChunk(validationState, chunk);
+		if (validationError !== null) return yield* Effect.fail(validationError);
+		yield* writeChunk(chunk);
+	})).pipe(Effect.catch((cause) => cause instanceof HostTreeTarError ? Effect.fail(cause) : Effect.fail(new HostTreeTarError({
+		stage: "stream-stdin",
+		operation: "untar",
+		detail: `source stream raised before EOF`,
+		cause
+	}))));
+	const finalValidationError = finishTarValidation(validationState);
+	if (finalValidationError !== null) return yield* Effect.fail(finalValidationError);
+	yield* Effect.sync(() => stdin.end());
+	const status = yield* Effect.promise(() => awaitProcessExit(child));
+	if (status.code !== 0 || status.signal !== null) return yield* Effect.fail(tarExitError("untar", status, stderrChunks));
+}).pipe(Effect.withSpan("substrate.host-tree-tar.untar"));
+//#endregion
+export { HostTreeTarError, tarHostTree, untarHostTree, validateHostTreeTarEntries };
+
+//# sourceMappingURL=index.mjs.map