@mysten-incubation/devstack 0.1.0 → 0.2.0

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

@@ -1 +1 @@
-{"version":3,"file":"format.mjs","names":[],"sources":["../../../src/orchestrators/codegen/format.ts"],"sourcesContent":["// TypeScript source rendering for codegen-emitted files.\n//\n// Distilled-doc § \"Hand-rolled TS-object-literal rendering ... drifts\n// subtly between emitters; a small shared renderer would absorb the\n// variation and own the bigint policy in one place.\" This module IS\n// that shared renderer.\n//\n// Output shape (one emitted file):\n//\n//   <generated-header>\n//   <do-not-commit-banner if sensitive>\n//   <imports?>\n//   <one `export const <name> = <literal> as const;` per export>\n//   <trailing newline>\n//\n// The renderer:\n//   - sorts object keys (deterministic re-emit, distilled-doc\n//     invariant \"Deterministic re-emit\"),\n//   - quotes identifier-unsafe keys with double-quoted strings,\n//   - serialises bigints as quoted decimal strings for\n//     `BigInt(<string>)` consumers,\n//   - refuses functions / symbols / undefined / circular refs with a\n//     typed render error,\n//   - emits arrays and records as readonly literal forms.\n//\n// The renderer does NOT format with prettier; it aims for\n// prettier-compatible spacing (two-space indent, trailing commas,\n// double-quoted strings, semicolons) so a prettier-on-write user\n// hook is a no-op on emitted bytes — that's load-bearing for the\n// \"no mtime touch on identical content\" idempotency invariant.\n\nimport { CodegenRenderError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Headers\n// -----------------------------------------------------------------------------\n\nconst GENERATED_HEADER = [\n\t'// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.',\n\t'// Do not edit by hand — your changes will be overwritten on the next',\n\t'// `devstack up` cycle. Apps consume codegen output; codegen output never',\n\t'// imports from devstack.',\n].join('\\n');\n\nconst SENSITIVE_HEADER = [\n\t'// !!! DO NOT COMMIT THIS FILE !!!',\n\t'// This file carries sensitive material (wallet pair token, database',\n\t'// credentials, or user extras). The output directory ships a .gitignore',\n\t'// covering it; this banner is a belt-and-braces reminder.',\n].join('\\n');\n\n// -----------------------------------------------------------------------------\n// Public render entry\n// -----------------------------------------------------------------------------\n\nexport interface RenderInput {\n\treadonly emitterName: string;\n\treadonly outputPath: string;\n\treadonly sensitive: boolean;\n\t/** The declarations written by `Codegenable.emit(ctx)`. Each entry\n\t *  becomes one `export const <key> = <literal> as const;`. */\n\treadonly exports: { readonly [key: string]: unknown };\n\t/** Optional import lines the emitter wants prepended (e.g. a\n\t *  type import from `@mysten/dapp-kit` for the wallet config).\n\t *  Each entry is a raw import statement string. */\n\treadonly imports?: ReadonlyArray<string>;\n}\n\n/** Result of a render attempt. Discriminated so callers can dispatch\n *  on `ok` without resorting to `instanceof` checks (STYLE_GUIDE §2). */\nexport type RenderResult =\n\t| { readonly ok: true; readonly text: string }\n\t| { readonly ok: false; readonly error: CodegenRenderError };\n\nconst renderErr = (\n\tinput: RenderInput,\n\tdetail: string,\n): { readonly ok: false; readonly error: CodegenRenderError } => ({\n\tok: false,\n\terror: new CodegenRenderError({\n\t\temitterName: input.emitterName,\n\t\toutputPath: input.outputPath,\n\t\tdetail,\n\t}),\n});\n\n/** Render an emitted file to a TS source string. Returns a discriminated\n *  `RenderResult` — `{ok: true, text}` on success, `{ok: false, error}`\n *  when the value is unserialisable or imports forbidden paths. */\nexport const renderFile = (input: RenderInput): RenderResult => {\n\tconst lines: Array<string> = [];\n\tlines.push(GENERATED_HEADER);\n\tif (input.sensitive) {\n\t\tlines.push('');\n\t\tlines.push(SENSITIVE_HEADER);\n\t}\n\tlines.push('');\n\tif (input.imports && input.imports.length > 0) {\n\t\tfor (const imp of input.imports) {\n\t\t\tif (isForbiddenGeneratedImport(imp)) {\n\t\t\t\treturn renderErr(input, `generated files must not import devstack source: ${imp}`);\n\t\t\t}\n\t\t\tlines.push(imp);\n\t\t}\n\t\tlines.push('');\n\t}\n\t// Stable export order: keys lexicographically sorted.\n\tconst keys = Object.keys(input.exports).sort();\n\tfor (const key of keys) {\n\t\tconst value = input.exports[key];\n\t\tconst rendered = tryRender(value, new Set());\n\t\tif (!rendered.ok) {\n\t\t\treturn renderErr(input, `export '${key}': ${rendered.detail}`);\n\t\t}\n\t\tif (!isIdentifier(key)) {\n\t\t\treturn renderErr(input, `export key '${key}' is not a valid TS identifier`);\n\t\t}\n\t\tlines.push(`export const ${key} = ${rendered.text} as const;`);\n\t\tlines.push('');\n\t}\n\t// Single trailing newline; never two.\n\twhile (lines.length > 1 && lines[lines.length - 1] === '' && lines[lines.length - 2] === '') {\n\t\tlines.pop();\n\t}\n\treturn {\n\t\tok: true,\n\t\ttext: lines.join('\\n') + (lines[lines.length - 1] === '' ? '' : '\\n'),\n\t};\n};\n\n// -----------------------------------------------------------------------------\n// Value rendering\n// -----------------------------------------------------------------------------\n\nconst INDENT = '\\t';\n\ntype TryRenderResult =\n\t| { readonly ok: true; readonly text: string }\n\t| { readonly ok: false; readonly detail: string };\n\nconst tryOk = (text: string): TryRenderResult => ({ ok: true, text });\nconst tryErr = (detail: string): TryRenderResult => ({ ok: false, detail });\n\nconst tryRender = (value: unknown, seen: Set<object>, depth = 1): TryRenderResult => {\n\tif (value === null) return tryOk('null');\n\tif (value === undefined) return tryErr('undefined is not serialisable — emit null instead');\n\tconst t = typeof value;\n\tif (t === 'string') return tryOk(JSON.stringify(value));\n\tif (t === 'number') {\n\t\tif (!Number.isFinite(value as number)) return tryErr('non-finite number');\n\t\treturn tryOk(String(value));\n\t}\n\tif (t === 'boolean') return tryOk(String(value));\n\tif (t === 'bigint') return tryOk(JSON.stringify(value.toString()));\n\tif (t === 'function' || t === 'symbol') return tryErr(`${t} is not serialisable`);\n\tif (Array.isArray(value)) {\n\t\tif (seen.has(value)) return tryErr('circular reference');\n\t\tseen.add(value);\n\t\tif (value.length === 0) return tryOk('[]');\n\t\tconst inner: Array<string> = [];\n\t\tfor (const item of value) {\n\t\t\tconst r = tryRender(item, seen, depth + 1);\n\t\t\tif (!r.ok) return r;\n\t\t\tinner.push(INDENT.repeat(depth) + r.text);\n\t\t}\n\t\tseen.delete(value);\n\t\treturn tryOk(`[\\n${inner.join(',\\n')},\\n${INDENT.repeat(depth - 1)}]`);\n\t}\n\tif (t === 'object') {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tif (seen.has(obj)) return tryErr('circular reference');\n\t\tseen.add(obj);\n\t\tconst keys = Object.keys(obj).sort();\n\t\tif (keys.length === 0) return tryOk('{}');\n\t\tconst lines: Array<string> = [];\n\t\tfor (const k of keys) {\n\t\t\tconst v = obj[k];\n\t\t\tif (v === undefined) continue; // drop undefined props (distilled-doc skip-emit-explicit)\n\t\t\tconst r = tryRender(v, seen, depth + 1);\n\t\t\tif (!r.ok) return r;\n\t\t\tconst keyText = isIdentifier(k) ? k : JSON.stringify(k);\n\t\t\tlines.push(`${INDENT.repeat(depth)}${keyText}: ${r.text}`);\n\t\t}\n\t\tseen.delete(obj);\n\t\tif (lines.length === 0) return tryOk('{}');\n\t\treturn tryOk(`{\\n${lines.join(',\\n')},\\n${INDENT.repeat(depth - 1)}}`);\n\t}\n\treturn tryErr(`unsupported value type ${t}`);\n};\n\nconst IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\nconst isIdentifier = (s: string): boolean => IDENT_RE.test(s);\n\nconst isForbiddenGeneratedImport = (line: string): boolean =>\n\t/\\bfrom\\s+[\"']@mysten-incubation\\/devstack(?:-rewrite)?(?:\\/|[\"'])/.test(line) ||\n\t/\\bimport\\s*\\(\\s*[\"']@mysten-incubation\\/devstack(?:-rewrite)?(?:\\/|[\"'])/.test(line) ||\n\t/\\bfrom\\s+[\"'][./][^\"']*\\/src\\//.test(line) ||\n\t/\\bimport\\s*\\(\\s*[\"'][./][^\"']*\\/src\\//.test(line);\n"],"mappings":"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"}
+{"version":3,"file":"format.mjs","names":[],"sources":["../../../src/orchestrators/codegen/format.ts"],"sourcesContent":["// TypeScript source rendering for codegen-emitted files.\n//\n// Distilled-doc § \"Hand-rolled TS-object-literal rendering ... drifts\n// subtly between emitters; a small shared renderer would absorb the\n// variation and own the bigint policy in one place.\" This module IS\n// that shared renderer.\n//\n// Output shape (one emitted file):\n//\n//   <generated-header>\n//   <do-not-commit-banner if sensitive>\n//   <imports?>\n//   <one `export const <name> = <literal> as const;` per export>\n//   <trailing newline>\n//\n// The renderer:\n//   - sorts object keys (deterministic re-emit, distilled-doc\n//     invariant \"Deterministic re-emit\"),\n//   - quotes identifier-unsafe keys with double-quoted strings,\n//   - serialises bigints as quoted decimal strings for\n//     `BigInt(<string>)` consumers,\n//   - refuses functions / symbols / undefined / circular refs with a\n//     typed render error,\n//   - emits arrays and records as readonly literal forms.\n//\n// The renderer does NOT format with prettier; it aims for\n// prettier-compatible spacing (two-space indent, trailing commas,\n// double-quoted strings, semicolons) so a prettier-on-write user\n// hook is a no-op on emitted bytes — that's load-bearing for the\n// \"no mtime touch on identical content\" idempotency invariant.\n\nimport { isRawExpr } from '../../contracts/codegenable.ts';\n\nimport { CodegenRenderError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Headers\n// -----------------------------------------------------------------------------\n\nconst GENERATED_HEADER = [\n\t'// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.',\n\t'// Do not edit by hand — your changes will be overwritten on the next',\n\t'// `devstack up` cycle. Apps consume codegen output; codegen output never',\n\t'// imports from devstack.',\n].join('\\n');\n\nconst SENSITIVE_HEADER = [\n\t'// !!! DO NOT COMMIT THIS FILE !!!',\n\t'// This file carries sensitive material (wallet pair token, database',\n\t'// credentials, or user extras). The output directory ships a .gitignore',\n\t'// covering it; this banner is a belt-and-braces reminder.',\n].join('\\n');\n\n// -----------------------------------------------------------------------------\n// Public render entry\n// -----------------------------------------------------------------------------\n\nexport interface RenderInput {\n\treadonly emitterName: string;\n\treadonly outputPath: string;\n\treadonly sensitive: boolean;\n\t/** The declarations written by `Codegenable.emit(ctx)`. Each entry\n\t *  becomes one `export const <key> = <literal> as const;`. */\n\treadonly exports: { readonly [key: string]: unknown };\n\t/** Optional import lines the emitter wants prepended (e.g. a\n\t *  type import from `@mysten/dapp-kit` for the wallet config).\n\t *  Each entry is a raw import statement string. */\n\treadonly imports?: ReadonlyArray<string>;\n}\n\n/** Result of a render attempt. Discriminated so callers can dispatch\n *  on `ok` without resorting to `instanceof` checks (STYLE_GUIDE §2). */\nexport type RenderResult =\n\t| { readonly ok: true; readonly text: string }\n\t| { readonly ok: false; readonly error: CodegenRenderError };\n\nconst renderErr = (\n\tinput: RenderInput,\n\tdetail: string,\n): { readonly ok: false; readonly error: CodegenRenderError } => ({\n\tok: false,\n\terror: new CodegenRenderError({\n\t\temitterName: input.emitterName,\n\t\toutputPath: input.outputPath,\n\t\tdetail,\n\t}),\n});\n\n/** Render an emitted file to a TS source string. Returns a discriminated\n *  `RenderResult` — `{ok: true, text}` on success, `{ok: false, error}`\n *  when the value is unserialisable or imports forbidden paths. */\nexport const renderFile = (input: RenderInput): RenderResult => {\n\tconst lines: Array<string> = [];\n\tlines.push(GENERATED_HEADER);\n\tif (input.sensitive) {\n\t\tlines.push('');\n\t\tlines.push(SENSITIVE_HEADER);\n\t}\n\tlines.push('');\n\tif (input.imports && input.imports.length > 0) {\n\t\tfor (const imp of input.imports) {\n\t\t\tif (isForbiddenGeneratedImport(imp)) {\n\t\t\t\treturn renderErr(input, `generated files must not import devstack source: ${imp}`);\n\t\t\t}\n\t\t\tlines.push(imp);\n\t\t}\n\t\tlines.push('');\n\t}\n\t// Stable export order: keys lexicographically sorted.\n\tconst keys = Object.keys(input.exports).sort();\n\tfor (const key of keys) {\n\t\tconst value = input.exports[key];\n\t\tconst rendered = tryRender(value, new Set());\n\t\tif (!rendered.ok) {\n\t\t\treturn renderErr(input, `export '${key}': ${rendered.detail}`);\n\t\t}\n\t\tif (!isIdentifier(key)) {\n\t\t\treturn renderErr(input, `export key '${key}' is not a valid TS identifier`);\n\t\t}\n\t\tlines.push(`export const ${key} = ${rendered.text} as const;`);\n\t\tlines.push('');\n\t}\n\t// Single trailing newline; never two.\n\twhile (lines.length > 1 && lines[lines.length - 1] === '' && lines[lines.length - 2] === '') {\n\t\tlines.pop();\n\t}\n\treturn {\n\t\tok: true,\n\t\ttext: lines.join('\\n') + (lines[lines.length - 1] === '' ? '' : '\\n'),\n\t};\n};\n\n// -----------------------------------------------------------------------------\n// Value rendering\n// -----------------------------------------------------------------------------\n\nconst INDENT = '\\t';\n\ntype TryRenderResult =\n\t| { readonly ok: true; readonly text: string }\n\t| { readonly ok: false; readonly detail: string };\n\nconst tryOk = (text: string): TryRenderResult => ({ ok: true, text });\nconst tryErr = (detail: string): TryRenderResult => ({ ok: false, detail });\n\nconst tryRender = (value: unknown, seen: Set<object>, depth = 1): TryRenderResult => {\n\tif (value === null) return tryOk('null');\n\tif (value === undefined) return tryErr('undefined is not serialisable — emit null instead');\n\t// Raw-expression escape hatch: a `RawExpr` is emitted VERBATIM (e.g.\n\t// `resolveId(\"@local/foo\")`) instead of as a quoted literal. The single\n\t// authorized use is id resolution in the emitted `config.ts` — ids are\n\t// LOADED CONFIG DATA injected at app build time, not codegen output, so\n\t// the config calls a runtime resolver rather than embedding a literal id.\n\tif (isRawExpr(value)) return tryOk(value.expr);\n\tconst t = typeof value;\n\tif (t === 'string') return tryOk(JSON.stringify(value));\n\tif (t === 'number') {\n\t\tif (!Number.isFinite(value as number)) return tryErr('non-finite number');\n\t\treturn tryOk(String(value));\n\t}\n\tif (t === 'boolean') return tryOk(String(value));\n\tif (t === 'bigint') return tryOk(JSON.stringify(value.toString()));\n\tif (t === 'function' || t === 'symbol') return tryErr(`${t} is not serialisable`);\n\tif (Array.isArray(value)) {\n\t\tif (seen.has(value)) return tryErr('circular reference');\n\t\tseen.add(value);\n\t\tif (value.length === 0) return tryOk('[]');\n\t\tconst inner: Array<string> = [];\n\t\tfor (const item of value) {\n\t\t\tconst r = tryRender(item, seen, depth + 1);\n\t\t\tif (!r.ok) return r;\n\t\t\tinner.push(INDENT.repeat(depth) + r.text);\n\t\t}\n\t\tseen.delete(value);\n\t\treturn tryOk(`[\\n${inner.join(',\\n')},\\n${INDENT.repeat(depth - 1)}]`);\n\t}\n\tif (t === 'object') {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tif (seen.has(obj)) return tryErr('circular reference');\n\t\tseen.add(obj);\n\t\tconst keys = Object.keys(obj).sort();\n\t\tif (keys.length === 0) return tryOk('{}');\n\t\tconst lines: Array<string> = [];\n\t\tfor (const k of keys) {\n\t\t\tconst v = obj[k];\n\t\t\tif (v === undefined) continue; // drop undefined props (distilled-doc skip-emit-explicit)\n\t\t\tconst r = tryRender(v, seen, depth + 1);\n\t\t\tif (!r.ok) return r;\n\t\t\tconst keyText = isIdentifier(k) ? k : JSON.stringify(k);\n\t\t\tlines.push(`${INDENT.repeat(depth)}${keyText}: ${r.text}`);\n\t\t}\n\t\tseen.delete(obj);\n\t\tif (lines.length === 0) return tryOk('{}');\n\t\treturn tryOk(`{\\n${lines.join(',\\n')},\\n${INDENT.repeat(depth - 1)}}`);\n\t}\n\treturn tryErr(`unsupported value type ${t}`);\n};\n\nconst IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\nconst isIdentifier = (s: string): boolean => IDENT_RE.test(s);\n\nconst isForbiddenGeneratedImport = (line: string): boolean =>\n\t/\\bfrom\\s+[\"']@mysten-incubation\\/devstack(?:-rewrite)?(?:\\/|[\"'])/.test(line) ||\n\t/\\bimport\\s*\\(\\s*[\"']@mysten-incubation\\/devstack(?:-rewrite)?(?:\\/|[\"'])/.test(line) ||\n\t/\\bfrom\\s+[\"'][./][^\"']*\\/src\\//.test(line) ||\n\t/\\bimport\\s*\\(\\s*[\"'][./][^\"']*\\/src\\//.test(line);\n"],"mappings":"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"}

