@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

package/README.md

@@ -23,7 +23,7 @@ This is **NOT** a development testing tool. This is a **production validation or
 2. **Validates configuration** - `config.json`, `operations.json` and `integration-contract.json`, through the manifest rows that own them
 3. **Validates the environment contract** - every `env.required` name is set
 4. **Validates operations** - the v3 handler-registry rules
-5. **Validates business logic** - cookbook tests with mocked infrastructure
+5. **Validates business logic** - cookbook tests against the two mocked doubles named below
 6. **Validates connector integration** - the two declarations agree and the environment backs them
 7. **Generates validation proof** - SHA256 proof carried into registration
 
@@ -58,7 +58,7 @@ runs Tier-1 validation in phase 0.2 — before MQ connects, before registration.
    sentences of its own, and the same defect was reported twice
 3. **Environment Contract** - every variable the contract declares `env.required` is set
 4. **Operations Compliance** - every operation declares `handler`, `bundle_scope`, `input`, `output`, and none carries a retired v2 field (`endpoint`, `method`, `path`); a missing `description` is a warning
-5. **Cookbook Tests** - business logic + integration (MOCKED infra)
+5. **Cookbook Tests** - business logic + integration; every step is dispatched in-process, with no transport, and against the service's real database (see below)
 6. **Connector Integration** - the connector declarations agree and the environment backs them
 7. **Manifest conformance** - the repository against the uniform manifest shipped in this package (see below)
 
@@ -68,6 +68,207 @@ signal saved to `ci/deployability.json`
 > The list said "Service Readiness — HTTP API works" until 2026-08-27. That step
 > was removed on 2026-08-22 under ADR 0005 and this README kept describing it.
 
