@orkestrel/scaffold 0.0.27 → 0.0.29

package/dist/host/claude/rules/tests.md

@@ -36,12 +36,14 @@ paths:
 A proof that covers the workspace instead of one module has a fixed location, so no package invents
 its own:
 
-| Path                        | Proves                                                         |
-| --------------------------- | -------------------------------------------------------------- |
-| `tests/policy.test.ts`      | Every source file obeys the syntactic coding and placement law |
-| `tests/config.test.ts`      | Root configuration resolves its aliases, projects, and outputs |
-| `tests/guides.test.ts`      | Every documented API exists and every public API is documented |
-| `tests/integration.test.ts` | The built package works when installed and driven from outside |
+| Path                         | Proves                                                          |
+| ---------------------------- | --------------------------------------------------------------- |
+| `tests/policy.test.ts`       | Every source file obeys the syntactic coding and placement law  |
+| `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs  |
+| `tests/guides.test.ts`       | Every documented API exists and every public API is documented  |
+| `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks   |
+| `tests/integration.test.ts`  | The built package works when installed and driven from outside  |
+| `tests/service/**/*.test.ts` | The live external services this package drives, driven for real |
 
 - `.claude/rules/workspace.md` names the Vitest project each location belongs to.
 - `integration.test.ts` is a reserved filename at any level. It names a scope rather than a module,
@@ -80,9 +82,11 @@ Three rules bind every probe:
 
 Live external services/models are the deliberate exception to fast hermetic defaults:
 
-- Put them in a dedicated isolated Vitest project with its own setup and longer timeout.
+- Put them in the `service` project, under `tests/service/`, with `tests/setupService.ts` for setup
+  and a longer timeout. That module's presence is what registers the project, so a live proof with
+  no readiness setup is a project nothing configures.
 - Keep them out of the default run.
-- Warm and verify service readiness in setup.
+- Warm and verify service readiness in `tests/setupService.ts`.
 - Hard-require readiness: throw loudly; never silently skip.
 - Verify service-dependent logic through that service's project, not unrelated module tests or scattered conditional skips.
 - Tune each request to the smallest input/context/output that proves one behavior without becoming brittle or expensive.
@@ -193,6 +197,14 @@ Coverage rules:
 Before acceptance:
 
 - prove every intended test file is discovered by the correct project;
+- prove every declared project is reachable from a gate. A project registered in the root
+  configuration with no script, or with a script no chain runs, is a proof that never executes — and
+  because it never executes it never fails, so the suite reports green while carrying it. Read the
+  chain, not the exit code: run each project directly once and compare that list against what `test`
+  actually invokes. The gate that would report this gap is the gate that is missing.
+- prove a declared project's include resolves to a real file. An empty project is not a passing
+  project: Vitest exits non-zero on "no test files found", so a project aimed at a path that was
+  never created stays invisible until something finally runs it.
 - inspect actual test counts and environments;
 - audit `.todo`, `.skip`, conditional skips, retries, and inflated timeouts;
 - confirm each assertion would fail for the defect it claims to catch, and that it fails rather than passes when its population is empty;

package/dist/host/claude/rules/workspace.md

