@mysten-incubation/devstack 0.2.0 → 0.4.0

package/dist/orchestrators/codegen/deployment-network-file.mjs

@@ -0,0 +1,130 @@
+import { CodegenRenderError } from "./errors.mjs";
+//#region src/orchestrators/codegen/deployment-network-file.ts
+/** Canonical directory (relative to the project root) committed per-network
+*  deployments live under — the convention the Vite plugin auto-discovers. */
+const DEPLOYMENTS_DIRNAME = "deployments";
+/** The header every emitted `deployments/<net>.ts` carries. Hand-editable —
+*  this is an authoring surface — so it is NOT marked auto-generated. */
+const HEADER = [
+	"// Committed per-network deployment for a real-network deploy.",
+	"//",
+	"// Emitted by `devstack dump-deployment --network <net>` from a resolved",
+	"// stack, then committed. Hand-editable: the `satisfies AppNetworkDeployment`",
+	"// type-checks it against this app declared packages + MVR placeholders, so a",
+	"// missing or mistyped id fails `tsc`. No dev `accounts` (those ride the",
+	"// runtime envelope, never the committed authoring surface)."
+].join("\n");
+const INDENT = "	";
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** A single-quoted TS string literal (prettier `singleQuote: true`). Falls
+*  back to a double-quoted literal only when the value itself contains a
+*  single quote but no double quote (prettier's own preference), else escapes
+*  within single quotes.
+*
+*  Escaping is derived from `JSON.stringify`, which already produces a valid
+*  double-quoted JS string literal for ANY input — escaping backslash, the
+*  double quote, and all control characters (newline, CR, tab, etc.) — so a
+*  `values`-channel blob with literal newlines (PEM/cert text, multi-line
+*  descriptions) can never emit an unterminated literal. The result is then
+*  rephrased into prettier's quote preference. `U+2028`/`U+2029` are valid in
+*  JS string literals (and `JSON.stringify` leaves them unescaped), but are
+*  escaped here defensively so the emitted file is robust under tools that
+*  treat them as line terminators. */
+const LINE_SEP = /* @__PURE__ */ new RegExp("\\u2028", "g");
+const PARA_SEP = /* @__PURE__ */ new RegExp("\\u2029", "g");
+const quote = (s) => {
+	const json = JSON.stringify(s).replace(LINE_SEP, "\\u2028").replace(PARA_SEP, "\\u2029");
+	if (s.includes("'") && !s.includes("\"")) return json;
+	return `'${json.slice(1, -1).replace(/\\"/g, "\"").replace(/'/g, "\\'")}'`;
+};
+const key = (k) => IDENT_RE.test(k) ? k : quote(k);
+/** Render a JSON value to a prettier-compatible, SINGLE-quoted TS literal at
+*  the given indent `depth`. The deployment value space is exactly JSON
+*  (strings/numbers/booleans/null/arrays/objects), so no function/bigint/
+*  symbol handling is needed. */
+const renderValue = (value, depth) => {
+	if (value === null) return "null";
+	const t = typeof value;
+	if (t === "string") return quote(value);
+	if (t === "number" || t === "boolean") return String(value);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		return `[\n${value.map((v) => INDENT.repeat(depth) + renderValue(v, depth + 1)).join(",\n")},\n${INDENT.repeat(depth - 1)}]`;
+	}
+	if (t === "object") {
+		const obj = value;
+		const keys = Object.keys(obj).sort();
+		if (keys.length === 0) return "{}";
+		return `{\n${keys.map((k) => `${INDENT.repeat(depth)}${key(k)}: ${renderValue(obj[k], depth + 1)}`).join(",\n")},\n${INDENT.repeat(depth - 1)}}`;
+	}
+	throw new CodegenRenderError({
+		emitterName: "dump-deployment",
+		outputPath: `${DEPLOYMENTS_DIRNAME}/<net>.ts`,
+		detail: `value of type ${t} is not JSON-serialisable`
+	});
+};
+/** The ordered, JSON-ish object the file body renders. Built explicitly (NOT a
+*  spread of the decoded unit) so the field order is stable and the dev-only
+*  `local` marker is dropped. Optional connection diagnostics are omitted when
+*  absent. `accounts` is structurally absent from `NetworkDeployment`, so it
+*  can never leak in.
+*
+*  Exported as the SHARED normalize seam: `dump-deployment --network`'s JSON
+*  `data` reflects this same shape (network re-derived from the arg, `local`
+*  dropped) so a `--json` consumer never sees a shape that diverges from the
+*  committed file actually written. */
+const deploymentBody = (network, unit) => {
+	const body = {
+		network,
+		rpc: unit.rpc
+	};
+	if (unit.chainId !== void 0) body.chainId = unit.chainId;
+	if (unit.faucet !== void 0) body.faucet = unit.faucet;
+	if (unit.graphql !== void 0) body.graphql = unit.graphql;
+	body.packages = unit.packages;
+	body.mvrOverrides = unit.mvrOverrides;
+	if (unit.values !== void 0) body.values = unit.values;
+	return body;
+};
+/**
+* Render a typed `deployments/<net>.ts` for `network` from its resolved
+* `NetworkDeployment` unit.
+*
+* `importPath` is the module specifier the emitted `import type` points at —
+* the app's generated `deployment.js` relative to the `deployments/` dir
+* (default `../src/generated/deployment.js`). Output is prettier-compatible
+* (tab indent, single quotes, trailing commas) so a prettier-on-write hook is
+* a no-op.
+*/
+const renderNetworkDeploymentFile = (network, unit, importPath = "../src/generated/deployment.js") => {
+	try {
+		const body = renderValue(deploymentBody(network, unit), 1);
+		return {
+			ok: true,
+			text: `${HEADER}
+
+import type { AppNetworkDeployment } from ${quote(importPath)};
+
+export const deployment = ${body} satisfies AppNetworkDeployment;
+`
+		};
+	} catch (cause) {
+		if (cause instanceof CodegenRenderError) return {
+			ok: false,
+			error: cause
+		};
+		return {
+			ok: false,
+			error: new CodegenRenderError({
+				emitterName: "dump-deployment",
+				outputPath: `${DEPLOYMENTS_DIRNAME}/${network}.ts`,
+				detail: "failed to render network deployment file",
+				cause
+			})
+		};
+	}
+};
+//#endregion
+export { DEPLOYMENTS_DIRNAME, deploymentBody, renderNetworkDeploymentFile };
+
+//# sourceMappingURL=deployment-network-file.mjs.map

