@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +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 } 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\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\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// `-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 = yield* Effect.try({\n\t\t\t\ttry: () =>\n\t\t\t\t\tspawn('tar', args, {\n\t\t\t\t\t\tstdio: ['ignore', 'pipe', 'pipe'],\n\t\t\t\t\t}),\n\t\t\t\tcatch: (cause) =>\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: `failed to spawn 'tar ${args.join(' ')}'`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t}),\n\t\t\t});\n\n\t\t\t// Stderr collection lives outside the data stream — we\n\t\t\t// accumulate the tail so an exit-code failure carries\n\t\t\t// actionable context. The stderr listener is removed on\n\t\t\t// scope close.\n\t\t\tconst stderrChunks: Array<Uint8Array> = [];\n\t\t\tconst onStderr = (chunk: Buffer): void => {\n\t\t\t\tstderrChunks.push(chunk);\n\t\t\t\tif (stderrChunks.length > 256) stderrChunks.splice(0, stderrChunks.length - 256);\n\t\t\t};\n\t\t\tchild.stderr?.on('data', onStderr);\n\n\t\t\t// Finalise the subprocess on scope close: kill if alive,\n\t\t\t// drop listeners either way.\n\t\t\tyield* Effect.addFinalizer(() =>\n\t\t\t\tEffect.sync(() => {\n\t\t\t\t\tchild.stderr?.off('data', onStderr);\n\t\t\t\t\tif (child.exitCode === null && child.signalCode === null) {\n\t\t\t\t\t\tchild.kill('SIGKILL');\n\t\t\t\t\t}\n\t\t\t\t}),\n\t\t\t);\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 = yield* Effect.try({\n\t\t\ttry: () =>\n\t\t\t\tspawn('tar', args, {\n\t\t\t\t\tstdio: ['pipe', 'ignore', 'pipe'],\n\t\t\t\t}),\n\t\t\tcatch: (cause) =>\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: `failed to spawn 'tar ${args.join(' ')}'`,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t});\n\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\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\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});\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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"}

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

