@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/api/inference-network.d.mts

@@ -0,0 +1,132 @@
+import { Effect } from "effect";
+
+//#region src/api/inference-network.d.ts
+/** Canonical default stack name (`'main'`). Single source of truth lives
+ *  in the discovery ladder's `DEFAULT_DISCOVERY_STACK`; re-exported here
+ *  (and from the vitest env module) so all entry points agree on one
+ *  literal. */
+declare const DEFAULT_STACK_NAME = "main";
+interface StackNameResolutionOptions {
+  readonly explicit?: string;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly cwd?: string;
+  readonly defaultName?: string;
+}
+interface AppNameResolutionOptions {
+  readonly explicit?: string;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly cwd?: string;
+  readonly defaultName?: string;
+}
+declare const resolveStackName: (options?: StackNameResolutionOptions) => string;
+declare const resolveAppName: (options?: AppNameResolutionOptions) => string;
+declare const FORK_DEVSTACK_NETWORK_NAMES: readonly ["testnet-fork", "mainnet-fork", "devnet-fork"];
+declare const DEVSTACK_NETWORK_NAMES: readonly ["localnet", "testnet", "mainnet", "devnet", "testnet-fork", "mainnet-fork", "devnet-fork"];
+type ForkDevstackNetworkName = (typeof FORK_DEVSTACK_NETWORK_NAMES)[number];
+type DevstackNetworkName = (typeof DEVSTACK_NETWORK_NAMES)[number];
+type LiveDevstackNetworkName = 'testnet' | 'mainnet' | 'devnet';
+type ParsedDevstackNetwork = {
+  readonly mode: 'local';
+  readonly name: 'localnet';
+} | {
+  readonly mode: 'live';
+  readonly name: LiveDevstackNetworkName;
+  readonly network: LiveDevstackNetworkName;
+} | {
+  readonly mode: 'fork';
+  readonly name: ForkDevstackNetworkName;
+  readonly upstream: LiveDevstackNetworkName;
+};
+declare class DevstackNetworkParseError extends Error {
+  readonly _tag = "DevstackNetworkParseError";
+  readonly value: string;
+  readonly source: string;
+  readonly supported: ReadonlyArray<DevstackNetworkName>;
+  constructor(args: {
+    readonly value: string;
+    readonly source: string;
+  });
+}
+declare const parseDevstackNetwork: (value: string | undefined, source?: string) => ParsedDevstackNetwork;
+declare const parseDevstackNetworkName: (value: string | undefined, source?: string) => DevstackNetworkName;
+/**
+ * Options for `resolveNetwork`. `explicit` is the caller-supplied
+ * override (typically a CLI flag or programmatic option). `env` is the
+ * environment value (typically `process.env.DEVSTACK_NETWORK`).
+ * `defaultName` is the final fallback when both miss. The precedence is
+ * explicit > env > default. The `source` string is embedded in the
+ * parse error's `source` field so the diagnosis names the offending
+ * input (e.g. `--network` vs `DEVSTACK_NETWORK`).
+ */
+interface ResolveNetworkOptions {
+  readonly explicit?: string | undefined;
+  readonly env?: string | undefined;
+  readonly defaultName?: string;
+  readonly explicitSource?: string;
+  readonly envSource?: string;
+}
+/** Default value when neither caller nor env provides one. Kept as a
+ *  string (not a `ParsedDevstackNetwork`) because every call site folds
+ *  it through `parseDevstackNetwork` first — keeping the default in the
+ *  same lookup table the env value flows through avoids two source-of-
+ *  truth shapes for "what is the default network?". */
+declare const DEFAULT_DEVSTACK_NETWORK: "sui:local";
+/**
+ * Result shape — both the typed parse AND the original input string the
+ * resolver picked. Consumers that thread the value through chain-keyed
+ * caches (the substrate folds chain id into cache namespaces) MUST keep
+ * the raw form to preserve existing on-disk cache keys; consumers that
+ * branch on mode (local/live/fork) read `parsed`.
+ */
+interface ResolvedDevstackNetwork {
+  readonly raw: string;
+  readonly parsed: ParsedDevstackNetwork;
+}
+/**
+ * Resolve a network from the canonical explicit > env > default ladder
+ * and parse the winning value through `parseDevstackNetwork`. Returns
+ * the typed parse alongside the raw input the resolver picked. A
+ * malformed value surfaces as `DevstackNetworkParseError` on the
+ * failure channel so CLI / library boot fail fast with a structured
+ * error rather than a downstream cryptic message.
+ *
+ * Used by both `api/run-stack.ts` (library embedding) and the CLI
+ * identity resolver so the two paths share one precedence rule + one
+ * parse error type.
+ */
+declare const resolveNetwork: (options?: ResolveNetworkOptions) => Effect.Effect<ResolvedDevstackNetwork, DevstackNetworkParseError>;
+/**
+ * Sync sibling of `resolveNetwork` for entry points that aren't running
+ * inside an Effect (the CLI identity resolver builds a plain TS record).
+ * Throws `DevstackNetworkParseError` on bad input — caller's job to lift
+ * into a typed failure channel if needed.
+ */
+declare const resolveNetworkSync: (options?: ResolveNetworkOptions) => ResolvedDevstackNetwork;
+interface ResolveStateDirOptions {
+  /** Caller-supplied `runtimeRoot` override (the canonical
+   *  `RunStackOptions.runtimeRoot` / CLI `--state-dir` field). Wins
+   *  over every other input. */
+  readonly runtimeRoot?: string;
+  /** Caller-supplied `stateDir` override (the
+   *  `DevstackOptions.stateDir` field on `defineDevstack(...)`).
+   *  Lower precedence than `runtimeRoot`. */
+  readonly stateDir?: string;
+  /** Env-var value (typically `process.env.DEVSTACK_STATE_DIR`).
+   *  Lower precedence than either explicit override. */
+  readonly env?: string;
+  /** Working directory used for the `.devstack` fallback and for
+   *  resolving any relative override path. */
+  readonly cwd: string;
+}
+/**
+ * Resolve the substrate's on-disk runtime root using the canonical
+ * precedence ladder: `runtimeRoot` > `stateDir` > `env` > `<cwd>/.devstack`.
+ * Relative paths are resolved against `cwd`; absolute paths pass through.
+ *
+ * Shared by `runStack`, the CLI bin, and the build-integrations
+ * discover module so all three entry points agree on the same ladder.
+ */
+declare const resolveStateDir: (options: ResolveStateDirOptions) => string;
+//#endregion
+export { DEFAULT_DEVSTACK_NETWORK, DEFAULT_STACK_NAME, DEVSTACK_NETWORK_NAMES, DevstackNetworkName, DevstackNetworkParseError, ParsedDevstackNetwork, ResolveNetworkOptions, ResolveStateDirOptions, ResolvedDevstackNetwork, parseDevstackNetwork, parseDevstackNetworkName, resolveAppName, resolveNetwork, resolveNetworkSync, resolveStackName, resolveStateDir };
+//# sourceMappingURL=inference-network.d.mts.map