package/dist/orchestrators/codegen/deployment-network-file.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-network-file.mjs","names":[],"sources":["../../../src/orchestrators/codegen/deployment-network-file.ts"],"sourcesContent":["// The typed per-network deployment file `dump-deployment --network <net>`\n// emits — a committed `deployments/<net>.ts` a prod build / dev serve loads.\n//\n// Unlike the boot-written `deployment.json` (the untyped multi-network\n// ENVELOPE), this is the SINGLE-network, hand-editable, type-checked authoring\n// surface: `export const deployment = {…} satisfies AppNetworkDeployment`. The\n// `satisfies` ties it to the app's strict generated `deployment.ts`, so a\n// missing/typo'd package id or MVR placeholder fails `tsc` against the app's\n// own `AppNetworkDeployment`.\n//\n// Sourced from one `networks.<net>` entry of the resolved envelope (the same\n// data `assembleDeployment` produces). The dev-only `accounts` are NOT part of\n// a `NetworkDeployment` (they live on the envelope), so they never appear here;\n// the `local` marker (a dev-stack flag) is also dropped — a committed\n// deployment is non-local by definition.\n//\n// This file is COMMITTED (not under `generated/`), so unlike the codegen\n// renderer (`format.ts`, double-quoted JSON literals in a prettier-IGNORED\n// tree) the output must be prettier-clean: SINGLE-quoted strings, tab indent,\n// trailing commas, sorted keys. A prettier-on-write hook is then a no-op.\n\nimport type { NetworkDeployment } from './deployment.ts';\nimport { CodegenRenderError } from './errors.ts';\n\n/** Canonical directory (relative to the project root) committed per-network\n *  deployments live under — the convention the Vite plugin auto-discovers. */\nexport const DEPLOYMENTS_DIRNAME = 'deployments';\n\n/** The header every emitted `deployments/<net>.ts` carries. Hand-editable —\n *  this is an authoring surface — so it is NOT marked auto-generated. */\nconst HEADER = [\n\t'// Committed per-network deployment for a real-network deploy.',\n\t'//',\n\t'// Emitted by `devstack dump-deployment --network <net>` from a resolved',\n\t'// stack, then committed. Hand-editable: the `satisfies AppNetworkDeployment`',\n\t'// type-checks it against this app declared packages + MVR placeholders, so a',\n\t'// missing or mistyped id fails `tsc`. No dev `accounts` (those ride the',\n\t'// runtime envelope, never the committed authoring surface).',\n].join('\\n');\n\nconst INDENT = '\\t';\nconst IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\n\n/** A single-quoted TS string literal (prettier `singleQuote: true`). Falls\n *  back to a double-quoted literal only when the value itself contains a\n *  single quote but no double quote (prettier's own preference), else escapes\n *  within single quotes.\n *\n *  Escaping is derived from `JSON.stringify`, which already produces a valid\n *  double-quoted JS string literal for ANY input — escaping backslash, the\n *  double quote, and all control characters (newline, CR, tab, etc.) — so a\n *  `values`-channel blob with literal newlines (PEM/cert text, multi-line\n *  descriptions) can never emit an unterminated literal. The result is then\n *  rephrased into prettier's quote preference. `U+2028`/`U+2029` are valid in\n *  JS string literals (and `JSON.stringify` leaves them unescaped), but are\n *  escaped here defensively so the emitted file is robust under tools that\n *  treat them as line terminators. */\n// JS line/paragraph separators: valid in string literals but treated as line\n// terminators by some tooling. Built from escape sequences so this SOURCE file\n// stays pure-ASCII (no raw separator bytes).\nconst LINE_SEP = new RegExp('\\\\u2028', 'g');\nconst PARA_SEP = new RegExp('\\\\u2029', 'g');\nconst quote = (s: string): string => {\n\t// `JSON.stringify` yields `\"…\"` with `\\\\`, `\\\"`, and all control chars\n\t// escaped; the body (sans surrounding quotes) is then a safe double-quoted\n\t// payload we can re-quote. Escape the JS line/paragraph separators too.\n\tconst json = JSON.stringify(s).replace(LINE_SEP, '\\\\u2028').replace(PARA_SEP, '\\\\u2029');\n\t// Prefer single quotes (prettier `singleQuote: true`). The JSON body escapes\n\t// `\"` as `\\\"`; to single-quote we unescape `\\\"` → `\"` and escape any literal\n\t// `'` instead. Keep the double-quoted form when the value has a single quote\n\t// but no double quote (prettier's own preference: fewer escapes).\n\tif (s.includes(\"'\") && !s.includes('\"')) return json;\n\tconst body = json.slice(1, -1).replace(/\\\\\"/g, '\"').replace(/'/g, \"\\\\'\");\n\treturn `'${body}'`;\n};\n\nconst key = (k: string): string => (IDENT_RE.test(k) ? k : quote(k));\n\n/** Render a JSON value to a prettier-compatible, SINGLE-quoted TS literal at\n *  the given indent `depth`. The deployment value space is exactly JSON\n *  (strings/numbers/booleans/null/arrays/objects), so no function/bigint/\n *  symbol handling is needed. */\nconst renderValue = (value: unknown, depth: number): string => {\n\tif (value === null) return 'null';\n\tconst t = typeof value;\n\tif (t === 'string') return quote(value as string);\n\tif (t === 'number' || t === 'boolean') return String(value);\n\tif (Array.isArray(value)) {\n\t\tif (value.length === 0) return '[]';\n\t\tconst inner = value.map((v) => INDENT.repeat(depth) + renderValue(v, depth + 1)).join(',\\n');\n\t\treturn `[\\n${inner},\\n${INDENT.repeat(depth - 1)}]`;\n\t}\n\tif (t === 'object') {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tconst keys = Object.keys(obj).sort();\n\t\tif (keys.length === 0) return '{}';\n\t\tconst lines = keys\n\t\t\t.map((k) => `${INDENT.repeat(depth)}${key(k)}: ${renderValue(obj[k], depth + 1)}`)\n\t\t\t.join(',\\n');\n\t\treturn `{\\n${lines},\\n${INDENT.repeat(depth - 1)}}`;\n\t}\n\t// `undefined` / symbol / function — not JSON. The deployment schema admits\n\t// only JSON, so this is unreachable for a schema-decoded unit; throw rather\n\t// than emit a broken file.\n\tthrow new CodegenRenderError({\n\t\temitterName: 'dump-deployment',\n\t\toutputPath: `${DEPLOYMENTS_DIRNAME}/<net>.ts`,\n\t\tdetail: `value of type ${t} is not JSON-serialisable`,\n\t});\n};\n\n/** The ordered, JSON-ish object the file body renders. Built explicitly (NOT a\n *  spread of the decoded unit) so the field order is stable and the dev-only\n *  `local` marker is dropped. Optional connection diagnostics are omitted when\n *  absent. `accounts` is structurally absent from `NetworkDeployment`, so it\n *  can never leak in.\n *\n *  Exported as the SHARED normalize seam: `dump-deployment --network`'s JSON\n *  `data` reflects this same shape (network re-derived from the arg, `local`\n *  dropped) so a `--json` consumer never sees a shape that diverges from the\n *  committed file actually written. */\nexport const deploymentBody = (\n\tnetwork: string,\n\tunit: NetworkDeployment,\n): Record<string, unknown> => {\n\tconst body: Record<string, unknown> = { network, rpc: unit.rpc };\n\tif (unit.chainId !== undefined) body.chainId = unit.chainId;\n\tif (unit.faucet !== undefined) body.faucet = unit.faucet;\n\tif (unit.graphql !== undefined) body.graphql = unit.graphql;\n\tbody.packages = unit.packages;\n\tbody.mvrOverrides = unit.mvrOverrides;\n\tif (unit.values !== undefined) body.values = unit.values;\n\treturn body;\n};\n\n/** Result of rendering — discriminated so the caller dispatches on `ok`\n *  without `instanceof` (STYLE_GUIDE §2). */\nexport type NetworkFileRenderResult =\n\t| { readonly ok: true; readonly text: string }\n\t| { readonly ok: false; readonly error: CodegenRenderError };\n\n/**\n * Render a typed `deployments/<net>.ts` for `network` from its resolved\n * `NetworkDeployment` unit.\n *\n * `importPath` is the module specifier the emitted `import type` points at —\n * the app's generated `deployment.js` relative to the `deployments/` dir\n * (default `../src/generated/deployment.js`). Output is prettier-compatible\n * (tab indent, single quotes, trailing commas) so a prettier-on-write hook is\n * a no-op.\n */\nexport const renderNetworkDeploymentFile = (\n\tnetwork: string,\n\tunit: NetworkDeployment,\n\timportPath = '../src/generated/deployment.js',\n): NetworkFileRenderResult => {\n\ttry {\n\t\tconst body = renderValue(deploymentBody(network, unit), 1);\n\t\tconst text = `${HEADER}\n\nimport type { AppNetworkDeployment } from ${quote(importPath)};\n\nexport const deployment = ${body} satisfies AppNetworkDeployment;\n`;\n\t\treturn { ok: true, text };\n\t} catch (cause) {\n\t\tif (cause instanceof CodegenRenderError) return { ok: false, error: cause };\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: new CodegenRenderError({\n\t\t\t\temitterName: 'dump-deployment',\n\t\t\t\toutputPath: `${DEPLOYMENTS_DIRNAME}/${network}.ts`,\n\t\t\t\tdetail: 'failed to render network deployment file',\n\t\t\t\tcause,\n\t\t\t}),\n\t\t};\n\t}\n};\n"],"mappings":";;;;AA0BA,MAAa,sBAAsB;;;AAInC,MAAM,SAAS;CACd;CACA;CACA;CACA;CACA;CACA;CACA;AACD,CAAC,CAAC,KAAK,IAAI;AAEX,MAAM,SAAS;AACf,MAAM,WAAW;;;;;;;;;;;;;;;AAmBjB,MAAM,2BAAW,IAAI,OAAO,WAAW,GAAG;AAC1C,MAAM,2BAAW,IAAI,OAAO,WAAW,GAAG;AAC1C,MAAM,SAAS,MAAsB;CAIpC,MAAM,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,UAAU,SAAS,CAAC,CAAC,QAAQ,UAAU,SAAS;CAKvF,IAAI,EAAE,SAAS,GAAG,KAAK,CAAC,EAAE,SAAS,IAAG,GAAG,OAAO;CAEhD,OAAO,IADM,KAAK,MAAM,GAAG,EAAE,CAAC,CAAC,QAAQ,QAAQ,IAAG,CAAC,CAAC,QAAQ,MAAM,KACpD,EAAE;AACjB;AAEA,MAAM,OAAO,MAAuB,SAAS,KAAK,CAAC,IAAI,IAAI,MAAM,CAAC;;;;;AAMlE,MAAM,eAAe,OAAgB,UAA0B;CAC9D,IAAI,UAAU,MAAM,OAAO;CAC3B,MAAM,IAAI,OAAO;CACjB,IAAI,MAAM,UAAU,OAAO,MAAM,KAAe;CAChD,IAAI,MAAM,YAAY,MAAM,WAAW,OAAO,OAAO,KAAK;CAC1D,IAAI,MAAM,QAAQ,KAAK,GAAG;EACzB,IAAI,MAAM,WAAW,GAAG,OAAO;EAE/B,OAAO,MADO,MAAM,KAAK,MAAM,OAAO,OAAO,KAAK,IAAI,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,KACrE,EAAE,KAAK,OAAO,OAAO,QAAQ,CAAC,EAAE;CAClD;CACA,IAAI,MAAM,UAAU;EACnB,MAAM,MAAM;EACZ,MAAM,OAAO,OAAO,KAAK,GAAG,CAAC,CAAC,KAAK;EACnC,IAAI,KAAK,WAAW,GAAG,OAAO;EAI9B,OAAO,MAHO,KACZ,KAAK,MAAM,GAAG,OAAO,OAAO,KAAK,IAAI,IAAI,CAAC,EAAE,IAAI,YAAY,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,CACjF,KAAK,KACU,EAAE,KAAK,OAAO,OAAO,QAAQ,CAAC,EAAE;CAClD;CAIA,MAAM,IAAI,mBAAmB;EAC5B,aAAa;EACb,YAAY,GAAG,oBAAoB;EACnC,QAAQ,iBAAiB,EAAE;CAC5B,CAAC;AACF;;;;;;;;;;;AAYA,MAAa,kBACZ,SACA,SAC6B;CAC7B,MAAM,OAAgC;EAAE;EAAS,KAAK,KAAK;CAAI;CAC/D,IAAI,KAAK,YAAY,KAAA,GAAW,KAAK,UAAU,KAAK;CACpD,IAAI,KAAK,WAAW,KAAA,GAAW,KAAK,SAAS,KAAK;CAClD,IAAI,KAAK,YAAY,KAAA,GAAW,KAAK,UAAU,KAAK;CACpD,KAAK,WAAW,KAAK;CACrB,KAAK,eAAe,KAAK;CACzB,IAAI,KAAK,WAAW,KAAA,GAAW,KAAK,SAAS,KAAK;CAClD,OAAO;AACR;;;;;;;;;;;AAkBA,MAAa,+BACZ,SACA,MACA,aAAa,qCACgB;CAC7B,IAAI;EACH,MAAM,OAAO,YAAY,eAAe,SAAS,IAAI,GAAG,CAAC;EAOzD,OAAO;GAAE,IAAI;GAAM,MAAA,GANH,OAAO;;4CAEmB,MAAM,UAAU,EAAE;;4BAElC,KAAK;;EAEP;CACzB,SAAS,OAAO;EACf,IAAI,iBAAiB,oBAAoB,OAAO;GAAE,IAAI;GAAO,OAAO;EAAM;EAC1E,OAAO;GACN,IAAI;GACJ,OAAO,IAAI,mBAAmB;IAC7B,aAAa;IACb,YAAY,GAAG,oBAAoB,GAAG,QAAQ;IAC9C,QAAQ;IACR;GACD,CAAC;EACF;CACD;AACD"}

package/dist/orchestrators/codegen/deployment-strict.mjs

