@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/substrate/runtime/runtime-decode.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-decode.mjs","names":[],"sources":["../../../src/substrate/runtime/runtime-decode.ts"],"sourcesContent":["// Compound Schema decode at trust boundaries — JSON / unknown →\n// typed values, with one parse/decode issue shape and typed error\n// projection. Reach for `decodeUnknown(Sync)` /\n// `decodeJsonText(Sync)` when you have a Schema and want to decode\n// a whole shape (multi-field, refinements, transforms).\n//\n// For one-field shape checks (\"port must be a positive integer\",\n// \"name must be a non-empty string\") that throw on bad input,\n// reach for the `expect*` helpers in `config-validation.ts` instead.\n\nimport { Effect, Schema } from 'effect';\n\nexport interface RuntimeDecodeIssue {\n\treadonly source: string;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport type RuntimeDecodeErrorFactory<E> = (issue: RuntimeDecodeIssue) => E;\n\nexport interface DecodeOptions<E> {\n\treadonly source: string;\n\treadonly mkError: RuntimeDecodeErrorFactory<E>;\n\treadonly message?: string;\n}\n\nexport interface JsonArrayElementDecodeOptions<E> extends DecodeOptions<E> {\n\treadonly index?: number;\n\treadonly missingMessage?: string;\n}\n\nconst issue = <E>(\n\toptions: DecodeOptions<E>,\n\tmessage: string,\n\tcause?: unknown,\n): RuntimeDecodeIssue => ({\n\tsource: options.source,\n\tmessage: options.message ?? message,\n\t...(cause === undefined ? {} : { cause }),\n});\n\nexport const parseJsonText = <E>(\n\ttext: string,\n\toptions: DecodeOptions<E>,\n): Effect.Effect<unknown, E> =>\n\tEffect.try({\n\t\ttry: () => JSON.parse(text) as unknown,\n\t\tcatch: (cause) => options.mkError(issue(options, 'failed to parse JSON', cause)),\n\t});\n\nexport const parseJsonTextSync = <E>(text: string, options: DecodeOptions<E>): unknown => {\n\ttry {\n\t\treturn JSON.parse(text) as unknown;\n\t} catch (cause) {\n\t\tthrow options.mkError(issue(options, 'failed to parse JSON', cause));\n\t}\n};\n\nexport const decodeUnknown = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\tvalue: unknown,\n\toptions: DecodeOptions<E>,\n): Effect.Effect<S['Type'], E> =>\n\tSchema.decodeUnknownEffect(schema)(value).pipe(\n\t\tEffect.mapError((cause) => options.mkError(issue(options, 'failed to decode value', cause))),\n\t);\n\nexport const decodeUnknownSync = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\tvalue: unknown,\n\toptions: DecodeOptions<E>,\n): S['Type'] => {\n\ttry {\n\t\treturn Schema.decodeUnknownSync(schema)(value);\n\t} catch (cause) {\n\t\tthrow options.mkError(issue(options, 'failed to decode value', cause));\n\t}\n};\n\nexport const decodeJsonText = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\ttext: string,\n\toptions: DecodeOptions<E>,\n): Effect.Effect<S['Type'], E> =>\n\tparseJsonText(text, options).pipe(\n\t\tEffect.flatMap((value) => decodeUnknown(schema, value, options)),\n\t);\n\nexport const decodeJsonTextSync = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\ttext: string,\n\toptions: DecodeOptions<E>,\n): S['Type'] => decodeUnknownSync(schema, parseJsonTextSync(text, options), options);\n\nexport const decodeJsonArrayElementSync = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\ttext: string,\n\toptions: JsonArrayElementDecodeOptions<E>,\n): S['Type'] => {\n\tconst index = options.index ?? 0;\n\tconst value = parseJsonTextSync(text, options);\n\tif (!Array.isArray(value) || value[index] === undefined) {\n\t\tthrow options.mkError(\n\t\t\tissue(\n\t\t\t\toptions,\n\t\t\t\toptions.missingMessage ?? `expected JSON array element at index ${index}`,\n\t\t\t\tvalue,\n\t\t\t),\n\t\t);\n\t}\n\treturn decodeUnknownSync(schema, value[index], options);\n};\n\nexport const decodeJsonLines = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\ttext: string,\n\toptions: DecodeOptions<E>,\n): Effect.Effect<ReadonlyArray<S['Type']>, E> =>\n\tEffect.forEach(\n\t\ttext\n\t\t\t.split(/\\r?\\n/u)\n\t\t\t.map((line) => line.trim())\n\t\t\t.filter((line) => line.length > 0),\n\t\t(line, index) =>\n\t\t\tdecodeJsonText(schema, line, {\n\t\t\t\t...options,\n\t\t\t\tsource: `${options.source}:${index + 1}`,\n\t\t\t}),\n\t);\n"],"mappings":";;;;;;;;;;;;;AA+BA,MAAM,SACL,SACA,SACA,WACyB;CACzB,QAAQ,QAAQ;CAChB,SAAS,QAAQ,WAAW;CAC5B,GAAI,UAAU,KAAA,IAAY,EAAE,GAAG,EAAE,OAAO;CACxC;AAED,MAAa,iBACZ,MACA,YAEA,OAAO,IAAI;CACV,WAAW,KAAK,MAAM,KAAK;CAC3B,QAAQ,UAAU,QAAQ,QAAQ,MAAM,SAAS,wBAAwB,MAAM,CAAC;CAChF,CAAC;AAEH,MAAa,qBAAwB,MAAc,YAAuC;AACzF,KAAI;AACH,SAAO,KAAK,MAAM,KAAK;UACf,OAAO;AACf,QAAM,QAAQ,QAAQ,MAAM,SAAS,wBAAwB,MAAM,CAAC;;;AAItE,MAAa,iBACZ,QACA,OACA,YAEA,OAAO,oBAAoB,OAAO,CAAC,MAAM,CAAC,KACzC,OAAO,UAAU,UAAU,QAAQ,QAAQ,MAAM,SAAS,0BAA0B,MAAM,CAAC,CAAC,CAC5F;AAEF,MAAa,qBACZ,QACA,OACA,YACe;AACf,KAAI;AACH,SAAO,OAAO,kBAAkB,OAAO,CAAC,MAAM;UACtC,OAAO;AACf,QAAM,QAAQ,QAAQ,MAAM,SAAS,0BAA0B,MAAM,CAAC;;;AAIxE,MAAa,kBACZ,QACA,MACA,YAEA,cAAc,MAAM,QAAQ,CAAC,KAC5B,OAAO,SAAS,UAAU,cAAc,QAAQ,OAAO,QAAQ,CAAC,CAChE;AAEF,MAAa,sBACZ,QACA,MACA,YACe,kBAAkB,QAAQ,kBAAkB,MAAM,QAAQ,EAAE,QAAQ;AAEpF,MAAa,8BACZ,QACA,MACA,YACe;CACf,MAAM,QAAQ,QAAQ,SAAS;CAC/B,MAAM,QAAQ,kBAAkB,MAAM,QAAQ;AAC9C,KAAI,CAAC,MAAM,QAAQ,MAAM,IAAI,MAAM,WAAW,KAAA,EAC7C,OAAM,QAAQ,QACb,MACC,SACA,QAAQ,kBAAkB,wCAAwC,SAClE,MACA,CACD;AAEF,QAAO,kBAAkB,QAAQ,MAAM,QAAQ,QAAQ;;AAGxD,MAAa,mBACZ,QACA,MACA,YAEA,OAAO,QACN,KACE,MAAM,SAAS,CACf,KAAK,SAAS,KAAK,MAAM,CAAC,CAC1B,QAAQ,SAAS,KAAK,SAAS,EAAE,GAClC,MAAM,UACN,eAAe,QAAQ,MAAM;CAC5B,GAAG;CACH,QAAQ,GAAG,QAAQ,OAAO,GAAG,QAAQ;CACrC,CAAC,CACH"}
+{"version":3,"file":"runtime-decode.mjs","names":[],"sources":["../../../src/substrate/runtime/runtime-decode.ts"],"sourcesContent":["// Compound Schema decode at trust boundaries — JSON / unknown →\n// typed values, with one parse/decode issue shape and typed error\n// projection. Reach for `decodeUnknown(Sync)` /\n// `decodeJsonText(Sync)` when you have a Schema and want to decode\n// a whole shape (multi-field, refinements, transforms).\n//\n// For one-field shape checks (\"port must be a positive integer\",\n// \"name must be a non-empty string\") that throw on bad input,\n// reach for the `expect*` helpers in `config-validation.ts` instead.\n\nimport { Effect, Schema } from 'effect';\n\nexport interface RuntimeDecodeIssue {\n\treadonly source: string;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport type RuntimeDecodeErrorFactory<E> = (issue: RuntimeDecodeIssue) => E;\n\nexport interface DecodeOptions<E> {\n\treadonly source: string;\n\treadonly mkError: RuntimeDecodeErrorFactory<E>;\n\treadonly message?: string;\n}\n\nexport interface JsonArrayElementDecodeOptions<E> extends DecodeOptions<E> {\n\treadonly index?: number;\n\treadonly missingMessage?: string;\n}\n\nconst issue = <E>(\n\toptions: DecodeOptions<E>,\n\tmessage: string,\n\tcause?: unknown,\n): RuntimeDecodeIssue => ({\n\tsource: options.source,\n\tmessage: options.message ?? message,\n\t...(cause === undefined ? {} : { cause }),\n});\n\nexport const parseJsonText = <E>(\n\ttext: string,\n\toptions: DecodeOptions<E>,\n): Effect.Effect<unknown, E> =>\n\tEffect.try({\n\t\ttry: () => JSON.parse(text) as unknown,\n\t\tcatch: (cause) => options.mkError(issue(options, 'failed to parse JSON', cause)),\n\t});\n\nexport const parseJsonTextSync = <E>(text: string, options: DecodeOptions<E>): unknown => {\n\ttry {\n\t\treturn JSON.parse(text) as unknown;\n\t} catch (cause) {\n\t\tthrow options.mkError(issue(options, 'failed to parse JSON', cause));\n\t}\n};\n\nexport const decodeUnknown = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\tvalue: unknown,\n\toptions: DecodeOptions<E>,\n): Effect.Effect<S['Type'], E> =>\n\tSchema.decodeUnknownEffect(schema)(value).pipe(\n\t\tEffect.mapError((cause) => options.mkError(issue(options, 'failed to decode value', cause))),\n\t);\n\nexport const decodeUnknownSync = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\tvalue: unknown,\n\toptions: DecodeOptions<E>,\n): S['Type'] => {\n\ttry {\n\t\treturn Schema.decodeUnknownSync(schema)(value);\n\t} catch (cause) {\n\t\tthrow options.mkError(issue(options, 'failed to decode value', cause));\n\t}\n};\n\nexport const decodeJsonText = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\ttext: string,\n\toptions: DecodeOptions<E>,\n): Effect.Effect<S['Type'], E> =>\n\tparseJsonText(text, options).pipe(\n\t\tEffect.flatMap((value) => decodeUnknown(schema, value, options)),\n\t);\n\nexport const decodeJsonTextSync = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\ttext: string,\n\toptions: DecodeOptions<E>,\n): S['Type'] => decodeUnknownSync(schema, parseJsonTextSync(text, options), options);\n\nexport const decodeJsonArrayElementSync = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\ttext: string,\n\toptions: JsonArrayElementDecodeOptions<E>,\n): S['Type'] => {\n\tconst index = options.index ?? 0;\n\tconst value = parseJsonTextSync(text, options);\n\tif (!Array.isArray(value) || value[index] === undefined) {\n\t\tthrow options.mkError(\n\t\t\tissue(\n\t\t\t\toptions,\n\t\t\t\toptions.missingMessage ?? `expected JSON array element at index ${index}`,\n\t\t\t\tvalue,\n\t\t\t),\n\t\t);\n\t}\n\treturn decodeUnknownSync(schema, value[index], options);\n};\n\nexport const decodeJsonLines = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\ttext: string,\n\toptions: DecodeOptions<E>,\n): Effect.Effect<ReadonlyArray<S['Type']>, E> =>\n\tEffect.forEach(\n\t\ttext\n\t\t\t.split(/\\r?\\n/u)\n\t\t\t.map((line) => line.trim())\n\t\t\t.filter((line) => line.length > 0),\n\t\t(line, index) =>\n\t\t\tdecodeJsonText(schema, line, {\n\t\t\t\t...options,\n\t\t\t\tsource: `${options.source}:${index + 1}`,\n\t\t\t}),\n\t);\n"],"mappings":";;;;;;;;;;;;;AA+BA,MAAM,SACL,SACA,SACA,WACyB;CACzB,QAAQ,QAAQ;CAChB,SAAS,QAAQ,WAAW;CAC5B,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;AACxC;AAEA,MAAa,iBACZ,MACA,YAEA,OAAO,IAAI;CACV,WAAW,KAAK,MAAM,IAAI;CAC1B,QAAQ,UAAU,QAAQ,QAAQ,MAAM,SAAS,wBAAwB,KAAK,CAAC;AAChF,CAAC;AAEF,MAAa,qBAAwB,MAAc,YAAuC;CACzF,IAAI;EACH,OAAO,KAAK,MAAM,IAAI;CACvB,SAAS,OAAO;EACf,MAAM,QAAQ,QAAQ,MAAM,SAAS,wBAAwB,KAAK,CAAC;CACpE;AACD;AAEA,MAAa,iBACZ,QACA,OACA,YAEA,OAAO,oBAAoB,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KACzC,OAAO,UAAU,UAAU,QAAQ,QAAQ,MAAM,SAAS,0BAA0B,KAAK,CAAC,CAAC,CAC5F;AAED,MAAa,qBACZ,QACA,OACA,YACe;CACf,IAAI;EACH,OAAO,OAAO,kBAAkB,MAAM,CAAC,CAAC,KAAK;CAC9C,SAAS,OAAO;EACf,MAAM,QAAQ,QAAQ,MAAM,SAAS,0BAA0B,KAAK,CAAC;CACtE;AACD;AAEA,MAAa,kBACZ,QACA,MACA,YAEA,cAAc,MAAM,OAAO,CAAC,CAAC,KAC5B,OAAO,SAAS,UAAU,cAAc,QAAQ,OAAO,OAAO,CAAC,CAChE;AAED,MAAa,sBACZ,QACA,MACA,YACe,kBAAkB,QAAQ,kBAAkB,MAAM,OAAO,GAAG,OAAO;AAEnF,MAAa,8BACZ,QACA,MACA,YACe;CACf,MAAM,QAAQ,QAAQ,SAAS;CAC/B,MAAM,QAAQ,kBAAkB,MAAM,OAAO;CAC7C,IAAI,CAAC,MAAM,QAAQ,KAAK,KAAK,MAAM,WAAW,KAAA,GAC7C,MAAM,QAAQ,QACb,MACC,SACA,QAAQ,kBAAkB,wCAAwC,SAClE,KACD,CACD;CAED,OAAO,kBAAkB,QAAQ,MAAM,QAAQ,OAAO;AACvD;AAEA,MAAa,mBACZ,QACA,MACA,YAEA,OAAO,QACN,KACE,MAAM,QAAQ,CAAC,CACf,KAAK,SAAS,KAAK,KAAK,CAAC,CAAC,CAC1B,QAAQ,SAAS,KAAK,SAAS,CAAC,IACjC,MAAM,UACN,eAAe,QAAQ,MAAM;CAC5B,GAAG;CACH,QAAQ,GAAG,QAAQ,OAAO,GAAG,QAAQ;AACtC,CAAC,CACH"}

