@orkestrel/scaffold 0.0.49 → 0.0.50

package/dist/host/guides/scaffold.md

@@ -59,27 +59,31 @@ Exported from `@orkestrel/scaffold`, and reachable from
 
 #### Interfaces
 
-| Name                | Kind      | Summary                                                                                 |
-| ------------------- | --------- | --------------------------------------------------------------------------------------- |
-| `AppDefinition`     | interface | The configuration and runtime-entry settings one private `app` environment contributes. |
-| `ArtifactBase`      | interface | The fields every planned file carries.                                                  |
-| `Audit`             | interface | The whole comparison of a plan against a target's current content.                      |
-| `Blueprint`         | interface | The closed, JSON-serializable workspace specification.                                  |
-| `CompileFailure`    | interface | The coded reason one compile stage failed.                                              |
-| `CompileRecord`     | interface | The input and output snapshot of one compile stage.                                     |
-| `CompilerInterface` | interface | The compilation contract: pure, synchronous, and host-independent.                      |
-| `CompilerOptions`   | interface | Options for the compiler.                                                               |
-| `ContentArtifact`   | interface | A text file produced by the template or computed compilation path.                      |
-| `Dependency`        | interface | One runtime `@orkestrel/*` dependency of a generated workspace.                         |
-| `HostArtifact`      | interface | A file byte-copied from the vendored data root, planned before its bytes are read.      |
-| `HydratedArtifact`  | interface | A vendored file whose exact bytes have been read, so its content can be compared.       |
-| `Override`          | interface | One artifact override.                                                                  |
-| `Plan`              | interface | The compiled, ordered artifact list and the selection it covers.                        |
-| `PlanSummary`       | interface | The tally of one plan by artifact origin.                                               |
-| `Question`          | interface | One validation issue raised against a blueprint or a plan.                              |
-| `Scaffolding`       | interface | The replayable outcome of one compile.                                                  |
-| `SrcDefinition`     | interface | The build and export settings one published `src` environment contributes.              |
-| `ViteMachinery`     | interface | Which host-specific pipelines a generated root Vite configuration carries.              |
+| Name                    | Kind      | Summary                                                                                 |
+| ----------------------- | --------- | --------------------------------------------------------------------------------------- |
+| `AppDefinition`         | interface | The configuration and runtime-entry settings one private `app` environment contributes. |
+| `ArtifactBase`          | interface | The fields every planned file carries.                                                  |
+| `Audit`                 | interface | The whole comparison of a plan against a target's current content.                      |
+| `Blueprint`             | interface | The closed, JSON-serializable workspace specification.                                  |
+| `CompileFailure`        | interface | The coded reason one compile stage failed.                                              |
+| `CompileRecord`         | interface | The input and output snapshot of one compile stage.                                     |
+| `CompilerInterface`     | interface | The compilation contract: pure, synchronous, and host-independent.                      |
+| `CompilerOptions`       | interface | Options for the compiler.                                                               |
+| `ContentArtifact`       | interface | A text file produced by the template or computed compilation path.                      |
+| `Dependency`            | interface | One runtime `@orkestrel/*` dependency of a generated workspace.                         |
+| `DependencyPinSet`      | interface | The runtime and development dependency sections a range writer may change.              |
+| `HostArtifact`          | interface | A file byte-copied from the vendored data root, planned before its bytes are read.      |
+| `HydratedArtifact`      | interface | A vendored file whose exact bytes have been read, so its content can be compared.       |
+| `ManifestDependencySet` | interface | The runtime, development, and peer declarations read from an existing manifest.         |
+| `ManifestRegionSet`     | interface | The manifest regions a writing operation may change.                                    |
+| `ManifestScript`        | interface | One manifest script a region-writing operation may replace.                             |
+| `Override`              | interface | One artifact override.                                                                  |
+| `Plan`                  | interface | The compiled, ordered artifact list and the selection it covers.                        |
+| `PlanSummary`           | interface | The tally of one plan by artifact origin.                                               |
+| `Question`              | interface | One validation issue raised against a blueprint or a plan.                              |
+| `Scaffolding`           | interface | The replayable outcome of one compile.                                                  |
+| `SrcDefinition`         | interface | The build and export settings one published `src` environment contributes.              |
+| `ViteMachinery`         | interface | Which host-specific pipelines a generated root Vite configuration carries.              |
 
 #### Constants
 
@@ -101,7 +105,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `DEFAULT_ENGINES`                 | const | The `engines.node` range a workspace starts with.                                                |
 | `DEFAULT_VERSION`                 | const | The version a workspace starts at.                                                               |
 | `DEPENDENCY_NAME_PATTERN`         | const | The runtime dependency name syntax: the `@orkestrel` scope and a bare name.                      |
-| `DISTRIBUTION_TEST_PATH`          | const | The packed-package proof whose presence makes a workspace `distribution`.                        |
+| `DISTRIBUTION_TEST_PATH`          | const | The generated packed-package proof every publishing workspace is planned at.                     |
 | `ENGINES_PATTERN`                 | const | The minimum-Node engine syntax a blueprint declares.                                             |
 | `ENVIRONMENTS`                    | const | The `Environment` values, frozen.                                                                |
 | `EXECUTABLE_PATHS`                | const | The vendored paths a target receives with its executable bit set, frozen.                        |
@@ -116,6 +120,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `HOST_INVENTORY_PATH`             | const | The repository-relative path where the committed vendored-file inventory is served.              |
 | `INTEGRATION_TEST_PATH`           | const | The cross-environment composition proof whose presence makes a workspace `integration`.          |
 | `INVALID_PATH_CHARACTER_PATTERN`  | const | Visible characters a target-relative path and a Markdown path cell both forbid.                  |
