@onlineapps/conn-orch-validator 7.0.0 → 8.0.0

package/README.md

@@ -1,3 +1,14 @@
+> Status: current
+> Owns: the validation a service runs over its own readiness — the uniform manifests, the cookbook test runner, and the mocks that stand in for infrastructure
+
+<!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
+Uniform: [library/orchestration](./manifests/library.manifest.json)
+
+Duty sections that apply:
+
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+<!-- END GENERATED: library-uniform -->
+
 # @onlineapps/conn-orch-validator
 
 **Validation Orchestrator for OA Drive Microservices**
@@ -9,7 +20,7 @@ Coordinates validation across ALL layers (base, infra, orch, business) to ensure
 This is **NOT** a development testing tool. This is a **production validation orchestrator** that:
 
 1. **Validates service structure** - directories, files, configuration
-2. **Validates configuration** - `config.json`, `operations.json` compliance
+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
@@ -38,16 +49,21 @@ runs Tier-1 validation in phase 0.2 — before MQ connects, before registration.
 
 ---
 
-## Validation Process (6 Steps)
+## Validation Process (7 Steps)
 
 1. **Service Structure** - directories and files exist
-2. **Config Files** - valid JSON, required fields
+2. **Config Files** - rows `C-SERVICE`, `C-OPS` and `C-CONTRACT` of the uniform manifest, run here so a
+   broken configuration stops the boot before steps 3-6; step 7 leaves them out because they are already
+   answered. The step decides nothing of its own — until d.224 it re-implemented two of those rules with
+   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)
 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)
 
-**Output:** Validation proof saved to `conn-runtime/validation-proof.json`
+**Output:** Validation proof saved to `conn-runtime/validation-proof.json`, deployability
+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.
@@ -90,6 +106,970 @@ legitimate state until every repo adopts the declaration, and never silent.
 
 ---
 
