@onlineapps/conn-orch-validator 12.2.0 → 13.0.0

package/src/manifest/checks/serviceConnectors.js

@@ -30,7 +30,10 @@
 const fs = require('fs');
 const path = require('path');
 
-const { verifyConnectorDeclarations, CONFIG_PATH, CONTRACT_PATH } = require('../../utils/connectorContract');
+const {
+  verifyConnectorDeclarations, CONNECTORS, CONFIG_PATH, CONTRACT_PATH
+} = require('../../utils/connectorContract');
+const { blockLines } = require('./serviceFiles');
 
 /**
  * The two declarations, or the reason they could not be read.
@@ -78,4 +81,179 @@ const connectorContract = Object.freeze({
   }
 });
 
-module.exports = { name: 'connector-contract', check: connectorContract };
+/**
+ * `C-CI-CONNECTOR-ENV` — the job that runs the suite sets the names the declared
+ * connectors are opened with.
+ *
+ * `C-CONNECTORS` above asks whether the two DECLARATIONS agree. This row asks
+ * whether the one environment those declarations are exercised in every day
+ * carries what they need. Measured 2026-09-18: three emailer tests failed in CI
+ * on `[RuntimeConfig] Missing environment variable - MINIO_USE_SSL`, a name no
+ * line of the service reads — `@onlineapps/conn-base-storage` resolves it,
+ * `required: true`, with no default. So `ci:gate:contract` could not see it
+ * (`utils/envContract.js` puts `node_modules` deliberately out of scope) and
+ * `ci:gate:env` emits six `OA_CI_*` names and measures nothing.
+ *
+ * Locally the same suite passes: the one-shot runner loads
+ * `config/env-templates/shared.env` through `env_file`, and that file — one
+ * generated copy of `api/config/shared-env.json`, held by `G-SHARED-ENV` —
+ * carries the key. The CI job's `variables:` is the SECOND delivery of the same
+ * set, copied by hand in eight repositories, and nothing compared it with the
+ * first. Owner decision `biz-service-manifest` 013, variant A.
+ *
+ * ## What it reads, and what it leaves alone
+ *
+ * The `variables:` of ONE job, named by the row, and only OUTSIDE the `oa-ci v1`
+ * block: that block is the platform's, `G-CI` renders it from the template byte
+ * for byte, and a value a service wrote there would not survive the next sync.
+ * The same boundary `D-DB-CI-ACCOUNT` reads, for the same reason, and reading a
+ * REGION rather than the whole file is what keeps both clear of the defect that
+ * had the whole-file row over `.gitlab-ci.yml` withdrawn after three days.
+ *
+ * It asks WHICH names that job sets and deliberately not WHETHER a repository
+ * runs one: "add a test job" is another fix, and one row with two fixes is two
+ * mechanisms under one name (`automation-gates.md` §1.2). A repository with no
+ * `.gitlab-ci.yml` at all is `G-CI`'s finding. Both silences are stated here
+ * because a boundary nobody states is read as coverage (`automation-gates.md` §5).
+ *
+ * It cannot see GitLab's project-level variables, which live outside the
+ * repository by design — so the names it measures are the ones with a platform
+ * value in `api/config/shared-env.json`, which belong in the file, never a
+ * secret.
+ *
+ * The set of names is NOT in the row: it is `CONNECTORS[<connector>].env`
+ * (`utils/connectorContract.js`), measured against the library that resolves
+ * them. A list copied into the manifest would be a second owner of one fact
+ * (`manifestShape.js` § OWNED_STRING_ARRAY_KEYS).
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md
+ */
+
+/** `KEY: value` as a YAML mapping line reads it, with the indent that places it. */
+const MAPPING = /^(\s*)([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$/;
+const COMMENT = /^\s*#/;
+const BLANK = /^\s*$/;
+
+/** The indent a line carries, or null when the line declares nothing. */
+function indentOf(line) {
+  if (COMMENT.test(line) || BLANK.test(line)) return null;
+  return line.length - line.trimStart().length;
+}
+
+/**
+ * The names the job's OWN `variables:` block sets.
+ *
+ * Indentation is the whole of the reading, because the measured file carries a
+ * SECOND `variables:` two levels deeper: the MinIO sidecar under `services:`
+ * sets `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD` for its own container. A scan
+ * collecting every `KEY:` under any `variables:` would read that container's
+ * environment as the job's and call a job green that sets nothing.
+ *
+ * @param {string[]} lines the file, split
+ * @param {number} jobAt index of the job's own key line
+ * @param {(index: number) => boolean} inBlock whether that line belongs to the generated block
+ * @returns {{names: Set<string>, at: number}} the names, and the line to point a finding at
+ */
+function jobVariables(lines, jobAt, inBlock) {
+  const names = new Set();
+  const jobIndent = indentOf(lines[jobAt]);
+
+  let bodyIndent = null;
+  let variablesAt = -1;
+
+  for (let index = jobAt + 1; index < lines.length; index += 1) {
+    const indent = indentOf(lines[index]);
+    if (indent === null) continue;
+    if (indent <= jobIndent) break; // the next job — this one's body has ended
+    if (bodyIndent === null) bodyIndent = indent;
+    if (indent !== bodyIndent) continue; // deeper: a sidecar, a script, a rules list
+
+    const mapping = lines[index].match(MAPPING);
+    if (mapping !== null && mapping[2] === 'variables') {
+      variablesAt = index;
+      break;
+    }
+  }
+
+  if (variablesAt === -1) return { names, at: jobAt };
+
+  for (let index = variablesAt + 1; index < lines.length; index += 1) {
+    if (inBlock(index)) break;
+    const indent = indentOf(lines[index]);
+    if (indent === null) continue;
+    if (indent <= bodyIndent) break;
+
+    const mapping = lines[index].match(MAPPING);
+    if (mapping !== null) names.add(mapping[2]);
+  }
+
+  return { names, at: variablesAt };
+}
+
+/** The generated copy of the platform's shared key set, as it sits in the repository. */
+const SHARED_TEMPLATE = 'config/env-templates/shared.env';
+
+/** Does the platform own a value for this name? Read from the generated copy, never printed. */
+function platformOwns(serviceRoot, key) {
+  const file = path.join(serviceRoot, ...SHARED_TEMPLATE.split('/'));
+  if (!fs.existsSync(file)) return false;
+  return fs.readFileSync(file, 'utf8').split('\n').some((line) => line.startsWith(`${key}=`));
+}
+
+const ciConnectorEnv = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'block', 'job']),
+
+  run({ row, serviceRoot }) {
+    const declarations = readDeclarations(serviceRoot);
+    if (declarations === null) return [];
+
+    const required = Object.entries(CONNECTORS)
+      .filter(([name]) => declarations.requiredConnectors[name] === true);
+    if (required.length === 0) return [];
+
+    const file = path.join(serviceRoot, ...row.path.split('/'));
+    // Whether the file is there at all is `G-CI`'s finding, with its own fix.
+    if (!fs.existsSync(file)) return [];
+
+    const text = fs.readFileSync(file, 'utf8');
+    const lines = text.split('\n');
+    const block = blockLines(text, row.block);
+    const blockStart = block.length === 0 ? -1 : lines.indexOf(block[0]);
+    const inBlock = (index) => blockStart !== -1 && index >= blockStart && index < blockStart + block.length;
+
+    const jobKey = new RegExp(`^(\\s*)${row.job.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*:\\s*(#.*)?$`);
+    const jobAt = lines.findIndex((line, index) => !inBlock(index) && jobKey.test(line));
+    // Which names that job sets is this row's question; whether the repository
+    // runs one at all is another fix and therefore another row.
+    if (jobAt === -1) return [];
+
+    const { names, at } = jobVariables(lines, jobAt, inBlock);
+
+    const findings = [];
+    for (const [connector, spec] of required) {
+      for (const key of spec.env) {
+        if (names.has(key)) continue;
+        findings.push({
+          where: `${row.path}:${at + 1}`,
+          what: `requiredConnectors.${connector} is true and the ${row.job} job declares no ${key} — the `
+            + "connector's library resolves that name with no default, so the suite meets it inside the "
+            + 'connector, where the cause is harder to see'
+            + (platformOwns(serviceRoot, key)
+              ? ` (the value is the one ${SHARED_TEMPLATE} declares for this key)`
+              : ` (${SHARED_TEMPLATE} declares no value for this key, so the job declares the one its own `
+                + 'sidecar uses)')
+        });
+      }
+    }
+
+    return findings;
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'connector-contract', check: connectorContract },
+    { name: 'ci-connector-env', check: ciConnectorEnv }
+  ]
+};