+| `MANIFEST_PATH`                   | const | The manifest path every compiler plan emits with birth ownership.                                |
 | `MAX_ARTIFACT_BYTES`              | const | Maximum bytes accepted for one artifact.                                                         |
 | `MAX_ARTIFACT_HEX_LENGTH`         | const | Maximum length of the hexadecimal string carrying one artifact's bytes.                          |
 | `MAX_AUDIT_FINDINGS`              | const | Maximum findings one audit can produce from a bounded plan and snapshot.                         |
@@ -126,6 +131,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `MAX_PATH_LENGTH`                 | const | Maximum length of one path, matching the longest a supported filesystem accepts.                 |
 | `MAX_RANGE_LENGTH`                | const | Maximum length of one declared package range.                                                    |
 | `MAX_REGISTRY_BYTES`              | const | Maximum decoded bytes accepted from one registry response.                                       |
+| `MAX_SCRIPT_LENGTH`               | const | Maximum length of one manifest script name or command.                                           |
 | `MAX_TOTAL_ARTIFACT_BYTES`        | const | Maximum bytes retained across one whole plan or audit.                                           |
 | `MAX_TOTAL_REGISTRY_BYTES`        | const | Maximum decoded bytes accepted across one registry-reading call.                                 |
 | `MINIMUM_NODE_VERSION`            | const | The oldest Node version the generated toolchain supports.                                        |
@@ -134,6 +140,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `ORCHESTRATION_PATH_PREFIXES`     | const | The path prefixes whose contents instruct or wire an agent, frozen.                              |
 | `ORKESTREL_RANGE_PATTERN`         | const | The exact caret-pinned pre-1.0 range accepted for an `@orkestrel/*` runtime dependency.          |
 | `PRINT_WIDTH`                     | const | Columns one emitted line may occupy, matching `printWidth` in `.oxfmtrc.json`.                   |
+| `RELEASE_PROOF_COMMAND`           | const | The `prepublishOnly` row that runs the packed-package proof against a real registry.             |
 | `SERVICE_SCRIPT_PATH`             | const | The provisioner skeleton a workspace with declared service vendors is given once.                |
 | `SERVICE_SETUP_PATH`              | const | The live-service readiness module whose presence makes a workspace `service`.                    |
 | `SERVICE_TEST_INCLUDE`            | const | The include the live-service project covers, which is a directory rather than one proof.         |
@@ -164,6 +171,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `isGroup`           | const    | Narrow a value to one `Group` a plan selects over.                               |
 | `isGroups`          | const    | Narrow a value to a bounded group selection.                                     |
 | `isHex`             | const    | Narrow a value to exact lowercase hexadecimal bytes within one artifact's limit. |
+| `isManifestScript`  | const    | Narrow a value to a `ManifestScript`.                                            |
 | `isMirror`          | const    | Narrow a value to a `Mirror`.                                                    |
 | `isOverride`        | const    | Narrow a value to an `Override`.                                                 |
 | `isPath`            | function | Narrow a value to a logical target-relative path.                                |
@@ -198,7 +206,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `inferDrift`                | function | Infer how one target path compares to the artifact planned for it.            |
 | `inferGroup`                | function | Infer the `Group` a path belongs to.                                          |
 | `isDeferredPath`            | function | Test whether another surface owns the vendored bytes at a path.               |
-| `manifestToDependencies`    | function | Project a package manifest's text to the `@orkestrel/*` packages it declares. |
+| `manifestToDependencies`    | function | Project a manifest's `@orkestrel/*` declarations into separate section lists. |
 | `manifestToName`            | function | Project a package manifest's text to its own name.                            |
 | `matchesDriftReachability`  | function | Test whether `inferDrift` could have produced a finding for an ownership.     |
 | `matchesEngines`            | function | Test whether a declared engines floor is at or above the supported minimum.   |
@@ -232,14 +240,16 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `blueprintToScripts`                | function | Project a blueprint into the scripts its manifest declares.                     |
 | `blueprintToSourceArtifacts`        | function | Compile every artifact in the `source` group.                                   |
 | `blueprintToTestArtifacts`          | function | Compile every artifact in the `tests` group that is not vendored from the host. |
+| `blueprintToWritableScripts`        | function | Project a blueprint into the manifest scripts a region write may replace.       |
 | `dependenciesToQuestions`           | function | Measure one declared package list against the name and range syntax it accepts. |
 | `nameToHostArtifacts`               | function | Compile the vendored host artifacts a named workspace plans.                    |
 | `overridesToQuestions`              | function | Measure a blueprint's overrides against the artifacts drafted for it.           |
 | `pathToCondition`                   | function | Build one `exports` condition block for a built environment.                    |
 | `planToFindings`                    | function | Compare a plan against a target's current content.                              |
 | `planToHash`                        | function | Compute a plan's content identity.                                              |
-| `replaceManifestRanges`             | function | Replace declared dependency ranges in package manifest text.                    |
-| `replacePlanRanges`                 | function | Replace dependency ranges in a plan's manifest and recompute its identity.      |
+| `replaceManifestRanges`             | function | Replace runtime and development ranges without reading or writing peer fields.  |
+| `replaceManifestScripts`            | function | Replace named script values, refusing a value the region does not accept.       |
+| `replacePlanRanges`                 | function | Replace writable ranges in a plan's manifest and recompute its identity.        |
 | `srcToEntry`                        | function | Project a published selection into the manifest's entry fields.                 |
 | `srcToExports`                      | function | Project a published selection into the manifest's `exports` map.                |
 | `srcToRoot`                         | function | Select the single published environment a package root points at.               |