package/dist/orchestrators/codegen/gitignore.mjs

@@ -6,13 +6,21 @@ import { Effect, FileSystem } from "effect";
 const USER_BLOCK_START = "# user: customisations below preserved across re-emits";
 const USER_BLOCK_END = "# /user: do not edit below this line";
 const DEFAULT_USER_BLOCK = `${USER_BLOCK_START}\n${USER_BLOCK_END}`;
-const HEADER = [
+const ignoreAllHeader = [
 	"# THIS FILE IS AUTO-GENERATED BY @mysten/devstack.",
 	"# The codegen output directory is engine-managed; the whole tree is",
 	"# ignored from git by default. Sensitive files have an explicit mention",
 	"# below for documentation. Add user customisations inside the `# user:`",
 	"# block; the rest is rewritten on every emit cycle."
 ].join("\n");
+const trackAllHeader = [
+	"# THIS FILE IS AUTO-GENERATED BY @mysten/devstack.",
+	"# This is the COMMITTED projection tree: the type bindings + sentinel-id",
+	"# config stubs are tracked so `tsc`/`vite build` work on a fresh clone",
+	"# with no stack running. Only genuinely sensitive files are ignored.",
+	"# Add user customisations inside the `# user:` block; the rest is",
+	"# rewritten on every emit cycle."
+].join("\n");
 /**
 * Compose the gitignore content, preserving any user customisations
 * between the `# user:` markers in any existing file at `path`.
@@ -21,16 +29,27 @@ const composeGitignore = (existing, input) => {
 	const userBlock = existing !== null ? extractUserBlock(existing) : null;
 	const sortedSensitive = [...input.sensitivePaths].sort();
 	const lines = [];
-	lines.push(HEADER);
-	lines.push("");
-	lines.push("# default policy: ignore the whole output directory.");
-	lines.push("*");
-	lines.push("# but keep this .gitignore tracked so cloners get the policy.");
-	lines.push("!.gitignore");
-	if (sortedSensitive.length > 0) {
+	if (input.trackTree === true) {
+		lines.push(trackAllHeader);
+		lines.push("");
+		lines.push("# default policy: track the whole committed projection tree.");
+		if (sortedSensitive.length > 0) {
+			lines.push("");
+			lines.push("# sensitive files — never commit these even though the tree is tracked.");
+			for (const p of sortedSensitive) lines.push(p);
+		}
+	} else {
+		lines.push(ignoreAllHeader);
 		lines.push("");
-		lines.push("# sensitive files — never commit even if you override the `*` above.");
-		for (const p of sortedSensitive) lines.push(p);
+		lines.push("# default policy: ignore the whole output directory.");
+		lines.push("*");
+		lines.push("# but keep this .gitignore tracked so cloners get the policy.");
+		lines.push("!.gitignore");
+		if (sortedSensitive.length > 0) {
+			lines.push("");
+			lines.push("# sensitive files — never commit even if you override the `*` above.");
+			for (const p of sortedSensitive) lines.push(p);
+		}
 	}
 	lines.push("");
 	lines.push(userBlock !== null ? userBlock : DEFAULT_USER_BLOCK);
@@ -54,7 +73,7 @@ const writeGitignore = (input) => Effect.gen(function* () {
 		stage: "gitignore",
 		cause: e
 	})));
-}).pipe(Effect.withSpan("codegen.writeGitignore", { attributes: { "codegen.path": input.path } }));
+});
 const extractUserBlock = (text) => {
 	const startIdx = text.indexOf(USER_BLOCK_START);
 	const endIdx = text.indexOf(USER_BLOCK_END);

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

@@ -1 +1 @@
-{"version":3,"file":"gitignore.mjs","names":[],"sources":["../../../src/orchestrators/codegen/gitignore.ts"],"sourcesContent":["// .gitignore emission for the codegen output directory.\n//\n// Distilled-doc §\"Boundary helpers\": \"A `.gitignore` inside the\n// output directory, covering sensitive emitted files by default and\n// preserving user customizations.\" Two design points:\n//\n//   1. The entire output directory is engine-managed and the\n//      pragmatic default is \"ignore everything emitted here\". The\n//      `*` line lives at the top of the file with a comment\n//      explaining the policy.\n//   2. Sensitive files get an explicit second mention so the\n//      `.gitignore` reads as documentation in addition to enforcing\n//      the policy.\n//   3. User customisations land in a tracked `# user:` block — any\n//      content the user adds between the `# user:` and `# /user:`\n//      markers is preserved verbatim across re-emits.\n//\n// The `.gitignore` is emitted with the same per-file atomic writer as\n// the rest of the codegen tree.\n\nimport { Effect, FileSystem } from 'effect';\n\nimport { emitOne } from './emit.ts';\nimport { CodegenWriteFailed } from './errors.ts';\nimport { NON_SENSITIVE_DIR_MODE, NON_SENSITIVE_FILE_MODE } from './permissions.ts';\n\nconst USER_BLOCK_START = '# user: customisations below preserved across re-emits';\nconst USER_BLOCK_END = '# /user: do not edit below this line';\n\nconst DEFAULT_USER_BLOCK = `${USER_BLOCK_START}\\n${USER_BLOCK_END}`;\n\nconst HEADER = [\n\t'# THIS FILE IS AUTO-GENERATED BY @mysten/devstack.',\n\t'# The codegen output directory is engine-managed; the whole tree is',\n\t'# ignored from git by default. Sensitive files have an explicit mention',\n\t'# below for documentation. Add user customisations inside the `# user:`',\n\t'# block; the rest is rewritten on every emit cycle.',\n].join('\\n');\n\nexport interface GitignoreInput {\n\treadonly path: string;\n\treadonly parentMode?: number;\n\t/** Relative paths inside the output dir that are sensitive — get\n\t *  an explicit gitignore line. Sorted lexicographically. */\n\treadonly sensitivePaths: ReadonlyArray<string>;\n}\n\n/**\n * Compose the gitignore content, preserving any user customisations\n * between the `# user:` markers in any existing file at `path`.\n */\nexport const composeGitignore = (existing: string | null, input: GitignoreInput): string => {\n\tconst userBlock = existing !== null ? extractUserBlock(existing) : null;\n\tconst sortedSensitive = [...input.sensitivePaths].sort();\n\tconst lines: Array<string> = [];\n\tlines.push(HEADER);\n\tlines.push('');\n\tlines.push('# default policy: ignore the whole output directory.');\n\tlines.push('*');\n\tlines.push('# but keep this .gitignore tracked so cloners get the policy.');\n\tlines.push('!.gitignore');\n\tif (sortedSensitive.length > 0) {\n\t\tlines.push('');\n\t\tlines.push('# sensitive files — never commit even if you override the `*` above.');\n\t\tfor (const p of sortedSensitive) lines.push(p);\n\t}\n\tlines.push('');\n\tlines.push(userBlock !== null ? userBlock : DEFAULT_USER_BLOCK);\n\treturn lines.join('\\n') + '\\n';\n};\n\n/**\n * Write the gitignore. Idempotent via `emitOne`'s no-touch path.\n */\nexport const writeGitignore = (\n\tinput: GitignoreInput,\n): Effect.Effect<void, CodegenWriteFailed, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst existing = yield* fs.readFileString(input.path).pipe(\n\t\t\tEffect.match({\n\t\t\t\tonSuccess: (text) => text,\n\t\t\t\tonFailure: () => null,\n\t\t\t}),\n\t\t);\n\t\tconst content = composeGitignore(existing, input);\n\t\tyield* emitOne({\n\t\t\tpath: input.path,\n\t\t\tcontent,\n\t\t\tmode: NON_SENSITIVE_FILE_MODE,\n\t\t\tparentMode: input.parentMode ?? NON_SENSITIVE_DIR_MODE,\n\t\t}).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(e) =>\n\t\t\t\t\tnew CodegenWriteFailed({\n\t\t\t\t\t\toutputPath: input.path,\n\t\t\t\t\t\tstage: 'gitignore',\n\t\t\t\t\t\tcause: e,\n\t\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t}).pipe(\n\t\tEffect.withSpan('codegen.writeGitignore', {\n\t\t\tattributes: { 'codegen.path': input.path },\n\t\t}),\n\t);\n\nconst extractUserBlock = (text: string): string | null => {\n\tconst startIdx = text.indexOf(USER_BLOCK_START);\n\tconst endIdx = text.indexOf(USER_BLOCK_END);\n\tif (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null;\n\t// Include both markers in the returned block.\n\tconst endLineEnd = text.indexOf('\\n', endIdx);\n\tconst stop = endLineEnd === -1 ? text.length : endLineEnd;\n\treturn text.slice(startIdx, stop);\n};\n"],"mappings":";;;;;AA0BA,MAAM,mBAAmB;AACzB,MAAM,iBAAiB;AAEvB,MAAM,qBAAqB,GAAG,iBAAiB,IAAI;AAEnD,MAAM,SAAS;CACd;CACA;CACA;CACA;CACA;CACA,CAAC,KAAK,KAAK;;;;;AAcZ,MAAa,oBAAoB,UAAyB,UAAkC;CAC3F,MAAM,YAAY,aAAa,OAAO,iBAAiB,SAAS,GAAG;CACnE,MAAM,kBAAkB,CAAC,GAAG,MAAM,eAAe,CAAC,MAAM;CACxD,MAAM,QAAuB,EAAE;AAC/B,OAAM,KAAK,OAAO;AAClB,OAAM,KAAK,GAAG;AACd,OAAM,KAAK,uDAAuD;AAClE,OAAM,KAAK,IAAI;AACf,OAAM,KAAK,gEAAgE;AAC3E,OAAM,KAAK,cAAc;AACzB,KAAI,gBAAgB,SAAS,GAAG;AAC/B,QAAM,KAAK,GAAG;AACd,QAAM,KAAK,uEAAuE;AAClF,OAAK,MAAM,KAAK,gBAAiB,OAAM,KAAK,EAAE;;AAE/C,OAAM,KAAK,GAAG;AACd,OAAM,KAAK,cAAc,OAAO,YAAY,mBAAmB;AAC/D,QAAO,MAAM,KAAK,KAAK,GAAG;;;;;AAM3B,MAAa,kBACZ,UAEA,OAAO,IAAI,aAAa;CAQvB,MAAM,UAAU,iBAAiB,QANT,OADN,WAAW,YACF,eAAe,MAAM,KAAK,CAAC,KACrD,OAAO,MAAM;EACZ,YAAY,SAAS;EACrB,iBAAiB;EACjB,CAAC,CACF,EAC0C,MAAM;AACjD,QAAO,QAAQ;EACd,MAAM,MAAM;EACZ;EACA,MAAA;EACA,YAAY,MAAM,cAAA;EAClB,CAAC,CAAC,KACF,OAAO,UACL,MACA,IAAI,mBAAmB;EACtB,YAAY,MAAM;EAClB,OAAO;EACP,OAAO;EACP,CAAC,CACH,CACD;EACA,CAAC,KACF,OAAO,SAAS,0BAA0B,EACzC,YAAY,EAAE,gBAAgB,MAAM,MAAM,EAC1C,CAAC,CACF;AAEF,MAAM,oBAAoB,SAAgC;CACzD,MAAM,WAAW,KAAK,QAAQ,iBAAiB;CAC/C,MAAM,SAAS,KAAK,QAAQ,eAAe;AAC3C,KAAI,aAAa,MAAM,WAAW,MAAM,SAAS,SAAU,QAAO;CAElE,MAAM,aAAa,KAAK,QAAQ,MAAM,OAAO;CAC7C,MAAM,OAAO,eAAe,KAAK,KAAK,SAAS;AAC/C,QAAO,KAAK,MAAM,UAAU,KAAK"}
+{"version":3,"file":"gitignore.mjs","names":[],"sources":["../../../src/orchestrators/codegen/gitignore.ts"],"sourcesContent":["// .gitignore emission for the codegen output directory.\n//\n// The `.gitignore` policy depends on WHICH tree this is (`trackTree`):\n//\n//   - An EPHEMERAL tree (e.g. `.devstack/...`) is engine-managed output\n//     — the pragmatic default is \"ignore everything emitted here\" (a\n//     blanket `*`). Its id-bearing files must never land in git (the\n//     `.devstack/` root is already gitignored too; this is\n//     defense-in-depth + self-documentation).\n//   - The COMMITTED tree at `src/generated`, written by the stack-free\n//     `codegen` verb, is meant to be TRACKED: the type bindings + config\n//     stubs (which carry NO on-chain ids — those are injected at app\n//     build time) are committed so `tsc`/`vite build` work on a fresh\n//     clone with no stack. Here the policy TRACKS everything by default\n//     and only ignores the genuinely sensitive files (`sensitivePaths`).\n//\n// Three design points common to both:\n//   1. A default policy line at the top of the file with a comment\n//      explaining it (`*` for live, an all-tracked comment for committed).\n//   2. Sensitive files get an explicit mention so the `.gitignore` reads\n//      as documentation in addition to enforcing the policy.\n//   3. User customisations land in a tracked `# user:` block — any\n//      content the user adds between the `# user:` and `# /user:`\n//      markers is preserved verbatim across re-emits.\n//\n// The `.gitignore` is emitted with the same per-file atomic writer as\n// the rest of the codegen tree.\n\nimport { Effect, FileSystem } from 'effect';\n\nimport { emitOne } from './emit.ts';\nimport { CodegenWriteFailed } from './errors.ts';\nimport { NON_SENSITIVE_DIR_MODE, NON_SENSITIVE_FILE_MODE } from './permissions.ts';\n\nconst USER_BLOCK_START = '# user: customisations below preserved across re-emits';\nconst USER_BLOCK_END = '# /user: do not edit below this line';\n\nconst DEFAULT_USER_BLOCK = `${USER_BLOCK_START}\\n${USER_BLOCK_END}`;\n\nconst ignoreAllHeader = [\n\t'# THIS FILE IS AUTO-GENERATED BY @mysten/devstack.',\n\t'# The codegen output directory is engine-managed; the whole tree is',\n\t'# ignored from git by default. Sensitive files have an explicit mention',\n\t'# below for documentation. Add user customisations inside the `# user:`',\n\t'# block; the rest is rewritten on every emit cycle.',\n].join('\\n');\n\nconst trackAllHeader = [\n\t'# THIS FILE IS AUTO-GENERATED BY @mysten/devstack.',\n\t'# This is the COMMITTED projection tree: the type bindings + sentinel-id',\n\t'# config stubs are tracked so `tsc`/`vite build` work on a fresh clone',\n\t'# with no stack running. Only genuinely sensitive files are ignored.',\n\t'# Add user customisations inside the `# user:` block; the rest is',\n\t'# rewritten on every emit cycle.',\n].join('\\n');\n\nexport interface GitignoreInput {\n\treadonly path: string;\n\treadonly parentMode?: number;\n\t/** Relative paths inside the output dir that are sensitive — get\n\t *  an explicit gitignore line. Sorted lexicographically. */\n\treadonly sensitivePaths: ReadonlyArray<string>;\n\t/** When `true`, this is the COMMITTED projection tree (`src/generated`,\n\t *  written by the stack-free `codegen` verb): track the stubs and only\n\t *  ignore `sensitivePaths`. When `false`/omitted, this is the LIVE\n\t *  ephemeral tree under `.devstack`: blanket-ignore everything. */\n\treadonly trackTree?: boolean;\n}\n\n/**\n * Compose the gitignore content, preserving any user customisations\n * between the `# user:` markers in any existing file at `path`.\n */\nexport const composeGitignore = (existing: string | null, input: GitignoreInput): string => {\n\tconst userBlock = existing !== null ? extractUserBlock(existing) : null;\n\tconst sortedSensitive = [...input.sensitivePaths].sort();\n\tconst lines: Array<string> = [];\n\tif (input.trackTree === true) {\n\t\t// COMMITTED tree: track everything; ignore only the sensitive files.\n\t\tlines.push(trackAllHeader);\n\t\tlines.push('');\n\t\tlines.push('# default policy: track the whole committed projection tree.');\n\t\tif (sortedSensitive.length > 0) {\n\t\t\tlines.push('');\n\t\t\tlines.push('# sensitive files — never commit these even though the tree is tracked.');\n\t\t\tfor (const p of sortedSensitive) lines.push(p);\n\t\t}\n\t} else {\n\t\t// LIVE tree: blanket-ignore everything.\n\t\tlines.push(ignoreAllHeader);\n\t\tlines.push('');\n\t\tlines.push('# default policy: ignore the whole output directory.');\n\t\tlines.push('*');\n\t\tlines.push('# but keep this .gitignore tracked so cloners get the policy.');\n\t\tlines.push('!.gitignore');\n\t\tif (sortedSensitive.length > 0) {\n\t\t\tlines.push('');\n\t\t\tlines.push('# sensitive files — never commit even if you override the `*` above.');\n\t\t\tfor (const p of sortedSensitive) lines.push(p);\n\t\t}\n\t}\n\tlines.push('');\n\tlines.push(userBlock !== null ? userBlock : DEFAULT_USER_BLOCK);\n\treturn lines.join('\\n') + '\\n';\n};\n\n/**\n * Write the gitignore. Idempotent via `emitOne`'s no-touch path.\n */\nexport const writeGitignore = (\n\tinput: GitignoreInput,\n): Effect.Effect<void, CodegenWriteFailed, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst existing = yield* fs.readFileString(input.path).pipe(\n\t\t\tEffect.match({\n\t\t\t\tonSuccess: (text) => text,\n\t\t\t\tonFailure: () => null,\n\t\t\t}),\n\t\t);\n\t\tconst content = composeGitignore(existing, input);\n\t\tyield* emitOne({\n\t\t\tpath: input.path,\n\t\t\tcontent,\n\t\t\tmode: NON_SENSITIVE_FILE_MODE,\n\t\t\tparentMode: input.parentMode ?? NON_SENSITIVE_DIR_MODE,\n\t\t}).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(e) =>\n\t\t\t\t\tnew CodegenWriteFailed({\n\t\t\t\t\t\toutputPath: input.path,\n\t\t\t\t\t\tstage: 'gitignore',\n\t\t\t\t\t\tcause: e,\n\t\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t});\n\nconst extractUserBlock = (text: string): string | null => {\n\tconst startIdx = text.indexOf(USER_BLOCK_START);\n\tconst endIdx = text.indexOf(USER_BLOCK_END);\n\tif (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null;\n\t// Include both markers in the returned block.\n\tconst endLineEnd = text.indexOf('\\n', endIdx);\n\tconst stop = endLineEnd === -1 ? text.length : endLineEnd;\n\treturn text.slice(startIdx, stop);\n};\n"],"mappings":";;;;;AAkCA,MAAM,mBAAmB;AACzB,MAAM,iBAAiB;AAEvB,MAAM,qBAAqB,GAAG,iBAAiB,IAAI;AAEnD,MAAM,kBAAkB;CACvB;CACA;CACA;CACA;CACA;AACD,CAAC,CAAC,KAAK,IAAI;AAEX,MAAM,iBAAiB;CACtB;CACA;CACA;CACA;CACA;CACA;AACD,CAAC,CAAC,KAAK,IAAI;;;;;AAmBX,MAAa,oBAAoB,UAAyB,UAAkC;CAC3F,MAAM,YAAY,aAAa,OAAO,iBAAiB,QAAQ,IAAI;CACnE,MAAM,kBAAkB,CAAC,GAAG,MAAM,cAAc,CAAC,CAAC,KAAK;CACvD,MAAM,QAAuB,CAAC;CAC9B,IAAI,MAAM,cAAc,MAAM;EAE7B,MAAM,KAAK,cAAc;EACzB,MAAM,KAAK,EAAE;EACb,MAAM,KAAK,8DAA8D;EACzE,IAAI,gBAAgB,SAAS,GAAG;GAC/B,MAAM,KAAK,EAAE;GACb,MAAM,KAAK,yEAAyE;GACpF,KAAK,MAAM,KAAK,iBAAiB,MAAM,KAAK,CAAC;EAC9C;CACD,OAAO;EAEN,MAAM,KAAK,eAAe;EAC1B,MAAM,KAAK,EAAE;EACb,MAAM,KAAK,sDAAsD;EACjE,MAAM,KAAK,GAAG;EACd,MAAM,KAAK,+DAA+D;EAC1E,MAAM,KAAK,aAAa;EACxB,IAAI,gBAAgB,SAAS,GAAG;GAC/B,MAAM,KAAK,EAAE;GACb,MAAM,KAAK,sEAAsE;GACjF,KAAK,MAAM,KAAK,iBAAiB,MAAM,KAAK,CAAC;EAC9C;CACD;CACA,MAAM,KAAK,EAAE;CACb,MAAM,KAAK,cAAc,OAAO,YAAY,kBAAkB;CAC9D,OAAO,MAAM,KAAK,IAAI,IAAI;AAC3B;;;;AAKA,MAAa,kBACZ,UAEA,OAAO,IAAI,aAAa;CAQvB,MAAM,UAAU,iBAAiB,QANT,OADN,WAAW,WAAA,CACF,eAAe,MAAM,IAAI,CAAC,CAAC,KACrD,OAAO,MAAM;EACZ,YAAY,SAAS;EACrB,iBAAiB;CAClB,CAAC,CACF,GAC2C,KAAK;CAChD,OAAO,QAAQ;EACd,MAAM,MAAM;EACZ;EACA,MAAA;EACA,YAAY,MAAM,cAAA;CACnB,CAAC,CAAC,CAAC,KACF,OAAO,UACL,MACA,IAAI,mBAAmB;EACtB,YAAY,MAAM;EAClB,OAAO;EACP,OAAO;CACR,CAAC,CACH,CACD;AACD,CAAC;AAEF,MAAM,oBAAoB,SAAgC;CACzD,MAAM,WAAW,KAAK,QAAQ,gBAAgB;CAC9C,MAAM,SAAS,KAAK,QAAQ,cAAc;CAC1C,IAAI,aAAa,MAAM,WAAW,MAAM,SAAS,UAAU,OAAO;CAElE,MAAM,aAAa,KAAK,QAAQ,MAAM,MAAM;CAC5C,MAAM,OAAO,eAAe,KAAK,KAAK,SAAS;CAC/C,OAAO,KAAK,MAAM,UAAU,IAAI;AACjC"}

package/dist/orchestrators/codegen/id-config.mjs

@@ -0,0 +1,107 @@
+import { decodeJsonTextSync } from "../../substrate/runtime/runtime-decode.mjs";
+import { atomicWriteFile } from "../../substrate/runtime/atomic-write.mjs";
+import { Effect, Schema } from "effect";
+//#region src/orchestrators/codegen/id-config.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 `networks.<name>` entry — the connection coordinates for a
+*  network. Mirrors `SuiNetworkConfigEntry` (plugins/sui/codegen.ts);
+*  `rpc` is the load-bearing field the app reads synchronously at module
+*  load. */
+const IdConfigNetworkSchema = Schema.Struct({
+	rpc: Schema.String,
+	chainId: Schema.optional(Schema.String),
+	faucet: Schema.optional(Schema.NullOr(Schema.String)),
+	graphql: Schema.optional(Schema.NullOr(Schema.String))
+});
+/** One `packages.<name>` entry — the resolved package id plus any
+*  resolved object captures for the active network. */
+const IdConfigPackageSchema = 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 id-config round-trips through `JSON.stringify` into the
+*  vite `define` global, so the value space is exactly JSON. */
+const IdConfigJsonSchema = Schema.suspend(() => Schema.Union([
+	Schema.Null,
+	Schema.String,
+	Schema.Number,
+	Schema.Boolean,
+	Schema.Array(IdConfigJsonSchema),
+	Schema.Record(Schema.String, IdConfigJsonSchema)
+]));
+/** 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`/`accounts`/
+*  `mvrOverrides` fields — it carries the plugin live values the fixed
+*  channel can't (deepbook pool ids, coin types, walrus/seal endpoints). */
+const IdConfigValuesSchema = Schema.Record(Schema.String, Schema.Record(Schema.String, IdConfigJsonSchema));
+/** The id-config interchange shape. 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 IdConfigSchema = Schema.Struct({
+	/** Active network name (the `networks.<name>` key the app reads).
+	*  Load-bearing — an id-config MUST name its network + connection. */
+	network: Schema.String,
+	networks: Schema.Record(Schema.String, IdConfigNetworkSchema),
+	/** Resolved package ids (+ object captures). Optional, default `{}`: an
+	*  id-config 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, IdConfigPackageSchema).pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+	accounts: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+	/** MVR placeholder (`@local/<slug>`) → resolved id, for the active
+	*  network. An app feeds this straight into dapp-kit's
+	*  `mvr.overrides.packages`. Optional, default `{}` (see `packages`). */
+	mvrOverrides: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+	/** Generic resolver channel — `values[namespace][key]` carries
+	*  arbitrary live plugin JSON the typed fields above can't. Optional
+	*  so older id-config files (no `values`) still decode. */
+	values: Schema.optional(IdConfigValuesSchema)
+});
+/** Failure reading or decoding an id-config file. */
+var IdConfigError = class extends Schema.TaggedErrorClass()("IdConfigError", {
+	source: Schema.String,
+	message: Schema.String,
+	cause: Schema.optional(Schema.Defect)
+}) {};
+/** Canonical filename of the per-stack id-config under
+*  `.devstack/stacks/<name>/`. */
+const ID_CONFIG_FILENAME = "devstack-ids.json";
+/** Write the id-config as pretty JSON. Idempotent at the byte level for
+*  identical input (sorted by the caller's assembly order). */
+const writeIdConfig = (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 IdConfigError({
+		source: path,
+		message: "failed to write id-config",
+		cause
+	})));
+});
+/** Project a runtime-decode issue into the typed `IdConfigError`. */
+const mkIdConfigError = (issue) => new IdConfigError({
+	source: issue.source,
+	message: issue.message,
+	...issue.cause === void 0 ? {} : { cause: issue.cause }
+});
+/** Decode + validate an id-config from already-read JSON text. The single
+*  schema-decode seam every reader shares (the Vite plugin, the `dump-ids`
+*  verb, the codegen verb) so the parse-and-validate decision lives in ONE
+*  place rather than each caller hand-rolling `JSON.parse`. Throws
+*  `IdConfigError` on malformed JSON or a shape that violates
+*  `IdConfigSchema`. */
+const decodeIdConfig = (text) => decodeJsonTextSync(IdConfigSchema, text, {
+	source: ID_CONFIG_FILENAME,
+	mkError: mkIdConfigError
+});
+//#endregion
+export { ID_CONFIG_FILENAME, UNRESOLVED_ID, decodeIdConfig, writeIdConfig };
+
+//# sourceMappingURL=id-config.mjs.map

