npm - @orkestrel/scaffold - Versions diffs - 0.0.24 → 0.0.26 - Mend

@orkestrel/scaffold 0.0.24 → 0.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/README.md +5 -0
package/dist/bin/main.js +45 -4
package/dist/bin/main.js.map +1 -1
package/dist/host/agents/orchestration.md +40 -11
package/dist/host/claude/agents/orkestrel.md +63 -48
package/dist/host/claude/rules/documentation.md +1 -1
package/dist/host/guides/guide.md +211 -100
package/dist/host/guides/scaffold.md +165 -10
package/dist/host/manifest.json +5 -5
package/dist/host/tests/config.test.ts +30 -7
package/dist/src/core/index.cjs +242 -149
package/dist/src/core/index.cjs.map +1 -1
package/dist/src/core/index.d.cts +185 -98
package/dist/src/core/index.d.ts +185 -98
package/dist/src/core/index.js +240 -150
package/dist/src/core/index.js.map +1 -1
package/dist/src/server/index.cjs +171 -66
package/dist/src/server/index.cjs.map +1 -1
package/dist/src/server/index.d.cts +140 -26
package/dist/src/server/index.d.ts +140 -26
package/dist/src/server/index.js +173 -69
package/dist/src/server/index.js.map +1 -1
package/package.json +1 -1

package/dist/src/core/index.d.cts CHANGED Viewed

