@orkestrel/scaffold 0.0.1

package/dist/src/core/index.d.ts

@@ -0,0 +1,1941 @@
+import { ArrayShape } from '@orkestrel/contract';
+import { BooleanShape } from '@orkestrel/contract';
+import { ContractShape } from '@orkestrel/contract';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { Guard } from '@orkestrel/contract';
+import { LiteralShape } from '@orkestrel/contract';
+import { NumberShape } from '@orkestrel/contract';
+import { ObjectShape } from '@orkestrel/contract';
+import { OptionalShape } from '@orkestrel/contract';
+import { StringShape } from '@orkestrel/contract';
+import { TableAlign } from '@orkestrel/markdown';
+import { TemplateDefinition } from '@orkestrel/template';
+
+/**
+ * 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 |'
+ * ```
+ */
+export declare function alignTable(header: readonly string[], rows: readonly (readonly string[])[], align?: readonly TableAlign[]): string;
+
+/**
+ * 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'
+ * ```
+ */
+export declare function applyOverrides(artifacts: readonly Artifact[], overrides: Blueprint['overrides']): readonly Artifact[];
+
+/**
+ * One file in a `Plan`.
+ *
+ * @remarks
+ * `content` present for `template` / `computed`, `source` (a host-relative
+ * path) for `host`.
+ */
+export declare interface Artifact {
+    readonly path: string;
+    readonly group: Group;
+    readonly origin: Origin;
+    readonly surface?: Surface;
+    readonly content?: string;
+    readonly source?: string;
+}
+
+/**
+ * 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.
+ */
+export declare function artifactShape(): ObjectShape<{
+    path: StringShape;
+    group: LiteralShape<readonly ["manifest", "configs", "source", "tests", "guides", "docs", "orchestration"]>;
+    origin: LiteralShape<readonly ["host", "template", "computed"]>;
+    surface: OptionalShape<LiteralShape<readonly ["core", "browser", "server"]>>;
+    content: OptionalShape<StringShape>;
+    source: OptionalShape<StringShape>;
+}, false>;
+
+/**
+ * The whole diff of a plan against a target's current content.
+ *
+ * @remarks
+ * A `Compiler.audit` over a gate-failing blueprint sets `complete: false` with
+ * the gate's `questions` and zero findings, while `diffPlan` over an existing
+ * plan is always `complete: true`.
+ */
+export declare interface Audit {
+    readonly findings: readonly Finding[];
+    readonly clean: boolean;
+    readonly complete: boolean;
+    readonly questions: readonly Question[];
+    readonly drifted: number;
+    readonly missing: number;
+    readonly foreign: number;
+}
+
+/**
+ * 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…'
+ * ```
+ */
+export declare function auditToReview(audit: Audit): string;
+
+/** The closed, JSON-serializable package spec. */
+export declare interface Blueprint {
+    readonly name: string;
+    readonly description?: string;
+    readonly keywords: readonly string[];
+    readonly surfaces: readonly Surface[];
+    readonly dependencies: readonly Dependency[];
+    /** Runtime `@orkestrel/*` peers, emitted as `peerDependencies` — a peer flagged `optional` also gets a `peerDependenciesMeta` entry. */
+    readonly peers: readonly Dependency[];
+    /** Package-specific `devDependencies` merged into the generated uniform baseline — the middleware pattern of shipping `@orkestrel/{database,router,server}` for its tests. */
+    readonly extras: readonly Dependency[];
+    readonly version: string;
+    readonly engines: string;
+    readonly overrides: readonly Override[];
+}
+
+/**
+ * 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'
+ * ```
+ */
+export declare function blueprint(name: string, options?: Partial<Omit<Blueprint, 'name'>>): Blueprint;
+
+/**
+ * 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.
+ */
+export declare function blueprintShape(): ObjectShape<{
+    name: StringShape;
+    description: OptionalShape<StringShape>;
+    keywords: ArrayShape<StringShape>;
+    surfaces: ArrayShape<LiteralShape<readonly ["core", "browser", "server"]>>;
+    dependencies: ArrayShape<ObjectShape<{
+        name: StringShape;
+        range: StringShape;
+        optional: OptionalShape<BooleanShape>;
+    }, false>>;
+    peers: ArrayShape<ObjectShape<{
+        name: StringShape;
+        range: StringShape;
+        optional: OptionalShape<BooleanShape>;
+    }, false>>;
+    extras: ArrayShape<ObjectShape<{
+        name: StringShape;
+        range: StringShape;
+        optional: OptionalShape<BooleanShape>;
+    }, false>>;
+    version: StringShape;
+    engines: StringShape;
+    overrides: ArrayShape<ObjectShape<{
+        path: StringShape;
+        content: StringShape;
+    }, false>>;
+}, false>;
+
+/**
+ * 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', … }
+ * ```
+ */
+export declare function blueprintToMembers(spec: Blueprint): readonly Member[];
+
+/**
+ * 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
+ * ```
+ */
+export declare function blueprintToPlan(blueprint: Blueprint, groups?: readonly Group[]): Plan;
+
+/**
+ * One fleet package's catalog row — the `orkestrel` agent's package-catalog
+ * section, derived rather than hand-maintained.
+ *
+ * @remarks
+ * `description` is the flattened text of the package's own guide's FIRST
+ * blockquote; empty (`''`) when that guide is missing, unreadable, or
+ * carries no blockquote — never a placeholder string.
+ */
+export declare interface CatalogEntry {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+}
+
+/**
+ * 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']
+ * ```
+ */
+export declare function catalogNames(text: string): readonly string[];
+
+/**
+ * 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…'
+ * ```
+ */
+export declare function catalogToBlock(entries: readonly CatalogEntry[]): string;
+
+/** The four `Category` values, frozen. */
+export declare const CATEGORIES: readonly ["type", "constant", "factory", "entity"];
+
+/** What a declared `Member` IS in the scaffolded surface. */
+export declare type Category = 'type' | 'constant' | 'factory' | 'entity';
+
+/**
+ * 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']
+ * ```
+ */
+export declare function compareCodeUnit(a: string, b: string): number;
+
+/** The pipeline phases in order, frozen. */
+export declare const COMPILE_STAGES: readonly ["draft", "gate", "pin"];
+
+/** A visible marker for a stage that failed. */
+export declare interface CompileFailure {
+    readonly stage: CompileStage;
+    readonly code: ScaffoldErrorCode;
+    readonly message: string;
+}
+
+/**
+ * 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()
+ * ```
+ */
+export declare class Compiler implements CompilerInterface {
+    #private;
+    constructor(options?: CompilerOptions);
+    get emitter(): EmitterInterface<CompilerEventMap>;
+    /**
+     * 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: Blueprint, groups?: readonly Group[]): 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: Blueprint, current: Readonly<Record<string, string>>, groups?: readonly Group[]): Audit;
+    /** Idempotent teardown — emits `destroy`, then destroys the emitter LAST. */
+    destroy(): void;
+}
+
+/** The default id for a `Compiler` orchestrator. */
+export declare const COMPILER_ID = "compiler";
+
+/** A structured input/output snapshot of one pipeline phase. */
+export declare interface CompileRecord {
+    readonly stage: CompileStage;
+    readonly input: unknown;
+    readonly output: unknown;
+    readonly failed: boolean;
+    readonly error?: string;
+}
+
+/** `Compiler`'s push observation surface (AGENTS §13). */
+export declare type CompilerEventMap = {
+    readonly compile: readonly [scaffolding: Scaffolding];
+    readonly audit: readonly [audit: Audit];
+    readonly block: readonly [questions: readonly Question[]];
+    readonly error: readonly [error: unknown];
+    readonly destroy: readonly [];
+};
+
+/** The compilation orchestrator contract. */
+export declare interface CompilerInterface {
+    readonly emitter: EmitterInterface<CompilerEventMap>;
+    compile(blueprint: Blueprint, groups?: readonly Group[]): Scaffolding;
+    audit(blueprint: Blueprint, current: Readonly<Record<string, string>>, groups?: readonly Group[]): Audit;
+    destroy(): void;
+}
+
+/** Options for `createCompiler` / the `Compiler` constructor. */
+export declare interface CompilerOptions {
+    readonly on?: EmitterHooks<CompilerEventMap>;
+    readonly error?: EmitterErrorHandler;
+}
+
+/** The three fixed pipeline phases, in order. */
+export declare type CompileStage = 'draft' | 'gate' | 'pin';
+
+/**
+ * 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'
+ * ```
+ */
+export declare function computeHash(text: string): string;
+
+/**
+ * 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
+ * ```
+ */
+export declare function configArtifacts(spec: Blueprint): readonly Artifact[];
+
+/**
+ * `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
+ * ```
+ */
+export declare function coreTsconfig(): string;
+
+/**
+ * `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
+ * ```
+ */
+export declare function coreViteConfig(): string;
+
+/**
+ * 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', …)
+     * ```
+     */
+ export declare function createBlueprint(data: Partial<Blueprint> & {
+     readonly name: string;
+ }): Blueprint;
+
+ /**
+  * 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()
+  * ```
+  */
+ export declare function createCompiler(options?: CompilerOptions): CompilerInterface;
+
+ /**
+  * 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()
+  * ```
+  */
+ export declare function createPlanManager(options?: PlanManagerOptions): PlanManagerInterface;
+
+ /** The `engines.node` range the `blueprint` builder fills. */
+ export declare const DEFAULT_ENGINES = ">=22";
+
+ /** The starting version the `blueprint` builder fills. */
+ export declare const DEFAULT_VERSION = "0.0.1";
+
+ /**
+  * 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) // ':----'
+  * ```
+  */
+ export declare function delimiterCell(columnAlign: TableAlign, width: number): string;
+
+ /**
+  * One runtime `@orkestrel/*` dependency.
+  *
+  * @remarks
+  * Drives its `package.json` entry, the build externals, and its
+  * `guides/src/<dep>.md` mirror — byte-correct for a dep this package vendors
+  * (contract / emitter / markdown / template / terminal / console / guide),
+  * a `host`-origin pointer the caller syncs otherwise.
+  */
+ export declare interface Dependency {
+     readonly name: string;
+     readonly range: string;
+     /** Meaningful only when this `Dependency` appears in a `Blueprint`'s `peers` — `true` emits a `peerDependenciesMeta` `{ optional: true }` entry alongside it. */
+     readonly optional?: boolean;
+ }
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function dependency(name: string, range: string, optional?: boolean): Dependency;
+
+ /**
+  * 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.
+  */
+ export declare const DEPENDENCY_NAME_PATTERN: RegExp;
+
+ /**
+  * Build the `Dependency` object shape.
+  *
+  * @returns A fresh `ContractShape` describing `{ name, range, optional? }`.
+  */
+ export declare function dependencyShape(): ObjectShape<{
+     name: StringShape;
+     range: StringShape;
+     optional: OptionalShape<BooleanShape>;
+ }, false>;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function devDependenciesFor(extras: readonly Dependency[]): Readonly<Record<string, string>>;
+
+ /**
+  * 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 }
+  * ```
+  */
+ export declare function diffPlan(plan: Plan, current: Readonly<Record<string, string>>): Audit;
+
+ /** One `Finding`'s verdict against the target's current content. */
+ export declare type Drift = 'aligned' | 'stale' | 'missing' | 'foreign';
+
+ /**
+  * 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' } }
+  * ```
+  */
+ export declare function dualCondition(path: string): Readonly<Record<string, unknown>>;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function entryFields(surfaces: readonly Surface[]): {
+     readonly main: string;
+     readonly module: string;
+     readonly types?: string;
+ };
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function exportsMap(surfaces: readonly Surface[]): Readonly<Record<string, unknown>>;
+
+ /**
+  * 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/*`.
+  */
+ export declare const EXTRA_NAME_PATTERN: RegExp;
+
+ /**
+  * 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…' }
+  * ```
+  */
+ export declare function fillArtifact(path: string, group: Group, id: string, values: Readonly<Record<string, unknown>>, surface?: Surface): Artifact;
+
+ /** One audit drift result. */
+ export declare interface Finding {
+     readonly path: string;
+     readonly group: Group;
+     readonly drift: Drift;
+ }
+
+ /** The four `Freshness` values, frozen — the currency axis `Sync` reports on. */
+ export declare const FRESHNESS: readonly ["current", "behind", "missing", "failed"];
+
+ /**
+  * One `GuideSync` / `VersionSync`'s currency against upstream.
+  *
+  * @remarks
+  * `missing` is an upstream `404`; `failed` is a transport fault.
+  */
+ export declare type Freshness = 'current' | 'behind' | 'missing' | 'failed';
+
+ /** The closed artifact-group vocabulary a plan selects over. */
+ export declare type Group = 'manifest' | 'configs' | 'source' | 'tests' | 'guides' | 'docs' | 'orchestration';
+
+ /** The seven `Group` values, frozen — the artifact-group selection vocabulary. */
+ export declare const GROUPS: readonly ["manifest", "configs", "source", "tests", "guides", "docs", "orchestration"];
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function guideArtifacts(spec: Blueprint, pascal: string, members: readonly Member[]): readonly Artifact[];
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function guideMemberTable(category: Member['category'], members: readonly Member[]): string;
+
+ /**
+  * One dependency guide fetched from upstream at its `path`, plus its
+  * `freshness` verdict against the local mirror.
+  *
+  * @remarks
+  * `note` carries the failure/anomaly CAUSE — a transport error message, an
+  * `HTTP <status>`, `redirected (redirect following is disabled)`, or a
+  * `response exceeded limit (<n> bytes)` — present on every non-`current`
+  * outcome that has a discoverable cause; absent on `current` and on `behind`
+  * (both are clean outcomes with nothing to explain).
+  */
+ export declare interface GuideSync {
+     readonly name: string;
+     readonly path: string;
+     readonly content: string;
+     readonly freshness: Freshness;
+     readonly note?: string;
+ }
+
+ /**
+  * 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`).
+  */
+ export declare const HOST_PATHS: readonly ["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"];
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function hostGroup(path: string): Group;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function inferGroup(path: string): Group;
+
+ /**
+  * 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.
+  */
+ export declare const isArtifact: Guard<Artifact>;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function isBehind(freshness: Freshness): boolean;
+
+ /**
+  * 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.
+  */
+ export declare const isBlueprint: Guard<Blueprint>;
+
+ /**
+  * 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.
+  */
+ export declare const isDependency: Guard<Dependency>;
+
+ /**
+  * 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.
+  */
+ export declare const isMember: Guard<Member>;
+
+ /**
+  * 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.
+  */
+ export declare const isOverride: Guard<Override>;
+
+ /**
+  * 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.
+  */
+ export declare const isPlan: Guard<Plan>;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function isRecord(value: unknown): value is Record<string, unknown>;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function isScaffoldError(value: unknown): value is ScaffoldError;
+
+ /**
+  * 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.
+  */
+ export declare const isSyncReport: Guard<SyncReport>;
+
+ /**
+  * 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' }]
+  * ```
+  */
+ export declare function manifestToDependencies(manifestText: string): readonly Dependency[];
+
+ /** One declared public export of the scaffolded package; derived by `blueprintToMembers`, never authored. */
+ export declare interface Member {
+     readonly name: string;
+     readonly category: Category;
+     readonly summary: string;
+     readonly surface: Surface;
+ }
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function member(name: string, category: Category, summary: string, surface?: Surface): Member;
+
+ /**
+  * Build the `Member` object shape.
+  *
+  * @returns A fresh `ContractShape` describing `{ name, category, summary, surface }`.
+  */
+ export declare function memberShape(): ObjectShape<{
+     name: StringShape;
+     category: LiteralShape<readonly ["type", "constant", "factory", "entity"]>;
+     summary: StringShape;
+     surface: LiteralShape<readonly ["core", "browser", "server"]>;
+ }, false>;
+
+ /** The package-name RegExp — lowercase alphanumeric-with-hyphens, letter-first. */
+ export declare const NAME_PATTERN: RegExp;
+
+ /**
+  * How an `Artifact`'s content is produced: `host` byte-copied from the vendored
+  * data root, `template` filled from a frozen `TemplateDefinition` by
+  * `@orkestrel/template`'s pure fill engine, `computed` derived by the core's
+  * own combination logic.
+  */
+ export declare type Origin = 'host' | 'template' | 'computed';
+
+ /** The three `Origin` values, frozen. */
+ export declare const ORIGINS: readonly ["host", "template", "computed"];
+
+ /**
+  * One caller template override.
+  *
+  * @remarks
+  * `content` REPLACES the rendered artifact at `path`, never partially merges.
+  * An override whose `path` matches no planned artifact, or targets a
+  * `host`-origin path, is a BLOCKING question — never a silent add.
+  */
+ export declare interface Override {
+     readonly path: string;
+     readonly content: string;
+ }
+
+ /**
+  * 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' }
+  * ```
+  */
+ export declare function override(path: string, content: string): Override;
+
+ /**
+  * Build the `Override` object shape.
+  *
+  * @returns A fresh `ContractShape` describing `{ path, content }`.
+  */
+ export declare function overrideShape(): ObjectShape<{
+     path: StringShape;
+     content: StringShape;
+ }, false>;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function packageManifest(spec: Blueprint): string;
+
+ /**
+  * 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   '
+  * ```
+  */
+ export declare function padCell(text: string, width: number): string;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function paritySpecifiers(spec: Blueprint): string;
+
+ /**
+  * 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`.
+  */
+ export declare const parseBlueprint: (input: unknown) => Blueprint | undefined;
+
+ /**
+  * 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`.
+  */
+ export declare const parsePlan: (input: unknown) => Plan | undefined;
+
+ /**
+  * 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`.
+  */
+ export declare const parseSyncReport: (input: unknown) => SyncReport | undefined;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function pascalCase(name: string): string;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function pinPlan(plan: Plan): Plan;
+
+ /** The compiled, ordered artifact list plus the selection it covers; `trace` / `hash` filled by the pin. */
+ export declare interface Plan {
+     readonly blueprint: Blueprint;
+     readonly groups: readonly Group[];
+     readonly artifacts: readonly Artifact[];
+     readonly trace?: string;
+     readonly hash?: string;
+ }
+
+ /**
+  * 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()
+  * ```
+  */
+ export declare class PlanManager implements PlanManagerInterface {
+     #private;
+     constructor(options?: PlanManagerOptions);
+     get emitter(): EmitterInterface<PlanManagerEventMap>;
+     get size(): number;
+     /**
+      * Whether a plan with the given id is registered.
+      *
+      * @param id - The plan record id.
+      * @returns `true` when `id` is registered.
+      */
+     has(id: string): boolean;
+     /**
+      * 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: string): PlanRecord | undefined;
+     /**
+      * List every registered plan record (AGENTS §9.1 plural accessor).
+      *
+      * @returns A snapshot array of every registered `PlanRecord`.
+      */
+     plans(): readonly PlanRecord[];
+     /**
+      * 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: Plan): PlanRecord;
+     /**
+      * Remove one, several, or every registered plan (AGENTS §9.2 batch
+      * overloads) — array overload declared first so a list resolves to the
+      * batch form.
+      *
+      * @remarks
+      * `remove()` removes every registered plan, emitting `remove` once per id.
+      * `remove(id)` removes one plan, emitting `remove` and returning `true`
+      * when it existed, `false` otherwise. `remove(ids)` is ALL-OR-NOTHING: if
+      * any listed id is unregistered, the collection is left untouched and
+      * `false` is returned.
+      *
+      * @param target - Omit to remove all, a single id, or a list of ids.
+      * @returns `boolean` for the single-id / list-of-ids forms; `void` for the remove-all form.
+      */
+     remove(ids: readonly string[]): boolean;
+     remove(id: string): boolean;
+     remove(): void;
+     /** Idempotent teardown — clears the collection, emits `destroy`, then destroys the emitter LAST. */
+     destroy(): void;
+ }
+
+ /** `PlanManager`'s push observation surface (AGENTS §13). */
+ export declare type PlanManagerEventMap = {
+     readonly add: readonly [id: string];
+     readonly remove: readonly [id: string];
+     readonly destroy: readonly [];
+ };
+
+ /** The plan registry contract (AGENTS §9). */
+ export declare interface PlanManagerInterface {
+     readonly emitter: EmitterInterface<PlanManagerEventMap>;
+     readonly size: number;
+     has(id: string): boolean;
+     plan(id: string): PlanRecord | undefined;
+     plans(): readonly PlanRecord[];
+     add(plan: Plan): PlanRecord;
+     remove(ids: readonly string[]): boolean;
+     remove(id: string): boolean;
+     remove(): void;
+     destroy(): void;
+ }
+
+ /** Options for `createPlanManager` / the `PlanManager` constructor. */
+ export declare interface PlanManagerOptions {
+     readonly plans?: readonly Plan[];
+     readonly on?: EmitterHooks<PlanManagerEventMap>;
+     readonly error?: EmitterErrorHandler;
+ }
+
+ /** A versioned, content-hashed `Plan` inside a `PlanManager`. */
+ export declare interface PlanRecord {
+     readonly id: string;
+     readonly plan: Plan;
+     readonly version: number;
+     readonly hash: string;
+ }
+
+ /**
+  * 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.
+  */
+ export declare function planShape(): ObjectShape<{
+     blueprint: ObjectShape<{
+         name: StringShape;
+         description: OptionalShape<StringShape>;
+         keywords: ArrayShape<StringShape>;
+         surfaces: ArrayShape<LiteralShape<readonly ["core", "browser", "server"]>>;
+         dependencies: ArrayShape<ObjectShape<{
+             name: StringShape;
+             range: StringShape;
+             optional: OptionalShape<BooleanShape>;
+         }, false>>;
+         peers: ArrayShape<ObjectShape<{
+             name: StringShape;
+             range: StringShape;
+             optional: OptionalShape<BooleanShape>;
+         }, false>>;
+         extras: ArrayShape<ObjectShape<{
+             name: StringShape;
+             range: StringShape;
+             optional: OptionalShape<BooleanShape>;
+         }, false>>;
+         version: StringShape;
+         engines: StringShape;
+         overrides: ArrayShape<ObjectShape<{
+             path: StringShape;
+             content: StringShape;
+         }, false>>;
+     }, false>;
+     groups: ArrayShape<LiteralShape<readonly ["manifest", "configs", "source", "tests", "guides", "docs", "orchestration"]>>;
+     artifacts: ArrayShape<ObjectShape<{
+         path: StringShape;
+         group: LiteralShape<readonly ["manifest", "configs", "source", "tests", "guides", "docs", "orchestration"]>;
+         origin: LiteralShape<readonly ["host", "template", "computed"]>;
+         surface: OptionalShape<LiteralShape<readonly ["core", "browser", "server"]>>;
+         content: OptionalShape<StringShape>;
+         source: OptionalShape<StringShape>;
+     }, false>>;
+     trace: OptionalShape<StringShape>;
+     hash: OptionalShape<StringShape>;
+ }, false>;
+
+ /** The dry-run tally. */
+ export declare interface PlanSummary {
+     readonly name: string;
+     readonly surfaces: readonly Surface[];
+     readonly groups: readonly Group[];
+     readonly artifacts: number;
+     readonly host: number;
+     readonly template: number;
+     readonly computed: number;
+ }
+
+ /**
+  * 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…'
+  * ```
+  */
+ export declare function planToReview(plan: Plan): string;
+
+ /**
+  * 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, … }
+  * ```
+  */
+ export declare function planToSummary(plan: Plan): PlanSummary;
+
+ /**
+  * One validation issue.
+  *
+  * @remarks
+  * `blocking: true` fails the gate closed, `false` is an advisory that rides a
+  * complete result.
+  */
+ export declare interface Question {
+     readonly field: string;
+     readonly text: string;
+     readonly blocking: boolean;
+     readonly candidates?: readonly string[];
+ }
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function rangeToFreshness(range: string, latest: string): Freshness;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function rootTsconfig(surfaces: readonly Surface[]): string;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function rootViteConfig(surfaces: readonly Surface[]): string;
+
+ /** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
+ export declare const SCAFFOLD_RANGE = "^0.0.1";
+
+ /**
+  * 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'
+  * }
+  * ```
+  */
+ export declare class ScaffoldError extends Error {
+     readonly code: ScaffoldErrorCode;
+     readonly context?: unknown;
+     constructor(code: ScaffoldErrorCode, message: string, context?: unknown);
+ }
+
+ /** Coded `ScaffoldError` reasons. */
+ export declare type ScaffoldErrorCode = 'INVALID' | 'BLOCKED' | 'DESTROYED' | 'TARGET' | 'WRITE' | 'FETCH';
+
+ /** The full, replayable outcome of one `compile()` call. */
+ export declare interface Scaffolding {
+     readonly blueprint: Blueprint;
+     readonly plan?: Plan;
+     readonly questions: readonly Question[];
+     readonly stages: readonly CompileRecord[];
+     readonly failures: readonly CompileFailure[];
+     readonly complete: boolean;
+     readonly digest: string;
+ }
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function singleSurfaceViteConfig(surface: 'browser' | 'server'): string;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function sourceArtifacts(spec: Blueprint, pascal: string): readonly Artifact[];
+
+ /**
+  * 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']
+  * ```
+  */
+ export declare function splitTableRow(line: string): readonly string[];
+
+ /**
+  * 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}'
+  * ```
+  */
+ export declare function stableStringify(value: unknown): string;
+
+ /** The environment surface an artifact or member belongs to (the SCAFFOLDED package's faces, not scaffold's own). */
+ export declare type Surface = 'core' | 'browser' | 'server';
+
+ /**
+  * 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.
+  */
+ export declare const SURFACE_MATRIX: Readonly<{
+     readonly core: Readonly<{
+         configs: readonly ["configs/src/vite.core.config.ts", "configs/src/tsconfig.core.json"];
+         project: "src:core";
+         path: ".";
+         formats: readonly ["es", "cjs"];
+     }>;
+     readonly browser: Readonly<{
+         configs: readonly ["configs/src/vite.browser.config.ts", "configs/src/tsconfig.browser.json"];
+         project: "src:browser";
+         path: "./browser";
+         formats: readonly ["es"];
+     }>;
+     readonly server: Readonly<{
+         configs: readonly ["configs/src/vite.server.config.ts", "configs/src/tsconfig.server.json"];
+         project: "src:server";
+         path: "./server";
+         formats: readonly ["es", "cjs"];
+     }>;
+ }>;
+
+ /** The three `Surface` values, frozen — compose with `literalOf(...)` / `parseEnum(...)`. */
+ export declare const SURFACES: readonly ["core", "browser", "server"];
+
+ /**
+  * `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
+  * ```
+  */
+ export declare function surfaceTsconfig(surface: 'browser' | 'server'): string;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function surfaceVariant(surfaces: readonly Surface[]): Surface | 'multi';
+
+ /**
+  * `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
+  * ```
+  */
+ export declare function surfaceViteConfig(surface: 'browser' | 'server'): string;
+
+ /**
+  * The whole outcome of a `Sync.pull`.
+  *
+  * @remarks
+  * `clean` is `true` iff no drift AND no failures; `failed` is the count of
+  * guide/version fetches that came back `missing` or `failed`.
+  */
+ export declare interface SyncReport {
+     readonly target: string;
+     readonly guides: readonly GuideSync[];
+     readonly versions: readonly VersionSync[];
+     readonly clean: boolean;
+     readonly failed: number;
+ }
+
+ /**
+  * 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.
+  */
+ export declare function syncReportShape(): ObjectShape<{
+     target: StringShape;
+     guides: ArrayShape<ObjectShape<{
+         name: StringShape;
+         path: StringShape;
+         content: StringShape;
+         freshness: LiteralShape<readonly ["current", "behind", "missing", "failed"]>;
+         note: OptionalShape<StringShape>;
+     }, boolean | ContractShape>>;
+     versions: ArrayShape<ObjectShape<{
+         name: StringShape;
+         range: StringShape;
+         latest: StringShape;
+         freshness: LiteralShape<readonly ["current", "behind", "missing", "failed"]>;
+         note: OptionalShape<StringShape>;
+     }, boolean | ContractShape>>;
+     clean: BooleanShape;
+     failed: NumberShape;
+ }, false>;
+
+ /**
+  * 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…'
+  * ```
+  */
+ export declare function syncToReview(report: SyncReport): string;
+
+ /**
+  * 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.
+  */
+ export declare const TEMPLATES: Readonly<Record<string, TemplateDefinition>>;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function testArtifacts(spec: Blueprint, pascal: string): readonly Artifact[];
+
+ /**
+  * 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: [] }
+  * ```
+  */
+ export declare function validateBlueprint(spec: Blueprint): Validation;
+
+ /**
+  * 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) {} }
+  * ```
+  */
+ export declare function validateDependencyArray(field: string, items: readonly Dependency[]): {
+     readonly questions: readonly Question[];
+     readonly seen: ReadonlySet<string>;
+ };
+
+ /** The semantic pass over a blueprint; returns, never throws. */
+ export declare interface Validation {
+     readonly valid: boolean;
+     readonly questions: readonly Question[];
+     readonly warnings: readonly string[];
+ }
+
+ /**
+  * One dependency's declared `range` against the registry `latest`, plus its
+  * `freshness` verdict.
+  *
+  * @remarks
+  * `note` carries the failure/anomaly CAUSE — see {@link GuideSync.note}.
+  */
+ export declare interface VersionSync {
+     readonly name: string;
+     readonly range: string;
+     readonly latest: string;
+     readonly freshness: Freshness;
+     readonly note?: string;
+ }
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function viteHeader(needsPlaywright: boolean): string;
+
+ export { }