@orkestrel/scaffold 0.0.25 → 0.0.27

package/dist/src/core/index.cjs

@@ -140,6 +140,25 @@ var HOST_PATHS = Object.freeze([
 	"guides/scaffold.md"
 ]);
 /**
+* The vendored paths a target receives with its executable bit set, frozen.
+*
+* @remarks
+* Declared rather than read from the staging host's filesystem, because that
+* reading is not portable: Windows carries no executable bit, so a host staged
+* there reports every file non-executable and every target receives hooks it
+* cannot run. Declaring the set here makes one checkout stage one manifest on
+* every host.
+*
+* Every entry is also a {@link HOST_PATHS} member or sits beneath one. A file
+* that must run when a target invokes it belongs here the moment it is vendored.
+*/
+var EXECUTABLE_PATHS = Object.freeze([
+	"scripts/codex.sh",
+	"scripts/cursor.sh",
+	"scripts/deps.sh",
+	"scripts/ollama.sh"
+]);
+/**
 * The path prefixes whose contents instruct or wire an agent, frozen.
 *
 * @remarks
@@ -227,7 +246,7 @@ var ENGINES_PATTERN = /^>=(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 var HEX_PATTERN = /^(?:[0-9a-f]{2})*$/;
 /** Unicode controls, formatting controls, and line and paragraph separators rejected in text. */
 var CONTROL_CHARACTER_PATTERN = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