@@ -60,9 +60,13 @@ Define aliases in `tsconfig.json` first. `vite.config.ts` derives from `compiler
 - `*/types.ts`: public API contracts.
 - `configs/src/` and `configs/app/`: thin per-target wrappers, including optional
   `configs/src/*bin*` files. Shared logic remains in root configs.
-- `configs/helpers.ts`: the one permitted leaf under `configs/`. It imports nothing from the
-  workspace, which is what keeps it a leaf. Each `configs/src/*.config.ts` imports the root config
-  rather than the leaf, so shared build logic stays in one place.
+- `configs/helpers.ts` and `configs/browsers.ts`: the only permitted leaves under `configs/`. Each
+  imports nothing from the workspace, which is what keeps it a leaf. Each `configs/src/*.config.ts`
+  imports the root config rather than a leaf, so shared build logic stays in one place.
+- Keep `configs/helpers.ts` free of any dependency a core-only workspace does not declare. It is
+  vendored byte-identical to every workspace, so an import there must resolve in all of them.
+  `configs/browsers.ts` exists for that reason: it imports `playwright` and
+  `@vitest/browser-playwright`, and only a workspace with a browser environment is given it.
 
 Environment rules:
 
@@ -110,12 +114,21 @@ environment:
 The second axis is cross-cutting workspace proofs. Each one covers the whole workspace rather than
 one environment, so each is its own project:
 
-| Project       | Files                       | Proves                                                         | In `test` |
-| ------------- | --------------------------- | -------------------------------------------------------------- | --------- |
-| `policy`      | `tests/policy.test.ts`      | Every source file obeys the syntactic coding and placement law | Yes       |
-| `config`      | `tests/config.test.ts`      | Root configuration resolves its aliases, projects, and outputs | Yes       |
-| `guides`      | `tests/guides.test.ts`      | Every documented API exists and every public API is documented | Yes       |
-| `integration` | `tests/integration.test.ts` | The built package works when installed and driven from outside | No        |
+| Project       | Files                        | Proves                                                          | In `test` |
+| ------------- | ---------------------------- | --------------------------------------------------------------- | --------- |
+| `policy`      | `tests/policy.test.ts`       | Every source file obeys the syntactic coding and placement law  | Yes       |
+| `config`      | `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs  | Yes       |
+| `guides`      | `tests/guides.test.ts`       | Every documented API exists and every public API is documented  | Yes       |
+| `conformance` | `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks   | Yes       |
+| `integration` | `tests/integration.test.ts`  | The built package works when installed and driven from outside  | No        |
+| `service`     | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real | No        |
+
+`conformance` and `service` are two subjects, not two names for one. `conformance` measures this
+package against an official artifact it stays compatible with and drives nothing external: the
+tooling it measures against is installed, and any server it drives is one the proof starts itself.
+That is what makes it hermetic and keeps it in `test`. `service` drives the real thing, so it takes
+`tests/setupService.ts` for readiness, longer timeouts, and no file parallelism, and it leaves
+`test` for `prepublishOnly`.
 
 One project sits on neither axis. `probe` includes `tmp/probe/**/*.test.ts` so an agent can run a
 throwaway instrument against real sources, aliases and setup. Declare no proof there. Every test
@@ -123,8 +136,9 @@ script names its project, so no gate runs it; its directory is ignored by git; a
 `.claude/rules/tests.md` governs what may live there.
 
 - Define a cross-cutting project only for a proof the package actually has.
-- A live-service project is the fifth kind. It is named for the service it drives, and
-  `.claude/rules/tests.md` governs it.
+- A live-service project is the fifth kind. It is the `service` project above, `scripts/service.sh`
+  provisions what it drives, and `.claude/rules/tests.md` governs it. Name it `service` whatever it
+  drives.
 - A project leaves the default run for one of two reasons: it drives a live external service, or it
   is hermetic but slow — it spawns processes, packs, installs, or drives a real build.
 - Every isolated project has its own script, is excluded from `test`, and runs in `prepublishOnly`.
@@ -137,7 +151,7 @@ Setup assets:
 
 Scope with `test:src`, `test:src:core`, `test:app`, `test:app:server`, and equivalent scripts. Each
 cross-cutting project has its own script too: `test:policy`, `test:config`, `test:guides`,
-`test:integration`.
+`test:conformance`, `test:integration`, `test:service`.
 
 ## Typechecking and environment isolation
 
@@ -211,3 +225,4 @@ Run `show` only **after** formatting. The committed `demo/showcase.html` is gene
 - Store text as UTF-8.
 - Before accepting broad generated or migrated edits, scan changed text for replacement characters, mojibake, unintended control characters, and accidental trailing debris.
 - Preserve intentional Unicode punctuation and symbols; do not “clean” valid text merely because it is non-ASCII.
+- Never renormalize Unicode while rewriting a file. Retyping a line can silently fold a decomposed sequence into its precomposed form — `e` + U+0301 becoming U+00E9 — and the two render identically, so the diff reads as a no-op and review sees nothing. Where the exact code points are the subject, as in an encoding or transport proof, that fold deletes the case the test exists for while leaving it green and named. Move such a line rather than retyping it, and compare bytes with `od -c` or a code-point dump rather than by eye.

package/dist/host/guides/scaffold.md

@@ -92,6 +92,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `BIN_ENTRY_PATH`                  | const | The executable entry whose presence makes a workspace `bin`.                                     |
 | `CATALOG_AGENT_PATH`              | const | The agent file whose marker-bounded package table the catalog verb alone owns.                   |
 | `CONFIG_TEMPLATES`                | const | Formatter-stable template text for every configuration artifact.                                 |
+| `CONFORMANCE_TEST_PATH`           | const | The official-tooling drift proof whose presence makes a workspace `conformance`.                 |
 | `CONTROL_CHARACTER_PATTERN`       | const | Unicode controls, formatting controls, and line and paragraph separators rejected in text.       |
 | `DEFAULT_ENGINES`                 | const | The `engines.node` range a workspace starts with.                                                |
 | `DEFAULT_VERSION`                 | const | The version a workspace starts at.                                                               |
@@ -124,6 +125,8 @@ 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.          |
 | `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.         |
 | `SHOWCASE_CONFIG_PATH`            | const | The Vite wrapper whose presence makes a workspace `showcase`.                                    |
 | `SHOWCASE_DEV_DEPENDENCIES`       | const | The development dependency used only by the optional single-file showcase build.                 |
 | `SOURCE_BROWSER_DEV_DEPENDENCIES` | const | The development dependencies a published browser `src` environment adds.                         |