@@ -0,0 +1,35 @@
+import { Effect } from "effect";
+import * as _$effect_Types0 from "effect/Types";
+import * as _$effect_Cause0 from "effect/Cause";
+
+//#region src/substrate/runtime/http-probe.d.ts
+declare namespace http_probe_d_exports {
+  export { HttpProbeError, HttpProbeFetch, HttpProbeOptions, HttpProbeValidator, waitForHttpEndpoint };
+}
+type HttpProbeFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type HttpProbeValidator = (response: Response) => boolean | Promise<boolean>;
+interface HttpProbeOptions {
+  readonly endpoint: string | URL;
+  readonly timeoutMs: number;
+  readonly intervalMs?: number;
+  readonly requestTimeoutMs?: number;
+  readonly requestInit?: Omit<RequestInit, 'signal'>;
+  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 & {
+  readonly _tag: "HttpProbeError";
+} & Readonly<A>;
+declare class HttpProbeError extends HttpProbeError_base<{
+  readonly endpoint: string;
+  readonly timeoutMs: number;
+  readonly intervalMs: number;
+  readonly requestTimeoutMs: number;
+  readonly message: string;
+  readonly lastStatus?: number;
+  readonly lastError?: unknown;
+}> {}
+declare const waitForHttpEndpoint: (options: HttpProbeOptions) => Effect.Effect<void, HttpProbeError>;
+//#endregion
+export { http_probe_d_exports };
+//# sourceMappingURL=http-probe.d.mts.map

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

@@ -0,0 +1,65 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.mjs";
+import { ProbeTimeoutError, waitForProbe } from "./probes.mjs";
+import { Data, Effect } from "effect";
+//#region src/substrate/runtime/http-probe.ts
+var http_probe_exports = /* @__PURE__ */ __exportAll({
+	HttpProbeError: () => HttpProbeError,
+	waitForHttpEndpoint: () => waitForHttpEndpoint
+});
+var HttpProbeError = class extends Data.TaggedError("HttpProbeError") {};
+const DEFAULT_INTERVAL_MS = 250;
+const waitForHttpEndpoint = (options) => Effect.gen(function* () {
+	const endpoint = String(options.endpoint);
+	const timeoutMs = options.timeoutMs;
+	const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+	const requestTimeoutMs = options.requestTimeoutMs ?? intervalMs;
+	const validate = options.validate ?? ((response) => response.ok);
+	const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+	let lastStatus;
+	return yield* waitForProbe({
+		label: endpoint,
+		timeoutMs,
+		intervalMs,
+		attemptTimeoutMs: requestTimeoutMs,
+		probe: () => Effect.tryPromise({
+			try: (signal) => fetchImpl(options.endpoint, {
+				method: "GET",
+				...options.requestInit,
+				signal
+			}),
+			catch: (cause) => cause
+		}).pipe(Effect.flatMap((response) => {
+			lastStatus = response.status;
+			return Effect.tryPromise({
+				try: () => Promise.resolve(validate(response)),
+				catch: (cause) => cause
+			}).pipe(Effect.map((ready) => ready ? true : {
+				ready: false,
+				detail: { status: response.status }
+			}));
+		}))
+	}).pipe(Effect.mapError((cause) => {
+		if (cause instanceof ProbeTimeoutError) return new HttpProbeError({
+			endpoint,
+			timeoutMs,
+			intervalMs,
+			requestTimeoutMs,
+			message: `HTTP endpoint ${endpoint} did not become ready within ${timeoutMs}ms`,
+			...lastStatus === void 0 ? {} : { lastStatus },
+			...cause.lastError === void 0 ? {} : { lastError: cause.lastError }
+		});
+		return new HttpProbeError({
+			endpoint,
+			timeoutMs,
+			intervalMs,
+			requestTimeoutMs,
+			message: `HTTP endpoint ${endpoint} probe failed`,
+			...lastStatus === void 0 ? {} : { lastStatus },
+			lastError: cause
+		});
+	}));
+});
+//#endregion
+export { http_probe_exports, waitForHttpEndpoint };
+
+//# sourceMappingURL=http-probe.mjs.map

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

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

package/dist/substrate/runtime/lease-broker/index.d.mts

@@ -0,0 +1 @@
+import { Lease, LeaseBroker, LeaseKey, Owner } from "./service.mjs";

package/dist/substrate/runtime/lease-broker/service.d.mts

@@ -0,0 +1,64 @@
+import { Brand } from "../../brand.mjs";
+import { Context, Effect, Layer, Scope } from "effect";
+
+//#region src/substrate/runtime/lease-broker/service.d.ts
+/** Opaque resource identifier. Substrate-blind: the broker treats
+ *  this as a string for map keying and never inspects it. Plugin
+ *  authors choose the encoding (`account:<addr>`, `gpu:<slot>`, etc.). */
+type LeaseKey = Brand<string, 'LeaseKey'>;
+/** Free-form owner identity, used for diagnostics (`holders()` output,
+ *  span attributes). The broker does NOT use this for re-entrancy:
+ *  two `acquire` calls from the same owner against the same key will
+ *  deadlock the second call. */
+type Owner = string;
+/** Lease handle. Carries only the diagnostic pair; the release is the
+ *  scope finalizer, not a method.
+ *
+ *  Why no `release()`: every consumer we have today wraps the lease
+ *  in `Effect.scoped` and lets the scope finalizer fire. Exposing an
+ *  explicit `release()` would invite double-release, release-while-
+ *  scope-still-open, and the "I released early but forgot to clear
+ *  the variable" footgun. The scope IS the lifetime. */
+interface Lease {
+  readonly key: LeaseKey;
+  readonly owner: Owner;
+}
+/** Service shape — what plugins yield from Context. */
+interface LeaseBroker {
+  /**
+   * Acquire the lease for `key`, attributed to `owner`. Blocks if the
+   * lease is already held, waiting in FIFO order behind earlier
+   * waiters. Cancellable: an interrupt while waiting unwinds without
+   * acquiring.
+   *
+   * Scope-bound release: the broker installs an uninterruptible
+   * finalizer on the surrounding scope. Calling `Effect.scoped` over
+   * an `acquire(...)` is the canonical shape.
+   *
+   * Non-reentrant: `acquire` from the same owner against a key the
+   * owner already holds will deadlock. Per-address sequence-number
+   * semantics require at-most-one in-flight; nesting is the caller's
+   * bug.
+   */
+  readonly acquire: (key: LeaseKey, owner: Owner) => Effect.Effect<Lease, never, Scope.Scope>;
+  /**
+   * Non-blocking variant. Returns `null` if the lease is held by any
+   * owner (including the calling owner); otherwise atomically claims
+   * the lease and returns the handle. The atomic-claim CAS is the
+   * same as `acquire`'s first step — the only difference is the
+   * `null` return vs. enqueue.
+   *
+   * Scope-bound release: same finalizer install as `acquire` when
+   * the claim wins.
+   */
+  readonly tryAcquire: (key: LeaseKey, owner: Owner) => Effect.Effect<Lease | null, never, Scope.Scope>;
+  /**
+   * Snapshot of current holders, keyed by `LeaseKey`. For diagnostics
+   * (renderer, debug logs); the result is a point-in-time read and
+   * may be stale by the time it's inspected.
+   */
+  readonly holders: () => Effect.Effect<ReadonlyMap<LeaseKey, Owner>>;
+}
+//#endregion
+export { Lease, LeaseBroker, LeaseKey, Owner };
+//# sourceMappingURL=service.d.mts.map

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

@@ -0,0 +1,155 @@
+import { Context, Deferred, Effect, Layer, Ref } from "effect";
+//#region src/substrate/runtime/lease-broker/service.ts
+/** Construct a `LeaseKey` from a free-form string. The boundary at
+*  which unbranded strings become branded; downstream code only sees
+*  branded values. */
+const leaseKey = (s) => s;
+var LeaseBrokerService = class extends Context.Service()("@devstack-rewrite/substrate/LeaseBroker") {};
+/**
+* In-process Layer. One broker per stack scope; closing the layer's
+* scope drops every entry. Parallel stacks each get their own broker
+* — the broker is name-blind, so cross-stack coordination on the
+* same logical key (e.g. an address that two stacks share) is NOT
+* provided here. A cross-process layer can be slotted in later as a
+* sibling factory; today's consumers are in-process only.
+*/
+const layerLeaseBroker = Layer.effect(LeaseBrokerService, Effect.gen(function* () {
+	const state = yield* Ref.make(/* @__PURE__ */ new Map());
+	/** Atomic finalizer body: clear `key`'s holder slot and, if any
+	*  waiter is queued, promote the head waiter to holder. Returns
+	*  the promoted waiter (so the caller can resolve their signal)
+	*  or `null` when the key is fully released. Uninterruptible by
+	*  construction — invoked from inside `Effect.addFinalizer` which
+	*  the runtime wraps uninterruptibly. */
+	const releaseAndPromote = (key) => Ref.modify(state, (current) => {
+		const entry = current.get(key);
+		if (!entry) return [null, current];
+		const head = entry.waiters[0];
+		if (head === void 0) {
+			const next = new Map(current);
+			next.delete(key);
+			return [null, next];
+		}
+		const rest = entry.waiters.slice(1);
+		const next = new Map(current);
+		next.set(key, {
+			holder: head.owner,
+			waiters: rest
+		});
+		return [head, next];
+	});
+	/** Remove `waiter` from `key`'s waiter list. Called when an
+	*  enqueued waiter is interrupted while parked on its signal. */
+	const removeWaiterIfQueued = (key, waiter) => Ref.update(state, (current) => {
+		const entry = current.get(key);
+		if (!entry) return current;
+		const filtered = entry.waiters.filter((w) => w !== waiter);
+		if (filtered.length === entry.waiters.length) return current;
+		const next = new Map(current);
+		next.set(key, {
+			holder: entry.holder,
+			waiters: filtered
+		});
+		return next;
+	});
+	/** Cleanup on cancellation of a waiting `acquire`: if we were
+	*  still queued, drop ourselves; if we were already promoted to
+	*  holder by a release that raced with our interrupt, release on
+	*  our behalf so the lease doesn't leak. */
+	const cleanupCancelledWait = (key, waiter) => Effect.gen(function* () {
+		if (yield* Ref.modify(state, (current) => {
+			const entry = current.get(key);
+			if (!entry) return [false, current];
+			if (entry.holder === waiter.owner && entry.waiters.indexOf(waiter) === -1) return [true, current];
+			return [false, current];
+		})) {
+			const promoted = yield* releaseAndPromote(key);
+			if (promoted !== null) yield* Deferred.succeed(promoted.signal, void 0);
+		} else yield* removeWaiterIfQueued(key, waiter);
+	});
+	/** Install the scope-bound release finalizer. Uninterruptible —
+	*  losing the release on a Ctrl-C double-tap would leak the
+	*  lease and stall everything queued behind it. */
+	const installReleaseFinalizer = (key) => Effect.addFinalizer(() => Effect.gen(function* () {
+		const promoted = yield* releaseAndPromote(key);
+		if (promoted !== null) yield* Deferred.succeed(promoted.signal, void 0);
+	}).pipe(Effect.uninterruptible));
+	const acquire = (key, owner) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+		const signal = yield* Deferred.make();
+		const waiter = {
+			owner,
+			signal
+		};
+		const becameHolder = yield* Ref.modify(state, (current) => {
+			const entry = current.get(key);
+			if (!entry) {
+				const next = new Map(current);
+				next.set(key, {
+					holder: owner,
+					waiters: []
+				});
+				return [true, next];
+			}
+			const next = new Map(current);
+			next.set(key, {
+				holder: entry.holder,
+				waiters: [...entry.waiters, waiter]
+			});
+			return [false, next];
+		});
+		if (!becameHolder) 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];
+			const next = new Map(current);
+			next.set(key, {
+				holder: owner,
+				waiters: []
+			});
+			return [true, next];
+		}))) {
+			yield* Effect.annotateCurrentSpan({
+				"leaseBroker.key": key,
+				"leaseBroker.owner": owner,
+				"leaseBroker.claimed": false
+			});
+			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"));
+	const holders = () => Effect.gen(function* () {
+		const current = yield* Ref.get(state);
+		const out = /* @__PURE__ */ new Map();
+		for (const [k, entry] of current) out.set(k, entry.holder);
+		return out;
+	});
+	return LeaseBrokerService.of({
+		acquire,
+		tryAcquire,
+		holders
+	});
+}));
+//#endregion
+export { LeaseBrokerService, layerLeaseBroker, leaseKey };
+
+//# sourceMappingURL=service.mjs.map

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

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

