@orkestrel/scaffold 0.0.25 → 0.0.26

package/dist/host/guides/scaffold.md

@@ -12,6 +12,10 @@ does not work. Scaffold makes the shared set data — a vendored data root shipp
 — and gives it three verbs: create a workspace from it, report how a workspace differs from it, and
 write the difference back.
 
+Every code fence below is illustrative. Nothing runs one, so a trailing `// value` comment inside a
+fence is this guide's claim rather than a measured answer; the driven examples are the ones the
+shipped declarations print. Limits states what that leaves unproven and what covers it instead.
+
 ```sh
 npm install --save-dev @orkestrel/scaffold
 ```
@@ -98,13 +102,15 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `EXTRA_RANGE_PATTERN`             | const | The registry-only semver subset accepted for a development extra's range.                        |
 | `GLOBAL_SETUP_PATH`               | const | The shared Vitest global-setup module whose presence makes a workspace `global`.                 |
 | `GUIDES_TEST_PATH`                | const | The guide-parity proof whose physical file selects the fixed `guides` project.                   |
+| `EXECUTABLE_PATHS`                | const | The vendored paths a target receives with its executable bit set, frozen.                        |
 | `GROUPS`                          | const | The seven `Group` values in plan order, frozen.                                                  |
 | `HEX_PATTERN`                     | const | Exact lowercase hexadecimal bytes: two digits per byte, and empty content is valid.              |
 | `HOST_PATHS`                      | const | The paths byte-copied from the vendored data root, frozen.                                       |
 | `INTEGRATION_TEST_PATH`           | const | The installed-package proof whose presence makes a workspace `integration`.                      |