@@ -188,6 +191,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `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.             |
 | `nameToGuide`               | function | Derive the guide mirror path a package name answers for.                      |
+| `nameToRewrite`             | function | Derive the declaration rewrite a published face roll-up applies.              |
 | `planToSummary`             | function | Project a plan into its tally by artifact origin.                             |
 | `selectGroups`              | function | Select the groups a compile covers, in plan order.                            |
 | `selectHostPaths`           | function | Select the host paths a named workspace vendors.                              |
@@ -456,25 +460,33 @@ workspace would otherwise declare a dependency that does not resolve.
 
 `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 `tests/integration.test.ts` for
-`integration`, `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 `services`. Reading verbs preserve and
-protect that birth-owned script, but do not infer its service list from edited text.
+`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.
 
 ### Reading a target
 
 `audit`, `repair`, `catalog`, and `overwrite` derive the blueprint from the target itself. The name
 and the declared `@orkestrel/*` packages come from `package.json`. The two environment axes come
 from the directories the target actually ships, because a directory is the fact and a declaration
-beside it could disagree. Four more facts come from exact-case files: `src/bin/main.ts` selects
-`bin`, `tests/integration.test.ts` selects `integration`, `tests/setupGlobal.ts` selects `global`,
+beside it could disagree. Six more facts come from exact-case files: `src/bin/main.ts` selects
+`bin`, `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.
 
-`services` is not reconstructed. Its only artifact, `scripts/service.sh`, is birth-owned, so edited
-script text is not a trustworthy declaration of a service list. A present script remains in the
+`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
 target and remains protected from deletion through the owned scripts inventory, but a reading verb
-does not infer services from it.
+does not infer vendors from it.
+
+That is why the live-service project follows `service` rather than `vendors`. A reading verb has to
+plan the project before it can say anything about a target that runs one, and a vendor list it
+cannot recover would leave every such workspace unplannable. `tests/setupService.ts` is recoverable,
+is the module the root configuration names by path, and is what a live proof needs anyway, so it
+carries the fact and the vendor list keeps its own separate job.
 
 The root Vite configuration always defines the fixed `guides` project and selects it at
 configuration load only when `tests/guides.test.ts` is a physical file with that exact path case. A
