@orkestrel/scaffold 0.0.26 → 0.0.28

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

@@ -110,12 +110,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 +132,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 +147,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 +221,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.                         |
@@ -172,6 +175,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | --------------------------- | -------- | ----------------------------------------------------------------------------- |
 | `artifactToHex`             | function | Project an artifact to the exact bytes it claims, as hexadecimal.             |
 | `bytesToHex`                | function | Encode bytes as exact lowercase hexadecimal text.                             |
+| `catalogToLayers`           | function | Project a catalog into the layers it publishes in.                            |
 | `cloneValue`                | function | Snapshot an untrusted value into exact JSON data the caller owns.             |
 | `compareVersions`           | function | Compare two versions by their numeric components.                             |
 | `computeBytes`              | function | Count the UTF-8 bytes text encodes to.                                        |
@@ -455,25 +459,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
@@ -559,9 +571,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
@@ -673,7 +692,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.
 
@@ -723,6 +743,46 @@ older planned finding refuses that call too. Take a fresh audit rather than repl
 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.
 
+## Fleet catalog
+
+`catalog` rewrites one marker-bounded region in `CATALOG_AGENT_PATH` and nothing else in that file.
+The region holds a table with four columns:
+
+| Column                 | Content                                                                    |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `Package`              | The published package name                                                 |
+| `Version`              | The registry's `dist-tags.latest`, or the cause when the lookup found none |
+| `Layer`                | The publish round the edges place the package in, as `L0`, `L1`, …         |
+| `Runtime dependencies` | Each declared runtime edge, as name and range                              |
+
+Both edge-bearing columns come from the same abbreviated packument the version came from, so a
+catalog costs one request per package and no more. Only `dependencies` is read. `devDependencies`
+reaches no consumer of the published package, so it constrains nothing about publish order, and
+reading it would place packages in rounds that do not exist.
+
+The layer is not stored on a row. `catalogToLayers` derives it from the rows' own edges, in the same
+call that writes them, so the two cannot disagree:
+
+```ts
+import { catalogToLayers } from '@orkestrel/scaffold'
+
+const layers = catalogToLayers(entries)
+layers[0] // the names that depend on nothing else in the fleet
+```
+
+An edge counts only when it names a package this catalog publishes. An edge leaving the fleet and an
+edge to a row that found no version each constrain nothing, so neither holds its dependent back.
+
+The order is load-bearing because these packages are `0.0.x`, where a caret pins one exact release.
+A dependent sees a new dependency version only after the dependent re-pins and republishes, so
+publishing a dependent before its dependency leaves the dependent pinned to the older release. Two
+ranges that disagree install two copies of one package, and the compiler reads those copies as two
+distinct types.
+
+A cycle cannot be published in rounds. `catalogToLayers` omits its members rather than placing them
+in an order that would be wrong, and their rows carry no layer cell. An absent name is the report:
+compare the returned names against the catalog to find one.
+
 ## Vendored data root
 
 The vendored data root is the shared file set, staged into the published package as plain data. It
@@ -919,7 +979,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
@@ -971,6 +1031,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)
 	})
 })