-| `INVALID_PATH_CHARACTER_PATTERN`  | const | Visible characters a portable path and a Markdown path cell both forbid.                         |
+| `INVALID_PATH_CHARACTER_PATTERN`  | const | Visible characters a target-relative path and a Markdown path cell both forbid.                  |
 | `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.                         |
 | `MAX_COLLECTION_ITEMS`            | const | Maximum items accepted in one public collection.                                                 |
 | `MAX_DEPENDENCY_NAME_LENGTH`      | const | Maximum dependency package name length, scope included, as the registry caps it.                 |
 | `MAX_MANIFEST_BYTES`              | const | Maximum bytes accepted for one package or vendored-host manifest.                                |
@@ -145,7 +151,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `isHex`             | const    | Narrow a value to exact lowercase hexadecimal bytes within one artifact's limit. |
 | `isMirror`          | const    | Narrow a value to a `Mirror`.                                                    |
 | `isOverride`        | const    | Narrow a value to an `Override`.                                                 |
-| `isPath`            | function | Narrow a value to a portable target-relative path.                               |
+| `isPath`            | function | Narrow a value to a logical target-relative path.                                |
 | `isPlan`            | const    | Narrow a value to a `Plan`.                                                      |
 | `isQuestion`        | const    | Narrow a value to a `Question`.                                                  |
 | `isScaffoldError`   | function | Narrow a caught value to a `ScaffoldError`.                                      |
@@ -176,6 +182,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `inferGroup`                | function | Infer the `Group` a path belongs to.                                          |
 | `manifestToDependencies`    | function | Project a package manifest's text to the `@orkestrel/*` packages it declares. |
 | `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.   |
 | `matchesOrchestrationPath`  | function | Test whether a path instructs or wires an agent rather than the toolchain.    |
 | `matchesRange`              | function | Test whether a declared range already admits a published version.             |
@@ -313,6 +320,7 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
 | `listDirectories`       | function | List a directory's descendant directories as sorted root-relative paths.              |
 | `listFiles`             | function | List a directory's files as sorted root-relative paths.                               |
 | `matchesAnchor`         | function | Test whether a captured directory is still the same directory.                        |
+| `matchesExecutablePath` | function | Test whether a vendored path is one a target receives executable.                     |
 | `matchesExpectation`    | function | Test whether a destination still holds what was captured of it.                       |
 | `matchesGitPath`        | function | Test whether a path addresses a target's own repository metadata.                     |
 | `matchesMissingPath`    | function | Test whether a caught filesystem error reports an absent path.                        |
@@ -388,7 +396,7 @@ no interface and is documented directly.
 | Method      | Summary                                                                            |
 | ----------- | ---------------------------------------------------------------------------------- |
 | `write`     | Stage one text file.                                                               |
-| `copy`      | Stage one byte-for-byte copy of a file that already exists on this host.           |
+| `copy`      | Stage one byte-for-byte copy in executable or non-executable destination mode.     |
 | `directory` | Establish one directory inside the target, one segment at a time.                  |
 | `remove`    | Mark one file for deletion at commit.                                              |
 | `commit`    | Promote every staged file and take every marked file, or roll the whole call back. |
@@ -510,7 +518,7 @@ standard error, so a piped value is never polluted.
 | Verb        | Value                                                                      |
 | ----------- | -------------------------------------------------------------------------- |
 | `new`       | `MaterializeResult` — `target`, `written`, `skipped`, `removed`            |
-| `audit`     | `Audit` — `findings` and `questions`                                       |
+| `audit`     | `Audit` — `findings` and `questions`; planned findings carry `ownership`   |
 | `repair`    | `MaterializeResult` plus `audit`, the terminal audit taken after the write |
 | `catalog`   | `MaterializeResult` plus `entries`, `mirrors`, and `dropped`               |
 | `overwrite` | The `catalog` value plus `audit`, `releases`, and `note` on a partial run  |
@@ -543,10 +551,24 @@ The two axes are independent, so a library-only, an application-only, and a mixe
 first class. `dependencies` and `peers` are runtime `@orkestrel/*` packages; `extras` are
 development dependencies and may carry any valid npm name.
 
+One published environment owns the package root directly. Several published environments require
+`core`, which owns that root while each other environment keeps its subpath. A multi-environment
+`src` selection without `core` therefore emits entry fields naming a `core` build the workspace
+never runs. The gate reports that as a non-blocking `src` question rather than refusing the compile,
+because the shape is chosen once and read afterwards: `new` refuses the advisory, while `audit` and
+`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`, `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.
 
+An axis-dependent structural fact projects only when its required axis exists. `integration`
+projects a published `src`, and `showcase` projects the browser `app` environment. When that axis is
+absent the flag adds no artifact, configuration, script, or dependency, and the gate reports a
+non-blocking question on that field so the caller who set it learns it emitted nothing. The same
+rule applies to both facts.
+
 `createBlueprint` enforces shape only. Whether the name is a name, the version a version, and the
 axis combination one this package can generate are the gate's laws, and the gate answers them with
 questions. A blueprint the gate will refuse is still constructible, so one law lives in one place.
@@ -577,12 +599,40 @@ refused blueprint is answered rather than raised, so a caller reads the refusal
 asked for. Each stage records its input and its output, a failed stage records the coded reason
 beside them, and the stages after a failed one never run.
 
+A plan says the blueprint can be built. It does not say the blueprint should be created. Every
+question beside the plan is advice the compile could not settle, and the caller that chose the shape
+is the one that answers it. So `new` refuses on any question, blocking or not, before it writes,
+while `audit` and `repair` carry the same questions through, because a target that already has that
+shape still has to be described and restored.
+
+A library caller creating a fresh workspace applies `new`'s rule itself:
+
+```ts
+import { createBlueprint, createCompiler } from '@orkestrel/scaffold'
+
+const compiler = createCompiler()
+const scaffolding = compiler.compile(createBlueprint('router', { src: ['browser', 'server'] }))
+
+scaffolding.plan === undefined || scaffolding.questions.length > 0 // true — do not write this shape
+compiler.destroy()
+```
+
+`materialize` does not apply that rule for you, and it could not: `compile` returns `questions`
+beside `plan`, and the writer receives the plan alone. It refuses what only a writer can see — a
+target that is not vacant — and writes the plan it is given otherwise. Choosing a shape is a policy
+about which workspace to want, the plan has already answered whether that workspace can be built,
+and the questions are where the package says what it thinks of the choice. That is the same line
+`createBlueprint` draws when it constructs a blueprint the gate will refuse: one law lives in one
+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. Both entry points snapshot the caller's
 value first and then guard the snapshot, so a property backed by an accessor is refused rather than
 read.
 
-Overrides replace a drafted artifact's content whole. An override that matches no planned artifact,
+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
+selected group does not block that compile. An override that matches no artifact in the full draft,
 that targets a host-origin artifact, or that targets the manifest is a blocking question rather
 than a silent no-op.
 
@@ -627,7 +677,19 @@ selected by their defining paths, as `guides` is. A workspace that needs other l
 must keep those edits outside a content-owned file; `repair` restores that file to the canonical
 project set.
 
-An audit reports one `Finding` per compared path.
+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
+no ownership because no artifact was planned for its path. `Ownership` says what scaffold claims at
+a path, not what one run did there. Counting planned findings by `content`, `presence`, and `birth`
+therefore says what audit is entitled to compare and stays the same against a vacant target and a
+repaired one. What one run compared comes from `ownership`, `drift`, and `observed` together. A
+content-owned finding carrying `observed` had its bytes compared. A content-owned `missing` finding
+and every presence-owned finding were decided by existence alone. A birth-owned finding was not
+examined. The foreign findings are exactly the ones no ownership accounts for. The audit stores no
+aggregate tally.
+
+The plan and snapshot are each bounded at `MAX_COLLECTION_ITEMS`. An audit may therefore carry one
+finding per planned artifact plus one per unplanned snapshot path, up to `MAX_AUDIT_FINDINGS`.
 
 | `Drift`   | Means                                 |
 | --------- | ------------------------------------- |
@@ -642,6 +704,25 @@ removes a foreign file each fail when the destination no longer matches what the
 The requirement sits in the type rather than in prose, because a deletion that cannot bind to what
 the audit showed is the one thing the destructive verb must never do.
 
+The shape a `Finding` admits is wider than the set an audit produces. Which combinations of
+`ownership`, `drift`, and `observed` a real comparison reaches is `inferDrift`'s law — birth is
+always aligned, presence compares existence only, and bytes are recorded only where they were
+read — so the shape admits a birth-owned path reported stale, which no audit produces. That is
+deliberate: restating the comparison's case analysis in the type would be a second copy of it, able
+to disagree with the one that decides. `isFinding` proves the shape a reader may destructure and
+nothing about whether the verdict is one an audit could have reached. `repair` and `remove`
+re-derive every verdict themselves and act only on what they derived, so a verdict the comparison
+could not have produced is refused by name rather than acted on.
+
+That shape is versioned, and the guard runs at runtime. `repair` and `remove` guard the whole audit
+before reading any of it, so an audit persisted or built against an earlier version of this package
+is refused with a coded `INVALID` failure rather than accepted and partly understood. A planned
+finding carries `ownership`, which findings made before that field existed do not. `remove` acts
+only on foreign findings, which never carried ownership, but the guard reads every finding, so one
+older planned finding refuses that call too. Take a fresh audit rather than replaying a stored one:
+a stored audit records what a target looked like then, and both verbs bind their writes to what a
+target holds now. The refusal is deliberate at `0.0.x` and there is no migration path.
+
 ## Vendored data root
 
 The vendored data root is the shared file set, staged into the published package as plain data. It
@@ -744,6 +825,19 @@ result.written // every path created
 materializer.destroy()
 ```
 
+`resolveContainedPath` refuses a lexical escape, a physical link out of the root, and a dangling
+link whose raw target contains a `..` segment. It returns the lexical join of `root` and `path` — an
+absolute path under `root`, which is what its shipped example prints — after checking the namespace,
+not an open filesystem handle. Its contract therefore excludes a concurrent rename or link swap
+during the check or before the caller finishes using that path. A caller that admits hostile
+concurrent namespace mutation needs a handle-bound operation instead.
+
+`resolveRealPath` answers the caller's own text collapsed lexically, then resolved through every link
+in what survives that collapse. A `..` the caller wrote cancels the segment before it as text, so
+`<root>/hop/..` answers `<root>` even where `hop` links elsewhere, rather than the directory holding
+what `hop` points at. The collapse only ever shortens the path, so nothing reaches outside it this
+way; the answer is a lexical location resolved through links, not a physical one.
+
 Read the registry and the guide host:
 
 ```ts
@@ -762,6 +856,17 @@ verdict carrying its cause rather than thrown, so one unreachable package never
 rest of the answer. The organization package list is the exception, because without it there is no
 fleet to report.
 
+Both bounds count decoded bytes, and a version lookup asks the registry for the abbreviated
+packument — `dist-tags` and a trimmed version map, rather than the full per-version metadata no
+verdict reads. That is the smallest form the registry publishes, and `limit` is capped at
+`MAX_ARTIFACT_BYTES`, so a package with enough published releases to pass it cannot be looked up at
+all. It comes back as a `failed` verdict naming the limit, which is this reader's bound and not a
+statement about the package.
+
+A status that carries no representation — a `204` or a `205` — is a `failed` verdict naming the
+status, never a `found` answer holding no bytes. A genuinely empty file arrives as a `200` and does
+read as found.
+
 Stage and swap a set of files yourself:
 
 ```ts
@@ -780,6 +885,9 @@ A transaction owns a private root beside the target on the same volume, so every
 rename rather than a copy. A failure part way through commit restores every destination it already
 promoted and removes every directory it created. No destination ever receives half-written bytes.
 It is not a journal: a process killed between two promotions leaves a mixed target.
+The transaction binds each directory's location rather than its lifetime, so an ancestor swapped
+for another path, a file, a symlink, or nothing is refused, and one deleted and recreated in place
+may not be.
 
 Narrow a refusal by its code:
 
@@ -793,9 +901,16 @@ try {
 }
 ```
 
-`INVALID` is off-contract input, `BLOCKED` is a refused blueprint recorded on a compile stage,
-`TARGET` is a destination that is not what the caller's observation said it was, `WRITE` is a
-mutation that could not be completed, and `FETCH` is an upstream read that produced no answer.
+`INVALID` is off-contract input, `BLOCKED` is a refused blueprint, `TARGET` is a destination that is
+not what the caller's observation said it was, `WRITE` is a mutation that could not be completed, and
+`FETCH` is an upstream read that produced no answer.
+
+`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 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 the package
+can describe and declines to create.
 
 Every entity publishes an emitter. The compiler emits `compile`, `audit`, `block`, `error`, and
 `destroy`; the materializer emits `write`, `remove`, `finish`, `error`, and `destroy`; the upstream
@@ -804,13 +919,53 @@ are thrown, so an observer sees a refusal even where the caller catches it.
 
 ## Limits
 
-Two things a reader will look for and not find.
+Six things a reader will look for and not find.
+
+**A code fence in this guide is unverified.** [`tests/guides.test.ts`](../tests/guides.test.ts)
+proves that every fence imports only real exports of the two barrels, and that every backticked name
+in this file resolves to one. It neither runs a fence nor typechecks one, so a trailing `// value`
+comment inside a fence states what this guide claims rather than what the build answered. The
+verdicts that are measured are the ones a consumer hovers:
+[`tests/integration.test.ts`](../tests/integration.test.ts) drives every `@example` the built
+declarations print against the installed package, scores each verdict it can read as a value, and
+names exactly the ones it cannot. Fences are not added to that instrument, because most of them
+cannot be run: several declare an ambient value that has no runtime, and several write to a
+directory or read the network, so executing them would be a mutation rather than a check.
+
+**The library does not enforce the creating verb's policy.** `new` refuses a blueprint carrying any
+question, and `materialize` writes any plan into any vacant target. A workspace of several published
+`src` environments without `core` is therefore constructible, compilable, and writable through the
+library, and its manifest names a `core` build the workspace never runs — which is exactly what the
+advisory said. The refusal lives in the verb that chose the shape because that verb is the only one
+holding the advice: `compile` returns `questions` beside `plan`, and `materialize` receives the plan
+alone, so it has nothing to refuse on. The Compile section states the rule a library caller applies
+in its place.
+
+**`isPath` does not prove host portability.** It proves bounded target-relative syntax and rejects
+traversal, separators, controls, and reserved syntax characters. It deliberately admits host-specific
+segment spellings such as a Windows device name, a trailing dot or space, and a segment beyond a
+filesystem's byte ceiling. The compiler emits none of those names. A caller-supplied plan may carry
+one, and the writer reports the host's refusal rather than treating logical path syntax as a promise
+that every filesystem can create it. `isFilesystemPath` is the separate server guard for target and
+vendored-root locations on the host. Both `/` and `\` are separators to every reading in this
+package, on every host, including the server's reading of a raw symbolic-link target. A POSIX
+filename that legally contains a backslash — `weird\..\name` — is therefore refused as three
+segments rather than admitted as one name. That is one separator law with a conservative side, not a
+host-dependent second one.
 
 **Scaffold emits no styles axis.** `SRC_MATRIX` is exactly `core`, `browser`, and `server`, and
 `Blueprint` carries no styles field. A workspace that needs `src/styles/` adds the directory, its
 configuration, and its Vitest project by hand. `.claude/rules/workspace.md` describes styles as an
 environment because the fleet has one; scaffold simply does not generate it.
 
+**No host path is normalized before it is guarded.** `isFilesystemPath` refuses an empty segment, so
+`packages//router` is off contract. A trailing separator does not produce one: it terminates a
+directory rather than opening a segment, and every Node path API reads `./packages/router/` and
+`./packages/router` as one location, so both are admitted. Every server entry point and the
+`--target` option guard the text they were handed and resolve it afterwards, so a directory taken
+from a shell completion arrives carrying the separator the shell appended and names the directory it
+appears to name.
+
 **A generated workspace has empty barrels and no starter entity.** Every emitted `index.ts` exports
 nothing. This is deliberate: a generated sample entity is repeatedly mistaken for real
 implementation. What a consumer does first is write the module's `types.ts`, then the

package/dist/host/manifest.json

@@ -463,22 +463,22 @@
 		{
 			"storage": "scripts/codex.sh",
 			"destination": "scripts/codex.sh",
-			"executable": false
+			"executable": true
 		},
 		{
 			"storage": "scripts/cursor.sh",
 			"destination": "scripts/cursor.sh",
-			"executable": false
+			"executable": true
 		},
 		{
 			"storage": "scripts/deps.sh",
 			"destination": "scripts/deps.sh",
-			"executable": false
+			"executable": true
 		},
 		{
 			"storage": "scripts/ollama.sh",
 			"destination": "scripts/ollama.sh",
-			"executable": false
+			"executable": true
 		},
 		{
 			"storage": "tests/config.test.ts",
@@ -531,5 +531,5 @@
 		".codex/agents",
 		".cursor/rules"
 	],
-	"digest": "b852817ada9fa3b30ce2ee47c7bf786e46dfbc1c5531e4d208b0bf8edcc2482c"
+	"digest": "ae9a32c599f4ca43278496001c659731504b3e669252ca231aaaf1c61d84810c"
 }

package/dist/host/tests/config.test.ts

@@ -110,6 +110,12 @@ describe('root configuration', () => {
 			})
 		}
 		expected.set('probe', { include: 'tmp/probe/**/*.test.ts', setup: ['./tests/setup.ts'] })