package/dist/orchestrators/codegen/id-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-config.mjs","names":[],"sources":["../../../src/orchestrators/codegen/id-config.ts"],"sourcesContent":["// The id-config 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, id-config?) → 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>/devstack-ids.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_IDS__` global.\n//   - INJECTOR: the vite plugin reads the live file (dev) or a committed\n//               id-config file (prod, via `ids`/`DEVSTACK_IDS_FILE`) and\n//               `define`s the global.\n//\n// The shape is the id-half of today's `config.ts`: networks (rpc + the\n// rest), per-package ids (+ captured object ids), account addresses, and\n// the MVR placeholder → id override map an app feeds dapp-kit.\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport { atomicWriteFile } from '../../substrate/runtime/atomic-write.ts';\nimport {\n\tdecodeJsonTextSync,\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 id-config round-trips through\n *  `JSON.stringify` into the injected `__DEVSTACK_IDS__` 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 `networks.<name>` entry — the connection coordinates for a\n *  network. Mirrors `SuiNetworkConfigEntry` (plugins/sui/codegen.ts);\n *  `rpc` is the load-bearing field the app reads synchronously at module\n *  load. */\nexport const IdConfigNetworkSchema = Schema.Struct({\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});\n\n/** One `packages.<name>` entry — the resolved package id plus any\n *  resolved object captures for the active network. */\nexport const IdConfigPackageSchema = 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 id-config 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 `IdConfigSchema`; `Codec<T>` defaults the decode/\n// encode services to `never`, matching the real (service-free) recursion.\nexport const IdConfigJsonSchema: 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(IdConfigJsonSchema),\n\t\tSchema.Record(Schema.String, IdConfigJsonSchema),\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`/`accounts`/\n *  `mvrOverrides` fields — it carries the plugin live values the fixed\n *  channel can't (deepbook pool ids, coin types, walrus/seal endpoints). */\nexport const IdConfigValuesSchema = Schema.Record(\n\tSchema.String,\n\tSchema.Record(Schema.String, IdConfigJsonSchema),\n);\n\n/** The id-config interchange shape. 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 IdConfigSchema = Schema.Struct({\n\t/** Active network name (the `networks.<name>` key the app reads).\n\t *  Load-bearing — an id-config MUST name its network + connection. */\n\tnetwork: Schema.String,\n\tnetworks: Schema.Record(Schema.String, IdConfigNetworkSchema),\n\t/** Resolved package ids (+ object captures). Optional, default `{}`: an\n\t *  id-config 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, IdConfigPackageSchema).pipe(\n\t\tSchema.withDecodingDefaultKey(Effect.succeed({})),\n\t),\n\taccounts: Schema.Record(Schema.String, Schema.String).pipe(\n\t\tSchema.withDecodingDefaultKey(Effect.succeed({})),\n\t),\n\t/** MVR placeholder (`@local/<slug>`) → resolved id, for the active\n\t *  network. An app feeds this straight into dapp-kit's\n\t *  `mvr.overrides.packages`. Optional, default `{}` (see `packages`). */\n\tmvrOverrides: Schema.Record(Schema.String, Schema.String).pipe(\n\t\tSchema.withDecodingDefaultKey(Effect.succeed({})),\n\t),\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 id-config files (no `values`) still decode. */\n\tvalues: Schema.optional(IdConfigValuesSchema),\n});\n\nexport type IdConfig = typeof IdConfigSchema.Type;\nexport type IdConfigNetwork = typeof IdConfigNetworkSchema.Type;\nexport type IdConfigPackage = typeof IdConfigPackageSchema.Type;\nexport type IdConfigValues = typeof IdConfigValuesSchema.Type;\n\n// -----------------------------------------------------------------------------\n// Error\n// -----------------------------------------------------------------------------\n\n/** Failure reading or decoding an id-config file. */\nexport class IdConfigError extends Schema.TaggedErrorClass<IdConfigError>()('IdConfigError', {\n\tsource: Schema.String,\n\tmessage: Schema.String,\n\tcause: Schema.optional(Schema.Defect),\n}) {}\n\n// -----------------------------------------------------------------------------\n// Read / write helpers\n// -----------------------------------------------------------------------------\n\n/** Canonical filename of the per-stack id-config under\n *  `.devstack/stacks/<name>/`. */\nexport const ID_CONFIG_FILENAME = 'devstack-ids.json';\n\n/** Write the id-config as pretty JSON. Idempotent at the byte level for\n *  identical input (sorted by the caller's assembly order). */\nexport const writeIdConfig = (\n\tpath: string,\n\tconfig: IdConfig,\n): Effect.Effect<void, IdConfigError, 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// id-config 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) => new IdConfigError({ source: path, message: 'failed to write id-config', cause }),\n\t\t\t),\n\t\t);\n\t});\n\n/** Project a runtime-decode issue into the typed `IdConfigError`. */\nconst mkIdConfigError = (issue: RuntimeDecodeIssue): IdConfigError =>\n\tnew IdConfigError({\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 an id-config from already-read JSON text. The single\n *  schema-decode seam every reader shares (the Vite plugin, the `dump-ids`\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 *  `IdConfigError` on malformed JSON or a shape that violates\n *  `IdConfigSchema`. */\nexport const decodeIdConfig = (text: string): IdConfig =>\n\tdecodeJsonTextSync(IdConfigSchema, text, {\n\t\tsource: ID_CONFIG_FILENAME,\n\t\tmkError: mkIdConfigError,\n\t});\n"],"mappings":";;;;;;;;AAwCA,MAAa,gBAAgB;;;;;AA8B7B,MAAa,wBAAwB,OAAO,OAAO;CAClD,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;AACtD,CAAC;;;AAID,MAAa,wBAAwB,OAAO,OAAO;CAClD,IAAI,OAAO;CACX,SAAS,OAAO,SAAS,OAAO,OAAO,OAAO,QAAQ,OAAO,MAAM,CAAC;AACrE,CAAC;;;;AASD,MAAa,qBAA8C,OAAO,cACjE,OAAO,MAAM;CACZ,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO,MAAM,kBAAkB;CAC/B,OAAO,OAAO,OAAO,QAAQ,kBAAkB;AAChD,CAAC,CACF;;;;;;;AAQA,MAAa,uBAAuB,OAAO,OAC1C,OAAO,QACP,OAAO,OAAO,OAAO,QAAQ,kBAAkB,CAChD;;;;AAKA,MAAa,iBAAiB,OAAO,OAAO;;;CAG3C,SAAS,OAAO;CAChB,UAAU,OAAO,OAAO,OAAO,QAAQ,qBAAqB;;;;;;;CAO5D,UAAU,OAAO,OAAO,OAAO,QAAQ,qBAAqB,CAAC,CAAC,KAC7D,OAAO,uBAAuB,OAAO,QAAQ,CAAC,CAAC,CAAC,CACjD;CACA,UAAU,OAAO,OAAO,OAAO,QAAQ,OAAO,MAAM,CAAC,CAAC,KACrD,OAAO,uBAAuB,OAAO,QAAQ,CAAC,CAAC,CAAC,CACjD;;;;CAIA,cAAc,OAAO,OAAO,OAAO,QAAQ,OAAO,MAAM,CAAC,CAAC,KACzD,OAAO,uBAAuB,OAAO,QAAQ,CAAC,CAAC,CAAC,CACjD;;;;CAIA,QAAQ,OAAO,SAAS,oBAAoB;AAC7C,CAAC;;AAYD,IAAa,gBAAb,cAAmC,OAAO,iBAAgC,CAAC,CAAC,iBAAiB;CAC5F,QAAQ,OAAO;CACf,SAAS,OAAO;CAChB,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CAAC,CAAC,CAAC,CAAC;;;AAQJ,MAAa,qBAAqB;;;AAIlC,MAAa,iBACZ,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,UAAU,IAAI,cAAc;EAAE,QAAQ;EAAM,SAAS;EAA6B;CAAM,CAAC,CAC3F,CACD;AACD,CAAC;;AAGF,MAAM,mBAAmB,UACxB,IAAI,cAAc;CACjB,QAAQ,MAAM;CACd,SAAS,MAAM;CACf,GAAI,MAAM,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,MAAM,MAAM;AAC3D,CAAC;;;;;;;AAQF,MAAa,kBAAkB,SAC9B,mBAAmB,gBAAgB,MAAM;CACxC,QAAQ;CACR,SAAS;AACV,CAAC"}