@@ -321,6 +331,7 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
 | `isHostManifest`        | const    | Narrow a value to one `HostManifest`.                                              |
 | `isInventory`           | function | Narrow a value to a working-tree inventory within the limit one target may report. |
 | `isManifestEntry`       | const    | Narrow a value to one `ManifestEntry`.                                             |
+| `isManifestRegionSet`   | const    | Narrow a value to one `ManifestRegionSet`.                                         |
 | `isMaterializerHooks`   | const    | Narrow a value to the materializer's initial listener record.                      |
 | `isMaterializerOptions` | const    | Narrow a value to `MaterializerOptions`.                                           |
 | `isMirrors`             | const    | Narrow a value to a bounded list of fetched guide mirrors.                         |
@@ -400,7 +411,7 @@ no interface and is documented directly.
 | `repair`      | Write a plan into an existing target, guided by an audit of it.                  |
 | `mirror`      | Write fetched dependency guides to their local mirrors.                          |
 | `catalog`     | Rewrite the marker-bounded package table in the target's catalog agent file.     |
-| `declare`     | Rewrite the `@orkestrel/*` range set in the target's manifest.                   |
+| `declare`     | Rewrite the manifest regions the caller names: the ranges and the scripts.       |
 | `remove`      | Re-derive and delete the tracked files the plan does not own.                    |
 | `destroy`     | Tear the materializer down. Every later call throws, and teardown is idempotent. |
 
@@ -430,13 +441,13 @@ no interface and is documented directly.
 Authority is the verb's: every verb except `audit` writes when it is typed, and no
 option grants a write.
 
-| Verb        | Writes                                                                          |
-| ----------- | ------------------------------------------------------------------------------- |
-| `new`       | A whole workspace, into a target that holds nothing the plan would collide with |
-| `audit`     | Nothing                                                                         |
-| `repair`    | Each planned path the target is missing or has let drift, and the ranges        |
-| `catalog`   | The package table, the guide mirrors, and the ranges                            |
-| `overwrite` | Everything `repair` and `catalog` write, plus deletions                         |
+| Verb        | Writes                                                                                     |
+| ----------- | ------------------------------------------------------------------------------------------ |
+| `new`       | A whole workspace, into a target that holds nothing the plan would collide with            |
+| `audit`     | Nothing                                                                                    |
+| `repair`    | Each planned path the target is missing or has let drift, and the range and script regions |
+| `catalog`   | The package table, the guide mirrors, and the range region                                 |
+| `overwrite` | Everything `repair` and `catalog` write, plus deletions                                    |
 
 ### Baselines
 
@@ -517,14 +528,17 @@ answers a read and grant no verb write authority that it did not already have.
 
 `new --bin` creates the executable entry, its test, and its scoped Vite and TypeScript wrappers. The
 other structural facts do not need creation flags. Add a root `tests/setup*.test.ts` proof for
-`setup`, `tests/guides.test.ts` for `guides`,
-`tests/distribution.test.ts` for `distribution`, `tests/integration.test.ts` for `integration`,
+`setup`, `tests/guides.test.ts` for `guides`, `tests/integration.test.ts` for `integration`,
 `tests/conformance.test.ts` for `conformance`, `tests/setupService.ts` for `service`,
 `tests/setupGlobal.ts` for `global`, and `configs/app/vite.showcase.config.ts` for `showcase`;
 reading verbs detect each exact-case file and register its fixed machinery. Add `scripts/service.sh`
 for `vendors`. Reading verbs preserve and protect that birth-owned script, but do not infer its
 vendor list from edited text.
 
+`distribution` is not on that list. Publishing at least one `src` environment is its whole
+condition, and scaffold writes `tests/distribution.test.ts` itself rather than waiting for you to.
+Limits states what makes that one proof generable when the others are not.
+
 ### Reading a target
 
 `audit`, `repair`, `catalog`, and `overwrite` derive the blueprint from the target itself. The name
@@ -532,11 +546,11 @@ and the declared `@orkestrel/*` packages come from `package.json`. The environme
 from the directories the target actually ships, because a directory is the fact and a declaration
 beside it could disagree. The remaining facts come from exact-case files: `src/bin/main.ts` selects
 `bin`, each root `tests/setup*.test.ts` match selects `setup`, `tests/guides.test.ts` selects
-`guides`, `tests/distribution.test.ts` selects `distribution`,
-`tests/integration.test.ts` selects `integration`, `tests/conformance.test.ts` selects
+`guides`, `tests/integration.test.ts` selects `integration`, `tests/conformance.test.ts` selects
 `conformance`, `tests/setupService.ts` selects `service`, `tests/setupGlobal.ts` selects `global`,
 and `configs/app/vite.showcase.config.ts` selects `showcase`. A containing directory does not select
-the fact by itself.
+the fact by itself. `tests/distribution.test.ts` selects nothing: the published `src` axis the
+target ships already decides the `distribution` project, and the file is planned from that.
 
 `vendors` is not reconstructed. Its only artifact, `scripts/service.sh`, is birth-owned, so edited
 script text is not a trustworthy declaration of a vendor list. A present script remains in the
@@ -568,16 +582,34 @@ question instead of licensing a write. The classifier is deliberately bounded to
 text that names `vitest`; an external wrapper whose name does not identify its runner supplies no
 static Vitest fact to infer.
 