@@ -0,0 +1,77 @@
+//#region src/orchestrators/codegen/deployment-strict.ts
+/** Output path (relative to the generated tree) of the emitted strict type. */
+const DEPLOYMENT_STRICT_OUTPUT_PATH = "deployment.ts";
+/** Render the app-specific strict deployment type from data. Pure +
+*  deterministic (stable key ordering), types-only output. */
+const renderDeploymentStrict = (input) => {
+	const { localNetworkName, packageNames, mvrPlaceholders, mvrTypeTags } = input;
+	const providedNetworks = [...new Set(input.providedNetworks)].filter((n) => n !== localNetworkName);
+	const packagesBody = packageNames.length > 0 ? packageNames.map((name) => `\treadonly ${JSON.stringify(name)}: { readonly id: string; readonly objects?: Record<string, string> };`).join("\n") : "	readonly [packageName: string]: never;";
+	const mvrPackagesBody = mvrPlaceholders.length > 0 ? mvrPlaceholders.map((mvr) => `\t\t\t${JSON.stringify(mvr)}: string;`).join("\n") : "			// (this app declares no MVR placeholders)";
+	const hasMvrTypes = mvrTypeTags.length > 0;
+	const mvrTypesBody = hasMvrTypes ? mvrTypeTags.map((tag) => `\t\t\t${JSON.stringify(tag)}: string;`).join("\n") : "";
+	const mvrTypesField = hasMvrTypes ? `\t\treadonly types: {\n${mvrTypesBody}\n\t\t} & { readonly [namedType: string]: string };` : `\t\treadonly types?: { readonly [namedType: string]: string };`;
+	const valueNamespaces = Object.keys(input.serviceValues).sort();
+	const hasServiceValues = valueNamespaces.length > 0;
+	const valuesBody = hasServiceValues ? valueNamespaces.map((ns) => {
+		const fields = Object.keys(input.serviceValues[ns]).sort().map((k) => `\t\t\t${JSON.stringify(k)}: ${input.serviceValues[ns][k]};`).join("\n");
+		return `\t\t${JSON.stringify(ns)}: {\n${fields}\n\t\t};`;
+	}).join("\n") : "";
+	return `// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.
+// Do not edit by hand — your changes will be overwritten by the next
+// \`devstack codegen\`. Apps consume codegen output; codegen output never
+// imports from devstack.
+//
+// The APP-SPECIFIC strict deployment type. A prod author writes a
+// \`deployments/<net>.ts\` that \`satisfies AppNetworkDeployment\` — the type
+// is exhaustive over this app's declared packages + MVR placeholders, so a
+// missing/typo'd id fails \`tsc\`. The live network set
+// (\`ProvidedNetwork\` / \`NETWORK_NAMES\`) is derived from the
+// \`deployments/*.ts\` filenames. Types-only — zero runtime — except the
+// \`NETWORK_NAMES\` literal tuple (for dapp-kit's typed \`switchNetwork\`).
+
+import type { NetworkDeployment } from './config-runtime.js';
+
+/** Exhaustive over THIS app's declared package names. */
+export interface AppPackages {
+${packagesBody}
+}
+
+/** The per-network shape a prod author hand-writes in
+ *  \`deployments/<net>.ts\`: a \`NetworkDeployment\` narrowed so \`packages\` is
+ *  exhaustive over this app's packages, \`mvrOverrides\` is the @mysten MVR
+ *  override surface (\`{ packages, types }\`) requiring every declared
+ *  \`@local/<slug>\` placeholder + named-type tag, and \`values\` requires every
+ *  service value namespace/key (when the app declares any). NO \`accounts\` —
+ *  dev accounts ride the runtime envelope, never the per-network authoring
+ *  surface. */
+export interface AppNetworkDeployment
+	extends Omit<NetworkDeployment, 'packages' | 'mvrOverrides' | 'values'> {
+	readonly packages: AppPackages;
+	readonly mvrOverrides: {
+		readonly packages: {
+${mvrPackagesBody}
+		} & { readonly [mvrPlaceholder: string]: string };
+${mvrTypesField}
+	};
+${hasServiceValues ? `\treadonly values: {\n${valuesBody}\n\t} & {\n\t\treadonly [namespace: string]: { readonly [key: string]: unknown };\n\t};` : `\treadonly values?: NetworkDeployment['values'];`}
+}
+
+/** The LIVE network names this app ships — the \`deployments/*.ts\` filenames
+ *  (local excluded). \`never\` when the app ships no committed deployments. */
+export type ProvidedNetwork = ${providedNetworks.length > 0 ? providedNetworks.map((n) => JSON.stringify(n)).join(" | ") : "never"};
+
+/** The committed per-network deployments map a prod build / dev serve loads.
+ *  Partial — an app need not ship every live network at once. */
+export type ProvidedDeployments = Partial<Record<ProvidedNetwork, AppNetworkDeployment>>;
+
+/** The full network-name set, local-first: \`[<local>, ...<provided>]\`.
+ *  dapp-kit's \`networks\` / \`switchNetwork\` type-check against this tuple
+ *  (D2). */
+export const NETWORK_NAMES = [${[localNetworkName, ...providedNetworks].map((n) => JSON.stringify(n)).join(", ")}] as const;
+`;
+};
+//#endregion
+export { DEPLOYMENT_STRICT_OUTPUT_PATH, renderDeploymentStrict };
+
+//# sourceMappingURL=deployment-strict.mjs.map

package/dist/orchestrators/codegen/deployment-strict.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-strict.mjs","names":[],"sources":["../../../src/orchestrators/codegen/deployment-strict.ts"],"sourcesContent":["// The APP-SPECIFIC strict deployment type — emitted as\n// `src/generated/deployment.ts`.\n//\n// Unlike `config-runtime.ts` (a verbatim constant string), THIS file is\n// RENDERED FROM DATA: it narrows the generic `NetworkDeployment` (from\n// `config-runtime.ts`) to exactly the package names + MVR placeholders the\n// app declares, and enumerates the live networks the app ships from the\n// `deployments/` directory filenames.\n//\n// Four exported types/values:\n//   - `AppPackages`           — exhaustive over THIS app's declared package\n//                               names.\n//   - `AppNetworkDeployment`  — the per-network shape a prod author hand-\n//                               writes in `deployments/<net>.ts`: a\n//                               `NetworkDeployment` with `packages: AppPackages`\n//                               and `mvrOverrides` requiring the declared\n//                               `@local/*` placeholder keys. NO `accounts`\n//                               (those ride the runtime envelope, dev-only).\n//   - `ProvidedNetwork`       — a union of the LIVE network names (the\n//                               `deployments/*.ts` filenames, local excluded);\n//                               `never` when none.\n//   - `ProvidedDeployments`   — `Partial<Record<ProvidedNetwork,\n//                               AppNetworkDeployment>>`.\n//   - `NETWORK_NAMES`         — a literal `as const` tuple\n//                               `[<localNetworkName>, ...<deployments files>]`\n//                               for dapp-kit's typed `switchNetwork` (D2).\n//\n// Types-only + zero runtime: on a clean clone (no `deployments/` dir) this is\n// the local network alone — `ProvidedNetwork = never`, `ProvidedDeployments`\n// empty — so `tsc` stays green.\n\n/** Input the renderer derives the strict types from. All values are\n *  CONFIG-known (no chain / no live resolution): the declared package names\n *  + MVR placeholders come from the `config.ts` aggregate bucket, the local\n *  network name from the sui binding, the live network names from the\n *  `deployments/*.ts` filenames. */\nexport interface DeploymentStrictInput {\n\t/** The local (dev-stack) network name — the sui binding's `network`\n\t *  field. Always the head of `NETWORK_NAMES`. */\n\treadonly localNetworkName: string;\n\t/** This app's declared package names (the `config.packages.<name>`\n\t *  keys), in stable order. */\n\treadonly packageNames: ReadonlyArray<string>;\n\t/** This app's declared MVR placeholders (the `@local/<slug>` keys an app\n\t *  feeds dapp-kit's `mvr.overrides.packages`), in stable order. */\n\treadonly mvrPlaceholders: ReadonlyArray<string>;\n\t/** This app's declared MVR `types` keys — fully-qualified\n\t *  `@local/<slug>::<module>::<Name>` named struct tags (the @mysten MVR\n\t *  `types` override surface), in stable order. Empty when the app declares\n\t *  no Move datatypes. Drives `AppNetworkDeployment.mvrOverrides.types`. */\n\treadonly mvrTypeTags: ReadonlyArray<string>;\n\t/** The LIVE network names — `deployments/*.ts` filenames (sans `.ts`),\n\t *  with the local network name excluded. Empty on a clean clone. */\n\treadonly providedNetworks: ReadonlyArray<string>;\n\t/** The structured SERVICE-VALUE channel: `values[namespace][key] = <tsType>`\n\t *  — every generic (non-sugar) config-binding the app's service plugins\n\t *  declare (deepbook ids/pools, walrus/seal endpoints, coin decimals +\n\t *  full coin type, package object captures). Drives a REQUIRED `values`\n\t *  shape on `AppNetworkDeployment` so a hand-written `deployments/<net>.ts`\n\t *  is compile-checked for every service value. Empty for a service-less\n\t *  (counter-style) app — then `values` stays optional/loose. */\n\treadonly serviceValues: Readonly<Record<string, Readonly<Record<string, string>>>>;\n}\n\n/** Output path (relative to the generated tree) of the emitted strict type. */\nexport const DEPLOYMENT_STRICT_OUTPUT_PATH = 'deployment.ts';\n\n/** Render the app-specific strict deployment type from data. Pure +\n *  deterministic (stable key ordering), types-only output. */\nexport const renderDeploymentStrict = (input: DeploymentStrictInput): string => {\n\tconst { localNetworkName, packageNames, mvrPlaceholders, mvrTypeTags } = input;\n\n\t// Defensive: the local network is the head of `NETWORK_NAMES` and is never a\n\t// committed/provided network, so drop it (and any duplicate) from\n\t// `providedNetworks` even if a caller passes it in. The source discovery\n\t// (`discoverProvidedNetworks`) already filters it, but a hand-supplied set\n\t// (tests, future callers) must not yield a duplicate `localnet` tuple element\n\t// or pollute the `ProvidedNetwork` union.\n\tconst providedNetworks = [...new Set(input.providedNetworks)].filter(\n\t\t(n) => n !== localNetworkName,\n\t);\n\n\t// `AppPackages` — exhaustive over the declared package names. Each entry\n\t// carries `{ id; objects? }`. An app with no packages still declares the\n\t// interface (empty), so `AppNetworkDeployment.packages` stays a concrete\n\t// type.\n\tconst packagesBody =\n\t\tpackageNames.length > 0\n\t\t\t? packageNames\n\t\t\t\t\t.map(\n\t\t\t\t\t\t(name) =>\n\t\t\t\t\t\t\t`\\treadonly ${JSON.stringify(name)}: { readonly id: string; readonly objects?: Record<string, string> };`,\n\t\t\t\t\t)\n\t\t\t\t\t.join('\\n')\n\t\t\t: '\\treadonly [packageName: string]: never;';\n\n\t// `mvrOverrides.packages` requires every declared `@local/<slug>` placeholder\n\t// key (resolved package id). The @mysten MVR override shape exactly:\n\t// `{ packages: Record<mvr, id>; types: Record<namedType, resolvedType> }`.\n\tconst mvrPackagesBody =\n\t\tmvrPlaceholders.length > 0\n\t\t\t? mvrPlaceholders.map((mvr) => `\\t\\t\\t${JSON.stringify(mvr)}: string;`).join('\\n')\n\t\t\t: '\\t\\t\\t// (this app declares no MVR placeholders)';\n\t// `mvrOverrides.types` is OPT-IN. When the app DECLARES named types, the\n\t// field is REQUIRED and exhaustively narrowed over the declared tags (a\n\t// hand-written `deployments/<net>.ts` must provide exactly those, valued by\n\t// the resolved `<packageId>::<module>::<Name>`), plus the permissive trailing\n\t// index. When NONE are declared, the field is OPTIONAL + loose so an app that\n\t// exposes no Move datatypes need not write a `types` block at all.\n\tconst hasMvrTypes = mvrTypeTags.length > 0;\n\tconst mvrTypesBody = hasMvrTypes\n\t\t? mvrTypeTags.map((tag) => `\\t\\t\\t${JSON.stringify(tag)}: string;`).join('\\n')\n\t\t: '';\n\tconst mvrTypesField = hasMvrTypes\n\t\t? `\\t\\treadonly types: {\\n${mvrTypesBody}\\n\\t\\t} & { readonly [namedType: string]: string };`\n\t\t: `\\t\\treadonly types?: { readonly [namedType: string]: string };`;\n\n\t// The structured `values` channel — required per service namespace/key with\n\t// its concrete TS type, so a hand-written deployment is compile-checked for\n\t// every service value (deepbook/coin/seal/walrus/package-objects). A\n\t// service-less app contributes nothing → `values` stays optional/loose.\n\tconst valueNamespaces = Object.keys(input.serviceValues).sort();\n\tconst hasServiceValues = valueNamespaces.length > 0;\n\tconst valuesBody = hasServiceValues\n\t\t? valueNamespaces\n\t\t\t\t.map((ns) => {\n\t\t\t\t\tconst keys = Object.keys(input.serviceValues[ns]!).sort();\n\t\t\t\t\tconst fields = keys\n\t\t\t\t\t\t.map((k) => `\\t\\t\\t${JSON.stringify(k)}: ${input.serviceValues[ns]![k]!};`)\n\t\t\t\t\t\t.join('\\n');\n\t\t\t\t\treturn `\\t\\t${JSON.stringify(ns)}: {\\n${fields}\\n\\t\\t};`;\n\t\t\t\t})\n\t\t\t\t.join('\\n')\n\t\t: '';\n\n\t// The emitted `values` field. With service values it is REQUIRED and\n\t// narrowed per namespace/key (a missing service value fails `tsc`), plus a\n\t// permissive trailing index so an app can carry extra namespaces. With NO\n\t// service values (a counter-style app) it stays OPTIONAL + loose so a\n\t// service-less clean clone stays `tsc`-green.\n\tconst valuesField = hasServiceValues\n\t\t? `\\treadonly values: {\\n${valuesBody}\\n\\t} & {\\n\\t\\treadonly [namespace: string]: { readonly [key: string]: unknown };\\n\\t};`\n\t\t: `\\treadonly values?: NetworkDeployment['values'];`;\n\n\t// `ProvidedNetwork` — the live (committed) network union; `never` when\n\t// the app ships none (a clean clone with no `deployments/` dir).\n\tconst providedUnion =\n\t\tprovidedNetworks.length > 0\n\t\t\t? providedNetworks.map((n) => JSON.stringify(n)).join(' | ')\n\t\t\t: 'never';\n\n\t// `NETWORK_NAMES` — `[<local>, ...<provided>]` as a literal tuple.\n\tconst networkNamesTuple = [localNetworkName, ...providedNetworks]\n\t\t.map((n) => JSON.stringify(n))\n\t\t.join(', ');\n\n\treturn `// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.\n// Do not edit by hand — your changes will be overwritten by the next\n// \\`devstack codegen\\`. Apps consume codegen output; codegen output never\n// imports from devstack.\n//\n// The APP-SPECIFIC strict deployment type. A prod author writes a\n// \\`deployments/<net>.ts\\` that \\`satisfies AppNetworkDeployment\\` — the type\n// is exhaustive over this app's declared packages + MVR placeholders, so a\n// missing/typo'd id fails \\`tsc\\`. The live network set\n// (\\`ProvidedNetwork\\` / \\`NETWORK_NAMES\\`) is derived from the\n// \\`deployments/*.ts\\` filenames. Types-only — zero runtime — except the\n// \\`NETWORK_NAMES\\` literal tuple (for dapp-kit's typed \\`switchNetwork\\`).\n\nimport type { NetworkDeployment } from './config-runtime.js';\n\n/** Exhaustive over THIS app's declared package names. */\nexport interface AppPackages {\n${packagesBody}\n}\n\n/** The per-network shape a prod author hand-writes in\n *  \\`deployments/<net>.ts\\`: a \\`NetworkDeployment\\` narrowed so \\`packages\\` is\n *  exhaustive over this app's packages, \\`mvrOverrides\\` is the @mysten MVR\n *  override surface (\\`{ packages, types }\\`) requiring every declared\n *  \\`@local/<slug>\\` placeholder + named-type tag, and \\`values\\` requires every\n *  service value namespace/key (when the app declares any). NO \\`accounts\\` —\n *  dev accounts ride the runtime envelope, never the per-network authoring\n *  surface. */\nexport interface AppNetworkDeployment\n\textends Omit<NetworkDeployment, 'packages' | 'mvrOverrides' | 'values'> {\n\treadonly packages: AppPackages;\n\treadonly mvrOverrides: {\n\t\treadonly packages: {\n${mvrPackagesBody}\n\t\t} & { readonly [mvrPlaceholder: string]: string };\n${mvrTypesField}\n\t};\n${valuesField}\n}\n\n/** The LIVE network names this app ships — the \\`deployments/*.ts\\` filenames\n *  (local excluded). \\`never\\` when the app ships no committed deployments. */\nexport type ProvidedNetwork = ${providedUnion};\n\n/** The committed per-network deployments map a prod build / dev serve loads.\n *  Partial — an app need not ship every live network at once. */\nexport type ProvidedDeployments = Partial<Record<ProvidedNetwork, AppNetworkDeployment>>;\n\n/** The full network-name set, local-first: \\`[<local>, ...<provided>]\\`.\n *  dapp-kit's \\`networks\\` / \\`switchNetwork\\` type-check against this tuple\n *  (D2). */\nexport const NETWORK_NAMES = [${networkNamesTuple}] as const;\n`;\n};\n"],"mappings":";;AAiEA,MAAa,gCAAgC;;;AAI7C,MAAa,0BAA0B,UAAyC;CAC/E,MAAM,EAAE,kBAAkB,cAAc,iBAAiB,gBAAgB;CAQzE,MAAM,mBAAmB,CAAC,GAAG,IAAI,IAAI,MAAM,gBAAgB,CAAC,CAAC,CAAC,QAC5D,MAAM,MAAM,gBACd;CAMA,MAAM,eACL,aAAa,SAAS,IACnB,aACC,KACC,SACA,cAAc,KAAK,UAAU,IAAI,EAAE,sEACrC,CAAC,CACA,KAAK,IAAI,IACV;CAKJ,MAAM,kBACL,gBAAgB,SAAS,IACtB,gBAAgB,KAAK,QAAQ,SAAS,KAAK,UAAU,GAAG,EAAE,UAAU,CAAC,CAAC,KAAK,IAAI,IAC/E;CAOJ,MAAM,cAAc,YAAY,SAAS;CACzC,MAAM,eAAe,cAClB,YAAY,KAAK,QAAQ,SAAS,KAAK,UAAU,GAAG,EAAE,UAAU,CAAC,CAAC,KAAK,IAAI,IAC3E;CACH,MAAM,gBAAgB,cACnB,0BAA0B,aAAa,uDACvC;CAMH,MAAM,kBAAkB,OAAO,KAAK,MAAM,aAAa,CAAC,CAAC,KAAK;CAC9D,MAAM,mBAAmB,gBAAgB,SAAS;CAClD,MAAM,aAAa,mBAChB,gBACC,KAAK,OAAO;EAEZ,MAAM,SADO,OAAO,KAAK,MAAM,cAAc,GAAI,CAAC,CAAC,KACjC,CAAC,CACjB,KAAK,MAAM,SAAS,KAAK,UAAU,CAAC,EAAE,IAAI,MAAM,cAAc,GAAG,CAAE,GAAI,EAAE,CAAC,CAC1E,KAAK,IAAI;EACX,OAAO,OAAO,KAAK,UAAU,EAAE,EAAE,OAAO,OAAO;CAChD,CAAC,CAAC,CACD,KAAK,IAAI,IACV;CAuBH,OAAO;;;;;;;;;;;;;;;;;EAiBN,aAAa;;;;;;;;;;;;;;;;EAgBb,gBAAgB;;EAEhB,cAAc;;EAnDK,mBACjB,yBAAyB,WAAW,2FACpC,mDAmDU;;;;;gCA9CZ,iBAAiB,SAAS,IACvB,iBAAiB,KAAK,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,IACzD,QAiDyC;;;;;;;;;gCA9CnB,CAAC,kBAAkB,GAAG,gBAAgB,CAAC,CAC/D,KAAK,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,CAC7B,KAAK,IAqDwC,EAAE;;AAElD"}

