@mysten-incubation/devstack 0.0.1 → 0.1.1

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

@@ -29,6 +29,32 @@ const failStage = (stage, targetPath, stagingPath) => (cause) => Effect.fail(new
 	stagingPath,
 	cause
 }));
+/**
+* Extract the original Node errno `code` from a `FileSystem.rename` failure.
+*
+* Effect v4's `@effect/platform-node` wraps the raw `NodeJS.ErrnoException`
+* (`handleErrnoException` in `platform-node-shared/internal/utils.ts`) into a
+* `PlatformError` whose `reason` is a `SystemError`. The raw errno is preserved
+* as `reason.cause` (the unmodified Node error) — and the `PlatformError`
+* constructor additionally hoists that to the wrapper's own top-level `cause`.
+* So a genuine cross-filesystem rename surfaces the code at `reason.cause.code`
+* (and, equivalently, at `cause.cause.code`), NOT at the top-level `.code`.
+*
+* We probe every plausible location defensively: the nested SystemError cause,
+* the hoisted wrapper cause, and a bare-errno shape (in case a caller injects a
+* raw `NodeJS.ErrnoException` or the wrapping ever changes).
+*/
+const errnoCode = (cause) => {
+	const codeOf = (value) => {
+		if (typeof value !== "object" || value === null) return void 0;
+		const code = value.code;
+		return typeof code === "string" ? code : void 0;
+	};
+	if (typeof cause !== "object" || cause === null) return void 0;
+	const reasonCause = cause.reason?.cause;
+	const directCause = cause.cause;
+	return codeOf(reasonCause) ?? codeOf(directCause) ?? codeOf(cause);
+};
 const normalizePreservedRelativePath = (relativePath) => {
 	const normalized = normalize(relativePath);
 	if (relativePath.length === 0 || isAbsolute(relativePath) || normalized === "." || normalized === ".." || normalized.startsWith(`..${sep}`)) return null;
@@ -42,6 +68,9 @@ const preserveTargetPaths = (args) => Effect.gen(function* () {
 		const source = join(args.backupPath, relativePath);
 		if (!(yield* fs.exists(source).pipe(Effect.catch(() => Effect.succeed(false))))) continue;
 		const target = join(args.stagingPath, relativePath);
+		if (preserved.overwrite === false) {
+			if (yield* fs.exists(target).pipe(Effect.catch(() => Effect.succeed(false)))) continue;
+		}
 		yield* fs.makeDirectory(dirname(target), { recursive: true }).pipe(Effect.catch(failStage("preserve-target-paths", args.targetPath, args.stagingPath)));
 		yield* fs.copy(source, target, { overwrite: true }).pipe(Effect.catch(failStage("preserve-target-paths", args.targetPath, args.stagingPath)));
 	}
@@ -68,10 +97,37 @@ const preserveTargetPaths = (args) => Effect.gen(function* () {
 * targetPath. The helper picks it as a sibling under the same parent
 * (caller passes `parentDir`, we mint the names) — this is enforced
 * by the helper's signature shape.
+*
+* ## Two call shapes
+*
+*   - Explicit-paths: callers that need bespoke sibling names (the
+*     Seal plugin uses `.backup.` not `.bak.`; pre-existing tests use
+*     literal `target.staging`/`target.bak`) pass both `stagingPath`
+*     and `backupPath` directly.
+*   - `idSuffix`: callers (codegen, snapshot) pass `idSuffix` and the
+*     primitive mints `<targetPath>.staging.<idSuffix>` /
+*     `<targetPath>.bak.<idSuffix>` so the staging/backup-naming
+*     convention is owned in ONE place. Callers MUST NOT pass both
+*     `idSuffix` and explicit paths.
+*
+* ## `preserveOnPreseed`
+*
+* When `true`, before the user's `build` runs the primitive copies the
+* current `targetPath` (if any) into `stagingPath` so `build` can
+* mutate that baseline incrementally. This subsumes the codegen
+* orchestrator's pre-seed dance (per-file no-touch idempotency relies
+* on seeing the previous target's mtimes). Cross-cutting with
+* `preserveFromTarget` is allowed: pre-seed clones the whole tree
+* BEFORE the build; `preserveFromTarget` cherry-picks paths AFTER the
+* build and BEFORE the swap (and reads from the backup, so the build
+* may have rewritten them in-tree). The two features answer different
+* questions and the primitive runs them in that order.
 */
 const stageAndSwap = (args) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
-	const { targetPath, stagingPath, backupPath, build, preserveFromTarget = [], publishLockPath } = args;
+	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
@@ -81,6 +137,15 @@ const stageAndSwap = (args) => Effect.gen(function* () {
 		force: true
 	}).pipe(Effect.ignore);
 	yield* fs.makeDirectory(stagingPath, { recursive: true }).pipe(Effect.catch(failStage("mkdir-staging", targetPath, stagingPath)));
+	if (preserveOnPreseed) {
+		if (yield* fs.exists(targetPath).pipe(Effect.catch(() => Effect.succeed(false)))) yield* fs.copy(targetPath, stagingPath, {
+			overwrite: true,
+			preserveTimestamps: true
+		}).pipe(Effect.catch(failStage("mkdir-staging", targetPath, stagingPath)), Effect.onError(() => fs.remove(stagingPath, {
+			recursive: true,
+			force: true
+		}).pipe(Effect.ignore)));
+	}
 	const result = yield* build.pipe(Effect.onError(() => fs.remove(stagingPath, {
 		recursive: true,
 		force: true
@@ -101,13 +166,16 @@ const stageAndSwap = (args) => Effect.gen(function* () {
 			})));
 		}
 		yield* fs.rename(stagingPath, targetPath).pipe(Effect.catch((cause) => {
-			if (cause.code === "EXDEV") return Effect.gen(function* () {
+			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"
 				}));
-				yield* fs.copy(stagingPath, targetPath, { overwrite: false }).pipe(Effect.catch(failStage("cross-filesystem-fallback", targetPath, stagingPath)));
+				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)));
+					return yield* failStage("cross-filesystem-fallback", targetPath, stagingPath)(copyCause);
+				})));
 				yield* fs.remove(stagingPath, {
 					recursive: true,
 					force: true
@@ -126,6 +194,6 @@ const stageAndSwap = (args) => Effect.gen(function* () {
 	return result;
 }).pipe(Effect.withSpan("substrate.stage-and-swap"));
 //#endregion
-export { stageAndSwap };
+export { StageAndSwapError, stageAndSwap };
 
 //# sourceMappingURL=index.mjs.map

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}\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\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\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 */\nexport const stageAndSwap = <A, E>(args: {\n\treadonly targetPath: string;\n\treadonly stagingPath: string;\n\treadonly backupPath: string;\n\treadonly build: Effect.Effect<A, E, FileSystem.FileSystem>;\n\treadonly preserveFromTarget?: ReadonlyArray<StageAndSwapPreservedPath>;\n\treadonly publishLockPath?: string;\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\tstagingPath,\n\t\t\tbackupPath,\n\t\t\tbuild,\n\t\t\tpreserveFromTarget = [],\n\t\t\tpublishLockPath,\n\t\t} = args;\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// 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\tconst code = (cause as NodeJS.ErrnoException).code;\n\t\t\t\t\t\tif (code === '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\n\t\t\t\t\t\t\t\t\t.copy(stagingPath, targetPath, { overwrite: false })\n\t\t\t\t\t\t\t\t\t.pipe(\n\t\t\t\t\t\t\t\t\t\tEffect.catch(failStage('cross-filesystem-fallback', targetPath, stagingPath)),\n\t\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// 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":";;;;;;;;AAyCA,IAAa,oBAAb,cAAuC,OAAO,kBAAqC,CAClF,qBACA;CACC,OAAO,OAAO,SAAS;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,CAAC;CACF,YAAY,OAAO;CACnB,aAAa,OAAO;CACpB,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CACD,CAAC;AAoBF,MAAM,aAEJ,OACA,YACA,iBAEA,UACA,OAAO,KAAK,IAAI,kBAAkB;CAAE;CAAO;CAAY;CAAa;CAAO,CAAC,CAAC;;;;;;;;;;;;;;;;AAiB/E,MAAM,aAAa,UAAuC;CACzD,MAAM,UAAU,UAAuC;AACtD,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO,KAAA;EACxD,MAAM,OAAQ,MAA6B;AAC3C,SAAO,OAAO,SAAS,WAAW,OAAO,KAAA;;AAE1C,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO,KAAA;CACxD,MAAM,cAAe,MAA2C,QAAQ;CACxE,MAAM,cAAe,MAA8B;AACnD,QAAO,OAAO,YAAY,IAAI,OAAO,YAAY,IAAI,OAAO,MAAM;;AAGnE,MAAM,kCAAkC,iBAAwC;CAC/E,MAAM,aAAa,UAAU,aAAa;AAC1C,KACC,aAAa,WAAW,KACxB,WAAW,aAAa,IACxB,eAAe,OACf,eAAe,QACf,WAAW,WAAW,KAAK,MAAM,CAEjC,QAAO;AAER,QAAO;;AAGR,MAAM,uBAAuB,SAM5B,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;AAC7B,MAAK,MAAM,aAAa,KAAK,gBAAgB;EAC5C,MAAM,eAAe,+BAA+B,UAAU,aAAa;AAC3E,MAAI,iBAAiB,KACpB,QAAO,OAAO,UACb,yBACA,KAAK,YACL,KAAK,YACL,iBAAC,IAAI,MAAM,0BAA0B,UAAU,eAAe,CAAC;EAEjE,MAAM,SAAS,KAAK,KAAK,YAAY,aAAa;AAElD,MAAI,EAAC,OADiB,GAAG,OAAO,OAAO,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,EAC1E;EACb,MAAM,SAAS,KAAK,KAAK,aAAa,aAAa;AAMnD,MAAI,UAAU,cAAc;OAIvB,OAHwB,GAC1B,OAAO,OAAO,CACd,KAAK,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,CAC/B;;AAEnB,SAAO,GACL,cAAc,QAAQ,OAAO,EAAE,EAAE,WAAW,MAAM,CAAC,CACnD,KAAK,OAAO,MAAM,UAAU,yBAAyB,KAAK,YAAY,KAAK,YAAY,CAAC,CAAC;AAC3F,SAAO,GACL,KAAK,QAAQ,QAAQ,EAAE,WAAW,MAAM,CAAC,CACzC,KAAK,OAAO,MAAM,UAAU,yBAAyB,KAAK,YAAY,KAAK,YAAY,CAAC,CAAC;;EAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDH,MAAa,gBACZ,SAWA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,EACL,YACA,OACA,qBAAqB,EAAE,EACvB,oBAAoB,OACpB,oBACG;CACJ,MAAM,cACL,KAAK,eAAe,GAAG,WAAW,WAAY,KAA8B;CAC7E,MAAM,aACL,KAAK,cAAc,GAAG,WAAW,OAAQ,KAA8B;AACxE,QAAO,OAAO,oBAAoB;EACjC,kCAAkC;EAClC,mCAAmC;EACnC,CAAC;AAIF,QAAO,GAAG,OAAO,aAAa;EAAE,WAAW;EAAM,OAAO;EAAM,CAAC,CAAC,KAAK,OAAO,OAAO;AACnF,QAAO,GACL,cAAc,aAAa,EAAE,WAAW,MAAM,CAAC,CAC/C,KAAK,OAAO,MAAM,UAAU,iBAAiB,YAAY,YAAY,CAAC,CAAC;AAQzE,KAAI;MAIC,OAHkC,GACpC,OAAO,WAAW,CAClB,KAAK,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,CAEhD,QAAO,GAAG,KAAK,YAAY,aAAa;GAAE,WAAW;GAAM,oBAAoB;GAAM,CAAC,CAAC,KACtF,OAAO,MAAM,UAAU,iBAAiB,YAAY,YAAY,CAAC,EACjE,OAAO,cACN,GAAG,OAAO,aAAa;GAAE,WAAW;GAAM,OAAO;GAAM,CAAC,CAAC,KAAK,OAAO,OAAO,CAC5E,CACD;;CAOH,MAAM,SAAS,OAAO,MAAM,KAC3B,OAAO,cACN,GAAG,OAAO,aAAa;EAAE,WAAW;EAAM,OAAO;EAAM,CAAC,CAAC,KAAK,OAAO,OAAO,CAC5E,CACD;AAiGD,KAAI,OA5FwB,OAAO,OAClC,OAAO,IAAI,aAAa;AACvB,MAAI,oBAAoB,KAAA,EACvB,QAAO,iBAAiB,gBAAgB,CAAC,KACxC,OAAO,MAAM,UAAU,wBAAwB,YAAY,YAAY,CAAC,CACxE;EAGF,MAAM,eAAe,OAAO,GAC1B,OAAO,WAAW,CAClB,KAAK,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC;AACjD,MAAI,cAAc;AAEjB,UAAO,GACL,OAAO,YAAY,WAAW,CAC9B,KAAK,OAAO,MAAM,UAAU,kBAAkB,YAAY,YAAY,CAAC,CAAC;AAC1E,UAAO,oBAAoB;IAC1B;IACA;IACA;IACA,gBAAgB;IAChB,CAAC,CAAC,KACF,OAAO,OAAO,UACb,OAAO,IAAI,aAAa;AACvB,WAAO,GACL,OAAO,YAAY,WAAW,CAC9B,KAAK,OAAO,MAAM,UAAU,kBAAkB,YAAY,YAAY,CAAC,CAAC;AAC1E,WAAO,OAAO,OAAO,KAAK,MAAM;KAC/B,CACF,CACD;;AAIF,SAAO,GAAG,OAAO,aAAa,WAAW,CAAC,KACzC,OAAO,OAAO,UAAU;AAIvB,OAAI,UAAU,MAAM,KAAK,QAIxB,QAAO,OAAO,IAAI,aAAa;AAC9B,WAAO,OAAO,WAAW,2CAA2C,CAAC,KACpE,OAAO,aAAa;MAClB,SAAS,yBAAyB;MAClC,SAAS,0BAA0B;MACnC,SAAS,YAAY;KACtB,CAAC,CACF;AACD,WAAO,GAAG,KAAK,aAAa,YAAY,EAAE,WAAW,OAAO,CAAC,CAAC,KAC7D,OAAO,OAAO,cACb,OAAO,IAAI,aAAa;AAIvB,SAAI,aACH,QAAO,GACL,OAAO,YAAY,WAAW,CAC9B,KAAK,OAAO,MAAM,UAAU,kBAAkB,YAAY,YAAY,CAAC,CAAC;AAE3E,YAAO,OAAO,UACb,6BACA,YACA,YACA,CAAC,UAAU;MACX,CACF,CACD;AACD,WAAO,GAAG,OAAO,aAAa;KAAE,WAAW;KAAM,OAAO;KAAM,CAAC,CAAC,KAAK,OAAO,OAAO;KAClF;AAIH,UAAO,OAAO,IAAI,aAAa;AAC9B,QAAI,aACH,QAAO,GACL,OAAO,YAAY,WAAW,CAC9B,KAAK,OAAO,MAAM,UAAU,kBAAkB,YAAY,YAAY,CAAC,CAAC;AAE3E,WAAO,OAAO,UAAU,sBAAsB,YAAY,YAAY,CAAC,MAAM;KAC5E;IACD,CACF;AAED,SAAO;GACN,CACF,CAKA,QAAO,GAAG,OAAO,YAAY;EAAE,WAAW;EAAM,OAAO;EAAM,CAAC,CAAC,KAAK,OAAO,OAAO;AAGnF,QAAO;EACN,CAAC,KAAK,OAAO,SAAS,2BAA2B,CAAC"}

package/dist/substrate/runtime/state-store/index.d.mts

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

package/dist/substrate/runtime/state-store/index.mjs

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

package/dist/substrate/runtime/state-store/schema.d.mts

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

package/dist/substrate/runtime/state-store/schema.mjs

@@ -1,3 +1,4 @@
+import { versionedDocSchema } from "../../versioned-doc-schema.mjs";
 import { Schema } from "effect";
 //#region src/substrate/runtime/state-store/schema.ts
 /** Stored value envelope. The phantom-typed `StateKey<V>` reads /
@@ -17,20 +18,24 @@ const StateEntry = Schema.Struct({
 	updatedAt: Schema.Number
 });
 /** Document — one file per stack. Keys are the `StateKey<V>` string
-*  form (`<pluginKey>/<suffix>`), values are entries. */
-const StateDocument = Schema.Struct({
-	/** Schema version; bump on incompatible changes. v1 is the
-	*  initial release; bumps are the only way to introduce
-	*  backward-incompatible shape changes. Schema-decode failure on
-	*  read with an unknown version surfaces as `corruption`. */
-	version: Schema.Literal(1),
-	/** Per-plugin namespaces. Key is the plugin-key prefix; nested
-	*  record is the plugin's own keys (suffix → entry). Two-level
-	*  structure (vs. flat `pluginKey/suffix → entry`) so `listUnder`
-	*  is an O(1) lookup and per-plugin wipes are O(1) field deletes. */
-	plugins: Schema.Record(Schema.String, Schema.Record(Schema.String, StateEntry))
-});
+*  form (`<pluginKey>/<suffix>`), values are entries.
+*
+*  Schema version: bump on incompatible changes. v1 is the initial
+*  release; bumps are the only way to introduce backward-incompatible
+*  shape changes. Schema-decode failure on read with an unknown
+*  version surfaces as `corruption`. */
+const StateDocument = versionedDocSchema(1, { 
+/** Per-plugin namespaces. Key is the plugin-key prefix; nested
+*  record is the plugin's own keys (suffix → entry). Two-level
+*  structure (vs. flat `pluginKey/suffix → entry`) so `listUnder`
+*  is an O(1) lookup and per-plugin wipes are O(1) field deletes. */
+plugins: Schema.Record(Schema.String, Schema.Record(Schema.String, StateEntry)) });
+/** Initial empty document. */
+const emptyDocument = {
+	version: 1,
+	plugins: {}
+};
 //#endregion
-export { StateDocument };
+export { StateDocument, StateEntry, emptyDocument };
 
 //# sourceMappingURL=schema.mjs.map

package/dist/substrate/runtime/state-store/schema.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"schema.mjs","names":[],"sources":["../../../../src/substrate/runtime/state-store/schema.ts"],"sourcesContent":["// On-disk schema for the per-stack state.json.\n//\n// One file per stack. Plugin-keyed top-level subtrees so two\n// plugins never see each other's keys. Tombstones distinguish\n// \"deleted\" from \"missing\" — see header of `state-store.ts`.\n\nimport { Schema } from 'effect';\n\n/** Stored value envelope. The phantom-typed `StateKey<V>` reads /\n *  writes against the `value` slot opaquely (the substrate doesn't\n *  introspect plugin values — it stores the JSON value as `unknown`\n *  and re-encodes the document on every set). */\nexport const StateEntry = Schema.Struct({\n\t/** Discriminator. `present` carries a value; `tombstone` records\n\t *  that the key was deleted (so reads can distinguish \"user\n\t *  removed this\" from \"user never wrote it\"). */\n\tstate: Schema.Literals(['present', 'tombstone']),\n\t/** Encoded value. For `tombstone` entries this is `null`; the\n\t *  substrate refuses to deliver it on `get`. */\n\tvalue: Schema.Unknown,\n\t/** Timestamp of the last mutation. Renderers may surface it;\n\t *  the substrate uses it only for diagnostics. */\n\tupdatedAt: Schema.Number,\n});\nexport type StateEntry = typeof StateEntry.Type;\n\n/** Document — one file per stack. Keys are the `StateKey<V>` string\n *  form (`<pluginKey>/<suffix>`), values are entries. */\nexport const StateDocument = Schema.Struct({\n\t/** Schema version; bump on incompatible changes. v1 is the\n\t *  initial release; bumps are the only way to introduce\n\t *  backward-incompatible shape changes. Schema-decode failure on\n\t *  read with an unknown version surfaces as `corruption`. */\n\tversion: Schema.Literal(1),\n\t/** Per-plugin namespaces. Key is the plugin-key prefix; nested\n\t *  record is the plugin's own keys (suffix → entry). Two-level\n\t *  structure (vs. flat `pluginKey/suffix → entry`) so `listUnder`\n\t *  is an O(1) lookup and per-plugin wipes are O(1) field deletes. */\n\tplugins: Schema.Record(Schema.String, Schema.Record(Schema.String, StateEntry)),\n});\nexport type StateDocument = typeof StateDocument.Type;\n\n/** Initial empty document. */\nexport const emptyDocument: StateDocument = { version: 1, plugins: {} };\n"],"mappings":";;;;;;AAYA,MAAa,aAAa,OAAO,OAAO;;;;CAIvC,OAAO,OAAO,SAAS,CAAC,WAAW,YAAY,CAAC;;;CAGhD,OAAO,OAAO;;;CAGd,WAAW,OAAO;CAClB,CAAC;;;AAKF,MAAa,gBAAgB,OAAO,OAAO;;;;;CAK1C,SAAS,OAAO,QAAQ,EAAE;;;;;CAK1B,SAAS,OAAO,OAAO,OAAO,QAAQ,OAAO,OAAO,OAAO,QAAQ,WAAW,CAAC;CAC/E,CAAC"}
+{"version":3,"file":"schema.mjs","names":[],"sources":["../../../../src/substrate/runtime/state-store/schema.ts"],"sourcesContent":["// On-disk schema for the per-stack state.json.\n//\n// One file per stack. Plugin-keyed top-level subtrees so two\n// plugins never see each other's keys. Tombstones distinguish\n// \"deleted\" from \"missing\" — see header of `state-store.ts`.\n\nimport { Schema } from 'effect';\n\nimport { versionedDocSchema } from '../../versioned-doc-schema.ts';\n\n/** Stored value envelope. The phantom-typed `StateKey<V>` reads /\n *  writes against the `value` slot opaquely (the substrate doesn't\n *  introspect plugin values — it stores the JSON value as `unknown`\n *  and re-encodes the document on every set). */\nexport const StateEntry = Schema.Struct({\n\t/** Discriminator. `present` carries a value; `tombstone` records\n\t *  that the key was deleted (so reads can distinguish \"user\n\t *  removed this\" from \"user never wrote it\"). */\n\tstate: Schema.Literals(['present', 'tombstone']),\n\t/** Encoded value. For `tombstone` entries this is `null`; the\n\t *  substrate refuses to deliver it on `get`. */\n\tvalue: Schema.Unknown,\n\t/** Timestamp of the last mutation. Renderers may surface it;\n\t *  the substrate uses it only for diagnostics. */\n\tupdatedAt: Schema.Number,\n});\nexport type StateEntry = typeof StateEntry.Type;\n\n/** Document — one file per stack. Keys are the `StateKey<V>` string\n *  form (`<pluginKey>/<suffix>`), values are entries.\n *\n *  Schema version: bump on incompatible changes. v1 is the initial\n *  release; bumps are the only way to introduce backward-incompatible\n *  shape changes. Schema-decode failure on read with an unknown\n *  version surfaces as `corruption`. */\nexport const StateDocument = versionedDocSchema(1, {\n\t/** Per-plugin namespaces. Key is the plugin-key prefix; nested\n\t *  record is the plugin's own keys (suffix → entry). Two-level\n\t *  structure (vs. flat `pluginKey/suffix → entry`) so `listUnder`\n\t *  is an O(1) lookup and per-plugin wipes are O(1) field deletes. */\n\tplugins: Schema.Record(Schema.String, Schema.Record(Schema.String, StateEntry)),\n});\nexport type StateDocument = typeof StateDocument.Type;\n\n/** Initial empty document. */\nexport const emptyDocument: StateDocument = { version: 1, plugins: {} };\n"],"mappings":";;;;;;;AAcA,MAAa,aAAa,OAAO,OAAO;;;;CAIvC,OAAO,OAAO,SAAS,CAAC,WAAW,YAAY,CAAC;;;CAGhD,OAAO,OAAO;;;CAGd,WAAW,OAAO;CAClB,CAAC;;;;;;;;AAUF,MAAa,gBAAgB,mBAAmB,GAAG;;;;;AAKlD,SAAS,OAAO,OAAO,OAAO,QAAQ,OAAO,OAAO,OAAO,QAAQ,WAAW,CAAC,EAC/E,CAAC;;AAIF,MAAa,gBAA+B;CAAE,SAAS;CAAG,SAAS,EAAE;CAAE"}

package/dist/substrate/runtime/state-store/service.d.mts

@@ -0,0 +1 @@
+import { Context, FileSystem, Layer } from "effect";

package/dist/substrate/runtime/state-store/service.mjs

@@ -0,0 +1,145 @@
+import { StackPathsService } from "../paths.mjs";
+import { StateStoreError } from "../errors.mjs";
+import { atomicWriteJson } from "../atomic-write.mjs";
+import { decodeJsonText } from "../runtime-decode.mjs";
+import { StateDocument, emptyDocument } from "./schema.mjs";
+import { CrossProcessLock } from "../cross-process/lock.mjs";
+import { Context, Effect, FileSystem, Layer, Ref } from "effect";
+//#region src/substrate/runtime/state-store/service.ts
+/**
+* The substrate-internal state-store service. The
+* `StateStore` interface re-exported from `substrate/state-store.ts`
+* is the user-facing shape; this is the wired-up implementation.
+*/
+var StateStoreService = class extends Context.Service()("@devstack/substrate/StateStore") {};
+/**
+* Parse `StateKey<V>` (`<pluginKey>/<suffix>`) into its two parts.
+* The key invariant from `substrate/state-store.ts`'s
+* `defineStateKey` is the single `/` separator; we cope with
+* suffix-contains-slash by splitting on the FIRST `/`.
+*/
+const splitKey = (key) => {
+	const i = key.indexOf("/");
+	if (i < 0) return {
+		plugin: "__malformed__",
+		suffix: key
+	};
+	return {
+		plugin: key.slice(0, i),
+		suffix: key.slice(i + 1)
+	};
+};
+/** Read+decode the document. Missing file → empty document. */
+const readDocument = Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const paths = yield* StackPathsService;
+	if (!(yield* fs.exists(paths.stateFile).pipe(Effect.catch((cause) => Effect.fail(new StateStoreError({
+		reason: "io-failed",
+		detail: `failed to stat state file: ${paths.stateFile}`,
+		cause
+	})))))) return emptyDocument;
+	return yield* decodeJsonText(StateDocument, yield* fs.readFileString(paths.stateFile).pipe(Effect.catch((cause) => Effect.fail(new StateStoreError({
+		reason: "io-failed",
+		detail: `failed to read state file: ${paths.stateFile}`,
+		cause
+	})))), {
+		source: paths.stateFile,
+		mkError: (issue) => new StateStoreError({
+			reason: "corruption",
+			detail: issue.message === "failed to parse JSON" ? `state file is not valid JSON: ${paths.stateFile}` : `state file failed schema decode: ${paths.stateFile}`,
+			cause: issue.cause
+		})
+	});
+}).pipe(Effect.withSpan("substrate.stateStore.read"));
+/** Write+encode the document atomically. */
+const writeDocument = (doc) => Effect.gen(function* () {
+	const paths = yield* StackPathsService;
+	yield* atomicWriteJson(paths.stateFile, StateDocument, doc).pipe(Effect.catch((cause) => Effect.fail(new StateStoreError({
+		reason: "io-failed",
+		detail: `atomic write failed: ${paths.stateFile}`,
+		cause
+	}))));
+}).pipe(Effect.withSpan("substrate.stateStore.write"));
+Layer.effect(StateStoreService, Effect.gen(function* () {
+	const lock = yield* CrossProcessLock;
+	const fs = yield* FileSystem.FileSystem;
+	const paths = yield* StackPathsService;
+	const provideEnv = (effect) => effect.pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(StackPathsService, paths));
+	const initial = yield* provideEnv(readDocument);
+	const cache = yield* Ref.make(initial);
+	const get = (key) => Effect.gen(function* () {
+		const doc = yield* Ref.get(cache);
+		const { plugin, suffix } = splitKey(key);
+		const entry = doc.plugins[plugin]?.[suffix];
+		if (!entry) return null;
+		if (entry.state === "tombstone") return null;
+		return entry.value;
+	});
+	const mapLockErrors = (eff) => eff.pipe(Effect.catchTags({
+		StackLockTimeoutError: (e) => Effect.fail(new StateStoreError({
+			reason: "lock-contention",
+			detail: `state-store write blocked: peer holds ${e.path} (waited ${e.waitedMillis}ms)`,
+			cause: e
+		})),
+		StackLockIoError: (e) => Effect.fail(new StateStoreError({
+			reason: "io-failed",
+			detail: `state-store lock IO error on ${e.path}`,
+			cause: e.cause
+		}))
+	}));
+	const set = (key, value) => mapLockErrors(lock.withLock(provideEnv(Effect.uninterruptible(Effect.gen(function* () {
+		const fresh = yield* readDocument;
+		const { plugin, suffix } = splitKey(key);
+		const next = {
+			version: 1,
+			plugins: {
+				...fresh.plugins,
+				[plugin]: {
+					...fresh.plugins[plugin],
+					[suffix]: {
+						state: "present",
+						value,
+						updatedAt: Date.now()
+					}
+				}
+			}
+		};
+		yield* writeDocument(next);
+		yield* Ref.set(cache, next);
+	})))));
+	const del = (key) => mapLockErrors(lock.withLock(provideEnv(Effect.uninterruptible(Effect.gen(function* () {
+		const fresh = yield* readDocument;
+		const { plugin, suffix } = splitKey(key);
+		const next = {
+			version: 1,
+			plugins: {
+				...fresh.plugins,
+				[plugin]: {
+					...fresh.plugins[plugin],
+					[suffix]: {
+						state: "tombstone",
+						value: null,
+						updatedAt: Date.now()
+					}
+				}
+			}
+		};
+		yield* writeDocument(next);
+		yield* Ref.set(cache, next);
+	})))));
+	const listUnder = (prefix) => Effect.gen(function* () {
+		const ns = (yield* Ref.get(cache)).plugins[prefix];
+		if (!ns) return [];
+		return Object.entries(ns).filter(([, entry]) => entry.state === "present").map(([suffix]) => `${prefix}/${suffix}`);
+	});
+	return StateStoreService.of({
+		get,
+		set,
+		delete: del,
+		listUnder
+	});
+}));
+//#endregion
+export { StateStoreService };
+
+//# sourceMappingURL=service.mjs.map

