@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

package/src/manifest/runManifest.js

@@ -19,7 +19,7 @@ const path = require('path');
 const { verifyManifestShape, rowNeedsWorkspace } = require('./manifestShape');
 const { collectRows } = require('./walk');
 const { discoverBearers, rootOfPattern } = require('./discovery');
-const { resolveWorkspacePath, canonicalRoot } = require('./workspaceRoot');
+const { resolveWorkspacePath, canonicalRoot, describeWorkspaceFix } = require('./workspaceRoot');
 const { CHECK_REGISTRY } = require('./checks');
 
 /** The three scopes, by the name the runner branches on. */
@@ -164,22 +164,45 @@ function runManifest({ manifest, serviceRoot = null, workspaceRoot = null, check
     const check = checkRegistry[row.check];
     const needsWorkspace = rowNeedsWorkspace({ check, row, block });
 
+    // The sentence a row is reported NOT RUN with belongs to the CHECK, because
+    // only the check knows what it could not read. Until d.518 a check that
+    // declared none borrowed `the workspace root is not reachable` from here —
+    // a sentence about a row this file knows nothing about, with no fix in it,
+    // which nothing reached: every registered workspace-dependent check owns
+    // one, and `service-identity` declares `needsWorkspace: () => false` and
+    // cannot arrive here at all. A default nobody reaches is the false
+    // guarantee `.claude/rules/automation-gates.md` §5 calls a defect, so the
+    // duty is stated rather than covered for — and stated on EVERY run, not
+    // only on the ones without a workspace, which is where it would otherwise
+    // be discovered (`architecture-principles.md` §4, fail-fast).
+    if (needsWorkspace && typeof check.describeNotRun !== 'function') {
+      throw new Error(`[Manifest] Check "${row.check}" owns no NOT RUN sentence - row ${row.id} needs the `
+        + 'workspace, so a run without one has to say why this row was not answered and how to answer it. '
+        + 'Fix: add describeNotRun({ row, block }) to the check, ending it with '
+        + 'workspaceRoot.js § describeWorkspaceFix.');
+    }
+
     if (needsWorkspace && workspace === null) {
       notRun.push({
         id: row.id,
         severity: row.severity,
-        reason: check.describeNotRun
-          ? check.describeNotRun({ row, block })
-          : 'the workspace root is not reachable'
+        reason: check.describeNotRun({ row, block })
       });
       continue;
     }
 
     if (needsWorkspace && outsideWorkspace) {
+      // A state sentence is not a remedy. This one said where the repository
+      // is NOT, and stopped — the same half-answer d.518 removed from the
+      // checks' own sentences, in the branch that reports it for them. The
+      // command comes from the one owner of it, and what the checkout has to
+      // carry is the repository under check (d.523).
       notRun.push({
         id: row.id,
         severity: row.severity,
-        reason: `service root is outside the workspace root ${workspace}`
+        reason: `service root is outside the workspace root ${workspace} `
+          + '- a row about the workspace cannot be answered about a repository that is not in it. '
+          + describeWorkspaceFix(root)
       });
       continue;
     }
@@ -320,13 +343,41 @@ function missingRoots({ roots, workspaceRoot }) {
 }
 
 /**
+ * The NOT RUN reason for a row whose sibling root is not there, naming every
+ * missing one AND what to do about it.
+ *
+ * The fix half is not decoration. This line is read where the reader has no
+ * workspace to look at — a service's own CI log, a container — and until d.511
+ * it stopped at "is not present in this checkout": true, and nothing anybody
+ * could act on. 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 run printed `NOT RUN  U-ORPHAN — sibling root api_biz is not
+ * present in this checkout` and, because the report's own incomplete-run
+ * sentence carries its fix only on a CLEAR verdict (`report.js`
+ * § describeClearOutcome), a run that also had findings named no fix at all.
+ * `automation-gates.md` §1 requirement 4 asks for the exact command, and the
+ * sync half of this package already gives it (`src/sync/uniformFiles.js`
+ * § planRow).
+ *
+ * The command is DERIVED from the missing roots rather than written beside
+ * them, so a row that starts reading a new sibling needs no second edit here.
+ * It is also not written HERE: the sentence belongs to `workspaceRoot.js`
+ * § describeWorkspaceFix, because the bridge to the documentation lint reports
+ * the same absence through the linter's own NOT RUN channel and must offer the
+ * same remedy (d.516, `.claude/rules/change-discipline.md` § One rail per
+ * concern). This function still owns what is missing; the helper owns what to
+ * do about it.
+ *
  * @param {string[]} missing the roots that are not there
- * @returns {string} the NOT RUN reason, naming every one of them
+ * @returns {string} the NOT RUN reason, naming every one of them and the fix
  */
 function describeMissingRoots(missing) {
-  return missing.length === 1
+  const found = missing.length === 1
     ? `sibling root ${missing[0]} is not present in this checkout`
     : `sibling roots ${missing.join(', ')} are not present in this checkout`;
+
+  return `${found} - an absent directory is not an empty one, so this row is not answered. `
+    + describeWorkspaceFix(missing.join(', '));
 }
 
 /**

package/src/manifest/workspaceRoot.js

@@ -37,10 +37,34 @@
  * `startDir` and get the workspace THAT TREE belongs to. It is a different
  * question, asked explicitly, never a fallback of the other one.
  *
+ * ## The service a run is ABOUT (d.540)
+ *
+ * A run over a service repository asks a third question, and it is as
+ * deterministic as the other two: the workspace is the nearest ancestor OF THE
+ * SERVICE ROOT that carries an api checkout — the root the caller named, never
+ * the directory the shell happens to stand in. `oa-validate` passes it as
+ * `serviceRoot`.
+ *
+ * It exists because the package question answers about the PACKAGE, and the copy
+ * a service runs is the one it installed: `oa-validate .` inside
+ * `<workspace>/api_biz/<service>` printed `Workspace root: NOT RESOLVED` and
+ * reported every `U-*` and `D-*` row NOT RUN, for a service lying in a complete
+ * workspace two directories up (measured 2026-09-16, BIZ-hello). The run knew
+ * where the service was and refused to look there.
+ *
+ * The three questions are asked in a stated order, and none of them reads
+ * ambient state: an explicit `--workspace` wins, then the tree the run is about
+ * (`startDir`, or `serviceRoot`), then the checkout this package is part of.
+ * The last one is what answers for a run whose subject lies in NO workspace —
+ * the service root is then reported as outside the workspace it names, which is
+ * true and actionable — and when neither question finds a checkout the run says
+ * NOT RESOLVED, exactly as before.
+ *
  * An INSTALLED copy (`<service>/node_modules/@onlineapps/conn-orch-validator`)
- * lies in no checkout, so it resolves nothing and the rows that need the SSOT
- * are reported NOT RUN — loudly, never as a pass (`automation-gates.md` §5).
- * That is what a service container has, and it is unchanged by this rule.
+ * lies in no checkout, so it speaks for none: the rows that read the platform
+ * SSOT are answered from the workspace the SERVICE lies in, or reported NOT RUN
+ * — loudly, never as a pass (`automation-gates.md` §5). A service container,
+ * whose image carries no workspace above `/app`, is unchanged by this rule.
  */
 
 const fs = require('fs');
@@ -201,11 +225,19 @@ function workspaceAbove(startDir) {
 }
 
 /**
- * @param {{ explicit?: string|null, startDir?: string|null }} params
+ * The three questions, in the order the header states them: the root the caller
+ * NAMED, then the tree the run is about, then the checkout this package is part
+ * of. `startDir` and `serviceRoot` are both "the tree this run is about" and
+ * differ in what happens when that tree lies in no workspace — a run that WRITES
+ * into a tree stops there (there is nowhere to write from), a run that MEASURES
+ * one lets the package answer, so the report can say which workspace the service
+ * root is outside of.
+ *
+ * @param {{ explicit?: string|null, startDir?: string|null, serviceRoot?: string|null }} params
  * @returns {string|null} absolute workspace root, or null when neither the named
  *   tree nor this package lies in one
  */
-function resolveWorkspaceRoot({ explicit = null, startDir = null } = {}) {
+function resolveWorkspaceRoot({ explicit = null, startDir = null, serviceRoot = null } = {}) {
   if (explicit !== null && explicit !== undefined) {
     const resolved = path.resolve(explicit);
     if (apiCheckoutOf(resolved) === null) {
@@ -226,17 +258,71 @@ function resolveWorkspaceRoot({ explicit = null, startDir = null } = {}) {
     return above === null ? null : canonicalRoot(above);
   }
 
+  if (serviceRoot !== null && serviceRoot !== undefined) {
+    if (typeof serviceRoot !== 'string' || serviceRoot.length === 0) {
+      throw new Error('[ManifestWorkspace] Service root is required - resolveWorkspaceRoot({ serviceRoot }) got '
+        + `${JSON.stringify(serviceRoot)}. Fix: pass the repository the run is about, or omit it to use this `
+        + 'package\'s own checkout.');
+    }
+    const above = workspaceAbove(serviceRoot);
+    if (above !== null) return canonicalRoot(above);
+  }
+
   return API_CHECKOUT_ROOT === null ? null : canonicalRoot(path.dirname(API_CHECKOUT_ROOT));
 }
 
+/**
+ * The command that turns "this run had no such checkout" into a run that does —
+ * one sentence, one owner, wherever a row is reported NOT RUN because the tree
+ * it needed was not under the workspace.
+ *
+ * It exists as a function because there are two such places and they were
+ * drifting apart. `runManifest.js` § describeMissingRoots gained it in d.511,
+ * from the roots a row declares; the bridge to the documentation lint
+ * (`checks/docsLintBridge.js`) reports the same absence through the linter's own
+ * NOT RUN channel and, until d.516, ended at "the probe could not be evaluated"
+ * — true, and nothing anybody could act on (`.claude/rules/automation-gates.md`
+ * §1 requirement 4). Two sentences for one remedy is the second rail
+ * `.claude/rules/change-discipline.md` § One rail per concern names.
+ *
+ * What the checkout must CARRY is the caller's, because only the caller knows
+ * it: a row declares its roots and names them, while the bridge is handed a
+ * reason written by the linter — which names the probe target itself, and which
+ * this package neither writes nor parses (the bridge cites the lint, it does not
+ * restate it).
+ *
+ * @param {string} carries what a workspace has to hold for the row to be
+ *   answered — the missing roots when the caller resolved them, otherwise the
+ *   thing the reason in front of this sentence already named
+ * @returns {string} the `Fix:` sentence, ending in a full stop
+ */
+function describeWorkspaceFix(carries) {
+  if (typeof carries !== 'string' || carries.length === 0) {
+    throw new Error('[ManifestWorkspace] Fix subject is required - describeWorkspaceFix() got '
+      + `${JSON.stringify(carries)}, so the sentence would tell the reader to carry nothing. `
+      + 'Fix: pass the missing roots, or the phrase naming what the reason before it points at.');
+  }
+  return `Fix: run with --workspace pointing at a checkout that carries ${carries}.`;
+}
+
+/**
+ * What the bridge to a delegated checker passes as `carries`: the absent thing
+ * is named by the checker's own reason, which sits immediately before this
+ * sentence, so the fix points back at it instead of repeating it in this
+ * package's words.
+ */
+const AS_THE_REASON_NAMES = 'what this reason names';
+
 module.exports = {
   resolveWorkspaceRoot,
   canonicalRoot,
   workspaceAbove,
   resolveWorkspacePath,
+  describeWorkspaceFix,
   apiCheckoutOf,
   API_CHECKOUT_ROOT,
   API_MARKER,
+  AS_THE_REASON_NAMES,
   PACKAGE_ROOT,
   WORKSPACE_MARKER
 };

package/src/sync/serviceTemplate.js

@@ -124,13 +124,33 @@ const PACKED_NAMES = Object.freeze({
 /**
  * The files a service is expected to EXECUTE, so the ones written executable.
  *
- * `init.sh` is the file a service is started through. `scripts/verify-deploy-uniform.sh`
- * is invoked by name from the `deploy-production` job of the rendered
- * `.gitlab-ci.yml`, so a copy without the bit fails that job with "permission
- * denied" instead of measuring the uniform — and a gate that cannot run is the
- * false guarantee `automation-gates.md` §5 names.
+ * `init.sh` is the file a service is started through — and since d.555 it is the
+ * only one: the deploy gate is no longer rendered into a service (see
+ * `PACKAGE_ONLY` below), so there is no copy of it in a repository to give a bit
+ * to.
  */
-const EXECUTABLE_FILES = Object.freeze(['init.sh', 'scripts/verify-deploy-uniform.sh']);
+const EXECUTABLE_FILES = Object.freeze(['init.sh']);
+
+/**
+ * Files this package carries INSIDE the template directory that are not part of
+ * the scaffold — the package's own, reached by the path a pin installs.
+ *
+ * `scripts/verify-deploy-uniform.sh` is the uniform gate. Until d.529 the
+ * rendered `.gitlab-ci.yml` ran the copy in the service repository; since then
+ * BOTH callers — the `validate-uniform` job and `deploy-production` — invoke
+ * `node_modules/@onlineapps/conn-orch-validator/templates/business-service/scripts/verify-deploy-uniform.sh`,
+ * the pinned one. So the rendered copy is read by nothing, and the four
+ * questions `change-discipline.md` § "Removing something removes its
+ * declaration" asks answer cleanly: it came to exist with the deploy job of
+ * d.421, it carried gate 008, nothing reads it because the callers moved to the
+ * pin, and what replaces it is MORE conceptual — one pin, one gate, versioned
+ * with the manifest it measures against, instead of eight copies that drift the
+ * day one of them is edited.
+ *
+ * It stays in the package rather than moving elsewhere in it: the path is what
+ * the rendered CI file names, and the file lives where that path points.
+ */
+const PACKAGE_ONLY = Object.freeze(['scripts/verify-deploy-uniform.sh']);
 
 /**
  * The env template's name in the template, and the name it is written under.
@@ -340,7 +360,7 @@ function listTemplateFiles(root) {
     }
   };
   walk(root, '');
-  return collected.sort();
+  return collected.filter((relative) => !PACKAGE_ONLY.includes(relative)).sort();
 }
 
 /**
@@ -483,6 +503,53 @@ function insertBlockUnder({ text, key, replacement }) {
   return [...lines.slice(0, at + 1), ...replacement, '', ...lines.slice(at + 1)].join('\n');
 }
 
+/**
+ * A file with a delimited block INSERTED after a shell function's closing brace,
+ * and every other line of it left exactly as it was.
+ *
+ * The sibling of `insertBlockUnder`, for the file that is not a mapping. Both
+ * answer the same question — where does a block that is not there yet go? — and
+ * both answer it from something the FILE declares rather than from a judgement
+ * about the service. In a compose file that is the `services:` key; in an
+ * `init.sh` it is the end of the function the block's own text refers to
+ * ("A service's own install steps belong in oa_npm_install() above, everything
+ * else it needs goes below"), which the row names as its anchor.
+ *
+ * Measured 2026-09-16 in api_biz/invoicing: the sync refused this state with
+ * "paste the block from the template once", a message telling a human to
+ * hand-copy generated content, which is what `automation-gates.md` §1.4 calls a
+ * defect — the run knows the bytes and, with the anchor, the place.
+ *
+ * Without the anchor the refusal STAYS a refusal, and names the anchor rather
+ * than the block: where a service's own install steps end is that service's
+ * decision, and a generator guessing it would write the block above or below
+ * code that has to run on the other side.
+ *
+ * @param {{text: string, fn: string, replacement: string[]}} args the file, the
+ *   shell function the block belongs after, and the block's lines
+ * @returns {string}
+ */
+function insertBlockAfterFunction({ text, fn, replacement }) {
+  const lines = text.split('\n');
+  const opens = new RegExp(`^${fn}\\s*\\(\\)\\s*\\{`);
+
+  const start = lines.findIndex((line) => opens.test(line.trimEnd()));
+  if (start === -1) {
+    throw new Error(`[ServiceTemplate] No ${fn}() to insert the block after - the file declares no line `
+      + `opening "${fn}() {", so where this service's own install steps end is undefined and the block `
+      + `has no unambiguous place. Fix: wrap this file's install command in a ${fn}() function, then run `
+      + 'the sync again.');
+  }
+
+  const end = lines.findIndex((line, index) => index > start && line.trimEnd() === '}');
+  if (end === -1) {
+    throw new Error(`[ServiceTemplate] The ${fn}() function never closes - "${fn}() {" is there, its "}" `
+      + 'is not, so the end of the install steps is undefined. Fix: close the function, then run the sync again.');
+  }
+
+  return [...lines.slice(0, end + 1), '', ...replacement, ...lines.slice(end + 1)].join('\n');
+}
+
 /** A top-level mapping key: a line that starts in column 0 and ends its key with a colon. */
 const TOP_LEVEL_KEY = /^([A-Za-z_][A-Za-z0-9_.-]*):/;
 
@@ -565,6 +632,7 @@ module.exports = {
   SSOT_PIN,
   PACKED_NAMES,
   EXECUTABLE_FILES,
+  PACKAGE_ONLY,
   ENV_TEMPLATE_SOURCE,
   envTemplateTarget,
   deriveParams,
@@ -577,6 +645,7 @@ module.exports = {
   renderText,
   renderTree,
   spliceBlock,
+  insertBlockAfterFunction,
   topLevelKeys,
   replaceTopLevelKeys,
   insertBlockUnder

package/src/sync/sharedEnv.js

@@ -66,10 +66,17 @@ function assertManifest(manifest) {
  * nothing that varies between two runs - the same manifest always renders the
  * same bytes, which is what makes `--check` a gate rather than a diff of noise.
  *
- * `consumers` is deliberately NOT rendered: who reads a key is a fact the code
- * owns and a check measures, and a hand-maintained copy of it inside every
- * service's env file would rot the moment a reader moved
- * (`.claude/rules/doc-code-binding.md` §1).
+ * `consumers` is deliberately NOT rendered: a hand-maintained copy of who reads
+ * a key, inside every service's env file, would rot the moment a reader moved
+ * (`.claude/rules/doc-code-binding.md` §1). That half is measured - the CONTROL
+ * case in `tests/unit/sharedEnv.test.js` moves the field and asserts the
+ * rendered text does not move with it. The field's own content is held by
+ * REVIEW: no code in this package reads it, and no gate elsewhere does either
+ * (`api/config/shared-env.json`, `_consumers`). The machine answer to "who
+ * reads this name" is per service, not per platform: the `env-contract` check
+ * (row `C-ENV-READS` of `manifests/biz-service.manifest.json`) measures the
+ * names a service's code reads against what its
+ * `config/service/integration-contract.json` declares.
  *
  * @param {{keys: Array<{name: string, value: string, why: string}>}} manifest
  * @returns {string}

package/src/sync/uniformFiles.js

@@ -11,12 +11,19 @@
  * points the check at. A second list here would be a second owner of the shape,
  * and the two would diverge exactly the way the nine copies of `init.sh` did.
  *
- * The corollary is that a row the manifest does not make renderable is NOT
- * rendered. `G-PROD-IMAGE` names no reference — it is a requirement about a
- * file, not a file — so it is reported NOT RUN, with the reason, rather than
- * being filled from something this module decided
- * (`.claude/rules/automation-gates.md` §5: silence is a defect, and so is a
- * mechanism that quietly covers less than it claims).
+ * The corollary is that a row the manifest does not make renderable is not a
+ * row of this run at all. `G-PROD-IMAGE` and `G-SETUP` name no reference — the
+ * first is a requirement about a pin inside a file, the second about a directory
+ * existing — so the MANIFEST run answers them and the sync does not plan them
+ * (`syncRows` below). Until d.507 the sync planned them and printed NOT RUN: a
+ * line every `--check` in every repository ended on, naming a state its reader
+ * could do nothing about, which is the false guarantee
+ * `.claude/rules/automation-gates.md` §5 calls a defect and the `Fix`-less
+ * message its §1 requirement 4 forbids.
+ *
+ * NOT RUN stays for the other case, which is the one it was made for: a row the
+ * sync MUST render and cannot reach the reference of — named, with the reason
+ * and the command that makes it reachable, never skipped in silence.
  *
  * WHERE A ROW NEEDS MORE THAN A SPLICE, THE MODULE THAT OWNS THE RULE RENDERS
  * IT. Two rows are not "the reference, verbatim": the runner block carries three
@@ -39,10 +46,11 @@ const {
   withoutBlock, IGNORE_BLOCK, DOCKERIGNORE_BLOCK
 } = require('../manifest/checks/serviceFiles');
 const {
-  spliceBlock, insertBlockUnder, topLevelKeys, replaceTopLevelKeys
+  spliceBlock, insertBlockUnder, insertBlockAfterFunction, topLevelKeys, replaceTopLevelKeys
 } = require('./serviceTemplate');
 const { requireIdentity } = require('../manifest/serviceIdentity');
 const { rowNeedsWorkspace } = require('../manifest/manifestShape');
+const { describeWorkspaceFix } = require('../manifest/workspaceRoot');
 const { KINDS, applyUniformRegion } = require('./readmePointer');
 const { serviceRegion } = require('./readmeLocation');
 const { CHECK_REGISTRY } = require('../manifest/checks');
@@ -291,7 +299,12 @@ function renderDockerignoreEntries({ row, current, workspaceRoot }) {
     `# --- ${DOCKERIGNORE_BLOCK}`,
     `# Derived from ${referenceOwner(row.from)}, the declaration .gitignore reads too —`,
     '# what a LOCAL production build must not copy into the image (being ignored by git',
-    "# excludes nothing from COPY . .). Everything above this block is this repository's own.",
+    '# excludes nothing from COPY . .), PLUS the test tree: tests stay in the repository',
+    '# and out of the artefact that runs, the same decision the library uniform makes as',
+    '# L-PACK-TESTS. The one exception is tests/cookbooks, which is not a test but a',
+    '# declaration the runtime reads — Tier-1 of the boot runs those cookbooks at phase',
+    '# 0.2, and an image without them refuses its own validation proof as NO_TESTS.',
+    "# Everything above this block is this repository's own.",
     ...missing,
     `# --- end ${DOCKERIGNORE_BLOCK}`,
     ''
@@ -322,7 +335,11 @@ const RENDERERS = Object.freeze({
 const SYNCABLE_CLASSES = Object.freeze(['identical', 'generated', 'contains']);
 
 /**
- * The manifest rows this run is defined by, in manifest order.
+ * The manifest rows of the classes the generator owns, in manifest order.
+ *
+ * Not every one of them is a row this run renders — see `syncRows`. This is the
+ * full declaration, and the CLI needs it to tell a path the uniform declares as
+ * a REQUIREMENT from a path it has never heard of.
  *
  * @param {object} manifest
  * @returns {object[]}
@@ -332,6 +349,34 @@ function uniformRows(manifest) {
   return SYNCABLE_CLASSES.flatMap((className) => files[className] || []);
 }
 
+/**
+ * Whether the sync is defined for this row: does it name what its content comes
+ * from?
+ *
+ * The predicate is the manifest's own distinction, not a list of ids: a row with
+ * a `from:` reference is a file rendered from that reference, a row without one
+ * is a requirement about the repository, and the reference is exactly what
+ * `desiredContent` would read. Judging the reference rather than the id is why a
+ * new requirement row needs no change here.
+ *
+ * @param {object} row
+ * @returns {boolean}
+ */
+function isSyncRow(row) {
+  if (!row || !row.from) return false;
+  return typeof row.from.path === 'string' || isPackageReference(row.from);
+}
+
+/**
+ * The manifest rows this run is defined by, in manifest order.
+ *
+ * @param {object} manifest
+ * @returns {object[]}
+ */
+function syncRows(manifest) {
+  return uniformRows(manifest).filter(isSyncRow);
+}
+
 /**
  * Where two texts first differ, what the file says there, and what the run would
  * put there instead.
@@ -373,17 +418,14 @@ function readServiceFile(serviceRoot, relative) {
 }
 
 /**
- * What a row's file should contain, or why this run cannot say.
+ * What a row's file should contain.
  *
- * @returns {{desired: string}|{reason: string}}
+ * Only ever called for a row `isSyncRow` accepts, so the reference is there to
+ * be read; `planRow` is where that is checked, once, before anything reads.
+ *
+ * @returns {{desired: string}}
  */
 function desiredContent({ row, current, serviceRoot, workspaceRoot }) {
-  if (!row.from || (typeof row.from.path !== 'string' && !isPackageReference(row.from))) {
-    return {
-      reason: 'the row declares no "from" reference, so nothing says what this file\'s content is rendered from'
-    };
-  }
-
   const render = RENDERERS[row.check];
   if (render !== undefined) return { desired: render({ row, current, serviceRoot, workspaceRoot }) };
 
@@ -401,6 +443,18 @@ function desiredContent({ row, current, serviceRoot, workspaceRoot }) {
     throw new Error(`[UniformSync] Reference block "${row.block}" not found in ${referenceOwner(row.from)} - the row `
       + 'names a block the template does not carry. Fix: restore the block in the template, or correct the row.');
   }
+
+  // The block is missing from a file that exists. That is "not synced", not
+  // "paste it in by hand": the content is generated and the run holds it, so the
+  // only open question is WHERE — and a row answers that by naming an anchor the
+  // file itself declares (`insert_after_function`). Without one the refusal
+  // stands, because the position would then be a decision about this service
+  // rather than a fact about the file (the same line `insertBlockUnder` draws
+  // for a compose mapping). A message that tells a human to copy generated bytes
+  // is the defect `.claude/rules/automation-gates.md` §1.4 names.
+  if (blockLines(current, row.block).length === 0 && typeof row.insert_after_function === 'string') {
+    return { desired: insertBlockAfterFunction({ text: current, fn: row.insert_after_function, replacement }) };
+  }
   return { desired: spliceBlock({ text: current, block: row.block, replacement }) };
 }
 
@@ -412,6 +466,15 @@ function desiredContent({ row, current, serviceRoot, workspaceRoot }) {
  *            current: string|null, desired?: string, detail?: string, reason?: string}}
  */
 function planRow({ row, serviceRoot, workspaceRoot }) {
+  // Fail-fast rather than a NOT RUN line: `planSync` hands over only the rows
+  // `syncRows` selected, so a requirement row arriving here is a caller's
+  // mistake, and the caller is told which run does answer that row.
+  if (!isSyncRow(row)) {
+    throw new Error(`[UniformSync] ${row.id} declares no "from" reference - nothing says what ${row.path} `
+      + 'would be rendered from, so this row is a requirement about the repository rather than a file this '
+      + 'run writes. Fix: check it with npx oa-validate <serviceRoot>, which is the run that answers it.');
+  }
+
   const current = readServiceFile(serviceRoot, row.path);
   const base = { id: row.id, path: row.path, current };
 
@@ -425,9 +488,17 @@ function planRow({ row, serviceRoot, workspaceRoot }) {
     return {
       ...base,
       outcome: 'not-run',
+      // The check's own sentence, remedy included — not that sentence plus one
+      // of this module's. `workspaceRoot.js` § describeWorkspaceFix is the ONE
+      // owner of "point --workspace at a checkout that carries X" (d.516), and
+      // since d.523 every workspace-dependent check ends its NOT RUN sentence
+      // with it. Appending a second `Fix:` here produced two remedies for one
+      // absence, separated by a stray full stop — the second rail
+      // `.claude/rules/change-discipline.md` § One rail per concern names, in
+      // the one line a reader acts on.
       reason: check.describeNotRun
         ? check.describeNotRun({ row, block: null })
-        : 'the workspace root is not reachable'
+        : `the workspace root is not reachable. ${describeWorkspaceFix('api/ and api_biz/')}`
     };
   }
 
@@ -438,7 +509,6 @@ function planRow({ row, serviceRoot, workspaceRoot }) {
     return { ...base, outcome: 'blocked', reason: error.message };
   }
 
-  if (outcome.reason !== undefined) return { ...base, outcome: 'not-run', reason: outcome.reason };
   if (outcome.desired === current) return { ...base, outcome: 'unchanged', desired: outcome.desired };
 
   return {
@@ -456,7 +526,7 @@ function planRow({ row, serviceRoot, workspaceRoot }) {
  * @returns {object[]} one entry per row, in manifest order
  */
 function planSync({ manifest, serviceRoot, workspaceRoot, paths = [] }) {
-  const rows = uniformRows(manifest);
+  const rows = syncRows(manifest);
 
   const wanted = paths.length === 0 ? rows : paths.map((wantedPath) => {
     const row = rows.find((candidate) => candidate.path === wantedPath);
@@ -471,4 +541,4 @@ function planSync({ manifest, serviceRoot, workspaceRoot, paths = [] }) {
   return wanted.map((row) => planRow({ row, serviceRoot, workspaceRoot }));
 }
 
-module.exports = { SYNCABLE_CLASSES, uniformRows, planRow, planSync, firstDifference };
+module.exports = { SYNCABLE_CLASSES, uniformRows, isSyncRow, syncRows, planRow, planSync, firstDifference };

package/src/utils/bizCiGateContract.js

@@ -82,7 +82,31 @@ function assertRepoRelativePath(value, fieldName) {
 function normalizeDatabaseDeclaration(database, connectors) {
   // Absent means "this service has no database". Null rather than {} so callers
   // distinguish that from an empty declaration and skip the steps explicitly.
-  if (database === undefined || database === null) return null;
+  //
+  // Absent is only allowed together with its connector. `db: true` with no
+  // block used to pass — a transition allowance while the six repositories
+  // still carried their own ci-setup-db.js ("F4 tightens this"). F4 landed:
+  // utils/setupDatabase.js replaced all six, none of the eight biz
+  // repositories carries one, and every repository declaring `db: true`
+  // declares a block (measured 2026-09-16), so the gate lands with compliance
+  // already in place (`automation-gates.md` §3) and the allowance goes with it
+  // (`architecture-principles.md` §11, no transition shims).
+  //
+  // What it cost while it stood: the combination makes `setup-db` report NOT
+  // APPLICABLE — correctly, there is no schema to build — while
+  // `wait-connectors` waits for a database and `run-prevalidation` then
+  // dispatches the service's own handlers against a schema nobody built. The
+  // DB steps must run exactly where a database is declared, and the two keys
+  // are one fact stated twice.
+  if (database === undefined || database === null) {
+    if (connectors.db) {
+      throw new Error('[BizCiGate] Contradictory contract - requiredConnectors.db is true but the contract '
+        + 'carries no "database" block, so setup-db has no schema to build while wait-connectors waits for '
+        + 'one and the cookbooks run against whatever is there. '
+        + 'Fix: declare the database block (engine, schema, migrations), or set requiredConnectors.db to false.');
+    }
+    return null;
+  }
 
   if (typeof database !== 'object' || Array.isArray(database)) {
     throw new Error('[BizCiGate] Invalid database - Expected an object with engine, schema and migrations. '