@orkestrel/scaffold 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,3636 @@
+import { arrayShape, booleanShape, createContract, integerShape, literalShape, objectShape, optionalShape, stringShape } from "@orkestrel/contract";
+import { parseInline, renderMarkdown } from "@orkestrel/markdown";
+import { fillTemplate } from "@orkestrel/template";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/core/constants.ts
+/** The three `Surface` values, frozen — compose with `literalOf(...)` / `parseEnum(...)`. */
+var SURFACES = Object.freeze([
+	"core",
+	"browser",
+	"server"
+]);
+/** The three `Origin` values, frozen. */
+var ORIGINS = Object.freeze([
+	"host",
+	"template",
+	"computed"
+]);
+/** The seven `Group` values, frozen — the artifact-group selection vocabulary. */
+var GROUPS = Object.freeze([
+	"manifest",
+	"configs",
+	"source",
+	"tests",
+	"guides",
+	"docs",
+	"orchestration"
+]);
+/** The four `Category` values, frozen. */
+var CATEGORIES = Object.freeze([
+	"type",
+	"constant",
+	"factory",
+	"entity"
+]);
+/** The four `Freshness` values, frozen — the currency axis `Sync` reports on. */
+var FRESHNESS = Object.freeze([
+	"current",
+	"behind",
+	"missing",
+	"failed"
+]);
+/** The pipeline phases in order, frozen. */
+var COMPILE_STAGES = Object.freeze([
+	"draft",
+	"gate",
+	"pin"
+]);
+/**
+* The per-surface variant matrix as data: per `Surface`, its `configs/src`
+* files, Vitest project label, `exports` subpath, and build formats — the
+* per-surface layer `blueprintToPlan` reads BENEATH the manifest/exports
+* combination rules it applies on top.
+*/
+var SURFACE_MATRIX = Object.freeze({
+	core: Object.freeze({
+		configs: Object.freeze(["configs/src/vite.core.config.ts", "configs/src/tsconfig.core.json"]),
+		project: "src:core",
+		path: ".",
+		formats: Object.freeze(["es", "cjs"])
+	}),
+	browser: Object.freeze({
+		configs: Object.freeze(["configs/src/vite.browser.config.ts", "configs/src/tsconfig.browser.json"]),
+		project: "src:browser",
+		path: "./browser",
+		formats: Object.freeze(["es"])
+	}),
+	server: Object.freeze({
+		configs: Object.freeze(["configs/src/vite.server.config.ts", "configs/src/tsconfig.server.json"]),
+		project: "src:server",
+		path: "./server",
+		formats: Object.freeze(["es", "cjs"])
+	})
+});
+/**
+* The byte-copied host artifact paths, frozen.
+*
+* @remarks
+* The root docs (`AGENTS.md` / `CLAUDE.md`), `LICENSE`, `.claude`, the three
+* SessionStart hook scripts (`scripts/deps.sh` / `scripts/cursor.sh` /
+* `scripts/ollama.sh`), the line's seven byte-identical root dotfiles,
+* `.github/workflows/ci.yml`, and the two guides-grouped mirrors every repo
+* carries: the line-wide dev-tooling guide (`guides/src/guide.md`) and the
+* scaffold engine's own self-guide (`guides/src/scaffold.md`).
+*/
+var HOST_PATHS = Object.freeze([
+	"AGENTS.md",
+	"CLAUDE.md",
+	"LICENSE",
+	".claude",
+	"scripts/deps.sh",
+	"scripts/cursor.sh",
+	"scripts/ollama.sh",
+	".editorconfig",
+	".gitattributes",
+	".gitignore",
+	".oxfmtrc.json",
+	".oxlintrc.json",
+	".oxlintignore",
+	".prettierignore",
+	".github/workflows/ci.yml",
+	"guides/src/guide.md",
+	"guides/src/scaffold.md"
+]);
+/** The package-name RegExp — lowercase alphanumeric-with-hyphens, letter-first. */
+var NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+* The `@orkestrel/*` dependency-name RegExp — every `Dependency.name` must be
+* scoped to `@orkestrel` and NAME_PATTERN-shaped after the scope, closing the
+* traversal vector a hand-built `../`-laced name would open through
+* `Compiler.#pointerArtifacts`' `guides/src/<short>.md` path derivation.
+*/
+var DEPENDENCY_NAME_PATTERN = /^@orkestrel\/[a-z][a-z0-9-]*$/;
+/**
+* The `extras` dependency-name RegExp — a strict npm package-name shape: an
+* optional single `@scope/` prefix, then lowercase letters, digits, hyphens,
+* dots, and underscores (never leading, never adjacent to the scope slash).
+* Broader than `DEPENDENCY_NAME_PATTERN` on purpose: `extras` names are
+* manifest-content only (`devDependenciesFor` keys `devDependencies` with
+* them, `Compiler.#pointerArtifacts` never reads them for a path), so they
+* carry no traversal vector — no `..`, no backslash, and the single optional
+* `/` is fixed to the one scope boundary, so the shape stays structurally
+* incapable of escaping a derived path even though it accepts any valid npm
+* package name (unscoped or externally-scoped), not just `@orkestrel/*`.
+*/
+var EXTRA_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/** The starting version the `blueprint` builder fills. */
+var DEFAULT_VERSION = "0.0.1";
+/** The `engines.node` range the `blueprint` builder fills. */
+var DEFAULT_ENGINES = ">=22";
+/** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
+var SCAFFOLD_RANGE = "^0.0.1";
+/** The default id for a `Compiler` orchestrator. */
+var COMPILER_ID = "compiler";
+//#endregion
+//#region src/core/errors.ts
+/**
+* Carries a `ScaffoldErrorCode` + optional `context` (AGENTS §12).
+*
+* @remarks
+* Throws are reserved for caller misuse: `createBlueprint` on off-contract
+* data throws `INVALID`, any method after `destroy()` throws `DESTROYED`, and
+* on the server surface a non-vacant target throws `TARGET` while a failed
+* write throws `WRITE`. A failing gate is NOT an error — it fails closed into
+* an incomplete `Scaffolding` whose `failures` carry a `BLOCKED` marker.
+*
+* @example
+* ```ts
+* import { ScaffoldError, isScaffoldError } from '@orkestrel/scaffold'
+*
+* try {
+* 	throw new ScaffoldError('INVALID', 'Blueprint failed the exact-record contract')
+* } catch (error) {
+* 	if (isScaffoldError(error)) error.code // 'INVALID'
+* }
+* ```
+*/
+var ScaffoldError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "ScaffoldError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Narrow a caught value to a `ScaffoldError`.
+*
+* @param value - The caught value to narrow.
+* @returns `true` when `value` is a {@link ScaffoldError}.
+*
+* @example
+* ```ts
+* import { isScaffoldError } from '@orkestrel/scaffold'
+*
+* isScaffoldError(new Error('plain')) // false
+* ```
+*/
+function isScaffoldError(value) {
+	return value instanceof ScaffoldError;
+}
+//#endregion
+//#region src/core/shapers.ts
+/**
+* Build the `Dependency` object shape.
+*
+* @returns A fresh `ContractShape` describing `{ name, range, optional? }`.
+*/
+function dependencyShape() {
+	return objectShape({
+		name: stringShape({ min: 1 }),
+		range: stringShape({ min: 1 }),
+		optional: optionalShape(booleanShape())
+	});
+}
+/**
+* Build the `Override` object shape.
+*
+* @returns A fresh `ContractShape` describing `{ path, content }`.
+*/
+function overrideShape() {
+	return objectShape({
+		path: stringShape({ min: 1 }),
+		content: stringShape({ min: 1 })
+	});
+}
+/**
+* Build the `Blueprint` object shape.
+*
+* @remarks
+* `surfaces` is a `literalShape(SURFACES)` array with `min: 1`; `name` is a
+* plain `min: 1` string, NOT pattern-constrained, so `generate` stays
+* satisfiable — the `NAME_PATTERN` law lives in the semantic pass
+* (`validateBlueprint`), never in this compiled contract. `peers` and `extras`
+* are `dependencyShape()` arrays alongside `dependencies` — the cross-array
+* uniqueness and overlap rules also live in `validateBlueprint`.
+*
+* @returns A fresh `ContractShape` describing the closed `Blueprint` spec.
+*/
+function blueprintShape() {
+	return objectShape({
+		name: stringShape({ min: 1 }),
+		description: optionalShape(stringShape()),
+		keywords: arrayShape(stringShape()),
+		surfaces: arrayShape(literalShape(SURFACES), { min: 1 }),
+		dependencies: arrayShape(dependencyShape()),
+		peers: arrayShape(dependencyShape()),
+		extras: arrayShape(dependencyShape()),
+		version: stringShape({ min: 1 }),
+		engines: stringShape({ min: 1 }),
+		overrides: arrayShape(overrideShape())
+	});
+}
+/**
+* Build the `Member` object shape.
+*
+* @returns A fresh `ContractShape` describing `{ name, category, summary, surface }`.
+*/
+function memberShape() {
+	return objectShape({
+		name: stringShape({ min: 1 }),
+		category: literalShape(CATEGORIES),
+		summary: stringShape({ min: 1 }),
+		surface: literalShape(SURFACES)
+	});
+}
+/**
+* Build the `Artifact` object shape.
+*
+* @remarks
+* `origin` is a `literalShape(ORIGINS)`; `content` and `source` are both
+* optional (the `origin` axis decides which one a given artifact carries).
+*
+* @returns A fresh `ContractShape` describing one planned file.
+*/
+function artifactShape() {
+	return objectShape({
+		path: stringShape({ min: 1 }),
+		group: literalShape(GROUPS),
+		origin: literalShape(ORIGINS),
+		surface: optionalShape(literalShape(SURFACES)),
+		content: optionalShape(stringShape()),
+		source: optionalShape(stringShape())
+	});
+}
+/**
+* Build the whole `Plan` object shape.
+*
+* @remarks
+* Composes {@link blueprintShape} and {@link artifactShape}; `trace` and
+* `hash` are optional (filled by the pin).
+*
+* @returns A fresh `ContractShape` describing the compiled, ordered plan.
+*/
+function planShape() {
+	return objectShape({
+		blueprint: blueprintShape(),
+		groups: arrayShape(literalShape(GROUPS)),
+		artifacts: arrayShape(artifactShape()),
+		trace: optionalShape(stringShape()),
+		hash: optionalShape(stringShape())
+	});
+}
+/**
+* Build the `SyncReport` object shape.
+*
+* @remarks
+* `guides` / `versions` are array sub-shapes, each with a
+* `literalShape(FRESHNESS)` `freshness` field; `isSyncReport` /
+* `parseSyncReport` compile from it.
+*
+* @returns A fresh `ContractShape` describing the whole sync outcome.
+*/
+function syncReportShape() {
+	return objectShape({
+		target: stringShape({ min: 1 }),
+		guides: arrayShape(objectShape({
+			name: stringShape({ min: 1 }),
+			path: stringShape({ min: 1 }),
+			content: stringShape(),
+			freshness: literalShape(FRESHNESS),
+			note: optionalShape(stringShape())
+		})),
+		versions: arrayShape(objectShape({
+			name: stringShape({ min: 1 }),
+			range: stringShape({ min: 1 }),
+			latest: stringShape(),
+			freshness: literalShape(FRESHNESS),
+			note: optionalShape(stringShape())
+		})),
+		clean: booleanShape(),
+		failed: integerShape({ min: 0 })
+	});
+}
+//#endregion
+//#region src/core/validators.ts
+/**
+* Narrow a value to a `Dependency` — `name` and `range` non-empty strings.
+*
+* @remarks
+* Compiled from {@link dependencyShape} via `createContract` (AGENTS §14) — a
+* total `Guard`, adversarial input returns `false`, never throws.
+*/
+var isDependency = createContract(dependencyShape()).is;
+/**
+* Narrow a value to an `Override` — `path` and `content` non-empty strings.
+*
+* @remarks
+* Compiled from {@link overrideShape} via `createContract` (AGENTS §14) — a
+* total `Guard`, adversarial input returns `false`, never throws.
+*/
+var isOverride = createContract(overrideShape()).is;
+/**
+* Narrow a value to a `Blueprint` — `surfaces` on-vocabulary and non-empty,
+* `name` a non-empty string.
+*
+* @remarks
+* Compiled from {@link blueprintShape} via `createContract` (AGENTS §14) —
+* the `NAME_PATTERN` law is the semantic pass's (`validateBlueprint`), not
+* this shape's; a total `Guard`, adversarial input returns `false`, never
+* throws.
+*/
+var isBlueprint = createContract(blueprintShape()).is;
+/**
+* Narrow a value to a `Member` — `category` and `surface` on-vocabulary.
+*
+* @remarks
+* Compiled from {@link memberShape} via `createContract` (AGENTS §14) — a
+* total `Guard`, adversarial input returns `false`, never throws.
+*/
+var isMember = createContract(memberShape()).is;
+/**
+* Narrow a value to an `Artifact` — `group` / `origin` on-vocabulary.
+*
+* @remarks
+* Compiled from {@link artifactShape} via `createContract` (AGENTS §14) — a
+* total `Guard`, adversarial input returns `false`, never throws.
+*/
+var isArtifact = createContract(artifactShape()).is;
+/**
+* Narrow a value to a `Plan` — the whole exact-record contract, section
+* guards composed.
+*
+* @remarks
+* Compiled from {@link planShape} via `createContract` (AGENTS §14) — a
+* total `Guard`, adversarial input returns `false`, never throws.
+*/
+var isPlan = createContract(planShape()).is;
+/**
+* Narrow a value to a `SyncReport` — the whole exact-record sync contract,
+* `guide` / `version` sections composed.
+*
+* @remarks
+* Compiled from {@link syncReportShape} via `createContract` (AGENTS §14) — a
+* total `Guard`, adversarial input returns `false`, never throws.
+*/
+var isSyncReport = createContract(syncReportShape()).is;
+//#endregion
+//#region src/core/parsers.ts
+/**
+* Parse a `Blueprint` from `unknown` (or a JSON string), else `undefined`.
+*
+* @remarks
+* The coercing counterpart of {@link isBlueprint}, compiled from the same
+* {@link blueprintShape} via `createContract` (AGENTS §14) — a guard-valid
+* value round-trips unchanged, an off-contract value returns `undefined`,
+* and this never throws, including on malformed JSON text.
+*
+* @param input - The value (or JSON string) to parse.
+* @returns A `Blueprint`, else `undefined`.
+*/
+var parseBlueprint = ((contract) => (input) => {
+	if (typeof input !== "string") return contract.parse(input);
+	try {
+		return contract.parse(JSON.parse(input));
+	} catch {
+		return;
+	}
+})(createContract(blueprintShape()));
+/**
+* Parse a `Plan` from `unknown` (or a JSON string), else `undefined`.
+*
+* @remarks
+* The coercing counterpart of {@link isPlan}, compiled from the same
+* {@link planShape} via `createContract` (AGENTS §14) — a guard-valid value
+* round-trips unchanged, an off-contract value returns `undefined`, and this
+* never throws, including on malformed JSON text.
+*
+* @param input - The value (or JSON string) to parse.
+* @returns A `Plan`, else `undefined`.
+*/
+var parsePlan = ((contract) => (input) => {
+	if (typeof input !== "string") return contract.parse(input);
+	try {
+		return contract.parse(JSON.parse(input));
+	} catch {
+		return;
+	}
+})(createContract(planShape()));
+/**
+* Parse a `SyncReport` from `unknown` (or a JSON string), else `undefined`.
+*
+* @remarks
+* The coercing counterpart of {@link isSyncReport}, compiled from the same
+* {@link syncReportShape} via `createContract` (AGENTS §14) — a guard-valid
+* value round-trips unchanged, an off-contract value returns `undefined`,
+* and this never throws, including on malformed JSON text.
+*
+* @param input - The value (or JSON string) to parse.
+* @returns A `SyncReport`, else `undefined`.
+*/
+var parseSyncReport = ((contract) => (input) => {
+	if (typeof input !== "string") return contract.parse(input);
+	try {
+		return contract.parse(JSON.parse(input));
+	} catch {
+		return;
+	}
+})(createContract(syncReportShape()));
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Build a fresh `Dependency`.
+*
+* @param name - The `@orkestrel/*` package name.
+* @param range - The semver range.
+* @param optional - Whether this dependency is optional; meaningful only when
+* used as a `Blueprint` peer. Omitted entirely when absent.
+* @returns A `Dependency` with `name` / `range` set, `optional` included only when passed.
+*
+* @example
+* ```ts
+* import { dependency } from '@orkestrel/scaffold'
+*
+* dependency('@orkestrel/contract', '^0.0.5') // { name: '@orkestrel/contract', range: '^0.0.5' }
+* dependency('@orkestrel/database', '^0.0.5', true) // optional: true
+* ```
+*/
+function dependency(name, range, optional) {
+	return optional === void 0 ? {
+		name,
+		range
+	} : {
+		name,
+		range,
+		optional
+	};
+}
+/**
+* Build a fresh `Override`.
+*
+* @param path - The artifact-relative path the override replaces.
+* @param content - The replacement content.
+* @returns An `Override` with both fields set.
+*
+* @example
+* ```ts
+* import { override } from '@orkestrel/scaffold'
+*
+* override('README.md', '# router\n') // { path: 'README.md', content: '# router\n' }
+* ```
+*/
+function override(path, content) {
+	return {
+		path,
+		content
+	};
+}
+/**
+* Build a fresh `Member`.
+*
+* @param name - The declared export name.
+* @param category - The `Member`'s `Category`.
+* @param summary - A one-line description.
+* @param surface - The owning `Surface`; defaults `'core'`.
+* @returns A `Member` with every field set.
+*
+* @example
+* ```ts
+* import { member } from '@orkestrel/scaffold'
+*
+* member('RouterOptions', 'type', 'Options for creating a Router.') // surface: 'core'
+* ```
+*/
+function member(name, category, summary, surface = "core") {
+	return {
+		name,
+		category,
+		summary,
+		surface
+	};
+}
+/**
+* Build a fresh `Blueprint` from a name and a partial of the rest.
+*
+* @param name - The package name.
+* @param options - A partial of the remaining `Blueprint` fields.
+* @remarks
+* `version` / `engines` default `DEFAULT_VERSION` / `DEFAULT_ENGINES`, `surfaces`
+* defaults `['core']`, and `keywords` / `dependencies` / `peers` / `extras` /
+* `overrides` default `[]`. `description` is OMITTED entirely when absent, so
+* the result round-trips the exact-record `Blueprint` guard.
+* @returns A complete `Blueprint`.
+*
+* @example
+* ```ts
+* import { blueprint } from '@orkestrel/scaffold'
+*
+* blueprint('router').version // '0.0.1'
+* ```
+*/
+function blueprint(name, options) {
+	const base = {
+		name,
+		keywords: options?.keywords ?? [],
+		surfaces: options?.surfaces ?? ["core"],
+		dependencies: options?.dependencies ?? [],
+		peers: options?.peers ?? [],
+		extras: options?.extras ?? [],
+		version: options?.version ?? "0.0.1",
+		engines: options?.engines ?? ">=22",
+		overrides: options?.overrides ?? []
+	};
+	return options?.description === void 0 ? base : {
+		...base,
+		description: options.description
+	};
+}
+/**
+* Derive the PascalCase entity name from a lowercase-hyphen package name.
+*
+* @param name - A lowercase-hyphen package name.
+* @returns The PascalCase entity name — hyphens are word breaks.
+*
+* @example
+* ```ts
+* import { pascalCase } from '@orkestrel/scaffold'
+*
+* pascalCase('my-router') // 'MyRouter'
+* ```
+*/
+function pascalCase(name) {
+	return name.split("-").filter((word) => word.length > 0).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+/**
+* Derive the declared public `Member[]` from a blueprint.
+*
+* @param spec - The blueprint to derive members from.
+* @remarks
+* The canonical per-surface inventory is the four `Category` buckets applied to
+* the package's PascalCase entity name: an `Options` type, an `Interface` type,
+* a `create*` factory, a default-id constant, and the entity itself. Standalone
+* helpers, validators, and shapers are hand-authored in implementation, not
+* scaffolded.
+* @returns The declared `Member[]`, one set per surface.
+*
+* @example
+* ```ts
+* import { blueprint, blueprintToMembers } from '@orkestrel/scaffold'
+*
+* blueprintToMembers(blueprint('router'))[0] // { name: 'Router', category: 'entity', … }
+* ```
+*/
+function blueprintToMembers(spec) {
+	const pascal = pascalCase(spec.name);
+	const screaming = pascal.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
+	const members = [];
+	for (const surface of spec.surfaces) {
+		members.push(member(pascal, "entity", `The ${pascal} entity.`, surface));
+		members.push(member(`${pascal}Options`, "type", `Options for creating a ${pascal}.`, surface));
+		members.push(member(`${pascal}Interface`, "type", `The ${pascal} contract.`, surface));
+		members.push(member(`create${pascal}`, "factory", `Create a ${pascal}.`, surface));
+		members.push(member(`${screaming}_ID`, "constant", `The default id for a ${pascal}.`, surface));
+	}
+	return members;
+}
+/**
+* Extract the `@orkestrel/<name>` package names from a catalog markdown
+* block/table, in row order.
+*
+* @param text - The markdown block/table text (the `orkestrel.md` embedded
+* catalog shape — GFM table rows opening `| @orkestrel/<name>`).
+* @remarks
+* Pure line-scan: a row matches when, after trimming, it starts with
+* `| @orkestrel/` followed by a `NAME_PATTERN`-shaped short name and a cell
+* boundary (`|` or whitespace) — the same row shape `runCatalog`'s shrink
+* count previously matched inline; this is the single source both consume.
+* Returns `[]` when the text has no markers/rows (never throws).
+* @returns The full `@orkestrel/<name>` names found, in order.
+*
+* @example
+* ```ts
+* import { catalogNames } from '@orkestrel/scaffold'
+*
+* catalogNames('| @orkestrel/contract | ... |\n| @orkestrel/emitter | ... |')
+* // ['@orkestrel/contract', '@orkestrel/emitter']
+* ```
+*/
+function catalogNames(text) {
+	const rowPattern = /^\|\s*(@orkestrel\/[a-z][a-z0-9-]*)(?=\s|\|)/;
+	const names = [];
+	for (const line of text.split("\n")) {
+		const match = rowPattern.exec(line.trimStart());
+		if (match !== null && match[1] !== void 0) names.push(match[1]);
+	}
+	return names;
+}
+/**
+* Build a formatter-width-aligned GFM table string from header and row cells.
+*
+* @param header - The header cell strings, in column order.
+* @param rows - The body rows, each a list of cell strings matching `header`'s column count.
+* @param align - Optional per-column alignment; defaults every column to `'none'`.
+* @remarks
+* Builds a `TableNode` (each cell parsed with `parseInline`) and serializes it
+* through `renderMarkdown`, which contributes the structure — `\|`-escaping any
+* literal pipe and emitting the alignment delimiter row — at a flat 1-space
+* cell padding. This function then re-pads BOTH the cells AND the delimiter row
+* to per-column codepoint width, matching oxfmt's markdown re-padding.
+* @returns The aligned GFM table string.
+*
+* @example
+* ```ts
+* import { alignTable } from '@orkestrel/scaffold'
+*
+* alignTable(['API', 'Kind'], [['`createRouter`', 'function']])
+* // '| API            | Kind     |\n| --------------- | -------- |\n| `createRouter` | function |'
+* ```
+*/
+function alignTable(header, rows, align) {
+	const columns = header.length;
+	const alignment = align ?? header.map(() => "none");
+	const lines = renderMarkdown({
+		element: "table",
+		header: header.map((cell) => parseInline(cell)),
+		rows: rows.map((row) => row.map((cell) => parseInline(cell))),
+		align: alignment
+	}).split("\n");
+	const headerCells = splitTableRow(lines[0] ?? "");
+	const bodyCells = lines.slice(2).map((line) => splitTableRow(line));
+	const widths = [];
+	for (let column = 0; column < columns; column += 1) {
+		let width = Array.from(headerCells[column] ?? "").length;
+		for (const row of bodyCells) {
+			const length = Array.from(row[column] ?? "").length;
+			if (length > width) width = length;
+		}
+		widths.push(Math.max(3, width));
+	}
+	return [
+		`| ${headerCells.map((cell, index) => padCell(cell, widths[index] ?? 3)).join(" | ")} |`,
+		`| ${alignment.map((columnAlign, index) => delimiterCell(columnAlign, widths[index] ?? 3)).join(" | ")} |`,
+		...bodyCells.map((row) => `| ${row.map((cell, index) => padCell(cell, widths[index] ?? 3)).join(" | ")} |`)
+	].join("\n");
+}
+/**
+* Split one rendered GFM table row into its trimmed cell strings.
+*
+* @param line - A single rendered table line (header, delimiter, or body row).
+* @remarks
+* Splits on an UNESCAPED `|` (a `\|` is a literal pipe inside a cell, not a
+* column boundary), then drops the leading/trailing empty segments the
+* boundary pipes produce and trims each remaining cell.
+* @returns The row's cell strings, in column order.
+*
+* @example
+* ```ts
+* import { splitTableRow } from '@orkestrel/scaffold'
+*
+* splitTableRow('| a | b |') // ['a', 'b']
+* ```
+*/
+function splitTableRow(line) {
+	return line.split(/(?<!\\)\|/).slice(1, -1).map((part) => part.trim());
+}
+/**
+* Right-pad a cell to a codepoint width, oxfmt-style.
+*
+* @param text - The cell text.
+* @param width - The target codepoint width.
+* @remarks
+* Measures via `Array.from` (codepoints, not UTF-16 code units) so a
+* surrogate-pair or wide codepoint counts once, matching oxfmt's own
+* width math. A cell already at or past `width` is returned unchanged.
+* @returns `text` padded with trailing spaces to `width` codepoints.
+*
+* @example
+* ```ts
+* import { padCell } from '@orkestrel/scaffold'
+*
+* padCell('ab', 5) // 'ab   '
+* ```
+*/
+function padCell(text, width) {
+	const length = Array.from(text).length;
+	return length >= width ? text : text + " ".repeat(width - length);
+}
+/**
+* Build one delimiter-row cell for a GFM table column.
+*
+* @param columnAlign - The column's `TableAlign`.
+* @param width - The column's codepoint width.
+* @remarks
+* `'left'` prefixes `:`, `'right'` suffixes `:`, `'center'` wraps both ends,
+* `'none'` is plain dashes — one dash per width unit, `:` markers consuming
+* a dash slot rather than adding to `width`.
+* @returns The delimiter cell string for this column.
+*
+* @example
+* ```ts
+* import { delimiterCell } from '@orkestrel/scaffold'
+*
+* delimiterCell('left', 5) // ':----'
+* ```
+*/
+function delimiterCell(columnAlign, width) {
+	if (columnAlign === "left") return `:${"-".repeat(width - 1)}`;
+	if (columnAlign === "right") return `${"-".repeat(width - 1)}:`;
+	if (columnAlign === "center") return `:${"-".repeat(width - 2)}:`;
+	return "-".repeat(width);
+}
+/**
+* Project a `Plan` into a `PlanSummary`.
+*
+* @param plan - The plan to summarize.
+* @returns The artifact tally by `origin`, the surfaces, and the covered groups.
+*
+* @example
+* ```ts
+* import { planToSummary } from '@orkestrel/scaffold'
+*
+* planToSummary(plan) // { name: 'router', artifacts: 21, host: 12, template: 6, computed: 3, … }
+* ```
+*/
+function planToSummary(plan) {
+	let host = 0;
+	let template = 0;
+	let computed = 0;
+	for (const artifact of plan.artifacts) if (artifact.origin === "host") host += 1;
+	else if (artifact.origin === "template") template += 1;
+	else computed += 1;
+	return {
+		name: plan.blueprint.name,
+		surfaces: plan.blueprint.surfaces,
+		groups: plan.groups,
+		artifacts: plan.artifacts.length,
+		host,
+		template,
+		computed
+	};
+}
+/**
+* Project a `Plan` into a copy-ready markdown review document.
+*
+* @param plan - The plan to review.
+* @returns The artifact table by group, the members table, and the summary — the diff-first dry run.
+*
+* @example
+* ```ts
+* import { planToReview } from '@orkestrel/scaffold'
+*
+* planToReview(plan) // '# Scaffolding router\n## Artifacts\n| Path | Group | Origin |\n…'
+* ```
+*/
+function planToReview(plan) {
+	const summary = planToSummary(plan);
+	const members = blueprintToMembers(plan.blueprint);
+	const artifactTable = alignTable([
+		"Path",
+		"Group",
+		"Origin"
+	], plan.artifacts.map((artifact) => [
+		artifact.path,
+		artifact.group,
+		artifact.origin
+	]));
+	const memberTable = alignTable([
+		"Name",
+		"Category",
+		"Surface"
+	], members.map((entry) => [
+		entry.name,
+		entry.category,
+		entry.surface
+	]));
+	return [
+		`# Scaffolding ${plan.blueprint.name}`,
+		"",
+		"## Artifacts",
+		"",
+		artifactTable,
+		"",
+		"## Members",
+		"",
+		memberTable,
+		"",
+		"## Summary",
+		"",
+		`- surfaces: ${summary.surfaces.join(", ")}`,
+		`- groups: ${summary.groups.join(", ")}`,
+		`- artifacts: ${summary.artifacts} (host: ${summary.host}, template: ${summary.template}, computed: ${summary.computed})`
+	].join("\n");
+}
+/**
+* Project an `Audit` into a markdown drift report.
+*
+* @param audit - The audit to report.
+* @returns Findings grouped by `drift`, `aligned` entries elided — what `repair` will touch.
+*
+* @example
+* ```ts
+* import { auditToReview } from '@orkestrel/scaffold'
+*
+* auditToReview(audit) // '# Audit\n\n- clean: false\n…\n## stale\n\n| Path | Group |\n…'
+* ```
+*/
+function auditToReview(audit) {
+	const groups = {
+		aligned: [],
+		stale: [],
+		missing: [],
+		foreign: []
+	};
+	for (const finding of audit.findings) groups[finding.drift].push(finding);
+	const sections = [
+		"# Audit",
+		"",
+		`- clean: ${audit.clean}`,
+		`- drifted: ${audit.drifted}`,
+		`- missing: ${audit.missing}`,
+		`- foreign: ${audit.foreign}`
+	];
+	for (const drift of [
+		"stale",
+		"missing",
+		"foreign"
+	]) {
+		const findings = groups[drift];
+		if (findings.length === 0) continue;
+		sections.push("", `## ${drift}`, "", alignTable(["Path", "Group"], findings.map((finding) => [finding.path, finding.group])));
+	}
+	return sections.join("\n");
+}
+/**
+* Test whether a `Freshness` verdict counts toward "behind".
+*
+* @param freshness - The freshness verdict to test.
+* @returns `true` iff `freshness` is `'behind'`.
+*
+* @example
+* ```ts
+* import { isBehind } from '@orkestrel/scaffold'
+*
+* isBehind('behind') // true
+* isBehind('current') // false
+* ```
+*/
+function isBehind(freshness) {
+	return freshness === "behind";
+}
+/**
+* Project a `SyncReport` into a markdown freshness report.
+*
+* @param report - The sync report to render.
+* @returns Guides and versions each in their own table, via `alignTable` — the sibling of `auditToReview`.
+*
+* @example
+* ```ts
+* import { syncToReview } from '@orkestrel/scaffold'
+*
+* syncToReview(report) // '# Sync — 2 behind\n## Guides\n| Name | Freshness |\n…'
+* ```
+*/
+function syncToReview(report) {
+	const sections = [
+		`# Sync — ${report.guides.filter((guide) => isBehind(guide.freshness)).length + report.versions.filter((version) => isBehind(version.freshness)).length} behind`,
+		"",
+		`- clean: ${report.clean}`,
+		`- failed: ${report.failed}`
+	];
+	if (report.guides.length > 0) sections.push("", "## Guides", "", alignTable(["Name", "Freshness"], report.guides.map((guide) => [guide.name, guide.freshness])));
+	if (report.versions.length > 0) sections.push("", "## Versions", "", alignTable([
+		"Name",
+		"Range",
+		"Latest",
+		"Freshness"
+	], report.versions.map((version) => [
+		version.name,
+		version.range,
+		version.latest,
+		version.freshness
+	])));
+	return sections.join("\n");
+}
+/**
+* Project a fleet package catalog into a markdown table — the block
+* `.claude/agents/orkestrel.md`'s catalog markers wrap.
+*
+* @param entries - The catalog rows to render.
+* @remarks
+* Deduplicated by `name` (a later entry for a repeated name wins), then
+* code-unit sorted by `name`. An empty `description` renders as `—` (an em
+* dash), never a blank cell. Deterministic — same input, same output, every
+* time — via `alignTable`; trailing-newline terminated.
+* @returns The aligned GFM table string.
+*
+* @example
+* ```ts
+* import { catalogToBlock } from '@orkestrel/scaffold'
+*
+* catalogToBlock([
+* 	{ name: '@orkestrel/router', version: '0.0.5', description: 'A tiny hash-router.' },
+* 	{ name: '@orkestrel/contract', version: '0.0.5', description: '' },
+* ])
+* // '| Package             | Version | Description         |\n| … |\n| @orkestrel/contract | 0.0.5   | —                   |\n…'
+* ```
+*/
+function catalogToBlock(entries) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const entry of entries) merged.set(entry.name, entry);
+	return `${alignTable([
+		"Package",
+		"Version",
+		"Description"
+	], [...merged.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0).map((entry) => [
+		entry.name,
+		entry.version,
+		entry.description.length === 0 ? "—" : entry.description
+	]))}\n`;
+}
+/**
+* Infer a foreign path's `Group` from its leading path segment.
+*
+* @param path - The target-relative path to classify.
+* @remarks
+* Ordered prefix match — `src/`, `tests/`, `guides/`, `docs/`, `configs/`,
+* then `.github/` / `scripts/` as `'orchestration'`, then the two manifest
+* files by exact name. Anything else (a root-level, prefix-less file) falls
+* through to `'configs'`.
+* @returns The inferred `Group` for `path`.
+*
+* @example
+* ```ts
+* import { inferGroup } from '@orkestrel/scaffold'
+*
+* inferGroup('src/core/index.ts') // 'source'
+* inferGroup('mystery.config.ts') // 'configs'
+* ```
+*/
+function inferGroup(path) {
+	if (path.startsWith("src/")) return "source";
+	if (path.startsWith("tests/")) return "tests";
+	if (path.startsWith("guides/")) return "guides";
+	if (path.startsWith("docs/")) return "docs";
+	if (path.startsWith("configs/")) return "configs";
+	if (path.startsWith(".github/") || path.startsWith("scripts/")) return "orchestration";
+	if (path === "package.json" || path === "package-lock.json") return "manifest";
+	return "configs";
+}
+/**
+* Diff a plan's artifacts against a target's current content.
+*
+* @param plan - The plan whose artifacts are the source of truth.
+* @param current - The target's current content, keyed by artifact-relative path.
+* @remarks
+* A `template` / `computed` artifact whose rendered content the target does not
+* match is `stale`; one the target lacks is `missing`; a target file the plan
+* does not own is `foreign`. A `host`-origin artifact is audited by PRESENCE
+* only — `missing` or `aligned`, never `stale` — UNLESS it has been hydrated
+* with its real host bytes (`hydratePlan`'s `content`), in which case it is
+* content-compared exactly like a `template` / `computed` artifact and CAN be
+* `stale`. A degrade-path or directory-shaped host artifact (never hydrated)
+* stays presence-only.
+* @returns The `Audit` of drift findings — pure, no I/O.
+*
+* @example
+* ```ts
+* import { diffPlan } from '@orkestrel/scaffold'
+*
+* diffPlan(plan, current) // { findings: [...], clean: false, complete: true, drifted: 1, missing: 20, foreign: 0 }
+* ```
+*/
+function diffPlan(plan, current) {
+	const findings = [];
+	const owned = /* @__PURE__ */ new Set();
+	for (const artifact of plan.artifacts) {
+		owned.add(artifact.path);
+		const seen = current[artifact.path];
+		if (artifact.origin === "host") {
+			let drift;
+			if (seen === void 0) drift = "missing";
+			else if (artifact.content === void 0) drift = "aligned";
+			else drift = seen === artifact.content ? "aligned" : "stale";
+			findings.push({
+				path: artifact.path,
+				group: artifact.group,
+				drift
+			});
+			continue;
+		}
+		if (seen === void 0) findings.push({
+			path: artifact.path,
+			group: artifact.group,
+			drift: "missing"
+		});
+		else if (seen === artifact.content) findings.push({
+			path: artifact.path,
+			group: artifact.group,
+			drift: "aligned"
+		});
+		else findings.push({
+			path: artifact.path,
+			group: artifact.group,
+			drift: "stale"
+		});
+	}
+	for (const path of Object.keys(current)) {
+		if (owned.has(path)) continue;
+		findings.push({
+			path,
+			group: inferGroup(path),
+			drift: "foreign"
+		});
+	}
+	let drifted = 0;
+	let missing = 0;
+	let foreign = 0;
+	for (const finding of findings) if (finding.drift === "stale") drifted += 1;
+	else if (finding.drift === "missing") missing += 1;
+	else if (finding.drift === "foreign") foreign += 1;
+	return {
+		findings,
+		clean: drifted === 0 && missing === 0 && foreign === 0,
+		complete: true,
+		questions: [],
+		drifted,
+		missing,
+		foreign
+	};
+}
+/**
+* Validate one dependency-shaped array under the name/range/duplicate rules.
+*
+* @param field - The `Question.field` to attribute a violation to (`'dependencies'` / `'peers'` / `'extras'`).
+* @param items - The `Dependency[]` to check.
+* @remarks
+* Pure — takes no closed-over `questions` array to mutate; the caller
+* concatenates the returned `questions` and inspects the returned `seen` set
+* to apply the cross-array (`dependencies` vs `peers` vs `extras`) overlap
+* rules `validateBlueprint` layers on top. `field === 'extras'` validates
+* names against `EXTRA_NAME_PATTERN` (broader — any valid npm package name);
+* `'dependencies'` and `'peers'` keep `DEPENDENCY_NAME_PATTERN` (closed to
+* `@orkestrel/*`) — the path-derived arrays stay orkestrel-closed, since only
+* `dependencies`/`peers` names ever reach `Compiler.#pointerArtifacts`' path
+* derivation; `extras` names are manifest-content only.
+* @returns The violations found and the set of names seen, in encounter order.
+*
+* @example
+* ```ts
+* import { validateDependencyArray } from '@orkestrel/scaffold'
+*
+* validateDependencyArray('dependencies', [{ name: '', range: '^1' }])
+* // { questions: [{ field: 'dependencies', text: 'A dependency name must not be empty', … }], seen: Set(0) {} }
+* ```
+*/
+function validateDependencyArray(field, items) {
+	const pattern = field === "extras" ? EXTRA_NAME_PATTERN : DEPENDENCY_NAME_PATTERN;
+	const questions = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of items) {
+		if (item.name.length === 0) questions.push({
+			field,
+			text: "A dependency name must not be empty",
+			blocking: true
+		});
+		else if (!pattern.test(item.name)) questions.push({
+			field,
+			text: `Dependency name "${item.name}" must match ${pattern.source}`,
+			blocking: true
+		});
+		if (item.range.length === 0) questions.push({
+			field,
+			text: `Dependency "${item.name}" is missing a version range`,
+			blocking: true
+		});
+		if (seen.has(item.name)) questions.push({
+			field,
+			text: `Dependency "${item.name}" is declared more than once`,
+			blocking: true
+		});
+		seen.add(item.name);
+	}
+	return {
+		questions,
+		seen
+	};
+}
+/**
+* The semantic pass over a blueprint.
+*
+* @param spec - The blueprint to validate.
+* @remarks
+* Checks the name against `NAME_PATTERN`, non-empty on-vocabulary `surfaces`
+* with no repeats (a repeat would produce duplicate members); a single
+* surface — `core`-only, `server`-only, `browser`-only — is a fully
+* first-class declaration (`rootViteConfig` retargets the root export and
+* runs the surface's own factory as the base, no `core` involved), but a
+* `browser`+`server` declaration with no `core` has no defined configuration
+* class `rootViteConfig` / `singleSurfaceViteConfig` can shape — that ONE
+* exemplar-less combination is a blocking question (without this gate it
+* would silently drop a surface at `rootViteConfig`'s dispatch while the
+* manifest still references it). And well-formed `dependencies` / `peers` /
+* `extras` (non-empty name/range, no duplicate names within an array):
+* `dependencies` and `peers` names are shaped `DEPENDENCY_NAME_PATTERN`
+* (closed to `@orkestrel/*`) — a NAME-shaped law at the gate that closes the
+* traversal vector a hand-built `../`-laced dependency name would open
+* through `Compiler.#pointerArtifacts`'s path derivation; `extras` names are
+* shaped `EXTRA_NAME_PATTERN` instead — broader (any valid npm package name),
+* safe because `extras` never feeds a path, only `devDependencies` content. A
+* name appearing in both `dependencies` and `peers` is a blocking question
+* (npm forbids sensibly declaring the same package both ways), and an
+* `extras` name may overlap neither `dependencies` nor `peers`.
+* @returns A `Validation` — never throws.
+*
+* @example
+* ```ts
+* import { validateBlueprint } from '@orkestrel/scaffold'
+*
+* validateBlueprint(blueprint('router')) // { valid: true, questions: [], warnings: [] }
+* ```
+*/
+function validateBlueprint(spec) {
+	const MAX_NAME_LENGTH = 203;
+	const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+	const ENGINES_PATTERN = /^>=\d+$/;
+	const questions = [];
+	if (!NAME_PATTERN.test(spec.name)) questions.push({
+		field: "name",
+		text: `Name "${spec.name}" must match ${NAME_PATTERN.source}`,
+		blocking: true
+	});
+	if (spec.name.length > MAX_NAME_LENGTH) questions.push({
+		field: "name",
+		text: `Name "${spec.name}" is ${spec.name.length} characters — the published @orkestrel/<name> must fit npm's 214-character limit (max ${MAX_NAME_LENGTH})`,
+		blocking: true
+	});
+	if (!VERSION_PATTERN.test(spec.version)) questions.push({
+		field: "version",
+		text: `Version "${spec.version}" must match ${VERSION_PATTERN.source}`,
+		blocking: true
+	});
+	if (!ENGINES_PATTERN.test(spec.engines)) questions.push({
+		field: "engines",
+		text: `Engines "${spec.engines}" must match ${ENGINES_PATTERN.source}`,
+		blocking: true
+	});
+	const seenOverridePaths = /* @__PURE__ */ new Set();
+	for (const item of spec.overrides) {
+		if (seenOverridePaths.has(item.path)) questions.push({
+			field: "overrides",
+			text: `Override path "${item.path}" is declared more than once`,
+			blocking: true
+		});
+		seenOverridePaths.add(item.path);
+		if (item.content.length === 0) questions.push({
+			field: "overrides",
+			text: `Override path "${item.path}" has empty content`,
+			blocking: true
+		});
+	}
+	if (spec.surfaces.length === 0) questions.push({
+		field: "surfaces",
+		text: "At least one surface is required",
+		blocking: true
+	});
+	else {
+		for (const surface of spec.surfaces) if (!SURFACES.includes(surface)) questions.push({
+			field: "surfaces",
+			text: `Surface "${surface}" is not recognized`,
+			blocking: true,
+			candidates: [...SURFACES]
+		});
+		if (new Set(spec.surfaces).size !== spec.surfaces.length) questions.push({
+			field: "surfaces",
+			text: "Surfaces must not repeat — a repeat produces duplicate members",
+			blocking: true
+		});
+		if (spec.surfaces.length > 1 && !spec.surfaces.includes("core")) questions.push({
+			field: "surfaces",
+			text: "The browser+server combination without core has no defined configuration class — declare core alongside them, or declare a single surface",
+			blocking: true
+		});
+	}
+	const dependenciesResult = validateDependencyArray("dependencies", spec.dependencies);
+	const peersResult = validateDependencyArray("peers", spec.peers);
+	const extrasResult = validateDependencyArray("extras", spec.extras);
+	questions.push(...dependenciesResult.questions, ...peersResult.questions, ...extrasResult.questions);
+	const seenDependencies = dependenciesResult.seen;
+	const seenPeers = peersResult.seen;
+	const seenExtras = extrasResult.seen;
+	for (const name of seenPeers) if (seenDependencies.has(name)) questions.push({
+		field: "peers",
+		text: `Dependency "${name}" is declared in both "dependencies" and "peers"`,
+		blocking: true
+	});
+	for (const name of seenExtras) {
+		if (seenDependencies.has(name)) questions.push({
+			field: "extras",
+			text: `Dependency "${name}" is declared in both "dependencies" and "extras"`,
+			blocking: true
+		});
+		if (seenPeers.has(name)) questions.push({
+			field: "extras",
+			text: `Dependency "${name}" is declared in both "peers" and "extras"`,
+			blocking: true
+		});
+	}
+	return {
+		valid: questions.length === 0,
+		questions,
+		warnings: []
+	};
+}
+/**
+* Narrow an unknown value to a plain (non-array, non-null) JSON object.
+*
+* @param value - The value to narrow.
+* @returns `true` iff `value` is a non-null, non-array object.
+*
+* @example
+* ```ts
+* import { isRecord } from '@orkestrel/scaffold'
+*
+* isRecord({ a: 1 }) // true
+* isRecord([1, 2]) // false
+* isRecord(null) // false
+* ```
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Parse a `package.json` text into its declared `@orkestrel/*` dependencies.
+*
+* @param manifestText - The `package.json` file content.
+* @remarks
+* Reads `dependencies`, `devDependencies`, and `peerDependencies` (ALL three,
+* in that order), keeps only `DEPENDENCY_NAME_PATTERN`-shaped names,
+* deduplicated (first occurrence wins). Malformed JSON, a non-object root, or
+* a non-object/non-string section entry is skipped, never thrown.
+* @returns The declared `Dependency[]` — pure, never throws.
+*
+* @example
+* ```ts
+* import { manifestToDependencies } from '@orkestrel/scaffold'
+*
+* manifestToDependencies('{"dependencies":{"@orkestrel/contract":"^0.0.5"}}')
+* // [{ name: '@orkestrel/contract', range: '^0.0.5' }]
+* ```
+*/
+function manifestToDependencies(manifestText) {
+	let parsed;
+	try {
+		parsed = JSON.parse(manifestText);
+	} catch {
+		return [];
+	}
+	if (!isRecord(parsed)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const dependencies = [];
+	for (const section of [
+		"dependencies",
+		"devDependencies",
+		"peerDependencies"
+	]) {
+		const entries = parsed[section];
+		if (!isRecord(entries)) continue;
+		for (const [name, range] of Object.entries(entries)) {
+			if (typeof range !== "string") continue;
+			if (!DEPENDENCY_NAME_PATTERN.test(name)) continue;
+			if (seen.has(name)) continue;
+			seen.add(name);
+			dependencies.push({
+				name,
+				range
+			});
+		}
+	}
+	return dependencies;
+}
+/**
+* Compare a declared range to the registry latest.
+*
+* @param range - The declared semver range.
+* @param latest - The registry's latest published version.
+* @remarks
+* The `0.0.x` exact-pin law: `'current'` iff `range`'s `^0.0.N` exact pin
+* equals `latest`, else `'behind'`. The `'missing'` / `'failed'` verdicts
+* come from the fetch layer, never this pure comparison.
+* @returns `'current'` or `'behind'`.
+*
+* @example
+* ```ts
+* import { rangeToFreshness } from '@orkestrel/scaffold'
+*
+* rangeToFreshness('^0.0.5', '0.0.5') // 'current' — pinned to latest
+* rangeToFreshness('^0.0.5', '0.0.7') // 'behind' — a newer patch is published
+* ```
+*/
+function rangeToFreshness(range, latest) {
+	return range.replace(/^\^/, "") === latest ? "current" : "behind";
+}
+/**
+* Compute a canonical FNV-1a digest of a text string.
+*
+* @param text - The text to digest.
+* @remarks
+* The 32-bit FNV-1a offset basis/prime, `Math.imul` for the wraparound
+* multiply, rendered as an 8-hex-digit zero-padded lowercase string —
+* deterministic, no clocks or randomness.
+* @returns The 8-hex-digit FNV-1a digest of `text`.
+*
+* @example
+* ```ts
+* import { computeHash } from '@orkestrel/scaffold'
+*
+* computeHash('hello-world') // '428d118e'
+* ```
+*/
+function computeHash(text) {
+	let hash = 2166136261;
+	for (let index = 0; index < text.length; index += 1) {
+		hash ^= text.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/**
+* Serialize a value to a canonical, key-order-INDEPENDENT JSON-like string.
+*
+* @param value - The value to stringify.
+* @remarks
+* Object keys sort code-unit; array order is preserved. So two
+* logically-equal blueprints built with their fields in a different
+* construction order still hash identically once fed through `computeHash`.
+* @returns The canonical string form of `value`.
+*
+* @example
+* ```ts
+* import { stableStringify } from '@orkestrel/scaffold'
+*
+* stableStringify({ b: 1, a: 2 }) // '{"a":2,"b":1}'
+* ```
+*/
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	if (typeof value === "object" && value !== null) return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(",")}}`;
+	return JSON.stringify(value);
+}
+/**
+* Return a fresh `Plan` with `trace` and `hash` filled.
+*
+* @param plan - The plan to pin.
+* @remarks
+* `hash` is a canonical `computeHash` digest of the plan's
+* blueprint/groups/artifacts, serialized through `stableStringify` —
+* deterministic, no clocks or randomness. `trace` is a one-line derivation
+* summary built from the plan's own `PlanSummary`.
+* @returns The plan with `trace` and `hash` filled.
+*
+* @example
+* ```ts
+* import { pinPlan } from '@orkestrel/scaffold'
+*
+* pinPlan(plan).trace // 'router · core+browser · groups:7 · artifacts:21'
+* ```
+*/
+function pinPlan(plan) {
+	const canonical = stableStringify({
+		blueprint: plan.blueprint,
+		groups: plan.groups,
+		artifacts: plan.artifacts
+	});
+	const summary = planToSummary(plan);
+	const trace = `${plan.blueprint.name} · ${summary.surfaces.join("+")} · groups:${summary.groups.length} · artifacts:${summary.artifacts}`;
+	return {
+		...plan,
+		trace,
+		hash: computeHash(canonical)
+	};
+}
+//#endregion
+//#region src/core/templates.ts
+/**
+* The shipped, versioned `TemplateDefinition` data behind every
+* `template`-origin artifact `blueprintToPlan` renders.
+*
+* @remarks
+* The generated-minimal stub prose/source, expressed as `{{name}}` /
+* `{{pascal}}` `{{token}}` placeholders for `@orkestrel/template`'s pure
+* `fillTemplate` LEAF. Only genuinely templated PROSE / source artifacts live
+* here — the token-collision boundary (AGENTS §14, this guide's Contract
+* invariant 3) keeps every STRUCTURAL file (`package.json`, the tsconfigs,
+* the vite configs) `computed` inside `blueprintToPlan` instead, so a literal
+* `{{…}}` in a config can never be mistaken for a placeholder. A convention
+* change here is a version bump of this package, never a hand-edit of a
+* scaffolded repo's copy.
+*/
+var TEMPLATES = (() => {
+	const EXPORT_KEYWORD = "export";
+	const CONST_KEYWORD = "const";
+	const IMPORT_KEYWORD = "import";
+	const FUNCTION_KEYWORD = "function";
+	return Object.freeze({
+		readme: Object.freeze({
+			id: "readme",
+			name: "readme",
+			summary: "The package root README — install, usage, and the guide's pointer.",
+			category: "docs",
+			placeholders: Object.freeze([Object.freeze({
+				name: "name",
+				description: "The lowercase-hyphen package name."
+			}), Object.freeze({
+				name: "pascal",
+				description: "The PascalCase entity name."
+			})]),
+			content: `# @orkestrel/{{name}}
+
+TODO: one-line description. Part of the \`@orkestrel\` line.
+
+## Install
+
+\`\`\`sh
+npm install @orkestrel/{{name}}
+\`\`\`
+
+## Usage
+
+\`\`\`ts
+import { create{{pascal}} } from '@orkestrel/{{name}}'
+
+${CONST_KEYWORD} instance = create{{pascal}}({ id: 'example' })
+\`\`\`
+
+## Guide
+
+For the full surface, see [\`guides/src/{{name}}.md\`](guides/src/{{name}}.md).
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).
+`
+		}),
+		guide: Object.freeze({
+			id: "guide",
+			name: "guide",
+			summary: "The package's own guide stub, with its Surface tables filled in.",
+			category: "guides",
+			placeholders: Object.freeze([
+				Object.freeze({
+					name: "name",
+					description: "The lowercase-hyphen package name."
+				}),
+				Object.freeze({
+					name: "pascal",
+					description: "The PascalCase entity name."
+				}),
+				Object.freeze({
+					name: "primary",
+					description: "The primary Surface (`core` when declared, else the sole surface)."
+				}),
+				Object.freeze({
+					name: "source",
+					description: "The rendered \"Source: …\" fragment over every declared surface."
+				}),
+				Object.freeze({
+					name: "barrel",
+					description: "The rendered \"Surfaced through …\" sentence."
+				}),
+				Object.freeze({
+					name: "tests",
+					description: "The rendered per-surface Tests section body."
+				}),
+				Object.freeze({
+					name: "factories",
+					description: "The rendered Factories surface table."
+				}),
+				Object.freeze({
+					name: "entities",
+					description: "The rendered Entities surface table."
+				}),
+				Object.freeze({
+					name: "types",
+					description: "The rendered Types surface table."
+				})
+			]),
+			content: `# {{pascal}}
+
+> TODO: one-paragraph description of \`{{pascal}}\` — what it is, what problem it
+> solves, and how it fits the \`@orkestrel\` line. Source: {{source}}.
+> {{barrel}}
+
+## Surface
+
+TODO: a short intro line, then a minimal usage example:
+
+\`\`\`ts
+import { create{{pascal}} } from '@src/{{primary}}'
+
+${CONST_KEYWORD} instance = create{{pascal}}({ id: 'example' })
+\`\`\`
+
+### Factories
+
+{{factories}}
+
+### Entities
+
+{{entities}}
+
+### Types
+
+{{types}}
+
+## Tests
+
+{{tests}}
+
+## See also
+
+- [\`AGENTS.md\`](../../AGENTS.md) — the rules.
+- [\`guide.md\`](guide.md) — the mirrored guide for \`@orkestrel/guide\`, the
+  devDependency powering this repo's guides-parity test suite.
+- [\`README.md\`](../README.md) — the guides index.
+`
+		}),
+		guidesReadme: Object.freeze({
+			id: "guidesReadme",
+			name: "guidesReadme",
+			summary: "The dual-axis guides index — by concept and by directory.",
+			category: "guides",
+			placeholders: Object.freeze([Object.freeze({
+				name: "concept",
+				description: "The rendered by-concept index table."
+			}), Object.freeze({
+				name: "directory",
+				description: "The rendered by-directory index table."
+			})]),
+			content: `# Guides
+
+A dual-axis index into this repository's guides — by concept, and by directory (AGENTS §22).
+
+## By concept
+
+{{concept}}
+
+## By directory
+
+{{directory}}
+
+## Dependency reference
+
+[\`src/guide.md\`](src/guide.md) is a byte-identical mirror of the guide for
+\`@orkestrel/guide\` — the devDependency powering this repo's guides-parity test
+suite (\`tests/guides/src/parity.test.ts\`). It documents **that package's**
+surface (\`Guide\` / \`Source\`, the manifest and comparison helpers), not anything
+sourced in this repo; it is kept here so a reader of the parity suite can see
+the primitives it is built from without leaving this guide set.
+
+## See also
+
+- [\`AGENTS.md\`](../AGENTS.md) — the rules; §22 documentation-as-contracts.
+`
+		}),
+		types: Object.freeze({
+			id: "types",
+			name: "types",
+			summary: "The generated-minimal `src/core/types.ts` stub.",
+			category: "source",
+			placeholders: Object.freeze([Object.freeze({
+				name: "pascal",
+				description: "The PascalCase entity name."
+			})]),
+			content: `/** Options for \`create{{pascal}}\`. */
+${EXPORT_KEYWORD} interface {{pascal}}Options {
+	readonly id?: string
+}
+
+/** A working \`{{pascal}}\` — pure data, no behavior. */
+${EXPORT_KEYWORD} interface {{pascal}}Interface {
+	readonly id: string
+}
+`
+		}),
+		entity: Object.freeze({
+			id: "entity",
+			name: "entity",
+			summary: "The generated-minimal `src/core/{Pascal}.ts` entity stub.",
+			category: "source",
+			placeholders: Object.freeze([Object.freeze({
+				name: "pascal",
+				description: "The PascalCase entity name."
+			})]),
+			content: `import type { {{pascal}}Interface, {{pascal}}Options } from './types.js'
+
+/**
+ * A working \`{{pascal}}\` — pure data, no behavior.
+ *
+ * @example
+ * \`\`\`ts
+ * const instance = new {{pascal}}({ id: 'example' })
+ * \`\`\`
+ */
+${EXPORT_KEYWORD} class {{pascal}} implements {{pascal}}Interface {
+	readonly id: string
+
+	constructor(options: {{pascal}}Options = {}) {
+		this.id = typeof options.id === 'string' ? options.id : crypto.randomUUID()
+	}
+}
+`
+		}),
+		factories: Object.freeze({
+			id: "factories",
+			name: "factories",
+			summary: "The generated-minimal `src/core/factories.ts` stub.",
+			category: "source",
+			placeholders: Object.freeze([Object.freeze({
+				name: "pascal",
+				description: "The PascalCase entity name."
+			})]),
+			content: `import type { {{pascal}}Interface, {{pascal}}Options } from './types.js'
+import { {{pascal}} } from './{{pascal}}.js'
+
+/**
+ * Create a \`{{pascal}}Interface\`.
+ *
+ * @param options - An optional \`id\` (defaults to a random UUID)
+ * @returns A working {@link {{pascal}}Interface}
+ *
+ * @example
+ * \`\`\`ts
+ * import { create{{pascal}} } from '@src/core'
+ *
+ * ${CONST_KEYWORD} instance = create{{pascal}}({ id: 'example' })
+ * \`\`\`
+ */
+${EXPORT_KEYWORD} function create{{pascal}}(options: {{pascal}}Options = {}): {{pascal}}Interface {
+	return new {{pascal}}(options)
+}
+`
+		}),
+		index: Object.freeze({
+			id: "index",
+			name: "index",
+			summary: "The generated-minimal `src/core/index.ts` barrel stub.",
+			category: "source",
+			placeholders: Object.freeze([Object.freeze({
+				name: "pascal",
+				description: "The PascalCase entity name."
+			})]),
+			content: `export type * from './types.js'
+export * from './{{pascal}}.js'
+export * from './factories.js'
+`
+		}),
+		setup: Object.freeze({
+			id: "setup",
+			name: "setup",
+			summary: "The generated-minimal `tests/setup.ts` recorder helper — no placeholders.",
+			category: "tests",
+			placeholders: Object.freeze([]),
+			content: `// ── Call recorder (a real callback, not a mock) ──────────────────────────────
+//
+// AGENTS §16.1: when a test only needs to count calls or inspect arguments, use a
+// recorder — a real listener that records every invocation — rather than a test-
+// framework spy. \`handler\` is a genuine callback; \`calls\` is each invocation's
+// argument tuple, in order.
+
+/** A real call-recording callback over an argument tuple (AGENTS §16.1). */
+${EXPORT_KEYWORD} interface TestRecorderInterface<TArgs extends readonly unknown[]> {
+	readonly calls: readonly TArgs[]
+	readonly count: number
+	readonly handler: (...args: TArgs) => void
+	clear(): void
+}
+
+/**
+ * Create a {@link TestRecorderInterface} — a real callback that records each
+ * invocation's arguments, for asserting what fired and with what (AGENTS §16.1).
+ *
+ * @typeParam TArgs - The argument tuple the recorded handler receives
+ * @returns A recorder whose \`handler\` records into \`calls\`
+ */
+${EXPORT_KEYWORD} function createRecorder<TArgs extends readonly unknown[]>(): TestRecorderInterface<TArgs> {
+	const calls: TArgs[] = []
+	return {
+		get calls() {
+			return calls
+		},
+		get count() {
+			return calls.length
+		},
+		handler(...args: TArgs) {
+			calls.push(args)
+		},
+		clear() {
+			calls.length = 0
+		},
+	}
+}
+`
+		}),
+		setupServer: Object.freeze({
+			id: "setupServer",
+			name: "setupServer",
+			summary: "The generated-minimal `tests/setupServer.ts` node-only helper — no placeholders.",
+			category: "tests",
+			placeholders: Object.freeze([]),
+			content: `// AGENTS §16.1: node-only test helpers anchor \`node:fs\` fixture loaders to
+// this workspace root rather than a relative path, so a loader works
+// regardless of the running test file's directory depth. Add server-specific
+// fixtures/helpers here as this surface grows beyond the shared recorder in
+// tests/setup.ts.
+
+${IMPORT_KEYWORD} { fileURLToPath } from 'node:url'
+
+/** The workspace root, for anchoring \`node:fs\` fixture loaders (AGENTS §16.1). */
+${EXPORT_KEYWORD} ${CONST_KEYWORD} WORKSPACE_ROOT = fileURLToPath(new URL('../', import.meta.url))
+`
+		}),
+		setupBrowser: Object.freeze({
+			id: "setupBrowser",
+			name: "setupBrowser",
+			summary: "The generated-minimal `tests/setupBrowser.ts` DOM-only helper — no placeholders.",
+			category: "tests",
+			placeholders: Object.freeze([]),
+			content: `// AGENTS §16.1: DOM/browser-only test helpers (builders, CSS assertion
+// primitives) go here as this surface grows fixtures beyond the shared
+// recorder in tests/setup.ts.
+
+// TODO: [Browser] add browser/DOM test helpers as this surface grows.
+export {}
+`
+		}),
+		entityTest: Object.freeze({
+			id: "entityTest",
+			name: "entityTest",
+			summary: "The generated-minimal `tests/src/<surface>/{Pascal}.test.ts` stub.",
+			category: "tests",
+			placeholders: Object.freeze([Object.freeze({
+				name: "pascal",
+				description: "The PascalCase entity name."
+			}), Object.freeze({
+				name: "surface",
+				description: "The owning Surface (`core`/`browser`/`server`)."
+			})]),
+			content: `import type { {{pascal}}Interface } from '@src/{{surface}}'
+import { {{pascal}} } from '@src/{{surface}}'
+import { describe, expect, it } from 'vitest'
+
+// The {{pascal}} entity — id assignment (explicit / generated) and independence
+// across instances. Factory-level assertions live in factories.test.ts.
+
+describe('{{pascal}}', () => {
+	it('round-trips an explicit id', () => {
+		const instance: {{pascal}}Interface = new {{pascal}}({ id: 'example' })
+
+		expect(instance.id).toBe('example')
+	})
+
+	it('generates a non-empty id when none is given', () => {
+		const instance = new {{pascal}}()
+
+		expect(typeof instance.id).toBe('string')
+		expect(instance.id.length).toBeGreaterThan(0)
+	})
+
+	it('gives distinct instances distinct generated ids', () => {
+		const a = new {{pascal}}()
+		const b = new {{pascal}}()
+
+		expect(a.id).not.toBe(b.id)
+	})
+})
+`
+		}),
+		factoriesTest: Object.freeze({
+			id: "factoriesTest",
+			name: "factoriesTest",
+			summary: "The generated-minimal `tests/src/<surface>/factories.test.ts` stub.",
+			category: "tests",
+			placeholders: Object.freeze([Object.freeze({
+				name: "pascal",
+				description: "The PascalCase entity name."
+			}), Object.freeze({
+				name: "surface",
+				description: "The owning Surface (`core`/`browser`/`server`)."
+			})]),
+			content: `import type { {{pascal}}Interface } from '@src/{{surface}}'
+import { create{{pascal}}, {{pascal}} } from '@src/{{surface}}'
+import { describe, expect, expectTypeOf, it } from 'vitest'
+
+// The {{pascal}} factory — that \`create{{pascal}}\` returns a working {{pascal}}Interface
+// backed by a real {{pascal}} instance.
+
+describe('create{{pascal}}', () => {
+	it('returns a {{pascal}} instance', () => {
+		const instance = create{{pascal}}()
+
+		expect(instance).toBeInstanceOf({{pascal}})
+	})
+
+	it('honors the id option', () => {
+		${CONST_KEYWORD} instance = create{{pascal}}({ id: 'example' })
+
+		expect(instance.id).toBe('example')
+	})
+
+	it('create{{pascal}} returns a {{pascal}}Interface', () => {
+		expectTypeOf(create{{pascal}}()).toEqualTypeOf<{{pascal}}Interface>()
+	})
+})
+`
+		}),
+		parityTest: Object.freeze({
+			id: "parityTest",
+			name: "parityTest",
+			summary: "The consumer-side guides-parity drop-in — `tests/guides/src/parity.test.ts`.",
+			category: "tests",
+			placeholders: Object.freeze([Object.freeze({
+				name: "name",
+				description: "The lowercase-hyphen package name."
+			}), Object.freeze({
+				name: "specifiers",
+				description: "The computed SELF_SPECIFIERS / SPECIFIER_MODULES / exportsFor block, one shape for every surface count."
+			})]),
+			content: `// The consumer-side guides-parity drop-in: runs \`@orkestrel/guide\`'s
+// checks against this repo's own \`guides/README.md\` manifest.
+
+${IMPORT_KEYWORD} { describe, expect, it } from 'vitest'
+${IMPORT_KEYWORD} { readdirSync, readFileSync } from 'node:fs'
+${IMPORT_KEYWORD} { fileURLToPath } from 'node:url'
+${IMPORT_KEYWORD} { join } from 'node:path'
+${IMPORT_KEYWORD} {
+	createGuide,
+	createSource,
+	fenceImports,
+	findMissing,
+	findUnexampled,
+	isExternalLink,
+	missingSymbols,
+	parseManifest,
+	resolveLink,
+	symbolKey,
+} from '@orkestrel/guide'
+
+${CONST_KEYWORD} ROOT = fileURLToPath(new URL('../../../', import.meta.url))
+${CONST_KEYWORD} WALK_DIRS = ['src', 'guides', 'tests']
+
+${FUNCTION_KEYWORD} walk(dir: string, acc: Record<string, string>): void {
+	for (const entry of readdirSync(join(ROOT, dir), { withFileTypes: true })) {
+		const relative = \`\${dir}/\${entry.name}\`
+		if (entry.isDirectory()) {
+			walk(relative, acc)
+			continue
+		}
+		if (!entry.name.endsWith('.ts') && !entry.name.endsWith('.md')) continue
+		acc[relative] = readFileSync(join(ROOT, relative), 'utf8')
+	}
+}
+
+${CONST_KEYWORD} files: Record<string, string> = {}
+for (const dir of WALK_DIRS) walk(dir, files)
+files['AGENTS.md'] = readFileSync(join(ROOT, 'AGENTS.md'), 'utf8')
+
+${FUNCTION_KEYWORD} readText(relative: string): string {
+	const text = files[relative]
+	if (text === undefined) throw new Error(\`Missing file: \${relative}\`)
+	return text
+}
+
+${CONST_KEYWORD} manifest = parseManifest(readText('guides/README.md'), 'guides')
+
+{{specifiers}}
+
+it('manifest lists at least one guide', () => {
+	expect(manifest.length).toBeGreaterThan(0)
+})
+
+for (const entry of manifest) {
+	const guide = createGuide(readText(entry.spec))
+	const source = createSource({ files, module: entry.source })
+
+	describe(\`\${entry.concept}\`, () => {
+		it('extracts a non-empty documented surface', () => {
+			expect(guide.surface().length).toBeGreaterThan(0)
+		})
+		it('documents every source export', () => {
+			expect(missingSymbols(source.exports(), guide.surface())).toEqual([])
+		})
+		it('documents only real exports', () => {
+			expect(missingSymbols(guide.surface(), source.exports())).toEqual([])
+		})
+
+		it('exposes no hidden module-scope declarations', () => {
+			expect(source.hidden().map(symbolKey)).toEqual([])
+		})
+
+		for (const group of guide.methods()) {
+			const members = source.methods(group.interface)
+			const entity = group.interface.replace(/Interface$/, '')
+			describe(\`\${group.interface}\`, () => {
+				it('documents at least one method', () => {
+					expect(group.methods.length).toBeGreaterThan(0)
+				})
+				it('documents every interface method', () => {
+					expect(findMissing(members, group.methods)).toEqual([])
+				})
+				it('documents no phantom method', () => {
+					expect(findMissing(group.methods, members)).toEqual([])
+				})
+				it(\`\${entity} exposes no undocumented method\`, () => {
+					const extra =
+						entity === group.interface ? [] : findMissing(source.methods(entity), group.methods)
+					expect(extra).toEqual([])
+				})
+			})
+		}
+
+		it('documents an example for every Surface function', () => {
+			const fences = guide.patterns()
+			const names = guide
+				.surface()
+				.filter((symbol) => symbol.kind === 'function')
+				.map((symbol) => symbol.name)
+			expect(findUnexampled(names, fences, source.examples())).toEqual([])
+		})
+
+		for (const group of guide.methods()) {
+			const entity = group.interface.replace(/Interface$/, '')
+			describe(\`\${group.interface} examples\`, () => {
+				it('documents an example for every method', () => {
+					const fences = guide.patterns()
+					const examples =
+						entity === group.interface
+							? source.examples(group.interface)
+							: source.examples(group.interface).concat(source.examples(entity))
+					expect(findUnexampled(group.methods, fences, examples)).toEqual([])
+				})
+			})
+		}
+
+		it('imports only real exports in every \`\`\`ts fence', () => {
+			for (const fence of guide.patterns()) {
+				for (const { specifier, names } of fenceImports(fence)) {
+					if (!SELF_SPECIFIERS.includes(specifier)) continue
+					expect(findMissing(names, exportsFor(specifier))).toEqual([])
+				}
+			}
+		})
+
+		it('resolves every relative link', () => {
+			const broken = guide
+				.links()
+				.filter((href) => !isExternalLink(href))
+				.map((href) => resolveLink(entry.spec, href))
+				.filter((path) => !source.exists(path))
+			expect(broken).toEqual([])
+		})
+		it('links only to test files that exist', () => {
+			const missing = guide
+				.tests()
+				.map((href) => resolveLink(entry.spec, href))
+				.filter((path) => !source.exists(path))
+			expect(missing).toEqual([])
+		})
+	})
+}
+`
+		})
+	});
+})();
+//#endregion
+//#region src/core/compilers.ts
+/**
+* Resolve the `Group` a byte-copied `HOST_PATHS` entry belongs to.
+*
+* @param path - A `HOST_PATHS` entry.
+* @returns The owning `Group`.
+*
+* @example
+* ```ts
+* hostGroup('AGENTS.md') // 'docs'
+* hostGroup('.claude') // 'orchestration'
+* ```
+*/
+function hostGroup(path) {
+	if (path === "AGENTS.md" || path === "CLAUDE.md" || path === "LICENSE") return "docs";
+	if (path === ".claude" || path === "scripts/deps.sh" || path === "scripts/cursor.sh" || path === "scripts/ollama.sh" || path === ".github/workflows/ci.yml") return "orchestration";
+	if (path === "guides/src/guide.md" || path === "guides/src/scaffold.md") return "guides";
+	return "configs";
+}
+/**
+* Fill one `TEMPLATES` entry into a `template`-origin `Artifact`, optionally
+* tagged with the owning `Surface` (source/tests artifacts that live under a
+* declared surface's tree).
+*
+* @param path - The artifact's output path.
+* @param group - The artifact's `Group`.
+* @param id - The `TEMPLATES` entry id to fill.
+* @param values - The placeholder values to fill the template with.
+* @param surface - The owning `Surface`, when the artifact lives under a declared surface's tree.
+* @returns The filled `template`-origin `Artifact`.
+*
+* @example
+* ```ts
+* fillArtifact('README.md', 'docs', 'readme', { name: 'router', pascal: 'Router' })
+* // { path: 'README.md', group: 'docs', origin: 'template', content: '# router\n…' }
+* ```
+*/
+function fillArtifact(path, group, id, values, surface) {
+	const definition = TEMPLATES[id];
+	if (!definition) throw new Error(`Unknown template id: ${id}`);
+	const content = fillTemplate(definition.content, values, {
+		missing: "error",
+		placeholders: definition.placeholders
+	});
+	return surface === void 0 ? {
+		path,
+		group,
+		origin: "template",
+		content
+	} : {
+		path,
+		group,
+		origin: "template",
+		surface,
+		content
+	};
+}
+/**
+* Classify a blueprint's surfaces into the manifest/exports variant class.
+*
+* @param surfaces - The declared `Surface[]`.
+* @returns The sole declared `Surface`, or `'multi'` when two or more are declared.
+*
+* @example
+* ```ts
+* surfaceVariant(['core']) // 'core'
+* surfaceVariant(['core', 'server']) // 'multi'
+* ```
+*/
+function surfaceVariant(surfaces) {
+	if (surfaces.length > 1) return "multi";
+	const [only] = surfaces;
+	return only ?? "core";
+}
+/**
+* Build the `main` / `module` / top-level `types` entry fields.
+*
+* @param surfaces - The declared `Surface[]`.
+* @returns The `package.json` `main` / `module` / optional `types` fields.
+*
+* @example
+* ```ts
+* entryFields(['browser']).main // './dist/src/browser/index.js'
+* ```
+*/
+function entryFields(surfaces) {
+	const variant = surfaceVariant(surfaces);
+	if (variant === "multi") return {
+		main: "./dist/src/core/index.cjs",
+		module: "./dist/src/core/index.js"
+	};
+	const root = variant;
+	if (root === "browser") return {
+		main: "./dist/src/browser/index.js",
+		module: "./dist/src/browser/index.js",
+		types: "./dist/src/browser/index.d.ts"
+	};
+	if (root === "server") return {
+		main: "./dist/src/server/index.cjs",
+		module: "./dist/src/server/index.js",
+		types: "./dist/src/server/index.d.ts"
+	};
+	return {
+		main: "./dist/src/core/index.cjs",
+		module: "./dist/src/core/index.js",
+		types: "./dist/src/core/index.d.ts"
+	};
+}
+/**
+* One dual-format (`import` + `require`) `exports` condition block.
+*
+* @param path - The extensionless dist path to point both conditions at.
+* @returns The dual `import`/`require` exports condition object.
+*
+* @example
+* ```ts
+* dualCondition('./dist/src/core/index')
+* // { import: { types: '….d.ts', default: '….js' }, require: { types: '….d.cts', default: '….cjs' } }
+* ```
+*/
+function dualCondition(path) {
+	return {
+		import: {
+			types: `${path}.d.ts`,
+			default: `${path}.js`
+		},
+		require: {
+			types: `${path}.d.cts`,
+			default: `${path}.cjs`
+		}
+	};
+}
+/**
+* Build the `package.json` `exports` map.
+*
+* @param surfaces - The declared `Surface[]`.
+* @returns The `package.json` `exports` map.
+*
+* @example
+* ```ts
+* exportsMap(['core'])['.'] // dual import/require condition block
+* ```
+*/
+function exportsMap(surfaces) {
+	const variant = surfaceVariant(surfaces);
+	if (variant === "browser") return {
+		".": {
+			types: "./dist/src/browser/index.d.ts",
+			import: "./dist/src/browser/index.js",
+			default: "./dist/src/browser/index.js"
+		},
+		"./package.json": "./package.json"
+	};
+	if (variant === "server") return {
+		".": dualCondition("./dist/src/server/index"),
+		"./package.json": "./package.json"
+	};
+	if (variant === "core") return {
+		".": dualCondition("./dist/src/core/index"),
+		"./package.json": "./package.json"
+	};
+	const map = { ".": dualCondition("./dist/src/core/index") };
+	for (const surface of surfaces) {
+		if (surface === "core") continue;
+		const row = SURFACE_MATRIX[surface];
+		if (surface === "browser") {
+			map[row.path] = { import: {
+				types: "./dist/src/browser/index.d.ts",
+				default: "./dist/src/browser/index.js"
+			} };
+			continue;
+		}
+		map[row.path] = dualCondition(`./dist/src/${surface}/index`);
+	}
+	map["./package.json"] = "./package.json";
+	return map;
+}
+/**
+* A code-unit (not locale-sensitive) comparator — matches the `keywords` sort
+* and keeps ordering stable across locales/environments.
+*
+* @param a - The first string.
+* @param b - The second string.
+* @returns `-1` / `0` / `1` per code-unit order.
+*
+* @example
+* ```ts
+* [...['b', 'a']].sort(compareCodeUnit) // ['a', 'b']
+* ```
+*/
+function compareCodeUnit(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+* The devDependency baseline — every repo in the line carries the same set
+* (`@vitest/browser-playwright` included regardless of a browser surface: both
+* @orkestrel/middleware, core+server, and @orkestrel/router, core+browser+server,
+* ship it — grounded, not conditional). A package's `extras` (code-unit sorted)
+* merge in on top, the extras' declared range winning on a name collision with
+* the baseline.
+*
+* @param extras - The blueprint's package-specific `extras` `Dependency[]`.
+* @returns The merged `devDependencies` record.
+*
+* @example
+* ```ts
+* devDependenciesFor([])['typescript'] // '^6.0.3'
+* ```
+*/
+function devDependenciesFor(extras) {
+	const baseline = {
+		"@microsoft/api-extractor": "^7.58.11",
+		"@orkestrel/guide": "^0.0.5",
+		"@orkestrel/scaffold": SCAFFOLD_RANGE,
+		"@types/node": "^26.1.1",
+		"@vitest/browser-playwright": "^4.1.10",
+		oxfmt: "^0.59.0",
+		oxlint: "^1.74.0",
+		typescript: "^6.0.3",
+		vite: "^8.1.5",
+		"vite-plugin-dts": "^5.0.3",
+		vitest: "^4.1.10"
+	};
+	for (const extra of [...extras].sort((a, b) => compareCodeUnit(a.name, b.name))) baseline[extra.name] = extra.range;
+	return baseline;
+}
+/**
+* Compute the `package.json` artifact's `content`, applying the manifest and
+* exports combination rules over a blueprint's surfaces — grounded against the
+* live @orkestrel/middleware (core+server) and @orkestrel/router
+* (core+browser+server) exemplars.
+*
+* @param spec - The `Blueprint` to derive the manifest from.
+* @returns The `package.json` file content, newline-terminated.
+*
+* @example
+* ```ts
+* packageManifest(blueprint('router')) // '{\n\t"name": "@orkestrel/router",\n…}\n'
+* ```
+*/
+function packageManifest(spec) {
+	const entry = entryFields(spec.surfaces);
+	const dependencies = {};
+	for (const dep of [...spec.dependencies].sort((a, b) => compareCodeUnit(a.name, b.name))) dependencies[dep.name] = dep.range;
+	const peerDependencies = {};
+	for (const peer of [...spec.peers].sort((a, b) => compareCodeUnit(a.name, b.name))) peerDependencies[peer.name] = peer.range;
+	const peerDependenciesMeta = {};
+	for (const peer of spec.peers) if (peer.optional === true) peerDependenciesMeta[peer.name] = { optional: true };
+	const scripts = {
+		clean: "node -e \"try{require('node:fs').rmSync('dist',{recursive:true,force:true})}catch{}\"",
+		copy: "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
+		"tmp:txt": "node -e \"const fs=require('node:fs'),p=require('node:path');function walk(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory()){walk(f)}else if(!e.name.endsWith('.md')&&!e.name.endsWith('.txt')){const t=f+'.txt';if(!fs.existsSync(t)){fs.renameSync(f,t)}else{console.warn('Skipping '+f+' — target exists: '+t)}}}}try{walk('tmp')}catch(e){if(e.code!=='ENOENT')throw e}\"",
+		scaffold: "scaffold",
+		lint: "oxlint --config .oxlintrc.json --fix .",
+		check: "tsc --noEmit --project tsconfig.json && npm run check:src",
+		"check:src": spec.surfaces.map((surface) => `npm run check:src:${surface}`).join(" && ")
+	};
+	for (const surface of spec.surfaces) scripts[`check:src:${surface}`] = `tsc --noEmit -p configs/src/tsconfig.${surface}.json`;
+	scripts.format = "oxfmt --config .oxfmtrc.json --write .";
+	scripts["format:check"] = "oxfmt --config .oxfmtrc.json --check .";
+	scripts["lint:check"] = "oxlint --config .oxlintrc.json .";
+	scripts.test = "npm run test:src && npm run test:guides";
+	scripts["test:src"] = "vitest run --config vite.config.ts --no-cache --reporter=dot " + spec.surfaces.map((surface) => `--project src:${surface}`).join(" ");
+	for (const surface of spec.surfaces) scripts[`test:src:${surface}`] = `vitest run --config vite.config.ts --no-cache --reporter=dot --project src:${surface}`;
+	scripts["test:guides"] = "vitest run --config vite.config.ts --reporter=dot --project guides";
+	scripts.build = "npm run clean && npm run build:src";
+	scripts["build:src"] = spec.surfaces.map((surface) => `npm run build:src:${surface}`).join(" && ");
+	for (const surface of spec.surfaces) scripts[`build:src:${surface}`] = surface === "browser" ? `vite build --config configs/src/vite.${surface}.config.ts` : `vite build --config configs/src/vite.${surface}.config.ts && npm run copy dist/src/${surface}/index.d.ts dist/src/${surface}/index.d.cts`;
+	scripts.prepublishOnly = "npm run format:check && npm run lint:check && npm run check && npm run build && npm test";
+	const manifest = {
+		name: `@orkestrel/${spec.name}`,
+		version: spec.version,
+		description: spec.description ?? "TODO: one-line description. Part of the @orkestrel line.",
+		keywords: [...spec.keywords].sort(),
+		homepage: `https://github.com/orkestrel/${spec.name}#readme`,
+		bugs: `https://github.com/orkestrel/${spec.name}/issues`,
+		license: "MIT",
+		repository: {
+			type: "git",
+			url: `git+https://github.com/orkestrel/${spec.name}.git`
+		},
+		files: ["dist", "README.md"],
+		type: "module",
+		sideEffects: false,
+		main: entry.main,
+		module: entry.module,
+		...entry.types ? { types: entry.types } : {},
+		exports: exportsMap(spec.surfaces),
+		publishConfig: { access: "public" },
+		scripts,
+		dependencies,
+		devDependencies: devDependenciesFor(spec.extras),
+		...Object.keys(peerDependencies).length > 0 ? { peerDependencies } : {},
+		...Object.keys(peerDependenciesMeta).length > 0 ? { peerDependenciesMeta } : {},
+		engines: { node: spec.engines }
+	};
+	return `${JSON.stringify(manifest, void 0, "	")}\n`;
+}
+/**
+* The root `tsconfig.json` — one `@src/<surface>` path alias per declared
+* surface, in declared order.
+*
+* @param surfaces - The declared `Surface[]`.
+* @returns The root `tsconfig.json` file content, newline-terminated.
+*
+* @example
+* ```ts
+* rootTsconfig(['core']) // '{\n\t"compilerOptions": {…}\n}\n'
+* ```
+*/
+function rootTsconfig(surfaces) {
+	const paths = {};
+	for (const surface of surfaces) paths[`@src/${surface}`] = [`./src/${surface}/index.ts`];
+	return `${JSON.stringify({
+		compilerOptions: {
+			target: "ESNext",
+			module: "ESNext",
+			moduleResolution: "bundler",
+			lib: [
+				"ESNext",
+				"DOM",
+				"DOM.Iterable"
+			],
+			types: [
+				"node",
+				"vite/client",
+				"vitest/globals"
+			],
+			moduleDetection: "force",
+			resolveJsonModule: true,
+			strict: true,
+			noImplicitOverride: true,
+			noFallthroughCasesInSwitch: true,
+			forceConsistentCasingInFileNames: true,
+			skipLibCheck: true,
+			noEmit: true,
+			paths
+		},
+		exclude: [
+			"node_modules",
+			"dist",
+			"tmp"
+		]
+	}, void 0, "	")}\n`;
+}
+/**
+* The rendered import / `resolve` header block every `rootViteConfig` shape
+* prefixes — the Playwright import lines + `createBrowserProvider` appear
+* only when `needsPlaywright`, per the three grounded `rootViteConfig`
+* shapes: unconditional for a multi-surface blueprint, conditional on the
+* sole surface being `'browser'` for a single non-`core` surface, absent for
+* `core`-only.
+*
+* @param needsPlaywright - Whether this shape ships a browser test project (and so needs Playwright).
+* @returns The rendered header block, newline-terminated.
+*
+* @example
+* ```ts
+* viteHeader(false).includes('@vitest/browser-playwright') // false
+* viteHeader(true).includes('@vitest/browser-playwright') // true
+* ```
+*/
+function viteHeader(needsPlaywright) {
+	const EXPORT_KEYWORD = "export";
+	return `import type { UserConfig } from 'vite'
+import { defineConfig, mergeConfig } from 'vitest/config'
+import tsconfig from './tsconfig.json' with { type: 'json' }
+import { fileURLToPath, URL } from 'node:url'
+${needsPlaywright ? `import { globSync } from 'node:fs'
+import { playwright } from '@vitest/browser-playwright'
+` : ""}
+${EXPORT_KEYWORD} function resolveWorkspacePath(relativePath: string): string {
+	return fileURLToPath(new URL(relativePath, import.meta.url))
+}
+${needsPlaywright ? `
+${EXPORT_KEYWORD} function createBrowserProvider() {
+	const { PLAYWRIGHT_EXECUTABLE_PATH, PLAYWRIGHT_WS_ENDPOINT, PLAYWRIGHT_CHANNEL } = process.env
+	if (PLAYWRIGHT_EXECUTABLE_PATH)
+		return playwright({ launchOptions: { executablePath: PLAYWRIGHT_EXECUTABLE_PATH } })
+	if (PLAYWRIGHT_WS_ENDPOINT)
+		return playwright({ connectOptions: { wsEndpoint: PLAYWRIGHT_WS_ENDPOINT } })
+	if (PLAYWRIGHT_CHANNEL) return playwright({ launchOptions: { channel: PLAYWRIGHT_CHANNEL } })
+	if (process.platform === 'linux') {
+		for (const pattern of [
+			'/opt/pw-browsers/chromium',
+			'/opt/pw-browsers/chromium-*/chrome-linux64/chrome',
+			'/opt/pw-browsers/chromium-*/chrome-linux/chrome',
+		]) {
+			const [executablePath] = globSync(pattern).sort().reverse()
+			if (executablePath) return playwright({ launchOptions: { executablePath } })
+		}
+	}
+	const channel = process.platform === 'win32' ? 'msedge' : 'chrome'
+	return playwright({ launchOptions: { channel } })
+}
+` : ""}
+const resolve = {
+	alias: Object.entries(tsconfig.compilerOptions.paths).reduce(
+		(a, [k, v]) => Object.assign(a, { [k]: resolveWorkspacePath(v[0]) }),
+		{},
+	),
+}
+`;
+}
+/**
+* The single non-`core` surface's factory IS the base (Shape 3 of
+* `rootViteConfig`) — the surface's own `viteHeader` (Playwright only when
+* `surface === 'browser'`, per the live sqlite/indexeddb exemplars) prefixes
+* the surface-specific `srcBrowser` / `srcServer` + `guides` projects export.
+*
+* @param surface - The sole declared non-`core` surface.
+* @returns The root `vite.config.ts` file content for a single non-`core` surface, newline-terminated.
+*
+* @example
+* ```ts
+* singleSurfaceViteConfig('server').includes('srcServer') // true
+* ```
+*/
+function singleSurfaceViteConfig(surface) {
+	const EXPORT_KEYWORD = "export";
+	const header = viteHeader(surface === "browser");
+	if (surface === "browser") return `${header}
+${EXPORT_KEYWORD} const srcBrowser = (config?: UserConfig): UserConfig =>
+	mergeConfig(
+		{
+			resolve,
+			build: {
+				emptyOutDir: true,
+				sourcemap: true,
+				minify: false,
+				lib: {
+					entry: resolveWorkspacePath('src/browser/index.ts'),
+					formats: ['es'],
+					fileName: () => 'index.js',
+				},
+				outDir: 'dist/src/browser',
+				rolldownOptions: {
+					external: (id: string) => id.startsWith('@orkestrel/'),
+				},
+			},
+			test: {
+				name: { label: 'src:browser', color: 'yellow' },
+				include: ['tests/src/browser/**/*.test.ts'],
+				setupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts'],
+				browser: {
+					enabled: true,
+					provider: createBrowserProvider(),
+					instances: [{ browser: 'chromium', headless: true }],
+				},
+				fileParallelism: false,
+			},
+		},
+		config ?? {},
+	)
+
+${EXPORT_KEYWORD} const guides = (config?: UserConfig): UserConfig =>
+	srcBrowser(
+		mergeConfig(
+			{
+				test: {
+					name: { label: 'guides', color: 'green' },
+					include: ['tests/guides/**/*.test.ts'],
+					exclude: ['tests/src/**/*.test.ts', 'tests/setup.test.ts'],
+					environment: 'node',
+					browser: { enabled: false },
+				},
+			},
+			config ?? {},
+		),
+	)
+
+export default defineConfig({
+	resolve,
+	test: {
+		projects: [srcBrowser, guides],
+	},
+})
+`;
+	return `${header}
+${EXPORT_KEYWORD} const srcServer = (config?: UserConfig): UserConfig =>
+	mergeConfig(
+		{
+			resolve,
+			build: {
+				emptyOutDir: true,
+				sourcemap: true,
+				minify: false,
+				lib: {
+					entry: resolveWorkspacePath('src/server/index.ts'),
+					formats: ['es', 'cjs'],
+					fileName: (format: string) => (format === 'es' ? 'index.js' : 'index.cjs'),
+				},
+				outDir: 'dist/src/server',
+				target: 'node24',
+				rolldownOptions: {
+					external: (id: string) => id.startsWith('node:') || id.startsWith('@orkestrel/'),
+				},
+			},
+			test: {
+				name: { label: 'src:server', color: 'red' },
+				include: ['tests/src/server/**/*.test.ts'],
+				setupFiles: ['./tests/setup.ts', './tests/setupServer.ts'],
+				environment: 'node',
+				browser: { enabled: false },
+			},
+		},
+		config ?? {},
+	)
+
+${EXPORT_KEYWORD} const guides = (config?: UserConfig): UserConfig =>
+	srcServer(
+		mergeConfig(
+			{
+				test: {
+					name: { label: 'guides', color: 'green' },
+					include: ['tests/guides/**/*.test.ts'],
+					exclude: ['tests/src/**/*.test.ts', 'tests/setup.test.ts'],
+				},
+			},
+			config ?? {},
+		),
+	)
+
+export default defineConfig({
+	resolve,
+	test: {
+		projects: [srcServer, guides],
+	},
+})
+`;
+}
+/**
+* The root `vite.config.ts` — three grounded shapes, chosen by a blueprint's
+* `surfaces`:
+*   1. `core`-only — `srcCore` + `guides`, no Playwright at all (the live
+*      timeout exemplar: no browser project exists anywhere in the file).
+*   2. Multi-surface (2+ surfaces, always including `core` per the live
+*      middleware/router exemplars) — `srcCore` is the shared base;
+*      `srcBrowser` / `srcServer` extend it and externalize `@src/core` to
+*      the sibling build. Playwright ships UNCONDITIONALLY (middleware
+*      carries it with no browser surface — grounded, not conditional).
+*   3. A single non-`core` surface (`browser`-only / `server`-only) — the
+*      surface factory itself IS the base (no `srcCore` to extend, so no
+*      dead `@src/core` externalize/remap either — there is no sibling
+*      core build), per the live sqlite (server-only) / indexeddb
+*      (browser-only) exemplars. Playwright ships only when the sole
+*      surface is `browser` (it must run its own tests in a real browser).
+*
+* @param surfaces - The declared `Surface[]`.
+* @returns The root `vite.config.ts` file content, newline-terminated.
+*
+* @example
+* ```ts
+* rootViteConfig(['core']).includes('srcCore') // true
+* ```
+*/
+function rootViteConfig(surfaces) {
+	const EXPORT_KEYWORD = "export";
+	const hasCore = surfaces.includes("core");
+	const nonCore = surfaces.filter((surface) => surface !== "core");
+	const header = viteHeader(surfaces.length > 1 || surfaces.includes("browser"));
+	if (!hasCore) {
+		const [onlySurface] = nonCore;
+		if (onlySurface === "browser" || onlySurface === "server") return singleSurfaceViteConfig(onlySurface);
+	}
+	const browserBlock = `
+${EXPORT_KEYWORD} const srcBrowser = (config?: UserConfig): UserConfig =>
+	srcCore(
+		mergeConfig(
+			{
+				build: {
+					lib: {
+						entry: resolveWorkspacePath('src/browser/index.ts'),
+						formats: ['es'],
+						fileName: () => 'index.js',
+					},
+					outDir: 'dist/src/browser',
+					rolldownOptions: {
+						external: (id: string) => id === '@src/core' || id.startsWith('@orkestrel/'),
+						output: { paths: { '@src/core': '../core/index.js' } },
+					},
+				},
+				test: {
+					name: { label: 'src:browser', color: 'yellow' },
+					include: ['tests/src/browser/**/*.test.ts'],
+					exclude: ['tests/src/core/**/*.test.ts'],
+					setupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts'],
+					browser: {
+						enabled: true,
+						provider: createBrowserProvider(),
+						instances: [{ browser: 'chromium', headless: true }],
+					},
+					fileParallelism: false,
+				},
+			},
+			config ?? {},
+		),
+	)
+`;
+	const serverBlock = `
+${EXPORT_KEYWORD} const srcServer = (config?: UserConfig): UserConfig =>
+	srcCore(
+		mergeConfig(
+			{
+				build: {
+					lib: {
+						entry: resolveWorkspacePath('src/server/index.ts'),
+						formats: ['es', 'cjs'],
+						fileName: (format: string) => (format === 'es' ? 'index.js' : 'index.cjs'),
+					},
+					outDir: 'dist/src/server',
+					target: 'node24',
+					rolldownOptions: {
+						external: (id: string) =>
+							id === '@src/core' || id.startsWith('node:') || id.startsWith('@orkestrel/'),
+						output: [
+							{
+								format: 'es',
+								entryFileNames: 'index.js',
+								paths: { '@src/core': '../core/index.js' },
+							},
+							{
+								format: 'cjs',
+								entryFileNames: 'index.cjs',
+								paths: { '@src/core': '../core/index.cjs' },
+							},
+						],
+					},
+				},
+				test: {
+					name: { label: 'src:server', color: 'red' },
+					include: ['tests/src/server/**/*.test.ts'],
+					exclude: ['tests/src/core/**/*.test.ts'],
+					setupFiles: ['./tests/setup.ts', './tests/setupServer.ts'],
+				},
+			},
+			config ?? {},
+		),
+	)
+`;
+	return `${header}
+${EXPORT_KEYWORD} const srcCore = (config?: UserConfig): UserConfig =>
+	mergeConfig(
+		{
+			resolve,
+			build: {
+				emptyOutDir: true,
+				sourcemap: true,
+				minify: false,
+			},
+			test: {
+				name: { label: 'src:core', color: 'magenta' },
+				include: ['tests/src/core/**/*.test.ts'],
+				setupFiles: ['./tests/setup.ts'],
+				environment: 'node',
+				browser: { enabled: false },
+			},
+		},
+		config ?? {},
+	)
+
+${EXPORT_KEYWORD} const guides = (config?: UserConfig): UserConfig =>
+	srcCore(
+		mergeConfig(
+			{
+				test: {
+					name: { label: 'guides', color: 'green' },
+					include: ['tests/guides/**/*.test.ts'],
+					exclude: ['tests/src/**/*.test.ts', 'tests/setup.test.ts'],
+				},
+			},
+			config ?? {},
+		),
+	)
+${nonCore.map((surface) => surface === "browser" ? browserBlock : serverBlock).join("")}
+export default defineConfig({
+	resolve,
+	test: {
+		projects: [${[
+		...hasCore ? ["srcCore"] : [],
+		...nonCore.map((surface) => `src${pascalCase(surface)}`),
+		"guides"
+	].join(", ")}],
+	},
+})
+`;
+}
+/**
+* `configs/src/tsconfig.core.json` — unchanged core shape.
+*
+* @returns The core surface `tsconfig` file content, newline-terminated.
+*
+* @example
+* ```ts
+* coreTsconfig().includes('"rootDir": "../../src/core"') // true
+* ```
+*/
+function coreTsconfig() {
+	return `${JSON.stringify({
+		extends: "../../tsconfig.json",
+		compilerOptions: {
+			lib: ["ESNext"],
+			noEmit: false,
+			declaration: true,
+			emitDeclarationOnly: true,
+			rootDir: "../../src/core",
+			outDir: "../../dist/src/core"
+		},
+		include: ["../../src/core/**/*.ts"]
+	}, void 0, "	")}\n`;
+}
+/**
+* `configs/src/vite.core.config.ts` — inlines its own `build.lib` /
+* `rollupOptions` (core's `srcCore` root export carries no build.lib).
+*
+* @returns The core surface `vite.config.ts` file content, newline-terminated.
+*
+* @example
+* ```ts
+* coreViteConfig().includes('srcCore(') // true
+* ```
+*/
+function coreViteConfig() {
+	return `import { defineConfig } from 'vite'
+import dts from 'vite-plugin-dts'
+import { srcCore, resolveWorkspacePath } from '../../vite.config'
+
+export default defineConfig(
+	srcCore({
+		plugins: [
+			dts({
+				tsconfigPath: resolveWorkspacePath('configs/src/tsconfig.core.json'),
+				bundleTypes: true,
+			}),
+		],
+		build: {
+			lib: {
+				entry: resolveWorkspacePath('src/core/index.ts'),
+				formats: ['es', 'cjs'],
+				fileName: (format) => (format === 'es' ? 'index.js' : 'index.cjs'),
+			},
+			outDir: 'dist/src/core',
+			rollupOptions: {
+				external: [/^node:/, /^@orkestrel\\//],
+			},
+		},
+	}),
+)
+`;
+}
+/**
+* `configs/src/tsconfig.<browser|server>.json` — `rootDir`/`outDir` point at
+* the whole `src`/`dist/src` tree (not a per-surface subfolder), per the live
+* middleware/router exemplars.
+*
+* @param surface - The non-`core` surface to derive the `tsconfig` for.
+* @returns The surface `tsconfig` file content, newline-terminated.
+*
+* @example
+* ```ts
+* surfaceTsconfig('server').includes('"rootDir": "../../src"') // true
+* ```
+*/
+function surfaceTsconfig(surface) {
+	const config = {
+		extends: "../../tsconfig.json",
+		compilerOptions: {
+			lib: surface === "browser" ? [
+				"ESNext",
+				"DOM",
+				"DOM.Iterable"
+			] : ["ESNext"],
+			types: surface === "browser" ? ["vite/client"] : ["node"],
+			noEmit: false,
+			declaration: true,
+			emitDeclarationOnly: true,
+			rootDir: "../../src",
+			outDir: "../../dist/src"
+		},
+		include: [`../../src/${surface}/**/*.ts`]
+	};
+	return `${JSON.stringify(config, void 0, "	")}\n`;
+}
+/**
+* `configs/src/vite.<browser|server>.config.ts` — a thin `dts`-only wrapper;
+* `build.lib` / externals live in the root `srcBrowser` / `srcServer` export
+* instead (per the live exemplars).
+*
+* @param surface - The non-`core` surface to derive the `vite.config.ts` for.
+* @returns The surface `vite.config.ts` file content, newline-terminated.
+*
+* @example
+* ```ts
+* surfaceViteConfig('browser').includes('srcBrowser') // true
+* ```
+*/
+function surfaceViteConfig(surface) {
+	const anchor = surface === "browser" ? "srcBrowser" : "srcServer";
+	return `import { defineConfig } from 'vite'
+import dts from 'vite-plugin-dts'
+import { ${anchor}, resolveWorkspacePath } from '../../vite.config'
+
+// Types are bundled inline by vite-plugin-dts (see configs/src/vite.core.config.ts
+// for the same pattern).
+export default defineConfig(
+	${anchor}({
+		plugins: [
+			dts({
+				tsconfigPath: resolveWorkspacePath('configs/src/tsconfig.${surface}.json'),
+				bundleTypes: true,
+			}),
+		],
+	}),
+)
+`;
+}
+/**
+* Draft the `configs` group's `computed` artifacts — the root
+* `tsconfig.json` / `vite.config.ts` plus each declared surface's
+* `configs/src/*` pair, grounded against the live middleware (core+server)
+* and router (core+browser+server) exemplars.
+*
+* @param spec - The `Blueprint` to derive config artifacts from.
+* @returns The `configs` group's `Artifact[]`.
+*
+* @example
+* ```ts
+* configArtifacts(blueprint('router')).length // 4
+* ```
+*/
+function configArtifacts(spec) {
+	const artifacts = [{
+		path: "tsconfig.json",
+		group: "configs",
+		origin: "computed",
+		content: rootTsconfig(spec.surfaces)
+	}, {
+		path: "vite.config.ts",
+		group: "configs",
+		origin: "computed",
+		content: rootViteConfig(spec.surfaces)
+	}];
+	for (const surface of spec.surfaces) {
+		const row = SURFACE_MATRIX[surface];
+		for (const path of row.configs) {
+			const isTsconfig = path.endsWith(".json");
+			const content = surface === "core" ? isTsconfig ? coreTsconfig() : coreViteConfig() : isTsconfig ? surfaceTsconfig(surface) : surfaceViteConfig(surface);
+			artifacts.push({
+				path,
+				group: "configs",
+				origin: "computed",
+				surface,
+				content
+			});
+		}
+	}
+	return artifacts;
+}
+/**
+* Draft the `source` group's `template` artifacts — the generated-minimal
+* `src/<surface>/*` stubs, one full {types, <Pascal>, factories, index} set
+* PER declared surface (never assuming `core`), filled from `TEMPLATES` with
+* `missing: 'error'`. `blueprintToMembers` already declares a full entity +
+* factory per surface (AGENTS §5's per-surface centralized-file pattern), so
+* every surface gets the same uniform stub shape.
+*
+* @param spec - The `Blueprint` to derive source stubs from.
+* @param pascal - The package's PascalCase entity name.
+* @returns The `source` group's `Artifact[]`.
+*
+* @example
+* ```ts
+* sourceArtifacts(blueprint('router'), 'Router').length // 4
+* ```
+*/
+function sourceArtifacts(spec, pascal) {
+	const values = { pascal };
+	const artifacts = [];
+	for (const surface of spec.surfaces) artifacts.push(fillArtifact(`src/${surface}/types.ts`, "source", "types", values, surface), fillArtifact(`src/${surface}/${pascal}.ts`, "source", "entity", values, surface), fillArtifact(`src/${surface}/factories.ts`, "source", "factories", values, surface), fillArtifact(`src/${surface}/index.ts`, "source", "index", values, surface));
+	return artifacts;
+}
+/**
+* Build the computed `SELF_SPECIFIERS` / `SPECIFIER_MODULES` / `exportsFor`
+* block the `parityTest` template's `{{specifiers}}` placeholder fills —
+* ONE shape for every surface count (grounded against the live single-surface
+* websocket/indexeddb and multi-surface router/middleware exemplars, which
+* both resolve a fence's specifier through a `SPECIFIER_MODULES` map rather
+* than a single-module lookup). The bare `@orkestrel/<name>` specifier
+* resolves to the PRIMARY surface — `core` when declared, else the sole
+* declared surface.
+*
+* @param spec - The `Blueprint` to derive the parity specifiers block from.
+* @returns The computed `parityTest` `{{specifiers}}` block content.
+*
+* @example
+* ```ts
+* paritySpecifiers(blueprint('router')).includes('SELF_SPECIFIERS') // true
+* ```
+*/
+function paritySpecifiers(spec) {
+	const CONST_KEYWORD = "const";
+	const FUNCTION_KEYWORD = "function";
+	const primary = spec.surfaces.includes("core") ? "core" : spec.surfaces[0] ?? "core";
+	const packageSpecifier = `@orkestrel/${spec.name}`;
+	const selfSpecifiers = [packageSpecifier, ...spec.surfaces.map((surface) => `@src/${surface}`)];
+	const modules = { [packageSpecifier]: `src/${primary}` };
+	for (const surface of spec.surfaces) modules[`@src/${surface}`] = `src/${surface}`;
+	return `const SELF_SPECIFIERS = [${selfSpecifiers.map((specifier) => `'${specifier}'`).join(", ")}]
+
+${CONST_KEYWORD} SPECIFIER_MODULES: Readonly<Record<string, string>> = {
+${Object.entries(modules).map(([specifier, module]) => `\t'${specifier}': '${module}',`).join("\n")}
+}
+${CONST_KEYWORD} specifierSources = new Map<string, ReturnType<typeof createSource>>()
+${FUNCTION_KEYWORD} exportsFor(specifier: string): readonly string[] {
+	const module = SPECIFIER_MODULES[specifier]
+	if (module === undefined) return []
+	let source = specifierSources.get(module)
+	if (source === undefined) {
+		source = createSource({ files, module })
+		specifierSources.set(module, source)
+	}
+	return source.exports().map((symbol) => symbol.name)
+}`;
+}
+/**
+* Draft the `tests` group's `template` artifacts — the shared recorder
+* setup, one environment-specific setup file per non-`core` surface
+* (`setupServer.ts` / `setupBrowser.ts`, grounded against the live
+* exemplars' setup-file naming), the generated-minimal entity / factory test
+* stubs PER declared surface, and the surface-aware guides-parity drop-in.
+*
+* @param spec - The `Blueprint` to derive test stubs from.
+* @param pascal - The package's PascalCase entity name.
+* @returns The `tests` group's `Artifact[]`.
+*
+* @example
+* ```ts
+* testArtifacts(blueprint('router'), 'Router').length // 3
+* ```
+*/
+function testArtifacts(spec, pascal) {
+	const artifacts = [fillArtifact("tests/setup.ts", "tests", "setup", {})];
+	if (spec.surfaces.includes("server")) artifacts.push(fillArtifact("tests/setupServer.ts", "tests", "setupServer", {}, "server"));
+	if (spec.surfaces.includes("browser")) artifacts.push(fillArtifact("tests/setupBrowser.ts", "tests", "setupBrowser", {}, "browser"));
+	for (const surface of spec.surfaces) {
+		const values = {
+			pascal,
+			surface
+		};
+		artifacts.push(fillArtifact(`tests/src/${surface}/${pascal}.test.ts`, "tests", "entityTest", values, surface), fillArtifact(`tests/src/${surface}/factories.test.ts`, "tests", "factoriesTest", values, surface));
+	}
+	artifacts.push(fillArtifact("tests/guides/src/parity.test.ts", "tests", "parityTest", {
+		name: spec.name,
+		specifiers: paritySpecifiers(spec)
+	}));
+	return artifacts;
+}
+/**
+* Build an `alignTable` markdown table over a member category's rows, deduped
+* by name — `blueprintToMembers` declares one full member set PER surface, so
+* a multi-surface blueprint carries byte-identical name/summary rows once per
+* surface; the one guide (AGENTS §22) lists each declared member once,
+* grouped across its surfaces.
+*
+* @param category - The `Member['category']` to filter rows by.
+* @param members - The blueprint's derived `Member[]` (previously closed over by the caller).
+* @returns The aligned markdown table for the category's deduped members.
+*
+* @example
+* ```ts
+* guideMemberTable('entity', blueprintToMembers(blueprint('router'))).includes('Router') // true
+* ```
+*/
+function guideMemberTable(category, members) {
+	const seen = /* @__PURE__ */ new Set();
+	const rows = [];
+	for (const item of members) {
+		if (item.category !== category) continue;
+		if (seen.has(item.name)) continue;
+		seen.add(item.name);
+		rows.push([`\`${item.name}\``, item.summary]);
+	}
+	return alignTable(["API", "Summary"], rows);
+}
+/**
+* Draft the `guides` group's artifacts — the package's own filled guide stub,
+* the guides index, and any vendored dependency guide mirrors.
+*
+* @param spec - The `Blueprint` to derive guide artifacts from.
+* @param pascal - The package's PascalCase entity name.
+* @param members - The blueprint's derived `Member[]`.
+* @returns The `guides` group's `Artifact[]`.
+*
+* @example
+* ```ts
+* guideArtifacts(blueprint('router'), 'Router', blueprintToMembers(blueprint('router'))).length // 2
+* ```
+*/
+function guideArtifacts(spec, pascal, members) {
+	const vendoredGuides = [
+		"@orkestrel/contract",
+		"@orkestrel/emitter",
+		"@orkestrel/markdown",
+		"@orkestrel/template",
+		"@orkestrel/terminal",
+		"@orkestrel/console",
+		"@orkestrel/guide"
+	];
+	const primary = spec.surfaces.includes("core") ? "core" : spec.surfaces[0] ?? "core";
+	const source = spec.surfaces.map((surface) => `[\`src/${surface}\`](../../src/${surface})`).join(", ");
+	const barrel = spec.surfaces.length === 1 ? `Surfaced through the \`@src/${primary}\` barrel.` : `Surfaced through the \`@orkestrel/${spec.name}\` barrel (aliased ${spec.surfaces.map((surface) => `\`@src/${surface}\``).join(" / ")} inside this repo).`;
+	const tests = spec.surfaces.map((surface) => `- [\`tests/src/${surface}/${pascal}.test.ts\`](../../tests/src/${surface}/${pascal}.test.ts) —\n  id assignment (explicit / generated) and independence across instances.\n- [\`tests/src/${surface}/factories.test.ts\`](../../tests/src/${surface}/factories.test.ts) —\n  \`create${pascal}\` returns a working \`${pascal}Interface\` backed by a real \`${pascal}\`.`).join("\n");
+	const artifacts = [fillArtifact(`guides/src/${spec.name}.md`, "guides", "guide", {
+		name: spec.name,
+		pascal,
+		primary,
+		source,
+		barrel,
+		tests,
+		factories: guideMemberTable("factory", members),
+		entities: guideMemberTable("entity", members),
+		types: guideMemberTable("type", members)
+	}), fillArtifact("guides/README.md", "guides", "guidesReadme", {
+		concept: alignTable([
+			"Concept",
+			"Spec",
+			"Source",
+			"Tests"
+		], [[
+			pascal,
+			`[\`${spec.name}.md\`](src/${spec.name}.md)`,
+			spec.surfaces.map((surface) => `[\`src/${surface}\`](../src/${surface})`).join(", "),
+			spec.surfaces.map((surface) => `[\`tests/src/${surface}\`](../tests/src/${surface})`).join(", ")
+		]]),
+		directory: alignTable(["Directory", "Guide"], spec.surfaces.map((surface) => [`src/${surface}`, `[\`${spec.name}.md\`](src/${spec.name}.md)`]))
+	})];
+	for (const dep of spec.dependencies) {
+		if (!vendoredGuides.includes(dep.name)) continue;
+		const short = dep.name.replace("@orkestrel/", "");
+		artifacts.push({
+			path: `guides/src/${short}.md`,
+			group: "guides",
+			origin: "host",
+			source: `guides/src/${short}.md`
+		});
+	}
+	return artifacts;
+}
+/**
+* Apply a blueprint's `overrides` over a drafted artifact list — an override
+* REPLACES the matching artifact's `content` in place; an override matching
+* no planned artifact, or targeting a `host`-origin path, is left unapplied
+* here (the gate stage surfaces it as a blocking question — this leaf only
+* performs the replacement half of the rule).
+*
+* @param artifacts - The drafted `Artifact[]`.
+* @param overrides - The blueprint's `overrides`.
+* @returns The artifact list with matching overrides applied.
+*
+* @example
+* ```ts
+* applyOverrides(artifacts, [override('README.md', '# custom')])[0].content // '# custom'
+* ```
+*/
+function applyOverrides(artifacts, overrides) {
+	if (overrides.length === 0) return artifacts;
+	const byPath = new Map(overrides.map((override) => [override.path, override.content]));
+	return artifacts.map((artifact) => {
+		if (artifact.origin === "host") return artifact;
+		const content = byPath.get(artifact.path);
+		return content === void 0 ? artifact : {
+			...artifact,
+			content
+		};
+	});
+}
+/**
+* The full pure compilation: draft a blueprint's artifacts — the manifest and
+* exports combination rules over the per-surface `SURFACE_MATRIX` rows, plus
+* `HOST_PATHS` and `overrides` — then pin.
+*
+* @param blueprint - The `Blueprint` to compile.
+* @param groups - An optional `Group[]` selection (default: all groups).
+* @returns The drafted, pinned `Plan`.
+*
+* @example
+* ```ts
+* const plan = blueprintToPlan(blueprint('router', { surfaces: ['core'] }))
+* plan.artifacts.length // every file the package needs
+* ```
+*/
+function blueprintToPlan(blueprint, groups) {
+	const selected = groups && groups.length > 0 ? groups : GROUPS;
+	const pascal = pascalCase(blueprint.name);
+	const members = blueprintToMembers(blueprint);
+	const artifacts = [];
+	if (selected.includes("manifest")) artifacts.push({
+		path: "package.json",
+		group: "manifest",
+		origin: "computed",
+		content: packageManifest(blueprint)
+	});
+	if (selected.includes("configs")) artifacts.push(...configArtifacts(blueprint));
+	if (selected.includes("source")) artifacts.push(...sourceArtifacts(blueprint, pascal));
+	if (selected.includes("tests")) artifacts.push(...testArtifacts(blueprint, pascal));
+	if (selected.includes("guides")) artifacts.push(...guideArtifacts(blueprint, pascal, members));
+	if (selected.includes("docs")) artifacts.push(fillArtifact("README.md", "docs", "readme", {
+		name: blueprint.name,
+		pascal
+	}));
+	for (const path of HOST_PATHS) {
+		const group = hostGroup(path);
+		if (!selected.includes(group)) continue;
+		artifacts.push({
+			path,
+			group,
+			origin: "host",
+			source: path
+		});
+	}
+	return pinPlan({
+		blueprint,
+		groups: [...selected],
+		artifacts: applyOverrides(artifacts, blueprint.overrides)
+	});
+}
+//#endregion
+//#region src/core/Compiler.ts
+/**
+* The compilation orchestrator — runs the fixed three-stage `[draft, gate,
+* pin]` pipeline over a `Blueprint` and the pure `audit` projection, owning a
+* typed `emitter` (AGENTS §13).
+*
+* @remarks
+* `compile` and `audit` are genuinely synchronous and pure; the gate fails
+* CLOSED — a blueprint failing `validateBlueprint`, or carrying an override
+* that matches no planned artifact or targets a `host`-origin path, yields a
+* visible incomplete `Scaffolding` (`plan` absent, `questions` populated)
+* rather than throwing. A dependency outside the vendored guide set surfaces
+* a non-blocking `Question` and a `host`-origin pointer artifact instead of a
+* fabricated mirror. `compile` emits `compile` only for a complete
+* compilation and `block` for a gated one; `audit` emits `block` (when gated)
+* then `audit`, never `compile`. After `destroy()` every method but the
+* getter and `destroy` itself throws `ScaffoldError('DESTROYED', …)`.
+*
+* @example
+* ```ts
+* import { blueprint, Compiler } from '@src/core'
+*
+* const compiler = new Compiler()
+* const scaffolding = compiler.compile(blueprint('router', { surfaces: ['core'] }))
+* scaffolding.complete // true
+* compiler.destroy()
+* ```
+*/
+var Compiler = class Compiler {
+	static #vendored = Object.freeze([
+		"@orkestrel/contract",
+		"@orkestrel/emitter",
+		"@orkestrel/markdown",
+		"@orkestrel/template",
+		"@orkestrel/terminal",
+		"@orkestrel/console",
+		"@orkestrel/guide"
+	]);
+	#emitter;
+	#destroyed = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	/**
+	* Run the three-stage pipeline over a `Blueprint`, returning a complete or
+	* visible-incomplete `Scaffolding`.
+	*
+	* @param blueprint - The `Blueprint` to compile.
+	* @param groups - Optional `Group` selection scoping the plan to those
+	* artifact groups; absent means the full plan.
+	* @returns The `Scaffolding` outcome of this compile.
+	*
+	* @example
+	* ```ts
+	* const scaffolding = compiler.compile(blueprint('timeout', { surfaces: ['core'] }))
+	* scaffolding.stages.map((record) => record.stage) // ['draft', 'gate', 'pin']
+	* ```
+	*/
+	compile(blueprint, groups) {
+		this.#assertAlive();
+		const scaffolding = this.#run(blueprint, groups);
+		if (scaffolding.complete) this.#emitter.emit("compile", scaffolding);
+		else this.#emitter.emit("block", scaffolding.questions);
+		return scaffolding;
+	}
+	/**
+	* Compile the blueprint, then diff the resulting plan against the
+	* caller-supplied current target content.
+	*
+	* @param blueprint - The `Blueprint` to compile and audit.
+	* @param current - The target's current content, keyed by artifact path.
+	* @param groups - Optional `Group` selection scoping the audit to those
+	* artifact groups; absent means the full plan.
+	* @returns The `Audit` outcome — a gated blueprint returns `complete: false`
+	* with the gate's blocking `questions` and zero findings.
+	*
+	* @example
+	* ```ts
+	* const audit = compiler.audit(blueprint('timeout', { surfaces: ['core'] }), {})
+	* audit.missing // every artifact — nothing exists at the target yet
+	* ```
+	*/
+	audit(blueprint, current, groups) {
+		this.#assertAlive();
+		const scaffolding = this.#run(blueprint, groups);
+		if (!scaffolding.complete || scaffolding.plan === void 0) {
+			this.#emitter.emit("block", scaffolding.questions);
+			const result = {
+				findings: [],
+				clean: false,
+				complete: false,
+				questions: scaffolding.questions,
+				drifted: 0,
+				missing: 0,
+				foreign: 0
+			};
+			this.#emitter.emit("audit", result);
+			return result;
+		}
+		const result = diffPlan(scaffolding.plan, current);
+		this.#emitter.emit("audit", result);
+		return result;
+	}
+	/** Idempotent teardown — emits `destroy`, then destroys the emitter LAST. */
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#run(blueprint, groups) {
+		const stages = [];
+		const failures = [];
+		let draft;
+		try {
+			draft = blueprintToPlan(blueprint, groups);
+			stages.push({
+				stage: "draft",
+				input: blueprint,
+				output: draft,
+				failed: false
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			stages.push({
+				stage: "draft",
+				input: blueprint,
+				output: void 0,
+				failed: true,
+				error: message
+			});
+			failures.push({
+				stage: "draft",
+				code: "INVALID",
+				message
+			});
+			this.#emitter.emit("error", error);
+			stages.push({
+				stage: "gate",
+				input: void 0,
+				output: void 0,
+				failed: true,
+				error: "Skipped: draft failed"
+			});
+			stages.push({
+				stage: "pin",
+				input: void 0,
+				output: void 0,
+				failed: true,
+				error: "Skipped: draft failed"
+			});
+			return {
+				blueprint,
+				questions: [],
+				stages,
+				failures,
+				complete: false,
+				digest: ""
+			};
+		}
+		const validation = validateBlueprint(blueprint);
+		const overrideQuestions = this.#overrideQuestions(blueprint, draft.artifacts);
+		const dependencyQuestions = this.#dependencyQuestions(blueprint);
+		const blocking = [...validation.questions, ...overrideQuestions];
+		const questions = [...blocking, ...dependencyQuestions];
+		stages.push({
+			stage: "gate",
+			input: draft,
+			output: {
+				blocking: blocking.length,
+				questions
+			},
+			failed: blocking.length > 0
+		});
+		if (blocking.length > 0) {
+			const message = `${blocking.length} blocking question${blocking.length === 1 ? "" : "s"}`;
+			failures.push({
+				stage: "gate",
+				code: "BLOCKED",
+				message
+			});
+			stages.push({
+				stage: "pin",
+				input: void 0,
+				output: void 0,
+				failed: true,
+				error: "Skipped: gate blocked"
+			});
+			return {
+				blueprint,
+				questions,
+				stages,
+				failures,
+				complete: false,
+				digest: ""
+			};
+		}
+		try {
+			const pointers = this.#pointerArtifacts(blueprint);
+			const plan = pinPlan({
+				...draft,
+				artifacts: [...draft.artifacts, ...pointers]
+			});
+			stages.push({
+				stage: "pin",
+				input: draft,
+				output: plan,
+				failed: false
+			});
+			return {
+				blueprint,
+				plan,
+				questions,
+				stages,
+				failures,
+				complete: true,
+				digest: plan.hash ?? ""
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			stages.push({
+				stage: "pin",
+				input: draft,
+				output: void 0,
+				failed: true,
+				error: message
+			});
+			failures.push({
+				stage: "pin",
+				code: "INVALID",
+				message
+			});
+			this.#emitter.emit("error", error);
+			return {
+				blueprint,
+				questions,
+				stages,
+				failures,
+				complete: false,
+				digest: ""
+			};
+		}
+	}
+	#overrideQuestions(blueprint, artifacts) {
+		const byPath = new Map(artifacts.map((artifact) => [artifact.path, artifact]));
+		const questions = [];
+		for (const item of blueprint.overrides) {
+			const artifact = byPath.get(item.path);
+			if (artifact === void 0) {
+				questions.push({
+					field: "overrides",
+					text: `Override path "${item.path}" matches no planned artifact`,
+					blocking: true
+				});
+				continue;
+			}
+			if (artifact.origin === "host") questions.push({
+				field: "overrides",
+				text: `Override path "${item.path}" targets a host-origin artifact`,
+				blocking: true
+			});
+		}
+		return questions;
+	}
+	#dependencyQuestions(blueprint) {
+		const questions = [];
+		for (const item of blueprint.dependencies) {
+			if (Compiler.#vendored.includes(item.name)) continue;
+			questions.push({
+				field: "dependencies",
+				text: `Dependency "${item.name}" is not vendored — sync its guides/src mirror from that repo at HEAD`,
+				blocking: false
+			});
+		}
+		return questions;
+	}
+	#pointerArtifacts(blueprint) {
+		const artifacts = [];
+		for (const item of blueprint.dependencies) {
+			if (Compiler.#vendored.includes(item.name)) continue;
+			const path = `guides/src/${item.name.replace("@orkestrel/", "")}.md`;
+			artifacts.push({
+				path,
+				group: "guides",
+				origin: "host",
+				source: path
+			});
+		}
+		return artifacts;
+	}
+	#assertAlive() {
+		if (this.#destroyed) throw new ScaffoldError("DESTROYED", "Compiler has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/PlanManager.ts
+/**
+* The self-owning, versioned/hashed plan registry (AGENTS §9).
+*
+* @remarks
+* `add` re-pins the plan and mints the record's `id` from its own content
+* `hash` — deterministic, no randomness. Re-adding a plan whose content is
+* unchanged resolves to the SAME id and returns the existing record
+* untouched (`version` stays put); a plan whose content differs mints a
+* fresh id at `version: 1`. The array overload of `remove` is declared FIRST
+* (AGENTS §9.2) so an id list resolves to the batch form; the batch form is
+* ALL-OR-NOTHING. After `destroy()` every method but the getters and
+* `destroy` itself throws `ScaffoldError('DESTROYED', …)`.
+*
+* @example
+* ```ts
+* import { blueprint, blueprintToPlan, PlanManager } from '@src/core'
+*
+* const plans = new PlanManager()
+* const record = plans.add(blueprintToPlan(blueprint('budget', { surfaces: ['core'] })))
+* record.id === record.hash // true — id minted from content
+* plans.destroy()
+* ```
+*/
+var PlanManager = class {
+	#plans = /* @__PURE__ */ new Map();
+	#emitter;
+	#destroyed = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		for (const plan of options?.plans ?? []) {
+			const record = this.#pin(plan);
+			this.#plans.set(record.id, record);
+		}
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get size() {
+		return this.#plans.size;
+	}
+	/**
+	* Whether a plan with the given id is registered.
+	*
+	* @param id - The plan record id.
+	* @returns `true` when `id` is registered.
+	*/
+	has(id) {
+		this.#assertAlive();
+		return this.#plans.has(id);
+	}
+	/**
+	* Look up one registered plan record by id (AGENTS §9.1 singular accessor).
+	*
+	* @param id - The plan record id.
+	* @returns The `PlanRecord`, or `undefined` when unregistered.
+	*/
+	plan(id) {
+		this.#assertAlive();
+		return this.#plans.get(id);
+	}
+	/**
+	* List every registered plan record (AGENTS §9.1 plural accessor).
+	*
+	* @returns A snapshot array of every registered `PlanRecord`.
+	*/
+	plans() {
+		this.#assertAlive();
+		return [...this.#plans.values()];
+	}
+	/**
+	* Register (or re-register) one plan, mints the record's id from its
+	* content hash.
+	*
+	* @param plan - The `Plan` to register.
+	* @returns The registered `PlanRecord`.
+	*
+	* @example
+	* ```ts
+	* const record = plans.add(blueprintToPlan(blueprint('budget', { surfaces: ['core'] })))
+	* record.version // 1
+	* ```
+	*/
+	add(plan) {
+		this.#assertAlive();
+		const record = this.#pin(plan);
+		const final = this.#plans.get(record.id) ?? record;
+		this.#plans.set(final.id, final);
+		this.#emitter.emit("add", final.id);
+		return final;
+	}
+	remove(target) {
+		this.#assertAlive();
+		if (target === void 0) {
+			for (const id of this.#plans.keys()) this.#emitter.emit("remove", id);
+			this.#plans.clear();
+			return;
+		}
+		if (typeof target === "string") {
+			if (!this.#plans.has(target)) return false;
+			this.#plans.delete(target);
+			this.#emitter.emit("remove", target);
+			return true;
+		}
+		for (const id of target) if (!this.#plans.has(id)) return false;
+		for (const id of target) {
+			this.#plans.delete(id);
+			this.#emitter.emit("remove", id);
+		}
+		return true;
+	}
+	/** Idempotent teardown — clears the collection, emits `destroy`, then destroys the emitter LAST. */
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#plans.clear();
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#pin(plan) {
+		const pinned = pinPlan(plan);
+		const hash = pinned.hash ?? "";
+		return {
+			id: hash,
+			plan: pinned,
+			version: 1,
+			hash
+		};
+	}
+	#assertAlive() {
+		if (this.#destroyed) throw new ScaffoldError("DESTROYED", "PlanManager has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create a `CompilerInterface` — the compilation orchestrator.
+*
+* @param options - `CompilerOptions` — `on` initial event listeners, `error` the listener-error handler.
+* @returns A fresh `Compiler`.
+*
+* @example
+* ```ts
+* import { createCompiler } from '@src/core'
+*
+* const compiler = createCompiler()
+* compiler.destroy()
+* ```
+*/
+function createCompiler(options) {
+	return new Compiler(options);
+}
+/**
+* Create a working `PlanManagerInterface`.
+*
+* @param options - `PlanManagerOptions` — `plans` to seed the registry, `on` / `error` for the emitter.
+* @returns A fresh `PlanManager`.
+*
+* @example
+* ```ts
+* import { createPlanManager } from '@src/core'
+*
+* const plans = createPlanManager()
+* plans.size // 0
+* plans.destroy()
+* ```
+*/
+function createPlanManager(options) {
+	return new PlanManager(options);
+}
+/**
+* Validate and return a `Blueprint` from plain data.
+*
+* @param data - A `name` plus a partial of the remaining `Blueprint` fields.
+* @remarks
+* Fills the builder defaults, then checks BOTH the exact-record shape
+* (`isBlueprint`) and the semantic pass (`validateBlueprint`) — so an
+* off-`NAME_PATTERN` name throws here too.
+* @returns The validated `Blueprint`.
+* @throws {@link ScaffoldError} coded `INVALID` when the structure or the
+* semantic pass fails.
+*
+* @example
+* ```ts
+* import { createBlueprint } from '@src/core'
+*
+* createBlueprint({ name: 'Router', surfaces: [] }) // throws ScaffoldError('INVALID', …)
+* ```
+*/
+function createBlueprint(data) {
+	const candidate = blueprint(data.name, data);
+	if (!isBlueprint(candidate)) throw new ScaffoldError("INVALID", "Blueprint failed the exact-record contract", { name: data.name });
+	const validation = validateBlueprint(candidate);
+	if (!validation.valid) throw new ScaffoldError("INVALID", "Blueprint failed validation", { questions: validation.questions });
+	return candidate;
+}
+//#endregion
+export { CATEGORIES, COMPILER_ID, COMPILE_STAGES, Compiler, DEFAULT_ENGINES, DEFAULT_VERSION, DEPENDENCY_NAME_PATTERN, EXTRA_NAME_PATTERN, FRESHNESS, GROUPS, HOST_PATHS, NAME_PATTERN, ORIGINS, PlanManager, SCAFFOLD_RANGE, SURFACES, SURFACE_MATRIX, ScaffoldError, TEMPLATES, alignTable, applyOverrides, artifactShape, auditToReview, blueprint, blueprintShape, blueprintToMembers, blueprintToPlan, catalogNames, catalogToBlock, compareCodeUnit, computeHash, configArtifacts, coreTsconfig, coreViteConfig, createBlueprint, createCompiler, createPlanManager, delimiterCell, dependency, dependencyShape, devDependenciesFor, diffPlan, dualCondition, entryFields, exportsMap, fillArtifact, guideArtifacts, guideMemberTable, hostGroup, inferGroup, isArtifact, isBehind, isBlueprint, isDependency, isMember, isOverride, isPlan, isRecord, isScaffoldError, isSyncReport, manifestToDependencies, member, memberShape, override, overrideShape, packageManifest, padCell, paritySpecifiers, parseBlueprint, parsePlan, parseSyncReport, pascalCase, pinPlan, planShape, planToReview, planToSummary, rangeToFreshness, rootTsconfig, rootViteConfig, singleSurfaceViteConfig, sourceArtifacts, splitTableRow, stableStringify, surfaceTsconfig, surfaceVariant, surfaceViteConfig, syncReportShape, syncToReview, testArtifacts, validateBlueprint, validateDependencyArray, viteHeader };
+
+//# sourceMappingURL=index.js.map