@onlineapps/conn-orch-validator 12.2.0 → 13.0.0

package/src/sync/readmeLocation.js

@@ -29,12 +29,10 @@ const path = require('path');
 
 const { loadManifest, DEFAULT_MANIFEST_PATH, LIBRARY_MANIFEST_PATH } = require('../manifest/loadManifest');
 const {
-  API_CHECKOUT_ROOT, PACKAGE_ROOT: OWN_ROOT, WORKSPACE_MARKER, resolveWorkspacePath
+  API_CHECKOUT_ROOT, PACKAGE_ROOT: OWN_ROOT, API_PREFIX, resolveWorkspacePath
 } = require('../manifest/workspaceRoot');
 const { KINDS, renderUniformRegion } = require('./readmePointer');
-
-/** The file the pointer is a region of. */
-const README_FILE = 'README.md';
+const { README_FILE } = require('./readmeFile');
 
 /**
  * This package, by the name a consumer installs it under — read when a link
@@ -74,13 +72,6 @@ function serviceManifestPath(serviceRoot) {
   return path.join(serviceRoot, 'node_modules', ...selfName().split('/'), SERVICE_MANIFEST_IN_PACKAGE);
 }
 
-/**
- * The conventional prefix a workspace-relative path uses for the api checkout,
- * read off the marker that declares it rather than typed a second time here
- * (`../manifest/workspaceRoot.js`, which owns both the prefix and the marker).
- */
-const [API_PREFIX] = WORKSPACE_MARKER.split('/');
-
 /**
  * Where this package lies inside its own workspace, workspace-relative — or null
  * when it lies in no checkout at all (an installed copy, a service container).
@@ -190,7 +181,6 @@ function libraryRegion({ packageDir, pkg, workspaceRoot, manifest }) {
 }
 
 module.exports = {
-  README_FILE,
   selfName,
   PACKAGE_ROOT,
   PACKAGE_IN_WORKSPACE,

package/src/sync/readmePointer.js

@@ -42,6 +42,7 @@
 const path = require('path');
 
 const { markersFor, replaceRegion, extractRegion: extractBetween, checkRegion } = require('./generatedRegion');
+const { README_FILE } = require('./readmeFile');
 
 /** The bearer kinds this package renders a pointer for. */
 const KINDS = Object.freeze({ library: 'library', service: 'service' });
@@ -57,8 +58,13 @@ const ALL_CATEGORIES = '*';
  */
 const DISCOVERY_SECTION = 'discovery';
 
-/** The file every error of this module is about; the prefix is generatedRegion.js's own. */
-const WHERE = Object.freeze({ file: 'README.md' });
+/**
+ * The file every error of this module is about; the prefix is
+ * generatedRegion.js's own. The name comes from `readmeFile.js`, which owns it
+ * for the whole package — this module renders the region and names no file of
+ * its own (d.739b).
+ */
+const WHERE = Object.freeze({ file: README_FILE });
 
 const code = (value) => `\`${value}\``;
 
@@ -392,7 +398,7 @@ function headerEnd(lines, { required }) {
     if (!required) return 0;
     throw new Error('[ReadmePointer] README has no node header - the file must open with the '
       + '"> Status:" / "> Owns:" block, and the region is placed after it. '
-      + 'Fix: give README.md the node header (api/docs/standards/INFRA-DOC-STANDARD.md).');
+      + `Fix: give ${README_FILE} the node header (api/docs/standards/INFRA-DOC-STANDARD.md).`);
   }
 
   let index = 0;
@@ -402,7 +408,7 @@ function headerEnd(lines, { required }) {
     throw new Error('[ReadmePointer] Node header is not followed by a blank line - the region is placed '
       + `after it and the shape has to be unambiguous, but line ${index + 1} is `
       + `${JSON.stringify(lines[index] === undefined ? null : lines[index])}. `
-      + 'Fix: leave one blank line between the "> " block and the rest of README.md.');
+      + `Fix: leave one blank line between the "> " block and the rest of ${README_FILE}.`);
   }
   return index + 1;
 }