package/dist/api/inference-network.mjs

@@ -1,7 +1,18 @@
+import { DEFAULT_DISCOVERY_STACK } from "../build-integrations/runtime/resolve-discovery-env.mjs";
+import { Effect } from "effect";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 //#region src/api/inference-network.ts
-const DEFAULT_STACK_NAME = "main";
+/** Canonical default stack name (`'main'`). Single source of truth lives
+*  in the discovery ladder's `DEFAULT_DISCOVERY_STACK`; re-exported here
+*  (and from the vitest env module) so all entry points agree on one
+*  literal. */
+const DEFAULT_STACK_NAME = DEFAULT_DISCOVERY_STACK;
+/** Normalize a candidate name: trim, strip an `@scope/` prefix, then
+*  strip any leading non-alphanumeric run. Returns `undefined` for empty
+*  or whitespace-only input, and for inputs that normalize to an empty
+*  string. Shared by every inferred-name resolver so explicit / env /
+*  package paths all reject the same junk. */
 const usefulName = (value) => {
 	const trimmed = value?.trim();
 	if (trimmed === void 0 || trimmed.length === 0) return void 0;
@@ -26,24 +37,34 @@ const inferPackageNameFromCwd = (cwd = process.cwd()) => {
 		dir = parent;
 	}
 };