package/dist/orchestrators/codegen/deployment.d.mts

@@ -0,0 +1,63 @@
+import { Effect, FileSystem, Schema } from "effect";
+
+//#region src/orchestrators/codegen/deployment.d.ts
+/** Any JSON-serialisable value. The deployment round-trips through
+ *  `JSON.stringify` into the injected `__DEVSTACK_DEPLOYMENT__` global, so a
+ *  plugin live value carried in the generic `values` channel must be JSON. */
+type JsonValue = null | string | number | boolean | ReadonlyArray<JsonValue> | {
+  readonly [key: string]: JsonValue;
+};
+/** One network's full resolved deployment — the per-network UNIT of the
+ *  multi-network envelope. Carries the connection coordinates (`rpc` is the
+ *  load-bearing field the app reads synchronously at module load, plus
+ *  optional `chainId`/`faucet`/`graphql`) FLATTENED inline alongside the
+ *  on-chain ids/values for that network. The whole document is data — no
+ *  functions, no devstack imports — so it round-trips through JSON and a
+ *  `JSON.stringify` into a vite `define` global. */
+declare const NetworkDeploymentSchema: Schema.Struct<{
+  /** This network's name (the `networks.<name>` key it sits under).
+   *  Optional on input — the envelope key is authoritative, so the Vite
+   *  merge and the boot writer set it from the key; a hand-written
+   *  committed `deployments/<net>.ts` need not restate it. */
+  readonly network: Schema.optional<Schema.String>; /** Load-bearing — the RPC endpoint the app reads synchronously. */
+  readonly rpc: Schema.String;
+  readonly chainId: Schema.optional<Schema.String>;
+  readonly faucet: Schema.optional<Schema.NullOr<Schema.String>>;
+  readonly graphql: Schema.optional<Schema.NullOr<Schema.String>>;
+  /** Marks a LIVE LOCAL network (a `devstack up` stack). The deploy
+   *  filter (`command === 'build'`) drops these — a production bundle
+   *  ships only committed, non-local networks. Optional so a hand-written
+   *  committed `deployments/<net>.ts` omits it (treated as non-local). */
+  readonly local: Schema.optional<Schema.Boolean>;
+  /** Resolved package ids (+ object captures). Optional, default `{}`: a
+   *  network may have zero packages (a network-only stack, or a
+   *  hand-authored deploy file), and the boot writer always emits the key
+   *  anyway — defaulting keeps the injected blob well-formed so the app's
+   *  resolvers throw `DevstackConfigMissingError` rather than a raw
+   *  TypeError on a missing section. */
+  readonly packages: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly objects: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+  }>>>;
+  /** The @mysten MVR override surface an app feeds straight into dapp-kit's
+   *  `mvr.overrides`, for this network:
+   *    - `packages`: `@local/<slug>` → resolved package id.
+   *    - `types`:    `@local/<slug>::<module>::<Name>` → resolved
+   *                  `<packageId>::<module>::<Name>` (each KEY passes
+   *                  `isValidNamedType`, each VALUE a concrete struct tag).
+   *  Both maps optional-default `{}` (a network may declare no packages, and
+   *  an older injected unit / hand-written committed deployment may omit
+   *  `types`). */
+  readonly mvrOverrides: Schema.withDecodingDefaultKey<Schema.Struct<{
+    readonly packages: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly types: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>>;
+  }>>;
+  /** Generic resolver channel — `values[namespace][key]` carries
+   *  arbitrary live plugin JSON the typed fields above can't. Optional
+   *  so older deployment files (no `values`) still decode. */
+  readonly values: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<JsonValue, JsonValue, never, never>>>>;
+}>;
+type NetworkDeployment = typeof NetworkDeploymentSchema.Type;
+//#endregion
+export { NetworkDeployment };
+//# sourceMappingURL=deployment.d.mts.map

package/dist/orchestrators/codegen/deployment.mjs

