@mysten-incubation/devstack 0.1.1 → 0.2.0

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

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

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

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

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

@@ -1,4 +1,5 @@
 import { awaitProcessExit, describeProcessExitStatus } from "../process-supervisor.mjs";
+import { finishTarReader, isSafeArchivePath, makeTarReaderState, processTarChunk, skipEntry } from "../tar/reader.mjs";
 import { Effect, Schema, Stream } from "effect";
 import { spawn } from "node:child_process";
 //#region src/substrate/runtime/host-tree-tar/index.ts
@@ -77,169 +78,26 @@ const spawnTar = (operation, args, stdio) => Effect.gen(function* () {
 		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) => {
-	if (state.content === null && state.skipRemaining >= chunk.length && state.buffer.length === 0) {
-		state.skipRemaining -= chunk.length;
-		return null;
-	}
-	state.buffer = concatBytes(state.buffer, chunk);
-	while (state.buffer.length > 0) {
-		if (state.content !== null) {
-			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 hostTreeValidationHooks = {
+	onEntry: (entry) => {
+		if (!isSafeArchivePath(entry.path)) return tarValidationError(`unsafe tar entry path: ${entry.path}`);
+		if ((entry.typeflag === "1" || entry.typeflag === "2") && !isSafeArchivePath(entry.linkPath)) return tarValidationError(`unsafe tar link target: ${entry.linkPath}`);
+		return skipEntry();
+	},
+	onExtendedError: (detail) => tarValidationError(detail === "global pax path/linkpath records are not supported" ? "global pax path/linkpath records are not supported in snapshots" : detail)
 };
 const validateHostTreeTarEntries = (stream) => Effect.gen(function* () {
-	const state = {
-		buffer: new Uint8Array(0),
-		skipRemaining: 0,
-		content: null,
-		pendingPath: null,
-		pendingLinkPath: null
-	};
+	const state = makeTarReaderState();
 	yield* Stream.runForEach(stream, (chunk) => {
-		const error = processTarValidationChunk(state, chunk);
+		const error = processTarChunk(state, chunk, hostTreeValidationHooks);
 		return error === null ? Effect.void : Effect.fail(error);
 	});
-	const finalError = finishTarValidation(state);
+	const finalError = finishTarReader(state, tarValidationError);
 	if (finalError !== null) return yield* Effect.fail(finalError);
 });
 /**
@@ -323,13 +181,7 @@ const untarHostTree = (stream, spec) => Effect.gen(function* () {
 		operation: "untar",
 		detail: `'tar' subprocess produced no stdin pipe`
 	}));
-	const validationState = {
-		buffer: new Uint8Array(0),
-		skipRemaining: 0,
-		content: null,
-		pendingPath: null,
-		pendingLinkPath: null
-	};
+	const validationState = makeTarReaderState();
 	const writeChunk = (chunk) => Effect.callback((resume) => {
 		let settled = false;
 		const settle = (effect) => {
@@ -354,7 +206,7 @@ const untarHostTree = (stream, spec) => Effect.gen(function* () {
 		});
 	});
 	yield* Stream.runForEach(stream, (chunk) => Effect.gen(function* () {
-		const validationError = processTarValidationChunk(validationState, chunk);
+		const validationError = processTarChunk(validationState, chunk, hostTreeValidationHooks);
 		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({
@@ -363,12 +215,12 @@ const untarHostTree = (stream, spec) => Effect.gen(function* () {
 		detail: `source stream raised before EOF`,
 		cause
 	}))));
-	const finalValidationError = finishTarValidation(validationState);
+	const finalValidationError = finishTarReader(validationState, tarValidationError);
 	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 };
 

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

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/substrate/runtime/host-tree-tar/index.ts"],"sourcesContent":["// host-tree-tar — stream a host filesystem subtree as a tar archive.\n//\n// Architecture §\"Substrate primitives roster\" (Open slot O21):\n// snapshot orchestrator hard-fails today on the `tarHostTree` /\n// `untarHostTree` stubs. This primitive fills the slot.\n//\n// Design:\n//   - Stream-based — `tarHostTree` returns a `Stream<Uint8Array>`;\n//     `untarHostTree` consumes one. The entire tree NEVER materialises\n//     in memory (snapshot trees can hold gigabytes of cache state).\n//   - Mode-preserving — the snapshot orchestrator carries 0o600 /\n//     0o700 mode bits on secret material (postgres keys, account\n//     keystores). System `tar -p` (extract) and `tar --no-recursion`\n//     (control) preserve them natively. We do NOT roll our own\n//     archive writer (a TypeScript-side reimplementation would have\n//     to track POSIX mode flags + extended attributes; system tar is\n//     correct by default).\n//   - Subprocess-based — spawn `tar` (BSD-tar on macOS, GNU-tar on\n//     Linux); both honour the flags used here (`-c` / `-x` / `-f -`).\n//     Exit code != 0 surfaces as `TarSpawnFailed`.\n//\n// Boundary:\n//   - Substrate-level: this is a generic filesystem primitive; no\n//     plugin names referenced.\n//   - The caller controls which subtrees are archived (snapshot\n//     orchestrator passes a list of relative paths under a parent\n//     dir). Permission preservation is unconditional.\n\nimport { spawn, type ChildProcess, type StdioOptions } from 'node:child_process';\n\nimport { Effect, Schema, Scope, Stream } from 'effect';\n\nimport {\n\tawaitProcessExit,\n\tdescribeProcessExitStatus,\n\ttype ManagedProcessChild,\n\ttype ManagedProcessExitStatus,\n} from '../process-supervisor.ts';\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\n/** Tagged failure during tar / untar. `stage` discriminates the\n *  precise step (spawn vs stream-read vs exit-code).\n *\n *  `cause` carries the underlying error verbatim; the cascade\n *  formatter walks it. */\nexport class HostTreeTarError extends Schema.TaggedErrorClass<HostTreeTarError>()(\n\t'HostTreeTarError',\n\t{\n\t\tstage: Schema.Literals([\n\t\t\t'spawn',\n\t\t\t'stream-stdout',\n\t\t\t'stream-stdin',\n\t\t\t'exit-code',\n\t\t\t'entry-validation',\n\t\t\t'no-subtrees',\n\t\t]),\n\t\toperation: Schema.Literals(['tar', 'untar']),\n\t\tdetail: Schema.String,\n\t\t/** Captured stderr from the `tar` subprocess (last ~4 KB). */\n\t\tstderrTail: Schema.optional(Schema.String),\n\t\texitCode: Schema.optional(Schema.Number),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n// ---------------------------------------------------------------------------\n// Tar one or more subtrees → Stream<Uint8Array>\n// ---------------------------------------------------------------------------\n\n/** Spec for `tarHostTree`.\n *\n *  - `parentDir`: directory the relative paths are anchored under.\n *    `tar -C <parentDir>` runs the archive with this as cwd, so the\n *    archive entries are stored relative to `parentDir`.\n *  - `relPaths`: subtree paths relative to `parentDir`. Empty list\n *    fails fast (`stage: 'no-subtrees'`) — the caller is responsible\n *    for the host-tree-included guard. */\nexport interface TarHostTreeSpec {\n\treadonly parentDir: string;\n\treadonly relPaths: ReadonlyArray<string>;\n}\n\nconst TAR_STDERR_TAIL_BYTES = 4096;\n\nconst collectStderrTail = (chunks: Array<Uint8Array>): string => {\n\tif (chunks.length === 0) return '';\n\tlet total = 0;\n\tfor (let i = chunks.length - 1; i >= 0; i--) {\n\t\ttotal += chunks[i]!.length;\n\t\tif (total >= TAR_STDERR_TAIL_BYTES) break;\n\t}\n\tconst bytes = Buffer.concat(chunks);\n\treturn bytes.subarray(Math.max(0, bytes.length - TAR_STDERR_TAIL_BYTES)).toString('utf8');\n};\n\nconst tarExitError = (\n\toperation: 'tar' | 'untar',\n\tstatus: ManagedProcessExitStatus,\n\tstderrChunks: Array<Uint8Array>,\n): HostTreeTarError =>\n\tnew HostTreeTarError({\n\t\tstage: 'exit-code',\n\t\toperation,\n\t\texitCode: status.code ?? -1,\n\t\tdetail: `'tar' exited with ${describeProcessExitStatus(status)}`,\n\t\tstderrTail: collectStderrTail(stderrChunks),\n\t});\n\n/** Spawn `tar` with a bounded stderr ring buffer and a SIGKILL-on-\n *  scope-close finalizer. Both `tarHostTree` and `untarHostTree` share\n *  this body verbatim — only the args, stdio direction (which pipe is\n *  the data channel), and the `operation` tag differ. The data pipe\n *  (`stdout` for tar, `stdin` for untar) is read off the returned\n *  `child` by the caller; stderr is always piped so the exit-code\n *  failure can carry the captured tail.\n *\n *  The stderr listener is removed and a live child is killed on scope\n *  close — the finalizer binds to the surrounding Scope (the stream's\n *  lifecycle for tar, the consuming Effect's for untar). */\nconst spawnTar = (\n\toperation: 'tar' | 'untar',\n\targs: ReadonlyArray<string>,\n\tstdio: StdioOptions,\n): Effect.Effect<\n\t{ readonly child: ChildProcess; readonly stderrChunks: Array<Uint8Array> },\n\tHostTreeTarError,\n\tScope.Scope\n> =>\n\tEffect.gen(function* () {\n\t\tconst child = yield* Effect.try({\n\t\t\ttry: () => spawn('tar', [...args], { stdio }),\n\t\t\tcatch: (cause) =>\n\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\tstage: 'spawn',\n\t\t\t\t\toperation,\n\t\t\t\t\tdetail: `failed to spawn 'tar ${args.join(' ')}'`,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t});\n\n\t\t// Stderr collection lives outside the data stream — we accumulate\n\t\t// the tail so an exit-code failure carries actionable context. The\n\t\t// stderr listener is removed on scope close.\n\t\tconst stderrChunks: Array<Uint8Array> = [];\n\t\tconst onStderr = (chunk: Buffer): void => {\n\t\t\tstderrChunks.push(chunk);\n\t\t\tif (stderrChunks.length > 256) stderrChunks.splice(0, stderrChunks.length - 256);\n\t\t};\n\t\tchild.stderr?.on('data', onStderr);\n\n\t\t// Finalise the subprocess on scope close: kill if alive, drop\n\t\t// listeners either way.\n\t\tyield* Effect.addFinalizer(() =>\n\t\t\tEffect.sync(() => {\n\t\t\t\tchild.stderr?.off('data', onStderr);\n\t\t\t\tif (child.exitCode === null && child.signalCode === null) {\n\t\t\t\t\tchild.kill('SIGKILL');\n\t\t\t\t}\n\t\t\t}),\n\t\t);\n\n\t\treturn { child, stderrChunks };\n\t});\n\nconst TAR_BLOCK_SIZE = 512;\nconst MAX_TAR_EXTENDED_PATH_BYTES = 1024 * 1024;\n\nconst bytesToString = (bytes: Uint8Array): string => {\n\tconst nul = bytes.indexOf(0);\n\tconst end = nul === -1 ? bytes.length : nul;\n\treturn Buffer.from(bytes.subarray(0, end)).toString('utf8');\n};\n\nconst concatBytes = (a: Uint8Array, b: Uint8Array): Uint8Array => {\n\tif (a.length === 0) return b;\n\tif (b.length === 0) return a;\n\tconst out = new Uint8Array(a.length + b.length);\n\tout.set(a, 0);\n\tout.set(b, a.length);\n\treturn out;\n};\n\nconst consumeBytes = (buffer: Uint8Array, count: number): Uint8Array => buffer.subarray(count);\n\nconst isZeroBlock = (block: Uint8Array): boolean => block.every((byte) => byte === 0);\n\nconst parseTarSize = (header: Uint8Array): number | null => {\n\tconst raw = bytesToString(header.subarray(124, 136)).trim();\n\tif (raw === '') return 0;\n\tif (!/^[0-7]+$/.test(raw)) return null;\n\tconst parsed = Number.parseInt(raw, 8);\n\treturn Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;\n};\n\nconst tarPathFromHeader = (header: Uint8Array): string => {\n\tconst name = bytesToString(header.subarray(0, 100));\n\tconst prefix = bytesToString(header.subarray(345, 500));\n\treturn prefix === '' ? name : `${prefix}/${name}`;\n};\n\nconst tarLinkPathFromHeader = (header: Uint8Array): string =>\n\tbytesToString(header.subarray(157, 257));\n\nconst trimExtendedPath = (bytes: Uint8Array): string => {\n\tconst value = Buffer.from(bytes).toString('utf8').replace(/\\n$/g, '');\n\tlet end = value.length;\n\twhile (end > 0 && value.charCodeAt(end - 1) === 0) end -= 1;\n\treturn value.slice(0, end);\n};\n\nconst isSafeArchivePath = (entryPath: string): boolean => {\n\tif (\n\t\tentryPath === '' ||\n\t\tentryPath === '.' ||\n\t\tentryPath.includes('\\0') ||\n\t\tentryPath.includes('\\\\') ||\n\t\tentryPath.startsWith('/') ||\n\t\t/^[A-Za-z]:/.test(entryPath)\n\t) {\n\t\treturn false;\n\t}\n\tconst meaningfulSegments = entryPath\n\t\t.split('/')\n\t\t.filter((segment) => segment !== '' && segment !== '.');\n\treturn meaningfulSegments.length > 0 && !meaningfulSegments.includes('..');\n};\n\nconst parsePaxRecords = (bytes: Uint8Array): Record<string, string> => {\n\tconst text = Buffer.from(bytes).toString('utf8');\n\tconst records: Record<string, string> = {};\n\tlet offset = 0;\n\twhile (offset < text.length) {\n\t\tconst space = text.indexOf(' ', offset);\n\t\tif (space === -1) break;\n\t\tconst lengthText = text.slice(offset, space);\n\t\tconst recordLength = Number.parseInt(lengthText, 10);\n\t\tif (!Number.isSafeInteger(recordLength) || recordLength <= 0) break;\n\t\tconst record = text.slice(space + 1, offset + recordLength).replace(/\\n$/g, '');\n\t\tconst eq = record.indexOf('=');\n\t\tif (eq > 0) {\n\t\t\trecords[record.slice(0, eq)] = record.slice(eq + 1);\n\t\t}\n\t\toffset += recordLength;\n\t}\n\treturn records;\n};\n\ninterface TarContentState {\n\treadonly kind: 'pax-local' | 'pax-global' | 'gnu-path' | 'gnu-link';\n\treadonly size: number;\n\treadonly paddedSize: number;\n\treadonly chunks: Array<Uint8Array>;\n\treadonly contentBytesRead: number;\n\treadonly totalBytesRead: number;\n}\n\ninterface TarValidationState {\n\tbuffer: Uint8Array;\n\tskipRemaining: number;\n\tcontent: TarContentState | null;\n\tpendingPath: string | null;\n\tpendingLinkPath: string | null;\n}\n\nconst tarValidationError = (detail: string): HostTreeTarError =>\n\tnew HostTreeTarError({\n\t\tstage: 'entry-validation',\n\t\toperation: 'untar',\n\t\tdetail,\n\t});\n\nconst applyExtendedContent = (\n\tstate: TarValidationState,\n\tcontent: TarContentState,\n): HostTreeTarError | null => {\n\tconst bytes =\n\t\tcontent.chunks.length === 1\n\t\t\t? content.chunks[0]!\n\t\t\t: Buffer.concat(content.chunks.map((chunk) => Buffer.from(chunk)));\n\tif (content.kind === 'gnu-path') {\n\t\tstate.pendingPath = trimExtendedPath(bytes);\n\t\treturn null;\n\t}\n\tif (content.kind === 'gnu-link') {\n\t\tstate.pendingLinkPath = trimExtendedPath(bytes);\n\t\treturn null;\n\t}\n\tconst records = parsePaxRecords(bytes);\n\tif (\n\t\tcontent.kind === 'pax-global' &&\n\t\t(records.path !== undefined || records.linkpath !== undefined)\n\t) {\n\t\treturn tarValidationError('global pax path/linkpath records are not supported in snapshots');\n\t}\n\tif (content.kind === 'pax-local') {\n\t\tif (records.path !== undefined) state.pendingPath = records.path;\n\t\tif (records.linkpath !== undefined) state.pendingLinkPath = records.linkpath;\n\t}\n\treturn null;\n};\n\nconst processTarValidationChunk = (\n\tstate: TarValidationState,\n\tchunk: Uint8Array,\n): HostTreeTarError | null => {\n\t// Fast path: we're mid-skip over a large file body and this chunk is\n\t// fully consumed by the skip. Avoid `concatBytes` (O(N) per call →\n\t// O(N²) across a multi-MB body streamed in 64KB chunks). The buffer\n\t// must be empty so we don't re-order bytes relative to the parser.\n\tif (\n\t\tstate.content === null &&\n\t\tstate.skipRemaining >= chunk.length &&\n\t\tstate.buffer.length === 0\n\t) {\n\t\tstate.skipRemaining -= chunk.length;\n\t\treturn null;\n\t}\n\tstate.buffer = concatBytes(state.buffer, chunk);\n\twhile (state.buffer.length > 0) {\n\t\tif (state.content !== null) {\n\t\t\tconst content = state.content;\n\t\t\tconst remaining = content.paddedSize - content.totalBytesRead;\n\t\t\tconst take = Math.min(remaining, state.buffer.length);\n\t\t\tconst contentTake = Math.max(0, Math.min(take, content.size - content.contentBytesRead));\n\t\t\tif (contentTake > 0) {\n\t\t\t\tcontent.chunks.push(state.buffer.subarray(0, contentTake));\n\t\t\t}\n\t\t\tstate.content = {\n\t\t\t\t...content,\n\t\t\t\tcontentBytesRead: content.contentBytesRead + contentTake,\n\t\t\t\ttotalBytesRead: content.totalBytesRead + take,\n\t\t\t};\n\t\t\tstate.buffer = consumeBytes(state.buffer, take);\n\t\t\tif (state.content.totalBytesRead === state.content.paddedSize) {\n\t\t\t\tconst completed = state.content;\n\t\t\t\tstate.content = null;\n\t\t\t\tconst error = applyExtendedContent(state, completed);\n\t\t\t\tif (error !== null) return error;\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (state.skipRemaining > 0) {\n\t\t\tconst take = Math.min(state.skipRemaining, state.buffer.length);\n\t\t\tstate.skipRemaining -= take;\n\t\t\tstate.buffer = consumeBytes(state.buffer, take);\n\t\t\tcontinue;\n\t\t}\n\t\tif (state.buffer.length < TAR_BLOCK_SIZE) return null;\n\t\tconst header = state.buffer.subarray(0, TAR_BLOCK_SIZE);\n\t\tstate.buffer = consumeBytes(state.buffer, TAR_BLOCK_SIZE);\n\t\tif (isZeroBlock(header)) continue;\n\n\t\tconst size = parseTarSize(header);\n\t\tif (size === null) return tarValidationError('tar entry has an invalid size header');\n\t\tconst paddedSize = Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;\n\t\tconst typeflag = String.fromCharCode(header[156] ?? 0).replace('\\0', '');\n\t\tif (typeflag === 'x' || typeflag === 'g' || typeflag === 'L' || typeflag === 'K') {\n\t\t\tif (size > MAX_TAR_EXTENDED_PATH_BYTES) {\n\t\t\t\treturn tarValidationError('tar extended path record is too large');\n\t\t\t}\n\t\t\tstate.content = {\n\t\t\t\tkind:\n\t\t\t\t\ttypeflag === 'x'\n\t\t\t\t\t\t? 'pax-local'\n\t\t\t\t\t\t: typeflag === 'g'\n\t\t\t\t\t\t\t? 'pax-global'\n\t\t\t\t\t\t\t: typeflag === 'L'\n\t\t\t\t\t\t\t\t? 'gnu-path'\n\t\t\t\t\t\t\t\t: 'gnu-link',\n\t\t\t\tsize,\n\t\t\t\tpaddedSize,\n\t\t\t\tchunks: [],\n\t\t\t\tcontentBytesRead: 0,\n\t\t\t\ttotalBytesRead: 0,\n\t\t\t};\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst entryPath = state.pendingPath ?? tarPathFromHeader(header);\n\t\tstate.pendingPath = null;\n\t\tif (!isSafeArchivePath(entryPath)) {\n\t\t\treturn tarValidationError(`unsafe tar entry path: ${entryPath}`);\n\t\t}\n\t\tconst linkPath = state.pendingLinkPath ?? tarLinkPathFromHeader(header);\n\t\tstate.pendingLinkPath = null;\n\t\tif ((typeflag === '1' || typeflag === '2') && !isSafeArchivePath(linkPath)) {\n\t\t\treturn tarValidationError(`unsafe tar link target: ${linkPath}`);\n\t\t}\n\t\tstate.skipRemaining = paddedSize;\n\t}\n\treturn null;\n};\n\nconst finishTarValidation = (state: TarValidationState): HostTreeTarError | null => {\n\tif (state.content !== null) return tarValidationError('tar ended inside an extended header');\n\tif (state.skipRemaining !== 0) return tarValidationError('tar ended inside file content');\n\tif (state.buffer.length !== 0 && !isZeroBlock(state.buffer)) {\n\t\treturn tarValidationError('tar ended with a partial header');\n\t}\n\treturn null;\n};\n\nexport const validateHostTreeTarEntries = <R>(\n\tstream: Stream.Stream<Uint8Array, HostTreeTarError, R>,\n): Effect.Effect<void, HostTreeTarError, R> =>\n\tEffect.gen(function* () {\n\t\tconst state: TarValidationState = {\n\t\t\tbuffer: new Uint8Array(0),\n\t\t\tskipRemaining: 0,\n\t\t\tcontent: null,\n\t\t\tpendingPath: null,\n\t\t\tpendingLinkPath: null,\n\t\t};\n\t\tyield* Stream.runForEach(stream, (chunk) => {\n\t\t\tconst error = processTarValidationChunk(state, chunk);\n\t\t\treturn error === null ? Effect.void : Effect.fail(error);\n\t\t});\n\t\tconst finalError = finishTarValidation(state);\n\t\tif (finalError !== null) return yield* Effect.fail(finalError);\n\t});\n\n/**\n * Stream the tar archive of `relPaths` (relative to `parentDir`) as a\n * `Stream<Uint8Array>`. Mode bits are preserved.\n *\n * The subprocess is bound to the consuming Scope: closing the scope\n * before the stream finishes kills the subprocess and surfaces\n * `stream-stdout` if the consumer was mid-read.\n *\n * Caller consumes via `Stream.run(...)` — e.g. pipe to a file via\n * `Stream.run(stream, Sink.fromWritable(() => createWriteStream(...)))`\n * or to an in-memory chunk array for the integrity hash.\n */\nexport const tarHostTree = (\n\tspec: TarHostTreeSpec,\n): Stream.Stream<Uint8Array, HostTreeTarError, never> =>\n\t// `Stream.unwrap` provides the channel's surrounding scope to the\n\t// inner Effect (see `effect/src/Channel.ts:7918` —\n\t// `Scope.provide(scope)`), so `Effect.addFinalizer` below binds to\n\t// the stream's lifecycle: the subprocess kill-on-close fires when\n\t// the stream terminates. The R-channel `Exclude<R, Scope>` reads\n\t// \"scope satisfied by the stream\" — not \"scope dropped\".\n\tStream.unwrap(\n\t\tEffect.gen(function* () {\n\t\t\tif (spec.relPaths.length === 0) {\n\t\t\t\treturn Stream.fail(\n\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\tstage: 'no-subtrees',\n\t\t\t\t\t\toperation: 'tar',\n\t\t\t\t\t\tdetail: 'tarHostTree called with empty relPaths list',\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t// Producer-boundary path defense — mirror the extraction-side\n\t\t\t// `isSafeArchivePath`. The caller controls `relPaths`, and they\n\t\t\t// are spliced straight into `tar -C <parentDir> … relPaths`. An\n\t\t\t// absolute path or a `..` segment would archive a subtree\n\t\t\t// outside `parentDir` (and on extraction escape `target`). We\n\t\t\t// reject at the producer rather than relying on the consumer's\n\t\t\t// entry validation alone.\n\t\t\tconst unsafe = spec.relPaths.find((relPath) => !isSafeArchivePath(relPath));\n\t\t\tif (unsafe !== undefined) {\n\t\t\t\treturn Stream.fail(\n\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\tstage: 'entry-validation',\n\t\t\t\t\t\toperation: 'tar',\n\t\t\t\t\t\tdetail: `unsafe tar relPath (absolute or contains '..'): ${unsafe}`,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t// `-c` create, `-f -` write to stdout, `-C <dir>` cd-before,\n\t\t\t// `-p` preserve permissions (matches BSD-tar + GNU-tar). The\n\t\t\t// subprocess emits its own bytes; we don't apply any\n\t\t\t// transcoding.\n\t\t\tconst args = ['-c', '-f', '-', '-C', spec.parentDir, '-p', ...spec.relPaths];\n\t\t\tconst { child, stderrChunks } = yield* spawnTar('tar', args, ['ignore', 'pipe', 'pipe']);\n\n\t\t\t// Wrap stdout (a Node Readable) as a Stream<Uint8Array>.\n\t\t\t// `Stream.fromReadable` is the substrate-blessed shape.\n\t\t\tconst stdout = child.stdout;\n\t\t\tif (stdout === null) {\n\t\t\t\treturn Stream.fail(\n\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\tstage: 'spawn',\n\t\t\t\t\t\toperation: 'tar',\n\t\t\t\t\t\tdetail: `'tar' subprocess produced no stdout pipe`,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t// Node `Readable` is an `AsyncIterable<Buffer>`; `Buffer`\n\t\t\t// extends `Uint8Array` structurally. The cast asserts the\n\t\t\t// nominal-vs-structural gap at the Node boundary and stays\n\t\t\t// off the user-facing API.\n\t\t\tconst dataStream = Stream.fromAsyncIterable(\n\t\t\t\tstdout as unknown as AsyncIterable<Uint8Array>,\n\t\t\t\t(cause) =>\n\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\tstage: 'stream-stdout',\n\t\t\t\t\t\toperation: 'tar',\n\t\t\t\t\t\tdetail: `read from tar stdout failed`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t}),\n\t\t\t);\n\n\t\t\t// After stdout closes, await the subprocess exit and surface\n\t\t\t// non-zero codes with the captured stderr tail. This appends\n\t\t\t// a \"tail\" sub-stream that emits zero bytes but can fail —\n\t\t\t// the consumer's `Stream.run` sees the exit-code failure\n\t\t\t// uniformly with stream-read failures.\n\t\t\tconst exitGate: Stream.Stream<Uint8Array, HostTreeTarError, never> = Stream.fromEffect(\n\t\t\t\tEffect.promise(() => awaitProcessExit(child as ManagedProcessChild)).pipe(\n\t\t\t\t\tEffect.flatMap((status) =>\n\t\t\t\t\t\tstatus.code === 0 && status.signal === null\n\t\t\t\t\t\t\t? Effect.succeed(new Uint8Array(0))\n\t\t\t\t\t\t\t: Effect.fail(tarExitError('tar', status, stderrChunks)),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t).pipe(Stream.filter((bytes) => bytes.length > 0));\n\n\t\t\treturn Stream.concat(dataStream, exitGate);\n\t\t}),\n\t);\n\n// ---------------------------------------------------------------------------\n// Untar a Stream<Uint8Array> into a target directory\n// ---------------------------------------------------------------------------\n\nexport interface UntarHostTreeSpec {\n\treadonly target: string;\n}\n\n/**\n * Extract a tar `Stream<Uint8Array>` into `target`, preserving mode\n * bits. The target directory MUST already exist; the caller is\n * responsible (stage-and-swap creates the staging directory before\n * calling).\n *\n * The subprocess consumes from the stream and writes into `target`;\n * scope close kills the subprocess. The Effect resolves when `tar`\n * exits cleanly (code 0).\n */\nexport const untarHostTree = <R>(\n\tstream: Stream.Stream<Uint8Array, HostTreeTarError, R>,\n\tspec: UntarHostTreeSpec,\n): Effect.Effect<void, HostTreeTarError, R | Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst args = ['-x', '-f', '-', '-C', spec.target, '-p'];\n\t\tconst { child, stderrChunks } = yield* spawnTar('untar', args, ['pipe', 'ignore', 'pipe']);\n\n\t\tconst stdin = child.stdin;\n\t\tif (stdin === null) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\tstage: 'spawn',\n\t\t\t\t\toperation: 'untar',\n\t\t\t\t\tdetail: `'tar' subprocess produced no stdin pipe`,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\n\t\tconst validationState: TarValidationState = {\n\t\t\tbuffer: new Uint8Array(0),\n\t\t\tskipRemaining: 0,\n\t\t\tcontent: null,\n\t\t\tpendingPath: null,\n\t\t\tpendingLinkPath: null,\n\t\t};\n\n\t\tconst writeChunk = (chunk: Uint8Array): Effect.Effect<void, HostTreeTarError> =>\n\t\t\tEffect.callback<void, HostTreeTarError>((resume) => {\n\t\t\t\tlet settled = false;\n\t\t\t\tconst settle = (effect: Effect.Effect<void, HostTreeTarError>): void => {\n\t\t\t\t\tif (!settled) {\n\t\t\t\t\t\tsettled = true;\n\t\t\t\t\t\tresume(effect);\n\t\t\t\t\t}\n\t\t\t\t};\n\t\t\t\tconst onDrain = (): void => settle(Effect.void);\n\t\t\t\tconst ok = stdin.write(chunk, (cause) => {\n\t\t\t\t\tstdin.off('drain', onDrain);\n\t\t\t\t\tif (cause) {\n\t\t\t\t\t\tsettle(\n\t\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\t\t\t\tstage: 'stream-stdin',\n\t\t\t\t\t\t\t\t\toperation: 'untar',\n\t\t\t\t\t\t\t\t\tdetail: `write to tar stdin failed`,\n\t\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tsettle(Effect.void);\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t\tif (!ok) {\n\t\t\t\t\tstdin.once('drain', onDrain);\n\t\t\t\t}\n\t\t\t\t// Interrupt while parked on backpressure must remove the\n\t\t\t\t// drain listener so it can't resume an interrupted fiber.\n\t\t\t\treturn Effect.sync(() => {\n\t\t\t\t\tstdin.off('drain', onDrain);\n\t\t\t\t});\n\t\t\t});\n\n\t\t// Pump the source stream into tar's stdin. Each chunk is\n\t\t// validated before it is handed to the tar subprocess, so unsafe\n\t\t// archive paths are rejected at the extraction boundary even if a\n\t\t// caller skipped any earlier preflight validation.\n\t\tyield* Stream.runForEach(stream, (chunk) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst validationError = processTarValidationChunk(validationState, chunk);\n\t\t\t\tif (validationError !== null) {\n\t\t\t\t\treturn yield* Effect.fail(validationError);\n\t\t\t\t}\n\t\t\t\tyield* writeChunk(chunk);\n\t\t\t}),\n\t\t).pipe(\n\t\t\tEffect.catch((cause) =>\n\t\t\t\tcause instanceof HostTreeTarError\n\t\t\t\t\t? Effect.fail(cause)\n\t\t\t\t\t: Effect.fail(\n\t\t\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\t\t\tstage: 'stream-stdin',\n\t\t\t\t\t\t\t\toperation: 'untar',\n\t\t\t\t\t\t\t\tdetail: `source stream raised before EOF`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\n\t\tconst finalValidationError = finishTarValidation(validationState);\n\t\tif (finalValidationError !== null) {\n\t\t\treturn yield* Effect.fail(finalValidationError);\n\t\t}\n\n\t\t// Close stdin so tar sees EOF and exits.\n\t\tyield* Effect.sync(() => stdin.end());\n\n\t\t// Await exit; non-zero surfaces with stderr tail.\n\t\tconst status = yield* Effect.promise(() => awaitProcessExit(child as ManagedProcessChild));\n\t\tif (status.code !== 0 || status.signal !== null) {\n\t\t\treturn yield* Effect.fail(tarExitError('untar', status, stderrChunks));\n\t\t}\n\t}).pipe(Effect.withSpan('substrate.host-tree-tar.untar'));\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/substrate/runtime/host-tree-tar/index.ts"],"sourcesContent":["// host-tree-tar — stream a host filesystem subtree as a tar archive.\n//\n// Architecture §\"Substrate primitives roster\" (Open slot O21):\n// snapshot orchestrator hard-fails today on the `tarHostTree` /\n// `untarHostTree` stubs. This primitive fills the slot.\n//\n// Design:\n//   - Stream-based — `tarHostTree` returns a `Stream<Uint8Array>`;\n//     `untarHostTree` consumes one. The entire tree NEVER materialises\n//     in memory (snapshot trees can hold gigabytes of cache state).\n//   - Mode-preserving — the snapshot orchestrator carries 0o600 /\n//     0o700 mode bits on secret material (postgres keys, account\n//     keystores). System `tar -p` (extract) and `tar --no-recursion`\n//     (control) preserve them natively. We do NOT roll our own\n//     archive writer (a TypeScript-side reimplementation would have\n//     to track POSIX mode flags + extended attributes; system tar is\n//     correct by default).\n//   - Subprocess-based — spawn `tar` (BSD-tar on macOS, GNU-tar on\n//     Linux); both honour the flags used here (`-c` / `-x` / `-f -`).\n//     Exit code != 0 surfaces as `TarSpawnFailed`.\n//\n// Boundary:\n//   - Substrate-level: this is a generic filesystem primitive; no\n//     plugin names referenced.\n//   - The caller controls which subtrees are archived (snapshot\n//     orchestrator passes a list of relative paths under a parent\n//     dir). Permission preservation is unconditional.\n\nimport { spawn, type ChildProcess, type StdioOptions } from 'node:child_process';\n\nimport { Effect, Schema, Scope, Stream } from 'effect';\n\nimport {\n\tawaitProcessExit,\n\tdescribeProcessExitStatus,\n\ttype ManagedProcessChild,\n\ttype ManagedProcessExitStatus,\n} from '../process-supervisor.ts';\nimport {\n\tfinishTarReader,\n\tisSafeArchivePath,\n\tmakeTarReaderState,\n\tprocessTarChunk,\n\tskipEntry,\n\ttype TarEntry,\n\ttype TarEntryDirective,\n} from '../tar/reader.ts';\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\n/** Tagged failure during tar / untar. `stage` discriminates the\n *  precise step (spawn vs stream-read vs exit-code).\n *\n *  `cause` carries the underlying error verbatim; the cascade\n *  formatter walks it. */\nexport class HostTreeTarError extends Schema.TaggedErrorClass<HostTreeTarError>()(\n\t'HostTreeTarError',\n\t{\n\t\tstage: Schema.Literals([\n\t\t\t'spawn',\n\t\t\t'stream-stdout',\n\t\t\t'stream-stdin',\n\t\t\t'exit-code',\n\t\t\t'entry-validation',\n\t\t\t'no-subtrees',\n\t\t]),\n\t\toperation: Schema.Literals(['tar', 'untar']),\n\t\tdetail: Schema.String,\n\t\t/** Captured stderr from the `tar` subprocess (last ~4 KB). */\n\t\tstderrTail: Schema.optional(Schema.String),\n\t\texitCode: Schema.optional(Schema.Number),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n// ---------------------------------------------------------------------------\n// Tar one or more subtrees → Stream<Uint8Array>\n// ---------------------------------------------------------------------------\n\n/** Spec for `tarHostTree`.\n *\n *  - `parentDir`: directory the relative paths are anchored under.\n *    `tar -C <parentDir>` runs the archive with this as cwd, so the\n *    archive entries are stored relative to `parentDir`.\n *  - `relPaths`: subtree paths relative to `parentDir`. Empty list\n *    fails fast (`stage: 'no-subtrees'`) — the caller is responsible\n *    for the host-tree-included guard. */\nexport interface TarHostTreeSpec {\n\treadonly parentDir: string;\n\treadonly relPaths: ReadonlyArray<string>;\n}\n\nconst TAR_STDERR_TAIL_BYTES = 4096;\n\nconst collectStderrTail = (chunks: Array<Uint8Array>): string => {\n\tif (chunks.length === 0) return '';\n\tlet total = 0;\n\tfor (let i = chunks.length - 1; i >= 0; i--) {\n\t\ttotal += chunks[i]!.length;\n\t\tif (total >= TAR_STDERR_TAIL_BYTES) break;\n\t}\n\tconst bytes = Buffer.concat(chunks);\n\treturn bytes.subarray(Math.max(0, bytes.length - TAR_STDERR_TAIL_BYTES)).toString('utf8');\n};\n\nconst tarExitError = (\n\toperation: 'tar' | 'untar',\n\tstatus: ManagedProcessExitStatus,\n\tstderrChunks: Array<Uint8Array>,\n): HostTreeTarError =>\n\tnew HostTreeTarError({\n\t\tstage: 'exit-code',\n\t\toperation,\n\t\texitCode: status.code ?? -1,\n\t\tdetail: `'tar' exited with ${describeProcessExitStatus(status)}`,\n\t\tstderrTail: collectStderrTail(stderrChunks),\n\t});\n\n/** Spawn `tar` with a bounded stderr ring buffer and a SIGKILL-on-\n *  scope-close finalizer. Both `tarHostTree` and `untarHostTree` share\n *  this body verbatim — only the args, stdio direction (which pipe is\n *  the data channel), and the `operation` tag differ. The data pipe\n *  (`stdout` for tar, `stdin` for untar) is read off the returned\n *  `child` by the caller; stderr is always piped so the exit-code\n *  failure can carry the captured tail.\n *\n *  The stderr listener is removed and a live child is killed on scope\n *  close — the finalizer binds to the surrounding Scope (the stream's\n *  lifecycle for tar, the consuming Effect's for untar). */\nconst spawnTar = (\n\toperation: 'tar' | 'untar',\n\targs: ReadonlyArray<string>,\n\tstdio: StdioOptions,\n): Effect.Effect<\n\t{ readonly child: ChildProcess; readonly stderrChunks: Array<Uint8Array> },\n\tHostTreeTarError,\n\tScope.Scope\n> =>\n\tEffect.gen(function* () {\n\t\tconst child = yield* Effect.try({\n\t\t\ttry: () => spawn('tar', [...args], { stdio }),\n\t\t\tcatch: (cause) =>\n\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\tstage: 'spawn',\n\t\t\t\t\toperation,\n\t\t\t\t\tdetail: `failed to spawn 'tar ${args.join(' ')}'`,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t});\n\n\t\t// Stderr collection lives outside the data stream — we accumulate\n\t\t// the tail so an exit-code failure carries actionable context. The\n\t\t// stderr listener is removed on scope close.\n\t\tconst stderrChunks: Array<Uint8Array> = [];\n\t\tconst onStderr = (chunk: Buffer): void => {\n\t\t\tstderrChunks.push(chunk);\n\t\t\tif (stderrChunks.length > 256) stderrChunks.splice(0, stderrChunks.length - 256);\n\t\t};\n\t\tchild.stderr?.on('data', onStderr);\n\n\t\t// Finalise the subprocess on scope close: kill if alive, drop\n\t\t// listeners either way.\n\t\tyield* Effect.addFinalizer(() =>\n\t\t\tEffect.sync(() => {\n\t\t\t\tchild.stderr?.off('data', onStderr);\n\t\t\t\tif (child.exitCode === null && child.signalCode === null) {\n\t\t\t\t\tchild.kill('SIGKILL');\n\t\t\t\t}\n\t\t\t}),\n\t\t);\n\n\t\treturn { child, stderrChunks };\n\t});\n\nconst tarValidationError = (detail: string): HostTreeTarError =>\n\tnew HostTreeTarError({\n\t\tstage: 'entry-validation',\n\t\toperation: 'untar',\n\t\tdetail,\n\t});\n\n// Host-tree-specific validation layer on top of the shared tar reader.\n// The reader resolves entries (pax/gnu paths applied); this hook\n// rejects unsafe entry paths and unsafe hardlink/symlink targets, then\n// skips the body. The reader owns the block discipline and pax/gnu\n// parsing; the validator never reads file content.\nconst hostTreeValidationHooks = {\n\tonEntry: (entry: TarEntry): TarEntryDirective | HostTreeTarError => {\n\t\tif (!isSafeArchivePath(entry.path)) {\n\t\t\treturn tarValidationError(`unsafe tar entry path: ${entry.path}`);\n\t\t}\n\t\tif ((entry.typeflag === '1' || entry.typeflag === '2') && !isSafeArchivePath(entry.linkPath)) {\n\t\t\treturn tarValidationError(`unsafe tar link target: ${entry.linkPath}`);\n\t\t}\n\t\treturn skipEntry();\n\t},\n\tonExtendedError: (detail: string): HostTreeTarError =>\n\t\ttarValidationError(\n\t\t\tdetail === 'global pax path/linkpath records are not supported'\n\t\t\t\t? 'global pax path/linkpath records are not supported in snapshots'\n\t\t\t\t: detail,\n\t\t),\n} as const;\n\nexport const validateHostTreeTarEntries = <R>(\n\tstream: Stream.Stream<Uint8Array, HostTreeTarError, R>,\n): Effect.Effect<void, HostTreeTarError, R> =>\n\tEffect.gen(function* () {\n\t\tconst state = makeTarReaderState();\n\t\tyield* Stream.runForEach(stream, (chunk) => {\n\t\t\tconst error = processTarChunk(state, chunk, hostTreeValidationHooks);\n\t\t\treturn error === null ? Effect.void : Effect.fail(error);\n\t\t});\n\t\tconst finalError = finishTarReader(state, tarValidationError);\n\t\tif (finalError !== null) return yield* Effect.fail(finalError);\n\t});\n\n/**\n * Stream the tar archive of `relPaths` (relative to `parentDir`) as a\n * `Stream<Uint8Array>`. Mode bits are preserved.\n *\n * The subprocess is bound to the consuming Scope: closing the scope\n * before the stream finishes kills the subprocess and surfaces\n * `stream-stdout` if the consumer was mid-read.\n *\n * Caller consumes via `Stream.run(...)` — e.g. pipe to a file via\n * `Stream.run(stream, Sink.fromWritable(() => createWriteStream(...)))`\n * or to an in-memory chunk array for the integrity hash.\n */\nexport const tarHostTree = (\n\tspec: TarHostTreeSpec,\n): Stream.Stream<Uint8Array, HostTreeTarError, never> =>\n\t// `Stream.unwrap` provides the channel's surrounding scope to the\n\t// inner Effect (see `effect/src/Channel.ts:7918` —\n\t// `Scope.provide(scope)`), so `Effect.addFinalizer` below binds to\n\t// the stream's lifecycle: the subprocess kill-on-close fires when\n\t// the stream terminates. The R-channel `Exclude<R, Scope>` reads\n\t// \"scope satisfied by the stream\" — not \"scope dropped\".\n\tStream.unwrap(\n\t\tEffect.gen(function* () {\n\t\t\tif (spec.relPaths.length === 0) {\n\t\t\t\treturn Stream.fail(\n\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\tstage: 'no-subtrees',\n\t\t\t\t\t\toperation: 'tar',\n\t\t\t\t\t\tdetail: 'tarHostTree called with empty relPaths list',\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t// Producer-boundary path defense — mirror the extraction-side\n\t\t\t// `isSafeArchivePath`. The caller controls `relPaths`, and they\n\t\t\t// are spliced straight into `tar -C <parentDir> … relPaths`. An\n\t\t\t// absolute path or a `..` segment would archive a subtree\n\t\t\t// outside `parentDir` (and on extraction escape `target`). We\n\t\t\t// reject at the producer rather than relying on the consumer's\n\t\t\t// entry validation alone.\n\t\t\tconst unsafe = spec.relPaths.find((relPath) => !isSafeArchivePath(relPath));\n\t\t\tif (unsafe !== undefined) {\n\t\t\t\treturn Stream.fail(\n\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\tstage: 'entry-validation',\n\t\t\t\t\t\toperation: 'tar',\n\t\t\t\t\t\tdetail: `unsafe tar relPath (absolute or contains '..'): ${unsafe}`,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t// `-c` create, `-f -` write to stdout, `-C <dir>` cd-before,\n\t\t\t// `-p` preserve permissions (matches BSD-tar + GNU-tar). The\n\t\t\t// subprocess emits its own bytes; we don't apply any\n\t\t\t// transcoding.\n\t\t\tconst args = ['-c', '-f', '-', '-C', spec.parentDir, '-p', ...spec.relPaths];\n\t\t\tconst { child, stderrChunks } = yield* spawnTar('tar', args, ['ignore', 'pipe', 'pipe']);\n\n\t\t\t// Wrap stdout (a Node Readable) as a Stream<Uint8Array>.\n\t\t\t// `Stream.fromReadable` is the substrate-blessed shape.\n\t\t\tconst stdout = child.stdout;\n\t\t\tif (stdout === null) {\n\t\t\t\treturn Stream.fail(\n\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\tstage: 'spawn',\n\t\t\t\t\t\toperation: 'tar',\n\t\t\t\t\t\tdetail: `'tar' subprocess produced no stdout pipe`,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t// Node `Readable` is an `AsyncIterable<Buffer>`; `Buffer`\n\t\t\t// extends `Uint8Array` structurally. The cast asserts the\n\t\t\t// nominal-vs-structural gap at the Node boundary and stays\n\t\t\t// off the user-facing API.\n\t\t\tconst dataStream = Stream.fromAsyncIterable(\n\t\t\t\tstdout as unknown as AsyncIterable<Uint8Array>,\n\t\t\t\t(cause) =>\n\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\tstage: 'stream-stdout',\n\t\t\t\t\t\toperation: 'tar',\n\t\t\t\t\t\tdetail: `read from tar stdout failed`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t}),\n\t\t\t);\n\n\t\t\t// After stdout closes, await the subprocess exit and surface\n\t\t\t// non-zero codes with the captured stderr tail. This appends\n\t\t\t// a \"tail\" sub-stream that emits zero bytes but can fail —\n\t\t\t// the consumer's `Stream.run` sees the exit-code failure\n\t\t\t// uniformly with stream-read failures.\n\t\t\tconst exitGate: Stream.Stream<Uint8Array, HostTreeTarError, never> = Stream.fromEffect(\n\t\t\t\tEffect.promise(() => awaitProcessExit(child as ManagedProcessChild)).pipe(\n\t\t\t\t\tEffect.flatMap((status) =>\n\t\t\t\t\t\tstatus.code === 0 && status.signal === null\n\t\t\t\t\t\t\t? Effect.succeed(new Uint8Array(0))\n\t\t\t\t\t\t\t: Effect.fail(tarExitError('tar', status, stderrChunks)),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t).pipe(Stream.filter((bytes) => bytes.length > 0));\n\n\t\t\treturn Stream.concat(dataStream, exitGate);\n\t\t}),\n\t);\n\n// ---------------------------------------------------------------------------\n// Untar a Stream<Uint8Array> into a target directory\n// ---------------------------------------------------------------------------\n\nexport interface UntarHostTreeSpec {\n\treadonly target: string;\n}\n\n/**\n * Extract a tar `Stream<Uint8Array>` into `target`, preserving mode\n * bits. The target directory MUST already exist; the caller is\n * responsible (stage-and-swap creates the staging directory before\n * calling).\n *\n * The subprocess consumes from the stream and writes into `target`;\n * scope close kills the subprocess. The Effect resolves when `tar`\n * exits cleanly (code 0).\n */\nexport const untarHostTree = <R>(\n\tstream: Stream.Stream<Uint8Array, HostTreeTarError, R>,\n\tspec: UntarHostTreeSpec,\n): Effect.Effect<void, HostTreeTarError, R | Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst args = ['-x', '-f', '-', '-C', spec.target, '-p'];\n\t\tconst { child, stderrChunks } = yield* spawnTar('untar', args, ['pipe', 'ignore', 'pipe']);\n\n\t\tconst stdin = child.stdin;\n\t\tif (stdin === null) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\tstage: 'spawn',\n\t\t\t\t\toperation: 'untar',\n\t\t\t\t\tdetail: `'tar' subprocess produced no stdin pipe`,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\n\t\tconst validationState = makeTarReaderState();\n\n\t\tconst writeChunk = (chunk: Uint8Array): Effect.Effect<void, HostTreeTarError> =>\n\t\t\tEffect.callback<void, HostTreeTarError>((resume) => {\n\t\t\t\tlet settled = false;\n\t\t\t\tconst settle = (effect: Effect.Effect<void, HostTreeTarError>): void => {\n\t\t\t\t\tif (!settled) {\n\t\t\t\t\t\tsettled = true;\n\t\t\t\t\t\tresume(effect);\n\t\t\t\t\t}\n\t\t\t\t};\n\t\t\t\tconst onDrain = (): void => settle(Effect.void);\n\t\t\t\tconst ok = stdin.write(chunk, (cause) => {\n\t\t\t\t\tstdin.off('drain', onDrain);\n\t\t\t\t\tif (cause) {\n\t\t\t\t\t\tsettle(\n\t\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\t\t\t\tstage: 'stream-stdin',\n\t\t\t\t\t\t\t\t\toperation: 'untar',\n\t\t\t\t\t\t\t\t\tdetail: `write to tar stdin failed`,\n\t\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tsettle(Effect.void);\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t\tif (!ok) {\n\t\t\t\t\tstdin.once('drain', onDrain);\n\t\t\t\t}\n\t\t\t\t// Interrupt while parked on backpressure must remove the\n\t\t\t\t// drain listener so it can't resume an interrupted fiber.\n\t\t\t\treturn Effect.sync(() => {\n\t\t\t\t\tstdin.off('drain', onDrain);\n\t\t\t\t});\n\t\t\t});\n\n\t\t// Pump the source stream into tar's stdin. Each chunk is\n\t\t// validated before it is handed to the tar subprocess, so unsafe\n\t\t// archive paths are rejected at the extraction boundary even if a\n\t\t// caller skipped any earlier preflight validation.\n\t\tyield* Stream.runForEach(stream, (chunk) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst validationError = processTarChunk(validationState, chunk, hostTreeValidationHooks);\n\t\t\t\tif (validationError !== null) {\n\t\t\t\t\treturn yield* Effect.fail(validationError);\n\t\t\t\t}\n\t\t\t\tyield* writeChunk(chunk);\n\t\t\t}),\n\t\t).pipe(\n\t\t\tEffect.catch((cause) =>\n\t\t\t\tcause instanceof HostTreeTarError\n\t\t\t\t\t? Effect.fail(cause)\n\t\t\t\t\t: Effect.fail(\n\t\t\t\t\t\t\tnew HostTreeTarError({\n\t\t\t\t\t\t\t\tstage: 'stream-stdin',\n\t\t\t\t\t\t\t\toperation: 'untar',\n\t\t\t\t\t\t\t\tdetail: `source stream raised before EOF`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\n\t\tconst finalValidationError = finishTarReader(validationState, tarValidationError);\n\t\tif (finalValidationError !== null) {\n\t\t\treturn yield* Effect.fail(finalValidationError);\n\t\t}\n\n\t\t// Close stdin so tar sees EOF and exits.\n\t\tyield* Effect.sync(() => stdin.end());\n\n\t\t// Await exit; non-zero surfaces with stderr tail.\n\t\tconst status = yield* Effect.promise(() => awaitProcessExit(child as ManagedProcessChild));\n\t\tif (status.code !== 0 || status.signal !== null) {\n\t\t\treturn yield* Effect.fail(tarExitError('untar', status, stderrChunks));\n\t\t}\n\t});\n"],"mappings":"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"}

package/dist/substrate/runtime/http-probe.d.mts

@@ -1,6 +1,4 @@
 import { Effect } from "effect";
-import * as _$effect_Cause0 from "effect/Cause";
-import * as _$effect_Types0 from "effect/Types";
 
 //#region src/substrate/runtime/http-probe.d.ts
 declare namespace http_probe_d_exports {
@@ -17,7 +15,7 @@ interface HttpProbeOptions {
   readonly validate?: HttpProbeValidator;
   readonly fetch?: HttpProbeFetch;
 }
-declare const HttpProbeError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+declare const HttpProbeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "HttpProbeError";
 } & Readonly<A>;
 declare class HttpProbeError extends HttpProbeError_base<{

package/dist/substrate/runtime/http-probe.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"http-probe.mjs","names":[],"sources":["../../../src/substrate/runtime/http-probe.ts"],"sourcesContent":["import { Data, Effect } from 'effect';\n\nimport { ProbeTimeoutError, waitForProbe } from './probes.ts';\n\nexport type HttpProbeFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;\n\nexport type HttpProbeValidator = (response: Response) => boolean | Promise<boolean>;\n\nexport interface HttpProbeOptions {\n\treadonly endpoint: string | URL;\n\treadonly timeoutMs: number;\n\treadonly intervalMs?: number;\n\treadonly requestTimeoutMs?: number;\n\treadonly requestInit?: Omit<RequestInit, 'signal'>;\n\treadonly validate?: HttpProbeValidator;\n\treadonly fetch?: HttpProbeFetch;\n}\n\nexport class HttpProbeError extends Data.TaggedError('HttpProbeError')<{\n\treadonly endpoint: string;\n\treadonly timeoutMs: number;\n\treadonly intervalMs: number;\n\treadonly requestTimeoutMs: number;\n\treadonly message: string;\n\treadonly lastStatus?: number;\n\treadonly lastError?: unknown;\n}> {}\n\nconst DEFAULT_INTERVAL_MS = 250;\n\nexport const waitForHttpEndpoint = (\n\toptions: HttpProbeOptions,\n): Effect.Effect<void, HttpProbeError> =>\n\tEffect.gen(function* () {\n\t\tconst endpoint = String(options.endpoint);\n\t\tconst timeoutMs = options.timeoutMs;\n\t\tconst intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;\n\t\tconst requestTimeoutMs = options.requestTimeoutMs ?? intervalMs;\n\t\tconst validate = options.validate ?? ((response: Response) => response.ok);\n\t\tconst fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);\n\t\tlet lastStatus: number | undefined;\n\n\t\treturn yield* waitForProbe({\n\t\t\tlabel: endpoint,\n\t\t\ttimeoutMs,\n\t\t\tintervalMs,\n\t\t\tattemptTimeoutMs: requestTimeoutMs,\n\t\t\tprobe: () =>\n\t\t\t\tEffect.tryPromise({\n\t\t\t\t\ttry: (signal) =>\n\t\t\t\t\t\tfetchImpl(options.endpoint, {\n\t\t\t\t\t\t\tmethod: 'GET',\n\t\t\t\t\t\t\t...options.requestInit,\n\t\t\t\t\t\t\tsignal,\n\t\t\t\t\t\t}),\n\t\t\t\t\tcatch: (cause) => cause,\n\t\t\t\t}).pipe(\n\t\t\t\t\tEffect.flatMap((response) => {\n\t\t\t\t\t\tlastStatus = response.status;\n\t\t\t\t\t\treturn Effect.tryPromise({\n\t\t\t\t\t\t\ttry: () => Promise.resolve(validate(response)),\n\t\t\t\t\t\t\tcatch: (cause) => cause,\n\t\t\t\t\t\t}).pipe(\n\t\t\t\t\t\t\tEffect.map((ready) =>\n\t\t\t\t\t\t\t\tready ? true : { ready: false, detail: { status: response.status } },\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t}).pipe(\n\t\t\tEffect.mapError((cause) => {\n\t\t\t\tif (cause instanceof ProbeTimeoutError) {\n\t\t\t\t\treturn new HttpProbeError({\n\t\t\t\t\t\tendpoint,\n\t\t\t\t\t\ttimeoutMs,\n\t\t\t\t\t\tintervalMs,\n\t\t\t\t\t\trequestTimeoutMs,\n\t\t\t\t\t\tmessage: `HTTP endpoint ${endpoint} did not become ready within ${timeoutMs}ms`,\n\t\t\t\t\t\t...(lastStatus === undefined ? {} : { lastStatus }),\n\t\t\t\t\t\t...(cause.lastError === undefined ? {} : { lastError: cause.lastError }),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\treturn new HttpProbeError({\n\t\t\t\t\tendpoint,\n\t\t\t\t\ttimeoutMs,\n\t\t\t\t\tintervalMs,\n\t\t\t\t\trequestTimeoutMs,\n\t\t\t\t\tmessage: `HTTP endpoint ${endpoint} probe failed`,\n\t\t\t\t\t...(lastStatus === undefined ? {} : { lastStatus }),\n\t\t\t\t\tlastError: cause,\n\t\t\t\t});\n\t\t\t}),\n\t\t);\n\t});\n"],"mappings":";;;;;;;;AAkBA,IAAa,iBAAb,cAAoC,KAAK,YAAY,iBAAiB,CAQnE;AAEH,MAAM,sBAAsB;AAE5B,MAAa,uBACZ,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,QAAQ,SAAS;CACzC,MAAM,YAAY,QAAQ;CAC1B,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,mBAAmB,QAAQ,oBAAoB;CACrD,MAAM,WAAW,QAAQ,cAAc,aAAuB,SAAS;CACvE,MAAM,YAAY,QAAQ,SAAS,WAAW,MAAM,KAAK,WAAW;CACpE,IAAI;AAEJ,QAAO,OAAO,aAAa;EAC1B,OAAO;EACP;EACA;EACA,kBAAkB;EAClB,aACC,OAAO,WAAW;GACjB,MAAM,WACL,UAAU,QAAQ,UAAU;IAC3B,QAAQ;IACR,GAAG,QAAQ;IACX;IACA,CAAC;GACH,QAAQ,UAAU;GAClB,CAAC,CAAC,KACF,OAAO,SAAS,aAAa;AAC5B,gBAAa,SAAS;AACtB,UAAO,OAAO,WAAW;IACxB,WAAW,QAAQ,QAAQ,SAAS,SAAS,CAAC;IAC9C,QAAQ,UAAU;IAClB,CAAC,CAAC,KACF,OAAO,KAAK,UACX,QAAQ,OAAO;IAAE,OAAO;IAAO,QAAQ,EAAE,QAAQ,SAAS,QAAQ;IAAE,CACpE,CACD;IACA,CACF;EACF,CAAC,CAAC,KACF,OAAO,UAAU,UAAU;AAC1B,MAAI,iBAAiB,kBACpB,QAAO,IAAI,eAAe;GACzB;GACA;GACA;GACA;GACA,SAAS,iBAAiB,SAAS,+BAA+B,UAAU;GAC5E,GAAI,eAAe,KAAA,IAAY,EAAE,GAAG,EAAE,YAAY;GAClD,GAAI,MAAM,cAAc,KAAA,IAAY,EAAE,GAAG,EAAE,WAAW,MAAM,WAAW;GACvE,CAAC;AAEH,SAAO,IAAI,eAAe;GACzB;GACA;GACA;GACA;GACA,SAAS,iBAAiB,SAAS;GACnC,GAAI,eAAe,KAAA,IAAY,EAAE,GAAG,EAAE,YAAY;GAClD,WAAW;GACX,CAAC;GACD,CACF;EACA"}
+{"version":3,"file":"http-probe.mjs","names":[],"sources":["../../../src/substrate/runtime/http-probe.ts"],"sourcesContent":["import { Data, Effect } from 'effect';\n\nimport { ProbeTimeoutError, waitForProbe } from './probes.ts';\n\nexport type HttpProbeFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;\n\nexport type HttpProbeValidator = (response: Response) => boolean | Promise<boolean>;\n\nexport interface HttpProbeOptions {\n\treadonly endpoint: string | URL;\n\treadonly timeoutMs: number;\n\treadonly intervalMs?: number;\n\treadonly requestTimeoutMs?: number;\n\treadonly requestInit?: Omit<RequestInit, 'signal'>;\n\treadonly validate?: HttpProbeValidator;\n\treadonly fetch?: HttpProbeFetch;\n}\n\nexport class HttpProbeError extends Data.TaggedError('HttpProbeError')<{\n\treadonly endpoint: string;\n\treadonly timeoutMs: number;\n\treadonly intervalMs: number;\n\treadonly requestTimeoutMs: number;\n\treadonly message: string;\n\treadonly lastStatus?: number;\n\treadonly lastError?: unknown;\n}> {}\n\nconst DEFAULT_INTERVAL_MS = 250;\n\nexport const waitForHttpEndpoint = (\n\toptions: HttpProbeOptions,\n): Effect.Effect<void, HttpProbeError> =>\n\tEffect.gen(function* () {\n\t\tconst endpoint = String(options.endpoint);\n\t\tconst timeoutMs = options.timeoutMs;\n\t\tconst intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;\n\t\tconst requestTimeoutMs = options.requestTimeoutMs ?? intervalMs;\n\t\tconst validate = options.validate ?? ((response: Response) => response.ok);\n\t\tconst fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);\n\t\tlet lastStatus: number | undefined;\n\n\t\treturn yield* waitForProbe({\n\t\t\tlabel: endpoint,\n\t\t\ttimeoutMs,\n\t\t\tintervalMs,\n\t\t\tattemptTimeoutMs: requestTimeoutMs,\n\t\t\tprobe: () =>\n\t\t\t\tEffect.tryPromise({\n\t\t\t\t\ttry: (signal) =>\n\t\t\t\t\t\tfetchImpl(options.endpoint, {\n\t\t\t\t\t\t\tmethod: 'GET',\n\t\t\t\t\t\t\t...options.requestInit,\n\t\t\t\t\t\t\tsignal,\n\t\t\t\t\t\t}),\n\t\t\t\t\tcatch: (cause) => cause,\n\t\t\t\t}).pipe(\n\t\t\t\t\tEffect.flatMap((response) => {\n\t\t\t\t\t\tlastStatus = response.status;\n\t\t\t\t\t\treturn Effect.tryPromise({\n\t\t\t\t\t\t\ttry: () => Promise.resolve(validate(response)),\n\t\t\t\t\t\t\tcatch: (cause) => cause,\n\t\t\t\t\t\t}).pipe(\n\t\t\t\t\t\t\tEffect.map((ready) =>\n\t\t\t\t\t\t\t\tready ? true : { ready: false, detail: { status: response.status } },\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t}).pipe(\n\t\t\tEffect.mapError((cause) => {\n\t\t\t\tif (cause instanceof ProbeTimeoutError) {\n\t\t\t\t\treturn new HttpProbeError({\n\t\t\t\t\t\tendpoint,\n\t\t\t\t\t\ttimeoutMs,\n\t\t\t\t\t\tintervalMs,\n\t\t\t\t\t\trequestTimeoutMs,\n\t\t\t\t\t\tmessage: `HTTP endpoint ${endpoint} did not become ready within ${timeoutMs}ms`,\n\t\t\t\t\t\t...(lastStatus === undefined ? {} : { lastStatus }),\n\t\t\t\t\t\t...(cause.lastError === undefined ? {} : { lastError: cause.lastError }),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\treturn new HttpProbeError({\n\t\t\t\t\tendpoint,\n\t\t\t\t\ttimeoutMs,\n\t\t\t\t\tintervalMs,\n\t\t\t\t\trequestTimeoutMs,\n\t\t\t\t\tmessage: `HTTP endpoint ${endpoint} probe failed`,\n\t\t\t\t\t...(lastStatus === undefined ? {} : { lastStatus }),\n\t\t\t\t\tlastError: cause,\n\t\t\t\t});\n\t\t\t}),\n\t\t);\n\t});\n"],"mappings":";;;;;;;;AAkBA,IAAa,iBAAb,cAAoC,KAAK,YAAY,gBAAgB,CAAC,CAQnE,CAAC;AAEJ,MAAM,sBAAsB;AAE5B,MAAa,uBACZ,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,QAAQ,QAAQ;CACxC,MAAM,YAAY,QAAQ;CAC1B,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,mBAAmB,QAAQ,oBAAoB;CACrD,MAAM,WAAW,QAAQ,cAAc,aAAuB,SAAS;CACvE,MAAM,YAAY,QAAQ,SAAS,WAAW,MAAM,KAAK,UAAU;CACnE,IAAI;CAEJ,OAAO,OAAO,aAAa;EAC1B,OAAO;EACP;EACA;EACA,kBAAkB;EAClB,aACC,OAAO,WAAW;GACjB,MAAM,WACL,UAAU,QAAQ,UAAU;IAC3B,QAAQ;IACR,GAAG,QAAQ;IACX;GACD,CAAC;GACF,QAAQ,UAAU;EACnB,CAAC,CAAC,CAAC,KACF,OAAO,SAAS,aAAa;GAC5B,aAAa,SAAS;GACtB,OAAO,OAAO,WAAW;IACxB,WAAW,QAAQ,QAAQ,SAAS,QAAQ,CAAC;IAC7C,QAAQ,UAAU;GACnB,CAAC,CAAC,CAAC,KACF,OAAO,KAAK,UACX,QAAQ,OAAO;IAAE,OAAO;IAAO,QAAQ,EAAE,QAAQ,SAAS,OAAO;GAAE,CACpE,CACD;EACD,CAAC,CACF;CACF,CAAC,CAAC,CAAC,KACF,OAAO,UAAU,UAAU;EAC1B,IAAI,iBAAiB,mBACpB,OAAO,IAAI,eAAe;GACzB;GACA;GACA;GACA;GACA,SAAS,iBAAiB,SAAS,+BAA+B,UAAU;GAC5E,GAAI,eAAe,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW;GACjD,GAAI,MAAM,cAAc,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW,MAAM,UAAU;EACvE,CAAC;EAEF,OAAO,IAAI,eAAe;GACzB;GACA;GACA;GACA;GACA,SAAS,iBAAiB,SAAS;GACnC,GAAI,eAAe,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW;GACjD,WAAW;EACZ,CAAC;CACF,CAAC,CACF;AACD,CAAC"}

package/dist/substrate/runtime/index.mjs

@@ -1,14 +1,9 @@
-import "./capability-sinks/service.mjs";
-import "./observability/formatter-registry.mjs";
-import "./capability-sinks/layer.mjs";
-import "./capability-sinks/index.mjs";
 import "./projection/state-ref.mjs";
-import "./projection/persisted.mjs";
 import "./cross-process/command-channel/channel.mjs";
 import "./cross-process/command-channel/index.mjs";
 import "./cross-process/roster.mjs";
+import "./supervisor/contribution-dispatcher.mjs";
 import "./observability/logger.mjs";
-import "./observability/index.mjs";
 import "./supervisor/start-supervisor.mjs";
 import "./supervisor/index.mjs";
 export {};

package/dist/substrate/runtime/lease-broker/service.mjs

@@ -80,7 +80,7 @@ const layerLeaseBroker = Layer.effect(LeaseBrokerService, Effect.gen(function* (
 			owner,
 			signal
 		};
-		const becameHolder = yield* Ref.modify(state, (current) => {
+		if (!(yield* Ref.modify(state, (current) => {
 			const entry = current.get(key);
 			if (!entry) {
 				const next = new Map(current);
@@ -96,19 +96,13 @@ const layerLeaseBroker = Layer.effect(LeaseBrokerService, Effect.gen(function* (
 				waiters: [...entry.waiters, waiter]
 			});
 			return [false, next];
-		});
-		if (!becameHolder) yield* restore(Deferred.await(signal)).pipe(Effect.onInterrupt(() => cleanupCancelledWait(key, waiter).pipe(Effect.uninterruptible)));
+		}))) yield* restore(Deferred.await(signal)).pipe(Effect.onInterrupt(() => cleanupCancelledWait(key, waiter).pipe(Effect.uninterruptible)));
 		yield* installReleaseFinalizer(key);
-		yield* Effect.annotateCurrentSpan({
-			"leaseBroker.key": key,
-			"leaseBroker.owner": owner,
-			"leaseBroker.contended": !becameHolder
-		});
 		return {
 			key,
 			owner
 		};
-	})).pipe(Effect.withSpan("substrate.leaseBroker.acquire"));
+	}));
 	const tryAcquire = (key, owner) => Effect.gen(function* () {
 		if (!(yield* Ref.modify(state, (current) => {
 			if (current.has(key)) return [false, current];
@@ -118,25 +112,13 @@ const layerLeaseBroker = Layer.effect(LeaseBrokerService, Effect.gen(function* (
 				waiters: []
 			});
 			return [true, next];
-		}))) {
-			yield* Effect.annotateCurrentSpan({
-				"leaseBroker.key": key,
-				"leaseBroker.owner": owner,
-				"leaseBroker.claimed": false
-			});
-			return null;
-		}
+		}))) return null;
 		yield* installReleaseFinalizer(key);
-		yield* Effect.annotateCurrentSpan({
-			"leaseBroker.key": key,
-			"leaseBroker.owner": owner,
-			"leaseBroker.claimed": true
-		});
 		return {
 			key,
 			owner
 		};
-	}).pipe(Effect.uninterruptible, Effect.withSpan("substrate.leaseBroker.tryAcquire"));
+	}).pipe(Effect.uninterruptible);
 	const holders = () => Effect.gen(function* () {
 		const current = yield* Ref.get(state);
 		const out = /* @__PURE__ */ new Map();

package/dist/substrate/runtime/lease-broker/service.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"service.mjs","names":[],"sources":["../../../../src/substrate/runtime/lease-broker/service.ts"],"sourcesContent":["// Lease broker — substrate-level service interface.\n//\n// Architecture (`notes/redesign/architecture.md` § \"L0 substrate\n// primitives\"): the substrate owns a generic lease primitive keyed by\n// an opaque resource identifier. Any caller that needs at-most-one-\n// in-flight serialization on a resource yields this service and calls\n// `acquire(key, owner)`. The first canonical consumer is the per-\n// address sequence-number lock (`plugins/account/address-lock.ts`,\n// today plugin-local; PR3 lifts it to consume this primitive);\n// callers in the same shape — sign+execute pipelines, per-connection\n// gate, per-slot work queue — share the same seam.\n//\n// Substrate name-blindness: the broker has no concept of what a\n// `LeaseKey` represents. The plugin author chooses the key shape; the\n// broker treats it as an opaque string with a brand. A wallet might\n// key by `account:<address>`, a GPU-bound plugin by `gpu:<slot>` —\n// the broker doesn't care.\n//\n// Lifetime: scope-bound. `acquire` returns a `Lease` handle whose\n// release fires when the surrounding `Effect.Scope` closes. There is\n// no `release()` method on `Lease` — the only release path is the\n// scope finalizer, which makes \"I forgot to release\" structurally\n// impossible.\n//\n// Mechanics: per-key state in a single `Ref<State>`. The blocking\n// queue is a FIFO of `Waiter`s carrying a `Deferred` that the\n// outgoing holder's finalizer resolves AFTER atomically installing\n// the next holder. `tryAcquire` does the same atomic-claim CAS as\n// `acquire`'s first step, but skips the wait — returning `null` if\n// the key is held.\n\nimport { Context, Deferred, Effect, Layer, Ref, Scope } from 'effect';\n\nimport type { Brand } from '../../brand.ts';\n\n// ----------------------------------------------------------------------\n// Public shape\n// ----------------------------------------------------------------------\n\n/** Opaque resource identifier. Substrate-blind: the broker treats\n *  this as a string for map keying and never inspects it. Plugin\n *  authors choose the encoding (`account:<addr>`, `gpu:<slot>`, etc.). */\nexport type LeaseKey = Brand<string, 'LeaseKey'>;\n\n/** Construct a `LeaseKey` from a free-form string. The boundary at\n *  which unbranded strings become branded; downstream code only sees\n *  branded values. */\nexport const leaseKey = (s: string): LeaseKey => s as LeaseKey;\n\n/** Free-form owner identity, used for diagnostics (`holders()` output,\n *  span attributes). The broker does NOT use this for re-entrancy:\n *  two `acquire` calls from the same owner against the same key will\n *  deadlock the second call. */\nexport type Owner = string;\n\n/** Lease handle. Carries only the diagnostic pair; the release is the\n *  scope finalizer, not a method.\n *\n *  Why no `release()`: every consumer we have today wraps the lease\n *  in `Effect.scoped` and lets the scope finalizer fire. Exposing an\n *  explicit `release()` would invite double-release, release-while-\n *  scope-still-open, and the \"I released early but forgot to clear\n *  the variable\" footgun. The scope IS the lifetime. */\nexport interface Lease {\n\treadonly key: LeaseKey;\n\treadonly owner: Owner;\n}\n\n/** Service shape — what plugins yield from Context. */\nexport interface LeaseBroker {\n\t/**\n\t * Acquire the lease for `key`, attributed to `owner`. Blocks if the\n\t * lease is already held, waiting in FIFO order behind earlier\n\t * waiters. Cancellable: an interrupt while waiting unwinds without\n\t * acquiring.\n\t *\n\t * Scope-bound release: the broker installs an uninterruptible\n\t * finalizer on the surrounding scope. Calling `Effect.scoped` over\n\t * an `acquire(...)` is the canonical shape.\n\t *\n\t * Non-reentrant: `acquire` from the same owner against a key the\n\t * owner already holds will deadlock. Per-address sequence-number\n\t * semantics require at-most-one in-flight; nesting is the caller's\n\t * bug.\n\t */\n\treadonly acquire: (key: LeaseKey, owner: Owner) => Effect.Effect<Lease, never, Scope.Scope>;\n\n\t/**\n\t * Non-blocking variant. Returns `null` if the lease is held by any\n\t * owner (including the calling owner); otherwise atomically claims\n\t * the lease and returns the handle. The atomic-claim CAS is the\n\t * same as `acquire`'s first step — the only difference is the\n\t * `null` return vs. enqueue.\n\t *\n\t * Scope-bound release: same finalizer install as `acquire` when\n\t * the claim wins.\n\t */\n\treadonly tryAcquire: (\n\t\tkey: LeaseKey,\n\t\towner: Owner,\n\t) => Effect.Effect<Lease | null, never, Scope.Scope>;\n\n\t/**\n\t * Snapshot of current holders, keyed by `LeaseKey`. For diagnostics\n\t * (renderer, debug logs); the result is a point-in-time read and\n\t * may be stale by the time it's inspected.\n\t */\n\treadonly holders: () => Effect.Effect<ReadonlyMap<LeaseKey, Owner>>;\n}\n\n// ----------------------------------------------------------------------\n// Internal state\n// ----------------------------------------------------------------------\n\n/** A fiber parked on `Deferred.await` waiting to become the next\n *  holder. The outgoing holder's finalizer transfers ownership by\n *  setting `holder = waiter.owner` on the per-key entry AND resolving\n *  the deferred — the awoken waiter doesn't re-CAS.\n *\n *  `Waiter` reference identity is the cancellation key: an interrupted\n *  waiter removes itself by reference-equality. */\ninterface Waiter {\n\treadonly owner: Owner;\n\treadonly signal: Deferred.Deferred<void>;\n}\n\ninterface KeyEntry {\n\treadonly holder: Owner;\n\treadonly waiters: ReadonlyArray<Waiter>;\n}\n\ntype State = ReadonlyMap<LeaseKey, KeyEntry>;\n\n// ----------------------------------------------------------------------\n// Service tag + Layer\n// ----------------------------------------------------------------------\n\nexport class LeaseBrokerService extends Context.Service<LeaseBrokerService, LeaseBroker>()(\n\t'@devstack/substrate/LeaseBroker',\n) {}\n\n/**\n * In-process Layer. One broker per stack scope; closing the layer's\n * scope drops every entry. Parallel stacks each get their own broker\n * — the broker is name-blind, so cross-stack coordination on the\n * same logical key (e.g. an address that two stacks share) is NOT\n * provided here. A cross-process layer can be slotted in later as a\n * sibling factory; today's consumers are in-process only.\n */\nexport const layerLeaseBroker: Layer.Layer<LeaseBrokerService> = Layer.effect(\n\tLeaseBrokerService,\n\tEffect.gen(function* () {\n\t\tconst state = yield* Ref.make<State>(new Map());\n\n\t\t/** Atomic finalizer body: clear `key`'s holder slot and, if any\n\t\t *  waiter is queued, promote the head waiter to holder. Returns\n\t\t *  the promoted waiter (so the caller can resolve their signal)\n\t\t *  or `null` when the key is fully released. Uninterruptible by\n\t\t *  construction — invoked from inside `Effect.addFinalizer` which\n\t\t *  the runtime wraps uninterruptibly. */\n\t\tconst releaseAndPromote = (key: LeaseKey): Effect.Effect<Waiter | null> =>\n\t\t\tRef.modify<State, Waiter | null>(state, (current) => {\n\t\t\t\tconst entry = current.get(key);\n\t\t\t\tif (!entry) return [null, current];\n\t\t\t\tconst head = entry.waiters[0];\n\t\t\t\tif (head === undefined) {\n\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\tnext.delete(key);\n\t\t\t\t\treturn [null, next];\n\t\t\t\t}\n\t\t\t\tconst rest = entry.waiters.slice(1);\n\t\t\t\tconst next = new Map(current);\n\t\t\t\tnext.set(key, { holder: head.owner, waiters: rest });\n\t\t\t\treturn [head, next];\n\t\t\t});\n\n\t\t/** Remove `waiter` from `key`'s waiter list. Called when an\n\t\t *  enqueued waiter is interrupted while parked on its signal. */\n\t\tconst removeWaiterIfQueued = (key: LeaseKey, waiter: Waiter): Effect.Effect<void> =>\n\t\t\tRef.update(state, (current) => {\n\t\t\t\tconst entry = current.get(key);\n\t\t\t\tif (!entry) return current;\n\t\t\t\tconst filtered = entry.waiters.filter((w) => w !== waiter);\n\t\t\t\tif (filtered.length === entry.waiters.length) return current;\n\t\t\t\tconst next = new Map(current);\n\t\t\t\tnext.set(key, { holder: entry.holder, waiters: filtered });\n\t\t\t\treturn next;\n\t\t\t});\n\n\t\t/** Cleanup on cancellation of a waiting `acquire`: if we were\n\t\t *  still queued, drop ourselves; if we were already promoted to\n\t\t *  holder by a release that raced with our interrupt, release on\n\t\t *  our behalf so the lease doesn't leak. */\n\t\tconst cleanupCancelledWait = (key: LeaseKey, waiter: Waiter): Effect.Effect<void> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst becameHolder = yield* Ref.modify<State, boolean>(state, (current) => {\n\t\t\t\t\tconst entry = current.get(key);\n\t\t\t\t\tif (!entry) return [false, current];\n\t\t\t\t\tif (entry.holder === waiter.owner && entry.waiters.indexOf(waiter) === -1) {\n\t\t\t\t\t\t// Promoted-but-not-awaited: we were handed the lease\n\t\t\t\t\t\t// in releaseAndPromote but interrupted before the\n\t\t\t\t\t\t// `Deferred.await` returned. Take responsibility for\n\t\t\t\t\t\t// releasing it.\n\t\t\t\t\t\treturn [true, current];\n\t\t\t\t\t}\n\t\t\t\t\treturn [false, current];\n\t\t\t\t});\n\t\t\t\tif (becameHolder) {\n\t\t\t\t\tconst promoted = yield* releaseAndPromote(key);\n\t\t\t\t\tif (promoted !== null) {\n\t\t\t\t\t\tyield* Deferred.succeed(promoted.signal, undefined);\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tyield* removeWaiterIfQueued(key, waiter);\n\t\t\t\t}\n\t\t\t});\n\n\t\t/** Install the scope-bound release finalizer. Uninterruptible —\n\t\t *  losing the release on a Ctrl-C double-tap would leak the\n\t\t *  lease and stall everything queued behind it. */\n\t\tconst installReleaseFinalizer = (key: LeaseKey): Effect.Effect<void, never, Scope.Scope> =>\n\t\t\tEffect.addFinalizer(() =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst promoted = yield* releaseAndPromote(key);\n\t\t\t\t\tif (promoted !== null) {\n\t\t\t\t\t\tyield* Deferred.succeed(promoted.signal, undefined);\n\t\t\t\t\t}\n\t\t\t\t}).pipe(Effect.uninterruptible),\n\t\t\t);\n\n\t\tconst acquire: LeaseBroker['acquire'] = (key, owner) =>\n\t\t\tEffect.uninterruptibleMask((restore) =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst signal = yield* Deferred.make<void>();\n\t\t\t\t\tconst waiter: Waiter = { owner, signal };\n\n\t\t\t\t\tconst becameHolder = yield* Ref.modify<State, boolean>(state, (current) => {\n\t\t\t\t\t\tconst entry = current.get(key);\n\t\t\t\t\t\tif (!entry) {\n\t\t\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\t\t\tnext.set(key, { holder: owner, waiters: [] });\n\t\t\t\t\t\t\treturn [true, next];\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\t\tnext.set(key, {\n\t\t\t\t\t\t\tholder: entry.holder,\n\t\t\t\t\t\t\twaiters: [...entry.waiters, waiter],\n\t\t\t\t\t\t});\n\t\t\t\t\t\treturn [false, next];\n\t\t\t\t\t});\n\n\t\t\t\t\tif (!becameHolder) {\n\t\t\t\t\t\tyield* restore(Deferred.await(signal)).pipe(\n\t\t\t\t\t\t\tEffect.onInterrupt(() =>\n\t\t\t\t\t\t\t\tcleanupCancelledWait(key, waiter).pipe(Effect.uninterruptible),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\n\t\t\t\t\tyield* installReleaseFinalizer(key);\n\t\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t\t'leaseBroker.key': key,\n\t\t\t\t\t\t'leaseBroker.owner': owner,\n\t\t\t\t\t\t'leaseBroker.contended': !becameHolder,\n\t\t\t\t\t});\n\t\t\t\t\treturn { key, owner } satisfies Lease;\n\t\t\t\t}),\n\t\t\t).pipe(Effect.withSpan('substrate.leaseBroker.acquire'));\n\n\t\tconst tryAcquire: LeaseBroker['tryAcquire'] = (key, owner) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst claimed = yield* Ref.modify<State, boolean>(state, (current) => {\n\t\t\t\t\tif (current.has(key)) return [false, current];\n\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\tnext.set(key, { holder: owner, waiters: [] });\n\t\t\t\t\treturn [true, next];\n\t\t\t\t});\n\t\t\t\tif (!claimed) {\n\t\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t\t'leaseBroker.key': key,\n\t\t\t\t\t\t'leaseBroker.owner': owner,\n\t\t\t\t\t\t'leaseBroker.claimed': false,\n\t\t\t\t\t});\n\t\t\t\t\treturn null;\n\t\t\t\t}\n\t\t\t\tyield* installReleaseFinalizer(key);\n\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t'leaseBroker.key': key,\n\t\t\t\t\t'leaseBroker.owner': owner,\n\t\t\t\t\t'leaseBroker.claimed': true,\n\t\t\t\t});\n\t\t\t\treturn { key, owner } satisfies Lease;\n\t\t\t}).pipe(\n\t\t\t\t// Make the claim-and-install-finalizer pair atomic w.r.t.\n\t\t\t\t// interruption: an interrupt arriving AFTER `Ref.modify`\n\t\t\t\t// claims the slot but BEFORE the finalizer is wired would\n\t\t\t\t// leak the lease. `Ref.modify` itself is a pure-data\n\t\t\t\t// transition, so wrapping the whole pipeline uninterruptibly\n\t\t\t\t// is safe.\n\t\t\t\tEffect.uninterruptible,\n\t\t\t\tEffect.withSpan('substrate.leaseBroker.tryAcquire'),\n\t\t\t);\n\n\t\tconst holders: LeaseBroker['holders'] = () =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst current = yield* Ref.get(state);\n\t\t\t\tconst out = new Map<LeaseKey, Owner>();\n\t\t\t\tfor (const [k, entry] of current) out.set(k, entry.holder);\n\t\t\t\treturn out;\n\t\t\t});\n\n\t\treturn LeaseBrokerService.of({ acquire, tryAcquire, holders });\n\t}),\n);\n"],"mappings":"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"}
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../../src/substrate/runtime/lease-broker/service.ts"],"sourcesContent":["// Lease broker — substrate-level service interface.\n//\n// Generic lease primitive keyed by an opaque resource identifier. Any caller\n// that needs at-most-one-in-flight serialization on a resource yields this\n// service and calls `acquire(key, owner)`. The first canonical consumer is the\n// per-address sequence-number lock (`plugins/account/address-lock.ts`);\n// callers in the same shape — sign+execute pipelines, per-connection gate,\n// per-slot work queue — share the same seam.\n//\n// Substrate name-blindness: the broker has no concept of what a\n// `LeaseKey` represents. The plugin author chooses the key shape; the\n// broker treats it as an opaque string with a brand. A wallet might\n// key by `account:<address>`, a GPU-bound plugin by `gpu:<slot>` —\n// the broker doesn't care.\n//\n// Lifetime: scope-bound. `acquire` returns a `Lease` handle whose\n// release fires when the surrounding `Effect.Scope` closes. There is\n// no `release()` method on `Lease` — the only release path is the\n// scope finalizer, which makes \"I forgot to release\" structurally\n// impossible.\n//\n// Mechanics: per-key state in a single `Ref<State>`. The blocking\n// queue is a FIFO of `Waiter`s carrying a `Deferred` that the\n// outgoing holder's finalizer resolves AFTER atomically installing\n// the next holder. `tryAcquire` does the same atomic-claim CAS as\n// `acquire`'s first step, but skips the wait — returning `null` if\n// the key is held.\n\nimport { Context, Deferred, Effect, Layer, Ref, Scope } from 'effect';\n\nimport type { Brand } from '../../brand.ts';\n\n// ----------------------------------------------------------------------\n// Public shape\n// ----------------------------------------------------------------------\n\n/** Opaque resource identifier. Substrate-blind: the broker treats\n *  this as a string for map keying and never inspects it. Plugin\n *  authors choose the encoding (`account:<addr>`, `gpu:<slot>`, etc.). */\nexport type LeaseKey = Brand<string, 'LeaseKey'>;\n\n/** Construct a `LeaseKey` from a free-form string. The boundary at\n *  which unbranded strings become branded; downstream code only sees\n *  branded values. */\nexport const leaseKey = (s: string): LeaseKey => s as LeaseKey;\n\n/** Free-form owner identity, used for diagnostics (`holders()` output,\n *  span attributes). The broker does NOT use this for re-entrancy:\n *  two `acquire` calls from the same owner against the same key will\n *  deadlock the second call. */\nexport type Owner = string;\n\n/** Lease handle. Carries only the diagnostic pair; the release is the\n *  scope finalizer, not a method.\n *\n *  Why no `release()`: every consumer we have today wraps the lease\n *  in `Effect.scoped` and lets the scope finalizer fire. Exposing an\n *  explicit `release()` would invite double-release, release-while-\n *  scope-still-open, and the \"I released early but forgot to clear\n *  the variable\" footgun. The scope IS the lifetime. */\nexport interface Lease {\n\treadonly key: LeaseKey;\n\treadonly owner: Owner;\n}\n\n/** Service shape — what plugins yield from Context. */\nexport interface LeaseBroker {\n\t/**\n\t * Acquire the lease for `key`, attributed to `owner`. Blocks if the\n\t * lease is already held, waiting in FIFO order behind earlier\n\t * waiters. Cancellable: an interrupt while waiting unwinds without\n\t * acquiring.\n\t *\n\t * Scope-bound release: the broker installs an uninterruptible\n\t * finalizer on the surrounding scope. Calling `Effect.scoped` over\n\t * an `acquire(...)` is the canonical shape.\n\t *\n\t * Non-reentrant: `acquire` from the same owner against a key the\n\t * owner already holds will deadlock. Per-address sequence-number\n\t * semantics require at-most-one in-flight; nesting is the caller's\n\t * bug.\n\t */\n\treadonly acquire: (key: LeaseKey, owner: Owner) => Effect.Effect<Lease, never, Scope.Scope>;\n\n\t/**\n\t * Non-blocking variant. Returns `null` if the lease is held by any\n\t * owner (including the calling owner); otherwise atomically claims\n\t * the lease and returns the handle. The atomic-claim CAS is the\n\t * same as `acquire`'s first step — the only difference is the\n\t * `null` return vs. enqueue.\n\t *\n\t * Scope-bound release: same finalizer install as `acquire` when\n\t * the claim wins.\n\t */\n\treadonly tryAcquire: (\n\t\tkey: LeaseKey,\n\t\towner: Owner,\n\t) => Effect.Effect<Lease | null, never, Scope.Scope>;\n\n\t/**\n\t * Snapshot of current holders, keyed by `LeaseKey`. For diagnostics\n\t * (renderer, debug logs); the result is a point-in-time read and\n\t * may be stale by the time it's inspected.\n\t */\n\treadonly holders: () => Effect.Effect<ReadonlyMap<LeaseKey, Owner>>;\n}\n\n// ----------------------------------------------------------------------\n// Internal state\n// ----------------------------------------------------------------------\n\n/** A fiber parked on `Deferred.await` waiting to become the next\n *  holder. The outgoing holder's finalizer transfers ownership by\n *  setting `holder = waiter.owner` on the per-key entry AND resolving\n *  the deferred — the awoken waiter doesn't re-CAS.\n *\n *  `Waiter` reference identity is the cancellation key: an interrupted\n *  waiter removes itself by reference-equality. */\ninterface Waiter {\n\treadonly owner: Owner;\n\treadonly signal: Deferred.Deferred<void>;\n}\n\ninterface KeyEntry {\n\treadonly holder: Owner;\n\treadonly waiters: ReadonlyArray<Waiter>;\n}\n\ntype State = ReadonlyMap<LeaseKey, KeyEntry>;\n\n// ----------------------------------------------------------------------\n// Service tag + Layer\n// ----------------------------------------------------------------------\n\nexport class LeaseBrokerService extends Context.Service<LeaseBrokerService, LeaseBroker>()(\n\t'@devstack/substrate/LeaseBroker',\n) {}\n\n/**\n * In-process Layer. One broker per stack scope; closing the layer's\n * scope drops every entry. Parallel stacks each get their own broker\n * — the broker is name-blind, so cross-stack coordination on the\n * same logical key (e.g. an address that two stacks share) is NOT\n * provided here. A cross-process layer can be slotted in later as a\n * sibling factory; today's consumers are in-process only.\n */\nexport const layerLeaseBroker: Layer.Layer<LeaseBrokerService> = Layer.effect(\n\tLeaseBrokerService,\n\tEffect.gen(function* () {\n\t\tconst state = yield* Ref.make<State>(new Map());\n\n\t\t/** Atomic finalizer body: clear `key`'s holder slot and, if any\n\t\t *  waiter is queued, promote the head waiter to holder. Returns\n\t\t *  the promoted waiter (so the caller can resolve their signal)\n\t\t *  or `null` when the key is fully released. Uninterruptible by\n\t\t *  construction — invoked from inside `Effect.addFinalizer` which\n\t\t *  the runtime wraps uninterruptibly. */\n\t\tconst releaseAndPromote = (key: LeaseKey): Effect.Effect<Waiter | null> =>\n\t\t\tRef.modify<State, Waiter | null>(state, (current) => {\n\t\t\t\tconst entry = current.get(key);\n\t\t\t\tif (!entry) return [null, current];\n\t\t\t\tconst head = entry.waiters[0];\n\t\t\t\tif (head === undefined) {\n\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\tnext.delete(key);\n\t\t\t\t\treturn [null, next];\n\t\t\t\t}\n\t\t\t\tconst rest = entry.waiters.slice(1);\n\t\t\t\tconst next = new Map(current);\n\t\t\t\tnext.set(key, { holder: head.owner, waiters: rest });\n\t\t\t\treturn [head, next];\n\t\t\t});\n\n\t\t/** Remove `waiter` from `key`'s waiter list. Called when an\n\t\t *  enqueued waiter is interrupted while parked on its signal. */\n\t\tconst removeWaiterIfQueued = (key: LeaseKey, waiter: Waiter): Effect.Effect<void> =>\n\t\t\tRef.update(state, (current) => {\n\t\t\t\tconst entry = current.get(key);\n\t\t\t\tif (!entry) return current;\n\t\t\t\tconst filtered = entry.waiters.filter((w) => w !== waiter);\n\t\t\t\tif (filtered.length === entry.waiters.length) return current;\n\t\t\t\tconst next = new Map(current);\n\t\t\t\tnext.set(key, { holder: entry.holder, waiters: filtered });\n\t\t\t\treturn next;\n\t\t\t});\n\n\t\t/** Cleanup on cancellation of a waiting `acquire`: if we were\n\t\t *  still queued, drop ourselves; if we were already promoted to\n\t\t *  holder by a release that raced with our interrupt, release on\n\t\t *  our behalf so the lease doesn't leak. */\n\t\tconst cleanupCancelledWait = (key: LeaseKey, waiter: Waiter): Effect.Effect<void> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst becameHolder = yield* Ref.modify<State, boolean>(state, (current) => {\n\t\t\t\t\tconst entry = current.get(key);\n\t\t\t\t\tif (!entry) return [false, current];\n\t\t\t\t\tif (entry.holder === waiter.owner && entry.waiters.indexOf(waiter) === -1) {\n\t\t\t\t\t\t// Promoted-but-not-awaited: we were handed the lease\n\t\t\t\t\t\t// in releaseAndPromote but interrupted before the\n\t\t\t\t\t\t// `Deferred.await` returned. Take responsibility for\n\t\t\t\t\t\t// releasing it.\n\t\t\t\t\t\treturn [true, current];\n\t\t\t\t\t}\n\t\t\t\t\treturn [false, current];\n\t\t\t\t});\n\t\t\t\tif (becameHolder) {\n\t\t\t\t\tconst promoted = yield* releaseAndPromote(key);\n\t\t\t\t\tif (promoted !== null) {\n\t\t\t\t\t\tyield* Deferred.succeed(promoted.signal, undefined);\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tyield* removeWaiterIfQueued(key, waiter);\n\t\t\t\t}\n\t\t\t});\n\n\t\t/** Install the scope-bound release finalizer. Uninterruptible —\n\t\t *  losing the release on a Ctrl-C double-tap would leak the\n\t\t *  lease and stall everything queued behind it. */\n\t\tconst installReleaseFinalizer = (key: LeaseKey): Effect.Effect<void, never, Scope.Scope> =>\n\t\t\tEffect.addFinalizer(() =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst promoted = yield* releaseAndPromote(key);\n\t\t\t\t\tif (promoted !== null) {\n\t\t\t\t\t\tyield* Deferred.succeed(promoted.signal, undefined);\n\t\t\t\t\t}\n\t\t\t\t}).pipe(Effect.uninterruptible),\n\t\t\t);\n\n\t\tconst acquire: LeaseBroker['acquire'] = (key, owner) =>\n\t\t\tEffect.uninterruptibleMask((restore) =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst signal = yield* Deferred.make<void>();\n\t\t\t\t\tconst waiter: Waiter = { owner, signal };\n\n\t\t\t\t\tconst becameHolder = yield* Ref.modify<State, boolean>(state, (current) => {\n\t\t\t\t\t\tconst entry = current.get(key);\n\t\t\t\t\t\tif (!entry) {\n\t\t\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\t\t\tnext.set(key, { holder: owner, waiters: [] });\n\t\t\t\t\t\t\treturn [true, next];\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\t\tnext.set(key, {\n\t\t\t\t\t\t\tholder: entry.holder,\n\t\t\t\t\t\t\twaiters: [...entry.waiters, waiter],\n\t\t\t\t\t\t});\n\t\t\t\t\t\treturn [false, next];\n\t\t\t\t\t});\n\n\t\t\t\t\tif (!becameHolder) {\n\t\t\t\t\t\tyield* restore(Deferred.await(signal)).pipe(\n\t\t\t\t\t\t\tEffect.onInterrupt(() =>\n\t\t\t\t\t\t\t\tcleanupCancelledWait(key, waiter).pipe(Effect.uninterruptible),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\n\t\t\t\t\tyield* installReleaseFinalizer(key);\n\t\t\t\t\treturn { key, owner } satisfies Lease;\n\t\t\t\t}),\n\t\t\t);\n\n\t\tconst tryAcquire: LeaseBroker['tryAcquire'] = (key, owner) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst claimed = yield* Ref.modify<State, boolean>(state, (current) => {\n\t\t\t\t\tif (current.has(key)) return [false, current];\n\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\tnext.set(key, { holder: owner, waiters: [] });\n\t\t\t\t\treturn [true, next];\n\t\t\t\t});\n\t\t\t\tif (!claimed) {\n\t\t\t\t\treturn null;\n\t\t\t\t}\n\t\t\t\tyield* installReleaseFinalizer(key);\n\t\t\t\treturn { key, owner } satisfies Lease;\n\t\t\t}).pipe(\n\t\t\t\t// Make the claim-and-install-finalizer pair atomic w.r.t.\n\t\t\t\t// interruption: an interrupt arriving AFTER `Ref.modify`\n\t\t\t\t// claims the slot but BEFORE the finalizer is wired would\n\t\t\t\t// leak the lease. `Ref.modify` itself is a pure-data\n\t\t\t\t// transition, so wrapping the whole pipeline uninterruptibly\n\t\t\t\t// is safe.\n\t\t\t\tEffect.uninterruptible,\n\t\t\t);\n\n\t\tconst holders: LeaseBroker['holders'] = () =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst current = yield* Ref.get(state);\n\t\t\t\tconst out = new Map<LeaseKey, Owner>();\n\t\t\t\tfor (const [k, entry] of current) out.set(k, entry.holder);\n\t\t\t\treturn out;\n\t\t\t});\n\n\t\treturn LeaseBrokerService.of({ acquire, tryAcquire, holders });\n\t}),\n);\n"],"mappings":"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"}

package/dist/substrate/runtime/lifecycle/dep-graph.mjs

@@ -57,7 +57,6 @@ const expand = (members) => {
 * supervisor's acquire spans.
 */
 const resolveGraph = (members) => Effect.gen(function* () {
-	yield* Effect.annotateCurrentSpan({ "devstack.dep-graph.memberCount": members.length });
 	const named = expand(members);
 	const providerByResourceId = /* @__PURE__ */ new Map();
 	for (const { key, member } of named) {
@@ -93,7 +92,8 @@ const resolveGraph = (members) => Effect.gen(function* () {
 			key,
 			member,
 			upstreamResources,
-			upstreamKeys
+			upstreamKeys,
+			keepAliveOnRestore: member.keepAliveOnRestore === true
 		});
 	}
 	const levels = [];
@@ -122,7 +122,7 @@ const resolveGraph = (members) => Effect.gen(function* () {
 		levels,
 		downstream: downstreamFrozen
 	};
-}).pipe(Effect.withSpan("lifecycle.dep-graph.resolve"));
+});
 /**
 * Compute the closure of nodes downstream of `root` (inclusive).
 * Used by the supervisor to tear down a subgraph in reverse-dep order