-/** Visible characters a portable path and a Markdown path cell both forbid. */
+/** Visible characters a target-relative path and a Markdown path cell both forbid. */
 var INVALID_PATH_CHARACTER_PATTERN = /[<>:"|?*\\]/;
 /**
 * Maximum bare workspace name length.
@@ -245,6 +264,8 @@ var MAX_RANGE_LENGTH = 2048;
 var MAX_PATH_LENGTH = 32767;
 /** Maximum items accepted in one public collection. */
 var MAX_COLLECTION_ITEMS = 1e3;
+/** Maximum findings one audit can produce from a bounded plan and snapshot. */
+var MAX_AUDIT_FINDINGS = MAX_COLLECTION_ITEMS * 2;
 /** Maximum bytes accepted for one artifact. */
 var MAX_ARTIFACT_BYTES = 5242880;
 /** Maximum length of the hexadecimal string carrying one artifact's bytes. */
@@ -262,8 +283,8 @@ var DEFAULT_ENGINES = `>=${MINIMUM_NODE_VERSION}`;
 /** The tooling versions scaffold and every generated workspace share. */
 var BASE_DEV_DEPENDENCIES = Object.freeze({
 	"@microsoft/api-extractor": "^7.58.12",
-	"@orkestrel/guide": "^0.0.9",
-	"@orkestrel/scaffold": "^0.0.25",
+	"@orkestrel/guide": "^0.0.10",
+	"@orkestrel/scaffold": "^0.0.27",
 	"@types/node": "^26.2.0",
 	oxfmt: "^0.62.0",
 	oxlint: "^1.77.0",
@@ -278,11 +299,11 @@ var SOURCE_BROWSER_DEV_DEPENDENCIES = Object.freeze({
 	playwright: "^1.62.1"
 });
 /** The development dependency every private `app` environment adds. */
-var APP_DEV_DEPENDENCIES = Object.freeze({ "@orkestrel/contract": "^0.0.10" });
+var APP_DEV_DEPENDENCIES = Object.freeze({ "@orkestrel/contract": "^0.0.11" });
 /** The development dependencies a private Vue browser application adds. */
 var APP_BROWSER_DEV_DEPENDENCIES = Object.freeze({
 	...SOURCE_BROWSER_DEV_DEPENDENCIES,
-	"@orkestrel/html": "^0.0.2",
+	"@orkestrel/html": "^0.0.3",
 	"@vitejs/plugin-vue": "^6.0.8",
 	vue: "^3.5.40",
 	"vue-tsc": "^3.3.7"
@@ -300,10 +321,10 @@ var APP_BROWSER_DEV_DEPENDENCIES = Object.freeze({
 var SHOWCASE_DEV_DEPENDENCIES = Object.freeze({ "vite-plugin-singlefile": "^2.3.3" });
 /** The development dependencies a private server application adds. */
 var APP_SERVER_DEV_DEPENDENCIES = Object.freeze({
-	"@orkestrel/emitter": "^0.0.5",
-	"@orkestrel/middleware": "^0.0.9",
-	"@orkestrel/router": "^0.0.8",
-	"@orkestrel/server": "^0.0.10"
+	"@orkestrel/emitter": "^0.0.6",
+	"@orkestrel/middleware": "^0.0.10",
+	"@orkestrel/router": "^0.0.9",
+	"@orkestrel/server": "^0.0.11"
 });
 //#endregion
 //#region src/core/templates.ts
@@ -356,12 +377,10 @@ var CONFIG_TEMPLATES = Object.freeze({
 	"exclude": ["node_modules", "dist", "tmp"]
 }
 `,
-		vite: `import type { UserConfig } from 'vite'
-{{imports}}
-import { defineConfig, mergeConfig } from 'vitest/config'
+		vite: `import type { {{viteTypes}} } from 'vite'
+{{imports}}import { defineConfig, mergeConfig } from 'vitest/config'
 import tsconfig from './tsconfig.json' with { type: 'json' }
-import { environmentBoundary, outputBoundary } from './configs/helpers.js'
-import { lstatSync, readdirSync, realpathSync } from 'node:fs'
+{{helpers}}import { lstatSync, readdirSync, realpathSync } from 'node:fs'
 import { basename, join, parse, relative, resolve as resolvePath, sep } from 'node:path'
 import { fileURLToPath, URL } from 'node:url'
 
@@ -553,14 +572,9 @@ const resolve = {
 `,
 			browser: `function applicationBrowser(showcase: boolean): UserConfig {
 	const output = showcase ? 'dist/showcase' : 'dist/app/browser'
-	return {
+{{showcasePlugins}}	return {
 		resolve,
-		plugins: [
-			outputBoundary(output),
-			environmentBoundary('app/browser'),
-			vue(),
-{{showcasePlugin}}		],
-		root: resolveWorkspacePath('app/browser'),
+{{plugins}}		root: resolveWorkspacePath('app/browser'),
 		publicDir: false,
 		build: {
 {{showcaseBuild}}			emptyOutDir: true,
@@ -943,9 +957,13 @@ export default defineConfig(appShowcase())
 *
 * @remarks
 * Builders in `compilers.ts` fill every varying span through
-* `@orkestrel/template`. Empty barrels and setup modules are intentional: the
-* generated workspace starts with no sample domain API, while each selected
-* Vitest project gets a real test that proves its barrel has no starter exports.
+* `@orkestrel/template`. Empty barrels, entries, and setup modules are
+* intentional: the generated workspace starts with no sample domain API, while
+* each selected Vitest project gets a real test that proves its barrel has no
+* starter exports. An entry starts empty for the same reason its barrel does,
+* and because the vendored lint config refuses an unassigned import outside a
+* stylesheet, so a starter `import './index.js'` would fail the workspace's own
+* `lint:check` on the day it is written.
 *
 * @example
 * ```ts
@@ -957,8 +975,6 @@ export default defineConfig(appShowcase())
 var ARTIFACT_TEMPLATES = Object.freeze({
 	source: Object.freeze({
 		empty: "",
-		main: `import './index.js'
-`,
 		browser: `<!doctype html>
 <html lang="en">
 	<head>
@@ -1143,16 +1159,20 @@ printf '%s\\n' \\
 * The one error this package throws, carrying the coded reason it was raised.
 *
 * @remarks
-* A throw is reserved for a caller the package cannot serve: `INVALID` for
-* off-contract input, `DESTROYED` for any call made after teardown, `TARGET`
-* for a destination that is not what the caller's observation said it was,
-* `WRITE` for a mutation that could not be completed, and `FETCH` for an
-* upstream read that produced no answer the caller can be given.
-*
-* A refused blueprint is not one of these. The gate fails closed and returns
-* the questions that closed it, and `BLOCKED` is the code those stage records
-* carry, so a caller reads a refusal from the value it asked for rather than
-* from a stack.
+* Each code names one cause: `INVALID` for off-contract input, `DESTROYED` for
+* any call made after teardown, `TARGET` for a destination that is not what the
+* caller's observation said it was, `WRITE` for a mutation that could not be
+* completed, `FETCH` for an upstream read that produced no answer the caller can
+* be given, and `BLOCKED` for a refused blueprint.
+*
+* `BLOCKED` covers both refusals a blueprint can meet, because they are one fact
+* — this blueprint will not be built — and the questions say which. The compiler
+* answers its refusal rather than throwing it: the gate fails closed, returns the
+* questions that closed it, and records `BLOCKED` on its stage, so a caller reads
+* that refusal from the value it asked for. A verb that creates a workspace
+* throws it, because it chose the shape and has nothing to hand back. A blocking
+* question closed the gate; a non-blocking one is a shape this package can
+* describe and declines to create.
 *
 * `context` carries whatever the raising site can say about the failure. It is
 * `unknown` because nothing narrows it usefully at the catch site; read it for
@@ -1206,19 +1226,20 @@ function isScaffoldError(value) {
 //#endregion
 //#region src/core/validators.ts
 /**
-* Narrow a value to a portable target-relative path.
+* Narrow a value to a logical target-relative path.
 *
 * @param value - The candidate path.
 * @returns `true` for a bounded relative path with no traversal, empty segment,
-* control character, or non-portable visible character.
+* control character, or reserved syntax character.
 *
 * @remarks
 * Every path this package reads or writes passes here, so one law covers a
 * planned artifact, an override target, an audit finding, a guide mirror, and a
 * snapshot key. Rejecting `..`, a leading `/`, and a backslash at the guard is
 * what stops a caller-supplied path from naming a destination outside the
-* target, and rejecting the non-portable visible characters is what keeps a
-* generated workspace checkable out on every supported filesystem.
+* target. Host-location validation is a separate server boundary: this guard
+* does not reject a device spelling, a trailing dot or space, or a segment that
+* exceeds a host filesystem's byte ceiling.
 *
 * @example
 * ```ts
@@ -1496,20 +1517,34 @@ var isQuestion = (0, _orkestrel_contract.recordOf)({
 * @remarks
 * `observed` is required exactly where the mutation it precedes is held to it,
 * absent where the destination had no bytes to record, and optional where the
-* comparison may not have been made.
+* comparison may not have been made. Planned findings require `ownership`;
+* foreign findings forbid it because no artifact was planned for their path.
+*
+* That is the whole claim. This guard proves the shape a reader may destructure
+* and nothing about whether the verdict is one an audit could have reached: the
+* correlation between `ownership`, `drift`, and `observed` belongs to
+* {@link inferDrift}, and it is re-derived at the verb that acts on the finding.
 */
 var isFinding = (0, _orkestrel_contract.unionOf)((0, _orkestrel_contract.recordOf)({
 	path: isPath,
 	group: isGroup,
-	drift: (0, _orkestrel_contract.literalOf)("stale", "foreign"),
+	ownership: (0, _orkestrel_contract.literalOf)("content", "presence", "birth"),
+	drift: (0, _orkestrel_contract.literalOf)("stale"),
+	observed: isHex
+}), (0, _orkestrel_contract.recordOf)({
+	path: isPath,
+	group: isGroup,
+	drift: (0, _orkestrel_contract.literalOf)("foreign"),
 	observed: isHex
 }), (0, _orkestrel_contract.recordOf)({
 	path: isPath,
 	group: isGroup,
+	ownership: (0, _orkestrel_contract.literalOf)("content", "presence", "birth"),
 	drift: (0, _orkestrel_contract.literalOf)("missing")
 }), (0, _orkestrel_contract.recordOf)({
 	path: isPath,
 	group: isGroup,
+	ownership: (0, _orkestrel_contract.literalOf)("content", "presence", "birth"),
 	drift: (0, _orkestrel_contract.literalOf)("aligned"),
 	observed: isHex
 }, ["observed"]));
@@ -1518,10 +1553,11 @@ var isFinding = (0, _orkestrel_contract.unionOf)((0, _orkestrel_contract.recordO
 *
 * @remarks
 * An audit reaches the writer and the destructive verb, so it is guarded as
-* strictly as the plan beside it.
+* strictly as the plan beside it. Findings use the sum of the two producer
+* bounds: one per planned artifact, then one per unplanned snapshot path.
 */
 var isAudit = (0, _orkestrel_contract.recordOf)({
-	findings: (0, _orkestrel_contract.andOf)(isCollection, (0, _orkestrel_contract.arrayOf)(isFinding)),
+	findings: (0, _orkestrel_contract.andOf)((value) => (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isArray)(value) && value.length <= 2e3), (0, _orkestrel_contract.arrayOf)(isFinding)),
 	questions: (0, _orkestrel_contract.andOf)(isCollection, (0, _orkestrel_contract.arrayOf)(isQuestion))
 });
 /**
@@ -1555,7 +1591,8 @@ var isMirror = (0, _orkestrel_contract.unionOf)((0, _orkestrel_contract.recordOf
 var isCatalogEntry = (0, _orkestrel_contract.unionOf)((0, _orkestrel_contract.recordOf)({
 	name: isDependencyName,
 	lookup: (0, _orkestrel_contract.literalOf)("found"),
-	version: _orkestrel_contract.isString
+	version: _orkestrel_contract.isString,
+	dependencies: (0, _orkestrel_contract.andOf)(isCollection, (0, _orkestrel_contract.arrayOf)(isDependency))
 }), (0, _orkestrel_contract.recordOf)({
 	name: isDependencyName,
 	lookup: (0, _orkestrel_contract.literalOf)("missing", "failed"),
@@ -2111,6 +2148,71 @@ function inferDrift(artifact, observed) {
 	return observed === artifactToHex(artifact) ? "aligned" : "stale";
 }
 /**
+* Test whether {@link inferDrift} could have produced a finding for an ownership.
+*
+* @param ownership - What scaffold claims at the planned path.
+* @param finding - The audit verdict to test.
+* @returns Whether the ownership and verdict are reachable through {@link inferDrift}.
+*
+* @remarks
+* This predicate keeps the comparison law beside the reachability law it
+* restates. A mutation uses it so a refusal can distinguish an impossible
+* verdict from a target that genuinely moved after its audit.
+*/
+function matchesDriftReachability(ownership, finding) {
+	if (finding.drift === "aligned") return ownership === "birth" || finding.observed !== void 0;
+	if (finding.drift === "missing") return ownership !== "birth";
+	return finding.drift === "stale" && ownership === "content";
+}
+/**
+* Project a catalog into the layers it publishes in.
+*
+* @param entries - The catalog rows to order.
+* @returns One layer per round, each holding the names publishable together,
+* sorted within the layer; a name whose edges never resolve is omitted.
+*
+* @remarks
+* A layer is a deterministic function of the catalog's own edges, so it is
+* computed here rather than stored on a row that could disagree with them.
+* Only RUNTIME edges between catalogued packages count: a development
+* dependency reaches no consumer, so it constrains nothing about publish order,
+* and an edge leaving the fleet is a package this catalog does not publish.
+*
+* The order matters because these packages are `0.0.x`, where a caret pins one
+* exact release. Publishing a dependent before its dependency leaves the
+* dependent pinned to the older release, and two ranges that disagree install
+* two copies of one package that the compiler reads as two distinct types.
+*
+* A cycle cannot be published in rounds, so its members are omitted rather than
+* placed in an order that would be wrong. An absent name is the report: compare
+* the returned names against the catalog to find one.
+*
+* @example
+* ```ts
+* import { catalogToLayers } from '@orkestrel/scaffold'
+*
+* catalogToLayers(entries)[0] // the names that depend on nothing in the fleet
+* ```
+*/
+function catalogToLayers(entries) {
+	const published = new Set(entries.filter((entry) => entry.lookup === "found").map((entry) => entry.name));
+	const pending = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (entry.lookup !== "found") continue;
+		const edges = entry.dependencies.map((dependency) => dependency.name);
+		pending.set(entry.name, new Set(edges.filter((name) => published.has(name))));
+	}
+	const layers = [];
+	while (pending.size > 0) {
+		const ready = [...pending].filter(([, edges]) => edges.size === 0).map(([name]) => name);
+		if (ready.length === 0) break;
+		for (const name of ready) pending.delete(name);
+		for (const edges of pending.values()) for (const name of ready) edges.delete(name);
+		layers.push(ready.sort());
+	}
+	return layers;
+}
+/**
 * Project a plan into its tally by artifact origin.
 *
 * @param plan - The plan to summarize.
@@ -2538,10 +2640,9 @@ function srcToExports(src) {
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToDevDependencies } from '@orkestrel/scaffold'
+* import { blueprintToDevDependencies, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { src: ['core'] })
 *
 * blueprintToDevDependencies(blueprint).typescript // the shared TypeScript pin
 * ```
@@ -2552,7 +2653,7 @@ function blueprintToDevDependencies(blueprint) {
 		...blueprint.src.includes("browser") ? SOURCE_BROWSER_DEV_DEPENDENCIES : {},
 		...blueprint.app.length > 0 ? APP_DEV_DEPENDENCIES : {},
 		...blueprint.app.includes("browser") ? APP_BROWSER_DEV_DEPENDENCIES : {},
-		...blueprint.showcase ? SHOWCASE_DEV_DEPENDENCIES : {},
+		...blueprint.showcase && blueprint.app.includes("browser") ? SHOWCASE_DEV_DEPENDENCIES : {},
 		...blueprint.app.includes("server") ? APP_SERVER_DEV_DEPENDENCIES : {}
 	};
 	for (const extra of blueprint.extras) merged[extra.name] = extra.range;
@@ -2581,10 +2682,9 @@ function blueprintToDevDependencies(blueprint) {
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToScripts } from '@orkestrel/scaffold'
+* import { blueprintToScripts, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { src: ['core'] })
 *
 * blueprintToScripts(blueprint)['format:check'] // 'oxfmt --config .oxfmtrc.json --check .'
 * ```
@@ -2700,10 +2800,9 @@ function blueprintToScripts(blueprint) {
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToManifest } from '@orkestrel/scaffold'
+* import { blueprintToManifest, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { src: ['core'] })
 *
 * blueprintToManifest(blueprint).endsWith('}\n') // true
 * ```
@@ -2779,12 +2878,11 @@ function blueprintToManifest(blueprint) {
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToMachinery } from '@orkestrel/scaffold'
+* import { blueprintToMachinery, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { app: ['browser'] })
 *
-* blueprintToMachinery(blueprint).vue // true when the app declares browser
+* blueprintToMachinery(blueprint).vue // true
 * ```
 */
 function blueprintToMachinery(blueprint) {
@@ -2804,10 +2902,9 @@ function blueprintToMachinery(blueprint) {
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToRootTsconfig } from '@orkestrel/scaffold'
+* import { blueprintToRootTsconfig, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { src: ['core'] })
 *
 * blueprintToRootTsconfig(blueprint).startsWith('{') // true
 * ```
@@ -2832,10 +2929,9 @@ function blueprintToRootTsconfig(blueprint) {
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToRootVite } from '@orkestrel/scaffold'
+* import { blueprintToRootVite, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { src: ['core'] })
 *
 * blueprintToRootVite(blueprint).includes('defineConfig') // true
 * ```
@@ -2865,8 +2961,7 @@ function blueprintToRootVite(blueprint) {
 		const core = blueprint.src.includes("core");
 		factories.push((0, _orkestrel_template.fillTemplate)(CONFIG_TEMPLATES.factories.src.server, {
 			external: core ? `external: (id: string) =>
-						id === '@src/core' || id.startsWith('node:') || id.startsWith('@orkestrel/'),` : `external: (id: string) =>
-						id.startsWith('node:') || id.startsWith('@orkestrel/'),`,
+						id === '@src/core' || id.startsWith('node:') || id.startsWith('@orkestrel/'),` : "external: (id: string) => id.startsWith('node:') || id.startsWith('@orkestrel/'),",
 			output: core ? `\t\t\t\t\toutput: [
 						{
 							format: 'es',
@@ -2892,28 +2987,35 @@ function blueprintToRootVite(blueprint) {
 		projects.push("appCore");
 	}
 	if (blueprint.app.includes("browser")) {
-		const showcasePlugin = machinery.showcase ? `\t\t\t...(showcase
-				? [
-						viteSingleFile({
-							removeViteModuleLoader: true,
-							useRecommendedBuildConfig: true,
-						}),
-						{
-							name: 'orkestrel-showcase-html',
-							transformIndexHtml: {
-								order: 'post',
-								handler(html) {
-									const stamp = new Date().toISOString()
-									return html.replace(
-										'</head>',
-										'\t\t<meta name="build-id" content="' + stamp + '" />\\n\t</head>',
-									)
-								},
-							},
+		const showcasePlugins = machinery.showcase ? `	const showcasePlugins: PluginOption[] = showcase
+		? [
+				viteSingleFile({
+					removeViteModuleLoader: true,
+					useRecommendedBuildConfig: true,
+				}),
+				{
+					name: 'orkestrel-showcase-html',
+					transformIndexHtml: {
+						order: 'post',
+						handler(html) {
+							const stamp = new Date().toISOString()
+							return html.replace(
+								'</head>',
+								'\t\t<meta name="build-id" content="' + stamp + '" />\\n\t</head>',
+							)
 						},
-					]
-				: []),
+					},
+				},
+			]
+		: []
 ` : "";
+		const plugins = machinery.showcase ? `\t\tplugins: [
+			outputBoundary(output),
+			environmentBoundary('app/browser'),
+			vue(),
+			...showcasePlugins,
+		],
+` : "		plugins: [outputBoundary(output), environmentBoundary('app/browser'), vue()],\n";
 		const showcaseBuild = machinery.showcase ? `\t\t\t...(showcase
 				? {
 						cssMinify: 'lightningcss',
@@ -2932,11 +3034,12 @@ export function appShowcase(...options: never[]): UserConfig {
 }
 ` : "";
 		factories.push((0, _orkestrel_template.fillTemplate)(CONFIG_TEMPLATES.factories.app.browser, {
-			showcasePlugin,
+			plugins,
+			showcasePlugins,
 			showcaseBuild,
 			showcaseFactory
 		}));
-		projects.push("appBrowser");
+		projects.push("appBrowser()");
 	}
 	if (blueprint.app.includes("server")) {
 		factories.push(CONFIG_TEMPLATES.factories.app.server);
@@ -2957,9 +3060,13 @@ export function appShowcase(...options: never[]): UserConfig {
 	const projectRows = `\t\tprojects: [
 ${projects.map((project) => `\t\t\t${project},`).join("\n")}
 	\t],`;
+	const body = `${factories.join("\n")}\n`;
+	const boundaries = ["environmentBoundary", "outputBoundary"].filter((boundary) => body.includes(boundary));
 	return (0, _orkestrel_template.fillTemplate)(CONFIG_TEMPLATES.root.vite, {
+		viteTypes: machinery.showcase ? "PluginOption, UserConfig" : "UserConfig",
 		imports: imports.length === 0 ? "" : `${imports.join("\n")}\n`,
-		factories: `${factories.join("\n")}\n`,
+		helpers: boundaries.length === 0 ? "" : `import { ${boundaries.join(", ")} } from './configs/helpers.js'\n`,
+		factories: body,
 		projects: projectRows
 	});
 }
@@ -2971,10 +3078,9 @@ ${projects.map((project) => `\t\t\t${project},`).join("\n")}
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToConfigArtifacts } from '@orkestrel/scaffold'
+* import { blueprintToConfigArtifacts, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { src: ['core'] })
 *
 * blueprintToConfigArtifacts(blueprint)[0]?.path // 'tsconfig.json'
 * ```
@@ -3000,7 +3106,8 @@ function blueprintToConfigArtifacts(blueprint) {
 		else if (path === "configs/src/tsconfig.browser.json") content = CONFIG_TEMPLATES.tsconfigs.src.browser;
 		else if (path === "configs/src/vite.server.config.ts") {
 			const packageName = serializeTypeScriptString(`@orkestrel/${blueprint.name}`);
-			const replacement = packageName.length <= 36 ? `\t\t\t\t\t\t? content.replaceAll(/(?:\\.\\.\\/)+core\\/index\\.ts/g, ${packageName})` : [
+			const joined = `\t\t\t\t\t\t? content.replaceAll(/(?:\\.\\.\\/)+core\\/index\\.ts/g, ${packageName})`;
+			const replacement = joined.replaceAll("	", "  ").length <= 100 ? joined : [
 				"						? content.replaceAll(",
 				"								/(?:\\.\\.\\/)+core\\/index\\.ts/g,",
 				`\t\t\t\t\t\t\t\t${packageName},`,
@@ -3065,7 +3172,7 @@ ${paths.join("\n")}
 			content
 		});
 	}
-	if (blueprint.showcase) artifacts.push({
+	if (blueprint.showcase && blueprint.app.includes("browser")) artifacts.push({
 		path: SHOWCASE_CONFIG_PATH,
 		group: "configs",
 		ownership: "content",
@@ -3082,16 +3189,18 @@ ${paths.join("\n")}
 * @returns Empty published barrels, selected application entries, and the optional bin entry.
 *
 * @remarks
-* The barrels and bin entry intentionally export nothing. A generated sample
-* entity is too easy to mistake for package implementation, so the scaffold
-* establishes only the selected environment boundaries.
+* The barrels and every runtime entry intentionally hold nothing. A generated
+* sample entity is too easy to mistake for package implementation, so the
+* scaffold establishes only the selected environment boundaries. An application
+* entry is empty for the same reason the bin entry is, and because the vendored
+* lint config refuses an unassigned import outside a stylesheet, so the entry
+* cannot start by importing its barrel for effect either.
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToSourceArtifacts } from '@orkestrel/scaffold'
+* import { blueprintToSourceArtifacts, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { src: ['core'] })
 *
 * blueprintToSourceArtifacts(blueprint).every(({ group }) => group === 'source') // true
 * ```
@@ -3121,7 +3230,7 @@ function blueprintToSourceArtifacts(blueprint) {
 			ownership: "birth",
 			origin: "template",
 			environment,
-			content: ARTIFACT_TEMPLATES.source.main
+			content: ARTIFACT_TEMPLATES.source.empty
 		}, {
 			path: "app/browser/index.html",
 			group: "source",
@@ -3136,7 +3245,7 @@ function blueprintToSourceArtifacts(blueprint) {
 			ownership: "birth",
 			origin: "template",
 			environment,
-			content: ARTIFACT_TEMPLATES.source.main
+			content: ARTIFACT_TEMPLATES.source.empty
 		});
 	}
 	if (blueprint.bin) artifacts.push({
@@ -3164,10 +3273,9 @@ function blueprintToSourceArtifacts(blueprint) {
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToTestArtifacts } from '@orkestrel/scaffold'
+* import { blueprintToTestArtifacts, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { src: ['core'] })
 *
 * blueprintToTestArtifacts(blueprint)[0]?.path // 'tests/setup.ts'
 * ```
@@ -3377,10 +3485,9 @@ function nameToHostArtifacts(name) {
 *
 * @example
 * ```ts
-* import type { Artifact } from '@orkestrel/scaffold'
-* import { applyOverrides } from '@orkestrel/scaffold'
+* import { applyOverrides, blueprintToConfigArtifacts, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const artifacts: readonly Artifact[]
+* const artifacts = blueprintToConfigArtifacts(createBlueprint('router', { src: ['core'] }))
 *
 * applyOverrides(artifacts, [{ path: 'README.md', content: '# Title\n' }])
 * ```
@@ -3418,12 +3525,11 @@ function applyOverrides(artifacts, overrides) {
 *
 * @example
 * ```ts
-* import type { Plan } from '@orkestrel/scaffold'
-* import { planToHash } from '@orkestrel/scaffold'
+* import { createBlueprint, createCompiler, planToHash } from '@orkestrel/scaffold'
 *
-* declare const plan: Plan
+* const { plan } = createCompiler().compile(createBlueprint('router', { src: ['core'] }))
 *
-* planToHash(plan)?.length // 16
+* plan === undefined ? undefined : planToHash(plan)?.length // 16
 * ```
 */
 function planToHash(plan) {
@@ -3441,13 +3547,16 @@ function planToHash(plan) {
 * @param artifact - The planned artifact.
 * @param observed - The destination's exact bytes as hexadecimal; absent when
 * the destination holds no file.
-* @returns The finding, carrying `observed` exactly where bytes were read.
+* @returns The finding, carrying the artifact's ownership and `observed`
+* exactly where bytes were read.
 *
 * @remarks
 * The comparison itself is {@link inferDrift}'s, so ownership decides it here
 * exactly as it does everywhere else. This adds only the shape: a missing
 * destination has no bytes to record, and every other verdict records the bytes
 * it was given, which is the precondition the mutation that follows is held to.
+* Ownership is copied rather than inferred from drift because aligned findings
+* span all three ownership tiers.
 *
 * `foreign` is not answerable here, because it describes a path no artifact was
 * planned for.
@@ -3459,29 +3568,34 @@ function planToHash(plan) {
 * artifactToFinding(
 * 	{ path: 'README.md', group: 'docs', ownership: 'content', origin: 'computed', content: 'hi\n' },
 * 	'6279650a',
-* ) // { path: 'README.md', group: 'docs', drift: 'stale', observed: '6279650a' }
+* ) // { path: 'README.md', group: 'docs', ownership: 'content', drift: 'stale', observed: '6279650a' }
 * ```
 */
 function artifactToFinding(artifact, observed) {
 	const path = artifact.path;
 	const group = artifact.group;
+	const ownership = artifact.ownership;
 	if (observed === void 0) return inferDrift(artifact) === "aligned" ? {
 		path,
 		group,
+		ownership,
 		drift: "aligned"
 	} : {
 		path,
 		group,
+		ownership,
 		drift: "missing"
 	};
 	return inferDrift(artifact, observed) === "stale" ? {
 		path,
 		group,
+		ownership,
 		drift: "stale",
 		observed
 	} : {
 		path,
 		group,
+		ownership,
 		drift: "aligned",
 		observed
 	};
@@ -3505,12 +3619,11 @@ function artifactToFinding(artifact, observed) {
 *
 * @example
 * ```ts
-* import type { Plan } from '@orkestrel/scaffold'
-* import { planToFindings } from '@orkestrel/scaffold'
+* import { createBlueprint, createCompiler, planToFindings } from '@orkestrel/scaffold'
 *
-* declare const plan: Plan
+* const { plan } = createCompiler().compile(createBlueprint('router', { src: ['core'] }))
 *
-* planToFindings(plan, { 'AGENTS.md': '68690a' })
+* plan === undefined ? [] : planToFindings(plan, { 'AGENTS.md': '68690a' })
 * ```
 */
 function planToFindings(plan, current) {
@@ -3594,8 +3707,8 @@ function dependenciesToQuestions(dependencies, field, name, range) {
 * Measure a blueprint against every law its own fields decide.
 *
 * @param blueprint - The workspace specification.
-* @returns One blocking question per rejected field, in blueprint field order,
-* with the rules that span several fields last.
+* @returns One question per rejected field, in blueprint field order, with the
+* rules that span several fields last.
 *
 * @remarks
 * Only the laws a blueprint answers alone are here. The structural record and
@@ -3606,19 +3719,25 @@ function dependenciesToQuestions(dependencies, field, name, range) {
 * a drafted plan belong to {@link artifactsToQuestions} and
 * {@link overridesToQuestions}.
 *
-* Every question is blocking, because each one describes a workspace this
-* package cannot generate rather than one it can generate imperfectly. An
-* environment question carries `ENVIRONMENTS` as its candidates, so a caller
-* reads the accepted values from the refusal instead of from the documentation.
+* A question blocks when it describes a workspace this package cannot generate.
+* Three do not, because each describes a workspace it can describe honestly and
+* should not create: a published axis of several environments without core, whose
+* manifest names a core build the workspace never runs, and a structural flag
+* whose required axis is absent, which emits nothing. Blocking those closed the
+* gate for every verb, and the verbs that read an existing workspace need the
+* plan the gate refused. The caller that chooses the shape refuses the advisory;
+* the callers that read one report it.
+*
+* An environment question carries `ENVIRONMENTS` as its candidates, so a caller
+* reads the accepted values from the question instead of from the documentation.
 *
 * @example
 * ```ts
-* import type { Blueprint } from '@orkestrel/scaffold'
-* import { blueprintToQuestions } from '@orkestrel/scaffold'
+* import { blueprintToQuestions, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const blueprint: Blueprint
+* const blueprint = createBlueprint('router', { src: ['core'] })
 *
-* blueprintToQuestions(blueprint).length === 0 // true when the gate passes
+* blueprintToQuestions(blueprint).length === 0 // true
 * ```
 */
 function blueprintToQuestions(blueprint) {
@@ -3644,6 +3763,12 @@ function blueprintToQuestions(blueprint) {
 		blocking: true,
 		candidates: ENVIRONMENTS
 	});
+	if (blueprint.src.length > 1 && !blueprint.src.includes("core")) questions.push({
+		field: "src",
+		message: "Several published environments put core at the package root, so this manifest names a core build the workspace never runs. Declare core on src, or publish one environment.",
+		blocking: false,
+		candidates: ENVIRONMENTS
+	});
 	for (const environment of ENVIRONMENTS) {
 		if (blueprint.src.filter((declared) => declared === environment).length > 1) questions.push({
 			field: "src",
@@ -3658,11 +3783,10 @@ function blueprintToQuestions(blueprint) {
 			candidates: ENVIRONMENTS
 		});
 	}
-	if (blueprint.showcase && !blueprint.app.includes("browser")) questions.push({
-		field: "showcase",
-		message: "A showcase projects the browser application, which app does not declare.",
-		blocking: true,
-		candidates: ENVIRONMENTS
+	if (blueprint.integration && blueprint.src.length === 0) questions.push({
+		field: "integration",
+		message: "integration projects a published src, and this workspace declares none, so it emits nothing.",
+		blocking: false
 	});
 	const services = /* @__PURE__ */ new Set();
 	for (const service of blueprint.services) {
@@ -3678,6 +3802,11 @@ function blueprintToQuestions(blueprint) {
 		});
 		services.add(service);
 	}
+	if (blueprint.showcase && !blueprint.app.includes("browser")) questions.push({
+		field: "showcase",
+		message: "showcase projects a browser app, and this workspace declares none, so it emits nothing.",
+		blocking: false
+	});
 	questions.push(...dependenciesToQuestions(blueprint.dependencies, "dependencies", DEPENDENCY_NAME_PATTERN, ORKESTREL_RANGE_PATTERN), ...dependenciesToQuestions(blueprint.peers, "peers", DEPENDENCY_NAME_PATTERN, ORKESTREL_RANGE_PATTERN), ...dependenciesToQuestions(blueprint.extras, "extras", EXTRA_NAME_PATTERN, EXTRA_RANGE_PATTERN));
 	const lists = [
 		["dependencies", blueprint.dependencies],
@@ -3726,12 +3855,11 @@ function blueprintToQuestions(blueprint) {
 *
 * @example
 * ```ts
-* import type { Artifact } from '@orkestrel/scaffold'
-* import { artifactsToQuestions } from '@orkestrel/scaffold'
+* import { artifactsToQuestions, blueprintToConfigArtifacts, createBlueprint } from '@orkestrel/scaffold'
 *
-* declare const artifacts: readonly Artifact[]
+* const artifacts = blueprintToConfigArtifacts(createBlueprint('router', { src: ['core'] }))
 *
-* artifactsToQuestions(artifacts).length === 0 // true when the draft is sound
+* artifactsToQuestions(artifacts).length === 0 // true
 * ```
 */
 function artifactsToQuestions(artifacts) {
@@ -3783,10 +3911,9 @@ function artifactsToQuestions(artifacts) {
 *
 * @example
 * ```ts
-* import type { Artifact } from '@orkestrel/scaffold'
-* import { overridesToQuestions } from '@orkestrel/scaffold'
+* import { blueprintToConfigArtifacts, createBlueprint, overridesToQuestions } from '@orkestrel/scaffold'
 *
-* declare const artifacts: readonly Artifact[]
+* const artifacts = blueprintToConfigArtifacts(createBlueprint('router', { src: ['core'] }))
 *
 * overridesToQuestions([{ path: 'package.json', content: '{}\n' }], artifacts).length // 1
 * ```
@@ -3913,12 +4040,19 @@ var Compiler = class {
 	* carries no plan, then `compile` with the whole outcome either way, so an
 	* observer reads every compile from one event and the refusals from the other.
 	*
+	* A plan says the blueprint can be built. It does not say the blueprint should
+	* be created, and the questions beside it are what this compiler could not
+	* settle. A caller creating a fresh workspace answers them first and writes
+	* nothing while any remains, which is the rule the `new` verb applies; a caller
+	* describing or repairing an existing target carries them through instead.
+	* Nothing downstream repeats that check, because only the caller knows which of
+	* the two it is.
+	*
 	* @example
 	* ```ts
-	* import type { Blueprint } from '@orkestrel/scaffold'
-	* import { createCompiler } from '@orkestrel/scaffold'
+	* import { createBlueprint, createCompiler } from '@orkestrel/scaffold'
 	*
-	* declare const blueprint: Blueprint
+	* const blueprint = createBlueprint('router', { src: ['core'] })
 	*
 	* createCompiler().compile(blueprint, ['manifest']).plan?.artifacts.length // 1
 	* ```
@@ -3946,14 +4080,19 @@ var Compiler = class {
 	* reports no findings and carries the questions instead. Emits `block` in that
 	* case, then `audit` with the verdict either way.
 	*
+	* Ownership decides each verdict, not absence. A birth-owned path is never
+	* compared and reads `aligned` against a target holding nothing, while a
+	* content-owned path with no bytes to read is `missing`. An empty snapshot
+	* therefore produces both verdicts rather than one.
+	*
 	* @example
 	* ```ts
-	* import type { Blueprint } from '@orkestrel/scaffold'
-	* import { createCompiler } from '@orkestrel/scaffold'
+	* import { createBlueprint, createCompiler } from '@orkestrel/scaffold'
 	*
-	* declare const blueprint: Blueprint
+	* const blueprint = createBlueprint('router', { src: ['core'] })
 	*
-	* createCompiler().audit(blueprint, {}).findings.every(({ drift }) => drift === 'missing') // true
+	* createCompiler().audit(blueprint, {}, ['manifest']).findings[0]?.drift // 'aligned'
+	* createCompiler().audit(blueprint, {}, ['configs']).findings[0]?.drift // 'missing'
 	* ```
 	*/
 	audit(blueprint, current, groups) {
@@ -3991,7 +4130,10 @@ var Compiler = class {
 	}
 	#scaffold(blueprint, groups) {
 		const stages = [];
-		const artifacts = this.#draft(blueprint, groups);
+		const draft = this.#draft(blueprint);
+		const selected = [];
+		for (const group of groups) for (const artifact of draft) if (artifact.group === group) selected.push(artifact);
+		const artifacts = applyOverrides(selected, blueprint.overrides);
 		stages.push({
 			stage: "draft",
 			input: {
@@ -4000,7 +4142,7 @@ var Compiler = class {
 			},
 			output: artifacts
 		});
-		const questions = this.#gate(blueprint, artifacts);
+		const questions = this.#gate(blueprint, draft, artifacts);
 		const blocking = questions.filter((question) => question.blocking);
 		if (blocking.length > 0) {
 			stages.push({
@@ -4069,8 +4211,8 @@ var Compiler = class {
 			stages
 		};
 	}
-	#draft(blueprint, groups) {
-		const drafted = [
+	#draft(blueprint) {
+		return [
 			{
 				path: "package.json",
 				group: "manifest",
@@ -4086,14 +4228,11 @@ var Compiler = class {
 			...blueprintToOrchestrationArtifacts(blueprint),
 			...nameToHostArtifacts(blueprint.name)
 		];
-		const covered = [];
-		for (const group of groups) for (const artifact of drafted) if (artifact.group === group) covered.push(artifact);
-		return applyOverrides(covered, blueprint.overrides);
 	}
-	#gate(blueprint, artifacts) {
+	#gate(blueprint, draft, artifacts) {
 		return [
 			...blueprintToQuestions(blueprint),
-			...overridesToQuestions(blueprint.overrides, artifacts),
+			...overridesToQuestions(blueprint.overrides, draft),
 			...artifactsToQuestions(artifacts)
 		];
 	}
@@ -4215,6 +4354,7 @@ exports.DEFAULT_VERSION = DEFAULT_VERSION;
 exports.DEPENDENCY_NAME_PATTERN = DEPENDENCY_NAME_PATTERN;
 exports.ENGINES_PATTERN = ENGINES_PATTERN;
 exports.ENVIRONMENTS = ENVIRONMENTS;
+exports.EXECUTABLE_PATHS = EXECUTABLE_PATHS;
 exports.EXTRA_NAME_PATTERN = EXTRA_NAME_PATTERN;
 exports.EXTRA_RANGE_PATTERN = EXTRA_RANGE_PATTERN;
 exports.GLOBAL_SETUP_PATH = GLOBAL_SETUP_PATH;
@@ -4226,6 +4366,7 @@ exports.INTEGRATION_TEST_PATH = INTEGRATION_TEST_PATH;
 exports.INVALID_PATH_CHARACTER_PATTERN = INVALID_PATH_CHARACTER_PATTERN;
 exports.MAX_ARTIFACT_BYTES = MAX_ARTIFACT_BYTES;
 exports.MAX_ARTIFACT_HEX_LENGTH = MAX_ARTIFACT_HEX_LENGTH;
+exports.MAX_AUDIT_FINDINGS = MAX_AUDIT_FINDINGS;
 exports.MAX_COLLECTION_ITEMS = MAX_COLLECTION_ITEMS;
 exports.MAX_DEPENDENCY_NAME_LENGTH = MAX_DEPENDENCY_NAME_LENGTH;
 exports.MAX_MANIFEST_BYTES = MAX_MANIFEST_BYTES;
@@ -4263,6 +4404,7 @@ exports.blueprintToScripts = blueprintToScripts;
 exports.blueprintToSourceArtifacts = blueprintToSourceArtifacts;
 exports.blueprintToTestArtifacts = blueprintToTestArtifacts;
 exports.bytesToHex = bytesToHex;
+exports.catalogToLayers = catalogToLayers;
 exports.cloneValue = cloneValue;
 exports.compareVersions = compareVersions;
 exports.computeBytes = computeBytes;
@@ -4298,6 +4440,7 @@ exports.isScaffoldError = isScaffoldError;
 exports.isSnapshot = isSnapshot;
 exports.manifestToDependencies = manifestToDependencies;
 exports.manifestToName = manifestToName;
+exports.matchesDriftReachability = matchesDriftReachability;
 exports.matchesEngines = matchesEngines;
 exports.matchesOrchestrationPath = matchesOrchestrationPath;
 exports.matchesRange = matchesRange;