package/src/sync/serviceTemplate.js

@@ -23,6 +23,8 @@
 const fs = require('fs');
 const path = require('path');
 
+const { rewritableTopLevelKeys } = require('../utils/yamlTopLevel');
+
 /** The template as it lies in this package. */
 const TEMPLATE_ROOT = path.join(__dirname, '..', '..', 'templates', 'business-service');
 
@@ -550,9 +552,6 @@ function insertBlockAfterFunction({ text, fn, replacement }) {
   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_.-]*):/;
-
 /**
  * The top-level mapping keys a run of lines declares, in the order it declares
  * them.
@@ -563,16 +562,17 @@ const TOP_LEVEL_KEY = /^([A-Za-z_][A-Za-z0-9_.-]*):/;
  * (`.claude/rules/change-discipline.md` § One rail per concern), and the day the
  * block gained a job the two would disagree about which file had drifted.
  *
- * Column 0 is the whole rule, and it is enough for the one file this reads:
- * a `.gitlab-ci.yml` job is a top-level key and everything it owns is indented
- * under it. Text in, text out — nothing is re-serialized, so a comment and a
- * quoting style survive (`.claude/rules/automation-gates.md` §1 requirement 3).
+ * What a top-level key IS has one owner, `src/utils/yamlTopLevel.js`, and this
+ * takes the REWRITABLE reading of it: hidden keys (`.oa-uniform:`) are left out,
+ * because the same list drives `replaceTopLevelKeys`, which DELETES what it
+ * matches, and a hidden key a service wrote itself is not the platform's to
+ * delete.
  *
  * @param {string[]} lines
  * @returns {string[]}
  */
 function topLevelKeys(lines) {
-  return lines.map((line) => (TOP_LEVEL_KEY.exec(line) || [])[1]).filter((key) => key !== undefined);
+  return rewritableTopLevelKeys(lines.join('\n')).map((key) => key.name);
 }
 
 /**
@@ -597,9 +597,7 @@ function topLevelKeys(lines) {
  */
 function replaceTopLevelKeys({ text, keys, replacement }) {
   const lines = text.split('\n');
-  const starts = lines
-    .map((line, index) => ({ key: (TOP_LEVEL_KEY.exec(line) || [])[1], index }))
-    .filter((entry) => entry.key !== undefined);
+  const starts = rewritableTopLevelKeys(text).map(({ name, line }) => ({ key: name, index: line }));
 
   const doomed = new Set();
   for (let i = 0; i < starts.length; i += 1) {

package/src/sync/sharedEnv.js

@@ -26,6 +26,49 @@ const DIFF_HEADER = Object.freeze([
   '+++ on disk'
 ]);
 
+/**
+ * The opening of the per-machine marker line, and the only field its
+ * declaration carries. A template says with it that the value of a key is a
+ * property of the box rather than of the platform, so the drift gate must not
+ * judge it.
+ *
+ * @see api/scripts/lib/env-template-markers.sh - the reader of this marker
+ * @see api/scripts/validate-env.sh - the gate that consults the reader (--check-drift)
+ */
+const PER_MACHINE_PREFIX = '# @per-machine — ';
+const PER_MACHINE_FIELDS = Object.freeze(['reason']);
+
+function assertPerMachine(name, perMachine) {
+  if (typeof perMachine !== 'object' || perMachine === null || Array.isArray(perMachine)) {
+    throw new Error(`[SharedEnv] Key ${name} has a "perMachine" that is not an object - expected `
+      + '{ "reason": "<why this machine\'s value differs>" }, because a marker with no reason '
+      + 'exempts a key from the drift gate without saying who decided it. Fix: write "perMachine": '
+      + '{ "reason": "..." } for that key in api/config/shared-env.json.');
+  }
+
+  Object.keys(perMachine).forEach((field) => {
+    if (!PER_MACHINE_FIELDS.includes(field)) {
+      throw new Error(`[SharedEnv] Key ${name} has an unknown "perMachine" field `
+        + `${JSON.stringify(field)} - expected "reason" and nothing else, so a field nobody renders `
+        + 'cannot look like a declaration. Fix: remove it from that key in '
+        + 'api/config/shared-env.json.');
+    }
+  });
+
+  if (typeof perMachine.reason !== 'string' || perMachine.reason.trim() === '') {
+    throw new Error(`[SharedEnv] Key ${name} has a "perMachine" with no "reason" - the marker line `
+      + 'states why THIS machine differs, and the drift gate quotes it back to the operator. '
+      + 'Fix: add "reason" to that key\'s "perMachine" in api/config/shared-env.json.');
+  }
+
+  if (/[\r\n]/.test(perMachine.reason)) {
+    throw new Error(`[SharedEnv] Key ${name} has a multi-line "perMachine.reason" - the generated `
+      + 'file carries one marker line per key, and the reader holds a marker only inside the '
+      + 'comment block immediately above the key. Fix: write it as a single sentence in '
+      + 'api/config/shared-env.json.');
+  }
+}
+
 function assertManifest(manifest) {
   const keys = manifest && manifest.keys;
   if (!Array.isArray(keys) || keys.length === 0) {
@@ -46,7 +89,7 @@ function assertManifest(manifest) {
     }
     if (typeof key.why !== 'string' || key.why.trim() === '') {
       throw new Error(`[SharedEnv] Key ${name} has no "why" - every shared key states why the platform `
-        + 'shares it (docs/biz/70-contracts/env-contract.md). Fix: add "why" to that key in '
+        + 'shares it (api/docs/biz/70-contracts/env-contract.md). Fix: add "why" to that key in '
         + 'api/config/shared-env.json.');
     }
     if (/[\r\n]/.test(key.why)) {
@@ -57,6 +100,9 @@ function assertManifest(manifest) {
       throw new Error(`[SharedEnv] Key ${name} has a multi-line "value" - an env file carries one line `
         + 'per key. Fix: correct the value in api/config/shared-env.json.');
     }
+    if (key.perMachine !== undefined) {
+      assertPerMachine(name, key.perMachine);
+    }
   });
 }
 
@@ -78,7 +124,13 @@ function assertManifest(manifest) {
  * 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
+ * A key that declares `perMachine` renders a second comment line under its
+ * `why`, immediately above `KEY=`: the marker of
+ * `api/scripts/lib/env-template-markers.sh`, which holds only inside the
+ * contiguous comment block above the key it belongs to.
+ *
+ * @param {{keys: Array<{name: string, value: string, why: string,
+ *   perMachine?: {reason: string}}>}} manifest
  * @returns {string}
  */
 function renderSharedEnv(manifest) {
@@ -86,7 +138,11 @@ function renderSharedEnv(manifest) {
 
   const lines = [...HEADER];
   manifest.keys.forEach((key) => {
-    lines.push('', `# ${key.why}`, `${key.name}=${key.value}`);
+    lines.push('', `# ${key.why}`);
+    if (key.perMachine !== undefined) {
+      lines.push(`${PER_MACHINE_PREFIX}${key.perMachine.reason}`);
+    }
+    lines.push(`${key.name}=${key.value}`);
   });
 
   return `${lines.join('\n')}\n`;

package/src/sync/uniformFiles.js

@@ -38,7 +38,11 @@
 const fs = require('fs');
 const path = require('path');
 
-const { readReferencedFile, isPackageReference, referenceOwner } = require('../manifest/discovery');
+const {
+  readReferencedFile, isPackageReference, referenceOwner, resolveFromDocument
+} = require('../manifest/discovery');
+const { renderSharedEnv } = require('./sharedEnv');
+const { collectRows } = require('../manifest/walk');
 const { readComposeServices } = require('../manifest/checks/composeShape');
 const { renderRunnerBlock, replaceServiceNode } = require('../manifest/checks/composeRunnerBlock');
 const {
@@ -175,6 +179,24 @@ function renderReadme({ row, current, serviceRoot }) {
   return applyUniformRegion(current, serviceRegion(serviceRoot), { kind: KINDS.service });
 }
 
+/**
+ * `config/env-templates/shared.env` from the platform env manifest.
+ *
+ * The same expression the row's own check evaluates
+ * (`../manifest/checks/serviceConfig.js` § sharedEnvGenerated): the referenced
+ * document, handed to the module that owns the shared key set. Nothing here
+ * knows a key, a format or a path to the SSOT — the row names the owner and
+ * `sharedEnv.js` renders it, which is why the `shared-env` subcommand and this
+ * run cannot produce two different files (`.claude/rules/change-discipline.md`
+ * § One rail per concern).
+ *
+ * @param {{row: object, workspaceRoot: string}} args
+ * @returns {string}
+ */
+function renderSharedEnvFile({ row, workspaceRoot }) {
+  return renderSharedEnv(resolveFromDocument({ from: row.from, workspaceRoot }));
+}
+
 /**
  * A whole file rendered for THIS repository: the template with the one parameter
  * a service has in it, its declared name.
@@ -325,7 +347,8 @@ const RENDERERS = Object.freeze({
   'template-render': renderRendered,
   'delimited-block-render': renderDelimitedBlock,
   'template-skeleton': renderSkeleton,
-  'readme-uniform-current': renderReadme
+  'readme-uniform-current': renderReadme,
+  'shared-env-generated': renderSharedEnvFile
 });
 
 /**
@@ -337,7 +360,28 @@ const SYNCABLE_CLASSES = Object.freeze(['identical', 'generated', 'contains']);
 /**
  * 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
+ * Two ways in, and the second one is why this is not one flatMap:
+ *
+ *   * a row of `files.<class>` wears the class of the array it sits in;
+ *   * a row ANYWHERE else wears the class it DECLARES, in a `class` field of
+ *     its own.
+ *
+ * The second exists because a generated file is not always reported under
+ * `files`. `G-SHARED-ENV` is filed under `config`, where the manifest reports
+ * about a service's configuration, and until d.710 that placement decided
+ * something it was never meant to decide: the sync's row set was the `files`
+ * section, so `oa-validate` measured `config/env-templates/shared.env` and the
+ * sync wrote nothing — instruction 3 of the cascade ("sync every row") was four
+ * commands each of the eight repositories assembled for itself, and BIZ-ingest
+ * escalated that the bare run does not include that row. A section is a place
+ * to report from; what a file IS belongs to the row.
+ *
+ * A row joins by SAYING so, never by being in a section somebody read as
+ * generated: `files.own` and `files.forbidden` cannot drift into this run, and
+ * neither can a future row of any other section (`automation-gates.md` §1
+ * requirement 1 — no dependence on state nobody declared).
+ *
+ * Not every row here 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.
  *
@@ -346,12 +390,18 @@ const SYNCABLE_CLASSES = Object.freeze(['identical', 'generated', 'contains']);
  */
 function uniformRows(manifest) {
   const files = (manifest && manifest.files) || {};
-  return SYNCABLE_CLASSES.flatMap((className) => files[className] || []);
+  const inFiles = SYNCABLE_CLASSES.flatMap((className) => files[className] || []);
+
+  const declared = collectRows(manifest || {})
+    .map((entry) => entry.row)
+    .filter((row) => SYNCABLE_CLASSES.includes(row.class) && !inFiles.includes(row));
+
+  return [...inFiles, ...declared];
 }
 
 /**
- * Whether the sync is defined for this row: does it name what its content comes
- * from?
+ * Whether the sync is defined for this row: does it name a file, and 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
@@ -359,11 +409,16 @@ function uniformRows(manifest) {
  * `desiredContent` would read. Judging the reference rather than the id is why a
  * new requirement row needs no change here.
  *
+ * The `path` is the other half, and it is not a formality: `R-NODE` names a
+ * reference and no path, because what it compares is `engines.node` — a FIELD of
+ * a file the service owns. There is no file to write from that reference, so a
+ * reference alone does not make a row renderable.
+ *
  * @param {object} row
  * @returns {boolean}
  */
 function isSyncRow(row) {
-  if (!row || !row.from) return false;
+  if (!row || !row.from || typeof row.path !== 'string') return false;
   return typeof row.from.path === 'string' || isPackageReference(row.from);
 }
 
@@ -461,9 +516,24 @@ function desiredContent({ row, current, serviceRoot, workspaceRoot }) {
 /**
  * One row's plan.
  *
+ * `block` is what this entry actually compared, and it is why a reader can
+ * trust the word `unchanged`. For a block row over a file that EXISTS, the
+ * desired text is the file's own with the markers spliced (`desiredContent`
+ * below), so the two sides can differ only inside them — everything else is
+ * this service's own and was never looked at. A line reporting that as a fact
+ * about the FILE is the false guarantee `.claude/rules/automation-gates.md` §5
+ * calls a defect, and it was measured: a `find` over node_modules with an
+ * `rm -rf` loop sat below `oa-deps-guard v1` in api_biz/hello for months while
+ * every run printed `unchanged init.sh` (d.42, hello `7d14d07`).
+ *
+ * It is absent where no splice happened — a whole-file row, and a block row
+ * whose file is not there, which is created entire. The name comes from the
+ * manifest row and from nowhere else, so this module still holds no list of
+ * blocks of its own.
+ *
  * @param {{row: object, serviceRoot: string, workspaceRoot: string}} args
  * @returns {{id: string, path: string, outcome: 'unchanged'|'change'|'not-run'|'blocked',
- *            current: string|null, desired?: string, detail?: string, reason?: string}}
+ *            current: string|null, block?: string, 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
@@ -477,6 +547,9 @@ function planRow({ row, serviceRoot, workspaceRoot }) {
 
   const current = readServiceFile(serviceRoot, row.path);
   const base = { id: row.id, path: row.path, current };
+  // The same predicate `desiredContent` decides the splice by, asked once here
+  // so the reported scope and the rendered scope cannot drift apart.
+  if (typeof row.block === 'string' && current !== null) base.block = row.block;
 
   // The same question the manifest run asks of the same row, answered by the
   // same predicate: does THIS row need the workspace? Since d.229 most of them

package/src/utils/bizCiGateContract.js

@@ -41,7 +41,7 @@ function assertBoolean(value, fieldName) {
 }
 
 // The service declares WHAT its database is; the library implements HOW it is
-// built (see docs/biz/00-model/uniformity-principle.md). Everything the six
+// built (see api/docs/biz/00-model/uniformity-principle.md). Everything the six
 // per-repo ci-setup-db.js scripts used to decide for themselves — client,
 // ordering, foreign-key handling — is a platform property and lives in the
 // library; only these four values legitimately differ per service.
@@ -51,7 +51,7 @@ const ENGINE_DECLARATION = /^(mariadb|mysql):[0-9][0-9.]*$/;
 /**
  * The collation a service declares its schema is created with — owner decision
  * 2026-09-14, `db-collation-declaration` 001, written into
- * `docs/biz/70-contracts/database-contract.md` §1.
+ * `api/docs/biz/70-contracts/database-contract.md` §1.
  *
  * Which utf8mb4 collation is the SERVICE's choice and this file sets none;
  * what it holds is that the value is one, because it is interpolated into

package/src/utils/connectorContract.js

@@ -38,6 +38,49 @@
  * services: an assumed wrapper.storage section for MinIO exists nowhere, and
  * guessing it would have failed emailer and pdfgen for a configuration neither
  * was ever meant to have.
+ *
+ * ## What `env` IS — and the three questions asked of it
+ *
+ * `env` is the set of environment names the connector's own library resolves
+ * WITHOUT a default: the names that decide whether the connector opens at all.
+ * It is measured against that library's runtime-config schema, never guessed:
+ *
+ *   db     — no shared library resolves a `DB_*` name; a service reaches its
+ *            schema itself, so `DB_HOST` is the endpoint of that reach
+ *   redis  — `@onlineapps/conn-base-cache/src/config.js` `REDIS_URL`. The
+ *            `REDIS_HOST`/`REDIS_PORT` of `conn-base-state` are NOT here: the
+ *            wrapper passes both explicitly, parsed out of `REDIS_URL`
+ *            (`ServiceWrapper.js` `stateConfig?.host || parsed.host`), so an
+ *            environment without them is no gap
+ *   mq     — `@onlineapps/mq-client-core/src/config.js` `RABBITMQ_URL`
+ *   minio  — `@onlineapps/conn-base-storage/src/config.js`, the five keys its
+ *            schema marks `required: true` with no default. `MINIO_ACTUAL_HOST`
+ *            is not among them: it is the OPTIONAL proxy-host override
+ *            (`config.js` `actualHost`, no `required`), so a row demanding it
+ *            would be this module inventing a requirement, and the services that
+ *            do route through a proxy declare it where they read it — the
+ *            `${MINIO_ACTUAL_HOST}` placeholder of `config/service/config.json`,
+ *            which is M1 coverage (`utils/envContract.js`)
+ *
+ * Three mechanisms read this set, and they ask three different questions of it —
+ * said out loud, because a list read three ways is where a silent drift starts:
+ *
+ *   1. `verifyConnectorContract` below, at boot: is at least ONE of them set —
+ *      evidence that the environment knows this connector at all. Deliberately
+ *      not "all of them": the check runs in phase 0.2 of every start, it is a
+ *      warning and not a stop, and the complete answer is question 3's;
+ *   2. `collectEnvCoverage` (`utils/envContract.js`), M2: these names are covered
+ *      by the connector declaration, so the `env` block of the integration
+ *      contract must not declare them a second time, and `--env-reads` lists them;
+ *   3. the uniform row `C-CI-CONNECTOR-ENV`
+ *      (`manifest/checks/serviceConnectors.js`): EVERY one of them is set in the
+ *      `variables:` of the job that runs the suite. That is the question the
+ *      other two never asked, and the gap it closes was measured on 2026-09-18 —
+ *      `MINIO_USE_SSL` missing from one CI job, failing three emailer tests on a
+ *      name no line of the service reads.
+ *
+ * The minio set grew from two names to these five on the owner's decision
+ * (`api/docs/governance/confirmations/biz-service-manifest.md` 013).
  */
 const CONNECTORS = {
   db: { configSections: [], env: ['DB_HOST'] },
@@ -47,7 +90,10 @@ const CONNECTORS = {
   // @onlineapps/conn-base-storage directly. Verified 2026-08-22 — no service on
   // the platform declares wrapper.storage. So it is declared by the contract and
   // evidenced only by the environment.
-  minio: { configSections: [], env: ['MINIO_ENDPOINT', 'MINIO_ACTUAL_HOST'] }
+  minio: {
+    configSections: [],
+    env: ['MINIO_ENDPOINT', 'MINIO_PORT', 'MINIO_USE_SSL', 'MINIO_ACCESS_KEY', 'MINIO_SECRET_KEY']
+  }
 };
 
 /** Where each of the two declarations lives, relative to the service root. */
@@ -165,9 +211,15 @@ function verifyConnectorContract({ config, requiredConnectors, env }) {
           + `       Fix: configure it, or set requiredConnectors.${name} to false if the service does not use it.`);
       }
 
+      // ONE of them, deliberately — question 1 of the three the header names.
+      // The message says which question it asked, so a reader does not take the
+      // silence of this step for the complete answer (`automation-gates.md` §5).
       const satisfied = spec.env.some((key) => env?.[key]);
       if (!satisfied) {
-        errors.push(`Connector "${name}" is required but ${spec.env.join(' / ')} is not set.\n`
+        const names = spec.env.length === 1
+          ? `${spec.env[0]} is not set`
+          : `none of ${spec.env.join(' / ')} is set`;
+        errors.push(`Connector "${name}" is required but ${names}.\n`
           + '       Fix: set it in the CI job or config/env-active/*.env — a required connector without its '
           + 'endpoint fails later, inside the connector, where the cause is harder to see.');
       }