@@ -560,9 +572,16 @@ 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`, `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.
+`bin`, `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.
+
+`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
+the project names. `vendors` names each external service the workspace drives and emits
+`scripts/service.sh`, the provisioner that starts them. Neither is derivable from the other: a
+workspace may declare vendors before it writes a suite, and a suite may drive a service the skeleton
+does not start.
 
 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
@@ -674,7 +693,8 @@ barrels, the tests, `README.md`, and `guides/README.md` are written once and are
 a later verb.
 
 Content ownership does not preserve an arbitrary custom Vitest project. Fixed optional proofs are
-selected by their defining paths, as `guides` is. A workspace that needs other local configuration
+selected by their defining paths, as `guides`, `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.
 
@@ -807,6 +827,17 @@ except the manifest.
 - One template artifact per configuration file the selection needs: the root `tsconfig.json` and
   `vite.config.ts`, plus a Vite config and a scoped TypeScript config per selected environment, and
   two more when `bin` is set.
+- One template artifact, `configs/browsers.ts`, for a workspace selecting `browser` on either axis.
+  It resolves the Chromium the Playwright provider launches, and the root `vite.config.ts` calls it
+  once into `browserOptions` and passes that to every `playwright()` provider it configures. The
+  precedence is `PLAYWRIGHT_EXECUTABLE_PATH`, `PLAYWRIGHT_WS_ENDPOINT`, `PLAYWRIGHT_CHANNEL`, the
+  managed Playwright Chromium, the container's bundled Chromium, a verified system channel, then the
+  platform default. An installed pinned revision returns empty options, so Playwright keeps its own
+  launch defaults. A pinned revision that is not installed falls through to a `chromium` alias or a
+  sibling `chromium-*` revision under the same browsers directory, because a managed container ships
+  one usable build for many Playwright versions. It is its own file rather than a block in the
+  vendored `configs/helpers.ts`, which every workspace receives byte-identical while only a browser
+  selection declares the `playwright` this module imports.
 - One template artifact per source and test file the selection needs: an `index.ts` barrel per
   selected environment, `main.ts` and `index.html` for an application browser, `tests/setup.ts`
   plus the host setup modules the selection reaches, and one entry test per axis project.
@@ -960,7 +991,7 @@ are thrown, so an observer sees a refusal even where the caller catches it.
 
 ## Limits
 
-Six things a reader will look for and not find.
+Seven 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
@@ -1012,6 +1043,30 @@ 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 conformance or live-service proof is registered, but neither is written for you.** Scaffold
+registers the `conformance` and `service` projects, their scripts, and the gate each belongs to. It
+emits no proof into either, because both name something only the package knows: 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.
+
+The consequence is one empty-project case in each direction. 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. Both cases are visible the first time the script runs, which is why
+neither is silent.
+
+Neither project folds into `integration`, which means something narrower: the built package works
+when installed and driven from outside. Two fleet packages hold the distinction. `@orkestrel/ollama`
+drives a real Ollama daemon through a `service` project, so a real service answers it and it runs
+from `prepublishOnly`. `@orkestrel/mcp` measures its server against the specification's own runner,
+`@modelcontextprotocol/conformance`, through a `conformance` project. It pins that runner as a
+development dependency and resolves it out of `node_modules`, and the server the runner drives is
+one the fixture starts itself on a loopback port, so the run drives nothing external and stays in
+`test`.
+
 ## Tests
 
 - [`tests/src/core/Compiler.test.ts`](../tests/src/core/Compiler.test.ts) — the three stages, the

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

@@ -102,13 +102,22 @@ describe('root configuration', () => {
 				setup: ['./tests/setup.ts', './tests/setupServer.ts'],
 			})
 		}
-		for (const label of ['policy', 'config', 'guides', 'integration']) {
+		for (const label of ['policy', 'config', 'guides', 'conformance', 'integration']) {
 			if (!existsSync(resolve(root, `tests/${label}.test.ts`))) continue
 			expected.set(label, {
 				include: `tests/${label}.test.ts`,
 				setup: ['./tests/setup.ts'],
 			})
 		}
+		// The live-service project covers a directory rather than one proof, so its
+		// readiness module is the fact that selects it. A suite beneath
+		// `tests/service` with no setup module is a project nothing configures.
+		if (existsSync(resolve(root, 'tests/setupService.ts'))) {
+			expected.set('service', {
+				include: 'tests/service/**/*.test.ts',
+				setup: ['./tests/setup.ts', './tests/setupService.ts'],
+			})
+		}
 		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
@@ -353,8 +362,35 @@ describe('root configuration', () => {
 		const test = Object.getOwnPropertyDescriptor(scripts, 'test')?.value
 		const config = Object.getOwnPropertyDescriptor(scripts, 'test:config')?.value
 		const integration = Object.getOwnPropertyDescriptor(scripts, 'test:integration')?.value
+		const conformance = Object.getOwnPropertyDescriptor(scripts, 'test:conformance')?.value
+		const service = Object.getOwnPropertyDescriptor(scripts, 'test:service')?.value
 		const publish = Object.getOwnPropertyDescriptor(scripts, 'prepublishOnly')?.value
 		const hasIntegration = existsSync(resolve(root, 'tests/integration.test.ts'))
+		// The optional proofs are read off the registered project set rather than off
+		// their files, because the defect this measures is a registered project no
+		// gate runs. A project selected by a path that is not yet there is still
+		// registered, and it is exactly the one whose script goes missing.
+		const rows = configuration.test?.projects
+		if (!Array.isArray(rows)) throw new Error('The root configuration carries no projects')
+		const registered = new Set<string>()
+		for (const row of rows) {
+			if (typeof row === 'function') {
+				registered.add(row.name)
+				continue
+			}
+			if (typeof row !== 'object' || row === null) continue
+			const block: unknown = Object.getOwnPropertyDescriptor(row, 'test')?.value
+			if (typeof block !== 'object' || block === null) continue
+			const named: unknown = Object.getOwnPropertyDescriptor(block, 'name')?.value
+			if (typeof named !== 'object' || named === null) continue
+			const label: unknown = Object.getOwnPropertyDescriptor(named, 'label')?.value
+			if (typeof label === 'string') registered.add(label)
+		}
+		// The population must be able to answer both ways before either answer counts.
+		expect(registered.has('config')).toBe(true)
+		expect(registered.has('control')).toBe(false)
+		const hasConformance = registered.has('conformance')
+		const hasService = registered.has('service')
 		expect(config).toBe(
 			'vitest run --config vite.config.ts --no-cache --reporter=dot --project config',
 		)
@@ -368,6 +404,25 @@ describe('root configuration', () => {
 		expect(typeof publish === 'string' && publish.includes('npm run test:integration')).toBe(
 			hasIntegration,
 		)
+		// A registered project no gate runs is a proof that never executes, and it
+		// never fails, so the suite reports green while carrying it. Conformance is
+		// hermetic and belongs to `test`; the live-service project drives a real
+		// service and belongs to `prepublishOnly` alone.
+		expect(conformance).toBe(
+			hasConformance
+				? 'vitest run --config vite.config.ts --no-cache --reporter=dot --project conformance'
+				: undefined,
+		)
+		expect(typeof test === 'string' && test.includes('npm run test:conformance')).toBe(
+			hasConformance,
+		)
+		expect(service).toBe(
+			hasService
+				? 'vitest run --config vite.config.ts --no-cache --reporter=dot --project service'
+				: undefined,
+		)
+		expect(typeof test === 'string' && test.includes('test:service')).toBe(false)
+		expect(typeof publish === 'string' && publish.includes('npm run test:service')).toBe(hasService)
 	})
 })