package/dist/substrate/runtime/state-store/service.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../../src/substrate/runtime/state-store/service.ts"],"sourcesContent":["// State-store implementation.\n//\n// Per-stack JSON file at `<runtime-root>/stacks/<stack>/state.json`.\n// Plugin-keyed namespacing; tombstone-vs-missing distinction;\n// atomic-write on every mutation; cross-process safety via the\n// injected lock.\n//\n// Tombstones:\n//   - `get` on a tombstoned key returns `null` (same as missing) —\n//     the type-level contract is \"absent\". The on-disk distinction\n//     is preserved so snapshot/restore round-trips correctly\n//     classify a deletion (tombstone) vs a never-written key\n//     (missing). Inspectors can `peek` to see the discriminator;\n//     normal plugin code never needs it.\n//   - `delete` writes a tombstone (rather than deleting the field).\n//     Two reasons:\n//       (a) Snapshot equality is now precise — \"removed since\n//           snapshot\" survives the round-trip.\n//       (b) An interrupted writer never silently resurrects a\n//           previously-deleted key (the present-record stays\n//           tombstone-shaped until set() runs again).\n//   - `wipe()` (full plugin namespace removal) IS a hard remove;\n//     tombstones are field-grain, namespace-grain wipe is route-\n//     grain.\n\nimport { Context, Effect, FileSystem, Layer, Ref } from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport type { StateKey, StateStore } from '../../state-store.ts';\nimport { atomicWriteJson } from '../atomic-write.ts';\nimport { CrossProcessLock } from '../cross-process/lock.ts';\nimport type { StackLockIoError, StackLockTimeoutError } from '../cross-process/stack-lock.ts';\nimport { StateStoreError } from '../errors.ts';\nimport { StackPathsService } from '../paths.ts';\nimport { decodeJsonText } from '../runtime-decode.ts';\nimport { emptyDocument, StateDocument, type StateEntry } from './schema.ts';\n\n/**\n * The substrate-internal state-store service. The\n * `StateStore` interface re-exported from `substrate/state-store.ts`\n * is the user-facing shape; this is the wired-up implementation.\n */\nexport class StateStoreService extends Context.Service<StateStoreService, StateStore>()(\n\t'@devstack/substrate/StateStore',\n) {}\n\n/**\n * Parse `StateKey<V>` (`<pluginKey>/<suffix>`) into its two parts.\n * The key invariant from `substrate/state-store.ts`'s\n * `defineStateKey` is the single `/` separator; we cope with\n * suffix-contains-slash by splitting on the FIRST `/`.\n */\nconst splitKey = (key: string): { readonly plugin: string; readonly suffix: string } => {\n\tconst i = key.indexOf('/');\n\t// A key without `/` is programmer error (`defineStateKey`\n\t// always produces one). Fall back gracefully so we don't\n\t// hard-crash on a misuse — store the whole string under a\n\t// `__malformed__` namespace, surfaced on listUnder for the\n\t// authoring plugin to notice in dev.\n\tif (i < 0) return { plugin: '__malformed__', suffix: key };\n\treturn { plugin: key.slice(0, i), suffix: key.slice(i + 1) };\n};\n\n/** Read+decode the document. Missing file → empty document. */\nconst readDocument: Effect.Effect<\n\tStateDocument,\n\tStateStoreError,\n\tFileSystem.FileSystem | StackPathsService\n> = Effect.gen(function* () {\n\tconst fs = yield* FileSystem.FileSystem;\n\tconst paths = yield* StackPathsService;\n\tconst exists = yield* fs.exists(paths.stateFile).pipe(\n\t\tEffect.catch((cause) =>\n\t\t\tEffect.fail(\n\t\t\t\tnew StateStoreError({\n\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\tdetail: `failed to stat state file: ${paths.stateFile}`,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t\t),\n\t\t),\n\t);\n\tif (!exists) return emptyDocument;\n\tconst text = yield* fs.readFileString(paths.stateFile).pipe(\n\t\tEffect.catch((cause) =>\n\t\t\tEffect.fail(\n\t\t\t\tnew StateStoreError({\n\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\tdetail: `failed to read state file: ${paths.stateFile}`,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t\t),\n\t\t),\n\t);\n\treturn yield* decodeJsonText(StateDocument, text, {\n\t\tsource: paths.stateFile,\n\t\tmkError: (issue) =>\n\t\t\tnew StateStoreError({\n\t\t\t\treason: 'corruption',\n\t\t\t\tdetail:\n\t\t\t\t\tissue.message === 'failed to parse JSON'\n\t\t\t\t\t\t? `state file is not valid JSON: ${paths.stateFile}`\n\t\t\t\t\t\t: `state file failed schema decode: ${paths.stateFile}`,\n\t\t\t\tcause: issue.cause,\n\t\t\t}),\n\t});\n}).pipe(Effect.withSpan('substrate.stateStore.read'));\n\n/** Write+encode the document atomically. */\nconst writeDocument = (\n\tdoc: StateDocument,\n): Effect.Effect<void, StateStoreError, FileSystem.FileSystem | StackPathsService> =>\n\tEffect.gen(function* () {\n\t\tconst paths = yield* StackPathsService;\n\t\tyield* atomicWriteJson(paths.stateFile, StateDocument, doc).pipe(\n\t\t\tEffect.catch((cause) =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\tnew StateStoreError({\n\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\tdetail: `atomic write failed: ${paths.stateFile}`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\t);\n\t}).pipe(Effect.withSpan('substrate.stateStore.write'));\n\n/**\n * The state-store Layer. Caches the document in a process-local\n * `Ref` so reads after the first don't touch disk; every mutation\n * runs under the cross-process lock so foreign processes don't\n * trample our changes mid-flight.\n *\n * Cache semantics: the in-process `Ref` is the truth for in-process\n * readers; it is invalidated by re-reading inside the locked\n * mutation. This deliberately does NOT poll the file — if another\n * process writes between our reads, we'll observe the change on the\n * next `withLock` r-m-w (re-read inside the critical section).\n * Plugins that need \"see foreign writes\" must invoke `refresh`\n * (exposed for the supervisor / watch dispatcher).\n */\nexport const layerStateStore: Layer.Layer<\n\tStateStoreService,\n\tStateStoreError,\n\tFileSystem.FileSystem | StackPathsService | CrossProcessLock\n> = Layer.effect(\n\tStateStoreService,\n\tEffect.gen(function* () {\n\t\tconst lock = yield* CrossProcessLock;\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst paths = yield* StackPathsService;\n\t\t// `readDocument` / `writeDocument` declare `FileSystem |\n\t\t// StackPathsService` requirements; we discharge both from the\n\t\t// Layer-level closure so the per-method Effects are `R = never`,\n\t\t// matching the `StateStore` contract.\n\t\tconst provideEnv = <A, E>(\n\t\t\teffect: Effect.Effect<A, E, FileSystem.FileSystem | StackPathsService>,\n\t\t): Effect.Effect<A, E> =>\n\t\t\teffect.pipe(\n\t\t\t\tEffect.provideService(FileSystem.FileSystem, fs),\n\t\t\t\tEffect.provideService(StackPathsService, paths),\n\t\t\t);\n\t\t// Prime the cache with the on-disk document. If decoding\n\t\t// fails at boot, we fail the Layer — the supervisor must\n\t\t// surface the corruption to the user (not silently re-init).\n\t\tconst initial = yield* provideEnv(readDocument);\n\t\tconst cache = yield* Ref.make(initial);\n\n\t\tconst get: StateStore['get'] = <V>(key: StateKey<V>) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst doc = yield* Ref.get(cache);\n\t\t\t\tconst { plugin, suffix } = splitKey(key);\n\t\t\t\tconst entry: StateEntry | undefined = doc.plugins[plugin]?.[suffix];\n\t\t\t\tif (!entry) return null;\n\t\t\t\tif (entry.state === 'tombstone') return null;\n\t\t\t\treturn entry.value as V;\n\t\t\t});\n\n\t\t// Map the lock's typed acquire failures onto our `lock-contention`\n\t\t// reason on `StateStoreError`. The `StateStore` contract already\n\t\t// advertises that mutation methods surface this reason — caller\n\t\t// recovery is the same shape as any other write failure (retry on\n\t\t// the next user action; surface in the supervisor cascade).\n\t\tconst mapLockErrors = <A, R>(\n\t\t\teff: Effect.Effect<A, StateStoreError | StackLockTimeoutError | StackLockIoError, R>,\n\t\t): Effect.Effect<A, StateStoreError, R> =>\n\t\t\teff.pipe(\n\t\t\t\tEffect.catchTags({\n\t\t\t\t\tStackLockTimeoutError: (e) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew StateStoreError({\n\t\t\t\t\t\t\t\treason: 'lock-contention',\n\t\t\t\t\t\t\t\tdetail: `state-store write blocked: peer holds ${e.path} (waited ${e.waitedMillis}ms)`,\n\t\t\t\t\t\t\t\tcause: e,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\tStackLockIoError: (e) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\tnew StateStoreError({\n\t\t\t\t\t\t\t\treason: 'io-failed',\n\t\t\t\t\t\t\t\tdetail: `state-store lock IO error on ${e.path}`,\n\t\t\t\t\t\t\t\tcause: e.cause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t}),\n\t\t\t);\n\n\t\tconst set: StateStore['set'] = <V>(key: StateKey<V>, value: V) =>\n\t\t\tmapLockErrors(\n\t\t\t\tlock.withLock(\n\t\t\t\t\tprovideEnv(\n\t\t\t\t\t\t// Uninterruptible: an interrupt landing between the\n\t\t\t\t\t\t// disk write and the cache update would leave the\n\t\t\t\t\t\t// in-process cache stale vs disk. The section is\n\t\t\t\t\t\t// short and already serialized by `withLock`, so\n\t\t\t\t\t\t// masking interruption here costs nothing and keeps\n\t\t\t\t\t\t// cache/disk coherent.\n\t\t\t\t\t\tEffect.uninterruptible(\n\t\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\t\t// Re-read INSIDE the lock so we don't clobber\n\t\t\t\t\t\t\t\t// foreign writes that landed since our prime.\n\t\t\t\t\t\t\t\tconst fresh = yield* readDocument;\n\t\t\t\t\t\t\t\tconst { plugin, suffix } = splitKey(key);\n\t\t\t\t\t\t\t\tconst next: StateDocument = {\n\t\t\t\t\t\t\t\t\tversion: 1,\n\t\t\t\t\t\t\t\t\tplugins: {\n\t\t\t\t\t\t\t\t\t\t...fresh.plugins,\n\t\t\t\t\t\t\t\t\t\t[plugin]: {\n\t\t\t\t\t\t\t\t\t\t\t...fresh.plugins[plugin],\n\t\t\t\t\t\t\t\t\t\t\t[suffix]: {\n\t\t\t\t\t\t\t\t\t\t\t\tstate: 'present',\n\t\t\t\t\t\t\t\t\t\t\t\tvalue: value as unknown,\n\t\t\t\t\t\t\t\t\t\t\t\tupdatedAt: Date.now(),\n\t\t\t\t\t\t\t\t\t\t\t},\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* writeDocument(next);\n\t\t\t\t\t\t\t\tyield* Ref.set(cache, next);\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);\n\n\t\tconst del: StateStore['delete'] = <V>(key: StateKey<V>) =>\n\t\t\tmapLockErrors(\n\t\t\t\tlock.withLock(\n\t\t\t\t\tprovideEnv(\n\t\t\t\t\t\t// Uninterruptible for the same cache/disk coherence\n\t\t\t\t\t\t// reason as `set` — see the note there.\n\t\t\t\t\t\tEffect.uninterruptible(\n\t\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\t\tconst fresh = yield* readDocument;\n\t\t\t\t\t\t\t\tconst { plugin, suffix } = splitKey(key);\n\t\t\t\t\t\t\t\t// Tombstone-write — preserves the\n\t\t\t\t\t\t\t\t// \"deleted-since\" record across snapshots.\n\t\t\t\t\t\t\t\tconst next: StateDocument = {\n\t\t\t\t\t\t\t\t\tversion: 1,\n\t\t\t\t\t\t\t\t\tplugins: {\n\t\t\t\t\t\t\t\t\t\t...fresh.plugins,\n\t\t\t\t\t\t\t\t\t\t[plugin]: {\n\t\t\t\t\t\t\t\t\t\t\t...fresh.plugins[plugin],\n\t\t\t\t\t\t\t\t\t\t\t[suffix]: {\n\t\t\t\t\t\t\t\t\t\t\t\tstate: 'tombstone',\n\t\t\t\t\t\t\t\t\t\t\t\tvalue: null,\n\t\t\t\t\t\t\t\t\t\t\t\tupdatedAt: Date.now(),\n\t\t\t\t\t\t\t\t\t\t\t},\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* writeDocument(next);\n\t\t\t\t\t\t\t\tyield* Ref.set(cache, next);\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);\n\n\t\tconst listUnder: StateStore['listUnder'] = (prefix: PluginKey) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst doc = yield* Ref.get(cache);\n\t\t\t\tconst ns = doc.plugins[prefix];\n\t\t\t\tif (!ns) return [];\n\t\t\t\t// Skip tombstones from `listUnder` — they're\n\t\t\t\t// internally observable via `peek` but the public\n\t\t\t\t// \"what keys are present?\" view hides them.\n\t\t\t\treturn Object.entries(ns)\n\t\t\t\t\t.filter(([, entry]) => entry.state === 'present')\n\t\t\t\t\t.map(([suffix]) => `${prefix}/${suffix}`);\n\t\t\t});\n\n\t\treturn StateStoreService.of({\n\t\t\tget,\n\t\t\tset,\n\t\t\tdelete: del,\n\t\t\tlistUnder,\n\t\t});\n\t}),\n);\n"],"mappings":"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"}