package/dist/orchestrators/codegen/output-location.mjs

@@ -1,38 +1,30 @@
-import { isAbsolute, resolve } from "node:path";
+import { stackSubpath } from "../../substrate/runtime/paths.mjs";
+import { join, resolve } from "node:path";
 //#region src/orchestrators/codegen/output-location.ts
-/** Default home-stack output dir (relative to `appRoot`). */
-const HOME_OUTPUT_SUBPATH = "src/generated";
-/** Resolve `<appRoot>/.devstack/stacks/<stack>/generated` for a
-*  non-home stack — sibling of that stack's manifest. */
-const nonHomeOutputDir = (appRoot, stack) => resolve(appRoot, ".devstack", "stacks", stack, "generated");
+/** The app-rooted base under which codegen authors its per-stack subtrees:
+*  `<appRoot>/.devstack`. Mirrors the substrate's `RuntimeRoot` base, but
+*  rooted at the app source tree (codegen output lives with the user's
+*  source, not in engine-private state). The `stacks/<stack>/...` shape is
+*  composed by the shared `stackSubpath` so the two authors (substrate at
+*  `RuntimeRoot`, codegen here) never drift. */
+const codegenStacksBase = (appRoot) => resolve(appRoot, ".devstack");
+/** Resolve `<appRoot>/.devstack/stacks/<stack>/generated-extras` — the
+*  dev-only + secret tree. Always under `.devstack`, so dev-extras never
+*  land in the committed `src/generated/` tree. */
+const extrasDirFor = (appRoot, stack) => stackSubpath(join, codegenStacksBase(appRoot), stack, "generated-extras");
 /**
-* Resolve the codegen output location for a stack. See the module
-* header for the rule. Pure — same inputs always yield the same
-* absolute paths.
-*
-* Precedence:
-*   1. Explicit `defineDevstack({ codegen.outputDir })` → honored
-*      verbatim (relative → resolved against `appRoot`). The explicit
-*      `stackSubdir` rides along.
-*   2. Home stack (`effectiveStack === homeStack`, or no `homeStack`
-*      declared) → `<appRoot>/src/generated`, `stackSubdir: null`.
-*   3. Non-home stack → `<appRoot>/.devstack/stacks/<effectiveStack>/generated`,
-*      `stackSubdir: null`.
+* Resolve the LIVE codegen output location for a stack. See the module
+* header for the rule. Pure — same inputs always yield the same absolute
+* path. A single fixed per-stack rule (no override): every live stack's
+* dev-only `generated-extras` tree lands under
+* `<appRoot>/.devstack/stacks/<effectiveStack>/generated-extras`. Boot
+* writes ONLY this tree (`emitExtras`); it never emits the committed
+* `src/generated` tree — that is owned solely by the stack-free `codegen`
+* verb (which resolves its own output path directly).
 */
 const resolveCodegenOutput = (input) => {
-	const { appRoot, effectiveStack, homeStack } = input;
-	const explicitStackSubdir = input.explicitStackSubdir ?? null;
-	if (input.explicitOutputDir !== void 0) {
-		const target = input.explicitOutputDir;
-		return {
-			outputDir: isAbsolute(target) ? target : resolve(appRoot, target),
-			stackSubdir: explicitStackSubdir
-		};
-	}
-	return {
-		outputDir: effectiveStack === (homeStack ?? effectiveStack) ? resolve(appRoot, HOME_OUTPUT_SUBPATH) : nonHomeOutputDir(appRoot, effectiveStack),
-		stackSubdir: null
-	};
+	const { appRoot, effectiveStack } = input;
+	return { extrasDir: extrasDirFor(appRoot, effectiveStack) };
 };
 //#endregion
 export { resolveCodegenOutput };