+## Test-coverage contract (`stackTiers` block)
+
+Every test file the service's jest config matches must be RUN somewhere: by the
+`test:all` chain, or by a script the contract declares as a stack tier with the
+reason it cannot run in `test:all`.
+
+```
+oa-biz-ci-gate verify-test-coverage [--service-root <path>]
+```
+
+Also folded into `verify-contract`, so a version bump activates it.
+
+| Set | What | How it is measured |
+|---|---|---|
+| T | files the service jest config matches | `jest --listTests` |
+| A | files the `test:all` chain runs | the chain decomposed `npm run …` → jest, each invocation asked `--listTests` |
+| B | files the declared stack tiers run | the same, per declared script |
+
+The question is always put to **jest**, and to the service's own jest resolved
+from its `node_modules` — a parse of `jest --config jest.config.js tests/unit`
+answers with the shape of the command, and a different jest version resolves a
+different `testMatch`. The gate therefore needs the dependencies installed:
+run it after `npm ci`.
+
+A file in T that is in neither A nor B is the defect: a suite that runs nowhere
+fails nowhere, so it looks like coverage and proves nothing.
+
+### Declaring a stack tier
+
+```json
+"stackTiers": [
+  { "script": "test:e2e", "requires": "needs a live biz-hello consumer on biz-hello.workflow; CI has no service runtime" }
+]
+```
+
+`requires` is mandatory — a tier nobody can justify is the one nobody dares
+delete, and a reader of a pipeline that does not contain the suite must be able
+to see why. There is no exemption by directory name: `tests/e2e/**` is not
+self-evidently un-runnable, and a name cannot carry a reason.
+
+| Violation | Reported as |
+|---|---|
+| a matched file that neither `test:all` nor a declaration reaches | `TEST_RUNS_NOWHERE` |
+| a declared script `package.json` does not define | `STACK_TIER_SCRIPT` |
+| a declared script that lists 0 test files | `STACK_TIER_EMPTY` |
+| a declared script whose tests `test:all` already runs | `STACK_TIER_IN_TEST_ALL` |
+| a step in the chain that is neither `npm run <script>` nor a jest command | `TEST_ALL_CHAIN` |
+| an entry without `requires` | refused when the contract loads |
+
+**Measurement boundary, printed on every run:** the gate never checks whether a
+declared stack tier is actually RUN anywhere. The declaration says why the suite
+cannot run in `test:all`; it does not claim something else runs it.
+
+A contract with no `stackTiers` block is the ordinary case — it means every test
+file is reachable from `test:all`.
+
+---
+
+## Manifest uniformy (`oa-validate`)
+
+`manifests/biz-service.manifest.json` is the machine-readable declaration of what a
+biz service is: sections by concern, one row per rule, each row carrying `id`,
+`severity`, `owner`, `fix`, `doc` and the name of the `check` that decides it. The
+manifest ships inside this package, so **the manifest version is the validator
+version** — a service pins the validator exactly and thereby pins the shape it is
+measured against. There is no version field in the file.
+
+```bash
+npx oa-validate                          # the current directory, workspace derived from this package
+npx oa-validate ../converter --workspace /path/to/workspace
+npx oa-validate . --json                 # the same run as data
+```
+
+One table (`id · severity · where · what · fix · owner`), the `doc` pointer of every
+reported row, and exit `0` / `1`; `2` when the run could not start. Rows that resolve
+a `from:` reference into the workspace (`api/config/services.json`, `api/.nvmrc`) are
+printed `NOT RUN` where that reference cannot be read, and never counted as passing.
+
+**A service run also RECORDS its verdict**, in `<serviceRoot>/ci/deployability.json` —
+the machine half described under [Step 7 and the deployability signal](#step-7-and-the-deployability-signal),
+written by the same builder and the same writer that step uses. That is what makes the
+run from the api checkout usable by a deploy gate: until d.232 the only writer was step 7,
+which runs inside the service container where the workspace SSOTs are absent, so every
+signal that existed said `complete: false` — and a gate asking for `deployable && complete`
+could never be satisfied, because the run that IS complete left no file behind. The
+workspace mode and `--library` write nothing: the signal is a verdict about one service
+tree, and neither run has one. An unwritable service root ends the run with exit `2`,
+after the table has been printed.
+
+**A rendered template directory is compared minus what the template ignores.** The
+template's own `.gitignore` is the one place saying which paths of a service tree are
+generated output, and `oa-sync-template template --check` reads it on both sides
+(`sync/serviceTemplate.js` § `listOutputFiles`). `oa-validate` records its verdict in the
+tree it measured (d.232), so a run over `api/templates/business-service` leaves
+`ci/deployability.json` there; git does not see it, and since d.237 neither does the
+mirror check.
+
+**A reference into this package runs everywhere.** The template ships INSIDE the
+validator (001 §2, §5), so the rows comparing a service against it reference the packaged
+file — `from: { "package": "templates/business-service/jest.config.js", "text": true }` —
+and resolve it from the package's own location. Those rows therefore answer in a service
+container and in a service's own CI checkout, which is exactly where the uniform is for.
+Measured over `api_biz/converter` on 2026-09-09: a run with no workspace used to report 13
+rows `NOT RUN`, F-RUNNER and G-SHARED-ENV among them, and raised neither of the two real
+findings they carry; it now reports the same findings as the workspace run, with
+`U-ORPHAN` and the five `D-*` rows the only ones left `NOT RUN`. What still needs the
+workspace is what reads something outside this package. `R-NODE` left that list in d.238:
+the platform Node major now comes from this package's own `engines.node`, which the
+library uniform's `L-ENGINES` holds equal to `api/.nvmrc`, so it is a checked projection
+of the SSOT that travels with the pin rather than a second copy of the number
+(confirmation `biz-service-manifest` 006 point 2).
+
+**Where the workspace comes from.** The run derives it from where THIS package sits:
+the checkout carrying `config/services.json` is the api checkout, and the workspace is
+its parent. What that checkout directory is CALLED does not matter — a CI job that
+clones into `infra-mono` resolves the same workspace as a developer with `api`.
+`--workspace` is the explicit override and always wins. The copy installed in a
+service's `node_modules` sits inside that service rather than beside the api checkout,
+so it resolves no workspace of its own and the rows reading the SSOT print `NOT RUN`
+with the reason — which is what a run inside a service container does.
+
+Rows, categories and discovery patterns are the manifest's own facts; every other
+fact is a `from:` reference to the file that owns it, and the suite
+`tests/unit/manifestShape.test.js` fails the build on a copied list.
+
+The service uniform is declared in eight sections, and what each one is for — with the
+reason every row exists — is confirmation
+[`biz-service-manifest`](../../../docs/governance/confirmations/biz-service-manifest.md) §2
+and §19:
+`discovery` (which directories wear the uniform, and who says they exist),
+`files` (byte-identical to the template, generated from it, carrying the platform's
+entries among its own, or forbidden outright),
+`scripts` (the bodies a suite is run with, and what may never run without being named),
+`tooling` (the repository's own `scripts/`, and what a reader can learn about one before
+running it), `config` (the files a service is configured by), `runtime` (the Node major,
+the memory norm and the ports it may not publish), `db` (whether it has a database, what
+its SQL package is called and which account reaches it) and `docs` (what the service's own
+documentation tree may not say). A row that cites a checker this package already runs — the deploy contract, the
+installation contract, the environment contract, the documentation lint — names its
+`requirement` or its `rule` and adds no rule of its own: the manifest cites, it never
+restates (confirmation 004 point 4).
+
+Beside the sections sits `guidance`: a duty the confirmations name for which nothing
+can decide the answer yet. It carries a `why` and a `doc` and never a `check` or a
+`severity`, because it produces no finding — "no check, so not a rule" (001 §6), said
+out loud rather than left as a row that reports nothing and reads as a pass.
+
+#### The script rows (`tooling`)
+
+*(The word is used twice in this package for two different things, and they never meet:
+here it is a SECTION of the service uniform, and in the library uniform below it is a
+`category` a package declares. Different manifests, different axes.)*
+
+`S-SCRIPTS` runs the SCRIPTS-STANDARD header rules over `scripts/**` of the repository:
+the five fields in order with the right comment marker, the closed `Status` and `Shell`
+vocabularies, the blank comment line, every `@see` target existing, and the
+`sourced`/`required` words in the two library directories. What an `Owns:` sentence SAYS
+is true no linter can check; content accuracy stays review, said plainly.
+
+Which of those two words a library owes is decided by its EXTENSION, not by which of the
+two directories it lies in (`S007`, d.249). The directory says one thing only — "a library,
+not an entry point", so the `Usage:` line carries a word instead of a command line — and
+`.sh` is `sourced` while a Node module is `required`. Until d.249 the rule read
+`scripts/lib/` as shell and `scripts/ci/lib/` as Node, which is what the tree looked like
+when it was written and is not what the tree is: BIZ-ingest measured a Node library under
+`scripts/lib/` in their repository and seven in meta's, none of which could go green
+without writing `sourced` about a file nothing sources. A rule satisfied only by an untrue
+sentence is the one `architecture-principles.md` §10 forbids weakening a test to meet, so
+the rule moved and the files stayed. Measured 2026-09-11, before and after: ingest 1
+finding → 0, meta 7 → 0, `api/scripts` 0 → 0 across 105 files.
+
+The rules ship in this package — `src/lint/scripts/lintScripts.js`, with
+`oa-lint-scripts` as its command — and that is the whole reason the row can exist.
+They used to be a file of the `api` checkout, and a file of one checkout cannot decide a
+rule about eight repositories: a service has no `api/` directory in its own CI and none
+at all inside its image. `api/scripts/ci/lint-scripts.mjs` now calls this module and holds
+no rule of its own, so `npm run scripts:lint`, the CI job `validate-scripts` and this row
+are one implementation (confirmation `biz-service-manifest` 003 §19).
+
+One thing in those rules needs a second root, and only when it is used: a script may cite
+`api/docs/…`, which names the api checkout beside the repository rather than a `docs/` of
+its own. With the workspace reachable the citation is resolved there; without it the lint
+returns the target as UNRESOLVED and the row is `NOT RUN` with the targets named — a run
+that could not look must not report a pass. Measured 2026-09-10 over the eight services:
+47 `@see` lines under their scripts directories, 4 of them with that prefix — and 86
+scripts of which not one carried a header.
+
+#### The SQL rows (`db`)
+
+Beside `D-DB-CONSISTENT` (does the repository agree with what it declared) and the two
+rows citing the installation contract, three rows say what the package is CALLED and who
+reaches it. All three ask their question only of a repository that DECLARES a database, so
+a stateless service is silent — `pdfgen` is the measured case.
+
+* **`D-DB-NAMING`** — `migrations/*.sql` reads the shape
+  `api/docs/biz/70-contracts/database-contract.md` §5 prescribes: three digits, an
+  underscore, a lowercase description. The row reads that node back rather than inventing
+  a stricter rule of its own, so `000_baseline.sql` — §5's own example, and an applied
+  migration by §8 — is a name and not a finding. No leading verb is demanded either,
+  because the measured counter-example is right (`009_cnv_batch_drop_pending_status.sql`
+  opens with a table prefix), and the three digits are not decoration (`999a_` sorts after
+  `999_` only by accident of the byte after the digits). The convention reaches one level
+  and stops: what `BASELINE/` and `SEED/**` must CARRY is the installation contract's §4,
+  which `D-DB-HEADERS` already checks, and that contract names no shape for their file
+  names at all.
+* **`D-DB-README`** — the installation contract §3 asks a repository with a database for
+  four things and `SQL_PACKAGE` checks three of them. The fourth is `migrations/README.md`,
+  the documented execution order that reproduces a working instance, and until d.218
+  nothing looked for it.
+* **`D-DB-ACCOUNT`** — `DB_USER` in this service's env template reads
+  `oagen_<shortname>`, from the same derivation `C-IDENTITY` holds `database.schema` to
+  (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.
+
+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:
+`src/config/database.js`. Seven of the eight services carried that file — a module
+singleton building its own Sequelize — beside `@onlineapps/conn-base-db`, whose
+`createSequelize` exists to be the one connection factory
+(`.claude/rules/change-discipline.md` § One rail per concern); the 8.0.0 cascade commit of
+each service switches its importers and deletes the file, and this row is what keeps it
+deleted (confirmation `biz-service-manifest` 009). Unlike the three rows above it does NOT
+ask `requiredConnectors.db` first: 009 names the path with no condition on it, and a
+service that declared no database has even less business carrying a connection factory. A
+repository without the file is silent either way — `pdfgen` is the measured case here too.
+
+#### What `.gitignore` may NOT hide: the `tracked` class
+
+`F-GITIGNORE` above says what the file must CONTAIN. **`X-IGNORED`** (`files.tracked`,
+check `git-tracked`) says what it may not cover, and the two together are the answer to the
+owner's sentence: a biz service has no right to ignore something the uniform requires.
+
+Every file row reads the WORKING TREE. What a clone, a CI checkout and the production image
+receive is what git TRACKS, and those are not the same thing — measured 2026-09-10 on a copy
+of converter outside the repository:
+
+| run | result |
+|---|---|
+| `init.sh` and `jest.config.js` in `.gitignore`, both files on disk | `F-INIT`, `F-JEST`: **no findings** |
+| the same two files deleted — what a clean clone has | both fire, NOT DEPLOYABLE |
+
+Developer green, CI and image red. The row reads **no list of its own**: the paths are the
+ones `files.identical`, `files.contains` and `files.generated` already name, read from the
+block it sits in, so a new file row extends this one too (004 point 2). A directory among
+them covers its whole tree — `scripts/` is the case that matters, because `S-SCRIPTS` lints
+the headers of scripts the clone may never receive. `files.forbidden` is excluded on
+purpose (demanding a banned file be tracked is a contradiction), and so is `files.own`.
+
+The question is TRACKED, not IGNORED: a tracked file matching an ignore line is harmless,
+an untracked one is gone from the clone whether a rule covers it or not. `git check-ignore`
+is asked only about the files that already failed, because that is what turns the finding
+into an edit. Outside a git checkout — a container, an exported tarball — the row is NOT RUN
+with that reason, never a pass.
+
+#### The template's own completeness: the `own` class
+
+`files.own` is not an exemption list; it is where the manifest says, for each file the
+template carries, that the SERVICE decides its content. `tests/unit/templateCoverage.test.js`
+walks `templates/business-service/**` and demands, for every file, either a row naming its
+path or membership of that class. Adding a file to the template is therefore a decision
+about who guards it, taken in the manifest — and the list is in the manifest rather than in
+the test precisely so that the next file cannot be exempted by editing a test
+(`.claude/rules/change-discipline.md` § One rail per concern). It was the missing check
+behind two files that had no row at all: `gitignore` (now `F-GITIGNORE`) and
+`.gitlab-ci.yml` (now `G-CI`).
+
+#### `.gitignore`: the `contains` class
+
+`F-GITIGNORE` compares the ignore ENTRIES the packaged template declares against the
+entries the repository declares — any order, every other line left alone. The class exists
+because this file is neither of the other two: it cannot be `identical` (a repository
+ignores its own scratch directories, and nine different files were measured across the
+eight services), and nothing renders it from a declaration. What must be true of it is a
+SET: every path this platform WRITES into a repository is a path git must not see, and
+`ci/deployability.json` is the measured case — `oa-validate` and the pre-push hook of
+confirmation 006 both write it, and in four of the eight repositories every run left it
+untracked. A narrower pattern does not satisfy the entry it narrows:
+`config/env-active/*.env` leaves every non-`.env` file in a directory of live secrets
+committable.
+
+The generator still writes a labelled `# --- oa-ignore v1` block, so a reader can tell the
+platform's lines from the repository's own — but the block is the FIX's shape and never
+the check's, and the renderer removes an existing one before it computes what is missing,
+so a second run adds no second block.
+
+#### The documentation rows (`docs`)
+
+The rules of `<service>/docs/**` already exist and already have an owner:
+`api/scripts/ci/lint-biz-docs.mjs`, held by BIZ-DOCS. So the rows here decide nothing —
+each citing row names the lint rule it stands for, in the lint's own `--rules` syntax,
+and `src/manifest/checks/docsLintBridge.js` runs the lint ONCE per service and hands each
+row the findings of the rules it cites, with the lint's own `file:line`:
+
+| row | cites | what it stands for |
+|---|---|---|
+| `D-PORT` | `F002:http-ports` | no document sends an operator to a port nothing listens on |
+| `D-NPM` | `L016` | a cited npm script is one this repository declares |
+| `D-SCRIPT` | `L007` | a cited script path exists in this repository |
+| `D-RETIRED` | `F002` | no live document teaches a retired concept |
+| `D-HEADER` | `S001,S002` | every node opens with `Parent:` and `Owns:` |
+| `D-LINT` | — | the lint reports nothing else over this tree |
+
+A finding lands on exactly ONE row: the most specific citation wins, so the ban on
+localhost ports goes to `D-PORT` rather than twice, and two rows citing one rule
+equally are a fail-fast.
+
+`D-LINT` is the catch-all and cites nothing — deliberately. What the rows above buy is
+their own `fix` sentence, not coverage: measured 2026-09-09 over the eight repositories,
+80 lint findings of which 16 fell to a citing row, so a tree the documentation gate called
+broken came back DEPLOYABLE here. A citation list on the catch-all would have to be held
+equal to the linter's and would fall behind it the first rule BIZ-DOCS wrote, so the row
+names none and takes every error-graded finding the rows above did not claim.
+
+It counts what the LINT graded `error` — the set its own `--severity error` prints. That
+is the whole of the safeguard: grading belongs to BIZ-DOCS
+(`api/config/biz-docs-lint.json` § severities), so a rule they add at `warn` is visible in
+their run and blocks no deploy until they raise it on their own dated transition
+(`automation-gates.md` §3). The documentation gate itself is unchanged and still lands in
+each repository's CI at zero findings (confirmation
+[`biz-docs-foreign-tree-gate`](../../../docs/governance/confirmations/biz-docs-foreign-tree-gate.md)).
+
+The rows are `bearer`-scoped and declare `api/scripts/ci` as a root they read, so in a
+service image and in a service's own CI — where there is no api checkout — the runner
+reports them `NOT RUN` with that reason. `C-LINT`, the row owning
+`config/biz-docs-lint.tree.json`, lives in this block too: the rows are INVOKED with the
+budget that file declares, so the path is written once, on the row, and the block names
+the row (`tree_config_row`) rather than repeating the path. A tree with no such file is
+reported as undecided rather than clean; an empty `docs/` raises nothing, because the
+absence of the tree is `G-SETUP`'s finding, not a second one with a different fix.
+
+**A rule the lint could not EVALUATE is `NOT RUN`, not a finding.** The linter has its own
+NOT RUN channel — that is what `--allow-missing-siblings` fills — and a ban whose evidence
+probe reads `api_biz/*` is undecidable in a checkout that has no siblings. Measured
+2026-09-10 over `git archive HEAD` into such a directory: the template mirror came back
+`NOT DEPLOYABLE` on `D-PORT` and `D-RETIRED`, whose bans nobody had violated, while
+`U-ORPHAN` in the same run said the honest thing. The two channels of the lint now map onto
+the two of this uniform: its `findings` are findings, its `skipped` list is `NOT RUN`. A
+tree the lint REFUSES outright (no tree config, a broken configuration) stays a finding,
+because that one has a fix somebody can carry out.
+
+`D-NPM` was guidance until 2026-09-10, and the guidance was true while it stood: no rule of
+the lint raised it, and a row citing a rule nobody raises reports nothing and reads as a
+clean tree (001 §6). BIZ-DOCS wrote `L016`, which resolves a cited `npm run <name>` against
+the `package.json` above the tree — exactly one file for a service repository — so the row
+exists now.
+
+#### The three configuration files, and who decides them
+
+Confirmation
+[`biz-service-manifest`](../../../docs/governance/confirmations/biz-service-manifest.md)
+§18 asks that `config/service/config.json`, `operations.json` and
+`integration-contract.json` be decided by schemas shipped with the validator. Two of
+the three already had an owner, so no second notation was introduced for them
+(`change-discipline.md` § One rail per concern):
+
+| file | row | decided by |
+|---|---|---|
+| `operations.json` | `C-OPS` | `service-validator-core` `validateOperationsSchema` — the mirror of the fifteen rules the Registry applies on registration |
+| `integration-contract.json` | `C-CONTRACT` | `utils/bizCiGateContract.js` — the validator the CI gate already runs over this document, so the gate and the table can never disagree about it |
+| `config.json` | `C-SERVICE` | `src/manifest/checks/serviceConfig.js`, which had no owner before |
+
+`C-IDENTITY` is the row about the NAME rather than about one file. `naming.md` derives
+every spelling of a biz service from a single short name, and says why that is not
+tidiness: the gateway compares `service_code` from the entitlement data against the
+service name in a cookbook step character by character, so a second spelling is a request
+that gets refused. The row takes the short name from `service.name` and holds the npm
+`name`, `container_name` in both compose files, `config/env-templates/<shortname>.env`
+with the `env_file` entries loading it, and `database.schema` where the repository
+declares one, to that one name. It reads nothing outside the repository, so it answers in
+a container too. Its workspace half is `U-IDENTITY`, beside `U-ORPHAN`: `directory`,
+`repo` (last path segment) and `container` in `api/config/services.json` against the same
+short name. Measured 2026-09-10 over the eight live services: seven wear one name each and
+`hello-service` wore four.
+
+`C-SERVICE` demands the three keys that were **measured** to have a reader:
+`service.name` (the identity the wrapper registers under), `service.workspaceScoped`
+(an explicit boolean — the wrapper refuses to boot without one, and it decides whether
+`list-workspaces` must exist) and `service.specificationEndpoint`. Everything else the
+file carries is the service's own business and passes untouched.
+
+The same measurement found declarations with **no reader anywhere**, and
+`C-SERVICE-DEAD` (severity `deploy`) refuses them rather than letting each new service
+copy them forward: `service.version` (`ConfigLoader` overwrites it from `package.json`
+on every load), `service.port` (a biz service binds none), `wrapper.registry.url`
+(registration travels over MQ to `registry.register`), `wrapper.tenantContext` (its only
+consumer `createTenantContextMiddleware` and the runtime default were deleted
+together, confirmation
+[`wrapper-tenant-middleware`](../../../docs/governance/confirmations/wrapper-tenant-middleware.md)
+001) and `contractVersion` in the integration contract. The keys themselves are listed
+once, in `DEAD_KEYS` (`src/manifest/checks/serviceConfig.js`), and the manifest row's
+`why` is held equal to that list by its own test — so this paragraph names the class,
+never the count. The fix is always the same sentence — delete the key.
+
+`service.url` is the one entry carrying a **date**: it is dead from wrapper **8.0.0**,
+not today. The published 7.0.0 still throws
+`Missing configuration - service.url is required`, so the key travels WITH the pin, which
+is what confirmation
+[`biz-service-port-url`](../../../docs/governance/confirmations/biz-service-port-url.md)
+001 already said. A rule claiming the key has no reader today would send a service pinned
+to 7.0.0 into a failed boot; the row names the work the cascade carries, and its `deploy`
+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):
+
+| Severity | Boot | `results` | What the operator sees |
+|---|---|---|---|
+| `boot` | refused | `success: false`, the finding in `errors` | the service does not start |
+| `deploy` | **succeeds** | `success: true`, `deployable: false`, the finding in `deployFindings` | the banner below, at every start, until it is gone |
+| `warn` | succeeds | table only | the row in the banner's table |
+
+```
+[ValidationOrchestrator] NOT DEPLOYABLE — 2 finding(s)
+[ValidationOrchestrator] id        severity  where                          what …  fix                                  owner
+[ValidationOrchestrator] X-HOOKS   deploy    hooks/pre-commit               …       rm -f hooks/pre-commit               BIZ-general
+[ValidationOrchestrator] X-PREVAL  deploy    scripts/run-pre-validation.js  …       rm -f scripts/run-pre-validation.js  BIZ-general
+```
+
+A clean run says so in one line, and says what it could not look at, because silence is
+the one outcome a reader cannot interpret and `no findings` alone reads as a proven clean
+bill of health over rows nobody opened. There are three of those lines, and which one is
+printed is decided by WHAT did not run (`report.js` § `describeClearOutcome`, the one
+owner this banner, the `oa-validate` report and the library report all use):
+
+```
+DEPLOYABLE — manifest conformance: no findings
+DEPLOYABLE — manifest conformance: no findings (1 row(s) not run)
+DEPLOYABLE — manifest conformance: no findings, INCOMPLETE: 6 deploy row(s) not run
+(U-ORPHAN, U-IDENTITY, D-PORT, D-SCRIPT, D-RETIRED, D-HEADER). Fix: run the uniform from
+the api checkout — npx oa-validate --workspace <workspace root>
+```
+
+The first is a run that answered every row. The second is a run that missed a row which
+could not have blocked anything (`warn`). The third is a run that missed a row which
+COULD have — and then the verdict is true only of the half that ran. The sentence itself
+belongs to the uniform (`verdict.incomplete` in the manifest, with `{count}` and `{ids}`
+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`
+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:
+
+```json
+{
+  "validator": "@onlineapps/conn-orch-validator",
+  "validatorVersion": "<the version this service pins>",
+  "uniform": "biz-service",
+  "serviceRoot": "/srv/biz-hello",
+  "deployable": false,
+  "complete": false,
+  "findings": [{ "id": "X-HOOKS", "severity": "deploy", "where": "…", "what": "…", "fix": "…", "owner": "…", "doc": "…" }],
+  "notRun": [{ "id": "U-ORPHAN", "severity": "deploy", "reason": "…" }]
+}
+```
+
+**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
+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
+signal at all — the rows reading the SSOTs report `NOT RUN` for exactly that reason, so
+the gate's complete run measures the checkout, never a copy of it. Neither field changes an exit code: a partial run in
+the container is the intent, and completeness is the gate's question, not the boot's.
+
+It is the shape of `ci/integration-signal.json` with three deliberate differences:
+no `generatedAt` (an unchanged tree must produce an unchanged file, or nothing can tell
+a re-run from a change), `validatorVersion` instead of a version of its own (the
+manifest version IS the validator version), and `deployable` instead of a
+`gate: {verdict, reason}` block (one fact, one owner). `notRun` is carried on purpose:
+rows that could not look are not passes, and each entry carries the `severity` of the row
+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.
+
+### Two run modes, three scopes
+
+Every check declares what it needs in order to look, and that word alone decides where
+the runner runs it. There are three of them (`src/manifest/manifestShape.js`
+§ `CHECK_SCOPES`):
+
+| Scope | What the check needs | Example row |
+|---|---|---|
+| `service` | the bearer's own root — all there is inside a container | `S-TEST`, `R-MEM` |
+| `workspace` | the workspace, because the check is ABOUT it | `U-ORPHAN` |
+| `bearer` | the bearer's root, plus whatever its `from:` reference names — the workspace (`L-PINS` reads `api/config/libraries.json`) or this package itself (`F-JEST` reads the packaged template, `R-NODE` its own `package.json`) | `F-JEST`, `R-NODE`, `L-PINS` |
+
+| Mode | Command | `service` rows | `workspace` rows (`U-ORPHAN`) | `bearer` rows |
+|---|---|---|---|---|
+| service | `oa-validate [serviceRoot]` | run | only findings under that service's root | run, for that one bearer |
+| workspace | `oa-validate --workspace <root>` (no service root) | `NOT RUN` | **all** of them | run, **once per discovered bearer** |
+
+A neighbour's orphan is the neighbour's blocker, so it does not appear in this service's
+table; the complete list is the workspace run, which is that check's home.
+
+`bearer` exists because `F-JEST` is neither of the other two: it is a fact of ONE service,
+and it reaches the template only through the workspace. Made `workspace` — which it was
+until 7.0.0 — it had to answer "no findings" in workspace mode, and that answer is
+indistinguishable from a clean workspace. Measured over the `service-workspace` fixture on
+2026-09-09: the workspace run printed `DEPLOYABLE — no findings` while two of its four
+services violated four of those rows between them. Who the bearers are is the manifest's
+own `discovery` block, never a second walk.
+
+**A checkout that does not carry its siblings.** CI checks out `api/` alone, so
+`<workspace>/api_biz` is not there. A check that reads it — `L-CONSUMER` asks who pins this
+package, `L-TOOLING` which service carries it, `U-ORPHAN` which directory nobody declared —
+would walk an absent directory and report the empty set as an answer. So a check declares
+the directories it walks (`requiresSiblings({ row, block })`, derived from the row's own
+patterns), and the runner verifies them before running it:
+
+```
+NOT RUN  L-CONSUMER — sibling root api_biz is not present in this checkout
+```
+
+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).
+
+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.
+
+### Uniforma knihoven (`oa-validate --library`)
+
+`manifests/library.manifest.json` is the same concept for the shared libraries, in the
+same package, carrying the same version — so the two shapes cannot drift apart
+(confirmation 002 §12). A library has no boot, so its rows carry one severity:
+`publish`. The choke point is `scripts/publish-library.sh`, and what fails there never
+becomes an artefact and therefore never reaches a service.
+
+```bash
+npx oa-validate --library ../../logger-contract      # one package
+npx oa-validate --library --all                      # every package the uniform finds
+npx oa-validate --library --all --workspace /path/to/workspace --json
+```
+
+One table (`id · category · where · what · fix`), the `doc` pointer of every reported
+row, exit `0` / `1`; `2` when the run could not start. `--library` with neither a
+package directory nor `--all` is a usage error — nothing is guessed.
+
+**Who wears the uniform** is discovery, not a list: `api/shared/**/package.json` minus
+`**/node_modules/**` and `**/tests/fixtures/**`, bound to `api/config/libraries.json`.
+A package the SSOT does not know, and a name in the SSOT with no package, are both
+`U-ORPHAN`. No library name appears in the manifest (004 point 3); the exclusion of the
+validator's own fixtures is a row of the manifest, never a branch in the code.
+
+**The category** is the one fact about a library that cannot be derived, so it is
+declared — `"oa": { "category": "core" }` — and checked against the dependency graph
+(005 point 3). A missing declaration and a declaration the graph contradicts are both
+`U-MISMATCH`.
+
+| category | layer | may depend on |
+|---|---|---|
+| `core` | L1 | nothing under `@onlineapps` |
+| `connector` | L2 | `core`, `connector` |
+| `orchestration` | L3 | `core`, `connector`, `orchestration` |
+| `runtime` | L4 | `core`, `connector`, `orchestration`, `runtime` |
+| `tooling` | — | any of the above |
+
+Within a layer is allowed; upward is not (`architecture-principles.md` §7 forbids a
+reverse dependency, not a neighbouring one). The list a category may depend on includes
+itself, explicitly, so no rule is implied anywhere.
+
+**The rows.** `all`: `L-MAIN`, `L-ENGINES` (the platform major, referenced from
+`api/.nvmrc`), `L-TESTS`, `L-TEST-SCRIPT`, `L-PACK-TESTS`, `L-PINS`, `L-NO-FILE-RANGE`,
+`L-CHANGELOG`, `L-README`, `L-README-REGION`, `L-CONSUMER`. Per category: `L-CORE-DEPS`, `L-CORE-EXPORTS`,
+`L-CONNECTOR-ENV`, `L-RUNTIME-CLIENT`, `L-TOOLING`. `orchestration` needs no row of its
+own — "depends only downward" is exactly what `U-MISMATCH` decides, and a second row
+would be a second owner of one rule.
+
+`L-CONNECTOR-ENV` asks its question of CODE. It reads each `src/**.js` with comments, the
+text of string and template literals, and regular-expression literals blanked out
+(`checks/librarySource.js` § `codeOnly`); what a template literal interpolates is code
+again, because `${process.env.X}` really does read the environment. Until d.239 it matched
+the raw file text, so a module documenting the duty it obeys — "this module reads no
+`process.env`" — was reported for the sentence in its own header.
+
+`L-PACK-TESTS` measures the **effect**, not the file: eight packages keep `tests/` out of
+the tarball with a `files` allowlist and no `.npmignore` at all, and a row checking for
+the file would report eight packages that are already right.
+
+**What is deliberately NOT a row** is written down as such, in the manifest's `guidance`
+block, with the reason and the decision it rests on — a duty nothing can decide is
+guidance, never a rule (001 §6). Today: `L-LINT` (002 §14 — one shared config or none,
+and "leave as is" is not an option), the logger/error contract, the boot-phase messages,
+"a removed export bumps the major", and the canonical body of the `test` script. The
+shape check fails the build if a guidance entry grows a `check`.
+
+Decision and specification: [`api/docs/governance/confirmations/biz-service-manifest.md`](../../../docs/governance/confirmations/biz-service-manifest.md)
+(entries 001–005).
+
+---
+
+## Generated files (`oa-sync-template`)
+
+### The business-service template lives here
+
+`templates/business-service/**` ships **inside this package**, so the shape a service is
+created from is pinned by the same version that pins the manifest it is measured against
+(confirmation 001 §2). `api/templates/business-service` is no longer that source: it is
+this generator's output, committed for reading (§5), and the acceptance §9 asks for —
+"differs from the generator's output by nothing" — is measured by
+`tests/unit/templateMirror.test.js`, file by file, in both directions.
+
+Two files are packed under a different name than they are written under, and the map is
+in `src/sync/serviceTemplate.js` (`PACKED_NAMES`). `gitignore` has no dot because npm
+never packs a file called `.gitignore`. `package.json.template` carries a suffix because a
+`package.json` inside a package is a second package to every tool that walks a package
+tree: measured 2026-09-09 under its written name, `oa-validate --library --all` reported
+eight findings about the template and `api/scripts/ci/verify-manifest-pins.mjs` — step 1
+of the pre-push hook — reported two more, all false. The template's pins are deliberately
+NOT the platform's; the generator writes the SSOT's versions when it creates a service.
+Every other file is packed and written under the name it has.
+
+`F-DOCKERIGNORE` is `F-GITIGNORE`'s row one step further along, over the SAME
+declaration. `Dockerfile` line `COPY . .` takes everything `.dockerignore` does not
+exclude, and being ignored by git excludes nothing at all: measured by BIZ-hello on
+2026-09-11, a LOCAL production image of hello came to 6.6 GB — 5.2 GB of it `logs/` — and
+carried `config/env-active/*.env` with `DB_PASSWORD`, `JWT_SECRET`, the MinIO keys and
+`RABBITMQ_URL`. The image CI builds is clean by accident, because a fresh checkout has no
+ignored file to copy, so the defect is invisible exactly where the image is built.
+
+The entries are DERIVED from `templates/business-service/gitignore` rather than written a
+second time, and the derivation is a translation, not a copy: a slash-less `.gitignore`
+pattern matches at every depth while a `.dockerignore` one is matched from the context
+root, so `*.log` there catches `debug.log` and not `logs/debug.log`. Every slash-less entry
+is therefore emitted in both shapes, an entry carrying a slash travels unchanged, a
+negation keeps its `!` in front and its place in the order, and `.git` is added — the one
+exclusion git can never declare about itself. What the derivation cannot do is exclude
+something `.gitignore` does not: `tests/` is the trap on that side, because Tier-1 of the
+boot reads `tests/cookbooks` and an image without it fails at phase 0.2.
+
+The criterion is a comparison and never a list of directories, which is how hello found it:
+the files in `/app` of an image built from the WORKING TREE, `node_modules` aside, are the
+files of an image built from `git archive HEAD`. `tests/unit/dockerignoreBuildContext.integration.test.js`
+measures exactly that through docker itself — `FROM scratch` + `COPY . /app` exported
+locally, so the matcher under test is BuildKit's own — and says NOT RUN with the reason
+when there is no daemon to ask.
+
+`G-CI` holds ONE delimited block of `.gitlab-ci.yml` — `oa-ci v1` — to the packaged
+template, rendered for this service. The block carries `include:`, `workflow:`, `stages:`,
+`variables:`, `verify-installation-contract:`, `build:`, `secret_detection:` and
+`deploy-production:`: the pipeline's platform half, which decides WHICH pipelines run at
+all, builds the same way everywhere, holds the installation document and the migrations to
+each other, pins the deploy to the digest CI pushed (`R1`, `R2` and `R5` read this file)
+and carries the step below. It is RENDERED rather than identical because that half names
+the service once, in `GIT_CLONE_PATH`.
+
+One key is outside the markers, and the sync never rewrites a line of it: `test:`. What
+separates it from the rest is not where it happened to sit but who decides it — which
+database an integration needs, which `ci:gate:*` steps run and which artefact it publishes
+are facts about the service. `workflow:` and `verify-installation-contract:` looked like
+the same kind of thing until they were measured: on 2026-09-11 all eight repositories
+carried each of them BYTE identical, one variant apiece, and what they say is the
+platform's, so they joined the block (d.251b). `test:` was the only key that actually
+differed, in all eight.
+
+The one thing the migration does move is position: a repository whose platform keys sit
+between its own keys — all eight, today — gets the block where the first platform key
+stood, so `test:` ends up after it, TEXT UNCHANGED. YAML mappings are unordered, and the
+alternative would be a block that is not one region. The reason the row is a block at all
+is a measurement and a rule: on 2026-09-11 the template was 151 lines and 7 root keys while
+the eight services carried 176 to 198 lines and 9, and the difference that mattered was the
+`test` job standing up MariaDB, Redis and RabbitMQ as service containers, five `ci:gate:*`
+steps and the `ci/integration-signal.json` artefact. A whole-file row would have had a fix
+that deleted eight integration tiers — a finding nobody can carry out
+(`.claude/rules/automation-gates.md` §3). `stages:` stays in the block and declares all
+four stages, the service's own jobs included; no biz service declares a fifth.
+
+The fix is therefore `npx oa-sync-template .gitlab-ci.yml --target .`, in three states: a
+file carrying the block is rewritten between its markers; a file carrying the platform's
+keys UNMARKED — all eight, today — has exactly those keys replaced by the block where the
+first of them stood, so no file ends up with two `build:` keys; a file that is not there is
+created whole, which is what `--new` writes. Which keys the block claims is read from the
+block itself (`src/sync/serviceTemplate.js` § `topLevelKeys`), so adding a job to the
+platform's half is one edit to the template.
+
+The template's `.gitlab-ci.yml` runs the conformance check once more in its
+`deploy-production` job, before the SSH step — deploy is confirmation, never discovery
+(confirmation 006 point 3, placed by 008). The step is one file,
+`scripts/verify-deploy-uniform.sh`, called with three arguments: the checkout GitLab made,
+the api repository URL carrying the job token, and the api ref production follows. It
+clones `api` read-only beside the checkout, runs `oa-validate <serviceRoot> --workspace
+<root>` with the engine this repository's pin installed, and refuses the deploy on one
+blocking finding or on `complete: false`. Nothing turns it off.
+
+The layout is the whole of why it can be complete: the rows reading a platform SSOT answer
+only for a service at `<root>/api_biz/<service>` beside `<root>/api`. Measured 2026-09-11
+over a converter export — in that layout `complete: true` in 1.1 s; as unrelated siblings,
+seven blocking rows NOT RUN and `complete: false`. So the job sets `GIT_CLONE_PATH` to put
+its own checkout there (no symlink, no second copy) and the script refuses any other
+layout by name. Whether a real pipeline reaches `complete: true` is not measured here: it
+also needs the runner's custom build directory and the api project's job-token allowlist,
+which is the owner's step (008 point 2).
+
+The same job carries the OTHER end of that sentence: after the SSH step it runs the
+platform's post-deploy gate over the target it declares —
+`DEPLOY_GATE_TARGETS: "biz:<registry name>"`, because the gate has no default and the job
+says which checks judge it (confirmation `deploy-gate-targets` 002). The gate is
+`api/scripts/run-post-deploy-gate.sh` out of the read-only `api` clone the uniform step
+already made, run in REMOTE mode: the container and its `RestartCount` are read on the biz
+box, the heartbeat projection Registry writes into Redis on the infra box, because those
+two facts live on two machines and this runner is a third (confirmation
+`deploy-gate-targets` 003, `server-topology` 004/005). The infra box is reached as the
+gate-reader account — `GATE_INFRA_HOST`, `GATE_INFRA_USER`, `GATE_INFRA_SSH_PRIVATE_KEY`
+as a second SSH identity — and the job REFUSES before it installs or deploys anything when
+that identity is not configured, naming the missing variables: a service deployed and then
+not verified is the false guarantee `automation-gates.md` §5 is about. A service whose
+contract declares `workflowChecks` needs its `DEPLOY_SMOKE_*` variables too; the gate says
+which one is missing.
+
+The template's `Dockerfile` runs the conformance check in its **production stage**, after
+the sources arrive and before the image is finished (confirmation 001 §3.1). It is this
+package's own CLI, and every biz service declares this library under `dependencies`
+(measured across all eight on 2026-09-09), so the `npm ci --omit=dev` above it installs
+what the line calls. An image has no workspace above it, so the rows reading a platform
+file print `NOT RUN` by name there and everything the repository answers for itself runs:
+one finding of severity `boot` or `deploy` exits non-zero and the image is never built.
+
+### `oa-sync-template --new` — a service
+
+```bash
+npx oa-sync-template --new <name> --into <serviceRoot> [--description <text>] [--workspace <root>]
+```
+
+`<name>` is the DIRECTORY name under `api_biz/`; everything else is derived from it and
+substituted — `__SERVICE_NAME__`, `__CONTAINER_NAME__` (`api_service_<name>`),
+`__REPO_NAME__` and `__REGISTRY_NAME__` (both `biz-<name>`). Three things are added to
+the render, and each is a fact about ONE service rather than about the shape: the env
+template is named after the service, `config/env-templates/shared.env` comes from the
+platform env manifest, and every `@onlineapps` pin comes from
+`api/config/libraries.json` — a dependency the SSOT does not know fails the run by name.
+
+`--description` is optional. Without it `__SERVICE_DESCRIPTION__` is **left standing**
+and the files carrying it are listed: this run has no description, and writing a
+plausible one would put a fact in the repository that nobody stated. `--into` must not
+exist yet, so nothing anybody else wrote is overwritten.
+
+`api/scripts/add-service.sh --scaffold` runs exactly this. What stays in that script is
+what is not the shape of a service: the entry in `api/config/services.json` and the port.
+
+### `oa-sync-template [path…]` — an existing service
+
+```bash
+npx oa-sync-template [path...] --target <serviceRoot> [--workspace <root>] [--check]
+```
+
+Rewrites the files the manifest declares in the classes `identical`, `generated` and
+`contains`, from the same `from:` reference those rows already point the conformance CHECK
+at — one definition, read twice. With no paths it plans every such row. Files of the `own`
+class — `src/**`, `tests/**`, the content of `docs/**` — are never written.
+
+**No workspace is required of the run itself** — only of the ROWS that read a workspace
+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
+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`
+and exits 1.
+
+Three rows need more than a splice, and the module that owns their CHECK renders them, so
+the generator cannot produce a file its own check rejects:
+
+* **`F-RUNNER`** — the `oa-test-runner v1` block is the template's, except for `build`,
+  `env_file` and `networks`, which the same row requires to equal the service the runner
+  tests. The check removes those three before comparing against the template; the sync
+  grafts this repository's own into the rendered block. Seven of the eight biz services
+  reach a second network in both nodes on 2026-09-09 — that is the rule being kept, not
+  broken, so neither half may report it.
+
+  Unlike `init.sh`, a compose file is never `BLOCKED`, because a mapping has one place its
+  entries can start. **Three states**: a file carrying the markers is rewritten between
+  them; a file carrying a runner but NO markers has that runner's declaration REPLACED
+  where it stands — measured 2026-09-10, seven of the eight repositories are in that state
+  (d.220), and a run that only inserted gave them a second `<container>_tests:` key, which
+  compose either refuses or resolves by taking the last one; a file carrying neither gets
+  the block inserted under `services:`. The replacement spans the KEY to the next key at
+  the same level, so a comment above it — in `api_biz/converter` the memory measurement
+  taken inside that container — survives untouched.
+* **`G-PROD`** — `docker-compose.production.yml` is the template rendered with this
+  repository's DECLARED name (`config/service/config.json` → `service.name`), whole file
+  and nothing else. The class is `generated` rather than `identical` because the file
+  carries an identity — the container, the image repository, the service's own env file —
+  and the render is what puts it there; owner decision `server-topology` 005, on the
+  measurement that the seven old-shape copies were byte-identical once the name was
+  normalised. There is no prose to protect here, so an existing file is REWRITTEN rather
+  than spliced or blocked, and the R1 bridge `G-PROD-IMAGE` keeps answering about the pin
+  beside it.
+* **`G-README`** — the generated uniform pointer of `README.md`, rendered from the packaged
+  manifest and applied to the region between the markers; everything outside them is left
+  as it was. The file itself is never created: a README is prose somebody wrote, and an
+  absent one is what the row reports.
+* **`G-SETUP-INSTALL` / `-MATRIX` / `-VALIDATION`** — `skeleton_only`: the check compares
+  the set of `##` headings against the template document and never the prose. A missing
+  document is created from the skeleton (header, title, sections, no prose); an existing
+  one is never rewritten, and a missing section is `BLOCKED` with the heading named. That
+  a document is absent at all stays `G-SETUP`'s finding, through the installation
+  contract's `SETUP_DOCS`, so one defect keeps one owner.
+
+`--check` writes nothing and exits 1, naming the first line that differs and what the run
+would put there — both sides, because one of them alone lies about half the runs: an
+INSERTION is not described by what the file already said at that line. Measured over the
+eight biz repositories on 2026-09-09, the set of files this run would change is exactly the
+set of `F-INIT`/`F-JEST` findings `oa-validate` reports on the same trees, which is what
+"one definition" has to mean to be worth anything. On the same trees `F-RUNNER` used to
+report `BLOCKED`, and the row's `fix` accordingly read "paste the block once by hand" —
+advice, where confirmation 001 §3.2 asks for a command. It is a command now.
+
+### `oa-sync-template template` — the committed template directory
+
+```bash
+npx oa-sync-template template --target <dir> [--check]
+```
+
+Renders the packaged template with its own placeholders as the parameters, which is what
+`api/templates/business-service` is. `--check` is the gate: it exits 1 both on a file that
+differs and on a file the packaged template has no source for.
+
+### `oa-sync-template shared-env`
+
+`config/env-templates/shared.env` is generated, never edited, never edited. The platform env manifest
+`api/config/shared-env.json` owns the shared key set — name, template value, why the
+platform shares it — and every bearer's copy is rendered from it, so a service can only
+add keys of its own in `service.env`.
+
+```bash
+npx oa-sync-template shared-env --target <bearer dir> [--workspace <root>] [--check]
+```
+
+`--target` is the bearer: a service root, `api/` itself, or the business-service
+template; `--workspace` is the directory holding `api/` and `api_biz/`, found upwards
+from the target when it is not given. `--check` writes nothing and exits 1 with the diff
+when the file on disk is not what the manifest renders; a run that cannot start at all
+exits 2. There is no flag pointing the run at another manifest — the shared key set has
+one owner.
+
+Decision and specification: [`api/docs/governance/confirmations/biz-service-manifest.md`](../../../docs/governance/confirmations/biz-service-manifest.md) §18.
+
+### `oa-sync-template readme-uniform`
+
+Discoverability of a uniform is one rendered pointer per repository, not a header per
+file: a generated region of the repository's `README.md`, everything in it read from the
+manifest that ships in this package — the link included, which is computed from the two
+paths rather than written down. Nothing outside the markers is touched.
+
+```bash
+npx oa-sync-template readme-uniform (--target <dir> | --all) [--workspace <root>] [--check]
+```
+
+`--target` reads the KIND from the disk, because the kind is a fact of the directory and a
+`--kind` flag would be a second way to state it:
+
+| the root carries | kind | the region between markers |
+|---|---|---|
+| `config/service/operations.json` | service | `biz-service-uniform` — `Uniform: [biz-service](<link>)`, which repositories wear the uniform (the `discovery` block and its SSOT), the row ids grouped by the manifest section that declares them, and which path falls under which row |
+| `package.json` (and no such file) | library | `library-uniform` — `Uniform: [library/<category>](<link>)` and the duty sections the declared category wears, with the ids of their rows |
+| neither | — | fail-fast naming both files it looked for |
+
+`--all` is the library run and stays one: the eight service repositories are separate
+checkouts, not siblings under one workspace, so there is no list to walk — a service is
+written one `--target` at a time. A service needs no workspace above it either; its region
+is the packaged manifest and its link is the copy npm installs into its own
+`node_modules`, which a reader resolves without a network.
+
+A service region renders a row's path, and a row taking its value from elsewhere renders
+the path that OWNS the value rather than the value (`` `api/.nvmrc` ``, not `Node 24`).
+Never a `why` or a `fix` — that prose has an owner, and the region is not it. A FORBIDDEN
+row contributes its id and not its path: `hooks/pre-commit` and
+`scripts/run-pre-validation.js` may not occur in a service repository as text at all
+(`api/tests/scripts/add-service.bats` greps the template for them, because `init.sh` used
+to install the hook), so a region naming them would write a retired path back into every
+service.
+
+The region carries no date, no version and no count. The version a README is checked
+against IS the pin on this package, because the manifest ships inside it; a date would
+make two runs render different bytes, and a generator whose output varies cannot be a
+gate. A library that declares no `oa.category` is reported `NOT RUN` under `--all` and
+counted out of the coverage line — its missing declaration is already the blocking
+finding `U-MISMATCH` of `oa-validate --library`, and this run never guesses one. Asked
+about such a package by name with `--target`, the run fails fast instead. A service
+declares nothing of the sort: the uniform it wears follows from its location (005 point 1).
+
+**The region is gated, not only generated** (owner decision 2026-09-09). A `generated` class
+is a generator PLUS a row carrying its `--check` (001 §2, the precedent being
+`G-SHARED-ENV`), and until d.215e this one had the generator alone: a README whose pointer
+had gone stale was reported by nothing anybody runs on a repository. Two rows say it now —
+`G-README` of the biz-service uniform (severity `deploy`) and `L-README-REGION` of the
+library one (severity `publish`) — and they render through this very module and compare
+through the same `checkUniformRegion` the `--check` run calls, so a row and the command
+cannot disagree about one file. A missing region, a stale one and an absent README are three
+sentences with three fixes; the row names the first line that differs, and the full diff is
+one command away, which is the row's own `fix`.
+
+`L-README` is untouched beside it: it asks whether the node header is there, which a human
+writes, while `L-README-REGION` asks whether the rendered half still says what the manifest
+says. Two writers, two fixes, two rows. A library declaring no category raises neither —
+that is `U-MISMATCH`, blocking, with its own fix — and a checkout holding no copy of this
+package reports `L-README-REGION` `NOT RUN` with that reason, because the link the region
+carries points at the manifest as it lies in the checkout being read.
+
+Decision and specification: [`api/docs/governance/confirmations/biz-service-manifest.md`](../../../docs/governance/confirmations/biz-service-manifest.md) § Confirmation 20260909-biz-service-manifest-005, point 2.
+
+### `oa-sync-template docs-region`
+
+The documentation tree copied the same descriptive lists by hand: the repository shape in
+three nodes, the `package.json` scripts in two, the runtime numbers in several. A copy is
+kept true by review only, which is what `.claude/rules/doc-code-binding.md` §1 forbids for
+a descriptive fact. Five regions render those lists from the two packaged manifests:
+
+| id | renders |
+|---|---|
+| `biz-service-tree` | the packaged template's files, each annotated with the row that owns the path; the forbidden paths, and a path a row owns that the template does not carry |
+| `biz-service-scripts` | `scripts.required` with the body of each row, and `scripts.forbidden` |
+| `biz-service-runtime` | the runtime rows and every row carrying a memory limit, with their own parameters |
+| `biz-service-alignment` | every row of the service manifest — id, severity, what it checks |
+| `library-duties` | the library categories with their layer and `may_depend_on`, the duty sections by row id, and the guidance entries marked apart as named non-rules |
+
+```bash
+npx oa-sync-template docs-region (--id <id> | --all) --file <document> [--workspace <root>] [--check]
+npx oa-sync-template docs-region --list
+```
+
+What a region carries is a row's observable — its id, its check, the paths and values its
+own parameters name. Never its `why` or `fix`: that prose has an owner, and a copy of it in
+five documents is the duplication the mechanism exists to remove. A `from:` reference
+renders as the path that OWNS the value, never as the value itself, so `` `api/.nvmrc` ``
+stays true when the platform moves to the next Node major. `${runner}` stays unexpanded,
+because the name of the one-shot test runner is per repository.
+
+The run REPLACES a region and never inserts one. These documents live in `api/docs/**`, a
+tree owned by other threads: where a section belongs in them is their owner's decision, and
+a generator writing into somebody else's document is the unsafe side effect
+`.claude/rules/automation-gates.md` §1 requirement 3 forbids. A document carrying no
+markers is therefore a failure that prints the two lines to paste; `--all` covers exactly
+the regions a document already declares. Like every region in this package, the output
+carries no date, no version and no count.
+
+Finding, replacing, extracting and diffing a marked region is `src/sync/generatedRegion.js`,
+shared with `readme-uniform` — one implementation of the marker shape in the package.
+
+Decision and specification: [`api/docs/governance/confirmations/biz-service-manifest.md`](../../../docs/governance/confirmations/biz-service-manifest.md) § Confirmation 20260909-biz-service-manifest-002, §16.2.
+
+---
+
 ## Runtime Directory Structure
 
 ```
@@ -239,6 +1219,60 @@ ServiceStructureValidator.getStandardLevels();
 
 **Related:** [Biz Service Canonical Shape — Implementation Standard Levels](/docs/biz/00-model/service-shape.md#implementation-standard-levels), [Biz Error Handling Contract](/docs/biz/70-contracts/error-handling.md)
 
+## Test namespace (`getTestNamespace`, `getForeignTestNamespace`, `assertAllowedTenant`)
+
+An integration test reaches a real database, so the tenant / workspace it writes
+into is a safety boundary — never a value a test file picks for itself. Both
+helpers read the platform env (`TESTING_TENANT_ID`, `TESTING_WORKSPACE_ID`) and
+refuse anything outside the environment classes
+[tenant-allocation.md](/docs/standards/tenant-allocation.md) allocates to
+non-production; a missing or malformed value throws rather than defaulting.
+
+```javascript
+const { getTestNamespace, getForeignTestNamespace } = require('@onlineapps/conn-orch-validator');
+
+const ctx = getTestNamespace();          // the namespace this test owns
+const other = getForeignTestNamespace(); // one it must NOT see rows from
+```
+
+`getForeignTestNamespace()` exists for isolation tests: a handler filters on
+tenant_id AND workspace_id, and proving it does needs a second namespace. It
+returns another of the same allowed classes, chosen by position in that list and
+wrapping at its end — deterministic for a given environment, and never a literal
+customer tenant or a derived `tenant + 1` (the platform default 99 + 1 is the
+LIVE tenant). The workspace half is the caller's own.
+
+Deploy-contract R8 accepts a call to either helper as the one legitimate source
+of a namespace inside `tests/integration/`.
+
+### `assertAllowedTenant(tenantId, { purpose, setBy })`
+
+The same boundary asked about an id the caller already holds. An operational
+script — clone a namespace, wipe one, backfill one — is handed a tenant on the
+command line, and the question it must answer is not "which namespace do I own"
+but "may I touch this one at all".
+
+```javascript
+const { assertAllowedTenant } = require('@onlineapps/conn-orch-validator');
+
+const target = assertAllowedTenant(args.tenant, {
+  purpose: '--to-tenant',          // what the caller calls the value
+  setBy: 'on the command line'     // where that name is given a value
+});
+// 98 — an integer, whatever shape came in ("98" and 98 both arrive this way)
+```
+
+It returns the id normalized to an integer, and throws otherwise: absent, not an
+integer, or not one of the environment classes the standard allocates to
+non-production. The refusal is the sentence `getTestNamespace()` throws, rendered
+from the same place — `purpose` and `setBy` are the only parts that differ, so an
+operator who typed `--to-tenant 101` is told to change that flag rather than an
+env file they never touched.
+
+The class list itself is deliberately **not** exported: a copy of a boundary is a
+second boundary, and the two drift. The refusal names the allowed classes, so a
+caller that has to show them never enumerates them itself.
+
 ## Related Documentation
 
 - [/docs/architecture/validator.md](/docs/architecture/validator.md)