package/dist/substrate/runtime/scoped-http-server.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"scoped-http-server.mjs","names":[],"sources":["../../../src/substrate/runtime/scoped-http-server.ts"],"sourcesContent":["// Scoped host HTTP server primitive.\n//\n// Generic ownership for in-process host HTTP listeners: bind, surface\n// listen failures through a caller-owned error mapper, and install a\n// scope finalizer that drops idle keepalive sockets before awaiting\n// close. Domain routing stays with the plugin that supplies the\n// Node request listener.\n\nimport { Effect } from 'effect';\nimport type { Scope } from 'effect';\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';\n\nexport type HttpRequestListener = (req: IncomingMessage, res: ServerResponse) => void;\n\nexport interface ScopedHttpServerOptions<E> {\n\treadonly bindAddress: string;\n\treadonly port: number;\n\treadonly listener: HttpRequestListener;\n\treadonly onListenError: (cause: unknown) => E;\n}\n\nexport interface ScopedHttpServerHandle {\n\treadonly url: string;\n\treadonly server: Server;\n\treadonly close: () => Effect.Effect<void>;\n}\n\n/** Best-effort graceful close. `closeAllConnections()` drops idle\n *  keepalive sockets so `close()` resolves; older Node versions\n *  without `closeAllConnections` rely on `close()` alone. */\nexport const gracefulCloseHttpServer = (server: Server): Effect.Effect<void> =>\n\tEffect.callback<void>((resume) => {\n\t\ttry {\n\t\t\tserver.closeAllConnections();\n\t\t} catch {\n\t\t\t// Older Node versions don't expose closeAllConnections;\n\t\t\t// `close()` alone will still terminate.\n\t\t}\n\t\tserver.close(() => resume(Effect.void));\n\t});\n\nexport const listenScopedHttpServer = <E>(\n\toptions: ScopedHttpServerOptions<E>,\n): Effect.Effect<ScopedHttpServerHandle, E, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\t// `acquireRelease` pairs the bound server with its close finalizer\n\t\t// atomically: the moment `listen` resolves, the graceful-close\n\t\t// finalizer is registered, so an interruption between bind and\n\t\t// finalizer registration can no longer leak a listener holding the\n\t\t// port.\n\t\tconst server = yield* Effect.acquireRelease(\n\t\t\tEffect.tryPromise({\n\t\t\t\ttry: () =>\n\t\t\t\t\tnew Promise<Server>((resolve, reject) => {\n\t\t\t\t\t\tconst srv = createServer(options.listener);\n\t\t\t\t\t\tconst onError = (err: Error) => reject(err);\n\t\t\t\t\t\tsrv.once('error', onError);\n\t\t\t\t\t\tsrv.listen(options.port, options.bindAddress, () => {\n\t\t\t\t\t\t\tsrv.removeListener('error', onError);\n\t\t\t\t\t\t\tresolve(srv);\n\t\t\t\t\t\t});\n\t\t\t\t\t}),\n\t\t\t\tcatch: options.onListenError,\n\t\t\t}),\n\t\t\t(srv) => gracefulCloseHttpServer(srv).pipe(Effect.uninterruptible),\n\t\t);\n\n\t\treturn {\n\t\t\turl: `http://${options.bindAddress}:${options.port}`,\n\t\t\tserver,\n\t\t\tclose: () => gracefulCloseHttpServer(server),\n\t\t};\n\t});\n"],"mappings":";;;;;;AA8BA,MAAa,2BAA2B,WACvC,OAAO,UAAgB,WAAW;AACjC,KAAI;AACH,SAAO,qBAAqB;SACrB;AAIR,QAAO,YAAY,OAAO,OAAO,KAAK,CAAC;EACtC;AAEH,MAAa,0BACZ,YAEA,OAAO,IAAI,aAAa;CAMvB,MAAM,SAAS,OAAO,OAAO,eAC5B,OAAO,WAAW;EACjB,WACC,IAAI,SAAiB,SAAS,WAAW;GACxC,MAAM,MAAM,aAAa,QAAQ,SAAS;GAC1C,MAAM,WAAW,QAAe,OAAO,IAAI;AAC3C,OAAI,KAAK,SAAS,QAAQ;AAC1B,OAAI,OAAO,QAAQ,MAAM,QAAQ,mBAAmB;AACnD,QAAI,eAAe,SAAS,QAAQ;AACpC,YAAQ,IAAI;KACX;IACD;EACH,OAAO,QAAQ;EACf,CAAC,GACD,QAAQ,wBAAwB,IAAI,CAAC,KAAK,OAAO,gBAAgB,CAClE;AAED,QAAO;EACN,KAAK,UAAU,QAAQ,YAAY,GAAG,QAAQ;EAC9C;EACA,aAAa,wBAAwB,OAAO;EAC5C;EACA"}
+{"version":3,"file":"scoped-http-server.mjs","names":[],"sources":["../../../src/substrate/runtime/scoped-http-server.ts"],"sourcesContent":["// Scoped host HTTP server primitive.\n//\n// Generic ownership for in-process host HTTP listeners: bind, surface\n// listen failures through a caller-owned error mapper, and install a\n// scope finalizer that drops idle keepalive sockets before awaiting\n// close. Domain routing stays with the plugin that supplies the\n// Node request listener.\n\nimport { Effect } from 'effect';\nimport type { Scope } from 'effect';\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';\n\nexport type HttpRequestListener = (req: IncomingMessage, res: ServerResponse) => void;\n\nexport interface ScopedHttpServerOptions<E> {\n\treadonly bindAddress: string;\n\treadonly port: number;\n\treadonly listener: HttpRequestListener;\n\treadonly onListenError: (cause: unknown) => E;\n}\n\nexport interface ScopedHttpServerHandle {\n\treadonly url: string;\n\treadonly server: Server;\n\treadonly close: () => Effect.Effect<void>;\n}\n\n/** Best-effort graceful close. `closeAllConnections()` drops idle\n *  keepalive sockets so `close()` resolves; older Node versions\n *  without `closeAllConnections` rely on `close()` alone. */\nexport const gracefulCloseHttpServer = (server: Server): Effect.Effect<void> =>\n\tEffect.callback<void>((resume) => {\n\t\ttry {\n\t\t\tserver.closeAllConnections();\n\t\t} catch {\n\t\t\t// Older Node versions don't expose closeAllConnections;\n\t\t\t// `close()` alone will still terminate.\n\t\t}\n\t\tserver.close(() => resume(Effect.void));\n\t});\n\nexport const listenScopedHttpServer = <E>(\n\toptions: ScopedHttpServerOptions<E>,\n): Effect.Effect<ScopedHttpServerHandle, E, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\t// `acquireRelease` pairs the bound server with its close finalizer\n\t\t// atomically: the moment `listen` resolves, the graceful-close\n\t\t// finalizer is registered, so an interruption between bind and\n\t\t// finalizer registration cannot leak a listener holding the port.\n\t\tconst server = yield* Effect.acquireRelease(\n\t\t\tEffect.tryPromise({\n\t\t\t\ttry: () =>\n\t\t\t\t\tnew Promise<Server>((resolve, reject) => {\n\t\t\t\t\t\tconst srv = createServer(options.listener);\n\t\t\t\t\t\tconst onError = (err: Error) => reject(err);\n\t\t\t\t\t\tsrv.once('error', onError);\n\t\t\t\t\t\tsrv.listen(options.port, options.bindAddress, () => {\n\t\t\t\t\t\t\tsrv.removeListener('error', onError);\n\t\t\t\t\t\t\tresolve(srv);\n\t\t\t\t\t\t});\n\t\t\t\t\t}),\n\t\t\t\tcatch: options.onListenError,\n\t\t\t}),\n\t\t\t(srv) => gracefulCloseHttpServer(srv).pipe(Effect.uninterruptible),\n\t\t);\n\n\t\treturn {\n\t\t\turl: `http://${options.bindAddress}:${options.port}`,\n\t\t\tserver,\n\t\t\tclose: () => gracefulCloseHttpServer(server),\n\t\t};\n\t});\n"],"mappings":";;;;;;AA8BA,MAAa,2BAA2B,WACvC,OAAO,UAAgB,WAAW;CACjC,IAAI;EACH,OAAO,oBAAoB;CAC5B,QAAQ,CAGR;CACA,OAAO,YAAY,OAAO,OAAO,IAAI,CAAC;AACvC,CAAC;AAEF,MAAa,0BACZ,YAEA,OAAO,IAAI,aAAa;CAKvB,MAAM,SAAS,OAAO,OAAO,eAC5B,OAAO,WAAW;EACjB,WACC,IAAI,SAAiB,SAAS,WAAW;GACxC,MAAM,MAAM,aAAa,QAAQ,QAAQ;GACzC,MAAM,WAAW,QAAe,OAAO,GAAG;GAC1C,IAAI,KAAK,SAAS,OAAO;GACzB,IAAI,OAAO,QAAQ,MAAM,QAAQ,mBAAmB;IACnD,IAAI,eAAe,SAAS,OAAO;IACnC,QAAQ,GAAG;GACZ,CAAC;EACF,CAAC;EACF,OAAO,QAAQ;CAChB,CAAC,IACA,QAAQ,wBAAwB,GAAG,CAAC,CAAC,KAAK,OAAO,eAAe,CAClE;CAEA,OAAO;EACN,KAAK,UAAU,QAAQ,YAAY,GAAG,QAAQ;EAC9C;EACA,aAAa,wBAAwB,MAAM;CAC5C;AACD,CAAC"}

package/dist/substrate/runtime/stage-and-swap/index.mjs

@@ -1,5 +1,5 @@
-import { SpanAttr } from "../observability/spans.mjs";
 import { acquireStackLock } from "../cross-process/stack-lock.mjs";
+import { LogAttr } from "../observability/log-attrs.mjs";
 import { Effect, FileSystem, Schema } from "effect";
 import { dirname, isAbsolute, join, normalize, sep } from "node:path";
 //#region src/substrate/runtime/stage-and-swap/index.ts
@@ -55,6 +55,35 @@ const errnoCode = (cause) => {
 	const directCause = cause.cause;
 	return codeOf(reasonCause) ?? codeOf(directCause) ?? codeOf(cause);
 };