-const resolveStackName = (options = {}) => {
-	const explicit = usefulName(options.explicit);
+/** Shared `explicit > env > package > default` precedence ladder for the
+*  app/stack name resolvers. Each input is fed through `usefulName` so a
+*  whitespace-only or junk-prefixed value falls through to the next rung
+*  rather than poisoning identity. `envKey` is the environment variable
+*  whose value (under `env`) supplies the env rung. */
+const resolveInferredName = (params) => {
+	const explicit = usefulName(params.explicit);
 	if (explicit !== void 0) return explicit;
-	const fromEnv = usefulName((options.env ?? process.env).DEVSTACK_STACK);
+	const fromEnv = usefulName((params.env ?? process.env)[params.envKey]);
 	if (fromEnv !== void 0) return fromEnv;
-	const fromPackage = inferPackageNameFromCwd(options.cwd);
+	const fromPackage = inferPackageNameFromCwd(params.cwd);
 	if (fromPackage !== void 0) return fromPackage;
-	return options.defaultName ?? "main";
-};
-const resolveAppName = (options = {}) => {
-	const explicit = usefulName(options.explicit);
-	if (explicit !== void 0) return explicit;
-	const fromEnv = usefulName((options.env ?? process.env).DEVSTACK_APP);
-	if (fromEnv !== void 0) return fromEnv;
-	const fromPackage = inferPackageNameFromCwd(options.cwd);
-	if (fromPackage !== void 0) return fromPackage;
-	return options.defaultName ?? "devstack";
+	return params.defaultName;
 };
+const resolveStackName = (options = {}) => resolveInferredName({
+	explicit: options.explicit,
+	envKey: "DEVSTACK_STACK",
+	env: options.env,
+	cwd: options.cwd,
+	defaultName: options.defaultName ?? DEFAULT_STACK_NAME
+});
+const resolveAppName = (options = {}) => resolveInferredName({
+	explicit: options.explicit,
+	envKey: "DEVSTACK_APP",
+	env: options.env,
+	cwd: options.cwd,
+	defaultName: options.defaultName ?? "devstack"
+});
 const ACTIVE_DEVSTACK_NETWORK_NAMES = [
 	"localnet",
 	"testnet",
@@ -116,7 +137,75 @@ const parseDevstackNetwork = (value, source = "DEVSTACK_NETWORK") => {
 	}
 };
 const parseDevstackNetworkName = (value, source = "DEVSTACK_NETWORK") => parseDevstackNetwork(value, source).name;
+/** Default value when neither caller nor env provides one. Kept as a
+*  string (not a `ParsedDevstackNetwork`) because every call site folds
+*  it through `parseDevstackNetwork` first — keeping the default in the
+*  same lookup table the env value flows through avoids two source-of-
+*  truth shapes for "what is the default network?". */
+const DEFAULT_DEVSTACK_NETWORK = "sui:local";
+const pickInput = (options) => {
+	if (options.explicit !== void 0 && options.explicit.length > 0) return {
+		value: options.explicit,
+		source: options.explicitSource ?? "--network"
+	};
+	if (options.env !== void 0 && options.env.length > 0) return {
+		value: options.env,
+		source: options.envSource ?? "DEVSTACK_NETWORK"
+	};
+	return {
+		value: options.defaultName ?? "sui:local",
+		source: "default"
+	};
+};
+/**
+* Resolve a network from the canonical explicit > env > default ladder
+* and parse the winning value through `parseDevstackNetwork`. Returns
+* the typed parse alongside the raw input the resolver picked. A
+* malformed value surfaces as `DevstackNetworkParseError` on the
+* failure channel so CLI / library boot fail fast with a structured
+* error rather than a downstream cryptic message.
+*
+* Used by both `api/run-stack.ts` (library embedding) and the CLI
+* identity resolver so the two paths share one precedence rule + one
+* parse error type.
+*/
+const resolveNetwork = (options = {}) => Effect.try({
+	try: () => {
+		const { value, source } = pickInput(options);
+		return {
+			raw: value,
+			parsed: parseDevstackNetwork(value, source)
+		};
+	},
+	catch: (cause) => cause
+});
+/**
+* Sync sibling of `resolveNetwork` for entry points that aren't running
+* inside an Effect (the CLI identity resolver builds a plain TS record).
+* Throws `DevstackNetworkParseError` on bad input — caller's job to lift
+* into a typed failure channel if needed.
+*/
+const resolveNetworkSync = (options = {}) => {
+	const { value, source } = pickInput(options);
+	return {
+		raw: value,
+		parsed: parseDevstackNetwork(value, source)
+	};
+};
+/**
+* Resolve the substrate's on-disk runtime root using the canonical
+* precedence ladder: `runtimeRoot` > `stateDir` > `env` > `<cwd>/.devstack`.
+* Relative paths are resolved against `cwd`; absolute paths pass through.
+*
+* Shared by `runStack`, the CLI bin, and the build-integrations
+* discover module so all three entry points agree on the same ladder.
+*/
+const resolveStateDir = (options) => {
+	const pick = (options.runtimeRoot !== void 0 && options.runtimeRoot.length > 0 ? options.runtimeRoot : void 0) ?? (options.stateDir !== void 0 && options.stateDir.length > 0 ? options.stateDir : void 0) ?? (options.env !== void 0 && options.env.length > 0 ? options.env : void 0);
+	if (pick === void 0) return resolve(options.cwd, ".devstack");
+	return resolve(options.cwd, pick);
+};
 //#endregion
-export { DEFAULT_STACK_NAME, parseDevstackNetworkName, resolveAppName, resolveStackName };
+export { DEFAULT_DEVSTACK_NETWORK, DEFAULT_STACK_NAME, DEVSTACK_NETWORK_NAMES, DevstackNetworkParseError, inferPackageNameFromCwd, parseDevstackNetwork, parseDevstackNetworkName, readPackageName, resolveAppName, resolveNetwork, resolveNetworkSync, resolveStackName, resolveStateDir };
 
 //# sourceMappingURL=inference-network.mjs.map

package/dist/api/inference-network.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"inference-network.mjs","names":[],"sources":["../../src/api/inference-network.ts"],"sourcesContent":["import { readFileSync } from 'node:fs';\nimport { dirname, resolve } from 'node:path';\n\nexport const DEFAULT_STACK_NAME = 'main';\n\nexport interface StackNameResolutionOptions {\n\treadonly explicit?: string;\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\treadonly cwd?: string;\n\treadonly defaultName?: string;\n}\n\nexport interface AppNameResolutionOptions {\n\treadonly explicit?: string;\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\treadonly cwd?: string;\n\treadonly defaultName?: string;\n}\n\nconst usefulName = (value: string | undefined): string | undefined => {\n\tconst trimmed = value?.trim();\n\tif (trimmed === undefined || trimmed.length === 0) return undefined;\n\tconst unscoped = trimmed.replace(/^@[^/]+\\//, '').replace(/^[^a-zA-Z0-9]+/, '');\n\treturn unscoped.length > 0 ? unscoped : undefined;\n};\n\nexport const readPackageName = (dir: string): string | undefined => {\n\ttry {\n\t\tconst pkg = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8')) as {\n\t\t\treadonly name?: string;\n\t\t};\n\t\treturn typeof pkg.name === 'string' ? usefulName(pkg.name) : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n};\n\nexport const inferPackageNameFromCwd = (cwd: string = process.cwd()): string | undefined => {\n\tlet dir = resolve(cwd);\n\tfor (let i = 0; i < 32; i += 1) {\n\t\tconst name = readPackageName(dir);\n\t\tif (name !== undefined) return name;\n\t\tconst parent = dirname(dir);\n\t\tif (parent === dir) return undefined;\n\t\tdir = parent;\n\t}\n\treturn undefined;\n};\n\nexport const resolveStackName = (options: StackNameResolutionOptions = {}): string => {\n\tconst explicit = usefulName(options.explicit);\n\tif (explicit !== undefined) return explicit;\n\tconst env = options.env ?? process.env;\n\tconst fromEnv = usefulName(env.DEVSTACK_STACK);\n\tif (fromEnv !== undefined) return fromEnv;\n\tconst fromPackage = inferPackageNameFromCwd(options.cwd);\n\tif (fromPackage !== undefined) return fromPackage;\n\treturn options.defaultName ?? DEFAULT_STACK_NAME;\n};\n\nexport const resolveAppName = (options: AppNameResolutionOptions = {}): string => {\n\tconst explicit = usefulName(options.explicit);\n\tif (explicit !== undefined) return explicit;\n\tconst env = options.env ?? process.env;\n\tconst fromEnv = usefulName(env.DEVSTACK_APP);\n\tif (fromEnv !== undefined) return fromEnv;\n\tconst fromPackage = inferPackageNameFromCwd(options.cwd);\n\tif (fromPackage !== undefined) return fromPackage;\n\treturn options.defaultName ?? 'devstack';\n};\n\nexport const ACTIVE_DEVSTACK_NETWORK_NAMES = ['localnet', 'testnet', 'mainnet', 'devnet'] as const;\n\nexport const FORK_DEVSTACK_NETWORK_NAMES = ['testnet-fork', 'mainnet-fork', 'devnet-fork'] as const;\n\nexport const DEVSTACK_NETWORK_NAMES = [\n\t...ACTIVE_DEVSTACK_NETWORK_NAMES,\n\t...FORK_DEVSTACK_NETWORK_NAMES,\n] as const;\n\nexport type ActiveDevstackNetworkName = (typeof ACTIVE_DEVSTACK_NETWORK_NAMES)[number];\nexport type ForkDevstackNetworkName = (typeof FORK_DEVSTACK_NETWORK_NAMES)[number];\nexport type DevstackNetworkName = (typeof DEVSTACK_NETWORK_NAMES)[number];\nexport type LiveDevstackNetworkName = 'testnet' | 'mainnet' | 'devnet';\n\nexport type ParsedDevstackNetwork =\n\t| {\n\t\t\treadonly mode: 'local';\n\t\t\treadonly name: 'localnet';\n\t  }\n\t| {\n\t\t\treadonly mode: 'live';\n\t\t\treadonly name: LiveDevstackNetworkName;\n\t\t\treadonly network: LiveDevstackNetworkName;\n\t  }\n\t| {\n\t\t\treadonly mode: 'fork';\n\t\t\treadonly name: ForkDevstackNetworkName;\n\t\t\treadonly upstream: LiveDevstackNetworkName;\n\t  };\n\nconst NETWORK_ALIASES: Readonly<Record<string, DevstackNetworkName>> = {\n\tlocal: 'localnet',\n\tlocalnet: 'localnet',\n\t'sui:local': 'localnet',\n\t'sui:localnet': 'localnet',\n\ttestnet: 'testnet',\n\t'sui:testnet': 'testnet',\n\tmainnet: 'mainnet',\n\t'sui:mainnet': 'mainnet',\n\tdevnet: 'devnet',\n\t'sui:devnet': 'devnet',\n\t'testnet-fork': 'testnet-fork',\n\t'sui:testnet-fork': 'testnet-fork',\n\t'mainnet-fork': 'mainnet-fork',\n\t'sui:mainnet-fork': 'mainnet-fork',\n\t'devnet-fork': 'devnet-fork',\n\t'sui:devnet-fork': 'devnet-fork',\n};\n\nexport class DevstackNetworkParseError extends Error {\n\treadonly _tag = 'DevstackNetworkParseError';\n\treadonly value: string;\n\treadonly source: string;\n\treadonly supported: ReadonlyArray<DevstackNetworkName>;\n\n\tconstructor(args: { readonly value: string; readonly source: string }) {\n\t\tsuper(\n\t\t\t`${args.source} must be one of: ${DEVSTACK_NETWORK_NAMES.join(', ')} (got ${JSON.stringify(args.value)})`,\n\t\t);\n\t\tthis.name = 'DevstackNetworkParseError';\n\t\tthis.value = args.value;\n\t\tthis.source = args.source;\n\t\tthis.supported = DEVSTACK_NETWORK_NAMES;\n\t}\n}\n\nexport const parseDevstackNetwork = (\n\tvalue: string | undefined,\n\tsource = 'DEVSTACK_NETWORK',\n): ParsedDevstackNetwork => {\n\tconst raw = value?.trim();\n\tconst name = raw === undefined || raw.length === 0 ? 'localnet' : NETWORK_ALIASES[raw];\n\tif (name === undefined) {\n\t\tthrow new DevstackNetworkParseError({ value: raw ?? '', source });\n\t}\n\tswitch (name) {\n\t\tcase 'localnet':\n\t\t\treturn { mode: 'local', name };\n\t\tcase 'testnet':\n\t\tcase 'mainnet':\n\t\tcase 'devnet':\n\t\t\treturn { mode: 'live', name, network: name };\n\t\tcase 'testnet-fork':\n\t\tcase 'mainnet-fork':\n\t\tcase 'devnet-fork':\n\t\t\treturn {\n\t\t\t\tmode: 'fork',\n\t\t\t\tname,\n\t\t\t\tupstream: name.replace(/-fork$/, '') as LiveDevstackNetworkName,\n\t\t\t};\n\t}\n};\n\nexport const parseDevstackNetworkName = (\n\tvalue: string | undefined,\n\tsource = 'DEVSTACK_NETWORK',\n): DevstackNetworkName => parseDevstackNetwork(value, source).name;\n"],"mappings":";;;AAGA,MAAa,qBAAqB;AAgBlC,MAAM,cAAc,UAAkD;CACrE,MAAM,UAAU,OAAO,MAAM;AAC7B,KAAI,YAAY,KAAA,KAAa,QAAQ,WAAW,EAAG,QAAO,KAAA;CAC1D,MAAM,WAAW,QAAQ,QAAQ,aAAa,GAAG,CAAC,QAAQ,kBAAkB,GAAG;AAC/E,QAAO,SAAS,SAAS,IAAI,WAAW,KAAA;;AAGzC,MAAa,mBAAmB,QAAoC;AACnE,KAAI;EACH,MAAM,MAAM,KAAK,MAAM,aAAa,QAAQ,KAAK,eAAe,EAAE,OAAO,CAAC;AAG1E,SAAO,OAAO,IAAI,SAAS,WAAW,WAAW,IAAI,KAAK,GAAG,KAAA;SACtD;AACP;;;AAIF,MAAa,2BAA2B,MAAc,QAAQ,KAAK,KAAyB;CAC3F,IAAI,MAAM,QAAQ,IAAI;AACtB,MAAK,IAAI,IAAI,GAAG,IAAI,IAAI,KAAK,GAAG;EAC/B,MAAM,OAAO,gBAAgB,IAAI;AACjC,MAAI,SAAS,KAAA,EAAW,QAAO;EAC/B,MAAM,SAAS,QAAQ,IAAI;AAC3B,MAAI,WAAW,IAAK,QAAO,KAAA;AAC3B,QAAM;;;AAKR,MAAa,oBAAoB,UAAsC,EAAE,KAAa;CACrF,MAAM,WAAW,WAAW,QAAQ,SAAS;AAC7C,KAAI,aAAa,KAAA,EAAW,QAAO;CAEnC,MAAM,UAAU,YADJ,QAAQ,OAAO,QAAQ,KACJ,eAAe;AAC9C,KAAI,YAAY,KAAA,EAAW,QAAO;CAClC,MAAM,cAAc,wBAAwB,QAAQ,IAAI;AACxD,KAAI,gBAAgB,KAAA,EAAW,QAAO;AACtC,QAAO,QAAQ,eAAA;;AAGhB,MAAa,kBAAkB,UAAoC,EAAE,KAAa;CACjF,MAAM,WAAW,WAAW,QAAQ,SAAS;AAC7C,KAAI,aAAa,KAAA,EAAW,QAAO;CAEnC,MAAM,UAAU,YADJ,QAAQ,OAAO,QAAQ,KACJ,aAAa;AAC5C,KAAI,YAAY,KAAA,EAAW,QAAO;CAClC,MAAM,cAAc,wBAAwB,QAAQ,IAAI;AACxD,KAAI,gBAAgB,KAAA,EAAW,QAAO;AACtC,QAAO,QAAQ,eAAe;;AAG/B,MAAa,gCAAgC;CAAC;CAAY;CAAW;CAAW;CAAS;AAEzF,MAAa,8BAA8B;CAAC;CAAgB;CAAgB;CAAc;AAE1F,MAAa,yBAAyB,CACrC,GAAG,+BACH,GAAG,4BACH;AAuBD,MAAM,kBAAiE;CACtE,OAAO;CACP,UAAU;CACV,aAAa;CACb,gBAAgB;CAChB,SAAS;CACT,eAAe;CACf,SAAS;CACT,eAAe;CACf,QAAQ;CACR,cAAc;CACd,gBAAgB;CAChB,oBAAoB;CACpB,gBAAgB;CAChB,oBAAoB;CACpB,eAAe;CACf,mBAAmB;CACnB;AAED,IAAa,4BAAb,cAA+C,MAAM;CACpD,OAAgB;CAChB;CACA;CACA;CAEA,YAAY,MAA2D;AACtE,QACC,GAAG,KAAK,OAAO,mBAAmB,uBAAuB,KAAK,KAAK,CAAC,QAAQ,KAAK,UAAU,KAAK,MAAM,CAAC,GACvG;AACD,OAAK,OAAO;AACZ,OAAK,QAAQ,KAAK;AAClB,OAAK,SAAS,KAAK;AACnB,OAAK,YAAY;;;AAInB,MAAa,wBACZ,OACA,SAAS,uBACkB;CAC3B,MAAM,MAAM,OAAO,MAAM;CACzB,MAAM,OAAO,QAAQ,KAAA,KAAa,IAAI,WAAW,IAAI,aAAa,gBAAgB;AAClF,KAAI,SAAS,KAAA,EACZ,OAAM,IAAI,0BAA0B;EAAE,OAAO,OAAO;EAAI;EAAQ,CAAC;AAElE,SAAQ,MAAR;EACC,KAAK,WACJ,QAAO;GAAE,MAAM;GAAS;GAAM;EAC/B,KAAK;EACL,KAAK;EACL,KAAK,SACJ,QAAO;GAAE,MAAM;GAAQ;GAAM,SAAS;GAAM;EAC7C,KAAK;EACL,KAAK;EACL,KAAK,cACJ,QAAO;GACN,MAAM;GACN;GACA,UAAU,KAAK,QAAQ,UAAU,GAAG;GACpC;;;AAIJ,MAAa,4BACZ,OACA,SAAS,uBACgB,qBAAqB,OAAO,OAAO,CAAC"}
+{"version":3,"file":"inference-network.mjs","names":[],"sources":["../../src/api/inference-network.ts"],"sourcesContent":["import { readFileSync } from 'node:fs';\nimport { dirname, resolve } from 'node:path';\n\nimport { Effect } from 'effect';\n\nimport { DEFAULT_DISCOVERY_STACK } from '../build-integrations/runtime/resolve-discovery-env.ts';\n\n/** Canonical default stack name (`'main'`). Single source of truth lives\n *  in the discovery ladder's `DEFAULT_DISCOVERY_STACK`; re-exported here\n *  (and from the vitest env module) so all entry points agree on one\n *  literal. */\nexport const DEFAULT_STACK_NAME = DEFAULT_DISCOVERY_STACK;\n\nexport interface StackNameResolutionOptions {\n\treadonly explicit?: string;\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\treadonly cwd?: string;\n\treadonly defaultName?: string;\n}\n\nexport interface AppNameResolutionOptions {\n\treadonly explicit?: string;\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\treadonly cwd?: string;\n\treadonly defaultName?: string;\n}\n\n/** Normalize a candidate name: trim, strip an `@scope/` prefix, then\n *  strip any leading non-alphanumeric run. Returns `undefined` for empty\n *  or whitespace-only input, and for inputs that normalize to an empty\n *  string. Shared by every inferred-name resolver so explicit / env /\n *  package paths all reject the same junk. */\nconst usefulName = (value: string | undefined): string | undefined => {\n\tconst trimmed = value?.trim();\n\tif (trimmed === undefined || trimmed.length === 0) return undefined;\n\tconst unscoped = trimmed.replace(/^@[^/]+\\//, '').replace(/^[^a-zA-Z0-9]+/, '');\n\treturn unscoped.length > 0 ? unscoped : undefined;\n};\n\nexport const readPackageName = (dir: string): string | undefined => {\n\ttry {\n\t\tconst pkg = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8')) as {\n\t\t\treadonly name?: string;\n\t\t};\n\t\treturn typeof pkg.name === 'string' ? usefulName(pkg.name) : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n};\n\nexport const inferPackageNameFromCwd = (cwd: string = process.cwd()): string | undefined => {\n\tlet dir = resolve(cwd);\n\tfor (let i = 0; i < 32; i += 1) {\n\t\tconst name = readPackageName(dir);\n\t\tif (name !== undefined) return name;\n\t\tconst parent = dirname(dir);\n\t\tif (parent === dir) return undefined;\n\t\tdir = parent;\n\t}\n\treturn undefined;\n};\n\n/** Shared `explicit > env > package > default` precedence ladder for the\n *  app/stack name resolvers. Each input is fed through `usefulName` so a\n *  whitespace-only or junk-prefixed value falls through to the next rung\n *  rather than poisoning identity. `envKey` is the environment variable\n *  whose value (under `env`) supplies the env rung. */\nconst resolveInferredName = (params: {\n\treadonly explicit: string | undefined;\n\treadonly envKey: string;\n\treadonly env: Readonly<Record<string, string | undefined>> | undefined;\n\treadonly cwd: string | undefined;\n\treadonly defaultName: string;\n}): string => {\n\tconst explicit = usefulName(params.explicit);\n\tif (explicit !== undefined) return explicit;\n\tconst env = params.env ?? process.env;\n\tconst fromEnv = usefulName(env[params.envKey]);\n\tif (fromEnv !== undefined) return fromEnv;\n\tconst fromPackage = inferPackageNameFromCwd(params.cwd);\n\tif (fromPackage !== undefined) return fromPackage;\n\treturn params.defaultName;\n};\n\nexport const resolveStackName = (options: StackNameResolutionOptions = {}): string =>\n\tresolveInferredName({\n\t\texplicit: options.explicit,\n\t\tenvKey: 'DEVSTACK_STACK',\n\t\tenv: options.env,\n\t\tcwd: options.cwd,\n\t\tdefaultName: options.defaultName ?? DEFAULT_STACK_NAME,\n\t});\n\nexport const resolveAppName = (options: AppNameResolutionOptions = {}): string =>\n\tresolveInferredName({\n\t\texplicit: options.explicit,\n\t\tenvKey: 'DEVSTACK_APP',\n\t\tenv: options.env,\n\t\tcwd: options.cwd,\n\t\tdefaultName: options.defaultName ?? 'devstack',\n\t});\n\nexport const ACTIVE_DEVSTACK_NETWORK_NAMES = ['localnet', 'testnet', 'mainnet', 'devnet'] as const;\n\nexport const FORK_DEVSTACK_NETWORK_NAMES = ['testnet-fork', 'mainnet-fork', 'devnet-fork'] as const;\n\nexport const DEVSTACK_NETWORK_NAMES = [\n\t...ACTIVE_DEVSTACK_NETWORK_NAMES,\n\t...FORK_DEVSTACK_NETWORK_NAMES,\n] as const;\n\nexport type ActiveDevstackNetworkName = (typeof ACTIVE_DEVSTACK_NETWORK_NAMES)[number];\nexport type ForkDevstackNetworkName = (typeof FORK_DEVSTACK_NETWORK_NAMES)[number];\nexport type DevstackNetworkName = (typeof DEVSTACK_NETWORK_NAMES)[number];\nexport type LiveDevstackNetworkName = 'testnet' | 'mainnet' | 'devnet';\n\nexport type ParsedDevstackNetwork =\n\t| {\n\t\t\treadonly mode: 'local';\n\t\t\treadonly name: 'localnet';\n\t  }\n\t| {\n\t\t\treadonly mode: 'live';\n\t\t\treadonly name: LiveDevstackNetworkName;\n\t\t\treadonly network: LiveDevstackNetworkName;\n\t  }\n\t| {\n\t\t\treadonly mode: 'fork';\n\t\t\treadonly name: ForkDevstackNetworkName;\n\t\t\treadonly upstream: LiveDevstackNetworkName;\n\t  };\n\nconst NETWORK_ALIASES: Readonly<Record<string, DevstackNetworkName>> = {\n\tlocal: 'localnet',\n\tlocalnet: 'localnet',\n\t'sui:local': 'localnet',\n\t'sui:localnet': 'localnet',\n\ttestnet: 'testnet',\n\t'sui:testnet': 'testnet',\n\tmainnet: 'mainnet',\n\t'sui:mainnet': 'mainnet',\n\tdevnet: 'devnet',\n\t'sui:devnet': 'devnet',\n\t'testnet-fork': 'testnet-fork',\n\t'sui:testnet-fork': 'testnet-fork',\n\t'mainnet-fork': 'mainnet-fork',\n\t'sui:mainnet-fork': 'mainnet-fork',\n\t'devnet-fork': 'devnet-fork',\n\t'sui:devnet-fork': 'devnet-fork',\n};\n\nexport class DevstackNetworkParseError extends Error {\n\treadonly _tag = 'DevstackNetworkParseError';\n\treadonly value: string;\n\treadonly source: string;\n\treadonly supported: ReadonlyArray<DevstackNetworkName>;\n\n\tconstructor(args: { readonly value: string; readonly source: string }) {\n\t\tsuper(\n\t\t\t`${args.source} must be one of: ${DEVSTACK_NETWORK_NAMES.join(', ')} (got ${JSON.stringify(args.value)})`,\n\t\t);\n\t\tthis.name = 'DevstackNetworkParseError';\n\t\tthis.value = args.value;\n\t\tthis.source = args.source;\n\t\tthis.supported = DEVSTACK_NETWORK_NAMES;\n\t}\n}\n\nexport const parseDevstackNetwork = (\n\tvalue: string | undefined,\n\tsource = 'DEVSTACK_NETWORK',\n): ParsedDevstackNetwork => {\n\tconst raw = value?.trim();\n\tconst name = raw === undefined || raw.length === 0 ? 'localnet' : NETWORK_ALIASES[raw];\n\tif (name === undefined) {\n\t\tthrow new DevstackNetworkParseError({ value: raw ?? '', source });\n\t}\n\tswitch (name) {\n\t\tcase 'localnet':\n\t\t\treturn { mode: 'local', name };\n\t\tcase 'testnet':\n\t\tcase 'mainnet':\n\t\tcase 'devnet':\n\t\t\treturn { mode: 'live', name, network: name };\n\t\tcase 'testnet-fork':\n\t\tcase 'mainnet-fork':\n\t\tcase 'devnet-fork':\n\t\t\treturn {\n\t\t\t\tmode: 'fork',\n\t\t\t\tname,\n\t\t\t\tupstream: name.replace(/-fork$/, '') as LiveDevstackNetworkName,\n\t\t\t};\n\t}\n};\n\nexport const parseDevstackNetworkName = (\n\tvalue: string | undefined,\n\tsource = 'DEVSTACK_NETWORK',\n): DevstackNetworkName => parseDevstackNetwork(value, source).name;\n\n// ---------------------------------------------------------------------------\n// resolveNetwork — single precedence ladder for every entry point.\n// ---------------------------------------------------------------------------\n\n/**\n * Options for `resolveNetwork`. `explicit` is the caller-supplied\n * override (typically a CLI flag or programmatic option). `env` is the\n * environment value (typically `process.env.DEVSTACK_NETWORK`).\n * `defaultName` is the final fallback when both miss. The precedence is\n * explicit > env > default. The `source` string is embedded in the\n * parse error's `source` field so the diagnosis names the offending\n * input (e.g. `--network` vs `DEVSTACK_NETWORK`).\n */\nexport interface ResolveNetworkOptions {\n\treadonly explicit?: string | undefined;\n\treadonly env?: string | undefined;\n\treadonly defaultName?: string;\n\treadonly explicitSource?: string;\n\treadonly envSource?: string;\n}\n\n/** Default value when neither caller nor env provides one. Kept as a\n *  string (not a `ParsedDevstackNetwork`) because every call site folds\n *  it through `parseDevstackNetwork` first — keeping the default in the\n *  same lookup table the env value flows through avoids two source-of-\n *  truth shapes for \"what is the default network?\". */\nexport const DEFAULT_DEVSTACK_NETWORK = 'sui:local' as const;\n\n/**\n * Result shape — both the typed parse AND the original input string the\n * resolver picked. Consumers that thread the value through chain-keyed\n * caches (the substrate folds chain id into cache namespaces) MUST keep\n * the raw form to preserve existing on-disk cache keys; consumers that\n * branch on mode (local/live/fork) read `parsed`.\n */\nexport interface ResolvedDevstackNetwork {\n\treadonly raw: string;\n\treadonly parsed: ParsedDevstackNetwork;\n}\n\nconst pickInput = (\n\toptions: ResolveNetworkOptions,\n): { readonly value: string; readonly source: string } => {\n\tif (options.explicit !== undefined && options.explicit.length > 0) {\n\t\treturn { value: options.explicit, source: options.explicitSource ?? '--network' };\n\t}\n\tif (options.env !== undefined && options.env.length > 0) {\n\t\treturn { value: options.env, source: options.envSource ?? 'DEVSTACK_NETWORK' };\n\t}\n\treturn { value: options.defaultName ?? DEFAULT_DEVSTACK_NETWORK, source: 'default' };\n};\n\n/**\n * Resolve a network from the canonical explicit > env > default ladder\n * and parse the winning value through `parseDevstackNetwork`. Returns\n * the typed parse alongside the raw input the resolver picked. A\n * malformed value surfaces as `DevstackNetworkParseError` on the\n * failure channel so CLI / library boot fail fast with a structured\n * error rather than a downstream cryptic message.\n *\n * Used by both `api/run-stack.ts` (library embedding) and the CLI\n * identity resolver so the two paths share one precedence rule + one\n * parse error type.\n */\nexport const resolveNetwork = (\n\toptions: ResolveNetworkOptions = {},\n): Effect.Effect<ResolvedDevstackNetwork, DevstackNetworkParseError> =>\n\tEffect.try({\n\t\ttry: (): ResolvedDevstackNetwork => {\n\t\t\tconst { value, source } = pickInput(options);\n\t\t\treturn { raw: value, parsed: parseDevstackNetwork(value, source) };\n\t\t},\n\t\tcatch: (cause) => cause as DevstackNetworkParseError,\n\t});\n\n/**\n * Sync sibling of `resolveNetwork` for entry points that aren't running\n * inside an Effect (the CLI identity resolver builds a plain TS record).\n * Throws `DevstackNetworkParseError` on bad input — caller's job to lift\n * into a typed failure channel if needed.\n */\nexport const resolveNetworkSync = (\n\toptions: ResolveNetworkOptions = {},\n): ResolvedDevstackNetwork => {\n\tconst { value, source } = pickInput(options);\n\treturn { raw: value, parsed: parseDevstackNetwork(value, source) };\n};\n\n// ---------------------------------------------------------------------------\n// resolveStateDir — single precedence ladder for the on-disk runtime root.\n// ---------------------------------------------------------------------------\n\nexport interface ResolveStateDirOptions {\n\t/** Caller-supplied `runtimeRoot` override (the canonical\n\t *  `RunStackOptions.runtimeRoot` / CLI `--state-dir` field). Wins\n\t *  over every other input. */\n\treadonly runtimeRoot?: string;\n\t/** Caller-supplied `stateDir` override (the\n\t *  `DevstackOptions.stateDir` field on `defineDevstack(...)`).\n\t *  Lower precedence than `runtimeRoot`. */\n\treadonly stateDir?: string;\n\t/** Env-var value (typically `process.env.DEVSTACK_STATE_DIR`).\n\t *  Lower precedence than either explicit override. */\n\treadonly env?: string;\n\t/** Working directory used for the `.devstack` fallback and for\n\t *  resolving any relative override path. */\n\treadonly cwd: string;\n}\n\n/**\n * Resolve the substrate's on-disk runtime root using the canonical\n * precedence ladder: `runtimeRoot` > `stateDir` > `env` > `<cwd>/.devstack`.\n * Relative paths are resolved against `cwd`; absolute paths pass through.\n *\n * Shared by `runStack`, the CLI bin, and the build-integrations\n * discover module so all three entry points agree on the same ladder.\n */\nexport const resolveStateDir = (options: ResolveStateDirOptions): string => {\n\tconst pick =\n\t\t(options.runtimeRoot !== undefined && options.runtimeRoot.length > 0\n\t\t\t? options.runtimeRoot\n\t\t\t: undefined) ??\n\t\t(options.stateDir !== undefined && options.stateDir.length > 0\n\t\t\t? options.stateDir\n\t\t\t: undefined) ??\n\t\t(options.env !== undefined && options.env.length > 0 ? options.env : undefined);\n\tif (pick === undefined) return resolve(options.cwd, '.devstack');\n\treturn resolve(options.cwd, pick);\n};\n"],"mappings":"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"}