@@ -46,10 +46,9 @@ export declare interface AppDefinition {
  *
  * @example
  * ```ts
- * import type { Artifact } from '@orkestrel/scaffold'
- * import { applyOverrides } from '@orkestrel/scaffold'
+ * import { applyOverrides, blueprintToConfigArtifacts, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const artifacts: readonly Artifact[]
+ * const artifacts = blueprintToConfigArtifacts(createBlueprint('router', { src: ['core'] }))
  *
  * applyOverrides(artifacts, [{ path: 'README.md', content: '# Title\n' }])
  * ```
@@ -71,9 +70,13 @@ export declare type Artifact = HostArtifact | HydratedArtifact | ContentArtifact
  *
  * @remarks
  * Builders in `compilers.ts` fill every varying span through
- * `@orkestrel/template`. Empty barrels and setup modules are intentional: the
- * generated workspace starts with no sample domain API, while each selected
- * Vitest project gets a real test that proves its barrel has no starter exports.
+ * `@orkestrel/template`. Empty barrels, entries, and setup modules are
+ * intentional: the generated workspace starts with no sample domain API, while
+ * each selected Vitest project gets a real test that proves its barrel has no
+ * starter exports. An entry starts empty for the same reason its barrel does,
+ * and because the vendored lint config refuses an unassigned import outside a
+ * stylesheet, so a starter `import './index.js'` would fail the workspace's own
+ * `lint:check` on the day it is written.
  *
  * @example
  * ```ts
@@ -85,7 +88,6 @@ export declare type Artifact = HostArtifact | HydratedArtifact | ContentArtifact
 export declare const ARTIFACT_TEMPLATES: Readonly<{
     source: Readonly<{
         empty: "";
-        main: "import './index.js'\n";
         browser: "<!doctype html>\n<html lang=\"en\">\n\t<head>\n\t\t<meta charset=\"UTF-8\" />\n\t\t<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n\t\t<title>Application</title>\n\t</head>\n\t<body>\n\t\t<script type=\"module\" src=\"/main.ts\"></script>\n\t</body>\n</html>\n";
     }>;
     tests: Readonly<{
@@ -133,12 +135,11 @@ export declare interface ArtifactBase {
  *
  * @example
  * ```ts
- * import type { Artifact } from '@orkestrel/scaffold'
- * import { artifactsToQuestions } from '@orkestrel/scaffold'
+ * import { artifactsToQuestions, blueprintToConfigArtifacts, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const artifacts: readonly Artifact[]
+ * const artifacts = blueprintToConfigArtifacts(createBlueprint('router', { src: ['core'] }))
  *
- * artifactsToQuestions(artifacts).length === 0 // true when the draft is sound
+ * artifactsToQuestions(artifacts).length === 0 // true
  * ```
  */
 export declare function artifactsToQuestions(artifacts: readonly Artifact[]): readonly Question[];
@@ -149,13 +150,16 @@ export declare function artifactsToQuestions(artifacts: readonly Artifact[]): re
  * @param artifact - The planned artifact.
  * @param observed - The destination's exact bytes as hexadecimal; absent when
  * the destination holds no file.
- * @returns The finding, carrying `observed` exactly where bytes were read.
+ * @returns The finding, carrying the artifact's ownership and `observed`
+ * exactly where bytes were read.
  *
  * @remarks
  * The comparison itself is {@link inferDrift}'s, so ownership decides it here
  * exactly as it does everywhere else. This adds only the shape: a missing
  * destination has no bytes to record, and every other verdict records the bytes
  * it was given, which is the precondition the mutation that follows is held to.
+ * Ownership is copied rather than inferred from drift because aligned findings
+ * span all three ownership tiers.
  *
  * `foreign` is not answerable here, because it describes a path no artifact was
  * planned for.
@@ -167,7 +171,7 @@ export declare function artifactsToQuestions(artifacts: readonly Artifact[]): re
  * artifactToFinding(
  * 	{ path: 'README.md', group: 'docs', ownership: 'content', origin: 'computed', content: 'hi\n' },
  * 	'6279650a',
- * ) // { path: 'README.md', group: 'docs', drift: 'stale', observed: '6279650a' }
+ * ) // { path: 'README.md', group: 'docs', ownership: 'content', drift: 'stale', observed: '6279650a' }
  * ```
  */
 export declare function artifactToFinding(artifact: Artifact, observed?: string): Finding;
@@ -205,7 +209,8 @@ export declare function artifactToHex(artifact: Artifact): string | undefined;
  * @remarks
  * A blocking question means the gate refused the blueprint, so `findings` is
  * empty and says nothing about the target. Tallies are not stored: count
- * `findings` by `drift`.
+ * `findings` by `drift` or `ownership`. The finding bound is the sum of the
+ * separately bounded plan artifacts and snapshot paths.
  */
 export declare interface Audit {
     readonly findings: readonly Finding[];
@@ -233,7 +238,11 @@ export declare const BIN_ENTRY_PATH = "src/bin/main.ts";
  * `bin`, `integration`, `services`, `global`, and `showcase` are structural
  * facts: each is set only when the workspace physically ships the directory or
  * exact-case file that defines it, never because of the workspace's name and
- * never because a sibling fact is set.
+ * never because a sibling fact is set. An axis-dependent fact projects nothing
+ * when its required axis is absent: `integration` projects only a published
+ * `src`, and `showcase` projects only a browser `app`. The gate answers that case
+ * with a non-blocking question, so a caller that set the flag learns it emitted
+ * nothing and the compile still completes.
  */
 export declare interface Blueprint {
     readonly name: string;
@@ -262,10 +271,9 @@ export declare interface Blueprint {
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToConfigArtifacts } from '@orkestrel/scaffold'
+ * import { blueprintToConfigArtifacts, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { src: ['core'] })
  *
  * blueprintToConfigArtifacts(blueprint)[0]?.path // 'tsconfig.json'
  * ```
@@ -298,10 +306,9 @@ export declare function blueprintToConfigArtifacts(blueprint: Blueprint): readon
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToDevDependencies } from '@orkestrel/scaffold'
+ * import { blueprintToDevDependencies, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { src: ['core'] })
  *
  * blueprintToDevDependencies(blueprint).typescript // the shared TypeScript pin
  * ```
@@ -344,12 +351,11 @@ export declare function blueprintToGuideArtifacts(blueprint: Blueprint): readonl
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToMachinery } from '@orkestrel/scaffold'
+ * import { blueprintToMachinery, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { app: ['browser'] })
  *
- * blueprintToMachinery(blueprint).vue // true when the app declares browser
+ * blueprintToMachinery(blueprint).vue // true
  * ```
  */
 export declare function blueprintToMachinery(blueprint: Blueprint): ViteMachinery;
@@ -382,10 +388,9 @@ export declare function blueprintToMachinery(blueprint: Blueprint): ViteMachiner
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToManifest } from '@orkestrel/scaffold'
+ * import { blueprintToManifest, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { src: ['core'] })
  *
  * blueprintToManifest(blueprint).endsWith('}\n') // true
  * ```
@@ -409,8 +414,8 @@ export declare function blueprintToOrchestrationArtifacts(blueprint: Blueprint):
  * Measure a blueprint against every law its own fields decide.
  *
  * @param blueprint - The workspace specification.
- * @returns One blocking question per rejected field, in blueprint field order,
- * with the rules that span several fields last.
+ * @returns One question per rejected field, in blueprint field order, with the
+ * rules that span several fields last.
  *
  * @remarks
  * Only the laws a blueprint answers alone are here. The structural record and
@@ -421,19 +426,25 @@ export declare function blueprintToOrchestrationArtifacts(blueprint: Blueprint):
  * a drafted plan belong to {@link artifactsToQuestions} and
  * {@link overridesToQuestions}.
  *
- * Every question is blocking, because each one describes a workspace this
- * package cannot generate rather than one it can generate imperfectly. An
- * environment question carries `ENVIRONMENTS` as its candidates, so a caller
- * reads the accepted values from the refusal instead of from the documentation.
+ * A question blocks when it describes a workspace this package cannot generate.
+ * Three do not, because each describes a workspace it can describe honestly and
+ * should not create: a published axis of several environments without core, whose
+ * manifest names a core build the workspace never runs, and a structural flag
+ * whose required axis is absent, which emits nothing. Blocking those closed the
+ * gate for every verb, and the verbs that read an existing workspace need the
+ * plan the gate refused. The caller that chooses the shape refuses the advisory;
+ * the callers that read one report it.
+ *
+ * An environment question carries `ENVIRONMENTS` as its candidates, so a caller
+ * reads the accepted values from the question instead of from the documentation.
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToQuestions } from '@orkestrel/scaffold'
+ * import { blueprintToQuestions, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { src: ['core'] })
  *
- * blueprintToQuestions(blueprint).length === 0 // true when the gate passes
+ * blueprintToQuestions(blueprint).length === 0 // true
  * ```
  */
 export declare function blueprintToQuestions(blueprint: Blueprint): readonly Question[];
@@ -446,10 +457,9 @@ export declare function blueprintToQuestions(blueprint: Blueprint): readonly Que
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToRootTsconfig } from '@orkestrel/scaffold'
+ * import { blueprintToRootTsconfig, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { src: ['core'] })
  *
  * blueprintToRootTsconfig(blueprint).startsWith('{') // true
  * ```
@@ -469,10 +479,9 @@ export declare function blueprintToRootTsconfig(blueprint: Blueprint): string;
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToRootVite } from '@orkestrel/scaffold'
+ * import { blueprintToRootVite, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { src: ['core'] })
  *
  * blueprintToRootVite(blueprint).includes('defineConfig') // true
  * ```
@@ -499,10 +508,9 @@ export declare function blueprintToRootVite(blueprint: Blueprint): string;
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToScripts } from '@orkestrel/scaffold'
+ * import { blueprintToScripts, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { src: ['core'] })
  *
  * blueprintToScripts(blueprint)['format:check'] // 'oxfmt --config .oxfmtrc.json --check .'
  * ```
@@ -516,16 +524,18 @@ export declare function blueprintToScripts(blueprint: Blueprint): Readonly<Recor
  * @returns Empty published barrels, selected application entries, and the optional bin entry.
  *
  * @remarks
- * The barrels and bin entry intentionally export nothing. A generated sample
- * entity is too easy to mistake for package implementation, so the scaffold
- * establishes only the selected environment boundaries.
+ * The barrels and every runtime entry intentionally hold nothing. A generated
+ * sample entity is too easy to mistake for package implementation, so the
+ * scaffold establishes only the selected environment boundaries. An application
+ * entry is empty for the same reason the bin entry is, and because the vendored
+ * lint config refuses an unassigned import outside a stylesheet, so the entry
+ * cannot start by importing its barrel for effect either.
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToSourceArtifacts } from '@orkestrel/scaffold'
+ * import { blueprintToSourceArtifacts, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { src: ['core'] })
  *
  * blueprintToSourceArtifacts(blueprint).every(({ group }) => group === 'source') // true
  * ```
@@ -548,10 +558,9 @@ export declare function blueprintToSourceArtifacts(blueprint: Blueprint): readon
  *
  * @example
  * ```ts
