@orkestrel/scaffold 0.0.25 → 0.0.26

package/dist/src/core/index.js

@@ -139,6 +139,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
@@ -226,7 +245,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.
@@ -244,6 +263,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,7 +283,7 @@ var DEFAULT_ENGINES = `>=${MINIMUM_NODE_VERSION}`;
 var BASE_DEV_DEPENDENCIES = Object.freeze({
 	"@microsoft/api-extractor": "^7.58.12",
 	"@orkestrel/guide": "^0.0.9",
-	"@orkestrel/scaffold": "^0.0.25",
+	"@orkestrel/scaffold": "^0.0.26",
 	"@types/node": "^26.2.0",
 	oxfmt: "^0.62.0",
 	oxlint: "^1.77.0",
@@ -355,12 +376,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'
 
@@ -552,14 +571,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,
@@ -942,9 +956,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
@@ -956,8 +974,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>
@@ -1142,16 +1158,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
@@ -1205,19 +1225,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
@@ -1495,20 +1516,34 @@ var isQuestion = 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 = unionOf(recordOf({
 	path: isPath,
 	group: isGroup,
-	drift: literalOf("stale", "foreign"),
+	ownership: literalOf("content", "presence", "birth"),
+	drift: literalOf("stale"),
+	observed: isHex
+}), recordOf({
+	path: isPath,
+	group: isGroup,
+	drift: literalOf("foreign"),
 	observed: isHex
 }), recordOf({
 	path: isPath,
 	group: isGroup,
+	ownership: literalOf("content", "presence", "birth"),
 	drift: literalOf("missing")
 }), recordOf({
 	path: isPath,
 	group: isGroup,
+	ownership: literalOf("content", "presence", "birth"),
 	drift: literalOf("aligned"),
 	observed: isHex
 }, ["observed"]));
@@ -1517,10 +1552,11 @@ var isFinding = unionOf(recordOf({
 *
 * @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 = recordOf({
-	findings: andOf(isCollection, arrayOf(isFinding)),
+	findings: andOf((value) => holds(() => isArray(value) && value.length <= 2e3), arrayOf(isFinding)),
 	questions: andOf(isCollection, arrayOf(isQuestion))
 });
 /**
@@ -2110,6 +2146,23 @@ 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 plan into its tally by artifact origin.
 *
 * @param plan - The plan to summarize.
@@ -2537,10 +2590,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
 * ```
@@ -2551,7 +2603,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;
@@ -2580,10 +2632,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 .'
 * ```
@@ -2699,10 +2750,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
 * ```
@@ -2778,12 +2828,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) {
@@ -2803,10 +2852,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
 * ```
@@ -2831,10 +2879,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
 * ```
@@ -2864,8 +2911,7 @@ function blueprintToRootVite(blueprint) {
 		const core = blueprint.src.includes("core");
 		factories.push(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',
@@ -2891,28 +2937,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',
@@ -2931,11 +2984,12 @@ export function appShowcase(...options: never[]): UserConfig {
 }
 ` : "";
 		factories.push(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);
@@ -2956,9 +3010,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 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
 	});
 }
@@ -2970,10 +3028,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'
 * ```
@@ -2999,7 +3056,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},`,
@@ -3064,7 +3122,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",
@@ -3081,16 +3139,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
 * ```
@@ -3120,7 +3180,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",
@@ -3135,7 +3195,7 @@ function blueprintToSourceArtifacts(blueprint) {
 			ownership: "birth",
 			origin: "template",
 			environment,
-			content: ARTIFACT_TEMPLATES.source.main
+			content: ARTIFACT_TEMPLATES.source.empty
 		});
 	}
 	if (blueprint.bin) artifacts.push({
@@ -3163,10 +3223,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'
 * ```
@@ -3376,10 +3435,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' }])
 * ```
@@ -3417,12 +3475,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) {
@@ -3440,13 +3497,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.
@@ -3458,29 +3518,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
 	};
@@ -3504,12 +3569,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) {
@@ -3593,8 +3657,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
@@ -3605,19 +3669,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) {
@@ -3643,6 +3713,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",
@@ -3657,11 +3733,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) {
@@ -3677,6 +3752,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],
@@ -3725,12 +3805,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) {
@@ -3782,10 +3861,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
 * ```
@@ -3912,12 +3990,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
 	* ```
@@ -3945,14 +4030,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) {
@@ -3990,7 +4080,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: {
@@ -3999,7 +4092,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({
@@ -4068,8 +4161,8 @@ var Compiler = class {
 			stages
 		};
 	}
-	#draft(blueprint, groups) {
-		const drafted = [
+	#draft(blueprint) {
+		return [
 			{
 				path: "package.json",
 				group: "manifest",
@@ -4085,14 +4178,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)
 		];
 	}
@@ -4197,6 +4287,6 @@ function createCompiler(options) {
 	return new Compiler(options);
 }
 //#endregion
-export { APP_BROWSER_DEV_DEPENDENCIES, APP_DEV_DEPENDENCIES, APP_MATRIX, APP_SERVER_DEV_DEPENDENCIES, ARTIFACT_TEMPLATES, BASE_DEV_DEPENDENCIES, BIN_CONFIGS, BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFIG_TEMPLATES, CONTROL_CHARACTER_PATTERN, Compiler, DEFAULT_ENGINES, DEFAULT_VERSION, DEPENDENCY_NAME_PATTERN, ENGINES_PATTERN, ENVIRONMENTS, EXTRA_NAME_PATTERN, EXTRA_RANGE_PATTERN, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HEX_PATTERN, HOST_PATHS, INTEGRATION_TEST_PATH, INVALID_PATH_CHARACTER_PATTERN, MAX_ARTIFACT_BYTES, MAX_ARTIFACT_HEX_LENGTH, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_NAME_LENGTH, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_TOTAL_ARTIFACT_BYTES, MINIMUM_NODE_VERSION, NAME_PATTERN, ORCHESTRATION_PATH_NAMES, ORCHESTRATION_PATH_PREFIXES, ORKESTREL_RANGE_PATTERN, SERVICE_SCRIPT_PATH, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SOURCE_BROWSER_DEV_DEPENDENCIES, SRC_MATRIX, ScaffoldError, VERSION_PATTERN, applyOverrides, artifactToFinding, artifactToHex, artifactsToQuestions, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToDocumentArtifacts, blueprintToGuideArtifacts, blueprintToMachinery, blueprintToManifest, blueprintToOrchestrationArtifacts, blueprintToQuestions, blueprintToRootTsconfig, blueprintToRootVite, blueprintToScripts, blueprintToSourceArtifacts, blueprintToTestArtifacts, bytesToHex, cloneValue, compareVersions, computeBytes, computeHash, contentToHex, createBlueprint, createCompiler, dependenciesToQuestions, extractVersion, inferDrift, inferGroup, isArtifact, isAudit, isBlueprint, isCatalogEntry, isCollection, isCompilerHooks, isCompilerOptions, isContent, isDependency, isDependencyName, isEnvironment, isFinding, isGroup, isGroups, isHex, isMirror, isOverride, isPath, isPlan, isQuestion, isScaffoldError, isSnapshot, manifestToDependencies, manifestToName, matchesEngines, matchesOrchestrationPath, matchesRange, nameToGuide, nameToHostArtifacts, overridesToQuestions, parseBlueprint, parseCompilerOptions, parseGroups, parseSnapshot, pathToCondition, planToFindings, planToHash, planToSummary, selectGroups, selectHostPaths, serializeTypeScriptString, srcToEntry, srcToExports, srcToRoot };
+export { APP_BROWSER_DEV_DEPENDENCIES, APP_DEV_DEPENDENCIES, APP_MATRIX, APP_SERVER_DEV_DEPENDENCIES, ARTIFACT_TEMPLATES, BASE_DEV_DEPENDENCIES, BIN_CONFIGS, BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFIG_TEMPLATES, CONTROL_CHARACTER_PATTERN, Compiler, DEFAULT_ENGINES, DEFAULT_VERSION, DEPENDENCY_NAME_PATTERN, ENGINES_PATTERN, ENVIRONMENTS, EXECUTABLE_PATHS, EXTRA_NAME_PATTERN, EXTRA_RANGE_PATTERN, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HEX_PATTERN, HOST_PATHS, INTEGRATION_TEST_PATH, INVALID_PATH_CHARACTER_PATTERN, MAX_ARTIFACT_BYTES, MAX_ARTIFACT_HEX_LENGTH, MAX_AUDIT_FINDINGS, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_NAME_LENGTH, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_TOTAL_ARTIFACT_BYTES, MINIMUM_NODE_VERSION, NAME_PATTERN, ORCHESTRATION_PATH_NAMES, ORCHESTRATION_PATH_PREFIXES, ORKESTREL_RANGE_PATTERN, SERVICE_SCRIPT_PATH, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SOURCE_BROWSER_DEV_DEPENDENCIES, SRC_MATRIX, ScaffoldError, VERSION_PATTERN, applyOverrides, artifactToFinding, artifactToHex, artifactsToQuestions, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToDocumentArtifacts, blueprintToGuideArtifacts, blueprintToMachinery, blueprintToManifest, blueprintToOrchestrationArtifacts, blueprintToQuestions, blueprintToRootTsconfig, blueprintToRootVite, blueprintToScripts, blueprintToSourceArtifacts, blueprintToTestArtifacts, bytesToHex, cloneValue, compareVersions, computeBytes, computeHash, contentToHex, createBlueprint, createCompiler, dependenciesToQuestions, extractVersion, inferDrift, inferGroup, isArtifact, isAudit, isBlueprint, isCatalogEntry, isCollection, isCompilerHooks, isCompilerOptions, isContent, isDependency, isDependencyName, isEnvironment, isFinding, isGroup, isGroups, isHex, isMirror, isOverride, isPath, isPlan, isQuestion, isScaffoldError, isSnapshot, manifestToDependencies, manifestToName, matchesDriftReachability, matchesEngines, matchesOrchestrationPath, matchesRange, nameToGuide, nameToHostArtifacts, overridesToQuestions, parseBlueprint, parseCompilerOptions, parseGroups, parseSnapshot, pathToCondition, planToFindings, planToHash, planToSummary, selectGroups, selectHostPaths, serializeTypeScriptString, srcToEntry, srcToExports, srcToRoot };
 
 //# sourceMappingURL=index.js.map