+### The shape of a run's result
+
+```js
+{
+  success, steps: { structure, config, env, operations, cookbooks, connectors, manifest },
+  errors: [ … ], warnings: [ … ],
+  totalTests, passedTests, failedTests,
+  deployable, deployFindings, notRun, durationMs, proof?, fingerprint?
+}
+```
+
+**Every step that was reached has a record in `steps`, and a step that THREW has one
+too** — `{ valid: false, threw: true, errors: [ … ] }`, with whatever it had already
+measured kept beside it. Absence therefore means one thing only: the run stopped before
+that step (it fail-fasts after steps 1 and 3). That distinction is not cosmetic:
+`@onlineapps/service-wrapper` 9.0.x decides whether a failed FÁZE 0.2 may be retried by
+reading `steps.<step>.valid` — `structure`, `config`, `env`, `operations` and `manifest`
+read files alone, so their verdict is permanent, while `cookbooks` and an exception of the
+validator itself keep the retry budget. Until d.602 a step whose body threw left NO record,
+so a structural defect read as "the validator threw" and bought the full six attempts:
+18,5 minutes of a boot that cannot succeed (measured on biz-converter, W591).
+
+**`errors` is one flat array of two shapes**, and a reader must handle both:
+
+| Shape | Written by | Carries `step` |
+|---|---|---|
+| object `{ type, path?, message, fix?, step }` | step 1, and every step that THREW (`type: 'STEP_THREW'`) | yes |
+| sentence, already in the `[Context] Problem - Expected/Fix` shape | steps 2-7 by their rules | no — see below |
+
+The `step` marker is ADDED to the objects, never substituted for what they carried, and the
+sentences keep their shape. That asymmetry is deliberate and measured: the released
+wrapper's `describeValidationFinding()` renders a string verbatim and an object only when
+it carries `type` **and** `message`, so rewriting the sentences into `{ step, message }`
+objects would deliver them to the operator as raw JSON. Unifying on objects is therefore a
+BREAKING change that waits for a wrapper which reads `step` (reported to BIZ-general with
+d.602). A finding's own `errors` array inside `steps.<step>` is the step's answer and is
+left untouched — the marker is on the copy that travels in `errors`.
+
+---
+
+## Pre-validation runs in-process — and against the real database
+
+A cookbook step is dispatched **in this process**, against the service's own v3
+handler, with no transport of any kind. There is nothing to mock: the ctx slots
+are `null` (pinned by `tests/unit/CookbookTestRunner.ctxShape.test.js`), and a
+handler that needs a schema reaches it the way it reaches it in production — by
+importing the service's own database module. **That connection is real.**
+
+`mockInfrastructure` — the option that once built a MockMQClient and a
+MockRegistry for transport dispatch — is retired: the runner and the cookbook
+format both refuse it by name (`tests/unit/mockInfrastructureRetired.test.js`).
+
+What the real database requires is ORDER, and the contract is what makes the
+order decidable:
+
+- a service that needs a database declares **both** `requiredConnectors.db: true`
+  **and** the `database` block; the contract refuses either one standing alone,
+  in both directions;
+- `setup-db` therefore builds a schema exactly where one is declared, and reports
+  `NOT APPLICABLE` — never `OK` — where none is;
+- `run-prevalidation` (`npm run test:cookbooks`) comes **after** `ci:gate:setup`
+  in the job, because by then the schema its handlers will reach exists.
+
+Run out of that order, or against a service whose schema was never built, the
+cookbooks fail in the handler's own database error. That is the truthful
+failure.
+
+---
+
+## A recipe builds its own fixture — `{{steps.<step_id>.output.…}}`
+
+A step's `input` may reference what an EARLIER step of the same cookbook
+returned. The runner resolves those references before it calls the handler, so a
+recipe can create the data it needs, use it, and delete it again — instead of
+depending on a seed that exists in one environment and not in another.
+
+```json
+{
+  "steps": [
+    { "step_id": "create_fixture", "service": "biz-x", "operation": "create-row",
+      "input": { "label": "boot-fixture" } },
+    { "step_id": "use_fixture", "service": "biz-x", "operation": "convert",
+      "depends_on": ["create_fixture"],
+      "input": { "id": "{{steps.create_fixture.output.id}}" } },
+    { "step_id": "delete_fixture", "service": "biz-x", "operation": "delete-row",
+      "depends_on": ["create_fixture"],
+      "input": { "id": "{{steps.create_fixture.output.id}}" } }
+  ]
+}
+```
+
+**The syntax is not this package's.** Which forms exist, that a whole-value
+expression keeps the resolved type while an expression inside text is
+stringified, that a step is addressed by `step_id` and never by position, and
+that an unresolvable reference survives as literal text — all of it is owned by
+[`api/docs/biz/40-cookbooks/variable-references.md`](../../../docs/biz/40-cookbooks/variable-references.md),
+and the traversal is `@onlineapps/cookbook-core`
+(`resolveReferencesWith` + `resolveReferencePath`) — the same two functions
+`WorkflowOrchestrator` calls. There is no second parser here, which is what keeps
+a recipe behaving the same at boot and in a production workflow.
+
+What Tier-1 adds is the SCOPE, and only the scope
+(`src/utils/stepReferences.js`):
+
+- `input` is the only field expanded. `expect`, `service`, `operation` and
+  `depends_on` are read literally — the format names three expansion sites and
+  none of them is `expect`
+  ([variable-references.md](../../../docs/biz/40-cookbooks/variable-references.md)
+  § Limitations).
+- A step entry is spelled the way
+  [`format.md`](../../../docs/biz/40-cookbooks/format.md) § Runtime context
+  (`context.steps`)
+  spells it: the step definition plus `output` and `_execution`, addressed by
+  `step_id`.
+- `output` appears on a step that PASSED. A failed step is recorded with its
+  status alone, so a reference into it stays literal and the failing input shows
+  the reader which step did not deliver.
+- The scope is per COOKBOOK. A run over a directory gives every cookbook its own,
+  so two recipes may use the same step names.
+- A Tier-1 run has no workflow input and no delivery, so `{{api_input.…}}`,
+  `{{delivery.…}}` and `{{current.…}}` resolve to nothing and stay literal.
+
+### What the runner REFUSES, because production does too
+
+A literal `{{…}}` is the right outcome for a value that is missing at that
+moment — a step that has not run yet, or one that failed. It is the wrong
+outcome for an expression no run could ever resolve, because then a green Tier-1
+certifies a recipe production does not accept. Two such shapes are refused
+BEFORE any step of the cookbook runs, each with its own `Fix:`:
+
+| Written in a step's `input` | Tier-1 | Production |
+|---|---|---|
+| `{{webalizeString(…)}}`, `{{string2file(…)}}` — any `name(…)` | refused: `Step <id> input calls the template helper "<name>"` | the orchestrator evaluates it through its helper registry, and throws on a name that registry does not carry |
+| `{{steps.<id>.…}}` naming no step THIS cookbook defines (`{{steps.0.…}}` included — `0` is a name no recipe declares) | refused: `Step <id> references an undefined step` | 400 `Invalid cookbook references` at submission |
+| `depends_on` naming no step this cookbook defines | refused: `Step <id> depends on an undefined step` | — |
+
+The helper registry is absent from the runner on purpose: a helper reaches its
+own runtime (`@onlineapps/content-resolver`, files, storage), which is not what a
+startup probe may do. A recipe that needs a computed value builds it in an
+earlier step and references that step's output.
+
+The reference half is the receiver's side of the owner's 2026-09-02 decision
+([`cookbook-validation-placement.md`](../../../docs/governance/confirmations/cookbook-validation-placement.md)
+001): the gateway answers 400 at submission, and the paths that bypass the
+gateway — a boot run is one — refuse it themselves. What stays literal is
+unchanged: `{{steps[0].…}}` (the bracket form is not a step reference),
+`{{api_input.…}}`, `{{context.…}}`, `{{current.…}}`, and a reference into a
+step that is defined but has not produced anything yet.
+
+Why the runner gained this: biz-converter's boot recipe needed a row that only a
+TEST_ONLY seed supplies, so on production Tier-1 answered `NOT_CONVERTIBLE` and
+the container restarted in a loop. The owner's decision was that the recipe stays
+as written and the runner learns what the orchestrator already does —
+`api/docs/governance/confirmations/converter-boot-cookbook.md` 001.
+
+---
+
+## The CI database account is the service's own (`setup-db-account`)
+
+`db-migrations-first-deploy` 001 says it in one line: **migrace nikdy pod
+rootem.** Production applies a service's migration set as `oagen_<service>`, an
+account granted its own schemas and nothing else. Until d.567 seven biz
+pipelines applied the SAME set under `DB_USER: "root"`, so CI proved the
+migrations under rights no production box grants.
+
+`setup-db-account` closes that gap. It runs **first** in `before_script` and is
+the **only** step of the pipeline that uses the database root account:
+
+```yaml
+  before_script:
+    - npx oa-biz-ci-gate setup-db-account   # the one root step
+    - npm run ci:gate:setup                 # …and everything after it is the service
+```
+
+Three facts, three owners, none of them invented by the command:
+
+| Fact | Owner |
+|---|---|
+| the schema | `database.schema` of `config/service/integration-contract.json` — what `setup-db` builds |
+| the account | `DB_USER` of `config/env-templates/<service>.env` — the declaration uniform row `D-DB-ACCOUNT` measures |
+| the statements | `src/utils/dbAccountGrants.js` — the same definition the production runbook installs from |
+
+The job supplies the credentials, and the two identities are named **separately**
+(`architecture-principles.md` §8 — the whole point is that they stop being one
+value):
+
+| Variable | What it is |
+|---|---|
+| `CI_DB_ROOT_USER` / `CI_DB_ROOT_PASSWORD` | the administrative account of the database sidecar, used by this step alone |
+| `DB_USER` | the account every later step connects as; it must equal what the env template declares, and the command refuses the job otherwise |
+| `DB_PASSWORD` | the throwaway password the account is **created with** and connects with — an env template declares the key, never the secret |
+
+A service whose contract declares no `database` block reports `NOT APPLICABLE`
+and exits 0, the way `setup-db` does. Neither password is ever printed, on any
+path.
+
+**CI gets one grant production does not**: `` `<schema>\_%` ``, the throwaway
+namespace an integration tier builds into (`src/utils/throwawaySchema.js`). The
+`_` is escaped, so the grant stays inside one service — unescaped it is a LIKE
+wildcard, and `oagen_meta_%` would also match `oagen_metadata`.
+
 ---
 
 ## Environment contract (`env` block)