- * import type { Blueprint } from '@orkestrel/scaffold'
- * import { blueprintToTestArtifacts } from '@orkestrel/scaffold'
+ * import { blueprintToTestArtifacts, createBlueprint } from '@orkestrel/scaffold'
  *
- * declare const blueprint: Blueprint
+ * const blueprint = createBlueprint('router', { src: ['core'] })
  *
  * blueprintToTestArtifacts(blueprint)[0]?.path // 'tests/setup.ts'
  * ```
@@ -759,12 +768,19 @@ export declare class Compiler implements CompilerInterface {
           * carries no plan, then `compile` with the whole outcome either way, so an
           * observer reads every compile from one event and the refusals from the other.
           *
+          * A plan says the blueprint can be built. It does not say the blueprint should
+          * be created, and the questions beside it are what this compiler could not
+          * settle. A caller creating a fresh workspace answers them first and writes
+          * nothing while any remains, which is the rule the `new` verb applies; a caller
+          * describing or repairing an existing target carries them through instead.
+          * Nothing downstream repeats that check, because only the caller knows which of
+          * the two it is.
+          *
           * @example
           * ```ts
-          * import type { Blueprint } from '@orkestrel/scaffold'
-          * import { createCompiler } from '@orkestrel/scaffold'
+          * import { createBlueprint, createCompiler } from '@orkestrel/scaffold'
           *