@@ -0,0 +1,153 @@
+import { decodeJsonTextSync, decodeUnknownSync } from "../../substrate/runtime/runtime-decode.mjs";
+import { atomicWriteFile } from "../../substrate/runtime/atomic-write.mjs";
+import { Effect, Schema } from "effect";
+//#region src/orchestrators/codegen/deployment.ts
+/** The all-zero Sui object id used as the placeholder for an unresolved
+*  (stack-free) id. A committed `config.ts` resolver treats this value —
+*  and a missing id — identically: it THROWS `DevstackConfigMissingError`
+*  at access time (see `config-runtime.ts`). Apps never transact with it. */
+const UNRESOLVED_ID = "0x0000000000000000000000000000000000000000000000000000000000000000";
+/** One `packages.<name>` entry — the resolved package id plus any
+*  resolved object captures for that network. */
+const DeploymentPackageSchema = Schema.Struct({
+	id: Schema.String,
+	objects: Schema.optional(Schema.Record(Schema.String, Schema.String))
+});
+/** A JSON-serialisable value carried in the generic `values` channel.
+*  The whole deployment round-trips through `JSON.stringify` into the
+*  vite `define` global, so the value space is exactly JSON. */
+const DeploymentJsonSchema = Schema.suspend(() => Schema.Union([
+	Schema.Null,
+	Schema.String,
+	Schema.Number,
+	Schema.Boolean,
+	Schema.Array(DeploymentJsonSchema),
+	Schema.Record(Schema.String, DeploymentJsonSchema)
+]));
+/** The generic resolver channel: a two-level namespaced map of arbitrary
+*  JSON values a plugin contributes at boot and the committed `config.ts`
+*  reads back via `resolveValue(namespace, key)`. This is the open-ended
+*  sibling to the typed `network`/`networks`/`packages`/`mvrOverrides`
+*  fields — it carries the plugin live values the fixed
+*  channel can't (deepbook pool ids, coin types, walrus/seal endpoints). */
+const DeploymentValuesSchema = Schema.Record(Schema.String, Schema.Record(Schema.String, DeploymentJsonSchema));
+/** One network's full resolved deployment — the per-network UNIT of the
+*  multi-network envelope. Carries the connection coordinates (`rpc` is the
+*  load-bearing field the app reads synchronously at module load, plus
+*  optional `chainId`/`faucet`/`graphql`) FLATTENED inline alongside the
+*  on-chain ids/values for that network. The whole document is data — no
+*  functions, no devstack imports — so it round-trips through JSON and a
+*  `JSON.stringify` into a vite `define` global. */
+const NetworkDeploymentSchema = Schema.Struct({
+	/** This network's name (the `networks.<name>` key it sits under).
+	*  Optional on input — the envelope key is authoritative, so the Vite
+	*  merge and the boot writer set it from the key; a hand-written
+	*  committed `deployments/<net>.ts` need not restate it. */
+	network: Schema.optional(Schema.String),
+	/** Load-bearing — the RPC endpoint the app reads synchronously. */
+	rpc: Schema.String,
+	chainId: Schema.optional(Schema.String),
+	faucet: Schema.optional(Schema.NullOr(Schema.String)),
+	graphql: Schema.optional(Schema.NullOr(Schema.String)),
+	/** Marks a LIVE LOCAL network (a `devstack up` stack). The deploy
+	*  filter (`command === 'build'`) drops these — a production bundle
+	*  ships only committed, non-local networks. Optional so a hand-written
+	*  committed `deployments/<net>.ts` omits it (treated as non-local). */
+	local: Schema.optional(Schema.Boolean),
+	/** Resolved package ids (+ object captures). Optional, default `{}`: a
+	*  network may have zero packages (a network-only stack, or a
+	*  hand-authored deploy file), and the boot writer always emits the key
+	*  anyway — defaulting keeps the injected blob well-formed so the app's
+	*  resolvers throw `DevstackConfigMissingError` rather than a raw
+	*  TypeError on a missing section. */
+	packages: Schema.Record(Schema.String, DeploymentPackageSchema).pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+	/** The @mysten MVR override surface an app feeds straight into dapp-kit's
+	*  `mvr.overrides`, for this network:
+	*    - `packages`: `@local/<slug>` → resolved package id.
+	*    - `types`:    `@local/<slug>::<module>::<Name>` → resolved
+	*                  `<packageId>::<module>::<Name>` (each KEY passes
+	*                  `isValidNamedType`, each VALUE a concrete struct tag).
+	*  Both maps optional-default `{}` (a network may declare no packages, and
+	*  an older injected unit / hand-written committed deployment may omit
+	*  `types`). */
+	mvrOverrides: Schema.Struct({
+		packages: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+		types: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed({})))
+	}).pipe(Schema.withDecodingDefaultKey(Effect.succeed({
+		packages: {},
+		types: {}
+	}))),
+	/** Generic resolver channel — `values[namespace][key]` carries
+	*  arbitrary live plugin JSON the typed fields above can't. Optional
+	*  so older deployment files (no `values`) still decode. */
+	values: Schema.optional(DeploymentValuesSchema)
+});
+/** The injected multi-network ENVELOPE — every network this deployment
+*  supports, keyed by name, plus the default the app opens on. The single
+*  on-disk / injected shape: boot writes one (single-network) envelope, the
+*  Vite plugin merges live + committed envelopes, and the generated resolver
+*  reads it off `__DEVSTACK_DEPLOYMENT__`. */
+const DevstackDeploymentSchema = Schema.Struct({
+	/** The network the app opens on (a `networks.<name>` key). */
+	defaultNetwork: Schema.String,
+	networks: Schema.Record(Schema.String, NetworkDeploymentSchema),
+	/** DEV-only account name → address map. Accounts are a network-AGNOSTIC
+	*  dev concept (keypair gen needs no network), so they live at the
+	*  envelope level — NOT per-`NetworkDeployment`. They exist only when
+	*  running THROUGH devstack (dev serve); a real prod deployment carries
+	*  none. Optional, default `{}` (a hand-written committed envelope, or a
+	*  pure prod build, omits it). */
+	accounts: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed({})))
+});
+/** Failure reading or decoding a deployment file. */
+var DeploymentDecodeError = class extends Schema.TaggedErrorClass()("DeploymentDecodeError", {
+	source: Schema.String,
+	message: Schema.String,
+	cause: Schema.optional(Schema.Defect)
+}) {};
+/** Canonical filename of the per-stack deployment under
+*  `.devstack/stacks/<name>/`. */
+const DEPLOYMENT_FILENAME = "deployment.json";
+/** Write the deployment as pretty JSON. Idempotent at the byte level for
+*  identical input (sorted by the caller's assembly order). */
+const writeDeployment = (path, config) => Effect.gen(function* () {
+	const text = `${JSON.stringify(config, null, 2)}\n`;
+	yield* atomicWriteFile(path, new TextEncoder().encode(text), { mode: 420 }).pipe(Effect.mapError((cause) => new DeploymentDecodeError({
+		source: path,
+		message: "failed to write deployment",
+		cause
+	})));
+});
+/** Project a runtime-decode issue into the typed `DeploymentDecodeError`. */
+const mkDeploymentError = (issue) => new DeploymentDecodeError({
+	source: issue.source,
+	message: issue.message,
+	...issue.cause === void 0 ? {} : { cause: issue.cause }
+});
+/** Decode + validate a deployment from already-read JSON text. The single
+*  schema-decode seam every reader shares (the Vite plugin, the `dump-deployment`
+*  verb, the codegen verb) so the parse-and-validate decision lives in ONE
+*  place rather than each caller hand-rolling `JSON.parse`. Throws
+*  `DeploymentDecodeError` on malformed JSON or a shape that violates
+*  `DeploymentSchema`. */
+const decodeDeployment = (text) => decodeJsonTextSync(DevstackDeploymentSchema, text, {
+	source: DEPLOYMENT_FILENAME,
+	mkError: mkDeploymentError
+});
+/** Decode + validate a single per-network `NetworkDeployment` unit from an
+*  already-parsed object (a committed `deployments/<net>.ts` thunk's
+*  `deployment`). The Vite plugin's merge layer calls this on each committed
+*  thunk so a malformed committed deployment surfaces loudly at config-load
+*  (rather than silently injecting a broken network). Throws
+*  `DeploymentDecodeError` on a shape that violates `NetworkDeploymentSchema`.
+*  The caller overwrites `network`/`local` from the envelope key afterwards,
+*  so the unit's own `network` field is optional here. */
+const decodeNetworkDeployment = (value, source) => decodeUnknownSync(NetworkDeploymentSchema, value, {
+	source,
+	mkError: mkDeploymentError,
+	message: "committed deployment is not a valid NetworkDeployment"
+});
+//#endregion
+export { DEPLOYMENT_FILENAME, UNRESOLVED_ID, decodeDeployment, decodeNetworkDeployment, writeDeployment };
+
+//# sourceMappingURL=deployment.mjs.map