-`audit` still completes the comparison and reports one non-blocking `projects` question. For a
+`audit` still completes the comparison and reports one non-blocking `projects` question when its
+selection includes `configs`. A scoped audit that excludes `configs` omits that question. For a
 literal absent project, its advisory tells the developer to register the project or remove the
 script. For a planned project absent from the gate chains, the advisory checks the direct
 `test:<project>` script. When the script is absent, the advisory gives the exact line to add to
 `package.json`. When the script is declared but ungated, the advisory names the script and the gate
-chain that must invoke it, without repeating a script line. `repair` and `overwrite` refuse either
-mismatch and do not write the manifest or configuration. Their absent-project refusal tells the
-developer to remove the script or not use scaffold writing verbs for a workspace that needs custom
-Vitest projects. It does not recommend editing the content-owned configuration that the refusing
-verb would restore. An advisory alone does not make an aligned target drift.
+chain that must invoke it, without repeating a script line. When `configs` is selected, `repair` and
+`overwrite` refuse either mismatch before writing. Their refusal names the `configs` group, the
+manifest and planned `vite.config.ts` conflict, and the option to exclude `configs` from
+`--groups`. A selection that excludes `configs` proceeds. An advisory alone does not make an aligned
+target drift.
+
+Scaffold writes one part of the manifest rather than advising on it: the script region a publishing
+workspace needs for the generated distribution proof. `repair` and `overwrite` write
+`test:distribution` and `prepublishOnly` there. A declared value is overwritten only when it is
+already the value being written, or, for `prepublishOnly`, the one predecessor the region accepts —
+the same gate chain without the release row. The overwrite happens in place, so every byte outside
+the replaced ranges survives, and a description, a keyword, a key order, and a script the workspace
+added are untouched. A script the manifest does not declare is appended after the last declared one,
+copying that section's indentation. `catalog` writes no script region; it names the ranges alone.
+
+A value matching neither is a chain the workspace author wrote. The region is then refused whole,
+without a byte moving, and the range region is still written. The `projects` advisory reads the
+manifest as a write would leave it, so a region scaffold writes for itself raises no question, while
+a refused region leaves the target's own text standing and the advisory reports whichever half is
+outstanding: the exact `test:distribution` line to paste, or the gate chain that must invoke a
+script the manifest already declares. The refusal covers the region rather than one script, so a
+manifest never holds one written value beside one refused one.
 
 The same plan-reading verbs compare the tooling set the derived blueprint plans against
 `dependencies` and `devDependencies` together. A missing planned package produces one non-blocking
@@ -585,9 +617,42 @@ The same plan-reading verbs compare the tooling set the derived blueprint plans
 order. The comparison measures membership: a workspace-owned extra is outside it, a planned tool may
 live in either section, and how current a declared range is belongs to the registry evidence
 Dependency floors describes rather than to this question. A present section that is not an object
-produces a question instead of a crash. `audit` reports the question without changing its exit
-semantics. `repair` and `overwrite` refuse before writing configuration, and no verb edits the
-birth-owned `package.json`.
+produces a question instead of a crash. This question belongs to `configs` and `tests`. `audit`
+reports it only when its selection includes either group, without changing its exit semantics.
+`repair` and `overwrite` refuse before writing a selected `configs` or `tests` group. A selection
+that excludes those groups proceeds, and no verb adds the declaration for you: `package.json` is
+birth-owned, and the range and script regions are the only parts of it a verb rewrites.
+
+`audit` reports one further non-blocking question, on the `setup` field, and it alone reports it.
+The question fires when the target carries a filled root `tests/setup*.ts` module that is neither a
+proof itself nor one of the vendored modules every target receives, while no proof of the same stem
+covers it. A module counts as filled when its text differs from the seed this blueprint plans at
+that same path.
+
+The comparison reads the module and the seed trimmed, so surrounding whitespace decides nothing: a
+trailing newline is not authorship, and a module holding whitespace alone reads as empty rather than
+as filled. It is seed-relative rather than a test for emptiness, because the seeds differ by path:
+`tests/setup.ts` is seeded with the empty string and `tests/setupGlobal.ts` is seeded with a `setup`
+function body. A test for emptiness therefore raises the question against a freshly materialized
+workspace. Holding each module to the seed the same blueprint plans at its own path reports what a
+maintainer wrote rather than what scaffold seeded.
+
+That reading carries a release-skew limit. A seeded setup module is birth-owned, so `repair` reports
+it aligned and never rewrites it. A target keeps the seed of the release that materialized it. When
+a release moves a planned seed, scaffold raises the question on every target materialized before it,
+against a module scaffold wrote and no maintainer touched.
+`tests/setupGlobal.ts` is the module that can meet it, because it is the one seeded with more than
+the empty string. A maintainer meeting that question closes it by writing the proof it asks for, or
+by taking the seed the installed release plans.
+
+Coverage is read per module: `tests/<name>.ts` is covered by `tests/<name>.test.ts` and by nothing
+else, which is the pairing the vendored policy proof resolves. Writing one proof retires that module
+and leaves every other uncovered module named, and the message pairs each module it names with the
+proof that module wants. The question belongs to the `tests` group, so a scoped audit that excludes
+`tests` omits it. Scaffold does not write the proof it asks for, and no writing verb raises the
+question: a writing verb refuses the advisories it reports, and refusing `repair` over this one
+would block every write on a gap no write can close. Run across a fleet, the question is the list of
+packages carrying a filled setup module that no proof covers.
 
 ### Exit codes
 
@@ -678,10 +743,10 @@ because the shape is chosen once and read afterwards: `new` refuses the advisory
 `repair` need the plan to describe and restore a target that already has that shape. A library
 caller creating a workspace holds the same refusal, and the Compile section below states it.
 