+/**
+* Roll a backed-up target back into place after a failed publish.
+*
+* The forward path renamed the live target away to `backupPath`; on any
+* subsequent failure we must put it back at `targetPath` so the world looks
+* exactly as it did at entry (contract item 5). The naive `rename(backupPath,
+* targetPath)` throws `ENOTEMPTY`/`EEXIST` if `targetPath` is unexpectedly
+* non-empty — e.g. a half-written staging tree that a prior interrupted run on
+* a reused state-dir left behind, or a leftover `.bak.<id>`. That rollback
+* bookkeeping failing is NOT a publish failure (the ORIGINAL `cause` is what we
+* surface); it's recoverable cosmetic state.
+*
+* So: reap any pre-existing `targetPath` first (recursive+force, idempotent) so
+* the rename can't collide, then rename. If the rename STILL fails we log a
+* recoverable WARNING and swallow it — the caller's original error is the real
+* outcome and we must not mask it with a `restore-backup` tag.
+*/
+const restoreBackupRename = (args) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	yield* fs.remove(args.targetPath, {
+		recursive: true,
+		force: true
+	}).pipe(Effect.ignore);
+	yield* fs.rename(args.backupPath, args.targetPath).pipe(Effect.catch((cause) => Effect.logWarning("stage-and-swap rollback-backup restore did not complete").pipe(Effect.annotateLogs({
+		[LogAttr.stageAndSwapTargetPath]: args.targetPath,
+		[LogAttr.stageAndSwapStagingPath]: args.stagingPath,
+		[LogAttr.errorCode]: errnoCode(cause) ?? "unknown"
+	}))));
+});
 const normalizePreservedRelativePath = (relativePath) => {
 	const normalized = normalize(relativePath);
 	if (relativePath.length === 0 || isAbsolute(relativePath) || normalized === "." || normalized === ".." || normalized.startsWith(`..${sep}`)) return null;
@@ -128,10 +157,6 @@ const stageAndSwap = (args) => Effect.gen(function* () {
 	const { targetPath, build, preserveFromTarget = [], preserveOnPreseed = false, publishLockPath } = args;
 	const stagingPath = args.stagingPath ?? `${targetPath}.staging.${args.idSuffix}`;
 	const backupPath = args.backupPath ?? `${targetPath}.bak.${args.idSuffix}`;
-	yield* Effect.annotateCurrentSpan({
-		"devstack.stage-and-swap.target": targetPath,
-		"devstack.stage-and-swap.staging": stagingPath
-	});
 	yield* fs.remove(stagingPath, {
 		recursive: true,
 		force: true
@@ -161,19 +186,27 @@ const stageAndSwap = (args) => Effect.gen(function* () {
 				stagingPath,
 				preservedPaths: preserveFromTarget
 			}).pipe(Effect.catch((error) => Effect.gen(function* () {
-				yield* fs.rename(backupPath, targetPath).pipe(Effect.catch(failStage("restore-backup", targetPath, stagingPath)));
+				yield* restoreBackupRename({
+					backupPath,
+					targetPath,
+					stagingPath
+				});
 				return yield* Effect.fail(error);
 			})));
 		}
 		yield* fs.rename(stagingPath, targetPath).pipe(Effect.catch((cause) => {
 			if (errnoCode(cause) === "EXDEV") return Effect.gen(function* () {
 				yield* Effect.logWarning("stage-and-swap cross-filesystem fallback").pipe(Effect.annotateLogs({
-					[SpanAttr.stageAndSwapTargetPath]: targetPath,
-					[SpanAttr.stageAndSwapStagingPath]: stagingPath,
-					[SpanAttr.errorCode]: "EXDEV"
+					[LogAttr.stageAndSwapTargetPath]: targetPath,
+					[LogAttr.stageAndSwapStagingPath]: stagingPath,
+					[LogAttr.errorCode]: "EXDEV"
 				}));
 				yield* fs.copy(stagingPath, targetPath, { overwrite: false }).pipe(Effect.catch((copyCause) => Effect.gen(function* () {
-					if (targetExists) yield* fs.rename(backupPath, targetPath).pipe(Effect.catch(failStage("restore-backup", targetPath, stagingPath)));
+					if (targetExists) yield* restoreBackupRename({
+						backupPath,
+						targetPath,
+						stagingPath
+					});
 					return yield* failStage("cross-filesystem-fallback", targetPath, stagingPath)(copyCause);
 				})));
 				yield* fs.remove(stagingPath, {
@@ -182,7 +215,11 @@ const stageAndSwap = (args) => Effect.gen(function* () {
 				}).pipe(Effect.ignore);
 			});
 			return Effect.gen(function* () {
-				if (targetExists) yield* fs.rename(backupPath, targetPath).pipe(Effect.catch(failStage("restore-backup", targetPath, stagingPath)));
+				if (targetExists) yield* restoreBackupRename({
+					backupPath,
+					targetPath,
+					stagingPath
+				});
 				return yield* failStage("rename-into-target", targetPath, stagingPath)(cause);
 			});
 		}));
@@ -192,7 +229,7 @@ const stageAndSwap = (args) => Effect.gen(function* () {
 		force: true
 	}).pipe(Effect.ignore);
 	return result;
-}).pipe(Effect.withSpan("substrate.stage-and-swap"));
+});
 //#endregion
 export { StageAndSwapError, stageAndSwap };
 

package/dist/substrate/runtime/stage-and-swap/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/substrate/runtime/stage-and-swap/index.ts"],"sourcesContent":["// Atomic stage-and-swap primitive.\n//\n// Architecture §\"Stage-and-swap rollback discipline is precious and\n// well-tested\": one tempdir, one rename for the whole publish.\n// Lifted to substrate so both snapshot AND codegen (per-cycle outer\n// swap) can consume — see ARCHITECTURE.md substrate roster + style\n// guide §19 (Open slot O14 closes with this lift).\n//\n// Contract:\n//   1. The caller provides a `targetPath` (the directory to publish).\n//   2. The orchestrator runs the build effect with a `stagingPath`\n//      (a sibling under the same parent so the rename stays on the\n//      same filesystem — POSIX rename atomicity is per-filesystem).\n//   3. If the build effect succeeds AND the rename succeeds, the\n//      target now points at the new tree; external watchers never\n//      observed a half-written intermediate.\n//   4. Optional `preserveFromTarget` paths are copied from the backed-up\n//      target into staging immediately before publish.\n//   5. On any failure the staging directory is removed; the previous\n//      target (if any) is restored verbatim from a same-parent\n//      backup.\n//   6. Cross-filesystem fallback (`EXDEV` from rename) logs and falls\n//      back to copy-then-rm — the architecture's documented exception.\n//\n// Discipline carried verbatim from the legacy `engine/snapshot/stage-\n// and-swap.ts` (distilled §17).\n\nimport { dirname, isAbsolute, join, normalize, sep } from 'node:path';\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport { acquireStackLock } from '../cross-process/stack-lock.ts';\nimport { SpanAttr } from '../observability/spans.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** Tagged failure during a stage-and-swap step. `stage` discriminates\n *  the precise failing step; the caller's underlying tag is preserved\n *  via `cause` (the primitive does NOT wrap the user's error). */\nexport class StageAndSwapError extends Schema.TaggedErrorClass<StageAndSwapError>()(\n\t'StageAndSwapError',\n\t{\n\t\tstage: Schema.Literals([\n\t\t\t'mkdir-staging',\n\t\t\t'mkdir-backup',\n\t\t\t'build',\n\t\t\t'acquire-publish-lock',\n\t\t\t'backup-current',\n\t\t\t'preserve-target-paths',\n\t\t\t'rename-into-target',\n\t\t\t'restore-backup',\n\t\t\t'cleanup-staging',\n\t\t\t'cross-filesystem-fallback',\n\t\t]),\n\t\ttargetPath: Schema.String,\n\t\tstagingPath: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n// -----------------------------------------------------------------------------\n// Primitive\n// -----------------------------------------------------------------------------\n\nexport interface StageAndSwapPreservedPath {\n\treadonly relativePath: string;\n\treadonly kind: 'file' | 'directory';\n\t/** When `false`, the backed-up live copy is preserved into staging ONLY if\n\t *  staging does not already carry the path — so a value the build already\n\t *  placed there (e.g. a deploy cache untarred from the snapshot's host-tree)\n\t *  WINS over the live copy. For a `directory` entry the skip is\n\t *  all-or-nothing, not a per-file merge: if staging already has the dir, the\n\t *  ENTIRE live copy is dropped, including any sub-path that existed only live\n\t *  (post-snapshot drift) — the intended \"restore-to-snapshot wins\" semantic.\n\t *  Defaults to `true` (always overwrite the staging copy with the live one). */\n\treadonly overwrite?: boolean;\n}\n\nconst failStage =\n\t<S extends StageAndSwapError['stage']>(\n\t\tstage: S,\n\t\ttargetPath: string,\n\t\tstagingPath: string,\n\t): ((cause: unknown) => Effect.Effect<never, StageAndSwapError>) =>\n\t(cause) =>\n\t\tEffect.fail(new StageAndSwapError({ stage, targetPath, stagingPath, cause }));\n\n/**\n * Extract the original Node errno `code` from a `FileSystem.rename` failure.\n *\n * Effect v4's `@effect/platform-node` wraps the raw `NodeJS.ErrnoException`\n * (`handleErrnoException` in `platform-node-shared/internal/utils.ts`) into a\n * `PlatformError` whose `reason` is a `SystemError`. The raw errno is preserved\n * as `reason.cause` (the unmodified Node error) — and the `PlatformError`\n * constructor additionally hoists that to the wrapper's own top-level `cause`.\n * So a genuine cross-filesystem rename surfaces the code at `reason.cause.code`\n * (and, equivalently, at `cause.cause.code`), NOT at the top-level `.code`.\n *\n * We probe every plausible location defensively: the nested SystemError cause,\n * the hoisted wrapper cause, and a bare-errno shape (in case a caller injects a\n * raw `NodeJS.ErrnoException` or the wrapping ever changes).\n */\nconst errnoCode = (cause: unknown): string | undefined => {\n\tconst codeOf = (value: unknown): string | undefined => {\n\t\tif (typeof value !== 'object' || value === null) return undefined;\n\t\tconst code = (value as { code?: unknown }).code;\n\t\treturn typeof code === 'string' ? code : undefined;\n\t};\n\tif (typeof cause !== 'object' || cause === null) return undefined;\n\tconst reasonCause = (cause as { reason?: { cause?: unknown } }).reason?.cause;\n\tconst directCause = (cause as { cause?: unknown }).cause;\n\treturn codeOf(reasonCause) ?? codeOf(directCause) ?? codeOf(cause);\n};\n\nconst normalizePreservedRelativePath = (relativePath: string): string | null => {\n\tconst normalized = normalize(relativePath);\n\tif (\n\t\trelativePath.length === 0 ||\n\t\tisAbsolute(relativePath) ||\n\t\tnormalized === '.' ||\n\t\tnormalized === '..' ||\n\t\tnormalized.startsWith(`..${sep}`)\n\t) {\n\t\treturn null;\n\t}\n\treturn normalized;\n};\n\nconst preserveTargetPaths = (args: {\n\treadonly backupPath: string;\n\treadonly targetPath: string;\n\treadonly stagingPath: string;\n\treadonly preservedPaths: ReadonlyArray<StageAndSwapPreservedPath>;\n}): Effect.Effect<void, StageAndSwapError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tfor (const preserved of args.preservedPaths) {\n\t\t\tconst relativePath = normalizePreservedRelativePath(preserved.relativePath);\n\t\t\tif (relativePath === null) {\n\t\t\t\treturn yield* failStage(\n\t\t\t\t\t'preserve-target-paths',\n\t\t\t\t\targs.targetPath,\n\t\t\t\t\targs.stagingPath,\n\t\t\t\t)(new Error(`unsafe preserved path: ${preserved.relativePath}`));\n\t\t\t}\n\t\t\tconst source = join(args.backupPath, relativePath);\n\t\t\tconst exists = yield* fs.exists(source).pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\tif (!exists) continue;\n\t\t\tconst target = join(args.stagingPath, relativePath);\n\t\t\t// `overwrite: false` — don't clobber a path the build already placed in\n\t\t\t// staging (e.g. a deploy cache the snapshot captured into the host-tree\n\t\t\t// tar): that captured copy is consistent with the restored chain, so it\n\t\t\t// WINS over the live copy. The live copy is only a fallback when staging\n\t\t\t// doesn't already carry it (e.g. a pre-capture snapshot).\n\t\t\tif (preserved.overwrite === false) {\n\t\t\t\tconst targetExists = yield* fs\n\t\t\t\t\t.exists(target)\n\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\t\tif (targetExists) continue;\n\t\t\t}\n\t\t\tyield* fs\n\t\t\t\t.makeDirectory(dirname(target), { recursive: true })\n\t\t\t\t.pipe(Effect.catch(failStage('preserve-target-paths', args.targetPath, args.stagingPath)));\n\t\t\tyield* fs\n\t\t\t\t.copy(source, target, { overwrite: true })\n\t\t\t\t.pipe(Effect.catch(failStage('preserve-target-paths', args.targetPath, args.stagingPath)));\n\t\t}\n\t});\n\n/**\n * Build-then-swap. `build` is a user effect that populates `stagingPath`;\n * on success the helper:\n *\n *   - backs up the current `targetPath` (if any) to `<targetPath>.bak.<pid>`,\n *   - copies any selected `preserveFromTarget` paths from that backup\n *     into staging,\n *   - renames `stagingPath` → `targetPath`,\n *   - removes the backup.\n *\n * On any failure the helper removes `stagingPath` and, if the backup\n * was taken, renames it back to `targetPath` so the world looks\n * exactly as it did at entry.\n *\n * The build effect's error type passes through unchanged — the\n * primitive returns `E | StageAndSwapError`. This is the\n * \"preserve the caller's error tag\" rule from distilled §17.\n *\n * IMPORTANT: stagingPath MUST be on the same filesystem as\n * targetPath. The helper picks it as a sibling under the same parent\n * (caller passes `parentDir`, we mint the names) — this is enforced\n * by the helper's signature shape.\n *\n * ## Two call shapes\n *\n *   - Explicit-paths: callers that need bespoke sibling names (the\n *     Seal plugin uses `.backup.` not `.bak.`; pre-existing tests use\n *     literal `target.staging`/`target.bak`) pass both `stagingPath`\n *     and `backupPath` directly.\n *   - `idSuffix`: callers (codegen, snapshot) pass `idSuffix` and the\n *     primitive mints `<targetPath>.staging.<idSuffix>` /\n *     `<targetPath>.bak.<idSuffix>` so the staging/backup-naming\n *     convention is owned in ONE place. Callers MUST NOT pass both\n *     `idSuffix` and explicit paths.\n *\n * ## `preserveOnPreseed`\n *\n * When `true`, before the user's `build` runs the primitive copies the\n * current `targetPath` (if any) into `stagingPath` so `build` can\n * mutate that baseline incrementally. This subsumes the codegen\n * orchestrator's pre-seed dance (per-file no-touch idempotency relies\n * on seeing the previous target's mtimes). Cross-cutting with\n * `preserveFromTarget` is allowed: pre-seed clones the whole tree\n * BEFORE the build; `preserveFromTarget` cherry-picks paths AFTER the\n * build and BEFORE the swap (and reads from the backup, so the build\n * may have rewritten them in-tree). The two features answer different\n * questions and the primitive runs them in that order.\n */\nexport const stageAndSwap = <A, E>(\n\targs: {\n\t\treadonly targetPath: string;\n\t\treadonly build: Effect.Effect<A, E, FileSystem.FileSystem>;\n\t\treadonly preserveFromTarget?: ReadonlyArray<StageAndSwapPreservedPath>;\n\t\treadonly preserveOnPreseed?: boolean;\n\t\treadonly publishLockPath?: string;\n\t} & (\n\t\t| { readonly stagingPath: string; readonly backupPath: string; readonly idSuffix?: never }\n\t\t| { readonly idSuffix: string; readonly stagingPath?: never; readonly backupPath?: never }\n\t),\n): Effect.Effect<A, E | StageAndSwapError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst {\n\t\t\ttargetPath,\n\t\t\tbuild,\n\t\t\tpreserveFromTarget = [],\n\t\t\tpreserveOnPreseed = false,\n\t\t\tpublishLockPath,\n\t\t} = args;\n\t\tconst stagingPath =\n\t\t\targs.stagingPath ?? `${targetPath}.staging.${(args as { idSuffix: string }).idSuffix}`;\n\t\tconst backupPath =\n\t\t\targs.backupPath ?? `${targetPath}.bak.${(args as { idSuffix: string }).idSuffix}`;\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.stage-and-swap.target': targetPath,\n\t\t\t'devstack.stage-and-swap.staging': stagingPath,\n\t\t});\n\n\t\t// 0. Pre-clean the staging slot (a previous crash may have left\n\t\t//    a sibling). recursive+force is idempotent.\n\t\tyield* fs.remove(stagingPath, { recursive: true, force: true }).pipe(Effect.ignore);\n\t\tyield* fs\n\t\t\t.makeDirectory(stagingPath, { recursive: true })\n\t\t\t.pipe(Effect.catch(failStage('mkdir-staging', targetPath, stagingPath)));\n\n\t\t// 0a. Optional pre-seed: when `preserveOnPreseed`, clone the\n\t\t//     current target into staging so the build can edit it\n\t\t//     incrementally (codegen needs this for per-file no-touch\n\t\t//     idempotency). `preserveTimestamps: true` keeps mtimes\n\t\t//     intact so HMR watchers (Vite/Turbopack — they trigger on\n\t\t//     mtime, not content) stay quiet for unchanged outputs.\n\t\tif (preserveOnPreseed) {\n\t\t\tconst targetExistsForPreseed = yield* fs\n\t\t\t\t.exists(targetPath)\n\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\tif (targetExistsForPreseed) {\n\t\t\t\tyield* fs.copy(targetPath, stagingPath, { overwrite: true, preserveTimestamps: true }).pipe(\n\t\t\t\t\tEffect.catch(failStage('mkdir-staging', targetPath, stagingPath)),\n\t\t\t\t\tEffect.onError(() =>\n\t\t\t\t\t\tfs.remove(stagingPath, { recursive: true, force: true }).pipe(Effect.ignore),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\t// 1. Run the user's build inside the staging directory. On\n\t\t//    failure clean up the staging dir (best-effort) BEFORE\n\t\t//    re-raising — preserves the caller's error tag (no wrap).\n\t\tconst result = yield* build.pipe(\n\t\t\tEffect.onError(() =>\n\t\t\t\tfs.remove(stagingPath, { recursive: true, force: true }).pipe(Effect.ignore),\n\t\t\t),\n\t\t);\n\n\t\t// 2. Backup the current target and promote staging while holding\n\t\t//    an optional caller-supplied lock. Restore uses this to block\n\t\t//    command/event writers while the stack root path is absent.\n\t\tconst targetExists = yield* Effect.scoped(\n\t\t\tEffect.gen(function* () {\n\t\t\t\tif (publishLockPath !== undefined) {\n\t\t\t\t\tyield* acquireStackLock(publishLockPath).pipe(\n\t\t\t\t\t\tEffect.catch(failStage('acquire-publish-lock', targetPath, stagingPath)),\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tconst targetExists = yield* fs\n\t\t\t\t\t.exists(targetPath)\n\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\t\tif (targetExists) {\n\t\t\t\t\t// Move current → backup (atomic rename on same filesystem).\n\t\t\t\t\tyield* fs\n\t\t\t\t\t\t.rename(targetPath, backupPath)\n\t\t\t\t\t\t.pipe(Effect.catch(failStage('backup-current', targetPath, stagingPath)));\n\t\t\t\t\tyield* preserveTargetPaths({\n\t\t\t\t\t\tbackupPath,\n\t\t\t\t\t\ttargetPath,\n\t\t\t\t\t\tstagingPath,\n\t\t\t\t\t\tpreservedPaths: preserveFromTarget,\n\t\t\t\t\t}).pipe(\n\t\t\t\t\t\tEffect.catch((error) =>\n\t\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\t\tyield* fs\n\t\t\t\t\t\t\t\t\t.rename(backupPath, targetPath)\n\t\t\t\t\t\t\t\t\t.pipe(Effect.catch(failStage('restore-backup', targetPath, stagingPath)));\n\t\t\t\t\t\t\t\treturn yield* Effect.fail(error);\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\n\t\t\t\t// 3. Promote staging → target. This is the atomic publish step.\n\t\t\t\tyield* fs.rename(stagingPath, targetPath).pipe(\n\t\t\t\t\tEffect.catch((cause) => {\n\t\t\t\t\t\t// A real Effect v4 `rename` failure is a PlatformError whose\n\t\t\t\t\t\t// raw Node errno lives at `reason.cause.code` (and the hoisted\n\t\t\t\t\t\t// `cause.cause.code`), NOT the top-level `.code` — see errnoCode.\n\t\t\t\t\t\tif (errnoCode(cause) === 'EXDEV') {\n\t\t\t\t\t\t\t// Cross-filesystem fallback — architecture's documented\n\t\t\t\t\t\t\t// exception. Log loudly; copy then rm. The atomicity\n\t\t\t\t\t\t\t// guarantee is LOST in this branch.\n\t\t\t\t\t\t\treturn Effect.gen(function* () {\n\t\t\t\t\t\t\t\tyield* Effect.logWarning('stage-and-swap cross-filesystem fallback').pipe(\n\t\t\t\t\t\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t\t\t\t\t\t[SpanAttr.stageAndSwapTargetPath]: targetPath,\n\t\t\t\t\t\t\t\t\t\t[SpanAttr.stageAndSwapStagingPath]: stagingPath,\n\t\t\t\t\t\t\t\t\t\t[SpanAttr.errorCode]: 'EXDEV',\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\tyield* fs.copy(stagingPath, targetPath, { overwrite: false }).pipe(\n\t\t\t\t\t\t\t\t\tEffect.catch((copyCause) =>\n\t\t\t\t\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\t\t\t\t\t// Copy failed mid-fallback. Mirror the same-FS branch:\n\t\t\t\t\t\t\t\t\t\t\t// if we backed a target up, restore it verbatim before\n\t\t\t\t\t\t\t\t\t\t\t// surfacing the original tag (contract item 5).\n\t\t\t\t\t\t\t\t\t\t\tif (targetExists) {\n\t\t\t\t\t\t\t\t\t\t\t\tyield* fs\n\t\t\t\t\t\t\t\t\t\t\t\t\t.rename(backupPath, targetPath)\n\t\t\t\t\t\t\t\t\t\t\t\t\t.pipe(Effect.catch(failStage('restore-backup', targetPath, stagingPath)));\n\t\t\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\t\t\treturn yield* failStage(\n\t\t\t\t\t\t\t\t\t\t\t\t'cross-filesystem-fallback',\n\t\t\t\t\t\t\t\t\t\t\t\ttargetPath,\n\t\t\t\t\t\t\t\t\t\t\t\tstagingPath,\n\t\t\t\t\t\t\t\t\t\t\t)(copyCause);\n\t\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\tyield* fs.remove(stagingPath, { recursive: true, force: true }).pipe(Effect.ignore);\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// Same-filesystem rename failed. Restore backup if we took\n\t\t\t\t\t\t// one; surface the original tag.\n\t\t\t\t\t\treturn Effect.gen(function* () {\n\t\t\t\t\t\t\tif (targetExists) {\n\t\t\t\t\t\t\t\tyield* fs\n\t\t\t\t\t\t\t\t\t.rename(backupPath, targetPath)\n\t\t\t\t\t\t\t\t\t.pipe(Effect.catch(failStage('restore-backup', targetPath, stagingPath)));\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\treturn yield* failStage('rename-into-target', targetPath, stagingPath)(cause);\n\t\t\t\t\t\t});\n\t\t\t\t\t}),\n\t\t\t\t);\n\n\t\t\t\treturn targetExists;\n\t\t\t}),\n\t\t);\n\n\t\t// 4. Drop the backup. Failure here is observable but non-fatal:\n\t\t//    the new target is live; an orphan backup is cosmetic.\n\t\tif (targetExists) {\n\t\t\tyield* fs.remove(backupPath, { recursive: true, force: true }).pipe(Effect.ignore);\n\t\t}\n\n\t\treturn result;\n\t}).pipe(Effect.withSpan('substrate.stage-and-swap'));\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/substrate/runtime/stage-and-swap/index.ts"],"sourcesContent":["// Atomic stage-and-swap primitive.\n//\n// Architecture §\"Stage-and-swap rollback discipline is precious and\n// well-tested\": one tempdir, one rename for the whole publish.\n// Lifted to substrate so both snapshot AND codegen (per-cycle outer\n// swap) can consume — see ARCHITECTURE.md substrate roster + style\n// guide §19 (Open slot O14 closes with this lift).\n//\n// Contract:\n//   1. The caller provides a `targetPath` (the directory to publish).\n//   2. The orchestrator runs the build effect with a `stagingPath`\n//      (a sibling under the same parent so the rename stays on the\n//      same filesystem — POSIX rename atomicity is per-filesystem).\n//   3. If the build effect succeeds AND the rename succeeds, the\n//      target now points at the new tree; external watchers never\n//      observed a half-written intermediate.\n//   4. Optional `preserveFromTarget` paths are copied from the backed-up\n//      target into staging immediately before publish.\n//   5. On any failure the staging directory is removed; the previous\n//      target (if any) is restored verbatim from a same-parent\n//      backup.\n//   6. Cross-filesystem fallback (`EXDEV` from rename) logs and falls\n//      back to copy-then-rm — the architecture's documented exception.\n//\n// Atomic stage-and-swap discipline (distilled §17).\n\nimport { dirname, isAbsolute, join, normalize, sep } from 'node:path';\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport { acquireStackLock } from '../cross-process/stack-lock.ts';\nimport { LogAttr } from '../observability/log-attrs.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** Tagged failure during a stage-and-swap step. `stage` discriminates\n *  the precise failing step; the caller's underlying tag is preserved\n *  via `cause` (the primitive does NOT wrap the user's error). */\nexport class StageAndSwapError extends Schema.TaggedErrorClass<StageAndSwapError>()(\n\t'StageAndSwapError',\n\t{\n\t\tstage: Schema.Literals([\n\t\t\t'mkdir-staging',\n\t\t\t'mkdir-backup',\n\t\t\t'build',\n\t\t\t'acquire-publish-lock',\n\t\t\t'backup-current',\n\t\t\t'preserve-target-paths',\n\t\t\t'rename-into-target',\n\t\t\t'restore-backup',\n\t\t\t'cleanup-staging',\n\t\t\t'cross-filesystem-fallback',\n\t\t]),\n\t\ttargetPath: Schema.String,\n\t\tstagingPath: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n// -----------------------------------------------------------------------------\n// Primitive\n// -----------------------------------------------------------------------------\n\nexport interface StageAndSwapPreservedPath {\n\treadonly relativePath: string;\n\t/** When `false`, the backed-up live copy is preserved into staging ONLY if\n\t *  staging does not already carry the path — so a value the build already\n\t *  placed there (e.g. a deploy cache untarred from the snapshot's host-tree)\n\t *  WINS over the live copy. For a `directory` entry the skip is\n\t *  all-or-nothing, not a per-file merge: if staging already has the dir, the\n\t *  ENTIRE live copy is dropped, including any sub-path that existed only live\n\t *  (post-snapshot drift) — the intended \"restore-to-snapshot wins\" semantic.\n\t *  Defaults to `true` (always overwrite the staging copy with the live one). */\n\treadonly overwrite?: boolean;\n}\n\nconst failStage =\n\t<S extends StageAndSwapError['stage']>(\n\t\tstage: S,\n\t\ttargetPath: string,\n\t\tstagingPath: string,\n\t): ((cause: unknown) => Effect.Effect<never, StageAndSwapError>) =>\n\t(cause) =>\n\t\tEffect.fail(new StageAndSwapError({ stage, targetPath, stagingPath, cause }));\n\n/**\n * Extract the original Node errno `code` from a `FileSystem.rename` failure.\n *\n * Effect v4's `@effect/platform-node` wraps the raw `NodeJS.ErrnoException`\n * (`handleErrnoException` in `platform-node-shared/internal/utils.ts`) into a\n * `PlatformError` whose `reason` is a `SystemError`. The raw errno is preserved\n * as `reason.cause` (the unmodified Node error) — and the `PlatformError`\n * constructor additionally hoists that to the wrapper's own top-level `cause`.\n * So a genuine cross-filesystem rename surfaces the code at `reason.cause.code`\n * (and, equivalently, at `cause.cause.code`), NOT at the top-level `.code`.\n *\n * We probe every plausible location defensively: the nested SystemError cause,\n * the hoisted wrapper cause, and a bare-errno shape (in case a caller injects a\n * raw `NodeJS.ErrnoException` or the wrapping ever changes).\n */\nconst errnoCode = (cause: unknown): string | undefined => {\n\tconst codeOf = (value: unknown): string | undefined => {\n\t\tif (typeof value !== 'object' || value === null) return undefined;\n\t\tconst code = (value as { code?: unknown }).code;\n\t\treturn typeof code === 'string' ? code : undefined;\n\t};\n\tif (typeof cause !== 'object' || cause === null) return undefined;\n\tconst reasonCause = (cause as { reason?: { cause?: unknown } }).reason?.cause;\n\tconst directCause = (cause as { cause?: unknown }).cause;\n\treturn codeOf(reasonCause) ?? codeOf(directCause) ?? codeOf(cause);\n};\n\n/**\n * Roll a backed-up target back into place after a failed publish.\n *\n * The forward path renamed the live target away to `backupPath`; on any\n * subsequent failure we must put it back at `targetPath` so the world looks\n * exactly as it did at entry (contract item 5). The naive `rename(backupPath,\n * targetPath)` throws `ENOTEMPTY`/`EEXIST` if `targetPath` is unexpectedly\n * non-empty — e.g. a half-written staging tree that a prior interrupted run on\n * a reused state-dir left behind, or a leftover `.bak.<id>`. That rollback\n * bookkeeping failing is NOT a publish failure (the ORIGINAL `cause` is what we\n * surface); it's recoverable cosmetic state.\n *\n * So: reap any pre-existing `targetPath` first (recursive+force, idempotent) so\n * the rename can't collide, then rename. If the rename STILL fails we log a\n * recoverable WARNING and swallow it — the caller's original error is the real\n * outcome and we must not mask it with a `restore-backup` tag.\n */\nconst restoreBackupRename = (args: {\n\treadonly backupPath: string;\n\treadonly targetPath: string;\n\treadonly stagingPath: string;\n}): Effect.Effect<void, never, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\t// Reap a non-empty destination so the rollback rename can't ENOTEMPTY.\n\t\tyield* fs.remove(args.targetPath, { recursive: true, force: true }).pipe(Effect.ignore);\n\t\tyield* fs.rename(args.backupPath, args.targetPath).pipe(\n\t\t\tEffect.catch((cause) =>\n\t\t\t\tEffect.logWarning('stage-and-swap rollback-backup restore did not complete').pipe(\n\t\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t\t[LogAttr.stageAndSwapTargetPath]: args.targetPath,\n\t\t\t\t\t\t[LogAttr.stageAndSwapStagingPath]: args.stagingPath,\n\t\t\t\t\t\t[LogAttr.errorCode]: errnoCode(cause) ?? 'unknown',\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\t);\n\t});\n\nconst normalizePreservedRelativePath = (relativePath: string): string | null => {\n\tconst normalized = normalize(relativePath);\n\tif (\n\t\trelativePath.length === 0 ||\n\t\tisAbsolute(relativePath) ||\n\t\tnormalized === '.' ||\n\t\tnormalized === '..' ||\n\t\tnormalized.startsWith(`..${sep}`)\n\t) {\n\t\treturn null;\n\t}\n\treturn normalized;\n};\n\nconst preserveTargetPaths = (args: {\n\treadonly backupPath: string;\n\treadonly targetPath: string;\n\treadonly stagingPath: string;\n\treadonly preservedPaths: ReadonlyArray<StageAndSwapPreservedPath>;\n}): Effect.Effect<void, StageAndSwapError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tfor (const preserved of args.preservedPaths) {\n\t\t\tconst relativePath = normalizePreservedRelativePath(preserved.relativePath);\n\t\t\tif (relativePath === null) {\n\t\t\t\treturn yield* failStage(\n\t\t\t\t\t'preserve-target-paths',\n\t\t\t\t\targs.targetPath,\n\t\t\t\t\targs.stagingPath,\n\t\t\t\t)(new Error(`unsafe preserved path: ${preserved.relativePath}`));\n\t\t\t}\n\t\t\tconst source = join(args.backupPath, relativePath);\n\t\t\tconst exists = yield* fs.exists(source).pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\tif (!exists) continue;\n\t\t\tconst target = join(args.stagingPath, relativePath);\n\t\t\t// `overwrite: false` — don't clobber a path the build already placed in\n\t\t\t// staging (e.g. a deploy cache the snapshot captured into the host-tree\n\t\t\t// tar): that captured copy is consistent with the restored chain, so it\n\t\t\t// WINS over the live copy. The live copy is only a fallback when staging\n\t\t\t// doesn't already carry it (e.g. a pre-capture snapshot).\n\t\t\tif (preserved.overwrite === false) {\n\t\t\t\tconst targetExists = yield* fs\n\t\t\t\t\t.exists(target)\n\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\t\tif (targetExists) continue;\n\t\t\t}\n\t\t\tyield* fs\n\t\t\t\t.makeDirectory(dirname(target), { recursive: true })\n\t\t\t\t.pipe(Effect.catch(failStage('preserve-target-paths', args.targetPath, args.stagingPath)));\n\t\t\tyield* fs\n\t\t\t\t.copy(source, target, { overwrite: true })\n\t\t\t\t.pipe(Effect.catch(failStage('preserve-target-paths', args.targetPath, args.stagingPath)));\n\t\t}\n\t});\n\n/**\n * Build-then-swap. `build` is a user effect that populates `stagingPath`;\n * on success the helper:\n *\n *   - backs up the current `targetPath` (if any) to `<targetPath>.bak.<pid>`,\n *   - copies any selected `preserveFromTarget` paths from that backup\n *     into staging,\n *   - renames `stagingPath` → `targetPath`,\n *   - removes the backup.\n *\n * On any failure the helper removes `stagingPath` and, if the backup\n * was taken, renames it back to `targetPath` so the world looks\n * exactly as it did at entry.\n *\n * The build effect's error type passes through unchanged — the\n * primitive returns `E | StageAndSwapError`. This is the\n * \"preserve the caller's error tag\" rule from distilled §17.\n *\n * IMPORTANT: stagingPath MUST be on the same filesystem as\n * targetPath. The helper picks it as a sibling under the same parent\n * (caller passes `parentDir`, we mint the names) — this is enforced\n * by the helper's signature shape.\n *\n * ## Two call shapes\n *\n *   - Explicit-paths: callers that need bespoke sibling names (the\n *     Seal plugin uses `.backup.` not `.bak.`; pre-existing tests use\n *     literal `target.staging`/`target.bak`) pass both `stagingPath`\n *     and `backupPath` directly.\n *   - `idSuffix`: callers (codegen, snapshot) pass `idSuffix` and the\n *     primitive mints `<targetPath>.staging.<idSuffix>` /\n *     `<targetPath>.bak.<idSuffix>` so the staging/backup-naming\n *     convention is owned in ONE place. Callers MUST NOT pass both\n *     `idSuffix` and explicit paths.\n *\n * ## `preserveOnPreseed`\n *\n * When `true`, before the user's `build` runs the primitive copies the\n * current `targetPath` (if any) into `stagingPath` so `build` can\n * mutate that baseline incrementally. This subsumes the codegen\n * orchestrator's pre-seed dance (per-file no-touch idempotency relies\n * on seeing the previous target's mtimes). Cross-cutting with\n * `preserveFromTarget` is allowed: pre-seed clones the whole tree\n * BEFORE the build; `preserveFromTarget` cherry-picks paths AFTER the\n * build and BEFORE the swap (and reads from the backup, so the build\n * may have rewritten them in-tree). The two features answer different\n * questions and the primitive runs them in that order.\n */\nexport const stageAndSwap = <A, E>(\n\targs: {\n\t\treadonly targetPath: string;\n\t\treadonly build: Effect.Effect<A, E, FileSystem.FileSystem>;\n\t\treadonly preserveFromTarget?: ReadonlyArray<StageAndSwapPreservedPath>;\n\t\treadonly preserveOnPreseed?: boolean;\n\t\treadonly publishLockPath?: string;\n\t} & (\n\t\t| { readonly stagingPath: string; readonly backupPath: string; readonly idSuffix?: never }\n\t\t| { readonly idSuffix: string; readonly stagingPath?: never; readonly backupPath?: never }\n\t),\n): Effect.Effect<A, E | StageAndSwapError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst {\n\t\t\ttargetPath,\n\t\t\tbuild,\n\t\t\tpreserveFromTarget = [],\n\t\t\tpreserveOnPreseed = false,\n\t\t\tpublishLockPath,\n\t\t} = args;\n\t\tconst stagingPath =\n\t\t\targs.stagingPath ?? `${targetPath}.staging.${(args as { idSuffix: string }).idSuffix}`;\n\t\tconst backupPath =\n\t\t\targs.backupPath ?? `${targetPath}.bak.${(args as { idSuffix: string }).idSuffix}`;\n\n\t\t// 0. Pre-clean the staging slot (a previous crash may have left\n\t\t//    a sibling). recursive+force is idempotent.\n\t\tyield* fs.remove(stagingPath, { recursive: true, force: true }).pipe(Effect.ignore);\n\t\tyield* fs\n\t\t\t.makeDirectory(stagingPath, { recursive: true })\n\t\t\t.pipe(Effect.catch(failStage('mkdir-staging', targetPath, stagingPath)));\n\n\t\t// 0a. Optional pre-seed: when `preserveOnPreseed`, clone the\n\t\t//     current target into staging so the build can edit it\n\t\t//     incrementally (codegen needs this for per-file no-touch\n\t\t//     idempotency). `preserveTimestamps: true` keeps mtimes\n\t\t//     intact so HMR watchers (Vite/Turbopack — they trigger on\n\t\t//     mtime, not content) stay quiet for unchanged outputs.\n\t\tif (preserveOnPreseed) {\n\t\t\tconst targetExistsForPreseed = yield* fs\n\t\t\t\t.exists(targetPath)\n\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\tif (targetExistsForPreseed) {\n\t\t\t\tyield* fs.copy(targetPath, stagingPath, { overwrite: true, preserveTimestamps: true }).pipe(\n\t\t\t\t\tEffect.catch(failStage('mkdir-staging', targetPath, stagingPath)),\n\t\t\t\t\tEffect.onError(() =>\n\t\t\t\t\t\tfs.remove(stagingPath, { recursive: true, force: true }).pipe(Effect.ignore),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\t// 1. Run the user's build inside the staging directory. On\n\t\t//    failure clean up the staging dir (best-effort) BEFORE\n\t\t//    re-raising — preserves the caller's error tag (no wrap).\n\t\tconst result = yield* build.pipe(\n\t\t\tEffect.onError(() =>\n\t\t\t\tfs.remove(stagingPath, { recursive: true, force: true }).pipe(Effect.ignore),\n\t\t\t),\n\t\t);\n\n\t\t// 2. Backup the current target and promote staging while holding\n\t\t//    an optional caller-supplied lock. Restore uses this to block\n\t\t//    command/event writers while the stack root path is absent.\n\t\tconst targetExists = yield* Effect.scoped(\n\t\t\tEffect.gen(function* () {\n\t\t\t\tif (publishLockPath !== undefined) {\n\t\t\t\t\tyield* acquireStackLock(publishLockPath).pipe(\n\t\t\t\t\t\tEffect.catch(failStage('acquire-publish-lock', targetPath, stagingPath)),\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tconst targetExists = yield* fs\n\t\t\t\t\t.exists(targetPath)\n\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\t\tif (targetExists) {\n\t\t\t\t\t// Move current → backup (atomic rename on same filesystem).\n\t\t\t\t\tyield* fs\n\t\t\t\t\t\t.rename(targetPath, backupPath)\n\t\t\t\t\t\t.pipe(Effect.catch(failStage('backup-current', targetPath, stagingPath)));\n\t\t\t\t\tyield* preserveTargetPaths({\n\t\t\t\t\t\tbackupPath,\n\t\t\t\t\t\ttargetPath,\n\t\t\t\t\t\tstagingPath,\n\t\t\t\t\t\tpreservedPaths: preserveFromTarget,\n\t\t\t\t\t}).pipe(\n\t\t\t\t\t\tEffect.catch((error) =>\n\t\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\t\tyield* restoreBackupRename({ backupPath, targetPath, stagingPath });\n\t\t\t\t\t\t\t\treturn yield* Effect.fail(error);\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\n\t\t\t\t// 3. Promote staging → target. This is the atomic publish step.\n\t\t\t\tyield* fs.rename(stagingPath, targetPath).pipe(\n\t\t\t\t\tEffect.catch((cause) => {\n\t\t\t\t\t\t// A real Effect v4 `rename` failure is a PlatformError whose\n\t\t\t\t\t\t// raw Node errno lives at `reason.cause.code` (and the hoisted\n\t\t\t\t\t\t// `cause.cause.code`), NOT the top-level `.code` — see errnoCode.\n\t\t\t\t\t\tif (errnoCode(cause) === 'EXDEV') {\n\t\t\t\t\t\t\t// Cross-filesystem fallback — architecture's documented\n\t\t\t\t\t\t\t// exception. Log loudly; copy then rm. The atomicity\n\t\t\t\t\t\t\t// guarantee is LOST in this branch.\n\t\t\t\t\t\t\treturn Effect.gen(function* () {\n\t\t\t\t\t\t\t\tyield* Effect.logWarning('stage-and-swap cross-filesystem fallback').pipe(\n\t\t\t\t\t\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t\t\t\t\t\t[LogAttr.stageAndSwapTargetPath]: targetPath,\n\t\t\t\t\t\t\t\t\t\t[LogAttr.stageAndSwapStagingPath]: stagingPath,\n\t\t\t\t\t\t\t\t\t\t[LogAttr.errorCode]: 'EXDEV',\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\tyield* fs.copy(stagingPath, targetPath, { overwrite: false }).pipe(\n\t\t\t\t\t\t\t\t\tEffect.catch((copyCause) =>\n\t\t\t\t\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\t\t\t\t\t// Copy failed mid-fallback. Mirror the same-FS branch:\n\t\t\t\t\t\t\t\t\t\t\t// if we backed a target up, restore it verbatim before\n\t\t\t\t\t\t\t\t\t\t\t// surfacing the original tag (contract item 5).\n\t\t\t\t\t\t\t\t\t\t\tif (targetExists) {\n\t\t\t\t\t\t\t\t\t\t\t\tyield* restoreBackupRename({ backupPath, targetPath, stagingPath });\n\t\t\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\t\t\treturn yield* failStage(\n\t\t\t\t\t\t\t\t\t\t\t\t'cross-filesystem-fallback',\n\t\t\t\t\t\t\t\t\t\t\t\ttargetPath,\n\t\t\t\t\t\t\t\t\t\t\t\tstagingPath,\n\t\t\t\t\t\t\t\t\t\t\t)(copyCause);\n\t\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\tyield* fs.remove(stagingPath, { recursive: true, force: true }).pipe(Effect.ignore);\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// Same-filesystem rename failed. Restore backup if we took\n\t\t\t\t\t\t// one; surface the original tag.\n\t\t\t\t\t\treturn Effect.gen(function* () {\n\t\t\t\t\t\t\tif (targetExists) {\n\t\t\t\t\t\t\t\tyield* restoreBackupRename({ backupPath, targetPath, stagingPath });\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\treturn yield* failStage('rename-into-target', targetPath, stagingPath)(cause);\n\t\t\t\t\t\t});\n\t\t\t\t\t}),\n\t\t\t\t);\n\n\t\t\t\treturn targetExists;\n\t\t\t}),\n\t\t);\n\n\t\t// 4. Drop the backup. Failure here is observable but non-fatal:\n\t\t//    the new target is live; an orphan backup is cosmetic.\n\t\tif (targetExists) {\n\t\t\tyield* fs.remove(backupPath, { recursive: true, force: true }).pipe(Effect.ignore);\n\t\t}\n\n\t\treturn result;\n\t});\n"],"mappings":"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"}

package/dist/substrate/runtime/strategy-registry/chain-keyed-strategy-for.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"chain-keyed-strategy-for.mjs","names":[],"sources":["../../../../src/substrate/runtime/strategy-registry/chain-keyed-strategy-for.ts"],"sourcesContent":["// `chainKeyedStrategyFor` — strategy-registry sugar for chain-keyed\n// strategy lookups. Mirrors `chainProbeFor`.\n//\n// The substrate is name-blind: the caller passes both the prefix and\n// the chain id, and the helper assembles `<prefix>:<chainId>` and\n// performs the registry lookup. The faucet plugin's\n// `FAUCET_CAPABILITY_KEY_PREFIX` is the single source of truth for the\n// faucet key shape; the substrate does NOT duplicate it.\n\nimport { Effect } from 'effect';\n\nimport type { ChainId } from '../../brand.ts';\nimport type { StrategyNotFoundError } from '../errors.ts';\nimport { StrategyRegistryService } from './service.ts';\n\n/**\n * Look up the strategy registered under `<prefix>:<chainId>` and surface\n * it with the caller's expected shape.\n *\n * The strategy shape `P` is a free generic — the plugin that owns the\n * capability prefix also owns its strategy contract, and callers pass\n * both at the call site:\n *\n * ```ts\n * import { FAUCET_CAPABILITY_KEY_PREFIX, type FaucetStrategy } from '../faucet/index.ts';\n *\n * const strategy = yield* chainKeyedStrategyFor<FaucetStrategy>(\n *   FAUCET_CAPABILITY_KEY_PREFIX,\n *   parts.chainId,\n * );\n * ```\n *\n * Failure shape is the substrate `StrategyNotFoundError`; callers that\n * want a plugin-flavored error project it via `Effect.catchTag` at the\n * call site.\n */\nexport const chainKeyedStrategyFor = <P>(\n\tprefix: string,\n\tchainId: ChainId,\n): Effect.Effect<P, StrategyNotFoundError, StrategyRegistryService> =>\n\tEffect.gen(function* () {\n\t\tconst registry = yield* StrategyRegistryService;\n\t\tconst key = `${prefix}:${chainId}`;\n\t\treturn yield* registry.get<typeof key, P>(key);\n\t});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAoCA,MAAa,yBACZ,QACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO;CACxB,MAAM,MAAM,GAAG,OAAO,GAAG;AACzB,QAAO,OAAO,SAAS,IAAmB,IAAI;EAC7C"}
+{"version":3,"file":"chain-keyed-strategy-for.mjs","names":[],"sources":["../../../../src/substrate/runtime/strategy-registry/chain-keyed-strategy-for.ts"],"sourcesContent":["// `chainKeyedStrategyFor` — strategy-registry sugar for chain-keyed\n// strategy lookups. Mirrors `chainProbeFor`.\n//\n// The substrate is name-blind: the caller passes both the prefix and\n// the chain id, and the helper assembles `<prefix>:<chainId>` and\n// performs the registry lookup. The faucet plugin's\n// `FAUCET_CAPABILITY_KEY_PREFIX` is the single source of truth for the\n// faucet key shape; the substrate does NOT duplicate it.\n\nimport { Effect } from 'effect';\n\nimport type { StrategyNotFoundError } from '../errors.ts';\nimport { StrategyRegistryService } from './service.ts';\n\n/**\n * Look up the strategy registered under `<prefix>:<chainId>` and surface\n * it with the caller's expected shape.\n *\n * The strategy shape `P` is a free generic — the plugin that owns the\n * capability prefix also owns its strategy contract, and callers pass\n * both at the call site:\n *\n * ```ts\n * import { FAUCET_CAPABILITY_KEY_PREFIX, type FaucetStrategy } from '../faucet/index.ts';\n *\n * const strategy = yield* chainKeyedStrategyFor<FaucetStrategy>(\n *   FAUCET_CAPABILITY_KEY_PREFIX,\n *   parts.chainId,\n * );\n * ```\n *\n * Failure shape is the substrate `StrategyNotFoundError`; callers that\n * want a plugin-flavored error project it via `Effect.catchTag` at the\n * call site.\n */\nexport const chainKeyedStrategyFor = <P>(\n\tprefix: string,\n\tchainId: string,\n): Effect.Effect<P, StrategyNotFoundError, StrategyRegistryService> =>\n\tEffect.gen(function* () {\n\t\tconst registry = yield* StrategyRegistryService;\n\t\tconst key = `${prefix}:${chainId}`;\n\t\treturn yield* registry.get<typeof key, P>(key);\n\t});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAmCA,MAAa,yBACZ,QACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO;CACxB,MAAM,MAAM,GAAG,OAAO,GAAG;CACzB,OAAO,OAAO,SAAS,IAAmB,GAAG;AAC9C,CAAC"}

package/dist/substrate/runtime/strategy-registry/chain-probe-for.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"chain-probe-for.mjs","names":[],"sources":["../../../../src/substrate/runtime/strategy-registry/chain-probe-for.ts"],"sourcesContent":["// `chainProbeFor` — strategy-registry sugar for the chain-probe lookup.\n//\n// Every plugin that produces an on-chain artifact (package, coin, seal,\n// walrus, action, ...) repeats the same 4-line dance: yield the\n// StrategyRegistryService, then `registry.get<...>(chainProbeCapabilityKey(chain))`\n// with the same generic args and the same trailing cast. The dance is\n// load-bearing exactly once (the cast threads `SuiProbeKey` through the\n// capability-key's `string` discriminator) — every other site is\n// boilerplate.\n//\n// This helper consolidates the pattern: one Effect, one R-channel\n// (`StrategyRegistryService`), one typed return (`ChainProbe<Key>`).\n// Call sites become a single `yield* chainProbeFor(sui.chain)`.\n\nimport { Effect } from 'effect';\n\nimport { chainProbeCapabilityKey, type ChainProbe } from '../../../contracts/chain-probe.ts';\nimport type { ChainId } from '../../brand.ts';\nimport type { StrategyNotFoundError } from '../errors.ts';\nimport { StrategyRegistryService } from './service.ts';\n\n/**\n * Look up the chain-probe contributed by the chain owner (Sui's\n * `acquire` registers one per resolved chain id) and surface it with\n * the caller's expected key shape.\n *\n * `Key` defaults to `unknown` so call sites that don't care about the\n * probe key shape can omit the generic; sites that consume Sui probes\n * pass `SuiProbeKey` explicitly. The cast from the registry's\n * `unknown` payload to `ChainProbe<Key>` is centralised here — call\n * sites stop repeating it.\n */\nexport const chainProbeFor = <Key = unknown>(\n\tchain: ChainId,\n): Effect.Effect<ChainProbe<Key>, StrategyNotFoundError, StrategyRegistryService> =>\n\tEffect.gen(function* () {\n\t\tconst registry = yield* StrategyRegistryService;\n\t\tconst probe = yield* registry.get<`chain-probe:${string}`, ChainProbe<Key>>(\n\t\t\tchainProbeCapabilityKey(chain),\n\t\t);\n\t\treturn probe;\n\t});\n"],"mappings":";;;;;;;;;;;;;;;AAgCA,MAAa,iBACZ,UAEA,OAAO,IAAI,aAAa;AAKvB,QAAO,QAHc,OADG,yBACM,IAC7B,wBAAwB,MAAM,CAC9B;EAEA"}
+{"version":3,"file":"chain-probe-for.mjs","names":[],"sources":["../../../../src/substrate/runtime/strategy-registry/chain-probe-for.ts"],"sourcesContent":["// `chainProbeFor` — strategy-registry sugar for the chain-probe lookup.\n//\n// Every plugin that produces an on-chain artifact (package, coin, seal,\n// walrus, action, ...) repeats the same 4-line dance: yield the\n// StrategyRegistryService, then `registry.get<...>(chainProbeCapabilityKey(chain))`\n// with the same generic args and the same trailing cast. The dance is\n// load-bearing exactly once (the cast threads `SuiProbeKey` through the\n// capability-key's `string` discriminator) — every other site is\n// boilerplate.\n//\n// This helper consolidates the pattern: one Effect, one R-channel\n// (`StrategyRegistryService`), one typed return (`ChainProbe<Key>`).\n// Call sites become a single `yield* chainProbeFor(sui.chain)`.\n\nimport { Effect } from 'effect';\n\nimport { chainProbeCapabilityKey, type ChainProbe } from '../../../contracts/chain-probe.ts';\nimport type { StrategyNotFoundError } from '../errors.ts';\nimport { StrategyRegistryService } from './service.ts';\n\n/**\n * Look up the chain-probe contributed by the chain owner (Sui's\n * `acquire` registers one per resolved chain id) and surface it with\n * the caller's expected key shape.\n *\n * `Key` defaults to `unknown` so call sites that don't care about the\n * probe key shape can omit the generic; sites that consume Sui probes\n * pass `SuiProbeKey` explicitly. The cast from the registry's\n * `unknown` payload to `ChainProbe<Key>` is centralised here — call\n * sites stop repeating it.\n */\nexport const chainProbeFor = <Key = unknown>(\n\tchain: string,\n): Effect.Effect<ChainProbe<Key>, StrategyNotFoundError, StrategyRegistryService> =>\n\tEffect.gen(function* () {\n\t\tconst registry = yield* StrategyRegistryService;\n\t\tconst probe = yield* registry.get<`chain-probe:${string}`, ChainProbe<Key>>(\n\t\t\tchainProbeCapabilityKey(chain),\n\t\t);\n\t\treturn probe;\n\t});\n"],"mappings":";;;;;;;;;;;;;;;AA+BA,MAAa,iBACZ,UAEA,OAAO,IAAI,aAAa;CAKvB,OAAO,QAHc,OADG,wBAAA,CACM,IAC7B,wBAAwB,KAAK,CAC9B;AAED,CAAC"}

package/dist/substrate/runtime/strategy-registry/service.mjs

@@ -1,8 +1,5 @@
-import { SpanAttr } from "../observability/spans.mjs";
-import { makeScopedMultimap } from "../scoped-multimap/service.mjs";
-import "../scoped-multimap/index.mjs";
 import { StrategyNotFoundError } from "../errors.mjs";
-import { Context, Effect, Layer } from "effect";
+import { Context, Effect, Layer, Ref } from "effect";
 //#region src/substrate/runtime/strategy-registry/service.ts
 var StrategyRegistryService = class extends Context.Service()("@devstack/substrate/StrategyRegistry") {};
 /**
@@ -11,27 +8,42 @@ var StrategyRegistryService = class extends Context.Service()("@devstack/substra
 * stack's registry, not a global one.
 */
 const layerStrategyRegistry = Layer.effect(StrategyRegistryService, Effect.gen(function* () {
-	const store = yield* makeScopedMultimap();
+	const ref = yield* Ref.make(/* @__PURE__ */ new Map());
+	const seqRef = yield* Ref.make(0);
+	const entriesFor = (key) => Ref.get(ref).pipe(Effect.map((current) => current.get(key) ?? []));
+	const keys = Ref.get(ref).pipe(Effect.map((current) => [...current.keys()]));
 	const register = (key, strategy, options) => Effect.gen(function* () {
 		const entry = {
 			strategy,
 			autoMounted: options?.autoMounted ?? false,
 			priority: options?.priority ?? 0
 		};
-		yield* store.register([{
-			key,
-			value: entry
-		}]);
-		yield* Effect.annotateCurrentSpan({
-			[SpanAttr.strategyKey]: key,
-			[SpanAttr.strategyAutoMounted]: entry.autoMounted
+		const seq = yield* Ref.updateAndGet(seqRef, (n) => n + 1);
+		yield* Ref.update(ref, (current) => {
+			const next = new Map(current);
+			const existing = next.get(key) ?? [];
+			next.set(key, [...existing, {
+				value: entry,
+				seq
+			}]);
+			return next;
 		});
-	}).pipe(Effect.withSpan("substrate.strategyRegistry.register"));
+		yield* Effect.addFinalizer((_exit) => Ref.update(ref, (current) => {
+			const next = new Map(current);
+			const existing = next.get(key);
+			if (existing) {
+				const filtered = existing.filter((e) => e.seq !== seq);
+				if (filtered.length === 0) next.delete(key);
+				else next.set(key, filtered);
+			}
+			return next;
+		}));
+	}).pipe(Effect.uninterruptible);
 	const get = (key) => Effect.gen(function* () {
-		const entries = yield* store.entriesFor(key);
+		const entries = yield* entriesFor(key);
 		if (entries.length === 0) return yield* new StrategyNotFoundError({
 			capabilityKey: key,
-			registeredKeys: yield* store.keys
+			registeredKeys: yield* keys
 		});
 		let best = entries[0];
 		for (let i = 1; i < entries.length; i++) {
@@ -39,8 +51,8 @@ const layerStrategyRegistry = Layer.effect(StrategyRegistryService, Effect.gen(f
 			if (e.value.priority > best.value.priority || e.value.priority === best.value.priority && e.seq > best.seq) best = e;
 		}
 		return best.value.strategy;
-	}).pipe(Effect.withSpan("substrate.strategyRegistry.get", { attributes: { key } }));
-	const list = () => store.keys;
+	});
+	const list = () => keys;
 	return StrategyRegistryService.of({
 		get,
 		register,

package/dist/substrate/runtime/strategy-registry/service.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"service.mjs","names":[],"sources":["../../../../src/substrate/runtime/strategy-registry/service.ts"],"sourcesContent":["// Strategy registry implementation.\n//\n// Architecture § StrategyContributor — generic capability-keyed\n// pub/sub for plugin-contributed strategies (faucet strategies,\n// network resolvers, account selection, etc.).\n//\n// Per-capability-key LIST of contributing plugins (a registry can\n// hold multiple contributions for the same key). Resolution is\n// ordered by registration time; the selector chooses among them.\n//\n// Scope-local. The registry is created per-stack-scope so parallel\n// stacks isolate. When the stack scope closes, the registry's\n// entries die with it (the architecture's \"scope-local, never\n// module-level\" rule).\n\nimport { Context, Effect, Layer, Scope } from 'effect';\n\nimport type { StrategyRegistry } from '../../../contracts/strategy-contributor.ts';\nimport { StrategyNotFoundError } from '../errors.ts';\nimport { SpanAttr } from '../observability/spans.ts';\nimport { makeScopedMultimap } from '../scoped-multimap/index.ts';\n\n/** One registered strategy under a capability key. The multimap stamps\n *  the registration `seq`; the payload carries the strategy + its\n *  visibility/priority. We keep the LIST (not the single winner)\n *  because:\n *   1. Renderers want to enumerate \"N contributors registered\".\n *   2. The selector is per-strategy and may inspect all of them.\n *   3. Auto-mounted vs user-supplied is a visibility distinction\n *      consumers need to surface separately. */\ninterface Entry {\n\treadonly strategy: unknown;\n\treadonly autoMounted: boolean;\n\treadonly priority: number;\n}\n\nexport class StrategyRegistryService extends Context.Service<\n\tStrategyRegistryService,\n\tStrategyRegistry\n>()('@devstack/substrate/StrategyRegistry') {}\n\n/**\n * Layer. Constructed per-scope; the orchestrator hands the registry\n * to each plugin's acquire so contributions land on the right\n * stack's registry, not a global one.\n */\nexport const layerStrategyRegistry: Layer.Layer<StrategyRegistryService> = Layer.effect(\n\tStrategyRegistryService,\n\tEffect.gen(function* () {\n\t\tconst store = yield* makeScopedMultimap<string, Entry>();\n\n\t\tconst register: StrategyRegistry['register'] = <Key extends string, S>(\n\t\t\tkey: Key,\n\t\t\tstrategy: S,\n\t\t\toptions?: { readonly autoMounted?: boolean; readonly priority?: number },\n\t\t) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entry: Entry = {\n\t\t\t\t\tstrategy,\n\t\t\t\t\tautoMounted: options?.autoMounted ?? false,\n\t\t\t\t\tpriority: options?.priority ?? 0,\n\t\t\t\t};\n\t\t\t\t// The multimap stamps the seq and wires the drop-by-seq\n\t\t\t\t// finalizer — parallel registrations stay isolated.\n\t\t\t\tyield* store.register([{ key, value: entry }]);\n\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t[SpanAttr.strategyKey]: key,\n\t\t\t\t\t[SpanAttr.strategyAutoMounted]: entry.autoMounted,\n\t\t\t\t});\n\t\t\t}).pipe(Effect.withSpan('substrate.strategyRegistry.register')) as Effect.Effect<\n\t\t\t\tvoid,\n\t\t\t\tnever,\n\t\t\t\tScope.Scope\n\t\t\t>;\n\n\t\tconst get: StrategyRegistry['get'] = <Key extends string, S>(key: Key) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entries = yield* store.entriesFor(key);\n\t\t\t\tif (entries.length === 0) {\n\t\t\t\t\tconst keys = yield* store.keys;\n\t\t\t\t\treturn yield* new StrategyNotFoundError({\n\t\t\t\t\t\tcapabilityKey: key,\n\t\t\t\t\t\tregisteredKeys: keys,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\t// Resolution policy:\n\t\t\t\t//   1. Higher priority wins.\n\t\t\t\t//   2. Tie on priority → later registration wins\n\t\t\t\t//      (last-write-wins for user overrides of\n\t\t\t\t//      built-ins — matches architecture § failure\n\t\t\t\t//      modes \"two strategies with the same key and\n\t\t\t\t//      same priority → last write wins\").\n\t\t\t\tlet best = entries[0]!;\n\t\t\t\tfor (let i = 1; i < entries.length; i++) {\n\t\t\t\t\tconst e = entries[i]!;\n\t\t\t\t\tif (\n\t\t\t\t\t\te.value.priority > best.value.priority ||\n\t\t\t\t\t\t(e.value.priority === best.value.priority && e.seq > best.seq)\n\t\t\t\t\t) {\n\t\t\t\t\t\tbest = e;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn best.value.strategy as S;\n\t\t\t}).pipe(Effect.withSpan('substrate.strategyRegistry.get', { attributes: { key } }));\n\n\t\tconst list: StrategyRegistry['list'] = () => store.keys;\n\n\t\treturn StrategyRegistryService.of({\n\t\t\tget: get as StrategyRegistry['get'],\n\t\t\tregister: register as StrategyRegistry['register'],\n\t\t\tlist,\n\t\t});\n\t}),\n);\n"],"mappings":";;;;;;AAoCA,IAAa,0BAAb,cAA6C,QAAQ,SAGlD,CAAC,uCAAuC,CAAC;;;;;;AAO5C,MAAa,wBAA8D,MAAM,OAChF,yBACA,OAAO,IAAI,aAAa;CACvB,MAAM,QAAQ,OAAO,oBAAmC;CAExD,MAAM,YACL,KACA,UACA,YAEA,OAAO,IAAI,aAAa;EACvB,MAAM,QAAe;GACpB;GACA,aAAa,SAAS,eAAe;GACrC,UAAU,SAAS,YAAY;GAC/B;AAGD,SAAO,MAAM,SAAS,CAAC;GAAE;GAAK,OAAO;GAAO,CAAC,CAAC;AAC9C,SAAO,OAAO,oBAAoB;IAChC,SAAS,cAAc;IACvB,SAAS,sBAAsB,MAAM;GACtC,CAAC;GACD,CAAC,KAAK,OAAO,SAAS,sCAAsC,CAAC;CAMhE,MAAM,OAAuD,QAC5D,OAAO,IAAI,aAAa;EACvB,MAAM,UAAU,OAAO,MAAM,WAAW,IAAI;AAC5C,MAAI,QAAQ,WAAW,EAEtB,QAAO,OAAO,IAAI,sBAAsB;GACvC,eAAe;GACf,gBAAgB,OAHG,MAAM;GAIzB,CAAC;EASH,IAAI,OAAO,QAAQ;AACnB,OAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;GACxC,MAAM,IAAI,QAAQ;AAClB,OACC,EAAE,MAAM,WAAW,KAAK,MAAM,YAC7B,EAAE,MAAM,aAAa,KAAK,MAAM,YAAY,EAAE,MAAM,KAAK,IAE1D,QAAO;;AAGT,SAAO,KAAK,MAAM;GACjB,CAAC,KAAK,OAAO,SAAS,kCAAkC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;CAEpF,MAAM,aAAuC,MAAM;AAEnD,QAAO,wBAAwB,GAAG;EAC5B;EACK;EACV;EACA,CAAC;EACD,CACF"}
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../../src/substrate/runtime/strategy-registry/service.ts"],"sourcesContent":["// Strategy registry implementation.\n//\n// Architecture § StrategyContributor — generic capability-keyed\n// pub/sub for plugin-contributed strategies (faucet strategies,\n// network resolvers, account selection, etc.).\n//\n// Per-capability-key LIST of contributing plugins (a registry can\n// hold multiple contributions for the same key). Resolution is\n// ordered by registration time; the selector chooses among them.\n//\n// Scope-local. The registry is created per-stack-scope so parallel\n// stacks isolate. When the stack scope closes, the registry's\n// entries die with it (the architecture's \"scope-local, never\n// module-level\" rule).\n\nimport { Context, Effect, Layer, Ref, Scope } from 'effect';\n\nimport type { StrategyRegistry } from '../../../contracts/strategy-contributor.ts';\nimport { StrategyNotFoundError } from '../errors.ts';\n\n/** One registered strategy under a capability key. The store stamps\n *  the registration `seq`; the payload carries the strategy + its\n *  visibility/priority. We keep the LIST (not the single winner)\n *  because:\n *   1. Renderers want to enumerate \"N contributors registered\".\n *   2. The selector is per-strategy and may inspect all of them.\n *   3. Auto-mounted vs user-supplied is a visibility distinction\n *      consumers need to surface separately. */\ninterface Entry {\n\treadonly strategy: unknown;\n\treadonly autoMounted: boolean;\n\treadonly priority: number;\n}\n\n/** One stored entry: the caller's `Entry` plus the monotonic `seq` the\n *  store stamped it with. The `seq` is the identity the finalizer drops\n *  on and the winner-fold tiebreaks on.\n *\n *  Why a per-key LIST tagged by a monotonic seq (rather than a single\n *  value-per-key with prior-restore):\n *\n *    - Parallel / sibling-scope safety. The naive \"remember the prior\n *      value, restore it on close\" finalizer is only correct under\n *      strict LIFO nesting. With sibling scopes it clobbers a still-live\n *      registration: scope A installs `X`, sibling B overwrites `X`\n *      (capturing A's value as its `prior`), then A closes first and its\n *      finalizer — holding `prior = nothing` — DELETES `X`, dropping B's\n *      live overlay.\n *\n *    - The seq-tagged list makes every finalizer remove ONLY the entry\n *      it added — it never touches a newer registration for the same\n *      key. \"Who wins right now\" is a pure function of the surviving\n *      entries (priority, then seq), so close order does not matter. */\ninterface StoredEntry {\n\treadonly value: Entry;\n\treadonly seq: number;\n}\n\ntype Store = ReadonlyMap<string, ReadonlyArray<StoredEntry>>;\n\nexport class StrategyRegistryService extends Context.Service<\n\tStrategyRegistryService,\n\tStrategyRegistry\n>()('@devstack/substrate/StrategyRegistry') {}\n\n/**\n * Layer. Constructed per-scope; the orchestrator hands the registry\n * to each plugin's acquire so contributions land on the right\n * stack's registry, not a global one.\n */\nexport const layerStrategyRegistry: Layer.Layer<StrategyRegistryService> = Layer.effect(\n\tStrategyRegistryService,\n\tEffect.gen(function* () {\n\t\t// Scope-local seq-tagged store. The backing `Ref`s are private to\n\t\t// this build effect, so they die with the stack scope (the\n\t\t// architecture's \"scope-local, never module-level\" rule). `seqRef`\n\t\t// stamps a fresh monotonic seq per registration; `ref` holds the\n\t\t// per-key LIST of surviving seq-tagged entries.\n\t\tconst ref = yield* Ref.make<Store>(new Map());\n\t\tconst seqRef = yield* Ref.make(0);\n\n\t\t// `entriesFor` — surviving entries under one key, in registration\n\t\t// order (ascending seq). Empty array when the key is absent.\n\t\tconst entriesFor = (key: string): Effect.Effect<ReadonlyArray<StoredEntry>> =>\n\t\t\tRef.get(ref).pipe(Effect.map((current) => current.get(key) ?? []));\n\n\t\t// `keys` — keys with at least one surviving entry.\n\t\tconst keys: Effect.Effect<ReadonlyArray<string>> = Ref.get(ref).pipe(\n\t\t\tEffect.map((current) => [...current.keys()]),\n\t\t);\n\n\t\tconst register: StrategyRegistry['register'] = <Key extends string, S>(\n\t\t\tkey: Key,\n\t\t\tstrategy: S,\n\t\t\toptions?: { readonly autoMounted?: boolean; readonly priority?: number },\n\t\t) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entry: Entry = {\n\t\t\t\t\tstrategy,\n\t\t\t\t\tautoMounted: options?.autoMounted ?? false,\n\t\t\t\t\tpriority: options?.priority ?? 0,\n\t\t\t\t};\n\t\t\t\t// Stamp a fresh monotonic seq, append the entry under `key`,\n\t\t\t\t// and wire a drop-by-seq finalizer onto the CALLER's scope.\n\t\t\t\t// The append + finalizer-wire pair is `uninterruptible`, so an\n\t\t\t\t// interrupt arriving between the two can't leak an entry past\n\t\t\t\t// scope close. The finalizer touches only the entry THIS\n\t\t\t\t// registration added — never a newer registration for the same\n\t\t\t\t// key — so sibling-scope close order is irrelevant.\n\t\t\t\tconst seq = yield* Ref.updateAndGet(seqRef, (n) => n + 1);\n\t\t\t\tyield* Ref.update(ref, (current) => {\n\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\tconst existing = next.get(key) ?? [];\n\t\t\t\t\tnext.set(key, [...existing, { value: entry, seq }]);\n\t\t\t\t\treturn next;\n\t\t\t\t});\n\t\t\t\tyield* Effect.addFinalizer((_exit) =>\n\t\t\t\t\tRef.update(ref, (current) => {\n\t\t\t\t\t\tconst next = new Map(current);\n\t\t\t\t\t\tconst existing = next.get(key);\n\t\t\t\t\t\tif (existing) {\n\t\t\t\t\t\t\tconst filtered = existing.filter((e) => e.seq !== seq);\n\t\t\t\t\t\t\tif (filtered.length === 0) next.delete(key);\n\t\t\t\t\t\t\telse next.set(key, filtered);\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn next;\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}).pipe(Effect.uninterruptible) as Effect.Effect<void, never, Scope.Scope>;\n\n\t\tconst get: StrategyRegistry['get'] = <Key extends string, S>(key: Key) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entries = yield* entriesFor(key);\n\t\t\t\tif (entries.length === 0) {\n\t\t\t\t\tconst registeredKeys = yield* keys;\n\t\t\t\t\treturn yield* new StrategyNotFoundError({\n\t\t\t\t\t\tcapabilityKey: key,\n\t\t\t\t\t\tregisteredKeys,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\t// Resolution policy:\n\t\t\t\t//   1. Higher priority wins.\n\t\t\t\t//   2. Tie on priority → later registration wins\n\t\t\t\t//      (last-write-wins for user overrides of\n\t\t\t\t//      built-ins — matches architecture § failure\n\t\t\t\t//      modes \"two strategies with the same key and\n\t\t\t\t//      same priority → last write wins\").\n\t\t\t\tlet best = entries[0]!;\n\t\t\t\tfor (let i = 1; i < entries.length; i++) {\n\t\t\t\t\tconst e = entries[i]!;\n\t\t\t\t\tif (\n\t\t\t\t\t\te.value.priority > best.value.priority ||\n\t\t\t\t\t\t(e.value.priority === best.value.priority && e.seq > best.seq)\n\t\t\t\t\t) {\n\t\t\t\t\t\tbest = e;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn best.value.strategy as S;\n\t\t\t});\n\n\t\tconst list: StrategyRegistry['list'] = () => keys;\n\n\t\treturn StrategyRegistryService.of({\n\t\t\tget: get as StrategyRegistry['get'],\n\t\t\tregister: register as StrategyRegistry['register'],\n\t\t\tlist,\n\t\t});\n\t}),\n);\n"],"mappings":";;;AA4DA,IAAa,0BAAb,cAA6C,QAAQ,QAGnD,CAAC,CAAC,sCAAsC,CAAC,CAAC,CAAC;;;;;;AAO7C,MAAa,wBAA8D,MAAM,OAChF,yBACA,OAAO,IAAI,aAAa;CAMvB,MAAM,MAAM,OAAO,IAAI,qBAAY,IAAI,IAAI,CAAC;CAC5C,MAAM,SAAS,OAAO,IAAI,KAAK,CAAC;CAIhC,MAAM,cAAc,QACnB,IAAI,IAAI,GAAG,CAAC,CAAC,KAAK,OAAO,KAAK,YAAY,QAAQ,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC;CAGlE,MAAM,OAA6C,IAAI,IAAI,GAAG,CAAC,CAAC,KAC/D,OAAO,KAAK,YAAY,CAAC,GAAG,QAAQ,KAAK,CAAC,CAAC,CAC5C;CAEA,MAAM,YACL,KACA,UACA,YAEA,OAAO,IAAI,aAAa;EACvB,MAAM,QAAe;GACpB;GACA,aAAa,SAAS,eAAe;GACrC,UAAU,SAAS,YAAY;EAChC;EAQA,MAAM,MAAM,OAAO,IAAI,aAAa,SAAS,MAAM,IAAI,CAAC;EACxD,OAAO,IAAI,OAAO,MAAM,YAAY;GACnC,MAAM,OAAO,IAAI,IAAI,OAAO;GAC5B,MAAM,WAAW,KAAK,IAAI,GAAG,KAAK,CAAC;GACnC,KAAK,IAAI,KAAK,CAAC,GAAG,UAAU;IAAE,OAAO;IAAO;GAAI,CAAC,CAAC;GAClD,OAAO;EACR,CAAC;EACD,OAAO,OAAO,cAAc,UAC3B,IAAI,OAAO,MAAM,YAAY;GAC5B,MAAM,OAAO,IAAI,IAAI,OAAO;GAC5B,MAAM,WAAW,KAAK,IAAI,GAAG;GAC7B,IAAI,UAAU;IACb,MAAM,WAAW,SAAS,QAAQ,MAAM,EAAE,QAAQ,GAAG;IACrD,IAAI,SAAS,WAAW,GAAG,KAAK,OAAO,GAAG;SACrC,KAAK,IAAI,KAAK,QAAQ;GAC5B;GACA,OAAO;EACR,CAAC,CACF;CACD,CAAC,CAAC,CAAC,KAAK,OAAO,eAAe;CAE/B,MAAM,OAAuD,QAC5D,OAAO,IAAI,aAAa;EACvB,MAAM,UAAU,OAAO,WAAW,GAAG;EACrC,IAAI,QAAQ,WAAW,GAEtB,OAAO,OAAO,IAAI,sBAAsB;GACvC,eAAe;GACf,gBAAA,OAH6B;EAI9B,CAAC;EASF,IAAI,OAAO,QAAQ;EACnB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;GACxC,MAAM,IAAI,QAAQ;GAClB,IACC,EAAE,MAAM,WAAW,KAAK,MAAM,YAC7B,EAAE,MAAM,aAAa,KAAK,MAAM,YAAY,EAAE,MAAM,KAAK,KAE1D,OAAO;EAET;EACA,OAAO,KAAK,MAAM;CACnB,CAAC;CAEF,MAAM,aAAuC;CAE7C,OAAO,wBAAwB,GAAG;EAC5B;EACK;EACV;CACD,CAAC;AACF,CAAC,CACF"}

package/dist/substrate/runtime/subnet-broker.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"subnet-broker.mjs","names":[],"sources":["../../../src/substrate/runtime/subnet-broker.ts"],"sourcesContent":["// Subnet-prefix derivation + EnsureNetworkSpec stamping — ONE canonical\n// implementation.\n//\n// Architecture § \"What's collapsed\" — multiple plugins (walrus, seal)\n// need a deterministic Docker `/24` subnet keyed off their stack\n// identity so parallel local stacks don't all collide on Docker's\n// default IPAM pool. Each plugin previously inlined the same FNV-1a\n// hash → IPv4 third-octet derivation; the only thing that varied was\n// the second-octet base offset (walrus uses `64`, seal uses `128`)\n// so they live in disjoint 64-wide bands inside `10.0.0.0/8`.\n//\n// Algorithm (DO NOT CHANGE without re-coordinating with every caller —\n// changing it shifts every parallel stack's assigned subnet, which\n// silently invalidates running containers and on-disk snapshots that\n// reference IPs by literal):\n//\n//   1. FNV-1a/32 over the UTF-16 code-unit sequence of `input`,\n//      seeded `0x811c9dc5`, prime `0x01000193`, kept in unsigned\n//      32-bit space via `>>> 0`.\n//   2. Take the low `64 * 256 = 16384` buckets of the hash.\n//   3. Split the bucket into a second-octet add (`bucket / 256`,\n//      0..63) and a third-octet (`bucket % 256`, 0..255).\n//   4. Emit `'10.<secondOctetOffset + add>.<third>'`.\n//\n// The returned prefix is the `a.b.c` of an IPv4 `/24` — callers\n// append `.0/24` for the subnet and `.1` for the gateway.\n\nimport type { EnsureNetworkSpec } from '../../contracts/container-runtime.ts';\n\n/**\n * Derive a deterministic `/24` IPv4 subnet prefix from an identity\n * string, suitable for `EnsureNetworkSpec.subnet` requests.\n *\n * Uses FNV-1a/32 to bucket the input into one of 16384 slots inside\n * a 64-wide band of `10.0.0.0/8`. `secondOctetOffset` selects the\n * band — pick a value disjoint from every other caller (current\n * users: walrus `64`, seal `128`).\n *\n * @param input - opaque identity string. Callers should pack their\n *   stack-identifying fields with a separator that cannot appear in\n *   any field (`\\0` is the convention).\n * @param secondOctetOffset - lower-bound of the second IPv4 octet.\n *   The derived second octet falls in `[offset, offset + 63]`.\n * @returns prefix string `'10.b.c'`. Append `.0/24` for the subnet\n *   and `.1` for the gateway.\n */\nexport const deriveSubnetPrefix = (input: string, secondOctetOffset: number): string => {\n\tlet hash = 0x811c9dc5;\n\tfor (let i = 0; i < input.length; i += 1) {\n\t\thash ^= input.charCodeAt(i);\n\t\thash = Math.imul(hash, 0x01000193) >>> 0;\n\t}\n\tconst bucket = hash % (64 * 256);\n\tconst secondOctet = secondOctetOffset + Math.floor(bucket / 256);\n\tconst thirdOctet = bucket % 256;\n\treturn `10.${secondOctet}.${thirdOctet}`;\n};\n\n/**\n * Expand a `/24` prefix into the `{ subnet, gateway }` shape the\n * container-runtime `EnsureNetworkSpec` consumes.\n *\n * Convention: `<prefix>.0/24` for the subnet, `<prefix>.1` for the\n * gateway — the same pair walrus and seal both stamp on their\n * `ensureNetwork` requests. Folded here so the `/24` + `.1` literals\n * live in ONE place.\n */\nexport const subnetSpec = (\n\tprefix: string,\n): { readonly subnet: string; readonly gateway: string } => ({\n\tsubnet: `${prefix}.0/24`,\n\tgateway: `${prefix}.1`,\n});\n\n/**\n * Stamp the `{subnet, gateway}` pair derived from `subnetPrefix` onto\n * any `EnsureNetworkSpec`-shaped value. Both walrus and seal need the\n * same fold:\n *\n *   {...spec, ...subnetSpec(prefix)}\n *\n * to widen a substrate-blind network spec into one that carries the\n * plugin's deterministic `/24` addressing — folded here so the literal\n * `Required<Pick<…, 'subnet' | 'gateway'>>` widening type lives in\n * ONE place.\n */\nexport const withSubnetAddressing = <Spec extends EnsureNetworkSpec>(\n\tspec: Spec,\n\tsubnetPrefix: string,\n): Spec & Required<Pick<EnsureNetworkSpec, 'subnet' | 'gateway'>> => ({\n\t...spec,\n\t...subnetSpec(subnetPrefix),\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;AA8CA,MAAa,sBAAsB,OAAe,sBAAsC;CACvF,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,GAAG;AACzC,UAAQ,MAAM,WAAW,EAAE;AAC3B,SAAO,KAAK,KAAK,MAAM,SAAW,KAAK;;CAExC,MAAM,SAAS,QAAQ,KAAK;AAG5B,QAAO,MAFa,oBAAoB,KAAK,MAAM,SAAS,IAAI,CAEvC,GADN,SAAS;;;;;;;;;;;AAa7B,MAAa,cACZ,YAC4D;CAC5D,QAAQ,GAAG,OAAO;CAClB,SAAS,GAAG,OAAO;CACnB;;;;;;;;;;;;;AAcD,MAAa,wBACZ,MACA,kBACqE;CACrE,GAAG;CACH,GAAG,WAAW,aAAa;CAC3B"}
+{"version":3,"file":"subnet-broker.mjs","names":[],"sources":["../../../src/substrate/runtime/subnet-broker.ts"],"sourcesContent":["// Subnet-prefix derivation + EnsureNetworkSpec stamping — ONE canonical\n// implementation.\n//\n// Multiple plugins (walrus, seal) need a deterministic Docker `/24`\n// subnet keyed off their stack identity so parallel local stacks don't\n// all collide on Docker's default IPAM pool. They share one FNV-1a\n// hash → IPv4 third-octet derivation; the only thing that varies is\n// the second-octet base offset (walrus uses `64`, seal uses `128`)\n// so they live in disjoint 64-wide bands inside `10.0.0.0/8`.\n//\n// Algorithm (DO NOT CHANGE without re-coordinating with every caller —\n// changing it shifts every parallel stack's assigned subnet, which\n// silently invalidates running containers and on-disk snapshots that\n// reference IPs by literal):\n//\n//   1. FNV-1a/32 over the UTF-16 code-unit sequence of `input`,\n//      seeded `0x811c9dc5`, prime `0x01000193`, kept in unsigned\n//      32-bit space via `>>> 0`.\n//   2. Take the low `64 * 256 = 16384` buckets of the hash.\n//   3. Split the bucket into a second-octet add (`bucket / 256`,\n//      0..63) and a third-octet (`bucket % 256`, 0..255).\n//   4. Emit `'10.<secondOctetOffset + add>.<third>'`.\n//\n// The returned prefix is the `a.b.c` of an IPv4 `/24` — callers\n// append `.0/24` for the subnet and `.1` for the gateway.\n\nimport type { EnsureNetworkSpec } from '../../contracts/container-runtime.ts';\n\n/**\n * Derive a deterministic `/24` IPv4 subnet prefix from an identity\n * string, suitable for `EnsureNetworkSpec.subnet` requests.\n *\n * Uses FNV-1a/32 to bucket the input into one of 16384 slots inside\n * a 64-wide band of `10.0.0.0/8`. `secondOctetOffset` selects the\n * band — pick a value disjoint from every other caller (current\n * users: walrus `64`, seal `128`).\n *\n * @param input - opaque identity string. Callers should pack their\n *   stack-identifying fields with a separator that cannot appear in\n *   any field (`\\0` is the convention).\n * @param secondOctetOffset - lower-bound of the second IPv4 octet.\n *   The derived second octet falls in `[offset, offset + 63]`.\n * @returns prefix string `'10.b.c'`. Append `.0/24` for the subnet\n *   and `.1` for the gateway.\n */\nexport const deriveSubnetPrefix = (input: string, secondOctetOffset: number): string => {\n\tlet hash = 0x811c9dc5;\n\tfor (let i = 0; i < input.length; i += 1) {\n\t\thash ^= input.charCodeAt(i);\n\t\thash = Math.imul(hash, 0x01000193) >>> 0;\n\t}\n\tconst bucket = hash % (64 * 256);\n\tconst secondOctet = secondOctetOffset + Math.floor(bucket / 256);\n\tconst thirdOctet = bucket % 256;\n\treturn `10.${secondOctet}.${thirdOctet}`;\n};\n\n/**\n * Expand a `/24` prefix into the `{ subnet, gateway }` shape the\n * container-runtime `EnsureNetworkSpec` consumes.\n *\n * Convention: `<prefix>.0/24` for the subnet, `<prefix>.1` for the\n * gateway — the same pair walrus and seal both stamp on their\n * `ensureNetwork` requests. Folded here so the `/24` + `.1` literals\n * live in ONE place.\n */\nexport const subnetSpec = (\n\tprefix: string,\n): { readonly subnet: string; readonly gateway: string } => ({\n\tsubnet: `${prefix}.0/24`,\n\tgateway: `${prefix}.1`,\n});\n\n/**\n * Stamp the `{subnet, gateway}` pair derived from `subnetPrefix` onto\n * any `EnsureNetworkSpec`-shaped value. Both walrus and seal need the\n * same fold:\n *\n *   {...spec, ...subnetSpec(prefix)}\n *\n * to widen a substrate-blind network spec into one that carries the\n * plugin's deterministic `/24` addressing — folded here so the literal\n * `Required<Pick<…, 'subnet' | 'gateway'>>` widening type lives in\n * ONE place.\n */\nexport const withSubnetAddressing = <Spec extends EnsureNetworkSpec>(\n\tspec: Spec,\n\tsubnetPrefix: string,\n): Spec & Required<Pick<EnsureNetworkSpec, 'subnet' | 'gateway'>> => ({\n\t...spec,\n\t...subnetSpec(subnetPrefix),\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;AA6CA,MAAa,sBAAsB,OAAe,sBAAsC;CACvF,IAAI,OAAO;CACX,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,GAAG;EACzC,QAAQ,MAAM,WAAW,CAAC;EAC1B,OAAO,KAAK,KAAK,MAAM,QAAU,MAAM;CACxC;CACA,MAAM,SAAS,QAAQ,KAAK;CAG5B,OAAO,MAFa,oBAAoB,KAAK,MAAM,SAAS,GAAG,EAEtC,GADN,SAAS;AAE7B;;;;;;;;;;AAWA,MAAa,cACZ,YAC4D;CAC5D,QAAQ,GAAG,OAAO;CAClB,SAAS,GAAG,OAAO;AACpB;;;;;;;;;;;;;AAcA,MAAa,wBACZ,MACA,kBACqE;CACrE,GAAG;CACH,GAAG,WAAW,YAAY;AAC3B"}