package/dist/api/plugin-errors.d.mts

@@ -0,0 +1,7 @@
+import { PluginErrorContribution } from "../substrate/plugin.mjs";
+
+//#region src/api/plugin-errors.d.ts
+declare const pluginErrorContributions: <Tags extends ReadonlyArray<string>>(errorTags: Tags, formatter?: PluginErrorContribution["formatter"]) => readonly [PluginErrorContribution];
+//#endregion
+export { pluginErrorContributions };
+//# sourceMappingURL=plugin-errors.d.mts.map

package/dist/api/run-stack.d.mts

@@ -2,8 +2,9 @@ import { SubscribableState } from "../substrate/projection.mjs";
 import { EngineEvent } from "../substrate/events.mjs";
 import { AnyPlugin } from "../substrate/plugin.mjs";
 import { Stack } from "./define-devstack.mjs";
+import { CapabilitySinksService } from "../substrate/runtime/capability-sinks/service.mjs";
 import { ProductionCodegenOptions } from "../orchestrators/runtime-composition.mjs";
-import { Cause, Effect, Layer, Stream, SubscriptionRef } from "effect";
+import { Cause, Context, Effect, Scope, Stream, SubscriptionRef } from "effect";
 
 //#region src/api/run-stack.d.ts
 /** Identity overrides for `runStack`. App and stack fall back through
@@ -23,12 +24,20 @@ interface RunStackOptions {
   readonly codegen?: Omit<ProductionCodegenOptions, 'appRoot'>;
   /** Filesystem root under which the substrate stores per-stack
    *  artifacts (cache, snapshots, manifest, projection, etc.).
-   *  Defaults to `$DEVSTACK_STATE_DIR` then `<cwd>/.devstack`. */
+   *  Precedence: `runtimeRoot` > `stateDir` (this option or
+   *  `DevstackOptions.stateDir` on the stack) > `$DEVSTACK_STATE_DIR`
+   *  > `<cwd>/.devstack`. */
   readonly runtimeRoot?: string;
