@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/substrate/runtime/artifact-publisher/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/substrate/runtime/artifact-publisher/index.ts"],"sourcesContent":["// ArtifactPublisher — substrate-level service.\n//\n// Architecture §10: substrate primitive that orchestrates the\n// `cache → verify → produce → register` cycle every on-chain\n// produce/verify plugin (package, coin, walrus deploy, seal deploy,\n// deepbook deploy, etc.) flows through.\n//\n// Plugins call `publisher.publish(spec)` with their per-cycle\n// `ArtifactSpec<Produced, Verified>` (namespace, chain,\n// contentHash, verifySchema, verify, produce, register). The\n// substrate handles:\n//\n//   1. `cache.lookup({namespace, chain, contentHash})`. Hit AND\n//      `spec.verify` returns a non-null value → `register`(decoded\n//      cached payload) and return.\n//   2. Miss OR verify-returned-null → run `spec.produce` under the\n//      caller's Scope; on success, write the produced payload to\n//      the cache (best-effort, errors logged but not propagated);\n//      then `register(produced)`.\n//\n// The substrate carries the cache + chain-probe seams via Layers\n// (CacheService, StrategyRegistryService). Plugins yield this\n// service from their acquire body; the supervisor injects it via\n// pluginContext.\n//\n// Cache payload codec: we serialize `Produced` as JSON. The artifact publisher\n// spec doesn't bake a codec in (`Produced` is generic); JSON\n// round-trip matches existing plugin call sites\n// (`CachedPackageEntry`, `CachedMint`, etc. are JSON-shaped).\n\nimport { Context, Effect, Layer, Scope } from 'effect';\n\nimport type {\n\tArtifactPublishError,\n\tArtifactPublisher,\n\tArtifactSpec,\n} from '../../../primitives/artifact-publisher.ts';\nimport { CacheService } from '../cache/index.ts';\nimport { parseJsonTextSync } from '../runtime-decode.ts';\n\n// Re-export the ChainOperation typed seam — plugin authors compose\n// produce bodies via `compileChainOperation({...})` rather than\n// hand-rolling the `Effect<Produced, ArtifactPublishError, Scope>`.\n//\n// `ResolvedSigner` is intentionally NOT re-exported here — it is\n// owned by `sui-execute/` and reached via that module's barrel; both\n// modules share the single canonical shape.\nexport {\n\tcompileChainOperation,\n\ttype ChainOperation,\n\ttype OneShotRunner,\n\ttype OneShotSpec,\n\ttype SuiEffects,\n\ttype SuiTxBuilder,\n} from './chain-operation.ts';\n\n// ---------------------------------------------------------------------------\n// Service tag\n// ---------------------------------------------------------------------------\n\n/**\n * Substrate-level service projecting the\n * `ArtifactPublisher` primitive. Plugins yield this tag in\n * their acquire body; the supervisor's `pluginContext` carries it.\n *\n * The service is constructed once per stack (Layer-driven) and\n * closes over the per-stack Cache + StrategyRegistry. Parallel\n * stacks isolate by construction — each stack's Layer build is\n * independent.\n */\nexport class ArtifactPublisherService extends Context.Service<\n\tArtifactPublisherService,\n\tArtifactPublisher\n>()('@devstack-rewrite/substrate/ArtifactPublisher') {}\n\n// ---------------------------------------------------------------------------\n// Encode / decode the cached payload\n// ---------------------------------------------------------------------------\n\nconst encode = (value: unknown): Uint8Array => new TextEncoder().encode(JSON.stringify(value));\n\nconst decode = <Produced>(bytes: Uint8Array): Produced | null => {\n\ttry {\n\t\treturn parseJsonTextSync(new TextDecoder().decode(bytes), {\n\t\t\tsource: 'artifact-publisher cache payload',\n\t\t\tmkError: (issue) => issue,\n\t\t}) as Produced;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n// ---------------------------------------------------------------------------\n// Publish: cache → verify → produce → register\n// ---------------------------------------------------------------------------\n\nconst makePublisher = (cache: typeof CacheService.Service): ArtifactPublisher => ({\n\tpublish: <Produced, Verified>(\n\t\tspec: ArtifactSpec<Produced, Verified>,\n\t): Effect.Effect<Produced | Verified, ArtifactPublishError, Scope.Scope> =>\n\t\tEffect.gen(function* () {\n\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t'artifactPublisher.namespace': spec.namespace,\n\t\t\t\t'artifactPublisher.chain': spec.chain,\n\t\t\t\t'artifactPublisher.contentHash': spec.contentHash,\n\t\t\t});\n\n\t\t\t// 1. Cache lookup. Best-effort: a CacheError on lookup\n\t\t\t//    surfaces as `cache-corrupt`; the substrate's contract\n\t\t\t//    is \"re-produce is always safe\", so we coerce read\n\t\t\t//    failures to a miss rather than abort the cycle.\n\t\t\tconst hit = yield* cache\n\t\t\t\t.lookup({\n\t\t\t\t\tnamespace: spec.namespace,\n\t\t\t\t\tchain: spec.chain,\n\t\t\t\t\tcontentHash: spec.contentHash,\n\t\t\t\t})\n\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(null)));\n\n\t\t\tif (hit !== null) {\n\t\t\t\t// Decode the cached `Produced` BEFORE verify so the\n\t\t\t\t// plugin's verify Effect can key its on-chain probe\n\t\t\t\t// off a field of the cached payload (e.g. action's\n\t\t\t\t// `digest`, package's `packageId`). A decode failure\n\t\t\t\t// here is \"cache corruption\" — drop through to\n\t\t\t\t// re-produce so the cycle is still safe.\n\t\t\t\tconst cached = decode<Produced>(hit.bytes);\n\t\t\t\tif (cached !== null) {\n\t\t\t\t\t// 2. Verify (lenient — returns null on transient\n\t\t\t\t\t//    failure or not-found). Architecture §10:\n\t\t\t\t\t//    verify-on-hit covers chain-state drift.\n\t\t\t\t\tconst verified = yield* spec.verify(cached);\n\t\t\t\t\tif (verified !== null) {\n\t\t\t\t\t\tconst payload: Produced | Verified = cached;\n\t\t\t\t\t\tyield* spec.register(payload);\n\t\t\t\t\t\tyield* Effect.annotateCurrentSpan({ 'artifactPublisher.path': 'hit' });\n\t\t\t\t\t\treturn payload;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// 3. Miss or verify-failed → produce.\n\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t'artifactPublisher.path': hit === null ? 'miss' : 'verify-failed',\n\t\t\t});\n\t\t\tconst produced = yield* spec.produce;\n\n\t\t\t// 4. Cache write — best-effort. Architecture: a write\n\t\t\t//    failure must NOT roll back the on-chain effect.\n\t\t\tyield* cache\n\t\t\t\t.write(\n\t\t\t\t\t{\n\t\t\t\t\t\tnamespace: spec.namespace,\n\t\t\t\t\t\tchain: spec.chain,\n\t\t\t\t\t\tcontentHash: spec.contentHash,\n\t\t\t\t\t},\n\t\t\t\t\tencode(produced),\n\t\t\t\t)\n\t\t\t\t.pipe(Effect.catch(() => Effect.void));\n\n\t\t\t// 5. Register — fires on EVERY cycle (architecture §10).\n\t\t\tyield* spec.register(produced);\n\t\t\treturn produced;\n\t\t}).pipe(Effect.withSpan('substrate.artifactPublisher.publish')),\n});\n\n// ---------------------------------------------------------------------------\n// Layer\n// ---------------------------------------------------------------------------\n\n/**\n * Layer that materializes the publisher from the substrate's\n * Cache service. Plugins yield `ArtifactPublisherService`;\n * the supervisor provides it via `pluginContext`.\n *\n * The publisher is service-name-blind: it reaches `CacheService`\n * via the Context, NOT through a hard-coded import edge with any\n * plugin. Chain-probe lookup is the caller's concern — the spec's\n * `verify` Effect closes over the probe.\n */\nexport const layerArtifactPublisher: Layer.Layer<ArtifactPublisherService, never, CacheService> =\n\tLayer.effect(\n\t\tArtifactPublisherService,\n\t\tEffect.gen(function* () {\n\t\t\tconst cache = yield* CacheService;\n\t\t\treturn ArtifactPublisherService.of(makePublisher(cache));\n\t\t}),\n\t);\n"],"mappings":";;;;;;;;;;;;;;AAsEA,IAAa,2BAAb,cAA8C,QAAQ,SAGnD,CAAC,gDAAgD,CAAC;AAMrD,MAAM,UAAU,UAA+B,IAAI,aAAa,CAAC,OAAO,KAAK,UAAU,MAAM,CAAC;AAE9F,MAAM,UAAoB,UAAuC;AAChE,KAAI;AACH,SAAO,kBAAkB,IAAI,aAAa,CAAC,OAAO,MAAM,EAAE;GACzD,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC;SACK;AACP,SAAO;;;AAQT,MAAM,iBAAiB,WAA2D,EACjF,UACC,SAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB;EACjC,+BAA+B,KAAK;EACpC,2BAA2B,KAAK;EAChC,iCAAiC,KAAK;EACtC,CAAC;CAMF,MAAM,MAAM,OAAO,MACjB,OAAO;EACP,WAAW,KAAK;EAChB,OAAO,KAAK;EACZ,aAAa,KAAK;EAClB,CAAC,CACD,KAAK,OAAO,YAAY,OAAO,QAAQ,KAAK,CAAC,CAAC;AAEhD,KAAI,QAAQ,MAAM;EAOjB,MAAM,SAAS,OAAiB,IAAI,MAAM;AAC1C,MAAI,WAAW;QAKV,OADoB,KAAK,OAAO,OAAO,MAC1B,MAAM;IACtB,MAAM,UAA+B;AACrC,WAAO,KAAK,SAAS,QAAQ;AAC7B,WAAO,OAAO,oBAAoB,EAAE,0BAA0B,OAAO,CAAC;AACtE,WAAO;;;;AAMV,QAAO,OAAO,oBAAoB,EACjC,0BAA0B,QAAQ,OAAO,SAAS,iBAClD,CAAC;CACF,MAAM,WAAW,OAAO,KAAK;AAI7B,QAAO,MACL,MACA;EACC,WAAW,KAAK;EAChB,OAAO,KAAK;EACZ,aAAa,KAAK;EAClB,EACD,OAAO,SAAS,CAChB,CACA,KAAK,OAAO,YAAY,OAAO,KAAK,CAAC;AAGvC,QAAO,KAAK,SAAS,SAAS;AAC9B,QAAO;EACN,CAAC,KAAK,OAAO,SAAS,sCAAsC,CAAC,EAChE;;;;;;;;;;;AAgBD,MAAa,yBACZ,MAAM,OACL,0BACA,OAAO,IAAI,aAAa;CACvB,MAAM,QAAQ,OAAO;AACrB,QAAO,yBAAyB,GAAG,cAAc,MAAM,CAAC;EACvD,CACF"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/substrate/runtime/artifact-publisher/index.ts"],"sourcesContent":["// ArtifactPublisher — substrate-level service.\n//\n// Architecture §10: substrate primitive that orchestrates the\n// `cache → verify → produce → register` cycle every on-chain\n// produce/verify plugin (package, coin, walrus deploy, seal deploy,\n// deepbook deploy, etc.) flows through.\n//\n// Plugins call `publisher.publish(spec)` with their per-cycle\n// `ArtifactSpec<Produced, Verified>` (namespace, chain,\n// contentHash, verify, produce, register). The\n// substrate handles:\n//\n//   1. `cache.lookup({namespace, chain, contentHash})`. Hit AND\n//      `spec.verify` returns a non-null value → `register`(decoded\n//      cached payload) and return.\n//   2. Miss OR verify-returned-null → run `spec.produce` under the\n//      caller's Scope; on success, write the produced payload to\n//      the cache (best-effort, errors logged but not propagated);\n//      then `register(produced)`.\n//\n// The substrate carries the cache + chain-probe seams via Layers\n// (CacheService, StrategyRegistryService). Plugins yield this\n// service from their acquire body; the supervisor injects it via\n// pluginContext.\n//\n// Cache payload codec: we serialize `Produced` as JSON. The artifact publisher\n// spec doesn't bake a codec in (`Produced` is generic); JSON\n// round-trip matches existing plugin call sites\n// (`CachedPackageEntry`, `CachedMint`, etc. are JSON-shaped).\n\nimport { Context, Effect, Layer, Scope } from 'effect';\n\nimport type {\n\tArtifactPublishError,\n\tArtifactPublisher,\n\tArtifactSpec,\n} from '../../../primitives/artifact-publisher.ts';\nimport { CacheService } from '../cache/index.ts';\nimport { setCurrentPluginPhase } from '../current-plugin.ts';\nimport { SpanAttr } from '../observability/spans.ts';\nimport { parseJsonTextSync } from '../runtime-decode.ts';\n\n// ---------------------------------------------------------------------------\n// Service tag\n// ---------------------------------------------------------------------------\n\n/**\n * Substrate-level service projecting the\n * `ArtifactPublisher` primitive. Plugins yield this tag in\n * their acquire body; the supervisor's `pluginContext` carries it.\n *\n * The service is constructed once per stack (Layer-driven) and\n * closes over the per-stack Cache + StrategyRegistry. Parallel\n * stacks isolate by construction — each stack's Layer build is\n * independent.\n */\nexport class ArtifactPublisherService extends Context.Service<\n\tArtifactPublisherService,\n\tArtifactPublisher\n>()('@devstack/substrate/ArtifactPublisher') {}\n\n// ---------------------------------------------------------------------------\n// Encode / decode the cached payload\n// ---------------------------------------------------------------------------\n\nconst encode = (value: unknown): Uint8Array => new TextEncoder().encode(JSON.stringify(value));\n\nconst decode = <Produced>(bytes: Uint8Array): Produced | null => {\n\ttry {\n\t\treturn parseJsonTextSync(new TextDecoder().decode(bytes), {\n\t\t\tsource: 'artifact-publisher cache payload',\n\t\t\tmkError: (issue) => issue,\n\t\t}) as Produced;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n// ---------------------------------------------------------------------------\n// Publish: cache → verify → produce → register\n// ---------------------------------------------------------------------------\n\nconst makePublisher = (cache: typeof CacheService.Service): ArtifactPublisher => ({\n\tpublish: <Produced, Verified>(\n\t\tspec: ArtifactSpec<Produced, Verified>,\n\t): Effect.Effect<Produced, ArtifactPublishError, Scope.Scope> =>\n\t\tEffect.gen(function* () {\n\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t[SpanAttr.artifactPublisherNamespace]: spec.namespace,\n\t\t\t\t[SpanAttr.artifactPublisherChain]: spec.chain,\n\t\t\t\t[SpanAttr.artifactPublisherContentHash]: spec.contentHash,\n\t\t\t});\n\n\t\t\t// 1. Cache lookup. Best-effort: a CacheError on lookup\n\t\t\t//    surfaces as `cache-corrupt`; the substrate's contract\n\t\t\t//    is \"re-produce is always safe\", so we coerce read\n\t\t\t//    failures to a miss rather than abort the cycle.\n\t\t\tconst hit = yield* cache\n\t\t\t\t.lookup({\n\t\t\t\t\tnamespace: spec.namespace,\n\t\t\t\t\tchain: spec.chain,\n\t\t\t\t\tcontentHash: spec.contentHash,\n\t\t\t\t})\n\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(null)));\n\n\t\t\tif (hit !== null) {\n\t\t\t\t// Decode the cached `Produced` BEFORE verify so the\n\t\t\t\t// plugin's verify Effect can key its on-chain probe\n\t\t\t\t// off a field of the cached payload (e.g. action's\n\t\t\t\t// `digest`, package's `packageId`). A decode failure\n\t\t\t\t// here is \"cache corruption\" — drop through to\n\t\t\t\t// re-produce so the cycle is still safe.\n\t\t\t\tconst cached = decode<Produced>(hit.bytes);\n\t\t\t\tif (cached !== null) {\n\t\t\t\t\t// 2. Verify (lenient — returns null on transient\n\t\t\t\t\t//    failure or not-found). Architecture §10:\n\t\t\t\t\t//    verify-on-hit covers chain-state drift.\n\t\t\t\t\tconst verified = yield* spec.verify(cached);\n\t\t\t\t\tif (verified !== null) {\n\t\t\t\t\t\t// The substrate always returns the decoded\n\t\t\t\t\t\t// `Produced` payload — the `Verified` shape is a\n\t\t\t\t\t\t// probe-only signal that never escapes. Callers\n\t\t\t\t\t\t// therefore type-narrow trivially against `Produced`.\n\t\t\t\t\t\tyield* spec.register(cached);\n\t\t\t\t\t\tyield* Effect.annotateCurrentSpan({ [SpanAttr.artifactPublisherPath]: 'hit' });\n\t\t\t\t\t\t// Reuse is the quiet, expected warm-restart path — debug\n\t\t\t\t\t\t// only. The interesting (and noisy) case is a *re-run*,\n\t\t\t\t\t\t// logged below.\n\t\t\t\t\t\tyield* Effect.logDebug(\n\t\t\t\t\t\t\t`artifact-publisher: reusing cached '${spec.namespace}' on chain ${spec.chain} ` +\n\t\t\t\t\t\t\t\t`(cache hit; no re-deploy).`,\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn cached;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// 3. Miss or verify-failed → produce. State WHEN and WHY loudly:\n\t\t\t//    on a restart this is the line that explains why an on-chain\n\t\t\t//    id is about to change. A fresh chain genesis misses every\n\t\t\t//    cache key (keyed by chain id), so packages / key servers /\n\t\t\t//    walrus all get brand-new ids, and content bound to the old\n\t\t\t//    ids (e.g. Seal-encrypted blobs) can no longer be resolved.\n\t\t\tif (hit === null) {\n\t\t\t\tyield* Effect.annotateCurrentSpan({ [SpanAttr.artifactPublisherPath]: 'miss' });\n\t\t\t\tyield* Effect.logInfo(\n\t\t\t\t\t`artifact-publisher: producing '${spec.namespace}' on chain ${spec.chain} — ` +\n\t\t\t\t\t\t`no cached artifact for this chain + content hash ` +\n\t\t\t\t\t\t`(first deploy on this chain, fresh genesis after a restart, or changed inputs).`,\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t[SpanAttr.artifactPublisherPath]: 'verify-failed',\n\t\t\t\t});\n\t\t\t\tyield* Effect.logWarning(\n\t\t\t\t\t`artifact-publisher: re-deploying '${spec.namespace}' on chain ${spec.chain} — ` +\n\t\t\t\t\t\t`a cached artifact existed but failed on-chain verification ` +\n\t\t\t\t\t\t`(object missing, or RPC unavailable during restart); a new id will replace ` +\n\t\t\t\t\t\t`the prior deployment.`,\n\t\t\t\t);\n\t\t\t\t// Effect logs are dropped under the `up` TUI (Logger.layer([])).\n\t\t\t\t// The verify-failed re-deploy is the anomalous restart case — a\n\t\t\t\t// cached id existed but is no longer resolvable — so narrate it\n\t\t\t\t// on the supervised plugin's row, the channel the TUI renders.\n\t\t\t\t// (A plain cache miss stays quiet here: on a cold boot every\n\t\t\t\t// artifact misses, and the plugin narrates its own publish.)\n\t\t\t\tyield* setCurrentPluginPhase(\n\t\t\t\t\t`re-deploying ${spec.namespace} (cached artifact failed verification on restart)`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst produced = yield* spec.produce;\n\n\t\t\t// 4. Cache write — best-effort. Architecture: a write\n\t\t\t//    failure must NOT roll back the on-chain effect.\n\t\t\tyield* cache\n\t\t\t\t.write(\n\t\t\t\t\t{\n\t\t\t\t\t\tnamespace: spec.namespace,\n\t\t\t\t\t\tchain: spec.chain,\n\t\t\t\t\t\tcontentHash: spec.contentHash,\n\t\t\t\t\t},\n\t\t\t\t\tencode(produced),\n\t\t\t\t)\n\t\t\t\t.pipe(Effect.catch(() => Effect.void));\n\n\t\t\t// 5. Register — fires on EVERY cycle (architecture §10).\n\t\t\tyield* spec.register(produced);\n\t\t\treturn produced;\n\t\t}).pipe(Effect.withSpan('substrate.artifactPublisher.publish')),\n});\n\n// ---------------------------------------------------------------------------\n// Layer\n// ---------------------------------------------------------------------------\n\n/**\n * Layer that materializes the publisher from the substrate's\n * Cache service. Plugins yield `ArtifactPublisherService`;\n * the supervisor provides it via `pluginContext`.\n *\n * The publisher is service-name-blind: it reaches `CacheService`\n * via the Context, NOT through a hard-coded import edge with any\n * plugin. Chain-probe lookup is the caller's concern — the spec's\n * `verify` Effect closes over the probe.\n */\nexport const layerArtifactPublisher: Layer.Layer<ArtifactPublisherService, never, CacheService> =\n\tLayer.effect(\n\t\tArtifactPublisherService,\n\t\tEffect.gen(function* () {\n\t\t\tconst cache = yield* CacheService;\n\t\t\treturn ArtifactPublisherService.of(makePublisher(cache));\n\t\t}),\n\t);\n"],"mappings":";;;;;;;;;;;;;;;;;AAwDA,IAAa,2BAAb,cAA8C,QAAQ,SAGnD,CAAC,wCAAwC,CAAC;AAM7C,MAAM,UAAU,UAA+B,IAAI,aAAa,CAAC,OAAO,KAAK,UAAU,MAAM,CAAC;AAE9F,MAAM,UAAoB,UAAuC;AAChE,KAAI;AACH,SAAO,kBAAkB,IAAI,aAAa,CAAC,OAAO,MAAM,EAAE;GACzD,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC;SACK;AACP,SAAO;;;AAQT,MAAM,iBAAiB,WAA2D,EACjF,UACC,SAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB;GAChC,SAAS,6BAA6B,KAAK;GAC3C,SAAS,yBAAyB,KAAK;GACvC,SAAS,+BAA+B,KAAK;EAC9C,CAAC;CAMF,MAAM,MAAM,OAAO,MACjB,OAAO;EACP,WAAW,KAAK;EAChB,OAAO,KAAK;EACZ,aAAa,KAAK;EAClB,CAAC,CACD,KAAK,OAAO,YAAY,OAAO,QAAQ,KAAK,CAAC,CAAC;AAEhD,KAAI,QAAQ,MAAM;EAOjB,MAAM,SAAS,OAAiB,IAAI,MAAM;AAC1C,MAAI,WAAW;QAKV,OADoB,KAAK,OAAO,OAAO,MAC1B,MAAM;AAKtB,WAAO,KAAK,SAAS,OAAO;AAC5B,WAAO,OAAO,oBAAoB,GAAG,SAAS,wBAAwB,OAAO,CAAC;AAI9E,WAAO,OAAO,SACb,uCAAuC,KAAK,UAAU,aAAa,KAAK,MAAM,6BAE9E;AACD,WAAO;;;;AAWV,KAAI,QAAQ,MAAM;AACjB,SAAO,OAAO,oBAAoB,GAAG,SAAS,wBAAwB,QAAQ,CAAC;AAC/E,SAAO,OAAO,QACb,kCAAkC,KAAK,UAAU,aAAa,KAAK,MAAM,qIAGzE;QACK;AACN,SAAO,OAAO,oBAAoB,GAChC,SAAS,wBAAwB,iBAClC,CAAC;AACF,SAAO,OAAO,WACb,qCAAqC,KAAK,UAAU,aAAa,KAAK,MAAM,gKAI5E;AAOD,SAAO,sBACN,gBAAgB,KAAK,UAAU,mDAC/B;;CAEF,MAAM,WAAW,OAAO,KAAK;AAI7B,QAAO,MACL,MACA;EACC,WAAW,KAAK;EAChB,OAAO,KAAK;EACZ,aAAa,KAAK;EAClB,EACD,OAAO,SAAS,CAChB,CACA,KAAK,OAAO,YAAY,OAAO,KAAK,CAAC;AAGvC,QAAO,KAAK,SAAS,SAAS;AAC9B,QAAO;EACN,CAAC,KAAK,OAAO,SAAS,sCAAsC,CAAC,EAChE;;;;;;;;;;;AAgBD,MAAa,yBACZ,MAAM,OACL,0BACA,OAAO,IAAI,aAAa;CACvB,MAAM,QAAQ,OAAO;AACrB,QAAO,yBAAyB,GAAG,cAAc,MAAM,CAAC;EACvD,CACF"}