-          * declare const blueprint: Blueprint
+          * const blueprint = createBlueprint('router', { src: ['core'] })
           *
           * createCompiler().compile(blueprint, ['manifest']).plan?.artifacts.length // 1
           * ```
@@ -785,14 +801,19 @@ export declare class Compiler implements CompilerInterface {
            * reports no findings and carries the questions instead. Emits `block` in that
            * case, then `audit` with the verdict either way.
            *
+           * Ownership decides each verdict, not absence. A birth-owned path is never
+           * compared and reads `aligned` against a target holding nothing, while a
+           * content-owned path with no bytes to read is `missing`. An empty snapshot
+           * therefore produces both verdicts rather than one.
+           *
            * @example
            * ```ts
-           * import type { Blueprint } from '@orkestrel/scaffold'
-           * import { createCompiler } from '@orkestrel/scaffold'
+           * import { createBlueprint, createCompiler } from '@orkestrel/scaffold'
            *
-           * declare const blueprint: Blueprint
+           * const blueprint = createBlueprint('router', { src: ['core'] })
            *
-           * createCompiler().audit(blueprint, {}).findings.every(({ drift }) => drift === 'missing') // true
+           * createCompiler().audit(blueprint, {}, ['manifest']).findings[0]?.drift // 'aligned'
+           * createCompiler().audit(blueprint, {}, ['configs']).findings[0]?.drift // 'missing'
            * ```
            */
        audit(blueprint: Blueprint, current: Snapshot, groups?: readonly Group[]): Audit;
@@ -941,7 +962,7 @@ export declare class Compiler implements CompilerInterface {
       export declare const CONFIG_TEMPLATES: Readonly<{
           root: Readonly<{
               tsconfig: "{\n\t\"compilerOptions\": {\n\t\t\"target\": \"ESNext\",\n\t\t\"module\": \"ESNext\",\n\t\t\"moduleResolution\": \"bundler\",\n\t\t\"allowImportingTsExtensions\": true,\n\t\t\"lib\": [\"ESNext\", \"DOM\", \"DOM.Iterable\"],\n\t\t\"types\": [\"node\", \"vite/client\", \"vitest/globals\"],\n\t\t\"moduleDetection\": \"force\",\n\t\t\"resolveJsonModule\": true,\n\t\t\"strict\": true,\n\t\t\"verbatimModuleSyntax\": true,\n\t\t\"noUncheckedIndexedAccess\": true,\n\t\t\"noUncheckedSideEffectImports\": true,\n\t\t\"exactOptionalPropertyTypes\": true,\n\t\t\"noUnusedLocals\": true,\n\t\t\"noUnusedParameters\": true,\n\t\t\"noImplicitOverride\": true,\n\t\t\"noFallthroughCasesInSwitch\": true,\n\t\t\"forceConsistentCasingInFileNames\": true,\n\t\t\"skipLibCheck\": true,\n\t\t\"noEmit\": true,\n\t\t\"paths\": {\n{{paths}}\n\t\t}\n\t},\n\t\"exclude\": [\"node_modules\", \"dist\", \"tmp\"]\n}\n";
-              vite: "import type { UserConfig } from 'vite'\n{{imports}}\nimport { defineConfig, mergeConfig } from 'vitest/config'\nimport tsconfig from './tsconfig.json' with { type: 'json' }\nimport { environmentBoundary, outputBoundary } from './configs/helpers.js'\nimport { lstatSync, readdirSync, realpathSync } from 'node:fs'\nimport { basename, join, parse, relative, resolve as resolvePath, sep } from 'node:path'\nimport { fileURLToPath, URL } from 'node:url'\n\nexport function resolveWorkspacePath(relativePath: string): string {\n\treturn fileURLToPath(new URL(relativePath, import.meta.url))\n}\n\n// A generated root config must classify its own fixed proof without importing\n// package source, so the exact-case check stays self-contained over Node APIs.\nfunction isExactCaseFile(path: string): boolean {\n\tconst full = resolvePath(path)\n\ttry {\n\t\tconst status = lstatSync(full)\n\t\tif (!status.isFile() || status.isSymbolicLink() || status.nlink !== 1) return false\n\t\tconst root = parse(full).root\n\t\tconst segments = relative(root, full).split(sep)\n\t\tlet parent = root\n\t\tfor (const segment of segments) {\n\t\t\ttry {\n\t\t\t\tif (!readdirSync(parent).includes(segment)) return false\n\t\t\t} catch {\n\t\t\t\tif (basename(realpathSync.native(join(parent, segment))) !== segment) return false\n\t\t\t}\n\t\t\tparent = join(parent, segment)\n\t\t}\n\t\treturn true\n\t} catch {\n\t\treturn false\n\t}\n}\n\nconst resolve = {\n\talias: Object.entries(tsconfig.compilerOptions.paths).reduce((aliases, [key, values]) => {\n\t\tconst [path] = values\n\t\tif (path === undefined) throw new Error('tsconfig path alias ' + key + ' has no target')\n\t\treturn Object.assign(aliases, { [key]: resolveWorkspacePath(path) })\n\t}, {}),\n}\n\n{{factories}}export default defineConfig({\n\tresolve,\n\ttest: {\n{{projects}}\n\t},\n})\n";
+              vite: "import type { {{viteTypes}} } from 'vite'\n{{imports}}import { defineConfig, mergeConfig } from 'vitest/config'\nimport tsconfig from './tsconfig.json' with { type: 'json' }\n{{helpers}}import { lstatSync, readdirSync, realpathSync } from 'node:fs'\nimport { basename, join, parse, relative, resolve as resolvePath, sep } from 'node:path'\nimport { fileURLToPath, URL } from 'node:url'\n\nexport function resolveWorkspacePath(relativePath: string): string {\n\treturn fileURLToPath(new URL(relativePath, import.meta.url))\n}\n\n// A generated root config must classify its own fixed proof without importing\n// package source, so the exact-case check stays self-contained over Node APIs.\nfunction isExactCaseFile(path: string): boolean {\n\tconst full = resolvePath(path)\n\ttry {\n\t\tconst status = lstatSync(full)\n\t\tif (!status.isFile() || status.isSymbolicLink() || status.nlink !== 1) return false\n\t\tconst root = parse(full).root\n\t\tconst segments = relative(root, full).split(sep)\n\t\tlet parent = root\n\t\tfor (const segment of segments) {\n\t\t\ttry {\n\t\t\t\tif (!readdirSync(parent).includes(segment)) return false\n\t\t\t} catch {\n\t\t\t\tif (basename(realpathSync.native(join(parent, segment))) !== segment) return false\n\t\t\t}\n\t\t\tparent = join(parent, segment)\n\t\t}\n\t\treturn true\n\t} catch {\n\t\treturn false\n\t}\n}\n\nconst resolve = {\n\talias: Object.entries(tsconfig.compilerOptions.paths).reduce((aliases, [key, values]) => {\n\t\tconst [path] = values\n\t\tif (path === undefined) throw new Error('tsconfig path alias ' + key + ' has no target')\n\t\treturn Object.assign(aliases, { [key]: resolveWorkspacePath(path) })\n\t}, {}),\n}\n\n{{factories}}export default defineConfig({\n\tresolve,\n\ttest: {\n{{projects}}\n\t},\n})\n";
           }>;
           factories: Readonly<{
               src: Readonly<{
@@ -952,7 +973,7 @@ export declare class Compiler implements CompilerInterface {
               }>;
               app: Readonly<{
                   core: "export const appCore = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\tpublicDir: false,\n\t\t\tplugins: [environmentBoundary('app/core')],\n\t\t\ttest: {\n\t\t\t\tname: { label: 'app:core', color: 'cyan' },\n\t\t\t\tinclude: ['tests/app/core/**/*.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
-                  browser: "function applicationBrowser(showcase: boolean): UserConfig {\n\tconst output = showcase ? 'dist/showcase' : 'dist/app/browser'\n\treturn {\n\t\tresolve,\n\t\tplugins: [\n\t\t\toutputBoundary(output),\n\t\t\tenvironmentBoundary('app/browser'),\n\t\t\tvue(),\n{{showcasePlugin}}\t\t],\n\t\troot: resolveWorkspacePath('app/browser'),\n\t\tpublicDir: false,\n\t\tbuild: {\n{{showcaseBuild}}\t\t\temptyOutDir: true,\n\t\t\toutDir: resolveWorkspacePath(output),\n\t\t\trolldownOptions: { input: resolveWorkspacePath('app/browser/index.html') },\n\t\t},\n\t\ttest: {\n\t\t\tname: { label: 'app:browser', color: 'blue' },\n\t\t\troot: resolveWorkspacePath('.'),\n\t\t\tdir: resolveWorkspacePath('.'),\n\t\t\tinclude: ['tests/app/browser/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts'],\n\t\t\tbrowser: {\n\t\t\t\tenabled: true,\n\t\t\t\tprovider: playwright(),\n\t\t\t\tinstances: [{ browser: 'chromium', headless: true }],\n\t\t\t},\n\t\t\tfileParallelism: false,\n\t\t},\n\t}\n}\n\nexport function appBrowser(...options: never[]): UserConfig {\n\tif (options.length > 0) throw new Error('Browser configuration overrides are not permitted')\n\treturn applicationBrowser(false)\n}\n{{showcaseFactory}}";
+                  browser: "function applicationBrowser(showcase: boolean): UserConfig {\n\tconst output = showcase ? 'dist/showcase' : 'dist/app/browser'\n{{showcasePlugins}}\treturn {\n\t\tresolve,\n{{plugins}}\t\troot: resolveWorkspacePath('app/browser'),\n\t\tpublicDir: false,\n\t\tbuild: {\n{{showcaseBuild}}\t\t\temptyOutDir: true,\n\t\t\toutDir: resolveWorkspacePath(output),\n\t\t\trolldownOptions: { input: resolveWorkspacePath('app/browser/index.html') },\n\t\t},\n\t\ttest: {\n\t\t\tname: { label: 'app:browser', color: 'blue' },\n\t\t\troot: resolveWorkspacePath('.'),\n\t\t\tdir: resolveWorkspacePath('.'),\n\t\t\tinclude: ['tests/app/browser/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts'],\n\t\t\tbrowser: {\n\t\t\t\tenabled: true,\n\t\t\t\tprovider: playwright(),\n\t\t\t\tinstances: [{ browser: 'chromium', headless: true }],\n\t\t\t},\n\t\t\tfileParallelism: false,\n\t\t},\n\t}\n}\n\nexport function appBrowser(...options: never[]): UserConfig {\n\tif (options.length > 0) throw new Error('Browser configuration overrides are not permitted')\n\treturn applicationBrowser(false)\n}\n{{showcaseFactory}}";
                   server: "export const appServer = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\tpublicDir: false,\n\t\t\tplugins: [outputBoundary('dist/app/server'), environmentBoundary('app/server')],\n\t\t\tbuild: {\n\t\t\t\temptyOutDir: true,\n\t\t\t\tlib: {\n\t\t\t\t\tentry: resolveWorkspacePath('app/server/main.ts'),\n\t\t\t\t\tformats: ['cjs'],\n\t\t\t\t\tfileName: () => 'main.cjs',\n\t\t\t\t},\n\t\t\t\toutDir: resolveWorkspacePath('dist/app/server'),\n\t\t\t\ttarget: 'node22',\n\t\t\t\trolldownOptions: { external: (id: string) => id.startsWith('node:') },\n\t\t\t},\n\t\t\ttest: {\n\t\t\t\tname: { label: 'app:server', color: 'green' },\n\t\t\t\tinclude: ['tests/app/server/**/*.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupServer.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
               }>;
               policy: "export const policy = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'policy', color: 'white' },\n\t\t\t\tinclude: ['tests/policy.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
@@ -1171,6 +1192,21 @@ export declare class Compiler implements CompilerInterface {
          */
         export declare const ENVIRONMENTS: readonly Environment[];
+        /**
+         * The vendored paths a target receives with its executable bit set, frozen.
+         *
+         * @remarks
+         * Declared rather than read from the staging host's filesystem, because that
+         * reading is not portable: Windows carries no executable bit, so a host staged
+         * there reports every file non-executable and every target receives hooks it
+         * cannot run. Declaring the set here makes one checkout stage one manifest on
+         * every host.
+         *
+         * Every entry is also a {@link HOST_PATHS} member or sits beneath one. A file
+         * that must run when a target invokes it belongs here the moment it is vendored.
+         */
+        export declare const EXECUTABLE_PATHS: readonly string[];
         /**
          * The development extra name syntax: any valid npm package name.
          *
@@ -1220,21 +1256,45 @@ export declare class Compiler implements CompilerInterface {
          * the audit showed is the one thing the destructive verb must never do. A
          * missing destination has no bytes to record. An aligned one may have gone
          * uncompared, which is what a birth-owned path always does, so it records
-         * bytes only where they were actually read.
+         * bytes only where they were actually read. Every planned finding carries its
+         * artifact's {@link Ownership}, so a consumer reads what scaffold claims at the
+         * path from the finding itself. A foreign finding has no planned artifact and
+         * therefore no ownership.
+         *
+         * Which combinations of `ownership`, `drift`, and `observed` a real audit
+         * produces is {@link inferDrift}'s law, not this type's. A birth-owned path is
+         * never compared and is always aligned, a presence-owned path compares existence
+         * only, and bytes are recorded only where they were read. This shape therefore
+         * admits a combination that law never produces — a birth-owned path reported
+         * stale is the plainest one — and it admits it deliberately: restating the
+         * comparison's case analysis here would be a second copy of it, able to disagree
+         * with the one that decides. What closes the gap is the writer: `repair` and
+         * `remove` re-derive every verdict themselves and refuse a caller's audit that
+         * does not match, so a verdict the comparison could not have reached is refused
+         * rather than acted on.
          */
         export declare type Finding = {
             readonly path: string;
             readonly group: Group;
-            readonly drift: 'stale' | 'foreign';
+            readonly ownership: Ownership;
+            readonly drift: 'stale';
             readonly observed: string;
         } | {
             readonly path: string;
             readonly group: Group;
+            readonly ownership?: never;
+            readonly drift: 'foreign';
+            readonly observed: string;
+        } | {
+            readonly path: string;
+            readonly group: Group;
+            readonly ownership: Ownership;
             readonly drift: 'missing';
             readonly observed?: never;
         } | {
             readonly path: string;
             readonly group: Group;
+            readonly ownership: Ownership;
             readonly drift: 'aligned';
             readonly observed?: string;
         };
@@ -1381,7 +1441,7 @@ export declare class Compiler implements CompilerInterface {
         /** The installed-package proof whose presence makes a workspace `integration`. */
         export declare const INTEGRATION_TEST_PATH = "tests/integration.test.ts";
-        /** Visible characters a portable path and a Markdown path cell both forbid. */
+        /** Visible characters a target-relative path and a Markdown path cell both forbid. */
         export declare const INVALID_PATH_CHARACTER_PATTERN: RegExp;
         /**
@@ -1408,7 +1468,8 @@ export declare class Compiler implements CompilerInterface {
          *
          * @remarks
          * An audit reaches the writer and the destructive verb, so it is guarded as
-         * strictly as the plan beside it.
+         * strictly as the plan beside it. Findings use the sum of the two producer
+         * bounds: one per planned artifact, then one per unplanned snapshot path.
          */
         export declare const isAudit: Guard<Audit>;
@@ -1552,7 +1613,13 @@ export declare class Compiler implements CompilerInterface {
          * @remarks
          * `observed` is required exactly where the mutation it precedes is held to it,
          * absent where the destination had no bytes to record, and optional where the
-         * comparison may not have been made.
+         * comparison may not have been made. Planned findings require `ownership`;
+         * foreign findings forbid it because no artifact was planned for their path.
+         *
+         * That is the whole claim. This guard proves the shape a reader may destructure
+         * and nothing about whether the verdict is one an audit could have reached: the
+         * correlation between `ownership`, `drift`, and `observed` belongs to
+         * {@link inferDrift}, and it is re-derived at the verb that acts on the finding.
          */
         export declare const isFinding: Guard<Finding>;
@@ -1617,19 +1684,20 @@ export declare class Compiler implements CompilerInterface {
         export declare const isOverride: Guard<Override>;
         /**
-         * Narrow a value to a portable target-relative path.
+         * Narrow a value to a logical target-relative path.
          *
          * @param value - The candidate path.
          * @returns `true` for a bounded relative path with no traversal, empty segment,
-         * control character, or non-portable visible character.
+         * control character, or reserved syntax character.
          *
          * @remarks
          * Every path this package reads or writes passes here, so one law covers a
          * planned artifact, an override target, an audit finding, a guide mirror, and a
          * snapshot key. Rejecting `..`, a leading `/`, and a backslash at the guard is
          * what stops a caller-supplied path from naming a destination outside the
-         * target, and rejecting the non-portable visible characters is what keeps a
-         * generated workspace checkable out on every supported filesystem.
+         * target. Host-location validation is a separate server boundary: this guard
+         * does not reject a device spelling, a trailing dot or space, or a segment that
+         * exceeds a host filesystem's byte ceiling.
          *
          * @example
          * ```ts