package/dist/orchestrators/codegen/deployment.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment.mjs","names":[],"sources":["../../../src/orchestrators/codegen/deployment.ts"],"sourcesContent":["// The deployment interchange file — the single source of on-chain ids.\n//\n// Stop treating on-chain ids as codegen OUTPUT. Treat them as loaded\n// CONFIG DATA. Codegen is a deterministic, stack-free function\n// `(Move source, deployment?) → generated`. Booting a stack's only new\n// job is to PRODUCE this file; the codegen verb READS it (or runs with\n// none); the vite plugin INJECTS it into the app build/dev server.\n//\n// Four authors/consumers, one shared schema:\n//   - WRITER:   `orchestrators/boot.ts` post-acquire assembles this from\n//               acquired plugin state and writes it to the gitignored\n//               `.devstack/stacks/<name>/deployment.json`.\n//   - READER:   the stack-free `devstack codegen` verb reads it via the\n//               optional `--config <file>` flag (absent ⇒ ids unresolved).\n//   - CONSUMER: the emitted `config-runtime.ts` resolver reads the same\n//               shape off the injected `__DEVSTACK_DEPLOYMENT__` global.\n//   - INJECTOR: the vite plugin reads the live file (dev) or committed\n//               per-network deployment files (prod, via the `deployments`\n//               option / `DEVSTACK_DEPLOYMENT_FILE`), MERGES them, and\n//               `define`s the global.\n//\n// The shape is a MULTI-NETWORK ENVELOPE: `{ defaultNetwork, networks }`.\n// Each `networks.<name>` entry is a `NetworkDeployment` — the id-half of\n// today's `config.ts` for that one network: rpc (+ chainId/faucet/graphql),\n// per-package ids (+ captured object ids), the MVR placeholder → id override\n// map an app feeds dapp-kit, and a generic `values` channel. Dev `accounts`\n// (name → address) live at the ENVELOPE level — they are network-agnostic\n// dev identities, not part of any per-network unit. A plain single-network dev stack produces an envelope\n// with exactly one entry (the live local network, `local: true`); a real\n// multi-network deployment keys several. The envelope is the uniform unit\n// the Vite plugin merges live (dev) + committed (prod) sources into.\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport { atomicWriteFile } from '../../substrate/runtime/atomic-write.ts';\nimport {\n\tdecodeJsonTextSync,\n\tdecodeUnknownSync,\n\ttype RuntimeDecodeIssue,\n} from '../../substrate/runtime/runtime-decode.ts';\n\n// -----------------------------------------------------------------------------\n// Sentinel — the all-zero id that marks an UNRESOLVED on-chain id.\n// -----------------------------------------------------------------------------\n\n/** The all-zero Sui object id used as the placeholder for an unresolved\n *  (stack-free) id. A committed `config.ts` resolver treats this value —\n *  and a missing id — identically: it THROWS `DevstackConfigMissingError`\n *  at access time (see `config-runtime.ts`). Apps never transact with it. */\nexport const UNRESOLVED_ID = '0x0000000000000000000000000000000000000000000000000000000000000000';\n\n/** True when `id` is absent or the all-zero sentinel — i.e. not a real\n *  resolved on-chain id. */\nexport const isUnresolvedId = (id: string | undefined | null): boolean =>\n\tid === undefined || id === null || id === UNRESOLVED_ID;\n\n// -----------------------------------------------------------------------------\n// JSON value space — the generic `values` channel carries exactly JSON.\n// -----------------------------------------------------------------------------\n\n/** Any JSON-serialisable value. The deployment round-trips through\n *  `JSON.stringify` into the injected `__DEVSTACK_DEPLOYMENT__` global, so a\n *  plugin live value carried in the generic `values` channel must be JSON. */\nexport type JsonValue =\n\t| null\n\t| string\n\t| number\n\t| boolean\n\t| ReadonlyArray<JsonValue>\n\t| { readonly [key: string]: JsonValue };\n\n// -----------------------------------------------------------------------------\n// Schema\n// -----------------------------------------------------------------------------\n\n/** One `packages.<name>` entry — the resolved package id plus any\n *  resolved object captures for that network. */\nexport const DeploymentPackageSchema = Schema.Struct({\n\tid: Schema.String,\n\tobjects: Schema.optional(Schema.Record(Schema.String, Schema.String)),\n});\n\n/** A JSON-serialisable value carried in the generic `values` channel.\n *  The whole deployment round-trips through `JSON.stringify` into the\n *  vite `define` global, so the value space is exactly JSON. */\n// Typed as `Schema.Codec<JsonValue>` (NOT `Schema.Schema<JsonValue>`): the\n// type-only `Schema<T>` widens `DecodingServices` to `unknown`, which would\n// poison every decoder of `DeploymentSchema`; `Codec<T>` defaults the decode/\n// encode services to `never`, matching the real (service-free) recursion.\nexport const DeploymentJsonSchema: Schema.Codec<JsonValue> = Schema.suspend(() =>\n\tSchema.Union([\n\t\tSchema.Null,\n\t\tSchema.String,\n\t\tSchema.Number,\n\t\tSchema.Boolean,\n\t\tSchema.Array(DeploymentJsonSchema),\n\t\tSchema.Record(Schema.String, DeploymentJsonSchema),\n\t]),\n) as Schema.Codec<JsonValue>;\n\n/** The generic resolver channel: a two-level namespaced map of arbitrary\n *  JSON values a plugin contributes at boot and the committed `config.ts`\n *  reads back via `resolveValue(namespace, key)`. This is the open-ended\n *  sibling to the typed `network`/`networks`/`packages`/`mvrOverrides`\n *  fields — it carries the plugin live values the fixed\n *  channel can't (deepbook pool ids, coin types, walrus/seal endpoints). */\nexport const DeploymentValuesSchema = Schema.Record(\n\tSchema.String,\n\tSchema.Record(Schema.String, DeploymentJsonSchema),\n);\n\n/** One network's full resolved deployment — the per-network UNIT of the\n *  multi-network envelope. Carries the connection coordinates (`rpc` is the\n *  load-bearing field the app reads synchronously at module load, plus\n *  optional `chainId`/`faucet`/`graphql`) FLATTENED inline alongside the\n *  on-chain ids/values for that network. The whole document is data — no\n *  functions, no devstack imports — so it round-trips through JSON and a\n *  `JSON.stringify` into a vite `define` global. */\nexport const NetworkDeploymentSchema = Schema.Struct({\n\t/** This network's name (the `networks.<name>` key it sits under).\n\t *  Optional on input — the envelope key is authoritative, so the Vite\n\t *  merge and the boot writer set it from the key; a hand-written\n\t *  committed `deployments/<net>.ts` need not restate it. */\n\tnetwork: Schema.optional(Schema.String),\n\t/** Load-bearing — the RPC endpoint the app reads synchronously. */\n\trpc: Schema.String,\n\tchainId: Schema.optional(Schema.String),\n\tfaucet: Schema.optional(Schema.NullOr(Schema.String)),\n\tgraphql: Schema.optional(Schema.NullOr(Schema.String)),\n\t/** Marks a LIVE LOCAL network (a `devstack up` stack). The deploy\n\t *  filter (`command === 'build'`) drops these — a production bundle\n\t *  ships only committed, non-local networks. Optional so a hand-written\n\t *  committed `deployments/<net>.ts` omits it (treated as non-local). */\n\tlocal: Schema.optional(Schema.Boolean),\n\t/** Resolved package ids (+ object captures). Optional, default `{}`: a\n\t *  network may have zero packages (a network-only stack, or a\n\t *  hand-authored deploy file), and the boot writer always emits the key\n\t *  anyway — defaulting keeps the injected blob well-formed so the app's\n\t *  resolvers throw `DevstackConfigMissingError` rather than a raw\n\t *  TypeError on a missing section. */\n\tpackages: Schema.Record(Schema.String, DeploymentPackageSchema).pipe(\n\t\tSchema.withDecodingDefaultKey(Effect.succeed({})),\n\t),\n\t/** The @mysten MVR override surface an app feeds straight into dapp-kit's\n\t *  `mvr.overrides`, for this network:\n\t *    - `packages`: `@local/<slug>` → resolved package id.\n\t *    - `types`:    `@local/<slug>::<module>::<Name>` → resolved\n\t *                  `<packageId>::<module>::<Name>` (each KEY passes\n\t *                  `isValidNamedType`, each VALUE a concrete struct tag).\n\t *  Both maps optional-default `{}` (a network may declare no packages, and\n\t *  an older injected unit / hand-written committed deployment may omit\n\t *  `types`). */\n\tmvrOverrides: Schema.Struct({\n\t\tpackages: Schema.Record(Schema.String, Schema.String).pipe(\n\t\t\tSchema.withDecodingDefaultKey(Effect.succeed({})),\n\t\t),\n\t\ttypes: Schema.Record(Schema.String, Schema.String).pipe(\n\t\t\tSchema.withDecodingDefaultKey(Effect.succeed({})),\n\t\t),\n\t}).pipe(Schema.withDecodingDefaultKey(Effect.succeed({ packages: {}, types: {} }))),\n\t/** Generic resolver channel — `values[namespace][key]` carries\n\t *  arbitrary live plugin JSON the typed fields above can't. Optional\n\t *  so older deployment files (no `values`) still decode. */\n\tvalues: Schema.optional(DeploymentValuesSchema),\n});\n\n/** The injected multi-network ENVELOPE — every network this deployment\n *  supports, keyed by name, plus the default the app opens on. The single\n *  on-disk / injected shape: boot writes one (single-network) envelope, the\n *  Vite plugin merges live + committed envelopes, and the generated resolver\n *  reads it off `__DEVSTACK_DEPLOYMENT__`. */\nexport const DevstackDeploymentSchema = Schema.Struct({\n\t/** The network the app opens on (a `networks.<name>` key). */\n\tdefaultNetwork: Schema.String,\n\tnetworks: Schema.Record(Schema.String, NetworkDeploymentSchema),\n\t/** DEV-only account name → address map. Accounts are a network-AGNOSTIC\n\t *  dev concept (keypair gen needs no network), so they live at the\n\t *  envelope level — NOT per-`NetworkDeployment`. They exist only when\n\t *  running THROUGH devstack (dev serve); a real prod deployment carries\n\t *  none. Optional, default `{}` (a hand-written committed envelope, or a\n\t *  pure prod build, omits it). */\n\taccounts: Schema.Record(Schema.String, Schema.String).pipe(\n\t\tSchema.withDecodingDefaultKey(Effect.succeed({})),\n\t),\n});\n\nexport type DevstackDeployment = typeof DevstackDeploymentSchema.Type;\nexport type NetworkDeployment = typeof NetworkDeploymentSchema.Type;\nexport type DeploymentPackage = typeof DeploymentPackageSchema.Type;\nexport type DeploymentValues = typeof DeploymentValuesSchema.Type;\n\n// -----------------------------------------------------------------------------\n// Error\n// -----------------------------------------------------------------------------\n\n/** Failure reading or decoding a deployment file. */\nexport class DeploymentDecodeError extends Schema.TaggedErrorClass<DeploymentDecodeError>()(\n\t'DeploymentDecodeError',\n\t{\n\t\tsource: Schema.String,\n\t\tmessage: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n// -----------------------------------------------------------------------------\n// Read / write helpers\n// -----------------------------------------------------------------------------\n\n/** Canonical filename of the per-stack deployment under\n *  `.devstack/stacks/<name>/`. */\nexport const DEPLOYMENT_FILENAME = 'deployment.json';\n\n/** Write the deployment as pretty JSON. Idempotent at the byte level for\n *  identical input (sorted by the caller's assembly order). */\nexport const writeDeployment = (\n\tpath: string,\n\tconfig: DevstackDeployment,\n): Effect.Effect<void, DeploymentDecodeError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst text = `${JSON.stringify(config, null, 2)}\\n`;\n\t\tconst bytes = new TextEncoder().encode(text);\n\t\t// Atomic temp+rename — the Vite plugin reads this file with a plain\n\t\t// `readFileSync` + `JSON.parse`, so a torn / partial write would surface\n\t\t// as a parse error. `atomicWriteFile` ensures the parent dir (the\n\t\t// deployment write may run before the manifest write) and fsyncs before\n\t\t// the rename, so readers only ever see a complete file.\n\t\tyield* atomicWriteFile(path, bytes, { mode: 0o644 }).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(cause) =>\n\t\t\t\t\tnew DeploymentDecodeError({ source: path, message: 'failed to write deployment', cause }),\n\t\t\t),\n\t\t);\n\t});\n\n/** Project a runtime-decode issue into the typed `DeploymentDecodeError`. */\nconst mkDeploymentError = (issue: RuntimeDecodeIssue): DeploymentDecodeError =>\n\tnew DeploymentDecodeError({\n\t\tsource: issue.source,\n\t\tmessage: issue.message,\n\t\t...(issue.cause === undefined ? {} : { cause: issue.cause }),\n\t});\n\n/** Decode + validate a deployment from already-read JSON text. The single\n *  schema-decode seam every reader shares (the Vite plugin, the `dump-deployment`\n *  verb, the codegen verb) so the parse-and-validate decision lives in ONE\n *  place rather than each caller hand-rolling `JSON.parse`. Throws\n *  `DeploymentDecodeError` on malformed JSON or a shape that violates\n *  `DeploymentSchema`. */\nexport const decodeDeployment = (text: string): DevstackDeployment =>\n\tdecodeJsonTextSync(DevstackDeploymentSchema, text, {\n\t\tsource: DEPLOYMENT_FILENAME,\n\t\tmkError: mkDeploymentError,\n\t});\n\n/** Decode + validate a single per-network `NetworkDeployment` unit from an\n *  already-parsed object (a committed `deployments/<net>.ts` thunk's\n *  `deployment`). The Vite plugin's merge layer calls this on each committed\n *  thunk so a malformed committed deployment surfaces loudly at config-load\n *  (rather than silently injecting a broken network). Throws\n *  `DeploymentDecodeError` on a shape that violates `NetworkDeploymentSchema`.\n *  The caller overwrites `network`/`local` from the envelope key afterwards,\n *  so the unit's own `network` field is optional here. */\nexport const decodeNetworkDeployment = (value: unknown, source: string): NetworkDeployment =>\n\tdecodeUnknownSync(NetworkDeploymentSchema, value, {\n\t\tsource,\n\t\tmkError: mkDeploymentError,\n\t\tmessage: 'committed deployment is not a valid NetworkDeployment',\n\t});\n"],"mappings":";;;;;;;;AAiDA,MAAa,gBAAgB;;;AA4B7B,MAAa,0BAA0B,OAAO,OAAO;CACpD,IAAI,OAAO;CACX,SAAS,OAAO,SAAS,OAAO,OAAO,OAAO,QAAQ,OAAO,MAAM,CAAC;AACrE,CAAC;;;;AASD,MAAa,uBAAgD,OAAO,cACnE,OAAO,MAAM;CACZ,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO,MAAM,oBAAoB;CACjC,OAAO,OAAO,OAAO,QAAQ,oBAAoB;AAClD,CAAC,CACF;;;;;;;AAQA,MAAa,yBAAyB,OAAO,OAC5C,OAAO,QACP,OAAO,OAAO,OAAO,QAAQ,oBAAoB,CAClD;;;;;;;;AASA,MAAa,0BAA0B,OAAO,OAAO;;;;;CAKpD,SAAS,OAAO,SAAS,OAAO,MAAM;;CAEtC,KAAK,OAAO;CACZ,SAAS,OAAO,SAAS,OAAO,MAAM;CACtC,QAAQ,OAAO,SAAS,OAAO,OAAO,OAAO,MAAM,CAAC;CACpD,SAAS,OAAO,SAAS,OAAO,OAAO,OAAO,MAAM,CAAC;;;;;CAKrD,OAAO,OAAO,SAAS,OAAO,OAAO;;;;;;;CAOrC,UAAU,OAAO,OAAO,OAAO,QAAQ,uBAAuB,CAAC,CAAC,KAC/D,OAAO,uBAAuB,OAAO,QAAQ,CAAC,CAAC,CAAC,CACjD;;;;;;;;;;CAUA,cAAc,OAAO,OAAO;EAC3B,UAAU,OAAO,OAAO,OAAO,QAAQ,OAAO,MAAM,CAAC,CAAC,KACrD,OAAO,uBAAuB,OAAO,QAAQ,CAAC,CAAC,CAAC,CACjD;EACA,OAAO,OAAO,OAAO,OAAO,QAAQ,OAAO,MAAM,CAAC,CAAC,KAClD,OAAO,uBAAuB,OAAO,QAAQ,CAAC,CAAC,CAAC,CACjD;CACD,CAAC,CAAC,CAAC,KAAK,OAAO,uBAAuB,OAAO,QAAQ;EAAE,UAAU,CAAC;EAAG,OAAO,CAAC;CAAE,CAAC,CAAC,CAAC;;;;CAIlF,QAAQ,OAAO,SAAS,sBAAsB;AAC/C,CAAC;;;;;;AAOD,MAAa,2BAA2B,OAAO,OAAO;;CAErD,gBAAgB,OAAO;CACvB,UAAU,OAAO,OAAO,OAAO,QAAQ,uBAAuB;;;;;;;CAO9D,UAAU,OAAO,OAAO,OAAO,QAAQ,OAAO,MAAM,CAAC,CAAC,KACrD,OAAO,uBAAuB,OAAO,QAAQ,CAAC,CAAC,CAAC,CACjD;AACD,CAAC;;AAYD,IAAa,wBAAb,cAA2C,OAAO,iBAAwC,CAAC,CAC1F,yBACA;CACC,QAAQ,OAAO;CACf,SAAS,OAAO;CAChB,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;;AAQH,MAAa,sBAAsB;;;AAInC,MAAa,mBACZ,MACA,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,GAAG,KAAK,UAAU,QAAQ,MAAM,CAAC,EAAE;CAOhD,OAAO,gBAAgB,MANT,IAAI,YAAY,CAAC,CAAC,OAAO,IAMN,GAAG,EAAE,MAAM,IAAM,CAAC,CAAC,CAAC,KACpD,OAAO,UACL,UACA,IAAI,sBAAsB;EAAE,QAAQ;EAAM,SAAS;EAA8B;CAAM,CAAC,CAC1F,CACD;AACD,CAAC;;AAGF,MAAM,qBAAqB,UAC1B,IAAI,sBAAsB;CACzB,QAAQ,MAAM;CACd,SAAS,MAAM;CACf,GAAI,MAAM,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,MAAM,MAAM;AAC3D,CAAC;;;;;;;AAQF,MAAa,oBAAoB,SAChC,mBAAmB,0BAA0B,MAAM;CAClD,QAAQ;CACR,SAAS;AACV,CAAC;;;;;;;;;AAUF,MAAa,2BAA2B,OAAgB,WACvD,kBAAkB,yBAAyB,OAAO;CACjD;CACA,SAAS;CACT,SAAS;AACV,CAAC"}