@@ -320,6 +521,18 @@ a stateless service is silent — `pdfgen` is the measured case.
   (confirmation `db-accounts-per-service` 001: root stops being an operational identity —
   it was the identity of nine containers across eight repositories). A repository that
   declares a database and no `DB_USER` is a finding and not a silence.
+* **`D-DB-CI-ACCOUNT`** — the row above measures the DECLARATION; this one measures the
+  one environment where that migration set is applied every day. Measured 2026-09-16:
+  seven of eight biz pipelines set `DB_USER: "root"` in their `test` job while declaring
+  `oagen_<service>` in the template, so CI proved the set under rights no production box
+  grants — the gap `db-migrations-first-deploy` 001 names ("migrace nikdy pod rootem") in
+  the only place a migration can be tried before a deploy. It reports that value, and a
+  `ci:gate:setup` with no `setup-db-account` step before it. A SEPARATE row rather than a
+  wider `D-DB-ACCOUNT`: another file, another fix, and one row with two fixes is two
+  mechanisms under one name (`automation-gates.md` §1.2). It reads the lines OUTSIDE the
+  `oa-ci v1` block, which is `G-CI`'s, and it asks WHO the database steps run as —
+  deliberately not WHETHER a repository runs them, since a job that builds no schema has
+  no account for the step to create.
 
 One more row about the database sits outside this section on purpose. **`X-DB-CONFIG`**
 is in `files.forbidden`, beside `X-HOOKS` and `X-PREVAL`, and it forbids one path:
@@ -373,6 +586,17 @@ the test precisely so that the next file cannot be exempted by editing a test
 behind two files that had no row at all: `gitignore` (now `F-GITIGNORE`) and
 `.gitlab-ci.yml` (now `G-CI`).
 
+The same suite reads the other two directions, which were silent until d.511 and silent in
+a worse way, because nothing reads a `from:` reference until a run needs it. Every
+`from: { package }` reference the manifest makes must name a file this package carries:
+`describeFromProblem` (`manifestShape.js`) checks a reference's SHAPE and never whether the
+file is there, so a template file renamed or deleted left every suite green here and threw
+`[ManifestDiscovery] Packaged file not found` later — inside whichever repository ran the
+uniform next, a service's CI or a container at boot. And every `files.own.allowed` entry
+must have something behind it in the template, so the class stays a decision about real
+files rather than a list nobody re-derives. Both read the references through `collectRows`,
+the manifest's own walk, so a row that moves into another block cannot fall out of them.
+
 #### `.gitignore`: the `contains` class
 
 `F-GITIGNORE` compares the ignore ENTRIES the packaged template declares against the
@@ -512,9 +736,9 @@ severity means it never stops one.
 ### Step 7 and the deployability signal
 
 The same check is step **7/7** of the boot validation (`ValidationOrchestrator`), so a
-service measures itself at every start against the manifest its pin selected. The two
-blocking severities have different consequences, and that difference is the point
-(confirmation `biz-service-manifest` 001 §4):
+service started from a git checkout measures itself at every start against the manifest
+its pin selected. The two blocking severities have different consequences, and that
+difference is the point (confirmation `biz-service-manifest` 001 §4):
 
 | Severity | Boot | `results` | What the operator sees |
 |---|---|---|---|
@@ -550,8 +774,34 @@ belongs to the uniform (`verdict.incomplete` in the manifest, with `{count}` and
 in it), never to the renderer: a library says `publish row(s)` there, and
 `PUBLISHABLE — no findings` where nothing was skipped.
 
-The same verdict is written, in the same step, to **`ci/deployability.json`** of the
-service root, which `deploy-production` reads and refuses on a single row. The `oa-validate`
+#### Outside a git checkout the step does not measure (d.592)
+
+A production image is not a checkout and carries neither `docker-compose.yml` nor
+`README.md`, so the uniform measured THERE reports absences that say nothing about the
+repository — 12 findings for a healthy service. Owner decision 2026-09-17 (confirmation
+`biz-service-manifest` 011): the step then reports NOT RUN, in one line, and measures
+nothing:
+
+```
+[ValidationOrchestrator] NOT RUN  manifest conformance — this tree is not a git checkout
+(git ls-files could not answer), so what a clone would receive cannot be read — a container
+and an exported tarball are in exactly this state. Deployability is proven per commit by
+the CI job `validate-uniform` over the checkout (confirmation biz-service-manifest 010).
+```
+
+`results.deployable` is then `null`, which is NOT MEASURED — a different statement from
+`false`, which is why the field has three states. No banner, no table, and **no
+`ci/deployability.json`**: the file IS a verdict, and this run reached none. The probe is
+the one `X-IGNORED` already used (`src/manifest/gitCheckout.js`), so the row and the step
+cannot answer the same question differently.
+
+What proves deployability is the CI job `validate-uniform`, from every commit, over the
+checkout (confirmation `biz-service-manifest` 010) — the only place that can see what a
+clone receives.
+
+The verdict of a run that DID measure is written, in the same step, to
+**`ci/deployability.json`** of the service root, which `deploy-production` reads and
+refuses on a single row. The `oa-validate`
 CLI writes the same file, through the same builder and writer
 (`src/manifest/deployabilitySignal.js`), for the service run it just printed — one file
 shape with two producers, never two shapes:
@@ -570,10 +820,10 @@ shape with two producers, never two shapes:
 ```
 
 **Two claims, not one.** `deployable` says nothing blocked among the rows that RAN;
-`complete` says no row that CAN block this bearer was skipped. Inside a service container
-the rows reading the workspace cannot run at all, so a signal is routinely deployable and
-incomplete at once — and a gate reading only the first was honouring a `--skip` nobody had
-flagged (`automation-gates.md` §1.5). **The deploy gate takes a signal only when both are
+`complete` says no row that CAN block this bearer was skipped. A run from a checkout that
+cannot reach the workspace root (the `--workspace` that names it) answers the workspace
+rows NOT RUN, so its signal is deployable and incomplete at once — and a gate reading only
+the first was honouring a `--skip` nobody had flagged (`automation-gates.md` §1.5). **The deploy gate takes a signal only when both are
 true**; the complete run is produced from the api checkout with
 `npx oa-validate --workspace <root> <service root>`, and since d.232 that run writes the
 file it is asked for. A service root OUTSIDE the workspace root cannot produce a complete
@@ -590,7 +840,8 @@ rows that could not look are not passes, and each entry carries the `severity` o
 that did not run — which is what decides `complete`.
 
 There is no switch that skips the step and none that moves the file — one path,
-unbypassable.
+unbypassable. What decides whether the step measures is not a flag anybody sets but
+whether git can answer in the tree it was handed (above).
 
 ### Two run modes, three scopes
 
@@ -628,19 +879,71 @@ the directories it walks (`requiresSiblings({ row, block })`, derived from the r
 patterns), and the runner verifies them before running it:
 
 ```