package/dist/orchestrators/codegen/output-location.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"output-location.mjs","names":[],"sources":["../../../src/orchestrators/codegen/output-location.ts"],"sourcesContent":["// Per-stack codegen output-location resolver.\n//\n// notes/per-stack-codegen-design.md §\"Output-location rule\": two stacks\n// of the same app must not emit Move codegen into the SAME\n// `src/generated/` dir — the second stack's `codegen.emitted` would\n// clobber the first's package-id / wallet-pair-token literals and break\n// the already-running app. This pure function is the single decision\n// point: it maps (appRoot, effective stack, home stack) → the output\n// dir codegen owns for THIS stack.\n//\n//   - Home stack (`effectiveStack === homeStack`, no explicit\n//     `--stack`/`$DEVSTACK_STACK` override) → `<appRoot>/src/generated`\n//     (canonical, unchanged, committed-ignored).\n//   - Non-home stack (`test`/`e2e`/`demo`/...) →\n//     `<appRoot>/.devstack/stacks/<effectiveStack>/generated` — a\n//     sibling of that stack's manifest at\n//     `.devstack/stacks/<stack>/manifest.json`, already gitignored +\n//     tsconfig-excluded.\n//   - An app that sets `codegen.outputDir` / `codegen.stackSubdir`\n//     explicitly (`defineDevstack({ codegen })`) keeps that behavior\n//     verbatim (back-compat escape hatch); per-stack isolation is then\n//     the app's responsibility.\n//\n// The decision is made ONCE here, at the boot seam where both the home\n// and effective stack names are in scope, and the resolved absolute\n// `outputDir` is then recorded in the per-stack manifest\n// (`codegen.generatedDir`) so the reader (the Vite plugin) consults the\n// SAME location the writer chose — read and write are gated by one\n// decision, not two. Pure + unit-testable; no `process.env`, no I/O.\n\nimport { isAbsolute, resolve } from 'node:path';\n\nexport interface ResolveCodegenOutputInput {\n\t/** The user application root — codegen output is resolved against\n\t *  it. */\n\treadonly appRoot: string;\n\t/** The stack the supervisor is actually running (the resolved\n\t *  identity's stack: explicit `--stack`/`$DEVSTACK_STACK` >\n\t *  `config.stackName` > inferred). */\n\treadonly effectiveStack: string;\n\t/** The config's declared `stackName` (`stack.options.stackName`).\n\t *  `undefined` when the config declares none — then there is no\n\t *  override to diverge from, so the run is treated as home. */\n\treadonly homeStack: string | undefined;\n\t/** Explicit `defineDevstack({ codegen: { outputDir } })` value, if\n\t *  the app pinned one. Honored verbatim (back-compat) — relative\n\t *  paths resolve against `appRoot`. */\n\treadonly explicitOutputDir?: string | undefined;\n\t/** Explicit `defineDevstack({ codegen: { stackSubdir } })` value, if\n\t *  the app pinned one. Passed through unchanged. */\n\treadonly explicitStackSubdir?: string | null | undefined;\n}\n\nexport interface ResolvedCodegenOutput {\n\t/** Absolute path to the directory codegen owns and overwrites for\n\t *  THIS stack. Recorded in the manifest as `codegen.generatedDir`. */\n\treadonly outputDir: string;\n\t/** Per-stack subdirectory under `outputDir`, threaded through to\n\t *  `CodegenRoot.stackSubdir` unchanged. `null` for the\n\t *  home/non-home default rules (the `.devstack/stacks/<stack>`\n\t *  location already isolates per stack, so no extra subdir is\n\t *  needed); only an explicit `defineDevstack({ codegen.stackSubdir })`\n\t *  populates it. */\n\treadonly stackSubdir: string | null;\n}\n\n/** Default home-stack output dir (relative to `appRoot`). */\nconst HOME_OUTPUT_SUBPATH = 'src/generated';\n\n/** Resolve `<appRoot>/.devstack/stacks/<stack>/generated` for a\n *  non-home stack — sibling of that stack's manifest. */\nconst nonHomeOutputDir = (appRoot: string, stack: string): string =>\n\tresolve(appRoot, '.devstack', 'stacks', stack, 'generated');\n\n/**\n * Resolve the codegen output location for a stack. See the module\n * header for the rule. Pure — same inputs always yield the same\n * absolute paths.\n *\n * Precedence:\n *   1. Explicit `defineDevstack({ codegen.outputDir })` → honored\n *      verbatim (relative → resolved against `appRoot`). The explicit\n *      `stackSubdir` rides along.\n *   2. Home stack (`effectiveStack === homeStack`, or no `homeStack`\n *      declared) → `<appRoot>/src/generated`, `stackSubdir: null`.\n *   3. Non-home stack → `<appRoot>/.devstack/stacks/<effectiveStack>/generated`,\n *      `stackSubdir: null`.\n */\nexport const resolveCodegenOutput = (input: ResolveCodegenOutputInput): ResolvedCodegenOutput => {\n\tconst { appRoot, effectiveStack, homeStack } = input;\n\tconst explicitStackSubdir = input.explicitStackSubdir ?? null;\n\n\t// (1) Explicit override wins — back-compat escape hatch. Per-stack\n\t// isolation is the app's responsibility once it pins `outputDir`.\n\tif (input.explicitOutputDir !== undefined) {\n\t\tconst target = input.explicitOutputDir;\n\t\treturn {\n\t\t\toutputDir: isAbsolute(target) ? target : resolve(appRoot, target),\n\t\t\tstackSubdir: explicitStackSubdir,\n\t\t};\n\t}\n\n\t// `homeStack === undefined` means the config declared no `stackName`,\n\t// so there is no config value for `effectiveStack` to diverge from —\n\t// the run is the home run by definition (it falls through to the\n\t// inferred/default stack with no explicit override). Collapse it to\n\t// `effectiveStack` so the equality below reads `true`.\n\tconst isHome = effectiveStack === (homeStack ?? effectiveStack);\n\n\t// (2) Home → canonical `src/generated`. (3) Non-home → per-stack\n\t// `.devstack/stacks/<stack>/generated`. Neither uses `stackSubdir`\n\t// (the `.devstack` path already isolates per stack); an explicit\n\t// `stackSubdir` only rides the explicit-outputDir branch above.\n\treturn {\n\t\toutputDir: isHome\n\t\t\t? resolve(appRoot, HOME_OUTPUT_SUBPATH)\n\t\t\t: nonHomeOutputDir(appRoot, effectiveStack),\n\t\tstackSubdir: null,\n\t};\n};\n"],"mappings":";;;AAmEA,MAAM,sBAAsB;;;AAI5B,MAAM,oBAAoB,SAAiB,UAC1C,QAAQ,SAAS,aAAa,UAAU,OAAO,YAAY;;;;;;;;;;;;;;;AAgB5D,MAAa,wBAAwB,UAA4D;CAChG,MAAM,EAAE,SAAS,gBAAgB,cAAc;CAC/C,MAAM,sBAAsB,MAAM,uBAAuB;AAIzD,KAAI,MAAM,sBAAsB,KAAA,GAAW;EAC1C,MAAM,SAAS,MAAM;AACrB,SAAO;GACN,WAAW,WAAW,OAAO,GAAG,SAAS,QAAQ,SAAS,OAAO;GACjE,aAAa;GACb;;AAcF,QAAO;EACN,WAPc,oBAAoB,aAAa,kBAQ5C,QAAQ,SAAS,oBAAoB,GACrC,iBAAiB,SAAS,eAAe;EAC5C,aAAa;EACb"}
+{"version":3,"file":"output-location.mjs","names":[],"sources":["../../../src/orchestrators/codegen/output-location.ts"],"sourcesContent":["// Per-stack codegen output-location resolver.\n//\n// Boot no longer runs codegen — `up` / `apply` write an id-config file to\n// `.devstack/stacks/<stack>/` instead. This resolver still owns the per-\n// stack `.devstack` dev tree (the `generated-extras` overlay the Vite\n// `@devstack-dev` alias reads). The COMMITTED `src/generated` tree is\n// written ONLY by the stack-free `codegen` verb, wired separately.\n//\n// This pure function is the single decision point for the per-stack dev\n// output dir: it maps (appRoot, effective stack) → the `.devstack` dir\n// codegen-adjacent dev artifacts own for THIS stack.\n//\n//   - Every live stack → `<appRoot>/.devstack/stacks/<effectiveStack>/generated-extras`\n//     — a sibling of that stack's manifest at\n//     `.devstack/stacks/<stack>/manifest.json`, already gitignored +\n//     tsconfig-excluded. Two stacks of the same app therefore never clobber\n//     each other's dev-only artifacts. There is NO output-dir override:\n//     `defineDevstack({ codegen })` exposes no public surface for the dev\n//     tree (boot writes only the per-stack `generated-extras` overlay + the\n//     id-config file), so the location is a single fixed per-stack rule.\n//\n// The resolved absolute `extrasDir` is recorded in the per-stack manifest\n// (`codegen.extrasDir`) so the reader (the Vite plugin's `@devstack-dev`\n// alias) consults the SAME location the writer chose. The committed\n// `src/generated` bindings tree is NOT recorded — the `@generated` alias\n// always resolves to it directly. Pure + unit-testable; no `process.env`,\n// no I/O.\n\nimport { join, resolve } from 'node:path';\n\nimport { stackSubpath } from '../../substrate/runtime/paths.ts';\n\n/** The app-rooted base under which codegen authors its per-stack subtrees:\n *  `<appRoot>/.devstack`. Mirrors the substrate's `RuntimeRoot` base, but\n *  rooted at the app source tree (codegen output lives with the user's\n *  source, not in engine-private state). The `stacks/<stack>/...` shape is\n *  composed by the shared `stackSubpath` so the two authors (substrate at\n *  `RuntimeRoot`, codegen here) never drift. */\nconst codegenStacksBase = (appRoot: string): string => resolve(appRoot, '.devstack');\n\nexport interface ResolveCodegenOutputInput {\n\t/** The user application root — codegen output is resolved against\n\t *  it. */\n\treadonly appRoot: string;\n\t/** The stack the supervisor is actually running (the resolved\n\t *  identity's stack: explicit `--stack`/`$DEVSTACK_STACK` >\n\t *  `config.stackName` > inferred). */\n\treadonly effectiveStack: string;\n}\n\nexport interface ResolvedCodegenOutput {\n\t/** Absolute path to the dev-only + secret `generated-extras` tree\n\t *  for THIS stack — always\n\t *  `<appRoot>/.devstack/stacks/<effectiveStack>/generated-extras`\n\t *  (gitignored + tsconfig-excluded already). Recorded in the\n\t *  manifest as `codegen.extrasDir`; reached via the `@devstack-dev`\n\t *  Vite alias. */\n\treadonly extrasDir: string;\n}\n\n/** Resolve `<appRoot>/.devstack/stacks/<stack>/generated-extras` — the\n *  dev-only + secret tree. Always under `.devstack`, so dev-extras never\n *  land in the committed `src/generated/` tree. */\nconst extrasDirFor = (appRoot: string, stack: string): string =>\n\tstackSubpath(join, codegenStacksBase(appRoot), stack, 'generated-extras');\n\n/**\n * Resolve the LIVE codegen output location for a stack. See the module\n * header for the rule. Pure — same inputs always yield the same absolute\n * path. A single fixed per-stack rule (no override): every live stack's\n * dev-only `generated-extras` tree lands under\n * `<appRoot>/.devstack/stacks/<effectiveStack>/generated-extras`. Boot\n * writes ONLY this tree (`emitExtras`); it never emits the committed\n * `src/generated` tree — that is owned solely by the stack-free `codegen`\n * verb (which resolves its own output path directly).\n */\nexport const resolveCodegenOutput = (input: ResolveCodegenOutputInput): ResolvedCodegenOutput => {\n\tconst { appRoot, effectiveStack } = input;\n\treturn {\n\t\textrasDir: extrasDirFor(appRoot, effectiveStack),\n\t};\n};\n"],"mappings":";;;;;;;;;AAsCA,MAAM,qBAAqB,YAA4B,QAAQ,SAAS,WAAW;;;;AAyBnF,MAAM,gBAAgB,SAAiB,UACtC,aAAa,MAAM,kBAAkB,OAAO,GAAG,OAAO,kBAAkB;;;;;;;;;;;AAYzE,MAAa,wBAAwB,UAA4D;CAChG,MAAM,EAAE,SAAS,mBAAmB;CACpC,OAAO,EACN,WAAW,aAAa,SAAS,cAAc,EAChD;AACD"}