-  /** Extra Layer composition. Reserved for plugin-author overlays
-   *  (e.g. custom `CapabilitySinks`, Logger) per ARCHITECTURE.md
-   *  § Plugin-author extension via Layer composition. */
-  readonly layers?: Layer.Layer<never>;
+  /** Sibling of `runtimeRoot` — the `DevstackOptions.stateDir` field
+   *  threaded through `runStack` so a stack-level default can be
+   *  overridden per-embedding without forcing every call site to
+   *  flip between `runtimeRoot` and `stateDir`. Same semantics as
+   *  `runtimeRoot`; lower precedence. */
+  readonly stateDir?: string;
+  /** Extend the plugin execution context after built-in plugin
+   *  services are installed. Use this for custom plugin-author
+   *  services, capability sinks, or logger overrides. */
+  readonly extendContext?: (ctx: Context.Context<never>) => Effect.Effect<Context.Context<never>, never, Scope.Scope | CapabilitySinksService>;
 }
 /** Boot error surfaced by `RunHandle.start`. Wraps the supervisor's
  *  startup failure tree for cascade-formatter rendering. */
@@ -47,9 +56,11 @@ interface RunHandle {
   /** Trigger graceful shutdown: enqueues `shutdown.requested` onto
    *  the supervisor's command channel, then awaits the fiber. */
   readonly stop: Effect.Effect<void, never, never>;
-  /** Resolve when the supervisor fiber exits. Always succeeds — any
-   *  errors surface via `start`. */
-  readonly awaitShutdown: Effect.Effect<void, never, never>;
+  /** Resolve when the supervisor fiber exits. Succeeds on a clean
+   *  shutdown; fails with the captured `Cause` if the supervisor died
+   *  mid-run after boot completed (e.g. a plugin scope finalizer
+   *  defect). Boot-time failures still surface via `start`. */
+  readonly awaitShutdown: Effect.Effect<void, unknown, never>;
   /** Tail of typed engine events from the supervisor's hub. The
    *  upstream is a `Queue.Dequeue`; consume via `Stream.run...`. */
   readonly events: Stream.Stream<EngineEvent, never, never>;

package/dist/api/run-stack.mjs

@@ -1,11 +1,14 @@
-import { appName, chainId, stackName } from "../substrate/brand.mjs";
 import { readStackEngine } from "./define-devstack.mjs";
-import { makeProjectionRef } from "../substrate/runtime/projection/state-ref.mjs";
-import { buildSubstrateLayers, superviseStackEffect } from "../substrate/runtime/run.mjs";
+import { appName, chainId, stackName } from "../substrate/brand.mjs";
+import "../substrate/runtime/capability-sinks/index.mjs";
+import { makeProjectionRefSync } from "../substrate/runtime/projection/state-ref.mjs";
+import "../substrate/runtime/index.mjs";
+import { buildSubstrateLayers, superviseStackEffect } from "../orchestrators/run.mjs";
 import { buildProductionOrchestratorSinks, buildProductionPostAcquireHook, layerProductionOrchestrators } from "../orchestrators/runtime-composition.mjs";
-import { extendBuiltInPluginContext, layerBuiltInPluginRuntime } from "../runtime/built-in-plugin-layers.mjs";
-import { resolveAppName, resolveStackName } from "./inference-network.mjs";
-import { Deferred, Effect, Exit, Fiber, Layer, Logger, Queue, Stream } from "effect";
+import { resolveCodegenOutput } from "../orchestrators/codegen/output-location.mjs";
+import { extendBuiltInPluginContext, layerBuiltInPluginRuntime } from "../orchestrators/built-in-plugin-layers.mjs";
+import { resolveAppName, resolveNetworkSync, resolveStackName, resolveStateDir } from "./inference-network.mjs";
+import { Cause, Deferred, Effect, Exit, Fiber, Layer, Logger, Queue, Ref, Stream } from "effect";
 //#region src/api/run-stack.ts
 const resolveIdentity = (stack, opts, cwd) => {
 	const app = resolveAppName({
@@ -16,19 +19,17 @@ const resolveIdentity = (stack, opts, cwd) => {
 		explicit: opts?.stack ?? stack.options.stackName,
 		cwd
 	});
-	const network = opts?.network ?? process.env.DEVSTACK_NETWORK ?? "sui:local";
+	const resolved = resolveNetworkSync({
+		explicit: opts?.network,
+		env: process.env.DEVSTACK_NETWORK,
+		explicitSource: "runStack({ identity.network })"
+	});
 	return {
 		app: appName(app),
 		stack: stackName(stackNameStr),
-		chain: chainId(network)
+		chain: chainId(resolved.raw)
 	};
 };
-const resolveRuntimeRoot = (override) => {
-	if (override !== void 0) return override;
-	const envRoot = process.env.DEVSTACK_STATE_DIR;
-	if (envRoot !== void 0 && envRoot.length > 0) return envRoot;
-	return `${process.cwd()}/.devstack`;
-};
 const toBootError = (cause) => ({
 	_tag: "BootError",
 	cause
@@ -54,7 +55,12 @@ const toBootError = (cause) => ({
 */
 const runStack = (stack, opts = {}) => {
 	const engineStack = readStackEngine(stack);
-	const runtimeRoot = resolveRuntimeRoot(opts.runtimeRoot);
+	const runtimeRoot = resolveStateDir({
+		runtimeRoot: opts.runtimeRoot,
+		stateDir: opts.stateDir ?? engineStack.options.stateDir,
+		env: process.env.DEVSTACK_STATE_DIR,
+		cwd: process.cwd()
+	});
 	const appRoot = opts.appRoot ?? process.cwd();
 	const identity = resolveIdentity(stack, opts.identity, appRoot);
 	const codegen = opts.codegen ?? engineStack.options.codegen;
@@ -63,46 +69,65 @@ const runStack = (stack, opts = {}) => {
 		members: engineStack.members,
 		options: engineStack.options
 	};
-	const state = Effect.runSync(makeProjectionRef());
+	const state = makeProjectionRefSync();
 	const bootDeferred = Effect.runSync(Deferred.make());
 	const stopRequested = Effect.runSync(Deferred.make());
 	const eventQueueRef = Effect.runSync(Deferred.make());
 	const fiberRef = Effect.runSync(Deferred.make());
+	const startClaim = Effect.runSync(Ref.make(false));
+	const midRunCauseRef = Effect.runSync(Ref.make(null));
+	const codegenOutput = resolveCodegenOutput({
+		appRoot,
+		effectiveStack: String(identity.stack),
+		homeStack: engineStack.options.stackName,
+		explicitOutputDir: codegen?.outputDir,
+		explicitStackSubdir: codegen?.stackSubdir ?? null
+	});
 	const substrate = layerProductionOrchestrators({ codegen: {
 		appRoot,
-		outputDir: codegen?.outputDir,
-		stackSubdir: codegen?.stackSubdir ?? null
+		outputDir: codegenOutput.outputDir,
+		stackSubdir: codegenOutput.stackSubdir
 	} }).pipe(Layer.provideMerge(buildSubstrateLayers(identity, runtimeRoot)));
 	const supervised = Effect.gen(function* () {
 		const orchestratorSinks = yield* buildProductionOrchestratorSinks();
 		yield* superviseStackEffect(supervisedStack, identity, state, {
 			orchestratorSinks,
 			postAcquireHook: yield* buildProductionPostAcquireHook({ extras: stack.options.extras }),
-			extendContext: extendBuiltInPluginContext,
+			extendContext: (ctx) => Effect.gen(function* () {
+				const builtInContext = yield* extendBuiltInPluginContext(ctx);
+				return opts.extendContext === void 0 ? builtInContext : yield* opts.extendContext(builtInContext);
+			}),
+			beforeInitialAcquire: (handle) => Effect.gen(function* () {
+				yield* Deferred.succeed(eventQueueRef, handle.events).pipe(Effect.catch(() => Effect.void));
+				yield* Effect.forkScoped(Effect.gen(function* () {
+					yield* Deferred.await(stopRequested);
+					yield* Queue.offer(handle.commands, { tag: "shutdown.requested" });
+				}));
+			}),
 			withinScope: (handle) => Effect.gen(function* () {
-				yield* Deferred.succeed(eventQueueRef, handle.events);
 				yield* Effect.forkScoped(Effect.gen(function* () {
 					const firstFailure = (yield* Effect.forEach(handle.graph.nodes, ([key]) => handle.registry.awaitReady(key).pipe(Effect.exit), { concurrency: "unbounded" })).find(Exit.isFailure);
 					if (firstFailure === void 0) yield* Deferred.succeed(bootDeferred, void 0);
 					else yield* Deferred.fail(bootDeferred, toBootError(firstFailure.cause));
 				}));
-				yield* Effect.forkScoped(Effect.gen(function* () {
-					yield* Deferred.await(stopRequested);
-					yield* Queue.offer(handle.commands, { tag: "shutdown.requested" });
-				}));
 			})
 		}).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));
 	});
 	const loggerLayer = Logger.layer([]);
-	const supervisedProgram = (opts.layers === void 0 ? supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer)) : supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer), Effect.provide(opts.layers))).pipe(Effect.catchCause((cause) => Deferred.fail(bootDeferred, toBootError(cause)).pipe(Effect.asVoid, Effect.catch(() => Effect.void))));
+	const supervisedProgram = supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer)).pipe(Effect.catchCause((cause) => Effect.gen(function* () {
+		const bootAlreadyCompleted = yield* Deferred.isDone(bootDeferred);
+		yield* Deferred.fail(bootDeferred, toBootError(cause)).pipe(Effect.asVoid, Effect.catch(() => Effect.void));
+		if (bootAlreadyCompleted) yield* Ref.set(midRunCauseRef, cause);
+		yield* Effect.logError(`devstack runStack: supervisor died\n${Cause.pretty(cause)}`);
+	})));
 	return {
-		start: Effect.gen(function* () {
-			if (!(yield* Deferred.isDone(fiberRef))) {
+		start: Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+			if (yield* Ref.modify(startClaim, (started) => started ? [false, true] : [true, true])) {
 				const fiber = yield* Effect.forkDetach(supervisedProgram);
 				yield* Deferred.succeed(fiberRef, fiber);
 			}
-			yield* Deferred.await(bootDeferred);
-		}),
+			yield* restore(Deferred.await(bootDeferred));
+		})),
 		stop: Effect.gen(function* () {
 			yield* Deferred.succeed(stopRequested, void 0).pipe(Effect.catch(() => Effect.void));
 			if (!(yield* Deferred.isDone(fiberRef))) return;
@@ -113,6 +138,8 @@ const runStack = (stack, opts = {}) => {
 			if (!(yield* Deferred.isDone(fiberRef))) return;
 			const fiber = yield* Deferred.await(fiberRef);
 			yield* Fiber.await(fiber);
+			const midRunCause = yield* Ref.get(midRunCauseRef);
+			if (midRunCause !== null) return yield* Effect.failCause(midRunCause);
 		}),
 		events: Stream.unwrap(Effect.gen(function* () {
 			const queue = yield* Deferred.await(eventQueueRef);