package/src/manifest/checks/serviceDb.js

@@ -43,9 +43,6 @@ const { blockLines } = require('./serviceFiles');
 const CONTRACT_PATH = 'config/service/integration-contract.json';
 const MIGRATIONS_DIR = 'migrations';
 
-/** The document an operator runs the SQL package from; the contract §3 requires it. */
-const MIGRATIONS_README = 'migrations/README.md';
-
 /** Where a service keeps its env templates, and the one that is not its own. */
 const ENV_TEMPLATE_DIR = 'config/env-templates';
 const SHARED_ENV = 'shared.env';

package/src/manifest/checks/serviceScripts.js

@@ -86,31 +86,14 @@ function binSpelling(body, bin) {
   return [bin, ...tokens.slice(2)].join(' ');
 }
 
-/**
- * Does this repository have an integration suite to run?
- *
- * The question decides whether `test:integration:container` is owed at all: a
- * script pointing at an absent suite is the dead declaration
- * `change-discipline.md` § "Removing something removes its declaration"
- * forbids, and jest exits 1 on a path that matches no test — so requiring it
- * unconditionally would ship a red script to every new service.
- *
- * @param {string} serviceRoot repository root
- * @param {string} relative the suite directory the row names
- * @returns {boolean}
- */
-function hasSuite(serviceRoot, relative) {
-  const dir = path.join(serviceRoot, ...relative.split('/'));
-  return fs.existsSync(dir) && fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length > 0;
-}
-
 const scriptBody = Object.freeze({
   scope: 'service',
   requires: Object.freeze(['name', 'body']),
 
   run({ row, serviceRoot }) {
-    if (row.only_with !== undefined && !hasSuite(serviceRoot, row.only_with)) return [];
-
+    // `only_with` sem nepatří a od d.838 tu není: podmíněnost je vlastnost
+    // ŘÁDKU a vyhodnocuje ji engine pro všechny druhy řádků
+    // (`manifest/runManifest.js`, `rowApplies`).
     const { scripts, present } = readScripts(serviceRoot);
     if (!present) return [{ where: 'package.json', what: 'absent — nothing declares this directory a service' }];
 

package/src/manifest/runManifest.js

@@ -19,7 +19,9 @@ const path = require('path');
 const { verifyManifestShape, rowNeedsWorkspace } = require('./manifestShape');
 const { collectRows } = require('./walk');
 const { discoverBearers, rootOfPattern } = require('./discovery');
-const { resolveWorkspacePath, canonicalRoot, describeWorkspaceFix } = require('./workspaceRoot');
+const {
+  resolveWorkspacePath, canonicalRoot, describeWorkspaceFix, workspaceRelativeOf
+} = require('./workspaceRoot');
 const { CHECK_REGISTRY } = require('./checks');
 
 /** The three scopes, by the name the runner branches on. */
@@ -100,19 +102,51 @@ const SCOPE_BEARER = 'bearer';
  * for eight services nobody looked at.
  */
 
+/**
+ * The shape a target version must have: `X.Y.Z` with an optional prerelease —
+ * what `npm publish` accepts as a version and what a CHANGELOG heading names.
+ */
+const TARGET_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/;
+
+/**
+ * Is this a version a run may be judged AS? The one owner of the question: the
+ * engine asks it at entry, and the CLI asks it while parsing `--as-version`, so a
+ * malformed value is refused before anything runs and with the same rule
+ * (`change-discipline.md` § One rail per concern).
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isTargetVersion(value) {
+  return typeof value === 'string' && TARGET_VERSION.test(value);
+}
+
 /**
  * @param {object} params
  * @param {object} params.manifest parsed manifest (loadManifest)
  * @param {string|null} [params.serviceRoot] the repository being checked; null = workspace mode
  * @param {string|null} params.workspaceRoot resolved workspace root, or null
  * @param {object} [params.checkRegistry] injected registry; defaults to the packaged one
+ * @param {string|null} [params.asVersion] the version being PUBLISHED, when it is not yet
+ *   in package.json — a publish dry run (`scripts/ci/lib/prepublishGate.js`, `--as-version`).
+ *   Handed to every check as `asVersion`; a check that judges a version reads it
+ *   (`checks/libraryDocs.js` § libraryChangelogEntry), the others ignore it. null = the
+ *   run judges the tree as it stands.
  * @returns {{ uniform: string, mode: string, serviceRoot: string|null, workspaceRoot: string|null,
  *             findings: Array<object>, notRun: Array<{id: string, reason: string}>, ok: boolean,
  *             blockingSeverities: string[], verdict: {blocked: string, clear: string} }}
  */
-function runManifest({ manifest, serviceRoot = null, workspaceRoot = null, checkRegistry = CHECK_REGISTRY }) {
+function runManifest({
+  manifest, serviceRoot = null, workspaceRoot = null, checkRegistry = CHECK_REGISTRY, asVersion = null
+}) {
   const mode = serviceRoot === null || serviceRoot === undefined ? 'workspace' : 'service';
 
+  if (asVersion !== null && !isTargetVersion(asVersion)) {
+    throw new Error(`[Manifest] Target version is not a version - asVersion ${JSON.stringify(asVersion)} `
+      + 'is not X.Y.Z or X.Y.Z-<prerelease>. Fix: pass the version being published, e.g. "1.2.4", '
+      + 'or null to judge package.json as it stands.');
+  }
+
   if (mode === 'workspace' && workspaceRoot === null) {
     throw new Error('[Manifest] A run without a service root needs a workspace root - runManifest() got '
       + 'neither, so it would check nothing. Fix: pass serviceRoot to check one repository, '
@@ -226,7 +260,7 @@ function runManifest({ manifest, serviceRoot = null, workspaceRoot = null, check
     }
 
     const raised = rowFindings({
-      check, row, block, mode, root, workspaceRoot: workspace, bearers, underServiceRoot
+      check, row, block, mode, root, workspaceRoot: workspace, bearers, underServiceRoot, asVersion
     });
 
     // A check may also report that it could not DECIDE the row — not because
@@ -400,6 +434,40 @@ function readAnswer(returned) {
   };
 }
 
+/** A row that answers nothing: neither a finding nor a reason it could not look. */
+const SILENT = Object.freeze({ findings: Object.freeze([]), notRun: null });
+
+/**
+ * Does this row apply to this bearer at all?
+ *
+ * `only_with: <relative path>` says the row is owed only where that path carries
+ * something — the suite `S-INT-C` names, the config file a future row will name.
+ * A directory that exists and is EMPTY does not count: an empty `tests/` is not
+ * a suite, and requiring the script that runs it would ship a red command to
+ * every new service (the reason the condition exists at all, d.482).
+ *
+ * The question is asked HERE, for every kind of row, because it is a property of
+ * the ROW, not of one check: until d.838 only `scriptBody` consulted it, so the
+ * same word in a config row would have stood in the manifest and decided
+ * nothing — a rule visible in the declaration and absent from the run
+ * (`automation-gates.md` §5). One place, every scope
+ * (`change-discipline.md` § One rail per concern).
+ *
+ * @param {object} row the manifest row
+ * @param {string} bearerRoot the root the row is measured against
+ * @returns {boolean}
+ */
+function rowApplies(row, bearerRoot) {
+  if (row.only_with === undefined) return true;
+
+  const target = path.join(bearerRoot, ...row.only_with.split('/'));
+  if (!fs.existsSync(target)) return false;
+
+  return fs.statSync(target).isDirectory()
+    ? fs.readdirSync(target).length > 0
+    : true;
+}
+
 /**
  * Run one row's check wherever its scope says it belongs, and return what it
  * raised. The three branches are the three scopes and nothing else — a caller
@@ -409,9 +477,10 @@ function readAnswer(returned) {
  * @param {object} params the check, its row and block, and the run's roots
  * @returns {{findings: Array<{where: string, what: string}>, notRun: string|null}}
  */
-function rowFindings({ check, row, block, mode, root, workspaceRoot, bearers, underServiceRoot }) {
+function rowFindings({ check, row, block, mode, root, workspaceRoot, bearers, underServiceRoot, asVersion }) {
   if (check.scope === SCOPE_WORKSPACE) {
-    const answer = readAnswer(check.run({ row, block, serviceRoot: root, workspaceRoot }));
+    if (!rowApplies(row, root)) return SILENT;
+    const answer = readAnswer(check.run({ row, block, serviceRoot: root, workspaceRoot, asVersion }));
     return { ...answer, findings: answer.findings.filter(underServiceRoot) };
   }
 
@@ -419,9 +488,11 @@ function rowFindings({ check, row, block, mode, root, workspaceRoot, bearers, un
     // One row, several bearers: the findings add up, and the row is NOT RUN as
     // soon as ONE bearer could not be decided — the run did not reach every
     // bearer of it, and saying otherwise is the silence this reports.
-    const answers = bearers().map((bearer) => readAnswer(check.run({
-      row, block, serviceRoot: bearer.dir, workspaceRoot
-    })));
+    const answers = bearers()
+      .filter((bearer) => rowApplies(row, bearer.dir))
+      .map((bearer) => readAnswer(check.run({
+        row, block, serviceRoot: bearer.dir, workspaceRoot, asVersion
+      })));
     const undecided = answers.find((answer) => answer.notRun !== null);
     return {
       findings: answers.flatMap((answer) => answer.findings),
@@ -429,7 +500,9 @@ function rowFindings({ check, row, block, mode, root, workspaceRoot, bearers, un
     };
   }
 
-  return readAnswer(check.run({ row, block, serviceRoot: root, workspaceRoot }));
+  if (!rowApplies(row, root)) return SILENT;
+
+  return readAnswer(check.run({ row, block, serviceRoot: root, workspaceRoot, asVersion }));
 }
 
 /**
@@ -490,11 +563,15 @@ function buildScopeFilter({ mode, root, workspaceRoot }) {
   // NOT RUN, not filtered.
   if (mode === 'workspace' || workspaceRoot === null) return () => true;
 
-  const relative = path.relative(workspaceRoot, root);
-  if (relative === '') return () => true;
+  // The SAME spelling `whereOf` gave the findings this filters, from the one
+  // owner of it (`workspaceRoot.js` § workspaceRelativeOf). Subtracting the
+  // workspace root here and writing `api/…` there would make a service-mode run
+  // in a checkout not named `api` — which every CI checkout is — drop every
+  // workspace finding about the service it was asked about.
+  const prefix = workspaceRelativeOf(workspaceRoot, root);
+  if (prefix === '') return () => true;
 
-  const prefix = relative.split(path.sep).join('/');
   return (finding) => finding.where === prefix || finding.where.startsWith(`${prefix}/`);
 }
 
-module.exports = { runManifest, incompleteRows };
+module.exports = { runManifest, incompleteRows, isTargetVersion };

package/src/manifest/workspaceRoot.js

@@ -70,7 +70,13 @@
 const fs = require('fs');
 const path = require('path');
 
-/** The prefix every manifest path uses for the api checkout. */
+/**
+ * The prefix every manifest path uses for the api checkout, and the one owner of
+ * that convention for this package: the lint that resolves an `api/…` citation,
+ * the row that reports such a citation NOT RUN and the README pointer all read
+ * this export rather than writing the word again
+ * (`api/.claude/rules/single-source-of-truth.md`).
+ */
 const API_PREFIX = 'api';
 
 /** What identifies an api checkout, whatever the checkout is named. */
@@ -202,8 +208,117 @@ function resolveWorkspacePath(workspaceRoot, relative) {
 }
 
 /**
- * The workspace a given tree belongs to: the nearest ancestor carrying the
- * marker under the name the prefix writes. This answers a DIFFERENT question
+ * The inverse of `resolveWorkspacePath`: an absolute path written back in the
+ * form the manifest, the rows and their findings write it — `api/…` for
+ * anything inside the api checkout, whatever that checkout is NAMED, and
+ * workspace-relative for everything else.
+ *
+ * It is the same rule `scripts/ci/lint-biz-docs.mjs` § workspaceRelativeOf
+ * already applies to its own findings, and it exists here for the same measured
+ * reason. Subtracting the workspace root yields the checkout's DIRECTORY NAME,
+ * and GitLab CI checks this repository out under the project name: measured
+ * 2026-09-18 in the CI image over a tree named `infra-mono` (job
+ * `test-unit-aggregate` 16581767451), the documentation row reported
+ * `infra-mono/shared/connector/conn-orch-validator/…/deployment.md:3` — a path
+ * that exists under no name the reader can paste anywhere
+ * (`.claude/rules/automation-gates.md` §1 requirement 4), from a run whose
+ * finding was real.
+ *
+ * One owner, two readers, and they must agree: `checks/libraryContext.js`
+ * § whereOf writes the `where` of a finding, and `runManifest.js`
+ * § buildScopeFilter decides which workspace findings a service-mode run keeps
+ * by comparing that same string against this same path. Two spellings of one
+ * path would make a service-mode run in CI drop every workspace finding about
+ * itself (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * @param {string} workspaceRoot
+ * @param {string} absolute a path inside the workspace, or inside its api checkout
+ * @returns {string} a `/`-separated workspace-relative path, `''` for the
+ *   workspace root itself and a `..`-leading path for anything outside it
+ */
+function workspaceRelativeOf(workspaceRoot, absolute) {
+  if (typeof workspaceRoot !== 'string' || workspaceRoot.length === 0) {
+    throw new Error('[ManifestWorkspace] Workspace root is required - workspaceRelativeOf() got '
+      + `${JSON.stringify(workspaceRoot)}. Fix: resolve it first (resolveWorkspaceRoot).`);
+  }
+
+  const target = path.resolve(absolute);
+  const apiRoot = apiCheckoutOf(workspaceRoot);
+  if (apiRoot !== null) {
+    // Both spellings, or a run below the system temp answers about the symlink
+    // instead of the directory (§ canonicalRoot).
+    const inside = path.relative(canonicalRoot(apiRoot), target);
+    if (inside === '') return API_PREFIX;
+    if (!inside.startsWith('..') && !path.isAbsolute(inside)) {
+      return [API_PREFIX, ...inside.split(path.sep)].join('/');
+    }
+  }
+  return path.relative(path.resolve(workspaceRoot), target).split(path.sep).join('/');
+}
+
+/**
+ * The checkout a tree lies in: the nearest directory, the tree itself included,
+ * that carries `API_MARKER` — or `null` when none above it does. It is read by
+ * `requirePackageInApiCheckout` alone, to name the checkout whose validator
+ * measures a package this one does not speak for.
+ *
+ * @param {string} tree
+ * @returns {string|null}
+ */
+function checkoutAbove(tree) {
+  let current = path.resolve(tree);
+  for (;;) {
+    if (carriesMarker(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * A library run measures ONE package against the api checkout of the workspace
+ * it resolved — the checkout this copy speaks for (§ apiCheckoutOf). Every row
+ * that renders a link or writes a `where` does so against that checkout, so a
+ * package lying outside it is judged against the wrong tree. Measured 2026-09-26
+ * (d.938): the validator of `api/` over the same package in a sibling worktree
+ * reported `L-README-REGION` with a fix that would have rewritten the README to
+ * point into the other checkout, while that checkout's own validator found
+ * nothing. The run stops before any row and names the command that measures the
+ * package from the checkout carrying it (d.940).
+ *
+ * @param {string} workspaceRoot the resolved workspace root of the run
+ * @param {string} packageRoot the canonical package directory the run is about
+ * @returns {void}
+ * @throws {Error} when the package lies outside that workspace's api checkout
+ */
+function requirePackageInApiCheckout(workspaceRoot, packageRoot) {
+  const apiRoot = apiCheckoutOf(workspaceRoot);
+  if (apiRoot === null) {
+    throw new Error(`[ManifestWorkspace] Workspace root holds no api checkout - ${path.resolve(workspaceRoot)} `
+      + `carries no directory with ${API_MARKER}, so no checkout can measure ${packageRoot}. `
+      + 'Fix: pass --workspace <root> holding the api checkout (under any name).');
+  }
+
+  const speaksFor = canonicalRoot(apiRoot);
+  const inside = path.relative(speaksFor, canonicalRoot(packageRoot));
+  const outside = inside === '..' || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside);
+  if (!outside) return;
+
+  const carrier = checkoutAbove(packageRoot);
+  if (carrier === null) {
+    throw new Error(`[ManifestWorkspace] ${packageRoot} lies outside the checkout this validator speaks for `
+      + `(${speaksFor}) - and no directory above it carries ${API_MARKER}, so no checkout carries it. `
+      + 'Fix: run oa-validate from the checkout that carries the package sources.');
+  }
+  const cli = path.join(carrier, ...PACKAGE_LOCATION, path.basename(PACKAGE_ROOT), 'src', 'cli', 'oa-validate.js');
+  throw new Error(`[ManifestWorkspace] ${packageRoot} lies outside the checkout this validator speaks for `
+    + `(${speaksFor}) - Fix: run oa-validate from the checkout that carries the package: `
+    + `node ${cli} --library ${packageRoot}`);
+}
+
+/**
+ * The workspace a given tree belongs to: the nearest ancestor that carries an
+ * api checkout. This answers a DIFFERENT question
  * from the one above — not "which SSOT does this package speak for" but "which
  * workspace is this tree part of" — and it is the question a run that writes
  * INTO a tree has to ask (`oa-sync-template --target <service>`, and the
@@ -211,13 +326,24 @@ function resolveWorkspacePath(workspaceRoot, relative) {
  * constructed with). A caller states which question it is asking by passing
  * `startDir` or leaving it out; neither is a default of the other.
  *
+ * WHAT makes an ancestor the workspace is `apiCheckoutOf`, not the literal
+ * string `api/config/services.json`, and the difference is the whole of the
+ * header above: the checkout is named after the GitLab project, so joining the
+ * literal onto every ancestor finds nothing in CI. Measured 2026-09-18 over a
+ * checkout named `infra-mono` (`tests/scripts/readme-uniform-pointer.bats:241`):
+ * `oa-sync-template readme-uniform` got `null` for a tree lying inside the very
+ * workspace it was run in, and labelled the file it wrote with an absolute path
+ * — a name that means something different on every machine. One rule for "this
+ * directory carries an api checkout", read by the three questions below and by
+ * this one (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
  * @param {string} startDir
  * @returns {string|null}
  */
 function workspaceAbove(startDir) {
   let current = path.resolve(startDir);
   for (;;) {
-    if (fs.existsSync(path.join(current, ...WORKSPACE_MARKER.split('/')))) return current;
+    if (apiCheckoutOf(current) !== null) return current;
     const parent = path.dirname(current);
     if (parent === current) return null;
     current = parent;
@@ -318,10 +444,13 @@ module.exports = {
   canonicalRoot,
   workspaceAbove,
   resolveWorkspacePath,
+  workspaceRelativeOf,
   describeWorkspaceFix,
   apiCheckoutOf,
+  requirePackageInApiCheckout,
   API_CHECKOUT_ROOT,
   API_MARKER,
+  API_PREFIX,
   AS_THE_REASON_NAMES,
   PACKAGE_ROOT,
   WORKSPACE_MARKER

package/src/mocks/MockMQClient.js

@@ -131,7 +131,7 @@ class MockMQClient {
    * Acknowledge message.
    *
    * Signature and idempotence per `BaseClient.ack(msg)` → transport
-   * `rabbitmqClient.js:2286`: a delivery already settled (marked
+   * `RabbitMQClient.ack` (`transports/rabbitmqClient.js`): a delivery already settled (marked
    * `_mqProcessed`) is silently skipped rather than settled twice.
    *
    * @param {Object} message - Broker message object
@@ -156,7 +156,7 @@ class MockMQClient {
    * Negative-acknowledge a message.
    *
    * Signature and semantics per `BaseClient.nack(msg, options)` → transport
-   * `rabbitmqClient.js:2313`:
+   * `RabbitMQClient.nack` (`transports/rabbitmqClient.js`):
    *
    *   const requeue = options.requeue !== undefined ? options.requeue : true;
    *

package/src/sync/docsRegion.js

@@ -4,8 +4,8 @@
  * The generated regions of the documentation tree.
  *
  * Confirmation `biz-service-manifest` 002 §16.2: the list of required files,
- * scripts, limits, categories and duties that `docs/biz/60-templates/…`,
- * `docs/guides/library-publishing-process.md` and `docs/guides/DEVELOPMENT.md`
+ * scripts, limits, categories and duties that `api/docs/biz/60-templates/…`,
+ * `api/docs/guides/library-publishing-process.md` and `api/docs/guides/DEVELOPMENT.md`
  * copy by hand becomes a generated region fed by the manifests, and `--check`
  * fails the run when a region is stale. Three documents were measured copying
  * the same repository tree, and two copying the same script table; a copy is

package/src/sync/readmeFile.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * The name of the file a uniform pointer is a region of — one declaration for
+ * the whole package.
+ *
+ * It is a module of its own, and the shape of the package is what decided that.
+ * Four places wrote the string by hand until d.739b: the module that decides
+ * WHERE a pointer lives (`readmeLocation.js`), the one that renders the region
+ * (`readmePointer.js`), the row that judges a library's README
+ * (`manifest/checks/libraryDocs.js`) and the sync command. Neither of the two
+ * modules that already know about READMEs could hold it for the others:
+ *
+ *   - `readmeLocation.js` cannot be the owner `readmePointer.js` imports from,
+ *     because `readmeLocation.js` already requires `./readmePointer` — the
+ *     second import would close a cycle;
+ *   - `readmePointer.js` cannot take the name from its caller instead, because
+ *     that changes `applyUniformRegion`'s signature, which `src/cli/oa-sync-template.js`
+ *     and `src/sync/uniformFiles.js` read from outside that pair.
+ *
+ * A module that owns the one constant and requires nothing is what neither
+ * problem touches, and it keeps `readmeLocation.js`'s own sentence true: the
+ * renderer knows no path of its own (`.claude/rules/change-discipline.md`
+ * § One rail per concern).
+ */
+
+/** The file the uniform pointer lives in, for both bearer kinds. */
+const README_FILE = 'README.md';
+
+module.exports = { README_FILE };