package/dist/orchestrators/codegen/paths.mjs

@@ -33,7 +33,12 @@ const layerCodegenPaths = Layer.effect(CodegenPathsService, Effect.gen(function*
 	const root = yield* CodegenRoot;
 	const path = yield* Path.Path;
 	const outputDir = root.stackSubdir ? path.join(root.outputDir, root.stackSubdir) : root.outputDir;
-	const codegenLockFile = `${outputDir}.codegen.lock`;
+	const extrasDir = root.extrasDir;
+	const codegenLockFile = `${extrasDir}.codegen.lock`;
+	const resolveExtras = (outputPath) => Effect.gen(function* () {
+		yield* assertRelativeCodegenOutputPath(outputPath);
+		return path.join(extrasDir, outputPath);
+	});
 	const buildAt = (atRoot) => {
 		const bindingsDir = path.join(atRoot, "bindings");
 		const resolve = (outputPath) => Effect.gen(function* () {
@@ -46,7 +51,9 @@ const layerCodegenPaths = Layer.effect(CodegenPathsService, Effect.gen(function*
 			gitignoreFile: path.join(atRoot, ".gitignore"),
 			bindingsDir,
 			codegenLockFile,
+			extrasDir,
 			resolve,
+			resolveExtras,
 			resolveBindingsPackage,
 			withRoot: (newRoot) => buildAt(newRoot)
 		};

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

@@ -1 +1 @@
-{"version":3,"file":"paths.mjs","names":[],"sources":["../../../src/orchestrators/codegen/paths.ts"],"sourcesContent":["// Codegen output-path layout.\n//\n// Distilled-doc § \"All outputs land under a single user-chosen\n// directory (default `./src/generated/`)\" + §\"Stable output paths\".\n// One file owns the layout so emitters never assemble paths by hand.\n//\n// Default root is `<appRoot>/src/generated/`. Tests and parallel\n// stacks pin a per-test root; the substrate's `RuntimeRoot` is for\n// engine-private state (~/.devstack/...), NOT for codegen output.\n// Codegen output lives in the USER's source tree.\n\nimport { Context, Effect, Layer, Path } from 'effect';\n\nimport { CodegenPathConflict } from './errors.ts';\n\n/** Guard plugin-authored `CodegenableDecl.outputPath` against `..`\n *  traversal and absolute paths. Fails with a typed\n *  `CodegenPathConflict({kind:'non-relative'})` — defense-in-depth\n *  for the file-layout invariants. Called once inside `buildAt` so\n *  both the root bundle and any `withRoot`-rebased view enforce the\n *  same `..`-rejecting `resolve` discipline.\n *\n *  POSIX-only: devstack runs on POSIX filesystems (substrate paths\n *  are POSIX-shaped throughout), so this check intentionally inspects\n *  only `/`-rooted absolutes and the `..` substring. A Windows-style\n *  `'foo/bar\\\\..\\\\baz'` would slip past — that's accepted because\n *  devstack never executes on a Windows runtime.\n *\n *  STYLE_GUIDE §2 rule 5 — orchestrator failures are typed. */\nexport const assertRelativeCodegenOutputPath = (\n\toutputPath: string,\n): Effect.Effect<void, CodegenPathConflict> =>\n\toutputPath.includes('..') || outputPath.startsWith('/')\n\t\t? Effect.fail(\n\t\t\t\tnew CodegenPathConflict({\n\t\t\t\t\tkind: 'non-relative',\n\t\t\t\t\toutputPath,\n\t\t\t\t\temitters: [],\n\t\t\t\t}),\n\t\t\t)\n\t\t: Effect.void;\n\n/**\n * Codegen output root — the directory codegen owns and overwrites.\n * Pinned at boot time from the user's `defineDevstack` options\n * (default `./src/generated/` resolved against the app's cwd).\n *\n * Held as a service so emitters can yield it without a function\n * argument; mirrors the substrate's `RuntimeRoot` pattern.\n */\nexport interface CodegenRootShape {\n\t/** Absolute path to the output directory. The orchestrator\n\t *  manages it; the user never writes here. */\n\treadonly outputDir: string;\n\t/** Optional per-stack subdirectory under `outputDir`. When set,\n\t *  parallel stacks emit into sibling directories under the same\n\t *  output root (distilled-doc §\"per-stack subdirectory\"). */\n\treadonly stackSubdir: string | null;\n}\n\nexport class CodegenRoot extends Context.Service<CodegenRoot, CodegenRootShape>()(\n\t'@devstack/orchestrator/CodegenRoot',\n) {}\n\n/** Build a `CodegenRoot` layer pinned to a literal path. */\nexport const layerCodegenRoot = (root: CodegenRootShape): Layer.Layer<CodegenRoot> =>\n\tLayer.succeed(CodegenRoot)(root);\n\n/** Closed bundle the resolver returns. Mirrors substrate `StackPaths`. */\nexport interface CodegenPaths {\n\t/** The directory the orchestrator emits into (after applying\n\t *  per-stack subdirectory if configured). The watcher MUST\n\t *  exclude this directory. */\n\treadonly outputDir: string;\n\t/** Path to the `.gitignore` inside `outputDir`. Written every\n\t *  emit (the dir is gitignored). */\n\treadonly gitignoreFile: string;\n\t/** Subtree where Move-to-TS bindings land. */\n\treadonly bindingsDir: string;\n\t/** Per-process lock file gating `runEmitCycle`. Sibling to\n\t *  `outputDir` so concurrent invocations (e.g. CLI direct-callers\n\t *  racing the supervisor) serialize cleanly without blocking the\n\t *  short-section substrate `stack.lock`. Codegen cycles can be\n\t *  file-system heavy (multi-emitter, Move-bindings compilation);\n\t *  the substrate lock is reserved for short sections per the\n\t *  cross-process safety protocol. */\n\treadonly codegenLockFile: string;\n\t/** Helper: resolve an emitter's `outputPath` (e.g. `sui/network.ts`)\n\t *  against the output root. Fails with `CodegenPathConflict({kind:\n\t *  'non-relative'})` if the supplied path escapes the root. */\n\treadonly resolve: (outputPath: string) => Effect.Effect<string, CodegenPathConflict>;\n\t/** Helper: resolve a per-package bindings subtree path. */\n\treadonly resolveBindingsPackage: (packageName: string) => string;\n\t/** Data-driven rebase: re-root the entire bundle at `newRoot`.\n\t *  Preserves the layout (bindings under `<root>/bindings`, gitignore\n\t *  at `<root>/.gitignore`) and the `..`-rejecting `resolve`\n\t *  discipline; only the prefix changes. Used by the stage-and-swap\n\t *  build to redirect the emit pipeline at the staging directory\n\t *  WITHOUT string-surgery in the caller.\n\t *\n\t *  Note: `codegenLockFile` is preserved verbatim — the lock is\n\t *  acquired ONCE outside the staging build, so the rebased view\n\t *  must still name the real lock path. */\n\treadonly withRoot: (newRoot: string) => CodegenPaths;\n}\n\nexport class CodegenPathsService extends Context.Service<CodegenPathsService, CodegenPaths>()(\n\t'@devstack/orchestrator/CodegenPaths',\n) {}\n\n/**\n * Materialize the resolver from `CodegenRoot` + Effect's `Path`\n * service. Stack subdir, if present, is appended:\n *   `<outputDir>` or `<outputDir>/<stackSubdir>`.\n */\nexport const layerCodegenPaths: Layer.Layer<CodegenPathsService, never, CodegenRoot | Path.Path> =\n\tLayer.effect(\n\t\tCodegenPathsService,\n\t\tEffect.gen(function* () {\n\t\t\tconst root = yield* CodegenRoot;\n\t\t\tconst path = yield* Path.Path;\n\t\t\tconst outputDir = root.stackSubdir\n\t\t\t\t? path.join(root.outputDir, root.stackSubdir)\n\t\t\t\t: root.outputDir;\n\t\t\t// Sibling of `outputDir` (NOT inside it) so the stage-and-swap\n\t\t\t// rename never sees the lock file as part of the output tree.\n\t\t\t// Captured once at boot — `withRoot` re-roots the rest of the\n\t\t\t// bundle but preserves the original lock path so the rebased\n\t\t\t// view names the real cross-process lock (the lock is acquired\n\t\t\t// ONCE outside the staging build).\n\t\t\tconst codegenLockFile = `${outputDir}.codegen.lock`;\n\t\t\tconst buildAt = (atRoot: string): CodegenPaths => {\n\t\t\t\tconst bindingsDir = path.join(atRoot, 'bindings');\n\t\t\t\tconst resolve = (outputPath: string): Effect.Effect<string, CodegenPathConflict> =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* assertRelativeCodegenOutputPath(outputPath);\n\t\t\t\t\t\treturn path.join(atRoot, outputPath);\n\t\t\t\t\t});\n\t\t\t\tconst resolveBindingsPackage = (packageName: string): string =>\n\t\t\t\t\tpath.join(bindingsDir, packageName);\n\t\t\t\tconst bundle: CodegenPaths = {\n\t\t\t\t\toutputDir: atRoot,\n\t\t\t\t\tgitignoreFile: path.join(atRoot, '.gitignore'),\n\t\t\t\t\tbindingsDir,\n\t\t\t\t\tcodegenLockFile,\n\t\t\t\t\tresolve,\n\t\t\t\t\tresolveBindingsPackage,\n\t\t\t\t\twithRoot: (newRoot: string) => buildAt(newRoot),\n\t\t\t\t};\n\t\t\t\treturn bundle;\n\t\t\t};\n\t\t\treturn CodegenPathsService.of(buildAt(outputDir));\n\t\t}),\n\t);\n"],"mappings":";;;;;;;;;;;;;;;;;AA6BA,MAAa,mCACZ,eAEA,WAAW,SAAS,KAAK,IAAI,WAAW,WAAW,IAAI,GACpD,OAAO,KACP,IAAI,oBAAoB;CACvB,MAAM;CACN;CACA,UAAU,EAAE;CACZ,CAAC,CACF,GACA,OAAO;AAoBX,IAAa,cAAb,cAAiC,QAAQ,SAAwC,CAChF,qCACA,CAAC;;AAGF,MAAa,oBAAoB,SAChC,MAAM,QAAQ,YAAY,CAAC,KAAK;AAwCjC,IAAa,sBAAb,cAAyC,QAAQ,SAA4C,CAC5F,sCACA,CAAC;;;;;;AAOF,MAAa,oBACZ,MAAM,OACL,qBACA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO;CACpB,MAAM,OAAO,OAAO,KAAK;CACzB,MAAM,YAAY,KAAK,cACpB,KAAK,KAAK,KAAK,WAAW,KAAK,YAAY,GAC3C,KAAK;CAOR,MAAM,kBAAkB,GAAG,UAAU;CACrC,MAAM,WAAW,WAAiC;EACjD,MAAM,cAAc,KAAK,KAAK,QAAQ,WAAW;EACjD,MAAM,WAAW,eAChB,OAAO,IAAI,aAAa;AACvB,UAAO,gCAAgC,WAAW;AAClD,UAAO,KAAK,KAAK,QAAQ,WAAW;IACnC;EACH,MAAM,0BAA0B,gBAC/B,KAAK,KAAK,aAAa,YAAY;AAUpC,SAAO;GARN,WAAW;GACX,eAAe,KAAK,KAAK,QAAQ,aAAa;GAC9C;GACA;GACA;GACA;GACA,WAAW,YAAoB,QAAQ,QAAQ;GAEnC;;AAEd,QAAO,oBAAoB,GAAG,QAAQ,UAAU,CAAC;EAChD,CACF"}
+{"version":3,"file":"paths.mjs","names":[],"sources":["../../../src/orchestrators/codegen/paths.ts"],"sourcesContent":["// Codegen output-path layout.\n//\n// Distilled-doc § \"All outputs land under a single user-chosen\n// directory (default `./src/generated/`)\" + §\"Stable output paths\".\n// One file owns the layout so emitters never assemble paths by hand.\n//\n// Default root is `<appRoot>/src/generated/`. Tests and parallel\n// stacks pin a per-test root; the substrate's `RuntimeRoot` is for\n// engine-private state (~/.devstack/...), NOT for codegen output.\n// Codegen output lives in the USER's source tree.\n\nimport { Context, Effect, Layer, Path } from 'effect';\n\nimport { CodegenPathConflict } from './errors.ts';\n\n/** Guard plugin-authored `CodegenableDecl.outputPath` against `..`\n *  traversal and absolute paths. Fails with a typed\n *  `CodegenPathConflict({kind:'non-relative'})` — defense-in-depth\n *  for the file-layout invariants. Called once inside `buildAt` so\n *  both the root bundle and any `withRoot`-rebased view enforce the\n *  same `..`-rejecting `resolve` discipline.\n *\n *  POSIX-only: devstack runs on POSIX filesystems (substrate paths\n *  are POSIX-shaped throughout), so this check intentionally inspects\n *  only `/`-rooted absolutes and the `..` substring. A Windows-style\n *  `'foo/bar\\\\..\\\\baz'` would slip past — that's accepted because\n *  devstack never executes on a Windows runtime.\n *\n *  STYLE_GUIDE §2 rule 5 — orchestrator failures are typed. */\nexport const assertRelativeCodegenOutputPath = (\n\toutputPath: string,\n): Effect.Effect<void, CodegenPathConflict> =>\n\toutputPath.includes('..') || outputPath.startsWith('/')\n\t\t? Effect.fail(\n\t\t\t\tnew CodegenPathConflict({\n\t\t\t\t\tkind: 'non-relative',\n\t\t\t\t\toutputPath,\n\t\t\t\t\temitters: [],\n\t\t\t\t}),\n\t\t\t)\n\t\t: Effect.void;\n\n/**\n * Codegen output root — the directory codegen owns and overwrites.\n * Pinned at boot time from the user's `defineDevstack` options\n * (default `./src/generated/` resolved against the app's cwd).\n *\n * Held as a service so emitters can yield it without a function\n * argument; mirrors the substrate's `RuntimeRoot` pattern.\n */\nexport interface CodegenRootShape {\n\t/** Absolute path to the output directory. The orchestrator\n\t *  manages it; the user never writes here. */\n\treadonly outputDir: string;\n\t/** Optional per-stack subdirectory under `outputDir`. When set,\n\t *  parallel stacks emit into sibling directories under the same\n\t *  output root (distilled-doc §\"per-stack subdirectory\"). */\n\treadonly stackSubdir: string | null;\n\t/** Absolute path to the dev-only + secret `generated-extras` tree\n\t *  (`.devstack/stacks/<stack>/generated-extras`). Decls / aggregates\n\t *  with `outputLocation: 'generated-extras'` emit here. Outside the\n\t *  staging-and-swap tree of `outputDir` — extras are gitignored and\n\t *  written in place (no atomic swap), so warm restarts never churn\n\t *  the runtime tree's mtimes. */\n\treadonly extrasDir: string;\n}\n\nexport class CodegenRoot extends Context.Service<CodegenRoot, CodegenRootShape>()(\n\t'@devstack/orchestrator/CodegenRoot',\n) {}\n\n/** Build a `CodegenRoot` layer pinned to a literal path. */\nexport const layerCodegenRoot = (root: CodegenRootShape): Layer.Layer<CodegenRoot> =>\n\tLayer.succeed(CodegenRoot)(root);\n\n/** Closed bundle the resolver returns. Mirrors substrate `StackPaths`. */\nexport interface CodegenPaths {\n\t/** The directory the orchestrator emits into (after applying\n\t *  per-stack subdirectory if configured). The watcher MUST\n\t *  exclude this directory. */\n\treadonly outputDir: string;\n\t/** Path to the `.gitignore` inside `outputDir`. Written every\n\t *  emit (the dir is gitignored). */\n\treadonly gitignoreFile: string;\n\t/** Subtree where Move-to-TS bindings land. */\n\treadonly bindingsDir: string;\n\t/** Per-process lock file gating `runEmitCycle`. Sibling to\n\t *  `outputDir` so concurrent invocations (e.g. CLI direct-callers\n\t *  racing the supervisor) serialize cleanly without blocking the\n\t *  short-section substrate `stack.lock`. Codegen cycles can be\n\t *  file-system heavy (multi-emitter, Move-bindings compilation);\n\t *  the substrate lock is reserved for short sections per the\n\t *  cross-process safety protocol. */\n\treadonly codegenLockFile: string;\n\t/** The dev-only + secret `generated-extras` tree. Decls /\n\t *  aggregates with `outputLocation: 'generated-extras'` resolve\n\t *  against this. Preserved verbatim across `withRoot` — the extras\n\t *  tree lives OUTSIDE the staging-and-swap of `outputDir`, so the\n\t *  staging rebase must still name the real extras dir. */\n\treadonly extrasDir: string;\n\t/** Helper: resolve an emitter's `outputPath` (e.g. `config.ts`)\n\t *  against the output root. Fails with `CodegenPathConflict({kind:\n\t *  'non-relative'})` if the supplied path escapes the root. */\n\treadonly resolve: (outputPath: string) => Effect.Effect<string, CodegenPathConflict>;\n\t/** Helper: resolve an emitter's `outputPath` against the\n\t *  `generated-extras` tree (`extrasDir`). Same `..`-rejecting\n\t *  discipline as `resolve`. */\n\treadonly resolveExtras: (outputPath: string) => Effect.Effect<string, CodegenPathConflict>;\n\t/** Helper: resolve a per-package bindings subtree path. */\n\treadonly resolveBindingsPackage: (packageName: string) => string;\n\t/** Data-driven rebase: re-root the entire bundle at `newRoot`.\n\t *  Preserves the layout (bindings under `<root>/bindings`, gitignore\n\t *  at `<root>/.gitignore`) and the `..`-rejecting `resolve`\n\t *  discipline; only the prefix changes. Used by the stage-and-swap\n\t *  build to redirect the emit pipeline at the staging directory\n\t *  WITHOUT string-surgery in the caller.\n\t *\n\t *  Note: `codegenLockFile` is preserved verbatim — the lock is\n\t *  acquired ONCE outside the staging build, so the rebased view\n\t *  must still name the real lock path. */\n\treadonly withRoot: (newRoot: string) => CodegenPaths;\n}\n\nexport class CodegenPathsService extends Context.Service<CodegenPathsService, CodegenPaths>()(\n\t'@devstack/orchestrator/CodegenPaths',\n) {}\n\n/**\n * Materialize the resolver from `CodegenRoot` + Effect's `Path`\n * service. Stack subdir, if present, is appended:\n *   `<outputDir>` or `<outputDir>/<stackSubdir>`.\n */\nexport const layerCodegenPaths: Layer.Layer<CodegenPathsService, never, CodegenRoot | Path.Path> =\n\tLayer.effect(\n\t\tCodegenPathsService,\n\t\tEffect.gen(function* () {\n\t\t\tconst root = yield* CodegenRoot;\n\t\t\tconst path = yield* Path.Path;\n\t\t\tconst outputDir = root.stackSubdir\n\t\t\t\t? path.join(root.outputDir, root.stackSubdir)\n\t\t\t\t: root.outputDir;\n\t\t\t// Captured once at boot. Preserved verbatim through `withRoot`\n\t\t\t// (the extras tree is OUTSIDE the staging swap of `outputDir`,\n\t\t\t// so the rebased view must keep naming the real extras dir).\n\t\t\tconst extrasDir = root.extrasDir;\n\t\t\t// Lock the codegen subsystem on a sibling of `extrasDir`, NOT of\n\t\t\t// `outputDir`. At BOOT nothing is ever emitted into the live\n\t\t\t// `outputDir` (`generated`) tree — boot's only codegen write is\n\t\t\t// `emitExtras`, which lands in `extrasDir` — so deriving the lock\n\t\t\t// from `extrasDir` keeps the live `generated` basename entirely\n\t\t\t// out of the boot footprint (no phantom `…/generated.codegen.lock`\n\t\t\t// next to a directory that is never created). The `codegen` verb\n\t\t\t// (the one path that DOES stage into `<outputDir>.staging.<id>`)\n\t\t\t// still gets a stable sibling lock — `<extrasDir>.codegen.lock` —\n\t\t\t// outside both its `outputDir` swap and the `extrasDir` tree.\n\t\t\t// Sibling-NOT-inside is what matters for the stage-and-swap rename\n\t\t\t// of `outputDir`, and an `extrasDir` sibling satisfies that.\n\t\t\t// Captured once at boot — `withRoot` re-roots the rest of the\n\t\t\t// bundle but preserves this lock path verbatim so the rebased\n\t\t\t// staging view names the real cross-process lock (the lock is\n\t\t\t// acquired ONCE outside the staging build).\n\t\t\tconst codegenLockFile = `${extrasDir}.codegen.lock`;\n\t\t\tconst resolveExtras = (outputPath: string): Effect.Effect<string, CodegenPathConflict> =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tyield* assertRelativeCodegenOutputPath(outputPath);\n\t\t\t\t\treturn path.join(extrasDir, outputPath);\n\t\t\t\t});\n\t\t\tconst buildAt = (atRoot: string): CodegenPaths => {\n\t\t\t\tconst bindingsDir = path.join(atRoot, 'bindings');\n\t\t\t\tconst resolve = (outputPath: string): Effect.Effect<string, CodegenPathConflict> =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* assertRelativeCodegenOutputPath(outputPath);\n\t\t\t\t\t\treturn path.join(atRoot, outputPath);\n\t\t\t\t\t});\n\t\t\t\tconst resolveBindingsPackage = (packageName: string): string =>\n\t\t\t\t\tpath.join(bindingsDir, packageName);\n\t\t\t\tconst bundle: CodegenPaths = {\n\t\t\t\t\toutputDir: atRoot,\n\t\t\t\t\tgitignoreFile: path.join(atRoot, '.gitignore'),\n\t\t\t\t\tbindingsDir,\n\t\t\t\t\tcodegenLockFile,\n\t\t\t\t\textrasDir,\n\t\t\t\t\tresolve,\n\t\t\t\t\tresolveExtras,\n\t\t\t\t\tresolveBindingsPackage,\n\t\t\t\t\twithRoot: (newRoot: string) => buildAt(newRoot),\n\t\t\t\t};\n\t\t\t\treturn bundle;\n\t\t\t};\n\t\t\treturn CodegenPathsService.of(buildAt(outputDir));\n\t\t}),\n\t);\n"],"mappings":";;;;;;;;;;;;;;;;;AA6BA,MAAa,mCACZ,eAEA,WAAW,SAAS,IAAI,KAAK,WAAW,WAAW,GAAG,IACnD,OAAO,KACP,IAAI,oBAAoB;CACvB,MAAM;CACN;CACA,UAAU,CAAC;AACZ,CAAC,CACF,IACC,OAAO;AA2BX,IAAa,cAAb,cAAiC,QAAQ,QAAuC,CAAC,CAChF,oCACD,CAAC,CAAC,CAAC;;AAGH,MAAa,oBAAoB,SAChC,MAAM,QAAQ,WAAW,CAAC,CAAC,IAAI;AAkDhC,IAAa,sBAAb,cAAyC,QAAQ,QAA2C,CAAC,CAC5F,qCACD,CAAC,CAAC,CAAC;;;;;;AAOH,MAAa,oBACZ,MAAM,OACL,qBACA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO;CACpB,MAAM,OAAO,OAAO,KAAK;CACzB,MAAM,YAAY,KAAK,cACpB,KAAK,KAAK,KAAK,WAAW,KAAK,WAAW,IAC1C,KAAK;CAIR,MAAM,YAAY,KAAK;CAiBvB,MAAM,kBAAkB,GAAG,UAAU;CACrC,MAAM,iBAAiB,eACtB,OAAO,IAAI,aAAa;EACvB,OAAO,gCAAgC,UAAU;EACjD,OAAO,KAAK,KAAK,WAAW,UAAU;CACvC,CAAC;CACF,MAAM,WAAW,WAAiC;EACjD,MAAM,cAAc,KAAK,KAAK,QAAQ,UAAU;EAChD,MAAM,WAAW,eAChB,OAAO,IAAI,aAAa;GACvB,OAAO,gCAAgC,UAAU;GACjD,OAAO,KAAK,KAAK,QAAQ,UAAU;EACpC,CAAC;EACF,MAAM,0BAA0B,gBAC/B,KAAK,KAAK,aAAa,WAAW;EAYnC,OAAO;GAVN,WAAW;GACX,eAAe,KAAK,KAAK,QAAQ,YAAY;GAC7C;GACA;GACA;GACA;GACA;GACA;GACA,WAAW,YAAoB,QAAQ,OAAO;EAEnC;CACb;CACA,OAAO,oBAAoB,GAAG,QAAQ,SAAS,CAAC;AACjD,CAAC,CACF"}

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

@@ -1 +1 @@
-{"version":3,"file":"permissions.mjs","names":[],"sources":["../../../src/orchestrators/codegen/permissions.ts"],"sourcesContent":["// Permission policy for codegen-emitted files.\n//\n// Distilled-doc § \"Sensitive emitted files have restrictive\n// filesystem permissions, re-applied on every emit (not just on\n// create) to recover from manual chmods\". The orchestrator hands the\n// emit/swap layer the mode it should apply.\n//\n// Two-axis policy:\n//   - `sensitive: true` → 0o600 (rw user only).\n//   - `sensitive: false` → 0o644 (rw user, r world).\n// The parent directory the emit lives in inherits the strictest\n// sensitivity of any file inside it — 0o700 when any file is\n// sensitive, 0o755 otherwise. The orchestrator applies parent mode\n// at swap time, separate from per-file modes.\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\nexport const SENSITIVE_FILE_MODE = 0o600;\nexport const NON_SENSITIVE_FILE_MODE = 0o644;\nexport const SENSITIVE_DIR_MODE = 0o700;\nexport const NON_SENSITIVE_DIR_MODE = 0o755;\n\n/** File mode for one codegen contribution. */\nexport const modeFor = (decl: Pick<CodegenableDecl, 'sensitive'>): number =>\n\tdecl.sensitive === true ? SENSITIVE_FILE_MODE : NON_SENSITIVE_FILE_MODE;\n\n/** Parent-directory mode given a set of contributions inside it. */\nexport const dirModeFor = (decls: ReadonlyArray<Pick<CodegenableDecl, 'sensitive'>>): number =>\n\tdecls.some((d) => d.sensitive === true) ? SENSITIVE_DIR_MODE : NON_SENSITIVE_DIR_MODE;\n\n/** True if ANY contribution in the set is sensitive — gates the\n *  `.gitignore` \"cover by default\" rule and the parent-mode policy. */\nexport const anySensitive = (decls: ReadonlyArray<Pick<CodegenableDecl, 'sensitive'>>): boolean =>\n\tdecls.some((d) => d.sensitive === true);\n"],"mappings":";AAuBA,MAAa,WAAW,SACvB,KAAK,cAAc,OAAA,MAAA;;AAGpB,MAAa,cAAc,UAC1B,MAAM,MAAM,MAAM,EAAE,cAAc,KAAK,GAAA,MAAA"}
+{"version":3,"file":"permissions.mjs","names":[],"sources":["../../../src/orchestrators/codegen/permissions.ts"],"sourcesContent":["// Permission policy for codegen-emitted files.\n//\n// Distilled-doc § \"Sensitive emitted files have restrictive\n// filesystem permissions, re-applied on every emit (not just on\n// create) to recover from manual chmods\". The orchestrator hands the\n// emit/swap layer the mode it should apply.\n//\n// Two-axis policy:\n//   - `sensitive: true` → 0o600 (rw user only).\n//   - `sensitive: false` → 0o644 (rw user, r world).\n// The parent directory the emit lives in inherits the strictest\n// sensitivity of any file inside it — 0o700 when any file is\n// sensitive, 0o755 otherwise. The orchestrator applies parent mode\n// at swap time, separate from per-file modes.\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\nexport const SENSITIVE_FILE_MODE = 0o600;\nexport const NON_SENSITIVE_FILE_MODE = 0o644;\nexport const SENSITIVE_DIR_MODE = 0o700;\nexport const NON_SENSITIVE_DIR_MODE = 0o755;\n\n/** File mode for one codegen contribution. */\nexport const modeFor = (decl: Pick<CodegenableDecl, 'sensitive'>): number =>\n\tdecl.sensitive === true ? SENSITIVE_FILE_MODE : NON_SENSITIVE_FILE_MODE;\n\n/** Parent-directory mode given a set of contributions inside it. */\nexport const dirModeFor = (decls: ReadonlyArray<Pick<CodegenableDecl, 'sensitive'>>): number =>\n\tdecls.some((d) => d.sensitive === true) ? SENSITIVE_DIR_MODE : NON_SENSITIVE_DIR_MODE;\n\n/** True if ANY contribution in the set is sensitive — gates the\n *  `.gitignore` \"cover by default\" rule and the parent-mode policy. */\nexport const anySensitive = (decls: ReadonlyArray<Pick<CodegenableDecl, 'sensitive'>>): boolean =>\n\tdecls.some((d) => d.sensitive === true);\n"],"mappings":";AAuBA,MAAa,WAAW,SACvB,KAAK,cAAc,OAAA,MAAA;;AAGpB,MAAa,cAAc,UAC1B,MAAM,MAAM,MAAM,EAAE,cAAc,IAAI,IAAA,MAAA"}