-NOT RUN  L-CONSUMER — sibling root api_biz is not present in this checkout
+NOT RUN  L-CONSUMER — sibling root api_biz is not present in this checkout - an absent
+directory is not an empty one, so this row is not answered. Fix: run with --workspace
+pointing at a checkout that carries api_biz.
 ```
 
 Measured against a `git archive` export of this repository on 2026-09-09: without the gate,
 `--library --all` raised a blocking `L-CONSUMER` on `conn-base-db` about files nobody
 opened. Never a finding, never a pass (`automation-gates.md` §5).
 
+The line carries its fix because of where it is read. Measured 2026-09-15 over a
+`git archive` export of `api_biz/hello-service` placed beside an api clone with no
+`api_biz/` around them: the reason ended at "is not present in this checkout", and the
+report's own incomplete-run sentence — the one that does name the command — prints only on
+a CLEAR verdict (`report.js` § `describeClearOutcome`), so a run that also had findings
+named no fix anywhere. `automation-gates.md` §1 requirement 4 asks for the exact command,
+and the sync half of this package already gave it (`src/sync/uniformFiles.js` § `planRow`).
+The command is derived from the missing roots, so a row that starts reading a new sibling
+needs no second edit.
+
+In the layout the deploy gate demands — the service at `<root>/api_biz/<service>` beside
+`<root>/api`, which `templates/business-service/.gitlab-ci.yml` asks GitLab for through
+`GIT_CLONE_PATH` — nothing is skipped: measured the same day over that export, `notRun` is
+empty and both `U-ORPHAN` and `R-NODE` decide. `R-NODE` left the NOT RUN list in d.238 and
+decides even where `api_biz` is absent, because the platform major it reads is this
+package's own `engines.node`.
+
 One case is neither mode: a service root that does not lie under the given workspace root.
 Filtering there would drop every finding and the empty table would read as "the row
 looked and found nothing", so each row that needs the workspace — `workspace` and `bearer`
 alike — is reported `NOT RUN — service root is outside the workspace root <root>` instead,
 in the banner and in the signal alike.
 
+### Which names the image reads (`oa-validate --env-reads`)
+
+A third mode, and not a verdict at all: it answers ONE question — which environment
+names this service reads — for a deploy gate that must not judge a service's `.env`
+against the platform's whole key set.
+
+```bash
+mapfile -t reads < <(npx oa-validate --env-reads "$repo") || exit 1
+for key in "${reads[@]}"; do
+  grep -q "^${key}=" "$env_file" || fail "$key is declared and missing"
+done
+```
+
+Names on stdout, one per line, sorted, without duplicates, and nothing else: no
+banner, no table, no `ci/deployability.json`. Exit 0 with the list, exit 2 with an
+`[oa-validate] … Fix: …` line on stderr where there is no readable
+`config/service/integration-contract.json` — a gate that cannot get the set must
+stop, never continue with an empty one. The mode combines with no other option
+(`--json`, `--library`, `--all`, `--workspace` are refused), because every other
+mode prints a verdict into the same stdout.
+
+The set is the one row `C-ENV-READS` measures the repository against — the contract's
+`env` block, the `${VAR}` placeholders of `config/service/*.json`, and the endpoint
+variables of the connectors the contract declares required — so the gate and the
+uniform cannot disagree about what a service reads. It is deliberately NOT a grep for
+`process.env`: most of the platform's environment is read inside installed libraries,
+where a grep over `src/` sees nothing, and in a gate a set too small means a key
+silently unchecked.
+
+The other direction is deliberate too: a name the SOURCE reads that the contract does
+not declare is absent here. That is a blocking finding of `C-ENV-READS`, with its own
+fix — and a gate must not demand a value for a key nobody owns.
+
 ### Uniforma knihoven (`oa-validate --library`)
 
 `manifests/library.manifest.json` is the same concept for the shared libraries, in the
@@ -875,12 +1178,17 @@ class — `src/**`, `tests/**`, the content of `docs/**` — are never written.
 file, and since d.229 most of them read a file this package carries. The predicate is the
 one the manifest run uses (`rowNeedsWorkspace`), so the `fix` command of `F-INIT`,
 `F-JEST` and `F-RUNNER` can be typed where their finding is now raised: inside the service
-image. A row that does need one is printed `NOT RUN` by name, never skipped in silence.
-
-A row the manifest does not make renderable is printed `NOT RUN` with the reason instead
-of being filled from a guess. Today that is `G-PROD-IMAGE` and `G-SETUP`: they declare no
-`from:` reference, so nothing says what their content is rendered from — the first is a
-requirement ABOUT a file, the second a directory that must exist. A row whose file
+image. A row that does need one is printed `NOT RUN` by name with the `--workspace` fix,
+never skipped in silence.
+
+A row the manifest does not make renderable is **not a row of this run**. Today that is
+`G-PROD-IMAGE` and `G-SETUP`: they declare no `from:` reference, so nothing says what
+their content would be rendered from — the first is a requirement ABOUT a file, the second
+a directory that must exist, and `oa-validate` is the run that answers both. Until d.507
+the sync planned them and printed `NOT RUN`, which every `--check` in every repository
+ended on: a line naming a state its reader could do nothing about, with no `Fix`
+(`automation-gates.md` §5 and §1 requirement 4). Naming a requirement path as an argument
+is refused by what it is, with the run that does answer it. A row whose file
 blocks the write — an `init.sh` carrying no block marker, where inserting one would mean
 choosing a position among somebody's own install steps; an installation document missing a
 section, where writing one would mean rewriting somebody's prose — is printed `BLOCKED`
@@ -1107,6 +1415,16 @@ services/my-service/
 ```
 
 **Proof Lifecycle:**
+- **Every number in it is a measurement.** `testsRun`, `testsPassed`,
+  `testsFailed` and `durationMs` are read from the aggregate the runner returns,
+  and a missing one is refused by name rather than filled with `0`: the same
+  number would otherwise stand for both "measured, and it was zero" and "nobody
+  measured this", with no way for a reader to tell them apart. A run that
+  executed nothing — a service whose `tests/cookbooks/` holds no `.json` file —
+  is refused outright: it has no failing step, so it used to publish a signed
+  proof asserting a passing validation of zero tests, which
+  `ValidationProofCodec.decode()` then refused at the registry as `NO_TESTS`,
+  days later and far from the cause.
 - **Written:** on every successful validation, i.e. on every boot. There is no
   proof cache — the one that existed skipped steps 1-3 and 5-6 to save 6 ms and
   bought a window of up to seven days in which validation asserted something no

package/docs/DESIGN.md

@@ -25,17 +25,31 @@ surface was removed together with the now-retired `ServiceValidator` /
 - **Production-ready** — the exact same code runs locally, in CI and during
   wrapper startup.
 - **Fail-fast** — missing logger, missing operations.json: immediate throw.
-  `serviceUrl` is *not* among them: it fed the retired `/health` probe and
-  nothing reads it (ADR 0005). It is accepted and ignored so existing callers
-  keep working.
+  `serviceUrl` is not among them because it is gone: it fed the retired
+  `/health` probe (ADR 0005), and neither `ValidationOrchestrator` nor
+  `CookbookTestRunner` reads, stores or documents it any more
+  (`tests/unit/ValidationOrchestrator.unit.test.js` § Constructor). Nor is one
+  passed: `ServiceWrapper._createValidationOrchestrator()` builds the
+  orchestrator from four options and this is not one of them
+  (`tests/unit/preValidation.test.js` § the runner is built with the service
+  identity and no retired options).
 
 ## Components
 
-### Mock Infrastructure (for unit tests)
+### Internal test doubles — not published
 
-- `MockMQClient` — in-memory message queue simulation
-- `MockRegistry` — service registry simulation
-- `MockStorage` — object storage simulation
+The package exports no infrastructure doubles. `mockInfrastructure`, the option
+that built them, is retired (d.576): a cookbook step is dispatched in-process
+against the service's own v3 handler, so there is no transport to stand in for
+and the database a handler reaches is the real one
+(`tests/unit/mockInfrastructureRetired.test.js`).
+
+- `MockRegistry` — the registry stand-in of `helpers/createServiceReadinessTests`,
+  internal to the package
+- `MockMQClient` — used by `tests/unit/RegistrationFlow.test.js` alone
+
+A double with no consumer is not kept: `MockStorage` was deleted with its own
+unit test in d.583 (`tests/unit/mockInfrastructureRetired.test.js`).
 
 ### Production Validation
 
@@ -51,7 +65,15 @@ surface was removed together with the now-retired `ServiceValidator` /
 - `ValidationProofGenerator` — fingerprint + codec helpers
 - `CookbookTestRunner` — cookbook execution probe. The single rail: the second
   one, `WorkflowTestRunner`, was deleted on 2026-09-05 (no consumer anywhere in
-  the workspace, and it read the banned `step.id`)
+  the workspace, and it read the banned `step.id`). A step's `input` may
+  reference an earlier step's output, so a recipe can build, use and remove its
+  own fixture instead of depending on a seed one environment has and another does
+  not (owner: `../../../docs/governance/confirmations/converter-boot-cookbook.md`
+  001). The syntax belongs to the cookbook format
+  ([variable-references.md](../../../docs/biz/40-cookbooks/variable-references.md))
+  and the traversal to `@onlineapps/cookbook-core`, the same rail
+  `WorkflowOrchestrator` runs on; `src/utils/stepReferences.js` supplies only the
+  run scope, and README § "A recipe builds its own fixture" says what it holds
 - `CookbookTestUtils` — static cookbook-structure validators
 
 ### Test Suite Helpers
@@ -79,7 +101,8 @@ surface was removed together with the now-retired `ServiceValidator` /
 
 1. **Service contract** — structure, config files and the v3 operations rules
 2. **Environment contract** — every name declared `env.required` is set
-3. **Workflow capability** — can process cookbooks, in-process, with mocks
+3. **Workflow capability** — can process cookbooks, in-process, including a
+   recipe whose later steps read what its earlier steps returned
 4. **Connector contract** — the two declarations agree and the environment backs them
 
 ## What We DO NOT Test