package/dist/substrate/runtime/atomic-write.mjs

@@ -1,7 +1,8 @@
+import { selfPid } from "./cross-process/self-pid.mjs";
 import { AtomicWriteFailed } from "./errors.mjs";
 import { Effect, FileSystem, Schema } from "effect";
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { closeSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 //#region src/substrate/runtime/atomic-write.ts
 /** 8-hex tempfile suffix. `crypto.randomUUID()` is collision-safe under
 *  parallel callers within the same pid — replaces the
@@ -23,20 +24,22 @@ const atomicWriteFile = (path, bytes, options = {}) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const mode = options.mode ?? 384;
 	const parentMode = options.parentMode ?? 448;
-	const tmp = `${path}.tmp.${process.pid}.${tempSuffix()}`;
+	const tmp = `${path}.tmp.${selfPid()}.${tempSuffix()}`;
 	yield* fs.makeDirectory(dirname(path), {
 		recursive: true,
 		mode: parentMode
 	}).pipe(Effect.catch(failStage(path, "mkdir-parent")));
-	yield* Effect.scoped(Effect.gen(function* () {
-		const file = yield* fs.open(tmp, {
-			flag: "wx",
-			mode
-		}).pipe(Effect.catch(failStage(path, "open-temp")));
-		yield* file.writeAll(bytes).pipe(Effect.catch(failStage(path, "write")));
-		yield* file.sync.pipe(Effect.catch(failStage(path, "fsync")));
-	}));
-	yield* fs.rename(tmp, path).pipe(Effect.catch((cause) => fs.remove(tmp, { force: true }).pipe(Effect.ignore, Effect.andThen(failStage(path, "rename")(cause)))));
+	yield* Effect.gen(function* () {
+		yield* Effect.scoped(Effect.gen(function* () {
+			const file = yield* fs.open(tmp, {
+				flag: "wx",
+				mode
+			}).pipe(Effect.catch(failStage(path, "open-temp")));
+			yield* file.writeAll(bytes).pipe(Effect.catch(failStage(path, "write")));
+			yield* file.sync.pipe(Effect.catch(failStage(path, "fsync")));
+		}));
+		yield* fs.rename(tmp, path).pipe(Effect.catch(failStage(path, "rename")));
+	}).pipe(Effect.onError(() => fs.remove(tmp, { force: true }).pipe(Effect.ignore)));
 }).pipe(Effect.withSpan("substrate.atomicWriteFile", { attributes: { path } }));
 /**
 * Atomically write a JSON value. Encodes via Schema (so the on-disk
@@ -49,20 +52,20 @@ const atomicWriteJson = (path, schema, value, options) => Effect.gen(function* (
 	yield* atomicWriteFile(path, new TextEncoder().encode(json), options);
 });
 /**
-* Synchronous atomic write. Same disk-side contract as
-* `atomicWriteFile` (mkdir-parent → O_EXCL temp → write → fsync →
-* rename). Returns `void` on success; throws on any failure with
-* `cause` set to the underlying `NodeJS.ErrnoException`.
+* Internal: mkdir-parent → O_EXCL temp → write → fsync. Returns the
+* tempfile path on success; throws on any failure (and unlinks the
+* tempfile if it managed to land). The temp exists after return —
+* the caller is responsible for moving it to its final home (rename
+* for clobber semantics, link for exclusive-create semantics) AND
+* for unlinking the temp afterwards.
 *
-* Used inside `Effect.try` by the cross-process modules; the caller
-* maps the thrown error to a typed plugin/runtime error
-* (`RosterIoError` / `SnapshotReservationIoError` / etc.).
+* Centralizes the durability boundary so both `atomicWriteFileSync`
+* (rename) and `atomicWriteFileExclusiveSync` (link+unlink) share
+* one tempfile/fsync implementation.
 */
-const atomicWriteFileSync = (path, bytes, options = {}) => {
-	const mode = options.mode ?? 384;
-	const parentMode = options.parentMode ?? 448;
-	const tmp = `${path}.tmp.${process.pid}.${tempSuffix()}`;
-	mkdirSync(dirname(path), {
+const writeAndFsyncTempSync = (finalPath, bytes, mode, parentMode) => {
+	const tmp = `${finalPath}.tmp.${selfPid()}.${tempSuffix()}`;
+	mkdirSync(dirname(finalPath), {
 		recursive: true,
 		mode: parentMode
 	});
@@ -70,21 +73,83 @@ const atomicWriteFileSync = (path, bytes, options = {}) => {
 		flag: "wx",
 		mode
 	});
-	let fd = null;
-	try {
-		fd = openSync(tmp, "r");
-		fsyncSync(fd);
-	} finally {
-		if (fd !== null) closeSync(fd);
-	}
 	try {
-		renameSync(tmp, path);
+		let fd = null;
+		try {
+			fd = openSync(tmp, "r");
+			fsyncSync(fd);
+		} finally {
+			if (fd !== null) closeSync(fd);
+		}
 	} catch (cause) {
 		try {
 			unlinkSync(tmp);
 		} catch {}
 		throw cause;
 	}
+	return tmp;
+};
+/** Best-effort unlink. Swallows errors — used in cleanup paths where
+*  a failure to remove the temp should NOT mask the original error. */
+const unlinkBestEffort = (path) => {
+	try {
+		unlinkSync(path);
+	} catch {}
+};
+/**
+* Synchronous atomic write. Same disk-side contract as
+* `atomicWriteFile` (mkdir-parent → O_EXCL temp → write → fsync →
+* rename). Returns `void` on success; throws on any failure with
+* `cause` set to the underlying `NodeJS.ErrnoException`.
+*
+* Rename CLOBBERS a pre-existing file at the final path. Callers
+* that need exclusive-create semantics ("fail if the final path
+* already exists, atomically") want `atomicWriteFileExclusiveSync`
+* instead — that surface uses `linkSync` which is POSIX-atomic and
+* fails with `EEXIST` rather than overwriting.
+*
+* Used inside `Effect.try` by the cross-process modules; the caller
+* maps the thrown error to a typed plugin/runtime error
+* (`RosterIoError` / `SnapshotReservationIoError` / etc.).
+*/
+const atomicWriteFileSync = (path, bytes, options = {}) => {
+	const tmp = writeAndFsyncTempSync(path, bytes, options.mode ?? 384, options.parentMode ?? 448);
+	let renamed = false;
+	try {
+		renameSync(tmp, path);
+		renamed = true;
+	} finally {
+		if (!renamed) unlinkBestEffort(tmp);
+	}
+};
+/**
+* Synchronous atomic EXCLUSIVE-CREATE write. Same disk-side contract
+* as `atomicWriteFileSync` (mkdir-parent → O_EXCL temp → write →
+* fsync) but uses `linkSync(tmp, final)` instead of `renameSync` for
+* the final installation step. `link` is POSIX-atomic and FAILS with
+* `EEXIST` if the target already exists — closing the rename-clobber
+* race that `existsSync` + `renameSync` cannot.
+*
+* On success: the tempfile is unlinked (the hard link satisfies the
+* final path).
+*
+* On `EEXIST`: the tempfile is unlinked and the underlying
+* `NodeJS.ErrnoException` (with `code === 'EEXIST'`) is rethrown so
+* the caller can read the winning final-path and decide what to do.
+*
+* On any other failure: the tempfile is unlinked and the error is
+* rethrown unchanged.
+*
+* POSIX `link(2)` is available on Linux + macOS + WSL. Devstack is
+* POSIX-only at runtime.
+*/
+const atomicWriteFileExclusiveSync = (path, bytes, options = {}) => {
+	const tmp = writeAndFsyncTempSync(path, bytes, options.mode ?? 384, options.parentMode ?? 448);
+	try {
+		linkSync(tmp, path);
+	} finally {
+		unlinkBestEffort(tmp);
+	}
 };
 /**
 * Synchronous atomic JSON write. Stringifies `value` and routes
@@ -101,6 +166,6 @@ const dirname = (p) => {
 	return i <= 0 ? "/" : p.slice(0, i);
 };
 //#endregion
-export { atomicWriteFile, atomicWriteJson, atomicWriteJsonSync };
+export { atomicWriteFile, atomicWriteFileExclusiveSync, atomicWriteFileSync, atomicWriteJson, atomicWriteJsonSync };
 
 //# sourceMappingURL=atomic-write.mjs.map

package/dist/substrate/runtime/atomic-write.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-write.mjs","names":[],"sources":["../../../src/substrate/runtime/atomic-write.ts"],"sourcesContent":["// Atomic write primitive — ONE canonical implementation.\n//\n// Architecture § \"What's collapsed\" — three tempfile+rename impls\n// (atomic-write, state-store, global registry) collapse to one. This\n// is that one.\n//\n// Contract:\n//   1. Ensure parent directory exists.\n//   2. Open `<final>.tmp.<pid>.<rand>` with `wx` (O_EXCL) — refuse\n//      to clobber a half-written sibling from a crashed earlier\n//      writer in the same pid.\n//   3. Write bytes.\n//   4. `fsync` the file.\n//   5. Rename tempfile → final. Rename on POSIX is atomic w.r.t.\n//      `open` of the final path.\n//   6. On any failure mid-flight, unlink the tempfile. Best-effort:\n//      a tempfile-cleanup failure does NOT mask the original error.\n//\n// Two surfaces:\n//   - `atomicWriteFile` / `atomicWriteJson` — Effect/FileSystem-based,\n//     used by every async write site (manifest, state-store, cache).\n//   - `atomicWriteFileSync` / `atomicWriteJsonSync` — node:fs-sync,\n//     used by the cross-process modules (roster, snapshot-reservation,\n//     stack-lock) that hold `stack.lock` and must keep their critical\n//     section non-yielding. Substrate-fix-plan #11 tracks unifying\n//     these onto Effect FS once we lift the cross-process modules off\n//     `node:fs`; until then both surfaces share THIS file (and only\n//     this file) so the tempfile dance has ONE owner.\n//\n// What we do NOT do here:\n//   - fsync the parent directory. Linux's man fsync(2) suggests it\n//     for full durability after rename(); the Effect platform layer\n//     does not expose dir-fsync. Documented limitation — recoverable\n//     on crash because the state-store rewrites on every change and\n//     cache misses re-produce.\n\nimport {\n\tcloseSync,\n\tfsyncSync,\n\tmkdirSync,\n\topenSync,\n\trenameSync,\n\tunlinkSync,\n\twriteFileSync,\n} from 'node:fs';\nimport { randomUUID } from 'node:crypto';\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport { AtomicWriteFailed } from './errors.ts';\n\n/** 8-hex tempfile suffix. `crypto.randomUUID()` is collision-safe under\n *  parallel callers within the same pid — replaces the\n *  `Math.random()`-based suffix flagged in STYLE_GUIDE §17. */\nconst tempSuffix = (): string => randomUUID().replace(/-/g, '').slice(0, 8);\n\nconst failStage =\n\t(\n\t\tpath: string,\n\t\tstage: AtomicWriteFailed['stage'],\n\t): ((cause: unknown) => Effect.Effect<never, AtomicWriteFailed>) =>\n\t(cause) =>\n\t\tEffect.fail(new AtomicWriteFailed({ path, stage, cause }));\n\n/**\n * Atomically write `bytes` to `path`. The helper ensures\n * `dirname(path)` exists (recursive mkdir, idempotent).\n *\n * `mode` is the final file mode bits (default 0o600 — secret-safe\n * default; cache callers may bump to 0o644 if they want world-read).\n */\nexport const atomicWriteFile = (\n\tpath: string,\n\tbytes: Uint8Array,\n\toptions: { readonly mode?: number; readonly parentMode?: number } = {},\n): Effect.Effect<void, AtomicWriteFailed, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst mode = options.mode ?? 0o600;\n\t\tconst parentMode = options.parentMode ?? 0o700;\n\t\tconst tmp = `${path}.tmp.${process.pid}.${tempSuffix()}`;\n\t\t// 1. Ensure parent. recursive: true is idempotent under\n\t\t//    concurrent callers — `mkdir -p` semantics.\n\t\tyield* fs\n\t\t\t.makeDirectory(dirname(path), { recursive: true, mode: parentMode })\n\t\t\t.pipe(Effect.catch(failStage(path, 'mkdir-parent')));\n\t\t// 2-4. Open tempfile with `wx` (O_EXCL), write, fsync, all\n\t\t//      inside a Scope so the file handle closes on any path.\n\t\tyield* Effect.scoped(\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst file = yield* fs\n\t\t\t\t\t.open(tmp, { flag: 'wx', mode })\n\t\t\t\t\t.pipe(Effect.catch(failStage(path, 'open-temp')));\n\t\t\t\tyield* file.writeAll(bytes).pipe(Effect.catch(failStage(path, 'write')));\n\t\t\t\t// fsync — durability boundary. Without this the\n\t\t\t\t// rename can land but bytes can stay in the page\n\t\t\t\t// cache through a power loss.\n\t\t\t\tyield* file.sync.pipe(Effect.catch(failStage(path, 'fsync')));\n\t\t\t}),\n\t\t);\n\t\t// 5. Atomic rename. On failure unlink the tempfile so we\n\t\t//    don't leak; unlink failure is ignored (the original\n\t\t//    rename failure is the one that matters).\n\t\tyield* fs\n\t\t\t.rename(tmp, path)\n\t\t\t.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tfs\n\t\t\t\t\t\t.remove(tmp, { force: true })\n\t\t\t\t\t\t.pipe(Effect.ignore, Effect.andThen(failStage(path, 'rename')(cause))),\n\t\t\t\t),\n\t\t\t);\n\t}).pipe(Effect.withSpan('substrate.atomicWriteFile', { attributes: { path } }));\n\n/**\n * Atomically write a JSON value. Encodes via Schema (so the on-disk\n * shape is the schema's `Encoded` form, not the rich `Type`). Caller\n * supplies a schema whose `Type` matches `value`.\n */\nexport const atomicWriteJson = <A, I>(\n\tpath: string,\n\tschema: Schema.Codec<A, I>,\n\tvalue: A,\n\toptions?: { readonly mode?: number; readonly parentMode?: number },\n): Effect.Effect<void, AtomicWriteFailed, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst encoded = yield* Schema.encodeUnknownEffect(schema)(value).pipe(\n\t\t\tEffect.catch(failStage(path, 'encode')),\n\t\t);\n\t\tconst json = JSON.stringify(encoded, null, 2);\n\t\tconst bytes = new TextEncoder().encode(json);\n\t\tyield* atomicWriteFile(path, bytes, options);\n\t});\n\n// -----------------------------------------------------------------------------\n// Sync surface — for the cross-process modules that hold `stack.lock`\n// and must keep their critical section non-yielding. Same contract as\n// the Effect surface above.\n// -----------------------------------------------------------------------------\n\n/**\n * Synchronous atomic write. Same disk-side contract as\n * `atomicWriteFile` (mkdir-parent → O_EXCL temp → write → fsync →\n * rename). Returns `void` on success; throws on any failure with\n * `cause` set to the underlying `NodeJS.ErrnoException`.\n *\n * Used inside `Effect.try` by the cross-process modules; the caller\n * maps the thrown error to a typed plugin/runtime error\n * (`RosterIoError` / `SnapshotReservationIoError` / etc.).\n */\nexport const atomicWriteFileSync = (\n\tpath: string,\n\tbytes: Uint8Array | string,\n\toptions: { readonly mode?: number; readonly parentMode?: number } = {},\n): void => {\n\tconst mode = options.mode ?? 0o600;\n\tconst parentMode = options.parentMode ?? 0o700;\n\tconst tmp = `${path}.tmp.${process.pid}.${tempSuffix()}`;\n\tmkdirSync(dirname(path), { recursive: true, mode: parentMode });\n\t// O_EXCL via `flag: 'wx'`. writeFileSync handles open + write +\n\t// close in one call but does NOT fsync; do it manually so we\n\t// preserve the durability boundary the Effect surface has.\n\twriteFileSync(tmp, bytes, { flag: 'wx', mode });\n\t// fsync — open the file just to fsync the bytes through the page\n\t// cache. `writeFileSync` already closed the original fd.\n\tlet fd: number | null = null;\n\ttry {\n\t\tfd = openSync(tmp, 'r');\n\t\tfsyncSync(fd);\n\t} finally {\n\t\tif (fd !== null) closeSync(fd);\n\t}\n\ttry {\n\t\trenameSync(tmp, path);\n\t} catch (cause) {\n\t\t// Best-effort tempfile cleanup; the original rename failure is\n\t\t// the one we re-throw to the caller.\n\t\ttry {\n\t\t\tunlinkSync(tmp);\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t\tthrow cause;\n\t}\n};\n\n/**\n * Synchronous atomic JSON write. Stringifies `value` and routes\n * through `atomicWriteFileSync`. No Schema encoding here — the\n * cross-process modules round-trip plain JSON (their schemas are\n * Schema.Struct of primitives; `JSON.stringify` is sufficient and\n * keeps the sync path dependency-free of Effect's Schema effects).\n */\nexport const atomicWriteJsonSync = (\n\tpath: string,\n\tvalue: unknown,\n\toptions?: { readonly mode?: number; readonly parentMode?: number },\n): void => {\n\tconst json = JSON.stringify(value);\n\tatomicWriteFileSync(path, json, options);\n};\n\n// Local dirname — we don't yield Path service here because\n// atomic-write may be called outside of a path-service-having\n// context (tests, recovery scripts). Posix-only; devstack is\n// posix-only in practice.\nconst dirname = (p: string): string => {\n\tconst i = p.lastIndexOf('/');\n\treturn i <= 0 ? '/' : p.slice(0, i);\n};\n"],"mappings":";;;;;;;;AAsDA,MAAM,mBAA2B,YAAY,CAAC,QAAQ,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE;AAE3E,MAAM,aAEJ,MACA,WAEA,UACA,OAAO,KAAK,IAAI,kBAAkB;CAAE;CAAM;CAAO;CAAO,CAAC,CAAC;;;;;;;;AAS5D,MAAa,mBACZ,MACA,OACA,UAAoE,EAAE,KAEtE,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,MAAM,GAAG,KAAK,OAAO,QAAQ,IAAI,GAAG,YAAY;AAGtD,QAAO,GACL,cAAc,QAAQ,KAAK,EAAE;EAAE,WAAW;EAAM,MAAM;EAAY,CAAC,CACnE,KAAK,OAAO,MAAM,UAAU,MAAM,eAAe,CAAC,CAAC;AAGrD,QAAO,OAAO,OACb,OAAO,IAAI,aAAa;EACvB,MAAM,OAAO,OAAO,GAClB,KAAK,KAAK;GAAE,MAAM;GAAM;GAAM,CAAC,CAC/B,KAAK,OAAO,MAAM,UAAU,MAAM,YAAY,CAAC,CAAC;AAClD,SAAO,KAAK,SAAS,MAAM,CAAC,KAAK,OAAO,MAAM,UAAU,MAAM,QAAQ,CAAC,CAAC;AAIxE,SAAO,KAAK,KAAK,KAAK,OAAO,MAAM,UAAU,MAAM,QAAQ,CAAC,CAAC;GAC5D,CACF;AAID,QAAO,GACL,OAAO,KAAK,KAAK,CACjB,KACA,OAAO,OAAO,UACb,GACE,OAAO,KAAK,EAAE,OAAO,MAAM,CAAC,CAC5B,KAAK,OAAO,QAAQ,OAAO,QAAQ,UAAU,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC,CACvE,CACD;EACD,CAAC,KAAK,OAAO,SAAS,6BAA6B,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC;;;;;;AAOhF,MAAa,mBACZ,MACA,QACA,OACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAU,OAAO,OAAO,oBAAoB,OAAO,CAAC,MAAM,CAAC,KAChE,OAAO,MAAM,UAAU,MAAM,SAAS,CAAC,CACvC;CACD,MAAM,OAAO,KAAK,UAAU,SAAS,MAAM,EAAE;AAE7C,QAAO,gBAAgB,MADT,IAAI,aAAa,CAAC,OAAO,KACL,EAAE,QAAQ;EAC3C;;;;;;;;;;;AAkBH,MAAa,uBACZ,MACA,OACA,UAAoE,EAAE,KAC5D;CACV,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,MAAM,GAAG,KAAK,OAAO,QAAQ,IAAI,GAAG,YAAY;AACtD,WAAU,QAAQ,KAAK,EAAE;EAAE,WAAW;EAAM,MAAM;EAAY,CAAC;AAI/D,eAAc,KAAK,OAAO;EAAE,MAAM;EAAM;EAAM,CAAC;CAG/C,IAAI,KAAoB;AACxB,KAAI;AACH,OAAK,SAAS,KAAK,IAAI;AACvB,YAAU,GAAG;WACJ;AACT,MAAI,OAAO,KAAM,WAAU,GAAG;;AAE/B,KAAI;AACH,aAAW,KAAK,KAAK;UACb,OAAO;AAGf,MAAI;AACH,cAAW,IAAI;UACR;AAGR,QAAM;;;;;;;;;;AAWR,MAAa,uBACZ,MACA,OACA,YACU;AAEV,qBAAoB,MADP,KAAK,UAAU,MACE,EAAE,QAAQ;;AAOzC,MAAM,WAAW,MAAsB;CACtC,MAAM,IAAI,EAAE,YAAY,IAAI;AAC5B,QAAO,KAAK,IAAI,MAAM,EAAE,MAAM,GAAG,EAAE"}
+{"version":3,"file":"atomic-write.mjs","names":[],"sources":["../../../src/substrate/runtime/atomic-write.ts"],"sourcesContent":["// Atomic write primitive — ONE canonical implementation.\n//\n// Architecture § \"What's collapsed\" — three tempfile+rename impls\n// (atomic-write, state-store, global registry) collapse to one. This\n// is that one.\n//\n// Contract:\n//   1. Ensure parent directory exists.\n//   2. Open `<final>.tmp.<pid>.<rand>` with `wx` (O_EXCL) — refuse\n//      to clobber a half-written sibling from a crashed earlier\n//      writer in the same pid.\n//   3. Write bytes.\n//   4. `fsync` the file.\n//   5. Rename tempfile → final. Rename on POSIX is atomic w.r.t.\n//      `open` of the final path.\n//   6. On any failure mid-flight, unlink the tempfile. Best-effort:\n//      a tempfile-cleanup failure does NOT mask the original error.\n//\n// Two surfaces:\n//   - `atomicWriteFile` / `atomicWriteJson` — Effect/FileSystem-based,\n//     used by every async write site (manifest, state-store, cache).\n//   - `atomicWriteFileSync` / `atomicWriteJsonSync` — node:fs-sync,\n//     used by the cross-process modules (roster, snapshot-reservation,\n//     stack-lock) that hold `stack.lock` and must keep their critical\n//     section non-yielding. Substrate-fix-plan #11 tracks unifying\n//     these onto Effect FS once we lift the cross-process modules off\n//     `node:fs`; until then both surfaces share THIS file (and only\n//     this file) so the tempfile dance has ONE owner.\n//\n// What we do NOT do here:\n//   - fsync the parent directory. Linux's man fsync(2) suggests it\n//     for full durability after rename(); the Effect platform layer\n//     does not expose dir-fsync. Documented limitation — recoverable\n//     on crash because the state-store rewrites on every change and\n//     cache misses re-produce.\n\nimport {\n\tcloseSync,\n\tfsyncSync,\n\tlinkSync,\n\tmkdirSync,\n\topenSync,\n\trenameSync,\n\tunlinkSync,\n\twriteFileSync,\n} from 'node:fs';\nimport { randomUUID } from 'node:crypto';\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport { selfPid } from './cross-process/self-pid.ts';\nimport { AtomicWriteFailed } from './errors.ts';\n\n/** 8-hex tempfile suffix. `crypto.randomUUID()` is collision-safe under\n *  parallel callers within the same pid — replaces the\n *  `Math.random()`-based suffix flagged in STYLE_GUIDE §17. */\nconst tempSuffix = (): string => randomUUID().replace(/-/g, '').slice(0, 8);\n\nconst failStage =\n\t(\n\t\tpath: string,\n\t\tstage: AtomicWriteFailed['stage'],\n\t): ((cause: unknown) => Effect.Effect<never, AtomicWriteFailed>) =>\n\t(cause) =>\n\t\tEffect.fail(new AtomicWriteFailed({ path, stage, cause }));\n\n/**\n * Atomically write `bytes` to `path`. The helper ensures\n * `dirname(path)` exists (recursive mkdir, idempotent).\n *\n * `mode` is the final file mode bits (default 0o600 — secret-safe\n * default; cache callers may bump to 0o644 if they want world-read).\n */\nexport const atomicWriteFile = (\n\tpath: string,\n\tbytes: Uint8Array,\n\toptions: { readonly mode?: number; readonly parentMode?: number } = {},\n): Effect.Effect<void, AtomicWriteFailed, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst mode = options.mode ?? 0o600;\n\t\tconst parentMode = options.parentMode ?? 0o700;\n\t\tconst tmp = `${path}.tmp.${selfPid()}.${tempSuffix()}`;\n\t\t// 1. Ensure parent. recursive: true is idempotent under\n\t\t//    concurrent callers — `mkdir -p` semantics.\n\t\tyield* fs\n\t\t\t.makeDirectory(dirname(path), { recursive: true, mode: parentMode })\n\t\t\t.pipe(Effect.catch(failStage(path, 'mkdir-parent')));\n\t\t// 2-5. Write + rename, with unconditional tempfile cleanup on\n\t\t//      ANY failure path (open-temp / write / fsync / rename).\n\t\t//      `force: true` makes the unlink a no-op if the file\n\t\t//      doesn't exist (open-temp failed early, or rename moved\n\t\t//      it to its final home).\n\t\tyield* Effect.gen(function* () {\n\t\t\tyield* Effect.scoped(\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst file = yield* fs\n\t\t\t\t\t\t.open(tmp, { flag: 'wx', mode })\n\t\t\t\t\t\t.pipe(Effect.catch(failStage(path, 'open-temp')));\n\t\t\t\t\tyield* file.writeAll(bytes).pipe(Effect.catch(failStage(path, 'write')));\n\t\t\t\t\t// fsync — durability boundary. Without this the\n\t\t\t\t\t// rename can land but bytes can stay in the page\n\t\t\t\t\t// cache through a power loss.\n\t\t\t\t\tyield* file.sync.pipe(Effect.catch(failStage(path, 'fsync')));\n\t\t\t\t}),\n\t\t\t);\n\t\t\tyield* fs.rename(tmp, path).pipe(Effect.catch(failStage(path, 'rename')));\n\t\t}).pipe(Effect.onError(() => fs.remove(tmp, { force: true }).pipe(Effect.ignore)));\n\t}).pipe(Effect.withSpan('substrate.atomicWriteFile', { attributes: { path } }));\n\n/**\n * Atomically write a JSON value. Encodes via Schema (so the on-disk\n * shape is the schema's `Encoded` form, not the rich `Type`). Caller\n * supplies a schema whose `Type` matches `value`.\n */\nexport const atomicWriteJson = <A, I>(\n\tpath: string,\n\tschema: Schema.Codec<A, I>,\n\tvalue: A,\n\toptions?: { readonly mode?: number; readonly parentMode?: number },\n): Effect.Effect<void, AtomicWriteFailed, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst encoded = yield* Schema.encodeUnknownEffect(schema)(value).pipe(\n\t\t\tEffect.catch(failStage(path, 'encode')),\n\t\t);\n\t\tconst json = JSON.stringify(encoded, null, 2);\n\t\tconst bytes = new TextEncoder().encode(json);\n\t\tyield* atomicWriteFile(path, bytes, options);\n\t});\n\n// -----------------------------------------------------------------------------\n// Sync surface — for the cross-process modules that hold `stack.lock`\n// and must keep their critical section non-yielding. Same contract as\n// the Effect surface above.\n// -----------------------------------------------------------------------------\n\n/**\n * Internal: mkdir-parent → O_EXCL temp → write → fsync. Returns the\n * tempfile path on success; throws on any failure (and unlinks the\n * tempfile if it managed to land). The temp exists after return —\n * the caller is responsible for moving it to its final home (rename\n * for clobber semantics, link for exclusive-create semantics) AND\n * for unlinking the temp afterwards.\n *\n * Centralizes the durability boundary so both `atomicWriteFileSync`\n * (rename) and `atomicWriteFileExclusiveSync` (link+unlink) share\n * one tempfile/fsync implementation.\n */\nconst writeAndFsyncTempSync = (\n\tfinalPath: string,\n\tbytes: Uint8Array | string,\n\tmode: number,\n\tparentMode: number,\n): string => {\n\tconst tmp = `${finalPath}.tmp.${selfPid()}.${tempSuffix()}`;\n\tmkdirSync(dirname(finalPath), { recursive: true, mode: parentMode });\n\t// O_EXCL via `flag: 'wx'`. writeFileSync handles open + write +\n\t// close in one call but does NOT fsync; do it manually so we\n\t// preserve the durability boundary the Effect surface has.\n\twriteFileSync(tmp, bytes, { flag: 'wx', mode });\n\t// Tempfile exists from here — fsync failure must unlink before\n\t// rethrowing so a crashed-mid-flight writer doesn't leak a\n\t// half-written sibling.\n\ttry {\n\t\tlet fd: number | null = null;\n\t\ttry {\n\t\t\tfd = openSync(tmp, 'r');\n\t\t\tfsyncSync(fd);\n\t\t} finally {\n\t\t\tif (fd !== null) closeSync(fd);\n\t\t}\n\t} catch (cause) {\n\t\ttry {\n\t\t\tunlinkSync(tmp);\n\t\t} catch {\n\t\t\t// ignore — best-effort\n\t\t}\n\t\tthrow cause;\n\t}\n\treturn tmp;\n};\n\n/** Best-effort unlink. Swallows errors — used in cleanup paths where\n *  a failure to remove the temp should NOT mask the original error. */\nconst unlinkBestEffort = (path: string): void => {\n\ttry {\n\t\tunlinkSync(path);\n\t} catch {\n\t\t// ignore\n\t}\n};\n\n/**\n * Synchronous atomic write. Same disk-side contract as\n * `atomicWriteFile` (mkdir-parent → O_EXCL temp → write → fsync →\n * rename). Returns `void` on success; throws on any failure with\n * `cause` set to the underlying `NodeJS.ErrnoException`.\n *\n * Rename CLOBBERS a pre-existing file at the final path. Callers\n * that need exclusive-create semantics (\"fail if the final path\n * already exists, atomically\") want `atomicWriteFileExclusiveSync`\n * instead — that surface uses `linkSync` which is POSIX-atomic and\n * fails with `EEXIST` rather than overwriting.\n *\n * Used inside `Effect.try` by the cross-process modules; the caller\n * maps the thrown error to a typed plugin/runtime error\n * (`RosterIoError` / `SnapshotReservationIoError` / etc.).\n */\nexport const atomicWriteFileSync = (\n\tpath: string,\n\tbytes: Uint8Array | string,\n\toptions: { readonly mode?: number; readonly parentMode?: number } = {},\n): void => {\n\tconst mode = options.mode ?? 0o600;\n\tconst parentMode = options.parentMode ?? 0o700;\n\tconst tmp = writeAndFsyncTempSync(path, bytes, mode, parentMode);\n\tlet renamed = false;\n\ttry {\n\t\trenameSync(tmp, path);\n\t\trenamed = true;\n\t} finally {\n\t\tif (!renamed) unlinkBestEffort(tmp);\n\t}\n};\n\n/**\n * Synchronous atomic EXCLUSIVE-CREATE write. Same disk-side contract\n * as `atomicWriteFileSync` (mkdir-parent → O_EXCL temp → write →\n * fsync) but uses `linkSync(tmp, final)` instead of `renameSync` for\n * the final installation step. `link` is POSIX-atomic and FAILS with\n * `EEXIST` if the target already exists — closing the rename-clobber\n * race that `existsSync` + `renameSync` cannot.\n *\n * On success: the tempfile is unlinked (the hard link satisfies the\n * final path).\n *\n * On `EEXIST`: the tempfile is unlinked and the underlying\n * `NodeJS.ErrnoException` (with `code === 'EEXIST'`) is rethrown so\n * the caller can read the winning final-path and decide what to do.\n *\n * On any other failure: the tempfile is unlinked and the error is\n * rethrown unchanged.\n *\n * POSIX `link(2)` is available on Linux + macOS + WSL. Devstack is\n * POSIX-only at runtime.\n */\nexport const atomicWriteFileExclusiveSync = (\n\tpath: string,\n\tbytes: Uint8Array | string,\n\toptions: { readonly mode?: number; readonly parentMode?: number } = {},\n): void => {\n\tconst mode = options.mode ?? 0o600;\n\tconst parentMode = options.parentMode ?? 0o700;\n\tconst tmp = writeAndFsyncTempSync(path, bytes, mode, parentMode);\n\ttry {\n\t\t// Atomic exclusive-create. On EEXIST the tempfile remains and\n\t\t// the finally below unlinks it; the EEXIST error propagates.\n\t\tlinkSync(tmp, path);\n\t} finally {\n\t\t// Always unlink the tempfile: on success the hard link IS the\n\t\t// final file; on failure (EEXIST or otherwise) the tempfile\n\t\t// should not leak.\n\t\tunlinkBestEffort(tmp);\n\t}\n};\n\n/**\n * Synchronous atomic JSON write. Stringifies `value` and routes\n * through `atomicWriteFileSync`. No Schema encoding here — the\n * cross-process modules round-trip plain JSON (their schemas are\n * Schema.Struct of primitives; `JSON.stringify` is sufficient and\n * keeps the sync path dependency-free of Effect's Schema effects).\n */\nexport const atomicWriteJsonSync = (\n\tpath: string,\n\tvalue: unknown,\n\toptions?: { readonly mode?: number; readonly parentMode?: number },\n): void => {\n\tconst json = JSON.stringify(value);\n\tatomicWriteFileSync(path, json, options);\n};\n\n// Local dirname — we don't yield Path service here because\n// atomic-write may be called outside of a path-service-having\n// context (tests, recovery scripts). Posix-only; devstack is\n// posix-only in practice.\nconst dirname = (p: string): string => {\n\tconst i = p.lastIndexOf('/');\n\treturn i <= 0 ? '/' : p.slice(0, i);\n};\n"],"mappings":";;;;;;;;;AAwDA,MAAM,mBAA2B,YAAY,CAAC,QAAQ,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE;AAE3E,MAAM,aAEJ,MACA,WAEA,UACA,OAAO,KAAK,IAAI,kBAAkB;CAAE;CAAM;CAAO;CAAO,CAAC,CAAC;;;;;;;;AAS5D,MAAa,mBACZ,MACA,OACA,UAAoE,EAAE,KAEtE,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,MAAM,GAAG,KAAK,OAAO,SAAS,CAAC,GAAG,YAAY;AAGpD,QAAO,GACL,cAAc,QAAQ,KAAK,EAAE;EAAE,WAAW;EAAM,MAAM;EAAY,CAAC,CACnE,KAAK,OAAO,MAAM,UAAU,MAAM,eAAe,CAAC,CAAC;AAMrD,QAAO,OAAO,IAAI,aAAa;AAC9B,SAAO,OAAO,OACb,OAAO,IAAI,aAAa;GACvB,MAAM,OAAO,OAAO,GAClB,KAAK,KAAK;IAAE,MAAM;IAAM;IAAM,CAAC,CAC/B,KAAK,OAAO,MAAM,UAAU,MAAM,YAAY,CAAC,CAAC;AAClD,UAAO,KAAK,SAAS,MAAM,CAAC,KAAK,OAAO,MAAM,UAAU,MAAM,QAAQ,CAAC,CAAC;AAIxE,UAAO,KAAK,KAAK,KAAK,OAAO,MAAM,UAAU,MAAM,QAAQ,CAAC,CAAC;IAC5D,CACF;AACD,SAAO,GAAG,OAAO,KAAK,KAAK,CAAC,KAAK,OAAO,MAAM,UAAU,MAAM,SAAS,CAAC,CAAC;GACxE,CAAC,KAAK,OAAO,cAAc,GAAG,OAAO,KAAK,EAAE,OAAO,MAAM,CAAC,CAAC,KAAK,OAAO,OAAO,CAAC,CAAC;EACjF,CAAC,KAAK,OAAO,SAAS,6BAA6B,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC;;;;;;AAOhF,MAAa,mBACZ,MACA,QACA,OACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAU,OAAO,OAAO,oBAAoB,OAAO,CAAC,MAAM,CAAC,KAChE,OAAO,MAAM,UAAU,MAAM,SAAS,CAAC,CACvC;CACD,MAAM,OAAO,KAAK,UAAU,SAAS,MAAM,EAAE;AAE7C,QAAO,gBAAgB,MADT,IAAI,aAAa,CAAC,OAAO,KACL,EAAE,QAAQ;EAC3C;;;;;;;;;;;;;AAoBH,MAAM,yBACL,WACA,OACA,MACA,eACY;CACZ,MAAM,MAAM,GAAG,UAAU,OAAO,SAAS,CAAC,GAAG,YAAY;AACzD,WAAU,QAAQ,UAAU,EAAE;EAAE,WAAW;EAAM,MAAM;EAAY,CAAC;AAIpE,eAAc,KAAK,OAAO;EAAE,MAAM;EAAM;EAAM,CAAC;AAI/C,KAAI;EACH,IAAI,KAAoB;AACxB,MAAI;AACH,QAAK,SAAS,KAAK,IAAI;AACvB,aAAU,GAAG;YACJ;AACT,OAAI,OAAO,KAAM,WAAU,GAAG;;UAEvB,OAAO;AACf,MAAI;AACH,cAAW,IAAI;UACR;AAGR,QAAM;;AAEP,QAAO;;;;AAKR,MAAM,oBAAoB,SAAuB;AAChD,KAAI;AACH,aAAW,KAAK;SACT;;;;;;;;;;;;;;;;;;AAqBT,MAAa,uBACZ,MACA,OACA,UAAoE,EAAE,KAC5D;CAGV,MAAM,MAAM,sBAAsB,MAAM,OAF3B,QAAQ,QAAQ,KACV,QAAQ,cAAc,IACuB;CAChE,IAAI,UAAU;AACd,KAAI;AACH,aAAW,KAAK,KAAK;AACrB,YAAU;WACD;AACT,MAAI,CAAC,QAAS,kBAAiB,IAAI;;;;;;;;;;;;;;;;;;;;;;;;AAyBrC,MAAa,gCACZ,MACA,OACA,UAAoE,EAAE,KAC5D;CAGV,MAAM,MAAM,sBAAsB,MAAM,OAF3B,QAAQ,QAAQ,KACV,QAAQ,cAAc,IACuB;AAChE,KAAI;AAGH,WAAS,KAAK,KAAK;WACV;AAIT,mBAAiB,IAAI;;;;;;;;;;AAWvB,MAAa,uBACZ,MACA,OACA,YACU;AAEV,qBAAoB,MADP,KAAK,UAAU,MACE,EAAE,QAAQ;;AAOzC,MAAM,WAAW,MAAsB;CACtC,MAAM,IAAI,EAAE,YAAY,IAAI;AAC5B,QAAO,KAAK,IAAI,MAAM,EAAE,MAAM,GAAG,EAAE"}

package/dist/substrate/runtime/cache/index.mjs

@@ -0,0 +1,3 @@
+import "./schema.mjs";
+import "./service.mjs";
+export {};

package/dist/substrate/runtime/cache/schema.mjs

@@ -1,10 +1,10 @@
+import { versionedDocSchema } from "../../versioned-doc-schema.mjs";
 import { Schema } from "effect";
 //#region src/substrate/runtime/cache/schema.ts
 /** Versioned envelope. Schema-decode failure on read is treated as
 *  a cache MISS (best-effort cache contract — corruption recovers
 *  by re-producing the artifact). */
-const CacheEntryDoc = Schema.Struct({
-	version: Schema.Literal(1),
+const CacheEntryDoc = versionedDocSchema(1, {
 	/** Bytes, base64-encoded. Chosen over hex because typical
 	*  artifacts are larger (image manifests, package digests) and
 	*  base64 is 33% overhead vs hex's 100%. */

package/dist/substrate/runtime/cache/schema.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"schema.mjs","names":[],"sources":["../../../../src/substrate/runtime/cache/schema.ts"],"sourcesContent":["// On-disk shape for one cache entry.\n//\n// One file per `(namespace, chain, contentHash)` triple, at\n// `<runtime-root>/stacks/<stack>/cache/<namespace>/<chain>/<contentHash>.json`.\n//\n// The entry envelope wraps the bytes (base64-encoded — JSON has no\n// binary literal) and the metadata renderer / verify needs. Cache\n// callers don't see the envelope; they only see `CacheEntry` from\n// `primitives/cache.ts` (bytes + writtenAt).\n\nimport { Schema } from 'effect';\n\n/** Versioned envelope. Schema-decode failure on read is treated as\n *  a cache MISS (best-effort cache contract — corruption recovers\n *  by re-producing the artifact). */\nexport const CacheEntryDoc = Schema.Struct({\n\tversion: Schema.Literal(1),\n\t/** Bytes, base64-encoded. Chosen over hex because typical\n\t *  artifacts are larger (image manifests, package digests) and\n\t *  base64 is 33% overhead vs hex's 100%. */\n\tbytes: Schema.String,\n\t/** Unix millis of the write. Renderers may show \"produced 5s\n\t *  ago\"; substrate uses it only for diagnostics. */\n\twrittenAt: Schema.Number,\n\t/** Optional namespace-private hint (e.g. \"image-tag the cached\n\t *  blob refers to\"). Substrate stores opaquely. */\n\thint: Schema.optional(Schema.String),\n});\nexport type CacheEntryDoc = typeof CacheEntryDoc.Type;\n"],"mappings":";;;;;AAeA,MAAa,gBAAgB,OAAO,OAAO;CAC1C,SAAS,OAAO,QAAQ,EAAE;;;;CAI1B,OAAO,OAAO;;;CAGd,WAAW,OAAO;;;CAGlB,MAAM,OAAO,SAAS,OAAO,OAAO;CACpC,CAAC"}
+{"version":3,"file":"schema.mjs","names":[],"sources":["../../../../src/substrate/runtime/cache/schema.ts"],"sourcesContent":["// On-disk shape for one cache entry.\n//\n// One file per `(namespace, chain, contentHash)` triple, at\n// `<runtime-root>/stacks/<stack>/cache/<namespace>/<chain>/<contentHash>.json`.\n//\n// The entry envelope wraps the bytes (base64-encoded — JSON has no\n// binary literal) and the metadata renderer / verify needs. Cache\n// callers don't see the envelope; they only see `CacheEntry` from\n// `primitives/cache.ts` (bytes + writtenAt).\n\nimport { Schema } from 'effect';\n\nimport { versionedDocSchema } from '../../versioned-doc-schema.ts';\n\n/** Versioned envelope. Schema-decode failure on read is treated as\n *  a cache MISS (best-effort cache contract — corruption recovers\n *  by re-producing the artifact). */\nexport const CacheEntryDoc = versionedDocSchema(1, {\n\t/** Bytes, base64-encoded. Chosen over hex because typical\n\t *  artifacts are larger (image manifests, package digests) and\n\t *  base64 is 33% overhead vs hex's 100%. */\n\tbytes: Schema.String,\n\t/** Unix millis of the write. Renderers may show \"produced 5s\n\t *  ago\"; substrate uses it only for diagnostics. */\n\twrittenAt: Schema.Number,\n\t/** Optional namespace-private hint (e.g. \"image-tag the cached\n\t *  blob refers to\"). Substrate stores opaquely. */\n\thint: Schema.optional(Schema.String),\n});\nexport type CacheEntryDoc = typeof CacheEntryDoc.Type;\n"],"mappings":";;;;;;AAiBA,MAAa,gBAAgB,mBAAmB,GAAG;;;;CAIlD,OAAO,OAAO;;;CAGd,WAAW,OAAO;;;CAGlB,MAAM,OAAO,SAAS,OAAO,OAAO;CACpC,CAAC"}

package/dist/substrate/runtime/cache/service.mjs

@@ -1,13 +1,14 @@
 import { StackPathsService } from "../paths.mjs";
+import { SpanAttr } from "../observability/spans.mjs";
 import { CacheError } from "../errors.mjs";
+import { atomicWriteJson } from "../atomic-write.mjs";
 import { decodeJsonText } from "../runtime-decode.mjs";
 import { CacheEntryDoc } from "./schema.mjs";
-import { atomicWriteJson } from "../atomic-write.mjs";
 import { Context, Effect, FileSystem, Layer } from "effect";
 //#region src/substrate/runtime/cache/service.ts
 const base64Encode = (bytes) => Buffer.from(bytes).toString("base64");
 const base64Decode = (s) => new Uint8Array(Buffer.from(s, "base64"));
-var CacheService = class extends Context.Service()("@devstack-rewrite/substrate/Cache") {};
+var CacheService = class extends Context.Service()("@devstack/substrate/Cache") {};
 /**
 * Cache Layer. Stateless beyond the path resolver and the platform
 * FileSystem — every read goes to disk (no in-memory hot cache; the
@@ -26,16 +27,17 @@ const layerCache = Layer.effect(CacheService, Effect.gen(function* () {
 			detail: `failed to stat cache entry: ${file}`,
 			cause
 		})))))) return null;
-		const text = yield* fs.readFileString(file).pipe(Effect.catch((cause) => Effect.fail(new CacheError({
+		const doc = yield* decodeJsonText(CacheEntryDoc, yield* fs.readFileString(file).pipe(Effect.catch((cause) => Effect.fail(new CacheError({
 			reason: "io-failed",
 			detail: `failed to read cache entry: ${file}`,
 			cause
-		}))));
-		const annotateCorruption = Effect.annotateCurrentSpan({ "cache.corruption": true });
-		const doc = yield* decodeJsonText(CacheEntryDoc, text, {
+		})))), {
 			source: file,
 			mkError: (issue) => issue
-		}).pipe(Effect.catch(() => annotateCorruption.pipe(Effect.as(null))));
+		}).pipe(Effect.tapCause((cause) => Effect.logDebug("cache entry decode failed; treating as miss", {
+			file,
+			cause
+		})), Effect.catch(() => Effect.annotateCurrentSpan({ [SpanAttr.cacheCorruption]: true }).pipe(Effect.as(null))));
 		if (doc === null) return null;
 		return {
 			bytes: base64Decode(doc.bytes),

package/dist/substrate/runtime/cache/service.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"service.mjs","names":[],"sources":["../../../../src/substrate/runtime/cache/service.ts"],"sourcesContent":["// Cache implementation.\n//\n// Universal artifact cache, content-addressed by\n// `(namespace, chainId, contentHash)`. Per-plugin namespace; the\n// substrate folds chainId in.\n//\n// Semantics:\n//\n//   - `lookup` is the precise \"is the entry present?\" query. Hit\n//     returns `CacheEntry`; miss returns `null`. Schema-decode\n//     failure (corruption) is treated as a MISS, not an error —\n//     re-producing the artifact is always safe; surfacing decode\n//     failures would force every caller to handle a recovery path\n//     they don't need. The corruption is logged via the span.\n//   - `write` is best-effort. The architecture is explicit: an\n//     ArtifactPublisher commits the on-chain effect, THEN\n//     writes the cache; a cache-write IO failure must NOT roll back\n//     the on-chain effect. We surface write failures via the\n//     `CacheError` channel so callers can opt into reporting them,\n//     but the typical caller pipes `Effect.ignore` over the write.\n//   - `delete` is a best-effort sweep.\n//\n// Tombstones: the cache does NOT use tombstones. Missing-vs-deleted\n// is meaningless for a content-addressed best-effort store —\n// re-producing the artifact has the same effect either way.\n\nimport { Context, Effect, FileSystem, Layer } from 'effect';\n\nimport type { Cache, CacheEntry, CacheKey } from '../../../primitives/cache.ts';\nimport { atomicWriteJson } from '../atomic-write.ts';\nimport { CacheError } from '../errors.ts';\nimport { StackPathsService } from '../paths.ts';\nimport { decodeJsonText } from '../runtime-decode.ts';\nimport { CacheEntryDoc } from './schema.ts';\n\nconst base64Encode = (bytes: Uint8Array): string => Buffer.from(bytes).toString('base64');\nconst base64Decode = (s: string): Uint8Array => new Uint8Array(Buffer.from(s, 'base64'));\n\nexport class CacheService extends Context.Service<CacheService, Cache>()(\n\t'@devstack-rewrite/substrate/Cache',\n) {}\n\n/**\n * Cache Layer. Stateless beyond the path resolver and the platform\n * FileSystem — every read goes to disk (no in-memory hot cache; the\n * OS page cache is enough). If a future perf pass shows the\n * substrate is hot-path-reading the same entries repeatedly, fold\n * an LRU in here; today's call-sites read once at acquire and never\n * again.\n */\nexport const layerCache: Layer.Layer<\n\tCacheService,\n\tnever,\n\tFileSystem.FileSystem | StackPathsService\n> = Layer.effect(\n\tCacheService,\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst paths = yield* StackPathsService;\n\n\t\tconst lookup = (key: CacheKey): Effect.Effect<CacheEntry | null, CacheError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst { file } = paths.cacheEntry(key.namespace, key.chain, key.contentHash);\n\t\t\t\tconst exists = yield* fs.exists(file).pipe(\n\t\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew CacheError({\n\t\t\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\t\t\tdetail: `failed to stat cache entry: ${file}`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tif (!exists) return null;\n\t\t\t\tconst text = yield* fs.readFileString(file).pipe(\n\t\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew CacheError({\n\t\t\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\t\t\tdetail: `failed to read cache entry: ${file}`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\t// Corruption = miss. The cache contract is\n\t\t\t\t// best-effort; surfacing decode failures would force\n\t\t\t\t// every caller to handle a recovery path that's\n\t\t\t\t// already implicit (re-produce). We do annotate the\n\t\t\t\t// span so the substrate's observability still\n\t\t\t\t// surfaces the rare corruption.\n\t\t\t\tconst annotateCorruption = Effect.annotateCurrentSpan({\n\t\t\t\t\t'cache.corruption': true,\n\t\t\t\t});\n\t\t\t\tconst doc = yield* decodeJsonText(CacheEntryDoc, text, {\n\t\t\t\t\tsource: file,\n\t\t\t\t\tmkError: (issue) => issue,\n\t\t\t\t}).pipe(\n\t\t\t\t\tEffect.catch(() => annotateCorruption.pipe(Effect.as(null as CacheEntryDoc | null))),\n\t\t\t\t);\n\t\t\t\tif (doc === null) return null;\n\t\t\t\treturn {\n\t\t\t\t\tbytes: base64Decode(doc.bytes),\n\t\t\t\t\twrittenAt: doc.writtenAt,\n\t\t\t\t};\n\t\t\t}).pipe(\n\t\t\t\tEffect.withSpan('substrate.cache.lookup', {\n\t\t\t\t\tattributes: {\n\t\t\t\t\t\tnamespace: key.namespace,\n\t\t\t\t\t\tchain: key.chain,\n\t\t\t\t\t\tcontentHash: key.contentHash,\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t\t);\n\n\t\tconst write = (key: CacheKey, bytes: Uint8Array): Effect.Effect<void, CacheError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst { file } = paths.cacheEntry(key.namespace, key.chain, key.contentHash);\n\t\t\t\tconst doc: CacheEntryDoc = {\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tbytes: base64Encode(bytes),\n\t\t\t\t\twrittenAt: Date.now(),\n\t\t\t\t};\n\t\t\t\tyield* atomicWriteJson(file, CacheEntryDoc, doc, {\n\t\t\t\t\tmode: 0o644,\n\t\t\t\t\tparentMode: 0o755,\n\t\t\t\t}).pipe(\n\t\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew CacheError({\n\t\t\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\t\t\tdetail: `cache write failed: ${file}`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t\tEffect.provideService(FileSystem.FileSystem, fs),\n\t\t\t\t);\n\t\t\t}).pipe(\n\t\t\t\tEffect.withSpan('substrate.cache.write', {\n\t\t\t\t\tattributes: {\n\t\t\t\t\t\tnamespace: key.namespace,\n\t\t\t\t\t\tchain: key.chain,\n\t\t\t\t\t\tcontentHash: key.contentHash,\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t\t);\n\n\t\tconst remove = (key: CacheKey): Effect.Effect<void, CacheError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst { file } = paths.cacheEntry(key.namespace, key.chain, key.contentHash);\n\t\t\t\tyield* fs.remove(file, { force: true }).pipe(\n\t\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew CacheError({\n\t\t\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\t\t\tdetail: `cache delete failed: ${file}`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}).pipe(\n\t\t\t\tEffect.withSpan('substrate.cache.delete', {\n\t\t\t\t\tattributes: {\n\t\t\t\t\t\tnamespace: key.namespace,\n\t\t\t\t\t\tchain: key.chain,\n\t\t\t\t\t\tcontentHash: key.contentHash,\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t\t);\n\n\t\treturn CacheService.of({\n\t\t\tlookup,\n\t\t\twrite,\n\t\t\tdelete: remove,\n\t\t});\n\t}),\n);\n"],"mappings":";;;;;;;AAmCA,MAAM,gBAAgB,UAA8B,OAAO,KAAK,MAAM,CAAC,SAAS,SAAS;AACzF,MAAM,gBAAgB,MAA0B,IAAI,WAAW,OAAO,KAAK,GAAG,SAAS,CAAC;AAExF,IAAa,eAAb,cAAkC,QAAQ,SAA8B,CACvE,oCACA,CAAC;;;;;;;;;AAUF,MAAa,aAIT,MAAM,OACT,cACA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,QAAQ,OAAO;CAErB,MAAM,UAAU,QACf,OAAO,IAAI,aAAa;EACvB,MAAM,EAAE,SAAS,MAAM,WAAW,IAAI,WAAW,IAAI,OAAO,IAAI,YAAY;AAY5E,MAAI,EAAC,OAXiB,GAAG,OAAO,KAAK,CAAC,KACrC,OAAO,OAAO,UACb,OAAO,KACN,IAAI,WAAW;GACd,QAAQ;GACR,QAAQ,+BAA+B;GACvC;GACA,CAAC,CACF,CACD,CACD,EACY,QAAO;EACpB,MAAM,OAAO,OAAO,GAAG,eAAe,KAAK,CAAC,KAC3C,OAAO,OAAO,UACb,OAAO,KACN,IAAI,WAAW;GACd,QAAQ;GACR,QAAQ,+BAA+B;GACvC;GACA,CAAC,CACF,CACD,CACD;EAOD,MAAM,qBAAqB,OAAO,oBAAoB,EACrD,oBAAoB,MACpB,CAAC;EACF,MAAM,MAAM,OAAO,eAAe,eAAe,MAAM;GACtD,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC,CAAC,KACF,OAAO,YAAY,mBAAmB,KAAK,OAAO,GAAG,KAA6B,CAAC,CAAC,CACpF;AACD,MAAI,QAAQ,KAAM,QAAO;AACzB,SAAO;GACN,OAAO,aAAa,IAAI,MAAM;GAC9B,WAAW,IAAI;GACf;GACA,CAAC,KACF,OAAO,SAAS,0BAA0B,EACzC,YAAY;EACX,WAAW,IAAI;EACf,OAAO,IAAI;EACX,aAAa,IAAI;EACjB,EACD,CAAC,CACF;CAEF,MAAM,SAAS,KAAe,UAC7B,OAAO,IAAI,aAAa;EACvB,MAAM,EAAE,SAAS,MAAM,WAAW,IAAI,WAAW,IAAI,OAAO,IAAI,YAAY;AAM5E,SAAO,gBAAgB,MAAM,eAAe;GAJ3C,SAAS;GACT,OAAO,aAAa,MAAM;GAC1B,WAAW,KAAK,KAAK;GAEyB,EAAE;GAChD,MAAM;GACN,YAAY;GACZ,CAAC,CAAC,KACF,OAAO,OAAO,UACb,OAAO,KACN,IAAI,WAAW;GACd,QAAQ;GACR,QAAQ,uBAAuB;GAC/B;GACA,CAAC,CACF,CACD,EACD,OAAO,eAAe,WAAW,YAAY,GAAG,CAChD;GACA,CAAC,KACF,OAAO,SAAS,yBAAyB,EACxC,YAAY;EACX,WAAW,IAAI;EACf,OAAO,IAAI;EACX,aAAa,IAAI;EACjB,EACD,CAAC,CACF;CAEF,MAAM,UAAU,QACf,OAAO,IAAI,aAAa;EACvB,MAAM,EAAE,SAAS,MAAM,WAAW,IAAI,WAAW,IAAI,OAAO,IAAI,YAAY;AAC5E,SAAO,GAAG,OAAO,MAAM,EAAE,OAAO,MAAM,CAAC,CAAC,KACvC,OAAO,OAAO,UACb,OAAO,KACN,IAAI,WAAW;GACd,QAAQ;GACR,QAAQ,wBAAwB;GAChC;GACA,CAAC,CACF,CACD,CACD;GACA,CAAC,KACF,OAAO,SAAS,0BAA0B,EACzC,YAAY;EACX,WAAW,IAAI;EACf,OAAO,IAAI;EACX,aAAa,IAAI;EACjB,EACD,CAAC,CACF;AAEF,QAAO,aAAa,GAAG;EACtB;EACA;EACA,QAAQ;EACR,CAAC;EACD,CACF"}
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../../src/substrate/runtime/cache/service.ts"],"sourcesContent":["// Cache implementation.\n//\n// Universal artifact cache, content-addressed by\n// `(namespace, chainId, contentHash)`. Per-plugin namespace; the\n// substrate folds chainId in.\n//\n// Semantics:\n//\n//   - `lookup` is the precise \"is the entry present?\" query. Hit\n//     returns `CacheEntry`; miss returns `null`. Schema-decode\n//     failure (corruption) is treated as a MISS, not an error —\n//     re-producing the artifact is always safe; surfacing decode\n//     failures would force every caller to handle a recovery path\n//     they don't need. The corruption is logged via the span.\n//   - `write` is best-effort. The architecture is explicit: an\n//     ArtifactPublisher commits the on-chain effect, THEN\n//     writes the cache; a cache-write IO failure must NOT roll back\n//     the on-chain effect. We surface write failures via the\n//     `CacheError` channel so callers can opt into reporting them,\n//     but the typical caller pipes `Effect.ignore` over the write.\n//   - `delete` is a best-effort sweep.\n//\n// Tombstones: the cache does NOT use tombstones. Missing-vs-deleted\n// is meaningless for a content-addressed best-effort store —\n// re-producing the artifact has the same effect either way.\n\nimport { Context, Effect, FileSystem, Layer } from 'effect';\n\nimport type { Cache, CacheEntry, CacheKey } from '../../../primitives/cache.ts';\nimport { atomicWriteJson } from '../atomic-write.ts';\nimport { CacheError } from '../errors.ts';\nimport { SpanAttr } from '../observability/spans.ts';\nimport { StackPathsService } from '../paths.ts';\nimport { decodeJsonText } from '../runtime-decode.ts';\nimport { CacheEntryDoc } from './schema.ts';\n\nconst base64Encode = (bytes: Uint8Array): string => Buffer.from(bytes).toString('base64');\nconst base64Decode = (s: string): Uint8Array => new Uint8Array(Buffer.from(s, 'base64'));\n\nexport class CacheService extends Context.Service<CacheService, Cache>()(\n\t'@devstack/substrate/Cache',\n) {}\n\n/**\n * Cache Layer. Stateless beyond the path resolver and the platform\n * FileSystem — every read goes to disk (no in-memory hot cache; the\n * OS page cache is enough). If a future perf pass shows the\n * substrate is hot-path-reading the same entries repeatedly, fold\n * an LRU in here; today's call-sites read once at acquire and never\n * again.\n */\nexport const layerCache: Layer.Layer<\n\tCacheService,\n\tnever,\n\tFileSystem.FileSystem | StackPathsService\n> = Layer.effect(\n\tCacheService,\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst paths = yield* StackPathsService;\n\n\t\tconst lookup = (key: CacheKey): Effect.Effect<CacheEntry | null, CacheError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst { file } = paths.cacheEntry(key.namespace, key.chain, key.contentHash);\n\t\t\t\tconst exists = yield* fs.exists(file).pipe(\n\t\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew CacheError({\n\t\t\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\t\t\tdetail: `failed to stat cache entry: ${file}`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tif (!exists) return null;\n\t\t\t\tconst text = yield* fs.readFileString(file).pipe(\n\t\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew CacheError({\n\t\t\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\t\t\tdetail: `failed to read cache entry: ${file}`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\t// Corruption = miss. The cache contract is\n\t\t\t\t// best-effort; surfacing decode failures would force\n\t\t\t\t// every caller to handle a recovery path that's\n\t\t\t\t// already implicit (re-produce). We annotate the span\n\t\t\t\t// AND emit a `logDebug` so the rare corruption is\n\t\t\t\t// visible in the log stream, not only via span backend.\n\t\t\t\tconst doc = yield* decodeJsonText(CacheEntryDoc, text, {\n\t\t\t\t\tsource: file,\n\t\t\t\t\tmkError: (issue) => issue,\n\t\t\t\t}).pipe(\n\t\t\t\t\tEffect.tapCause((cause) =>\n\t\t\t\t\t\tEffect.logDebug('cache entry decode failed; treating as miss', {\n\t\t\t\t\t\t\tfile,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t\tEffect.catch(() =>\n\t\t\t\t\t\tEffect.annotateCurrentSpan({ [SpanAttr.cacheCorruption]: true }).pipe(\n\t\t\t\t\t\t\tEffect.as(null as CacheEntryDoc | null),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tif (doc === null) return null;\n\t\t\t\treturn {\n\t\t\t\t\tbytes: base64Decode(doc.bytes),\n\t\t\t\t\twrittenAt: doc.writtenAt,\n\t\t\t\t};\n\t\t\t}).pipe(\n\t\t\t\tEffect.withSpan('substrate.cache.lookup', {\n\t\t\t\t\tattributes: {\n\t\t\t\t\t\tnamespace: key.namespace,\n\t\t\t\t\t\tchain: key.chain,\n\t\t\t\t\t\tcontentHash: key.contentHash,\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t\t);\n\n\t\tconst write = (key: CacheKey, bytes: Uint8Array): Effect.Effect<void, CacheError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst { file } = paths.cacheEntry(key.namespace, key.chain, key.contentHash);\n\t\t\t\tconst doc: CacheEntryDoc = {\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tbytes: base64Encode(bytes),\n\t\t\t\t\twrittenAt: Date.now(),\n\t\t\t\t};\n\t\t\t\tyield* atomicWriteJson(file, CacheEntryDoc, doc, {\n\t\t\t\t\tmode: 0o644,\n\t\t\t\t\tparentMode: 0o755,\n\t\t\t\t}).pipe(\n\t\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew CacheError({\n\t\t\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\t\t\tdetail: `cache write failed: ${file}`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t\tEffect.provideService(FileSystem.FileSystem, fs),\n\t\t\t\t);\n\t\t\t}).pipe(\n\t\t\t\tEffect.withSpan('substrate.cache.write', {\n\t\t\t\t\tattributes: {\n\t\t\t\t\t\tnamespace: key.namespace,\n\t\t\t\t\t\tchain: key.chain,\n\t\t\t\t\t\tcontentHash: key.contentHash,\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t\t);\n\n\t\tconst remove = (key: CacheKey): Effect.Effect<void, CacheError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst { file } = paths.cacheEntry(key.namespace, key.chain, key.contentHash);\n\t\t\t\tyield* fs.remove(file, { force: true }).pipe(\n\t\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew CacheError({\n\t\t\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\t\t\tdetail: `cache delete failed: ${file}`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}).pipe(\n\t\t\t\tEffect.withSpan('substrate.cache.delete', {\n\t\t\t\t\tattributes: {\n\t\t\t\t\t\tnamespace: key.namespace,\n\t\t\t\t\t\tchain: key.chain,\n\t\t\t\t\t\tcontentHash: key.contentHash,\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t\t);\n\n\t\treturn CacheService.of({\n\t\t\tlookup,\n\t\t\twrite,\n\t\t\tdelete: remove,\n\t\t});\n\t}),\n);\n"],"mappings":";;;;;;;;AAoCA,MAAM,gBAAgB,UAA8B,OAAO,KAAK,MAAM,CAAC,SAAS,SAAS;AACzF,MAAM,gBAAgB,MAA0B,IAAI,WAAW,OAAO,KAAK,GAAG,SAAS,CAAC;AAExF,IAAa,eAAb,cAAkC,QAAQ,SAA8B,CACvE,4BACA,CAAC;;;;;;;;;AAUF,MAAa,aAIT,MAAM,OACT,cACA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,QAAQ,OAAO;CAErB,MAAM,UAAU,QACf,OAAO,IAAI,aAAa;EACvB,MAAM,EAAE,SAAS,MAAM,WAAW,IAAI,WAAW,IAAI,OAAO,IAAI,YAAY;AAY5E,MAAI,EAAC,OAXiB,GAAG,OAAO,KAAK,CAAC,KACrC,OAAO,OAAO,UACb,OAAO,KACN,IAAI,WAAW;GACd,QAAQ;GACR,QAAQ,+BAA+B;GACvC;GACA,CAAC,CACF,CACD,CACD,EACY,QAAO;EAkBpB,MAAM,MAAM,OAAO,eAAe,eAAe,OAjB7B,GAAG,eAAe,KAAK,CAAC,KAC3C,OAAO,OAAO,UACb,OAAO,KACN,IAAI,WAAW;GACd,QAAQ;GACR,QAAQ,+BAA+B;GACvC;GACA,CAAC,CACF,CACD,CACD,EAOsD;GACtD,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC,CAAC,KACF,OAAO,UAAU,UAChB,OAAO,SAAS,+CAA+C;GAC9D;GACA;GACA,CAAC,CACF,EACD,OAAO,YACN,OAAO,oBAAoB,GAAG,SAAS,kBAAkB,MAAM,CAAC,CAAC,KAChE,OAAO,GAAG,KAA6B,CACvC,CACD,CACD;AACD,MAAI,QAAQ,KAAM,QAAO;AACzB,SAAO;GACN,OAAO,aAAa,IAAI,MAAM;GAC9B,WAAW,IAAI;GACf;GACA,CAAC,KACF,OAAO,SAAS,0BAA0B,EACzC,YAAY;EACX,WAAW,IAAI;EACf,OAAO,IAAI;EACX,aAAa,IAAI;EACjB,EACD,CAAC,CACF;CAEF,MAAM,SAAS,KAAe,UAC7B,OAAO,IAAI,aAAa;EACvB,MAAM,EAAE,SAAS,MAAM,WAAW,IAAI,WAAW,IAAI,OAAO,IAAI,YAAY;AAM5E,SAAO,gBAAgB,MAAM,eAAe;GAJ3C,SAAS;GACT,OAAO,aAAa,MAAM;GAC1B,WAAW,KAAK,KAAK;GAEyB,EAAE;GAChD,MAAM;GACN,YAAY;GACZ,CAAC,CAAC,KACF,OAAO,OAAO,UACb,OAAO,KACN,IAAI,WAAW;GACd,QAAQ;GACR,QAAQ,uBAAuB;GAC/B;GACA,CAAC,CACF,CACD,EACD,OAAO,eAAe,WAAW,YAAY,GAAG,CAChD;GACA,CAAC,KACF,OAAO,SAAS,yBAAyB,EACxC,YAAY;EACX,WAAW,IAAI;EACf,OAAO,IAAI;EACX,aAAa,IAAI;EACjB,EACD,CAAC,CACF;CAEF,MAAM,UAAU,QACf,OAAO,IAAI,aAAa;EACvB,MAAM,EAAE,SAAS,MAAM,WAAW,IAAI,WAAW,IAAI,OAAO,IAAI,YAAY;AAC5E,SAAO,GAAG,OAAO,MAAM,EAAE,OAAO,MAAM,CAAC,CAAC,KACvC,OAAO,OAAO,UACb,OAAO,KACN,IAAI,WAAW;GACd,QAAQ;GACR,QAAQ,wBAAwB;GAChC;GACA,CAAC,CACF,CACD,CACD;GACA,CAAC,KACF,OAAO,SAAS,0BAA0B,EACzC,YAAY;EACX,WAAW,IAAI;EACf,OAAO,IAAI;EACX,aAAa,IAAI;EACjB,EACD,CAAC,CACF;AAEF,QAAO,aAAa,GAAG;EACtB;EACA;EACA,QAAQ;EACR,CAAC;EACD,CACF"}

package/dist/substrate/runtime/capability-sinks/index.d.mts

@@ -1 +1 @@
-import { CapabilitySink, ContributionKind, HarvestContext } from "./service.mjs";
+import { AnyContribution, CapabilitySink, CapabilitySinksService, CapabilitySinksShape, ContributionKind, ContributionSinkFailed, HarvestContext, UnknownContributionKind } from "./service.mjs";

package/dist/substrate/runtime/capability-sinks/index.mjs

@@ -0,0 +1,3 @@
+import "./service.mjs";
+import "./layer.mjs";
+export {};

package/dist/substrate/runtime/capability-sinks/layer.mjs

@@ -1,5 +1,5 @@
-import { FormatterRegistryService, layerFormatterRegistry } from "../observability/formatter-registry.mjs";
 import { CapabilitySinksService, layerCapabilitySinks } from "./service.mjs";
+import { FormatterRegistryService, layerFormatterRegistry } from "../observability/formatter-registry.mjs";
 import { Effect, Layer } from "effect";
 //#region src/substrate/runtime/capability-sinks/layer.ts
 const errorContributionSink = (formatters) => ({

package/dist/substrate/runtime/capability-sinks/service.d.mts

@@ -1,13 +1,29 @@
 import { PluginKey } from "../../brand.mjs";
 import { EngineEvent } from "../../events.mjs";
 import { StrategyContributorDecl } from "../../../contracts/strategy-contributor.mjs";
+import { CapabilityDecl } from "../../../contracts/capability-decl.mjs";
 import { Identity } from "../../identity.mjs";
+import { PluginErrorContribution } from "../../plugin.mjs";
 import { Context, Effect, Layer, Scope } from "effect";
+import * as _$effect_Cause0 from "effect/Cause";
+import * as _$effect_Types0 from "effect/Types";
+
 //#region src/substrate/runtime/capability-sinks/service.d.ts
+/** A single harvested item — either a capability decl OR an error
+ *  contribution. Discriminated by the literal `kind`. The supervisor
+ *  produces one of these for each item it pulls off a plugin during
+ *  the harvest loop. */
+type AnyContribution = {
+  readonly source: 'capability';
+  readonly decl: CapabilityDecl;
+} | {
+  readonly source: 'error';
+  readonly contribution: PluginErrorContribution;
+};
 /** The discriminator the sinks register against. Substrate-owned
  *  literal vocabulary — plugins authoring a custom contract add a new
  *  literal and a sink. */
-type ContributionKind = 'snapshotable' | 'routable' | 'codegenable' | 'projection' | 'strategy-contributor' | 'liveness-classifier' | 'error-contribution' | (string & {
+type ContributionKind = 'snapshotable' | 'routable' | 'codegenable' | 'projection' | 'strategy-contributor' | 'error-contribution' | (string & {
   readonly __extensionKind?: never;
 });
 /** Context the harvest loop supplies to each sink invocation. Carries
@@ -31,6 +47,49 @@ interface CapabilitySink<K extends ContributionKind, TDecl> {
   readonly kind: K;
   readonly accept: (decl: TDecl, ctx: HarvestContext) => Effect.Effect<void, unknown, Scope.Scope>;
 }
+declare const UnknownContributionKind_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "UnknownContributionKind";
+} & Readonly<A>;
+/** Surfaced when `dispatch` receives a kind no sink is registered for.
+ *  Substrate stays open by default — unknown kinds are no-ops at the
+ *  supervisor's call site (see `dispatchOrIgnore`); but tests + custom
+ *  callers can drive the strict surface via `dispatch`. */
+declare class UnknownContributionKind extends UnknownContributionKind_base<{
+  readonly kind: string;
+  readonly known: ReadonlyArray<string>;
+}> {}
+declare const ContributionSinkFailed_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "ContributionSinkFailed";
+} & Readonly<A>;
+/** Surfaced when a registered sink rejects while handling a known
+ *  contribution kind. The original failure stays attached as `cause`
+ *  so the supervisor's structured error renderer shows the domain
+ *  error, such as `RouteCollision`, underneath the dispatch wrapper. */
+declare class ContributionSinkFailed extends ContributionSinkFailed_base<{
+  readonly kind: string;
+  readonly message: string;
+  readonly cause: unknown;
+}> {}
+interface CapabilitySinksShape {
+  /** Register a sink for a contribution kind. Last-write-wins on
+   *  duplicate kinds: a plugin-author overlay shadows the built-in
+   *  (the highest-seq surviving registration wins at `dispatch`).
+   *  Scope-bound: registering inside a `Layer` and providing the
+   *  layer to the supervisor's scope reaps the sink on shutdown.
+   *  Closing an overlay's scope un-shadows the built-in WITHOUT
+   *  clobbering any newer sibling registration for the same kind —
+   *  the scoped-multimap drops only this registration's own entry. */
+  readonly registerSink: <K extends ContributionKind, TDecl>(sink: CapabilitySink<K, TDecl>) => Effect.Effect<void, never, Scope.Scope>;
+  /** Dispatch a contribution to its registered sink. Errors with
+   *  `UnknownContributionKind` when no sink matches; the supervisor's
+   *  loop catches and downgrades to a no-op (per the
+   *  substrate-open-by-default rule). */
+  readonly dispatch: (contribution: AnyContribution, ctx: HarvestContext) => Effect.Effect<void, UnknownContributionKind | ContributionSinkFailed, Scope.Scope>;
+  /** Snapshot the kinds the registry currently knows. Diagnostic. */
+  readonly knownKinds: Effect.Effect<ReadonlyArray<string>>;
+}
+declare const CapabilitySinksService_base: Context.ServiceClass<CapabilitySinksService, "@devstack/substrate/CapabilitySinks", CapabilitySinksShape>;
+declare class CapabilitySinksService extends CapabilitySinksService_base {}
 //#endregion
-export { CapabilitySink, ContributionKind, HarvestContext };
+export { AnyContribution, CapabilitySink, CapabilitySinksService, CapabilitySinksShape, ContributionKind, ContributionSinkFailed, HarvestContext, UnknownContributionKind };
 //# sourceMappingURL=service.d.mts.map

package/dist/substrate/runtime/capability-sinks/service.mjs

@@ -1,4 +1,7 @@
-import { Context, Data, Effect, Layer, Ref } from "effect";
+import { SpanAttr } from "../observability/spans.mjs";
+import { makeScopedMultimap } from "../scoped-multimap/service.mjs";
+import "../scoped-multimap/index.mjs";
+import { Context, Data, Effect, Layer } from "effect";
 //#region src/substrate/runtime/capability-sinks/service.ts
 /** Surfaced when `dispatch` receives a kind no sink is registered for.
 *  Substrate stays open by default — unknown kinds are no-ops at the
@@ -10,7 +13,7 @@ var UnknownContributionKind = class extends Data.TaggedError("UnknownContributio
 *  so the supervisor's structured error renderer shows the domain
 *  error, such as `RouteCollision`, underneath the dispatch wrapper. */
 var ContributionSinkFailed = class extends Data.TaggedError("ContributionSinkFailed") {};
-var CapabilitySinksService = class extends Context.Service()("@devstack-rewrite/substrate/CapabilitySinks") {};
+var CapabilitySinksService = class extends Context.Service()("@devstack/substrate/CapabilitySinks") {};
 /** Derive the discriminator literal from a harvested contribution.
 *  Substrate name-blindness: this is the ONE place the substrate
 *  reads a `kind` off a decl — every other site routes through the
@@ -24,44 +27,36 @@ const kindOf = (contribution) => {
 *  authored sinks compose by providing a Layer that yields the
 *  service and calls `registerSink`. */
 const layerCapabilitySinks = Layer.effect(CapabilitySinksService, Effect.gen(function* () {
-	const sinksRef = yield* Ref.make(/* @__PURE__ */ new Map());
+	const store = yield* makeScopedMultimap();
 	const registerSink = (sink) => Effect.gen(function* () {
 		const accept = sink.accept;
-		const prior = yield* Ref.modify(sinksRef, (current) => {
-			const next = new Map(current);
-			const had = next.get(sink.kind) ?? null;
-			next.set(sink.kind, accept);
-			return [had, next];
-		});
-		yield* Effect.addFinalizer((_exit) => Ref.update(sinksRef, (current) => {
-			const next = new Map(current);
-			if (prior === null) next.delete(sink.kind);
-			else next.set(sink.kind, prior);
-			return next;
-		}));
-		yield* Effect.annotateCurrentSpan({ "capability-sinks.kind": sink.kind });
+		yield* store.register([{
+			key: sink.kind,
+			value: accept
+		}]);
+		yield* Effect.annotateCurrentSpan({ [SpanAttr.capabilitySinksKind]: sink.kind });
 	}).pipe(Effect.withSpan("substrate.capabilitySinks.registerSink"));
 	const dispatch = (contribution, ctx) => Effect.gen(function* () {
 		const kind = kindOf(contribution);
-		const sinks = yield* Ref.get(sinksRef);
-		const accept = sinks.get(kind);
-		if (accept === void 0) return yield* new UnknownContributionKind({
+		const entries = yield* store.entriesFor(kind);
+		if (entries.length === 0) return yield* new UnknownContributionKind({
 			kind,
-			known: [...sinks.keys()]
+			known: yield* store.keys
 		});
+		let chosen = entries[0];
+		for (let i = 1; i < entries.length; i++) if (entries[i].seq > chosen.seq) chosen = entries[i];
+		const accept = chosen.value;
 		yield* accept(contribution.source === "error" ? contribution.contribution : contribution.decl, ctx).pipe(Effect.mapError((cause) => new ContributionSinkFailed({
 			kind,
 			message: `capability sink '${kind}' failed`,
 			cause
 		})));
 		yield* Effect.annotateCurrentSpan({
-			"capability-sinks.kind": kind,
-			"devstack.plugin": ctx.pluginKey
+			[SpanAttr.capabilitySinksKind]: kind,
+			[SpanAttr.plugin]: ctx.pluginKey
 		});
 	}).pipe(Effect.withSpan("substrate.capabilitySinks.dispatch"));
-	const knownKinds = Effect.gen(function* () {
-		return [...(yield* Ref.get(sinksRef)).keys()];
-	});
+	const knownKinds = store.keys;
 	return CapabilitySinksService.of({
 		registerSink,
 		dispatch,
@@ -69,6 +64,6 @@ const layerCapabilitySinks = Layer.effect(CapabilitySinksService, Effect.gen(fun
 	});
 }));
 //#endregion
-export { CapabilitySinksService, layerCapabilitySinks };
+export { CapabilitySinksService, ContributionSinkFailed, UnknownContributionKind, kindOf, layerCapabilitySinks };
 
 //# sourceMappingURL=service.mjs.map