-`bin`, `setup`, `guides`, `distribution`, `integration`, `conformance`, `service`, `vendors`,
-`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.
+`bin`, `setup`, `guides`, `integration`, `conformance`, `service`, `vendors`, `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.
 
 `setup` registers every root `tests/setup*.test.ts` proof in one Node project that loads
 `tests/setup.ts`. A nested or wrong-case match does not set the fact. The generated manifest emits
@@ -702,9 +767,12 @@ Adding a structural proof is therefore these steps, in order: write the file; de
 regenerates the root configuration and registers the project. `audit` reports whichever piece is
 still outstanding at each step.
 
-`distribution` projects only when the workspace also publishes at least one `src` environment. It
-packs and installs the published artifact, so without that axis there is nothing to pack, and the
-declared flag alone adds no project, no `test:distribution` script, and no gate entry.
+`distribution` is not a field at all. A published `src` environment is its whole condition, read
+from the `src` axis the blueprint already carries. The proof packs and installs the published
+artifact, so a workspace publishing none has nothing for it to read and gets no project, no
+`test:distribution` script, and no gate entry. A workspace publishing any gets the project, the
+script, the `prepublishOnly` entry, and `tests/distribution.test.ts` itself. Limits states why this
+is the one proof scaffold generates from the workspace's own shape.
 
 `service` says the workspace runs a live-service Vitest project over `tests/service`, and it alone
 registers that project, its `test:service` script, and the `tests/setupService.ts` readiness module
@@ -786,7 +854,8 @@ place, and the caller that picked the shape is the one holding it.
 Off-contract input is different. A value that is not the exact shape raises `ScaffoldError` coded
 `INVALID`, because it is not a question anyone can answer. Each entry point snapshots the caller's
 value first and then guards the snapshot, so a property backed by an accessor is refused rather than
-read.
+read. `isPlan` refuses an artifact at `package.json` unless it carries `birth` ownership, because a
+plan claiming `content` or `presence` there contradicts the compiler-produced plan.
 
 Overrides replace a drafted artifact's content whole. The gate checks each override against the
 blueprint's full draft before a group selection narrows the returned plan, so an override outside a
@@ -828,10 +897,23 @@ content is produced. `Ownership` says what scaffold claims at the path.
 
 Presence ownership has separate mechanisms, and a reader needs to know which applies:
 
-| Mechanism       | Paths                                             | Bytes belong to       | Cost                                                    |
-| --------------- | ------------------------------------------------- | --------------------- | ------------------------------------------------------- |
-| Verb-owned      | `CATALOG_AGENT_PATH` and dependency guide mirrors | `catalog` or `mirror` | The owning verb is the only route for a later update.   |
-| Workspace-owned | `WORKSPACE_OWNED_PATHS`, which holds `.gitignore` | The target workspace  | Present bytes receive no later canonical ignore update. |
+| Mechanism       | Paths                                             | Bytes belong to                              | Cost                                                        |
+| --------------- | ------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------- |
+| Verb-owned      | `CATALOG_AGENT_PATH` and dependency guide mirrors | `catalog` or `mirror`                        | The owning verb is the only route for a later update.       |
+| Workspace-owned | `WORKSPACE_OWNED_PATHS`, which holds `.gitignore` | The target workspace                         | Present bytes receive no later canonical ignore update.     |
+| Plan-owned      | `DISTRIBUTION_TEST_PATH`                          | The plan, until the workspace writes its own | A deleted file is restored from the plan on the next write. |
+| Unhydrated      | Every vendored path a core-compiled plan carries  | Scaffold, after a hydrating face reads them  | Hydration restores the byte claim the core plan omits.      |
+
+The unhydrated row is the one a core-only caller meets most, and reading it as a claim about the
+path is the mistake it invites. `Compiler` runs in the pure core face, which cannot read the
+vendored data root, so every host artifact it plans carries `presence`: a claim over bytes nobody
+has read is a claim no comparison could check. A `src: ['core']` plan therefore reports `presence`
+for `AGENTS.md`, `.claude/settings.json`, `tests/policy.test.ts`, and every other vendored path, and
+a consumer concluding from that reading that scaffold never replaces those bytes is wrong.
+`Materializer` hydrates the plan before it audits or writes: hydration reads the vendored root and
+turns each path scaffold owns the bytes of into a content-owned artifact, leaving `presence` on the
+workspace-owned paths and the mirror pointers the preceding rows name. What a verb claims at a
+vendored path is the hydrated ownership, and `HostArtifact` carries the same narrowing on the type.
 
 Birth ownership is what makes a generated workspace the consumer's. `materialize` writes a
 birth-owned path into a vacant target. A later `repair` or `overwrite` call treats that path as