package/dist/substrate/runtime/strategy-registry/chain-keyed-strategy-for.d.mts

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

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

@@ -0,0 +1,33 @@
+import { StrategyRegistryService } from "./service.mjs";
+import { Effect } from "effect";
+//#region src/substrate/runtime/strategy-registry/chain-keyed-strategy-for.ts
+/**
+* Look up the strategy registered under `<prefix>:<chainId>` and surface
+* it with the caller's expected shape.
+*
+* The strategy shape `P` is a free generic — the plugin that owns the
+* capability prefix also owns its strategy contract, and callers pass
+* both at the call site:
+*
+* ```ts
+* import { FAUCET_CAPABILITY_KEY_PREFIX, type FaucetStrategy } from '../faucet/index.ts';
+*
+* const strategy = yield* chainKeyedStrategyFor<FaucetStrategy>(
+*   FAUCET_CAPABILITY_KEY_PREFIX,
+*   parts.chainId,
+* );
+* ```
+*
+* Failure shape is the substrate `StrategyNotFoundError`; callers that
+* want a plugin-flavored error project it via `Effect.catchTag` at the
+* call site.
+*/
+const chainKeyedStrategyFor = (prefix, chainId) => Effect.gen(function* () {
+	const registry = yield* StrategyRegistryService;
+	const key = `${prefix}:${chainId}`;
+	return yield* registry.get(key);
+});
+//#endregion
+export { chainKeyedStrategyFor };
+
+//# sourceMappingURL=chain-keyed-strategy-for.mjs.map

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

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

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