package/dist/orchestrators/codegen/errors.mjs

@@ -21,17 +21,15 @@ var CodegenEmitterCollision = class extends Schema.TaggedErrorClass()("CodegenEm
 	outputPaths: Schema.Array(Schema.String)
 }) {};
 /** Two `Codegenable` contributions target the SAME aggregate
-*  `bucket` but disagree on its routing/sensitivity metadata
-*  (`outputLocation` or `sensitive`). The `AggregateContribution`
-*  contract requires all contributors to a bucket to agree; the
-*  orchestrator routes the synthesized aggregate from the FIRST
-*  contributor it sees, so a silent disagreement could misroute a
-*  sensitive aggregate into the committed `generated` tree. Detected
-*  while folding contributions so the cycle fails fast rather than
-*  emitting a secret with non-sensitive handling. */
+*  `bucket` but disagree on its `sensitive` metadata. The
+*  `AggregateContribution` contract requires all contributors to a
+*  bucket to agree; the orchestrator takes the FIRST contributor's
+*  sensitivity, so a silent disagreement could emit a secret with
+*  non-sensitive handling. Detected while folding contributions so the
+*  cycle fails fast. */
 var CodegenAggregateConflict = class extends Schema.TaggedErrorClass()("CodegenAggregateConflict", {
 	bucket: Schema.String,
-	field: Schema.Literals(["outputLocation", "sensitive"]),
+	field: Schema.Literals(["sensitive"]),
 	/** The value the first contributor established for the bucket. */
 	established: Schema.String,
 	/** The conflicting value a later contributor declared. */

package/dist/orchestrators/codegen/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/orchestrators/codegen/errors.ts"],"sourcesContent":["// Typed errors for the Codegen orchestrator.\n//\n// A phase-tagged failure-mode taxonomy: \"emitter-collision at acquire\",\n// \"binary shell-out failure\", and \"pure render failure\" each get a\n// separate tag so callers can `catchTag` on each.\n//\n// Phase tags inside each error name the lifecycle step that failed\n// (resolve → emit → render → write → bindings → finalize) so error\n// attribution stays accurate.\n\nimport { Schema } from 'effect';\n\n/** Path-layer rejection from the codegen orchestrator.\n *  - `kind: 'duplicate'` — two `Codegenable` contributions claim the\n *    same `outputPath`. Hard failure detected BEFORE write so the\n *    user-visible output dir never sees an ambiguous overwrite.\n *  - `kind: 'non-relative'` — a plugin-authored `outputPath` escapes\n *    the codegen root (contains `..` or is absolute). Defense-in-depth\n *    for the file-layout invariants. */\nexport class CodegenPathConflict extends Schema.TaggedErrorClass<CodegenPathConflict>()(\n\t'CodegenPathConflict',\n\t{\n\t\tkind: Schema.Literals(['duplicate', 'non-relative']),\n\t\toutputPath: Schema.String,\n\t\temitters: Schema.Array(Schema.String),\n\t},\n) {}\n\n/** Two `Codegenable` contributions share the SAME `emitterName`\n *  literal but resolve to different `outputPath`s — programming\n *  bug in plugin code (emitter name should be unique). Distinct\n *  from `CodegenPathConflict` so attribution stays clean. */\nexport class CodegenEmitterCollision extends Schema.TaggedErrorClass<CodegenEmitterCollision>()(\n\t'CodegenEmitterCollision',\n\t{\n\t\temitterName: Schema.String,\n\t\toutputPaths: Schema.Array(Schema.String),\n\t},\n) {}\n\n/** Two `Codegenable` contributions target the SAME aggregate\n *  `bucket` but disagree on its routing/sensitivity metadata\n *  (`outputLocation` or `sensitive`). The `AggregateContribution`\n *  contract requires all contributors to a bucket to agree; the\n *  orchestrator routes the synthesized aggregate from the FIRST\n *  contributor it sees, so a silent disagreement could misroute a\n *  sensitive aggregate into the committed `generated` tree. Detected\n *  while folding contributions so the cycle fails fast rather than\n *  emitting a secret with non-sensitive handling. */\nexport class CodegenAggregateConflict extends Schema.TaggedErrorClass<CodegenAggregateConflict>()(\n\t'CodegenAggregateConflict',\n\t{\n\t\tbucket: Schema.String,\n\t\tfield: Schema.Literals(['outputLocation', 'sensitive']),\n\t\t/** The value the first contributor established for the bucket. */\n\t\testablished: Schema.String,\n\t\t/** The conflicting value a later contributor declared. */\n\t\tconflicting: Schema.String,\n\t\t/** Emitter names: the contributor that established the value and\n\t\t *  the one that disagreed. */\n\t\temitters: Schema.Array(Schema.String),\n\t},\n) {}\n\n/** A `Codegenable.emit()` wrote a value that the renderer cannot\n *  serialise (a function, a symbol, a circular reference, etc.). */\nexport class CodegenRenderError extends Schema.TaggedErrorClass<CodegenRenderError>()(\n\t'CodegenRenderError',\n\t{\n\t\temitterName: Schema.String,\n\t\toutputPath: Schema.String,\n\t\tdetail: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** `Codegenable.emit()` raised. Wraps the inner Effect failure\n *  rather than propagating it raw so the orchestrator's error\n *  channel stays closed. */\nexport class CodegenEmitFailed extends Schema.TaggedErrorClass<CodegenEmitFailed>()(\n\t'CodegenEmitFailed',\n\t{\n\t\temitterName: Schema.String,\n\t\toutputPath: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** Disk write (atomic-write or permission-tighten) failed. */\nexport class CodegenWriteFailed extends Schema.TaggedErrorClass<CodegenWriteFailed>()(\n\t'CodegenWriteFailed',\n\t{\n\t\toutputPath: Schema.String,\n\t\tstage: Schema.Literals(['mkdir-parent', 'write', 'rename', 'chmod', 'gitignore']),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** `@mysten/codegen` shell-out (Move-to-TS bindings) failed or\n *  silently no-op'd. Distilled-doc § \"Silent no-op from a\n *  downstream tool is a failure\" — we surface a hint about the\n *  common `Move.toml` cause. */\nexport class CodegenBindingsFailed extends Schema.TaggedErrorClass<CodegenBindingsFailed>()(\n\t'CodegenBindingsFailed',\n\t{\n\t\tpackage: Schema.String,\n\t\tsourcePath: Schema.String,\n\t\treason: Schema.Literals(['summary-failed', 'no-output', 'render-failed', 'write-failed']),\n\t\thint: Schema.optional(Schema.String),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** The reader of the manifest envelope detected drift between\n *  what plugins contributed and what's on disk — e.g. a stale\n *  envelope from a previous stack lifecycle. */\nexport class CodegenManifestDrift extends Schema.TaggedErrorClass<CodegenManifestDrift>()(\n\t'CodegenManifestDrift',\n\t{\n\t\tdetail: Schema.String,\n\t},\n) {}\n\nexport type CodegenError =\n\t| CodegenPathConflict\n\t| CodegenEmitterCollision\n\t| CodegenAggregateConflict\n\t| CodegenRenderError\n\t| CodegenEmitFailed\n\t| CodegenWriteFailed\n\t| CodegenBindingsFailed\n\t| CodegenManifestDrift;\n"],"mappings":";;;;;;;;;AAmBA,IAAa,sBAAb,cAAyC,OAAO,iBAAsC,CAAC,CACtF,uBACA;CACC,MAAM,OAAO,SAAS,CAAC,aAAa,cAAc,CAAC;CACnD,YAAY,OAAO;CACnB,UAAU,OAAO,MAAM,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;;;;AAMH,IAAa,0BAAb,cAA6C,OAAO,iBAA0C,CAAC,CAC9F,2BACA;CACC,aAAa,OAAO;CACpB,aAAa,OAAO,MAAM,OAAO,MAAM;AACxC,CACD,CAAC,CAAC,CAAC;;;;;;;;;;AAWH,IAAa,2BAAb,cAA8C,OAAO,iBAA2C,CAAC,CAChG,4BACA;CACC,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,CAAC,kBAAkB,WAAW,CAAC;;CAEtD,aAAa,OAAO;;CAEpB,aAAa,OAAO;;;CAGpB,UAAU,OAAO,MAAM,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;;AAIH,IAAa,qBAAb,cAAwC,OAAO,iBAAqC,CAAC,CACpF,sBACA;CACC,aAAa,OAAO;CACpB,YAAY,OAAO;CACnB,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;;;AAKH,IAAa,oBAAb,cAAuC,OAAO,iBAAoC,CAAC,CAClF,qBACA;CACC,aAAa,OAAO;CACpB,YAAY,OAAO;CACnB,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;AAGH,IAAa,qBAAb,cAAwC,OAAO,iBAAqC,CAAC,CACpF,sBACA;CACC,YAAY,OAAO;CACnB,OAAO,OAAO,SAAS;EAAC;EAAgB;EAAS;EAAU;EAAS;CAAW,CAAC;CAChF,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;;;;AAMH,IAAa,wBAAb,cAA2C,OAAO,iBAAwC,CAAC,CAC1F,yBACA;CACC,SAAS,OAAO;CAChB,YAAY,OAAO;CACnB,QAAQ,OAAO,SAAS;EAAC;EAAkB;EAAa;EAAiB;CAAc,CAAC;CACxF,MAAM,OAAO,SAAS,OAAO,MAAM;CACnC,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;AAKuC,OAAO,iBAAuC,CAAC,CACxF,wBACA,EACC,QAAQ,OAAO,OAChB,CACD"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/orchestrators/codegen/errors.ts"],"sourcesContent":["// Typed errors for the Codegen orchestrator.\n//\n// A phase-tagged failure-mode taxonomy: \"emitter-collision at acquire\",\n// \"binary shell-out failure\", and \"pure render failure\" each get a\n// separate tag so callers can `catchTag` on each.\n//\n// Phase tags inside each error name the lifecycle step that failed\n// (resolve → emit → render → write → bindings → finalize) so error\n// attribution stays accurate.\n\nimport { Schema } from 'effect';\n\n/** Path-layer rejection from the codegen orchestrator.\n *  - `kind: 'duplicate'` — two `Codegenable` contributions claim the\n *    same `outputPath`. Hard failure detected BEFORE write so the\n *    user-visible output dir never sees an ambiguous overwrite.\n *  - `kind: 'non-relative'` — a plugin-authored `outputPath` escapes\n *    the codegen root (contains `..` or is absolute). Defense-in-depth\n *    for the file-layout invariants. */\nexport class CodegenPathConflict extends Schema.TaggedErrorClass<CodegenPathConflict>()(\n\t'CodegenPathConflict',\n\t{\n\t\tkind: Schema.Literals(['duplicate', 'non-relative']),\n\t\toutputPath: Schema.String,\n\t\temitters: Schema.Array(Schema.String),\n\t},\n) {}\n\n/** Two `Codegenable` contributions share the SAME `emitterName`\n *  literal but resolve to different `outputPath`s — programming\n *  bug in plugin code (emitter name should be unique). Distinct\n *  from `CodegenPathConflict` so attribution stays clean. */\nexport class CodegenEmitterCollision extends Schema.TaggedErrorClass<CodegenEmitterCollision>()(\n\t'CodegenEmitterCollision',\n\t{\n\t\temitterName: Schema.String,\n\t\toutputPaths: Schema.Array(Schema.String),\n\t},\n) {}\n\n/** Two `Codegenable` contributions target the SAME aggregate\n *  `bucket` but disagree on its `sensitive` metadata. The\n *  `AggregateContribution` contract requires all contributors to a\n *  bucket to agree; the orchestrator takes the FIRST contributor's\n *  sensitivity, so a silent disagreement could emit a secret with\n *  non-sensitive handling. Detected while folding contributions so the\n *  cycle fails fast. */\nexport class CodegenAggregateConflict extends Schema.TaggedErrorClass<CodegenAggregateConflict>()(\n\t'CodegenAggregateConflict',\n\t{\n\t\tbucket: Schema.String,\n\t\tfield: Schema.Literals(['sensitive']),\n\t\t/** The value the first contributor established for the bucket. */\n\t\testablished: Schema.String,\n\t\t/** The conflicting value a later contributor declared. */\n\t\tconflicting: Schema.String,\n\t\t/** Emitter names: the contributor that established the value and\n\t\t *  the one that disagreed. */\n\t\temitters: Schema.Array(Schema.String),\n\t},\n) {}\n\n/** A `Codegenable.emit()` wrote a value that the renderer cannot\n *  serialise (a function, a symbol, a circular reference, etc.). */\nexport class CodegenRenderError extends Schema.TaggedErrorClass<CodegenRenderError>()(\n\t'CodegenRenderError',\n\t{\n\t\temitterName: Schema.String,\n\t\toutputPath: Schema.String,\n\t\tdetail: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** `Codegenable.emit()` raised. Wraps the inner Effect failure\n *  rather than propagating it raw so the orchestrator's error\n *  channel stays closed. */\nexport class CodegenEmitFailed extends Schema.TaggedErrorClass<CodegenEmitFailed>()(\n\t'CodegenEmitFailed',\n\t{\n\t\temitterName: Schema.String,\n\t\toutputPath: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** Disk write (atomic-write or permission-tighten) failed. */\nexport class CodegenWriteFailed extends Schema.TaggedErrorClass<CodegenWriteFailed>()(\n\t'CodegenWriteFailed',\n\t{\n\t\toutputPath: Schema.String,\n\t\tstage: Schema.Literals(['mkdir-parent', 'write', 'rename', 'chmod', 'gitignore']),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** `@mysten/codegen` shell-out (Move-to-TS bindings) failed or\n *  silently no-op'd. Distilled-doc § \"Silent no-op from a\n *  downstream tool is a failure\" — we surface a hint about the\n *  common `Move.toml` cause. */\nexport class CodegenBindingsFailed extends Schema.TaggedErrorClass<CodegenBindingsFailed>()(\n\t'CodegenBindingsFailed',\n\t{\n\t\tpackage: Schema.String,\n\t\tsourcePath: Schema.String,\n\t\treason: Schema.Literals(['summary-failed', 'no-output', 'render-failed', 'write-failed']),\n\t\thint: Schema.optional(Schema.String),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** The reader of the manifest envelope detected drift between\n *  what plugins contributed and what's on disk — e.g. a stale\n *  envelope from a previous stack lifecycle. */\nexport class CodegenManifestDrift extends Schema.TaggedErrorClass<CodegenManifestDrift>()(\n\t'CodegenManifestDrift',\n\t{\n\t\tdetail: Schema.String,\n\t},\n) {}\n\nexport type CodegenError =\n\t| CodegenPathConflict\n\t| CodegenEmitterCollision\n\t| CodegenAggregateConflict\n\t| CodegenRenderError\n\t| CodegenEmitFailed\n\t| CodegenWriteFailed\n\t| CodegenBindingsFailed\n\t| CodegenManifestDrift;\n"],"mappings":";;;;;;;;;AAmBA,IAAa,sBAAb,cAAyC,OAAO,iBAAsC,CAAC,CACtF,uBACA;CACC,MAAM,OAAO,SAAS,CAAC,aAAa,cAAc,CAAC;CACnD,YAAY,OAAO;CACnB,UAAU,OAAO,MAAM,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;;;;AAMH,IAAa,0BAAb,cAA6C,OAAO,iBAA0C,CAAC,CAC9F,2BACA;CACC,aAAa,OAAO;CACpB,aAAa,OAAO,MAAM,OAAO,MAAM;AACxC,CACD,CAAC,CAAC,CAAC;;;;;;;;AASH,IAAa,2BAAb,cAA8C,OAAO,iBAA2C,CAAC,CAChG,4BACA;CACC,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,CAAC,WAAW,CAAC;;CAEpC,aAAa,OAAO;;CAEpB,aAAa,OAAO;;;CAGpB,UAAU,OAAO,MAAM,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;;AAIH,IAAa,qBAAb,cAAwC,OAAO,iBAAqC,CAAC,CACpF,sBACA;CACC,aAAa,OAAO;CACpB,YAAY,OAAO;CACnB,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;;;AAKH,IAAa,oBAAb,cAAuC,OAAO,iBAAoC,CAAC,CAClF,qBACA;CACC,aAAa,OAAO;CACpB,YAAY,OAAO;CACnB,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;AAGH,IAAa,qBAAb,cAAwC,OAAO,iBAAqC,CAAC,CACpF,sBACA;CACC,YAAY,OAAO;CACnB,OAAO,OAAO,SAAS;EAAC;EAAgB;EAAS;EAAU;EAAS;CAAW,CAAC;CAChF,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;;;;;AAMH,IAAa,wBAAb,cAA2C,OAAO,iBAAwC,CAAC,CAC1F,yBACA;CACC,SAAS,OAAO;CAChB,YAAY,OAAO;CACnB,QAAQ,OAAO,SAAS;EAAC;EAAkB;EAAa;EAAiB;CAAc,CAAC;CACxF,MAAM,OAAO,SAAS,OAAO,MAAM;CACnC,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;AAKuC,OAAO,iBAAuC,CAAC,CACxF,wBACA,EACC,QAAQ,OAAO,OAChB,CACD"}

package/dist/orchestrators/codegen/format.mjs

@@ -1,5 +1,5 @@
 import { CodegenRenderError } from "./errors.mjs";
-import { isRawExpr } from "../../contracts/codegenable.mjs";
+import { isForNetworkBucket, isRawExpr } from "../../contracts/codegenable.mjs";
 //#region src/orchestrators/codegen/format.ts
 const GENERATED_HEADER = [
 	"// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.",
@@ -39,6 +39,10 @@ const renderFile = (input) => {
 		}
 		lines.push("");
 	}
+	if (input.preamble && input.preamble.length > 0) {
+		for (const stmt of input.preamble) lines.push(stmt);
+		lines.push("");
+	}
 	const keys = Object.keys(input.exports).sort();
 	for (const key of keys) {
 		const value = input.exports[key];
@@ -67,6 +71,21 @@ const tryRender = (value, seen, depth = 1) => {
 	if (value === null) return tryOk("null");
 	if (value === void 0) return tryErr("undefined is not serialisable — emit null instead");
 	if (isRawExpr(value)) return tryOk(value.expr);
+	if (isForNetworkBucket(value)) {
+		const inner = tryRender(value.inner, seen, depth + 2);
+		if (!inner.ok) return inner;
+		const method = INDENT.repeat(depth);
+		const body = INDENT.repeat(depth + 1);
+		const close = INDENT.repeat(depth - 1);
+		const param = value.needsDep ? "network" : "_network";
+		const lines = ["{"];
+		lines.push(`${method}forNetwork(${param}: string) {`);
+		if (value.needsDep) lines.push(`${body}const dep = loadDeployment().forNetwork(network);`);
+		lines.push(`${body}return ${inner.text} as const;`);
+		lines.push(`${method}},`);
+		lines.push(`${close}}`);
+		return tryOk(lines.join("\n"));
+	}
 	const t = typeof value;
 	if (t === "string") return tryOk(JSON.stringify(value));
 	if (t === "number") {