@@ -1763,6 +1831,20 @@ export declare class Compiler implements CompilerInterface {
          */
         export declare function manifestToName(manifest: string): string | undefined;
+        /**
+         * Test whether {@link inferDrift} could have produced a finding for an ownership.
+         *
+         * @param ownership - What scaffold claims at the planned path.
+         * @param finding - The audit verdict to test.
+         * @returns Whether the ownership and verdict are reachable through {@link inferDrift}.
+         *
+         * @remarks
+         * This predicate keeps the comparison law beside the reachability law it
+         * restates. A mutation uses it so a refusal can distinguish an impossible
+         * verdict from a target that genuinely moved after its audit.
+         */
+        export declare function matchesDriftReachability(ownership: Ownership, finding: Finding): boolean;
         /**
          * Test whether a declared engines floor is at or above the supported minimum.
          *
@@ -1861,6 +1943,9 @@ export declare class Compiler implements CompilerInterface {
         /** Maximum length of the hexadecimal string carrying one artifact's bytes. */
         export declare const MAX_ARTIFACT_HEX_LENGTH: number;
+        /** Maximum findings one audit can produce from a bounded plan and snapshot. */
+        export declare const MAX_AUDIT_FINDINGS: number;
         /** Maximum items accepted in one public collection. */
         export declare const MAX_COLLECTION_ITEMS = 1000;
@@ -2024,9 +2109,10 @@ export declare class Compiler implements CompilerInterface {
          *
          * @remarks
          * `content` replaces the rendered artifact at `path` and never partially
-         * merges it. An override that matches no planned artifact, that targets a
-         * host-origin artifact, or that targets the manifest is a blocking question
-         * rather than a silent no-op.
+         * merges it. Legality is measured against every artifact the blueprint drafts,
+         * before a compile narrows the returned groups. An override that matches none
+         * of those artifacts, that targets a host-origin artifact, or that targets the
+         * manifest is a blocking question rather than a silent no-op.
          */
         export declare interface Override {
             readonly path: string;
@@ -2051,10 +2137,9 @@ export declare class Compiler implements CompilerInterface {
          *
          * @example
          * ```ts
-         * import type { Artifact } from '@orkestrel/scaffold'
-         * import { overridesToQuestions } from '@orkestrel/scaffold'
+         * import { blueprintToConfigArtifacts, createBlueprint, overridesToQuestions } from '@orkestrel/scaffold'
          *
-         * declare const artifacts: readonly Artifact[]
+         * const artifacts = blueprintToConfigArtifacts(createBlueprint('router', { src: ['core'] }))
          *
          * overridesToQuestions([{ path: 'package.json', content: '{}\n' }], artifacts).length // 1
          * ```
@@ -2224,12 +2309,11 @@ export declare class Compiler implements CompilerInterface {
          *
          * @example
          * ```ts
-         * import type { Plan } from '@orkestrel/scaffold'
-         * import { planToFindings } from '@orkestrel/scaffold'
+         * import { createBlueprint, createCompiler, planToFindings } from '@orkestrel/scaffold'
          *
-         * declare const plan: Plan
+         * const { plan } = createCompiler().compile(createBlueprint('router', { src: ['core'] }))
          *
-         * planToFindings(plan, { 'AGENTS.md': '68690a' })
+         * plan === undefined ? [] : planToFindings(plan, { 'AGENTS.md': '68690a' })
          * ```
          */
         export declare function planToFindings(plan: Plan, current: Snapshot): readonly Finding[];
@@ -2255,12 +2339,11 @@ export declare class Compiler implements CompilerInterface {
          *
          * @example
          * ```ts
-         * import type { Plan } from '@orkestrel/scaffold'
-         * import { planToHash } from '@orkestrel/scaffold'
+         * import { createBlueprint, createCompiler, planToHash } from '@orkestrel/scaffold'
          *
-         * declare const plan: Plan
+         * const { plan } = createCompiler().compile(createBlueprint('router', { src: ['core'] }))
          *
-         * planToHash(plan)?.length // 16
+         * plan === undefined ? undefined : planToHash(plan)?.length // 16
          * ```
          */
         export declare function planToHash(plan: Plan): string | undefined;
@@ -2331,16 +2414,20 @@ export declare class Compiler implements CompilerInterface {
          * The one error this package throws, carrying the coded reason it was raised.
          *
          * @remarks
-         * A throw is reserved for a caller the package cannot serve: `INVALID` for
-         * off-contract input, `DESTROYED` for any call made after teardown, `TARGET`
-         * for a destination that is not what the caller's observation said it was,
-         * `WRITE` for a mutation that could not be completed, and `FETCH` for an
-         * upstream read that produced no answer the caller can be given.
-         *
-         * A refused blueprint is not one of these. The gate fails closed and returns
-         * the questions that closed it, and `BLOCKED` is the code those stage records
-         * carry, so a caller reads a refusal from the value it asked for rather than
-         * from a stack.
+         * Each code names one cause: `INVALID` for off-contract input, `DESTROYED` for
+         * any call made after teardown, `TARGET` for a destination that is not what the
+         * caller's observation said it was, `WRITE` for a mutation that could not be
+         * completed, `FETCH` for an upstream read that produced no answer the caller can
+         * be given, and `BLOCKED` for a refused blueprint.
+         *
+         * `BLOCKED` covers both refusals a blueprint can meet, because they are one fact
+         * — this blueprint will not be built — and the questions say which. The compiler
+         * answers its refusal rather than throwing it: the gate fails closed, returns the
+         * questions that closed it, and records `BLOCKED` on its stage, so a caller reads
+         * that refusal from the value it asked for. A verb that creates a workspace
+         * throws it, because it chose the shape and has nothing to hand back. A blocking
+         * question closed the gate; a non-blocking one is a shape this package can
+         * describe and declines to create.
          *
          * `context` carries whatever the raising site can say about the failure. It is
          * `unknown` because nothing narrows it usefully at the catch site; read it for