@@ -842,16 +924,29 @@ You own `tests/setup.ts`, the selected `tests/setupBrowser.ts`, `tests/setupServ
 `tests/setupService.ts`, and `tests/setupGlobal.ts` modules, each root `tests/setup*.test.ts` proof,
 the selected environment entry tests under `tests/src` and `tests/app`, the
 `tests/src/bin/main.test.ts` file, and the `tests/integration.test.ts` seed. Scaffold writes those
-planned files only during materialize and leaves later edits or deletions alone. You also own the `tests/guides.test.ts`,
-`tests/distribution.test.ts`, `tests/conformance.test.ts`, and `tests/service/**/*.test.ts` proof
-files that you add to select their projects. Scaffold content-owns `tests/setupPolicy.ts`,
+planned files only during materialize and leaves later edits or deletions alone. You also own the
+`tests/guides.test.ts`, `tests/conformance.test.ts`, and `tests/service/**/*.test.ts` proof files,
+each of which selects its project by being written. Scaffold content-owns `tests/setupPolicy.ts`,
 `tests/policy.test.ts`, and `tests/config.test.ts`; `repair` and `overwrite` restore those files when
 their bytes drift or the files are missing.
 
-Content ownership does not preserve an arbitrary custom Vitest project. Fixed optional proofs are
-selected by their defining paths, as `guides`, `distribution`, `integration`, `conformance`, and
-`service` are. A workspace that needs other local configuration must keep those edits outside a
-content-owned file; `repair` restores that file to the canonical project set.
+`tests/distribution.test.ts` is the one proof scaffold generates, and the one test artifact it
+claims by presence. Generation is the line, not writing: scaffold writes the vendored
+`tests/policy.test.ts` and `tests/config.test.ts` proofs too, and restores them, but those are the
+shared file set's own bytes copied into the target. The distribution proof is derived from the
+workspace's own shape instead, which is why it is the one proof a generated file can be. A
+publishing workspace missing that file reports `missing` drift, and `repair` or `overwrite` writes
+the generated proof there. A workspace that replaced the generated proof with a better one keeps its
+own bytes exactly: presence compares existence, so no verb reads what is already at the path, none
+replaces it, and none ever reports it stale. Deleting the file is how you ask for the generated
+proof back; editing it is how you keep your own. Limits states what makes this proof generable when
+the others are not.
+
+Content ownership does not preserve an arbitrary custom Vitest project. The optional proof projects
+are fixed: `guides`, `integration`, `conformance`, and `service` are selected by their defining
+paths, and `distribution` by a published `src` environment. A workspace that needs other local
+configuration must keep those edits outside a content-owned file; `repair` restores that file to the
+canonical project set.
 
 An audit reports one `Finding` per planned path, followed by any foreign path beneath the groups
 the plan covers. Every planned finding carries its artifact's `ownership`. A foreign finding has
@@ -938,12 +1033,18 @@ lookup verdict records why the registry row could not enter a layer.
 
 ## Dependency floors
 
-Every scaffold-owned range from its dependency tables is a floor: a caret over a whole
+Every scaffold-owned runtime or development range is a floor: a caret over a whole
 `major.minor.patch` version. The triple is the newest release the registry served when that floor
 was last raised, so a workspace generated with no network still receives the latest floor scaffold
-knew rather than a bare `major.0.0`. Caller extras and peers pass through unchanged. Extras follow
-`EXTRA_RANGE_PATTERN`; fleet peers follow `ORKESTREL_RANGE_PATTERN`; foreign peers follow
-`FLOOR_RANGE_PATTERN`.
+knew rather than a bare `major.0.0`. A `Blueprint.peers` row is written during creation into a
+vacant target. After creation, peer declarations and `peerDependenciesMeta` are caller-owned:
+`audit`, `repair`, `catalog`, and `overwrite` do not invent, rewrite, insert, or remove them. Caller
+extras also pass through unchanged. Extras follow `EXTRA_RANGE_PATTERN`; fleet peers follow
+`ORKESTREL_RANGE_PATTERN`; foreign peers follow `FLOOR_RANGE_PATTERN`.
+
+The distribution project packs a caller-owned peer beside a co-peer witness that requires an exact
+version. The real npm resolver accepts the preserved range. Its narrowed-range control reports
+`ERESOLVE`.
 
 The floors live in scaffold's own `package.json`. `BASE_DEV_DEPENDENCIES` and the tables beside it
 derive each row scaffold installs from that manifest, and the self-pin from its `version` field, so
@@ -1107,6 +1208,12 @@ except the manifest.
   integration selection also emits a birth-owned `tests/integration.test.ts` seed that imports each
   selected public barrel and records its initial empty exports for the consumer to replace with an
   observable cross-environment flow.
+- One template artifact, `tests/distribution.test.ts`, for a workspace publishing any `src`
+  environment. It is the packed-package proof, and it is claimed by presence rather than birth, so a
+  workspace that replaces it keeps its replacement. A published browser environment adds the
+  real-browser stage to it: the stage bundles the installed package with the workspace's own
+  `configs/browsers.ts` resolution, serves the bundle over a loopback server, and drives it in
+  Playwright Chromium.
 - One template artifact each for `README.md` and `guides/README.md`.
 - One host artifact per vendored path the workspace selects. A vendored directory is one planned
   path that expands into the files the data root stores beneath it.
@@ -1317,32 +1424,157 @@ nothing. This is deliberate: a generated sample entity is repeatedly mistaken fo
 implementation. What a consumer does first is write the module's `types.ts`, then the
 implementation that conforms to it, then export both from the barrel — the order `AGENTS.md` fixes.
 
-**A selected distribution, conformance, or live-service proof is registered, but none is written for
-you.** Scaffold registers `conformance` and `service` when their structural facts are set, and
-registers `distribution` only when the workspace also publishes `src`. In a publishing workspace,
-`distribution` and `service` run from `prepublishOnly` and `conformance` stays in `test`. In a
-`private: true` workspace, `distribution` is absent, `service` runs from `test`, and there is no
-`prepublishOnly` at all. Scaffold emits no proof into any registered project, because each names
-something only the package knows: the behavior its own packed artifact must hold after it is
-installed, the official artifact a conformance check measures against, and the service a live proof
-drives. A generated placeholder would read as a proof while measuring nothing, so the file a
-consumer writes is the file that selects the project.
-
-A distribution proof carries one contract scaffold does enforce from the outside. The generated
-`prepublishOnly` invokes it as `npm run test:distribution -- --mode release`, and a proof that reads
-`import.meta.env.MODE === 'release'` must **fail** on an unreachable registry rather than skip. An
-ordinary local run may skip that case, because a developer offline is not a defect; a release run
-may not, because skipping there passes the publish gate without ever proving the artifact installs.
-Scaffold writes no proof, so honouring the flag is the consumer's, and a proof that ignores it
-reports green on exactly the runs that matter.
-
-The consequence is one empty-project case per registered proof. A publishing blueprint carrying
-`distribution` with no `tests/distribution.test.ts`, or any blueprint carrying `conformance` with no
-`tests/conformance.test.ts`, registers a project whose include resolves to nothing, and Vitest exits
-non-zero on it. A blueprint carrying `service` gets `tests/setupService.ts` — the root configuration
-names that module by path, so an absent one fails the project's load rather than its run — and still
-no suite beneath `tests/service`, so `test:service` reports no test files until the consumer writes
-the first one. Every case is visible the first time the script runs, which is why none is silent.
+**Scaffold generates the distribution proof and refuses to generate every other one.** The subject
+is what separates them, and it is the whole rule. Generating a file is not the same as writing one:
+scaffold also writes `tests/policy.test.ts` and `tests/config.test.ts` into a target, byte for byte
+from the shared file set, and the distribution proof is the one it derives from the workspace it is
+writing into.
+
+A distribution proof's every assertion derives from the artifact the workspace installs: the
+`exports` map the packed tarball declares, the built declarations beside it, and the module objects
+a Node import, a CommonJS require, and a real browser hand back from that installed tree. Nothing
+there has to be named, so one generated file measures every publishing workspace, and it stays true
+as that workspace's published surface moves.
+
+A guide, conformance, live-service, or setup proof asserts something scaffold cannot read: the API a
+guide fence claims, the official runner a conformance check measures against, the service a live
+proof drives, and what a setup module does. That subject is what no generated file can reach, and
+the claim here is about the subject rather than about every property those files have. A structural
+property of the same files can be derivable — whether each root `tests/setup*.ts` module is
+reachable from the root configuration is one — and a file asserting it would still leave the
+module's behavior unmeasured. A generated file there would read as a proof while measuring nothing,
+which is worse than an absent one. So the file a consumer writes is what selects each of those
+projects, and `tests/distribution.test.ts` is the one proof scaffold generates for you.
+
+Registration follows the same split. Scaffold registers `conformance` and `service` when their
+structural facts are set, and registers `distribution` whenever the workspace publishes at least one
+`src` environment. In a publishing workspace, `distribution` and `service` run from `prepublishOnly`
+and `conformance` stays in `test`. In a `private: true` workspace, `distribution` is absent,
+`service` runs from `test`, and there is no `prepublishOnly` at all. One gap the project set cannot
+show, `audit` reports directly: a filled `tests/setup*.ts` module that no `tests/setup*.test.ts`
+proof covers raises the non-blocking `setup` question, which names the modules and the proof to add.
+Scaffold generates nothing there either, because what that proof asserts is those modules' own
+behavior, which only the workspace that wrote them can state.
+
+The generated proof partitions the installed `exports` map rather than sampling it. Every published
+subpath lands in exactly one of driven, undeclared, or excluded, and a totality assertion holds that
+partition against the map's own subpath list, so a subpath the proof classifies into none of them
+reddens instead of disappearing. Another assertion beside it names every driven subpath whose entry
+resolves no Node target and no browser target: each drive retires itself for such a subpath, so
+membership of the partition alone would leave one measured by nothing. Together they hold that every
+published subpath is driven, or is named where the proof cannot drive it.
+
+A subpath is driven when its entry resolves a declaration, and each measurement resolves that entry
+under the conditions of the driver taking it rather than under one shared set. The Node ESM runtime
+resolves `node-addons`, `node`, `import`, and `module-sync`; the Node CommonJS runtime resolves
+`node-addons`, `node`, `require`, and `module-sync`; Vite's production client build resolves
+`module`, `browser`, `production`, and `import`. A subpath whose Vite resolution lands under
+`dist/src/browser/` is driven in a real browser and the Node drives retire for it; every other
+subpath is imported where the Node ESM set resolves a target and required where the Node CommonJS
+set resolves one.
+
+The CommonJS compile probe resolves the declaration under `types`, `node`, and `require`, then reads
+that declaration's format. TypeScript accepts an existing declaration target directly. Otherwise it
+substitutes beside the resolved JavaScript target: `.cjs` maps to `.d.cts`, `.mjs` maps to `.d.mts`,
+and `.js` maps to `.d.ts`. A missing target under `types` leaves that condition unresolved, so the
+walk continues through the remaining conditions or fallback members. A `.d.cts` declaration admits
+the subpath. A `.d.mts` declaration refuses it. A `.d.ts` declaration takes the nearest enclosing
+physical `package.json` file from its own directory: a `"type": "module"` field refuses, while
+`"type": "commonjs"`, an omitted field, or a manifest that cannot supply a readable field admits.
+A directory named `package.json` starts no scope, so the walk continues outward. The runtime target
+does not decide compile membership. The runtime drive separately resolves under `node-addons`,
+`node`, `require`, and `module-sync`, then loads the subpath whatever declaration format the compile
+probe found. An invalid non-list target beside a valid CommonJS declaration therefore reaches Node's
+`ERR_INVALID_PACKAGE_TARGET` failure instead of being dropped during classification.
+
+The mirror assertion reports a CommonJS typing defect only when the entry's own mapping declares an
+explicit `require` condition, the Node `require` resolver reaches the entry, and the selected
+declaration refuses a CommonJS consumer. A `default` branch that merely resolves under the require
+condition set makes no CommonJS claim.
+
+Each drive compares against the declaration its own consumer reads, resolved under the conditions
+TypeScript applies for that resolution and importing format: `types` first and the format's own
+condition after it, with `node` between them for the `node16` and `nodenext` resolutions and left
+out for `bundler`, which is the set the browser drive compares against. The import declaration and
+the require declaration are resolved independently and kept separately on the entry, so a dual
+subpath is compiled against the declaration each consumer format reads rather than against whichever
+one answered first. That is what drives a `require`-only subpath declaring its types inside
+`require`, and what admits a conventional subpath that publishes no `types` condition but ships the
+adjacent declaration TypeScript substitutes from its runtime target.
+
+A subpath is undeclared when it resolves no declaration and names a runtime target, which is a
+defect, because a consumer importing it compiles against nothing under `node16`. A target is a
+runtime target when its own file name carries no extension at all, or carries `.js`, `.mjs`,
+`.cjs`, or `.node`. An extensionless target loads, because `require` reads such a file through its
+JavaScript handler; a `.wasm` target does not, because it carries an extension that is not a
+JavaScript one. A
+`.node` target is named beside them because `require` loads a native addon through its own handler
+rather than the JavaScript one, and the addon publishes names to whatever loads it. The test is the
+extension the name carries rather than a denylist of asset extensions. Reading the
+file name rather than the whole path is load-bearing: `./dist/bundle.js/feature` and
+`./dist/v1.2/index` are modules, and reading the path gets each of them wrong. What the rule
+excludes is stated where the proof is emitted: an extensionless file published for a reader, such as
+a `LICENSE` at a subpath, reports undeclared until it is given an extension or a declaration. That
+is the safe direction: the proof names a subpath it cannot vouch for rather than passing one it
+never measured.
+
+A subpath is excluded when it resolves no declaration and names no runtime target: the
+`./package.json` pointer, a published stylesheet, and a WebAssembly binary are read rather than
+imported, and the proof names them where it excludes them.
+
+Classification reads every target the entry names under every condition, and the members of a
+fallback list with them: Node reads an array in an exports entry as a list of fallbacks, and a
+reader taking a later member takes a file the installed tree still owes. Node's package-target rules
+apply inside that list, so a member naming a path outside the package or carrying a `.`, `..`, or
+`node_modules` segment is skipped rather than resolved or collected: Node falls through to the next
+member, and no reader can take the one it passed. A standalone target Node rejects the same way is
+still read and reported, because Node throws on one rather than falling through to anything. So a
+`require`-only CommonJS subpath carrying no declaration reddens too, and a `.d.ts` or `.d.cts`
+target never satisfies the runtime-target test, so a types-only condition cannot stand in for a
+missing declaration.
+
+A `./*` subpath pattern is read as an ordinary subpath, with no expansion of the `*`, so a pattern
+naming a runtime target reddens rather than landing in excluded. That is deliberate: excluding the
+pattern would account for a whole family of published subpaths and measure none of them, which is
+the silence this partition exists to close. Measuring the family means expanding the pattern against
+the installed tree and driving each match, which this proof does not do. A maintainer meeting that
+red is reading the honest answer — the proof does not measure that family — rather than a defect in
+the proof.
+
+The proof generated for a workspace publishing no browser face asserts that no browser face exists.
+That variant drives a Node import and a Node require and carries no browser branch, because the
+branch follows a published browser face on the `src` axis: the browser drive measures the packed
+artifact, and only a published face is packed. A workspace that selects `browser` on its `app` axis
+alone declares `playwright` and `@vitest/browser-playwright` and gets `configs/browsers.ts` emitted,
+and its proof still carries no branch: the selector reads the `src` axis, and a generated manifest
+packs `dist/src`, so an application face is neither selected nor packed. The imports the branch
+needs are declared by either axis, so they do not select the branch. The `vite` import selects
+nothing either: every workspace declares `vite`, whatever it publishes. In a core-only workspace,
+those imports resolve to nothing, and emitting the branch there would fail its own `check` and
+`lint:check` gates. Its Node cases retire themselves for a browser face, so a face published after
+the file was written would leave nothing measuring it. The assertion reddens instead, and names the
+subpath a browser branch is owed for. The remedy it carries is to delete the file and run `repair`,
+which writes the variant that carries the branch — the same route presence ownership already gives
+you for asking for the generated proof back.
+
+The generated distribution proof takes its release contract from the outside. The generated
+`prepublishOnly` invokes it as `npm run test:distribution -- --mode release`, and the proof reads
+`import.meta.env.MODE === 'release'` and **fails** on an unreachable registry rather than skipping.
+An ordinary local run skips that case, because a developer offline is not a defect; a release run
+does not, because skipping there passes the publish gate without ever proving the artifact installs.
+A workspace that replaces the generated proof takes that contract with it: presence ownership leaves
+a replacement alone, so a replacement that ignores the flag reports green on exactly the runs that
+matter.
+
+The consequence is one empty-project case per refused proof. A blueprint carrying `conformance` with
+no `tests/conformance.test.ts` registers a project whose include resolves to nothing, and Vitest
+exits non-zero on it. A blueprint carrying `service` gets `tests/setupService.ts` — the root
+configuration names that module by path, so an absent one fails the project's load rather than its
+run — and still no suite beneath `tests/service`, so `test:service` reports no test files until the
+consumer writes the first one. The `distribution` project no longer has that case: `new` writes the
+proof into the workspace it registers the project in, and a target that later lost the file reports
+drift that `repair` closes. Every remaining case is visible the first time the script runs, which is
+why none is silent.
 
 None of those folds into `integration`, which measures a different axis rather than a smaller
 one: the workspace's selected environments compose through their public barrels. The generated seed