@@ -1,5 +1,5 @@
-import { chainProbeCapabilityKey } from "../../../contracts/chain-probe.mjs";
 import { StrategyRegistryService } from "./service.mjs";
+import { chainProbeCapabilityKey } from "../../../contracts/chain-probe.mjs";
 import { Effect } from "effect";
 //#region src/substrate/runtime/strategy-registry/chain-probe-for.ts
 /**

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 { StrategyNotFoundError } from '../../../contracts/strategy-contributor.ts';\nimport type { ChainId } from '../../brand.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 { 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"}

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

@@ -0,0 +1,4 @@
+import "./service.mjs";
+import "./chain-probe-for.mjs";
+import "./chain-keyed-strategy-for.mjs";
+export {};

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

@@ -1,60 +1,46 @@
+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, Ref } from "effect";
+import { Context, Effect, Layer } from "effect";
 //#region src/substrate/runtime/strategy-registry/service.ts
-var StrategyRegistryService = class extends Context.Service()("@devstack-rewrite/substrate/StrategyRegistry") {};
+var StrategyRegistryService = class extends Context.Service()("@devstack/substrate/StrategyRegistry") {};
 /**
 * Layer. Constructed per-scope; the orchestrator hands the registry
 * to each plugin's acquire so contributions land on the right
 * stack's registry, not a global one.
 */
 const layerStrategyRegistry = Layer.effect(StrategyRegistryService, Effect.gen(function* () {
-	const state = yield* Ref.make(/* @__PURE__ */ new Map());
-	const seqRef = yield* Ref.make(0);
+	const store = yield* makeScopedMultimap();
 	const register = (key, strategy, options) => Effect.gen(function* () {
-		const seq = yield* Ref.updateAndGet(seqRef, (n) => n + 1);
 		const entry = {
 			strategy,
 			autoMounted: options?.autoMounted ?? false,
-			priority: options?.priority ?? 0,
-			seq
+			priority: options?.priority ?? 0
 		};
-		yield* Ref.update(state, (current) => {
-			const existing = current.get(key) ?? [];
-			const next = new Map(current);
-			next.set(key, [...existing, entry]);
-			return next;
-		});
-		yield* Effect.addFinalizer((_exit) => Ref.update(state, (current) => {
-			const existing = current.get(key);
-			if (!existing) return current;
-			const filtered = existing.filter((e) => e.seq !== seq);
-			const next = new Map(current);
-			if (filtered.length === 0) next.delete(key);
-			else next.set(key, filtered);
-			return next;
-		}));
+		yield* store.register([{
+			key,
+			value: entry
+		}]);
 		yield* Effect.annotateCurrentSpan({
-			"strategy.key": key,
-			"strategy.autoMounted": entry.autoMounted
+			[SpanAttr.strategyKey]: key,
+			[SpanAttr.strategyAutoMounted]: entry.autoMounted
 		});
 	}).pipe(Effect.withSpan("substrate.strategyRegistry.register"));
 	const get = (key) => Effect.gen(function* () {
-		const current = yield* Ref.get(state);
-		const entries = current.get(key);
-		if (!entries || entries.length === 0) return yield* new StrategyNotFoundError({
+		const entries = yield* store.entriesFor(key);
+		if (entries.length === 0) return yield* new StrategyNotFoundError({
 			capabilityKey: key,
-			registeredKeys: [...current.keys()]
+			registeredKeys: yield* store.keys
 		});
 		let best = entries[0];
 		for (let i = 1; i < entries.length; i++) {
 			const e = entries[i];
-			if (e.priority > best.priority || e.priority === best.priority && e.seq > best.seq) best = e;
+			if (e.value.priority > best.value.priority || e.value.priority === best.value.priority && e.seq > best.seq) best = e;
 		}
-		return best.strategy;
+		return best.value.strategy;
 	}).pipe(Effect.withSpan("substrate.strategyRegistry.get", { attributes: { key } }));
-	const list = () => Effect.gen(function* () {
-		return [...(yield* Ref.get(state)).keys()];
-	});
+	const list = () => store.keys;
 	return StrategyRegistryService.of({
 		get,
 		register,