+		// A row that is a configuration rather than a factory. A workspace with a
+		// browser application emits one, because that factory refuses overrides and
+		// so is not a value Vitest may call. It is required here, in a workspace that
+		// has no browser application, so this proof exercises that resolution
+		// wherever it runs instead of only where the shape happens to occur.
+		expected.set('concrete', { include: 'tests/concrete.test.ts', setup: ['./tests/setup.ts'] })
 
 		const projects = configuration.test?.projects
 		if (!Array.isArray(projects)) throw new Error('The root configuration carries no projects')
@@ -128,7 +134,14 @@ describe('root configuration', () => {
 			'name',
 			{ value: 'control' },
 		)
-		const controlled = projects.concat(control)
+		const concrete = {
+			test: {
+				name: { label: 'concrete' },
+				include: ['tests/concrete.test.ts'],
+				setupFiles: ['./tests/setup.ts'],
+			},
+		}
+		const controlled = projects.concat(control, concrete)
 		const configured = new Map<
 			string,
 			{ readonly include: string; readonly setup: readonly string[] }
@@ -137,13 +150,23 @@ describe('root configuration', () => {
 			const factoryName = requiredLabel.replace(/:([a-z])/gu, (_match, letter: string) =>
 				letter.toUpperCase(),
 			)
-			const factory = controlled.find(
-				(candidate) => typeof candidate === 'function' && candidate.name === factoryName,
-			)
-			if (typeof factory !== 'function') {
-				throw new Error(`${requiredLabel} has no project factory`)
+			// A row is either the factory named for the project or the configuration
+			// that project resolves to, and a required project is found as whichever
+			// it is. Only the required row is read, so an extra factory is still
+			// selected by name and never called.
+			const row = controlled.find((candidate) => {
+				if (typeof candidate === 'function') return candidate.name === factoryName
+				if (typeof candidate !== 'object' || candidate === null) return false
+				const block: unknown = Object.getOwnPropertyDescriptor(candidate, 'test')?.value
+				if (typeof block !== 'object' || block === null) return false
+				const named: unknown = Object.getOwnPropertyDescriptor(block, 'name')?.value
+				if (typeof named !== 'object' || named === null) return false
+				return Object.getOwnPropertyDescriptor(named, 'label')?.value === requiredLabel
+			})
+			if (row === undefined) {
+				throw new Error(`${requiredLabel} has no project factory or configuration`)
 			}
-			const project: unknown = Reflect.apply(factory, undefined, [])
+			const project: unknown = typeof row === 'function' ? Reflect.apply(row, undefined, []) : row
 			if (typeof project !== 'object' || project === null) {
 				throw new Error('A project factory returned no configuration')
 			}