package/dist/substrate/runtime/lifecycle/dep-graph.d.mts

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

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

@@ -0,0 +1,138 @@
+import { uniqueResourceRefs } from "../../plugin.mjs";
+import { pluginKey } from "../../brand.mjs";
+import { Data, Effect } from "effect";
+//#region src/substrate/runtime/lifecycle/dep-graph.ts
+/** Cycle detected in the dep graph. Carries the offending key path so
+*  the user sees the loop. Compile-time `defineDevstack` doesn't catch
+*  every cycle (capability-typed consumes resolve at runtime), so this
+*  surfaces a typed error at boot. */
+var DepGraphCycleError = class extends Data.TaggedError("DepGraphCycleError") {};
+/** A dependency resource matched no provider. This is normally caught by
+*  the compile-time `MissingProviders` check, but runtime-built stacks can
+*  hit it. */
+var UnresolvedDependencyError = class extends Data.TaggedError("UnresolvedDependencyError") {};
+/** Mint a stable PluginKey for a plugin. Plugins may declare a stable
+*  key; otherwise keys derive from resource id + ordinal so duplicates
+*  do not collide. */
+const mintKey = (member, ordinal) => {
+	if (member.pluginKey !== void 0) return pluginKey(String(member.pluginKey));
+	return pluginKey(`${member.id}#${ordinal}`);
+};
+/** Walk the member tuple and emit one named-member entry per node. */
+const expand = (members) => {
+	const out = [];
+	let ordinal = 0;
+	for (const member of members) {
+		const key = mintKey(member, ordinal++);
+		out.push({
+			key,
+			member
+		});
+	}
+	return out;
+};
+/**
+* Resolve a flat member tuple into a topo-sorted level batch.
+*
+* Steps:
+*  1. Mint a plugin key for every member.
+*  2. Build the resource-id -> key index (providers).
+*  3. For each node, resolve its dependency refs to upstream keys.
+*  4. Kahn's algorithm: peel zero-indegree nodes into level 0, decrement
+*     downstream indegrees, repeat.
+*  5. If any node remains, return `DepGraphCycleError`.
+*
+* Span-instrumented so trace exports show the resolution alongside the
+* 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) providerByResourceId.set(member.id, key);
+	const nodes = /* @__PURE__ */ new Map();
+	const indegree = /* @__PURE__ */ new Map();
+	const downstream = /* @__PURE__ */ new Map();
+	for (const { key } of named) {
+		indegree.set(key, 0);
+		downstream.set(key, /* @__PURE__ */ new Set());
+	}
+	for (const { key, member } of named) {
+		const upstreamKeys = [];
+		const upstreamResources = uniqueResourceRefs(member.dependsOn);
+		for (const resource of upstreamResources) {
+			const providerKey = providerByResourceId.get(resource.id);
+			if (providerKey === void 0) return yield* Effect.fail(new UnresolvedDependencyError({
+				pluginKey: key,
+				missingResourceId: resource.id
+			}));
+			upstreamKeys.push(providerKey);
+			downstream.get(providerKey)?.add(key);
+			indegree.set(key, (indegree.get(key) ?? 0) + 1);
+		}
+		nodes.set(key, {
+			key,
+			member,
+			upstreamResources,
+			upstreamKeys
+		});
+	}
+	const levels = [];
+	const settled = /* @__PURE__ */ new Set();
+	while (settled.size < nodes.size) {
+		const layer = [];
+		for (const [key, deg] of indegree) {
+			if (settled.has(key)) continue;
+			if (deg === 0) layer.push(key);
+		}
+		if (layer.length === 0) {
+			const trapped = [];
+			for (const key of nodes.keys()) if (!settled.has(key)) trapped.push(key);
+			return yield* Effect.fail(new DepGraphCycleError({ cycle: trapped }));
+		}
+		levels.push(layer);
+		for (const key of layer) {
+			settled.add(key);
+			for (const child of downstream.get(key) ?? []) indegree.set(child, (indegree.get(child) ?? 1) - 1);
+		}
+	}
+	const downstreamFrozen = /* @__PURE__ */ new Map();
+	for (const [k, v] of downstream) downstreamFrozen.set(k, v);
+	return {
+		nodes,
+		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
+* and re-acquire in forward order.
+*
+* Architecture § Watch-triggered invalidation:
+*   Invalidating a producer invalidates downstream consumers along
+*   dep-graph edges (cascade semantics).
+*/
+const downstreamClosure = (graph, root) => {
+	const closure = new Set([root]);
+	const queue = [root];
+	while (queue.length > 0) {
+		const next = queue.shift();
+		for (const child of graph.downstream.get(next) ?? []) if (!closure.has(child)) {
+			closure.add(child);
+			queue.push(child);
+		}
+	}
+	return closure;
+};
+/** Order a set of keys by their dep-graph level — forward (low-to-high)
+*  for acquire, reverse (high-to-low) for teardown. */
+const orderByLevel = (graph, keys, direction) => {
+	const out = [];
+	for (const level of graph.levels) for (const key of level) if (keys.has(key)) out.push(key);
+	return direction === "reverse" ? out.slice().reverse() : out;
+};
+//#endregion
+export { downstreamClosure, orderByLevel, resolveGraph };
+
+//# sourceMappingURL=dep-graph.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dep-graph.mjs","names":["makePluginKey"],"sources":["../../../../src/substrate/runtime/lifecycle/dep-graph.ts"],"sourcesContent":["// Dep-graph resolution — turn a `Stack` member tuple into a topo-sorted\n// acquire schedule.\n//\n// Architecture § Plugin lifecycle within a stack:\n//   \"Resolution. Upstream keys (concrete or capability-typed) resolve\n//   once. Bootstrap asset dedup-by-key fires before the scheduler\n//   starts node fibers. Scheduling. Plugin enters `pending`. When all\n//   upstream keys are `ready`, the node begins `acquiring`. Per-key\n//   serialization: only one acquire at a time per key.\"\n//\n// This module is the pure dep-graph math: members in, levels out.\n\nimport { Data, Effect } from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport { pluginKey as makePluginKey } from '../../brand.ts';\nimport { uniqueResourceRefs, type AnyPlugin, type AnyResourceRef } from '../../plugin.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** Cycle detected in the dep graph. Carries the offending key path so\n *  the user sees the loop. Compile-time `defineDevstack` doesn't catch\n *  every cycle (capability-typed consumes resolve at runtime), so this\n *  surfaces a typed error at boot. */\nexport class DepGraphCycleError extends Data.TaggedError('DepGraphCycleError')<{\n\treadonly cycle: ReadonlyArray<PluginKey>;\n}> {}\n\n/** A dependency resource matched no provider. This is normally caught by\n *  the compile-time `MissingProviders` check, but runtime-built stacks can\n *  hit it. */\nexport class UnresolvedDependencyError extends Data.TaggedError('UnresolvedDependencyError')<{\n\treadonly pluginKey: PluginKey;\n\treadonly missingResourceId: string;\n}> {}\n\nexport type DepGraphError = DepGraphCycleError | UnresolvedDependencyError;\n\n// -----------------------------------------------------------------------------\n// Node shape\n// -----------------------------------------------------------------------------\n\n/** A resolved node in the dep graph. Wraps the original plugin with a\n *  substrate-assigned `PluginKey`. */\nexport interface DepNode {\n\treadonly key: PluginKey;\n\treadonly member: AnyPlugin;\n\t/** Unique dependency refs and their resolved upstream keys. The two\n\t *  arrays are positional peers. */\n\treadonly upstreamResources: ReadonlyArray<AnyResourceRef>;\n\treadonly upstreamKeys: ReadonlyArray<PluginKey>;\n}\n\n/** The result of resolving a member tuple. Levels are batches the\n *  scheduler can acquire in parallel; each level's nodes only depend\n *  on prior levels. */\nexport interface ResolvedGraph {\n\treadonly nodes: ReadonlyMap<PluginKey, DepNode>;\n\treadonly levels: ReadonlyArray<ReadonlyArray<PluginKey>>;\n\t/** Reverse-dep index: each key → keys that depend on it. The\n\t *  supervisor uses this for selective-restart cascade. */\n\treadonly downstream: ReadonlyMap<PluginKey, ReadonlySet<PluginKey>>;\n}\n\n// -----------------------------------------------------------------------------\n// Plugin key minting\n// -----------------------------------------------------------------------------\n\ninterface NamedMember {\n\treadonly key: PluginKey;\n\treadonly member: AnyPlugin;\n}\n\n/** Mint a stable PluginKey for a plugin. Plugins may declare a stable\n *  key; otherwise keys derive from resource id + ordinal so duplicates\n *  do not collide. */\nconst mintKey = (member: AnyPlugin, ordinal: number): PluginKey => {\n\tif (member.pluginKey !== undefined) {\n\t\treturn makePluginKey(String(member.pluginKey));\n\t}\n\treturn makePluginKey(`${member.id}#${ordinal}`);\n};\n\n/** Walk the member tuple and emit one named-member entry per node. */\nconst expand = (members: ReadonlyArray<AnyPlugin>): ReadonlyArray<NamedMember> => {\n\tconst out: NamedMember[] = [];\n\tlet ordinal = 0;\n\tfor (const member of members) {\n\t\tconst key = mintKey(member, ordinal++);\n\t\tout.push({ key, member });\n\t}\n\treturn out;\n};\n\n// -----------------------------------------------------------------------------\n// Topological sort (Kahn's algorithm)\n// -----------------------------------------------------------------------------\n\n/**\n * Resolve a flat member tuple into a topo-sorted level batch.\n *\n * Steps:\n *  1. Mint a plugin key for every member.\n *  2. Build the resource-id -> key index (providers).\n *  3. For each node, resolve its dependency refs to upstream keys.\n *  4. Kahn's algorithm: peel zero-indegree nodes into level 0, decrement\n *     downstream indegrees, repeat.\n *  5. If any node remains, return `DepGraphCycleError`.\n *\n * Span-instrumented so trace exports show the resolution alongside the\n * supervisor's acquire spans.\n */\nexport const resolveGraph = (\n\tmembers: ReadonlyArray<AnyPlugin>,\n): Effect.Effect<ResolvedGraph, DepGraphError> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({ 'devstack.dep-graph.memberCount': members.length });\n\t\tconst named = expand(members);\n\n\t\t// Provider index: resource-id → key. Last writer wins; the\n\t\t// compile-time `MissingProviders` check ensures uniqueness on\n\t\t// the user-typed path, so a duplicate here would be a programmer\n\t\t// error in a runtime-typed stack — we don't enforce uniqueness at\n\t\t// runtime; the duplicate just resolves to the latest declaration.\n\t\tconst providerByResourceId = new Map<string, PluginKey>();\n\t\tfor (const { key, member } of named) {\n\t\t\tproviderByResourceId.set(member.id, key);\n\t\t}\n\n\t\tconst nodes = new Map<PluginKey, DepNode>();\n\t\tconst indegree = new Map<PluginKey, number>();\n\t\tconst downstream = new Map<PluginKey, Set<PluginKey>>();\n\t\tfor (const { key } of named) {\n\t\t\tindegree.set(key, 0);\n\t\t\tdownstream.set(key, new Set());\n\t\t}\n\n\t\tfor (const { key, member } of named) {\n\t\t\tconst upstreamKeys: PluginKey[] = [];\n\t\t\tconst upstreamResources = uniqueResourceRefs(member.dependsOn);\n\t\t\tfor (const resource of upstreamResources) {\n\t\t\t\tconst providerKey = providerByResourceId.get(resource.id);\n\t\t\t\tif (providerKey === undefined) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tnew UnresolvedDependencyError({ pluginKey: key, missingResourceId: resource.id }),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tupstreamKeys.push(providerKey);\n\t\t\t\tdownstream.get(providerKey)?.add(key);\n\t\t\t\tindegree.set(key, (indegree.get(key) ?? 0) + 1);\n\t\t\t}\n\t\t\tnodes.set(key, {\n\t\t\t\tkey,\n\t\t\t\tmember,\n\t\t\t\tupstreamResources,\n\t\t\t\tupstreamKeys,\n\t\t\t});\n\t\t}\n\n\t\t// Kahn's algorithm — peel zero-indegree nodes level by level.\n\t\tconst levels: PluginKey[][] = [];\n\t\tconst settled = new Set<PluginKey>();\n\t\twhile (settled.size < nodes.size) {\n\t\t\tconst layer: PluginKey[] = [];\n\t\t\tfor (const [key, deg] of indegree) {\n\t\t\t\tif (settled.has(key)) continue;\n\t\t\t\tif (deg === 0) layer.push(key);\n\t\t\t}\n\t\t\tif (layer.length === 0) {\n\t\t\t\t// Cycle: collect every unsettled node as the cycle's witness.\n\t\t\t\t// More precise cycle extraction (Tarjan SCC) is overkill for\n\t\t\t\t// the user-facing message; we surface the trapped keys.\n\t\t\t\tconst trapped: PluginKey[] = [];\n\t\t\t\tfor (const key of nodes.keys()) {\n\t\t\t\t\tif (!settled.has(key)) trapped.push(key);\n\t\t\t\t}\n\t\t\t\treturn yield* Effect.fail(new DepGraphCycleError({ cycle: trapped }));\n\t\t\t}\n\t\t\tlevels.push(layer);\n\t\t\tfor (const key of layer) {\n\t\t\t\tsettled.add(key);\n\t\t\t\tfor (const child of downstream.get(key) ?? []) {\n\t\t\t\t\tindegree.set(child, (indegree.get(child) ?? 1) - 1);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Freeze downstream sets to ReadonlySet shape.\n\t\tconst downstreamFrozen = new Map<PluginKey, ReadonlySet<PluginKey>>();\n\t\tfor (const [k, v] of downstream) downstreamFrozen.set(k, v);\n\n\t\treturn {\n\t\t\tnodes,\n\t\t\tlevels,\n\t\t\tdownstream: downstreamFrozen,\n\t\t} satisfies ResolvedGraph;\n\t}).pipe(Effect.withSpan('lifecycle.dep-graph.resolve'));\n\n// -----------------------------------------------------------------------------\n// Selective-restart helpers\n// -----------------------------------------------------------------------------\n\n/**\n * Compute the closure of nodes downstream of `root` (inclusive).\n * Used by the supervisor to tear down a subgraph in reverse-dep order\n * and re-acquire in forward order.\n *\n * Architecture § Watch-triggered invalidation:\n *   Invalidating a producer invalidates downstream consumers along\n *   dep-graph edges (cascade semantics).\n */\nexport const downstreamClosure = (\n\tgraph: ResolvedGraph,\n\troot: PluginKey,\n): ReadonlySet<PluginKey> => {\n\tconst closure = new Set<PluginKey>([root]);\n\tconst queue: PluginKey[] = [root];\n\twhile (queue.length > 0) {\n\t\tconst next = queue.shift()!;\n\t\tfor (const child of graph.downstream.get(next) ?? []) {\n\t\t\tif (!closure.has(child)) {\n\t\t\t\tclosure.add(child);\n\t\t\t\tqueue.push(child);\n\t\t\t}\n\t\t}\n\t}\n\treturn closure;\n};\n\n/** Order a set of keys by their dep-graph level — forward (low-to-high)\n *  for acquire, reverse (high-to-low) for teardown. */\nexport const orderByLevel = (\n\tgraph: ResolvedGraph,\n\tkeys: ReadonlySet<PluginKey>,\n\tdirection: 'forward' | 'reverse',\n): ReadonlyArray<PluginKey> => {\n\tconst out: PluginKey[] = [];\n\tfor (const level of graph.levels) {\n\t\tfor (const key of level) if (keys.has(key)) out.push(key);\n\t}\n\treturn direction === 'reverse' ? out.slice().reverse() : out;\n};\n"],"mappings":";;;;;;;;AA0BA,IAAa,qBAAb,cAAwC,KAAK,YAAY,qBAAqB,CAE3E;;;;AAKH,IAAa,4BAAb,cAA+C,KAAK,YAAY,4BAA4B,CAGzF;;;;AA0CH,MAAM,WAAW,QAAmB,YAA+B;AAClE,KAAI,OAAO,cAAc,KAAA,EACxB,QAAOA,UAAc,OAAO,OAAO,UAAU,CAAC;AAE/C,QAAOA,UAAc,GAAG,OAAO,GAAG,GAAG,UAAU;;;AAIhD,MAAM,UAAU,YAAkE;CACjF,MAAM,MAAqB,EAAE;CAC7B,IAAI,UAAU;AACd,MAAK,MAAM,UAAU,SAAS;EAC7B,MAAM,MAAM,QAAQ,QAAQ,UAAU;AACtC,MAAI,KAAK;GAAE;GAAK;GAAQ,CAAC;;AAE1B,QAAO;;;;;;;;;;;;;;;;AAqBR,MAAa,gBACZ,YAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB,EAAE,kCAAkC,QAAQ,QAAQ,CAAC;CACvF,MAAM,QAAQ,OAAO,QAAQ;CAO7B,MAAM,uCAAuB,IAAI,KAAwB;AACzD,MAAK,MAAM,EAAE,KAAK,YAAY,MAC7B,sBAAqB,IAAI,OAAO,IAAI,IAAI;CAGzC,MAAM,wBAAQ,IAAI,KAAyB;CAC3C,MAAM,2BAAW,IAAI,KAAwB;CAC7C,MAAM,6BAAa,IAAI,KAAgC;AACvD,MAAK,MAAM,EAAE,SAAS,OAAO;AAC5B,WAAS,IAAI,KAAK,EAAE;AACpB,aAAW,IAAI,qBAAK,IAAI,KAAK,CAAC;;AAG/B,MAAK,MAAM,EAAE,KAAK,YAAY,OAAO;EACpC,MAAM,eAA4B,EAAE;EACpC,MAAM,oBAAoB,mBAAmB,OAAO,UAAU;AAC9D,OAAK,MAAM,YAAY,mBAAmB;GACzC,MAAM,cAAc,qBAAqB,IAAI,SAAS,GAAG;AACzD,OAAI,gBAAgB,KAAA,EACnB,QAAO,OAAO,OAAO,KACpB,IAAI,0BAA0B;IAAE,WAAW;IAAK,mBAAmB,SAAS;IAAI,CAAC,CACjF;AAEF,gBAAa,KAAK,YAAY;AAC9B,cAAW,IAAI,YAAY,EAAE,IAAI,IAAI;AACrC,YAAS,IAAI,MAAM,SAAS,IAAI,IAAI,IAAI,KAAK,EAAE;;AAEhD,QAAM,IAAI,KAAK;GACd;GACA;GACA;GACA;GACA,CAAC;;CAIH,MAAM,SAAwB,EAAE;CAChC,MAAM,0BAAU,IAAI,KAAgB;AACpC,QAAO,QAAQ,OAAO,MAAM,MAAM;EACjC,MAAM,QAAqB,EAAE;AAC7B,OAAK,MAAM,CAAC,KAAK,QAAQ,UAAU;AAClC,OAAI,QAAQ,IAAI,IAAI,CAAE;AACtB,OAAI,QAAQ,EAAG,OAAM,KAAK,IAAI;;AAE/B,MAAI,MAAM,WAAW,GAAG;GAIvB,MAAM,UAAuB,EAAE;AAC/B,QAAK,MAAM,OAAO,MAAM,MAAM,CAC7B,KAAI,CAAC,QAAQ,IAAI,IAAI,CAAE,SAAQ,KAAK,IAAI;AAEzC,UAAO,OAAO,OAAO,KAAK,IAAI,mBAAmB,EAAE,OAAO,SAAS,CAAC,CAAC;;AAEtE,SAAO,KAAK,MAAM;AAClB,OAAK,MAAM,OAAO,OAAO;AACxB,WAAQ,IAAI,IAAI;AAChB,QAAK,MAAM,SAAS,WAAW,IAAI,IAAI,IAAI,EAAE,CAC5C,UAAS,IAAI,QAAQ,SAAS,IAAI,MAAM,IAAI,KAAK,EAAE;;;CAMtD,MAAM,mCAAmB,IAAI,KAAwC;AACrE,MAAK,MAAM,CAAC,GAAG,MAAM,WAAY,kBAAiB,IAAI,GAAG,EAAE;AAE3D,QAAO;EACN;EACA;EACA,YAAY;EACZ;EACA,CAAC,KAAK,OAAO,SAAS,8BAA8B,CAAC;;;;;;;;;;AAexD,MAAa,qBACZ,OACA,SAC4B;CAC5B,MAAM,UAAU,IAAI,IAAe,CAAC,KAAK,CAAC;CAC1C,MAAM,QAAqB,CAAC,KAAK;AACjC,QAAO,MAAM,SAAS,GAAG;EACxB,MAAM,OAAO,MAAM,OAAO;AAC1B,OAAK,MAAM,SAAS,MAAM,WAAW,IAAI,KAAK,IAAI,EAAE,CACnD,KAAI,CAAC,QAAQ,IAAI,MAAM,EAAE;AACxB,WAAQ,IAAI,MAAM;AAClB,SAAM,KAAK,MAAM;;;AAIpB,QAAO;;;;AAKR,MAAa,gBACZ,OACA,MACA,cAC8B;CAC9B,MAAM,MAAmB,EAAE;AAC3B,MAAK,MAAM,SAAS,MAAM,OACzB,MAAK,MAAM,OAAO,MAAO,KAAI,KAAK,IAAI,IAAI,CAAE,KAAI,KAAK,IAAI;AAE1D,QAAO,cAAc,YAAY,IAAI,OAAO,CAAC,SAAS,GAAG"}

package/dist/substrate/runtime/lifecycle/index.d.mts

@@ -0,0 +1 @@
+export { };