@onlineapps/conn-orch-validator 10.0.0 → 12.0.0

package/src/manifest/checks/serviceRuntime.js

@@ -53,6 +53,9 @@ const SERVICE_MEMORY_PATH = 'deploy.resources.limits.memory';
 /** The profile that marks the test runner — its budget is F-RUNNER's row, not R-MEM's. */
 const TEST_PROFILE = 'test';
 
+/** How a compose service names the identity its container runs as. */
+const COMPOSE_USER_KEY = 'user';
+
 const readOrNull = (serviceRoot, relative) => {
   const target = path.join(serviceRoot, ...relative.split('/'));
   return fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
@@ -269,6 +272,125 @@ const composeCommand = Object.freeze({
   }
 });
 
+/**
+ * The instructions of ONE `FROM … AS <stage>` block, up to the next `FROM`.
+ *
+ * Comments are dropped, because the comment beside the identity names the very
+ * words this check reads and a comment is not an instruction.
+ *
+ * @param {string} dockerfile
+ * @param {string} stage the name after `AS`
+ * @returns {string[]|null} null when the file declares no such stage
+ */
+function stageInstructions(dockerfile, stage) {
+  const lines = dockerfile.split('\n').map((line) => line.trim());
+  const starts = lines
+    .map((line, index) => ({ line, index }))
+    .filter((entry) => /^FROM\s/i.test(entry.line));
+
+  const wanted = starts.find((entry) => new RegExp(`\\sAS\\s+${stage}\\s*$`, 'i').test(entry.line));
+  if (wanted === undefined) return null;
+
+  const after = starts.find((entry) => entry.index > wanted.index);
+  return lines
+    .slice(wanted.index, after === undefined ? lines.length : after.index)
+    .filter((line) => line !== '' && !line.startsWith('#'));
+}
+
+/**
+ * `R-USER` — WHICH USER the service process is.
+ *
+ * Measured 2026-09-17 on a production image built from the platform template:
+ * `docker run --rm <image> id` answered `uid=0(root) gid=0(root)`, while the dev
+ * container beside it ran as `1000:1000` because `docker-compose.yml` pins it.
+ * Nobody had decided that difference — the production stage declared no `USER`
+ * at all — and nothing in the uniform could say so, because `Dockerfile` is a
+ * file of the `own` class. This row is the SECOND platform fact carved out of
+ * that class, for the same reason as the first (`R-NODE`, the node major): what
+ * a service BUILDS is its own, what it RUNS AS is the platform's.
+ *
+ * Two facts, and they are the two nothing else holds:
+ *
+ *   * the `production` stage of the `Dockerfile` declares a non-root `USER` —
+ *     that is the stage CI builds (`docker build --target production`), and the
+ *     one the defect lived in;
+ *   * the SERVICE node of the dev compose pins the same identity numerically.
+ *
+ * The other two places it appears already have an owner, and a second rail over
+ * them would report one fact twice (`change-discipline.md` § One rail per
+ * concern): the runner's `user:` sits inside the block `F-RUNNER` holds byte for
+ * byte, and the production compose is `G-PROD`'s whole-file render.
+ *
+ * The two spellings are one identity, and the row carries both because no
+ * machine can resolve an account NAME to a uid without the image: `node` is uid
+ * 1000, gid 1000 in the node images this platform builds on (measured
+ * `docker run --rm node:24-alpine id node`), which is the `1000:1000` the compose
+ * files pin. Same shape as `R-MEM` and `R-PID1`, which carry their values for
+ * the same reason.
+ *
+ * @see api/docs/biz/00-model/service-shape.md
+ */
+const processIdentity = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'image_path', 'image_stage', 'service_user', 'service_uid']),
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const findings = [];
+    const identity = `the platform identity is ${JSON.stringify(row.service_user)} `
+      + '(uid 1000, gid 1000 in the node images this platform builds on)';
+    const imageWhere = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.image_path });
+
+    const dockerfile = readOrNull(serviceRoot, row.image_path);
+    if (dockerfile === null) {
+      findings.push({ where: imageWhere, what: 'absent — the image this service runs as is built from it' });
+    } else {
+      const stage = stageInstructions(dockerfile, row.image_stage);
+      if (stage === null) {
+        findings.push({
+          where: imageWhere,
+          what: `declares no stage "AS ${row.image_stage}" — that is the stage CI builds, so nothing here `
+            + 'says what the deployed container runs as'
+        });
+      } else {
+        // The LAST one wins, the way docker reads it: a stage may switch twice,
+        // and what the container runs as is whatever stood at the end.
+        const declared = stage.filter((line) => /^USER\s/i.test(line)).pop();
+        if (declared === undefined) {
+          findings.push({
+            where: imageWhere,
+            what: `the ${row.image_stage} stage declares no USER, so the container runs as root — ${identity}`
+          });
+        } else if (declared.replace(/^USER\s+/i, '').trim() !== row.service_user) {
+          findings.push({
+            where: imageWhere,
+            what: `the ${row.image_stage} stage runs as ${JSON.stringify(declared.replace(/^USER\s+/i, '').trim())} — ${identity}`
+          });
+        }
+      }
+    }
+
+    const composeWhere = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const compose = readOrNull(serviceRoot, row.path);
+    if (compose === null) {
+      findings.push({ where: composeWhere, what: 'absent — the service is run from it' });
+      return findings;
+    }
+
+    for (const [name, node] of runtimeServices(compose)) {
+      const declared = declarationOf(node, COMPOSE_USER_KEY).trim().replace(/^["']|["']$/g, '');
+      if (declared === row.service_uid) continue;
+      findings.push({
+        where: composeWhere,
+        what: declared === ''
+          ? `service ${name} declares no user — the platform identity is ${JSON.stringify(row.service_uid)}`
+          : `service ${name} runs as ${JSON.stringify(declared)} — the platform identity is ${JSON.stringify(row.service_uid)}`
+      });
+    }
+
+    return findings;
+  }
+});
+
 const composeNoPorts = Object.freeze({
   scope: 'service',
   requires: Object.freeze(['path']),
@@ -291,6 +413,7 @@ module.exports = {
     { name: 'node-major', check: nodeMajor },
     { name: 'memory-limit', check: memoryLimit },
     { name: 'compose-command', check: composeCommand },
+    { name: 'process-identity', check: processIdentity },
     { name: 'compose-no-ports', check: composeNoPorts }
   ],
   majorOf

package/src/manifest/discovery.js

@@ -21,7 +21,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const { resolveWorkspacePath } = require('./workspaceRoot');
+const { resolveWorkspacePath, apiCheckoutOf } = require('./workspaceRoot');
 
 /** Never walked: neither is part of any repository's declared shape. */
 const NEVER_WALKED = Object.freeze(['node_modules', '.git']);
@@ -211,11 +211,50 @@ function readReferencedFile({ from, workspaceRoot }) {
   try {
     return fs.readFileSync(file, 'utf8');
   } catch (cause) {
-    throw new Error(`[ManifestDiscovery] Referenced file not found - ${from.path} under ${workspaceRoot}. `
-      + 'Fix: run with --workspace pointing at the directory that holds api/ and api_biz/.', { cause });
+    throw new Error(describeMissingReference({ from, workspaceRoot, file }), { cause });
   }
 }
 
+/**
+ * Why a `from:` file could not be read, said as the two different things it can
+ * be — because the reader's next move is a different one in each case.
+ *
+ * The run was pointed at a workspace that carries no api checkout: the layout is
+ * the problem, and `--workspace` is the answer it has always been.
+ *
+ * The run REACHED the checkout and the file is not in it: the layout is right
+ * and the advice to pass `--workspace` is one nobody can carry out — a CI job
+ * passes that flag itself. Measured on BIZ-invoicing 2026-09-17: the job reached
+ * `api/`, and the clone made at the api ref that job measures against did not
+ * carry `api/config/shared-env.json`, because that ref predates the file. What
+ * moves is the checkout (locally) or the ref (in CI), so the message names both,
+ * and it names the ref by variable — the two of confirmation
+ * `biz-service-manifest` 012.
+ *
+ * It stays a hard failure in both cases: a missing SSOT in a workspace this run
+ * CAN read is a finding, never a NOT RUN (`automation-gates.md` §5).
+ *
+ * @param {{ from: {path: string}, workspaceRoot: string, file: string }} params
+ * @returns {string}
+ */
+function describeMissingReference({ from, workspaceRoot, file }) {
+  const apiRoot = apiCheckoutOf(workspaceRoot);
+  const insideApiCheckout = apiRoot !== null
+    && path.resolve(file).startsWith(apiRoot + path.sep);
+
+  if (!insideApiCheckout) {
+    return `[ManifestDiscovery] Referenced file not found - ${from.path} under ${workspaceRoot}. `
+      + 'Fix: run with --workspace pointing at the directory that holds api/ and api_biz/.';
+  }
+
+  return `[ManifestDiscovery] Referenced file not found - ${from.path} is missing from the api checkout `
+    + `${apiRoot}, which this run reached. The workspace is there and so is the checkout, so this is `
+    + 'not a --workspace problem: the checkout does not carry the file at the state it stands on. '
+    + `Fix: locally, update that checkout (git -C ${apiRoot} pull); in CI, move the api ref this job `
+    + 'measures against to a commit that carries the file - API_UNIFORM_REF_CONTINUOUS for the '
+    + 'validate-uniform job, API_UNIFORM_REF_DEPLOY for deploy-production.';
+}
+
 /**
  * The whole referenced file as one value: `{ path, text: true }`.
  *

package/src/manifest/gitCheckout.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * The one probe that answers "is this tree a git checkout" — and the one command
+ * that asks it.
+ *
+ * Two places need the answer and they must never disagree:
+ *
+ *   - the `git-tracked` row (`checks/gitTracked.js`), which asks what a clone
+ *     would receive and reports NOT RUN where git cannot say;
+ *   - step 7 of `ValidationOrchestrator`, which measures the whole uniform and,
+ *     outside a checkout, is NOT RUN for the same reason (owner decision
+ *     2026-09-17, confirmation `api/docs/governance/confirmations/biz-service-manifest.md`
+ *     011).
+ *
+ * A second copy of `git ls-files` would be a second rail for one concern
+ * (`.claude/rules/change-discipline.md` § One rail per concern) and, worse, two
+ * rails that can answer differently: one of them would eventually grow a
+ * `.git` existence check, which is not the same question — a worktree, a
+ * submodule and a `$GIT_DIR` elsewhere are checkouts without a `.git`
+ * DIRECTORY, and a directory called `.git` inside an exported tarball is not a
+ * checkout. What decides is whether git itself can answer.
+ *
+ * Nothing here guesses: a command git could not answer returns `null`, and the
+ * caller turns that into NOT RUN. What a negative answer MEANS is stated here
+ * once, in `NOT_A_CHECKOUT`; the remedy is the caller's own, because a row and a
+ * whole step do not fix the same way.
+ */
+
+const { execFileSync } = require('child_process');
+
+/**
+ * What a negative answer means — the half both callers state identically, so it
+ * cannot drift into two versions of one fact. Each of them appends its own
+ * remedy sentence after it.
+ */
+const NOT_A_CHECKOUT = 'this tree is not a git checkout (git ls-files could not answer), so what a clone '
+  + 'would receive cannot be read — a container and an exported tarball are in exactly this state.';
+
+/**
+ * Run one git command in the tree, or return null when git itself could not
+ * answer.
+ *
+ * @param {string} root the directory to run in
+ * @param {string[]} args the git arguments, without `-C <root>`
+ * @param {string} [input] stdin for commands that read it
+ * @returns {string|null} stdout, or null when git could not answer
+ */
+function gitCommand(root, args, input = undefined) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      input,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+  } catch (error) {
+    // check-ignore exits 1 when nothing matched, which is an ANSWER.
+    if (error.status === 1 && typeof error.stdout === 'string') return error.stdout;
+    return null;
+  }
+}
+
+/**
+ * What git tracks in this tree, NUL-separated exactly as `git ls-files -z`
+ * printed it — or null when this is not a checkout.
+ *
+ * @param {string} root
+ * @returns {string|null}
+ */
+function listTrackedFiles(root) {
+  return gitCommand(root, ['ls-files', '-z']);
+}
+
+/**
+ * Is this tree a git checkout?
+ *
+ * @param {string} root
+ * @returns {boolean}
+ */
+function isGitCheckout(root) {
+  return listTrackedFiles(root) !== null;
+}
+
+module.exports = { gitCommand, listTrackedFiles, isGitCheckout, NOT_A_CHECKOUT };

package/src/utils/dbAccountGrants.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * The one definition of a biz service's database account.
+ *
+ * Owner decision `db-accounts-per-service` 001: every service reaches its schema
+ * as ITSELF, with grants on its own schemas, and root stops being an operational
+ * identity. `db-migrations-first-deploy` 001 says what that is worth — "migrace
+ * nikdy pod rootem" (:32) — and, in the same breath, "žádný nový generátor SQL …
+ * žádná druhá kolej" (:33). So these statements exist ONCE: the production
+ * runbook (`api/docs/setup/INSTALL.md` § the account and its grants) and
+ * `biz-ci-gate setup-db-account` are two CALLERS of this function, not two
+ * copies of the same SQL.
+ *
+ * `createDatabaseSql` in `setupDatabase.js` stays where it is and is not
+ * re-exported here: creating the SCHEMA and creating the ACCOUNT are two
+ * concerns with two moments (the account exists before the schema in CI, and is
+ * created by the operator before the installer runs in production).
+ *
+ * ## The one difference between CI and production
+ *
+ * An integration suite builds THROWAWAY schemas beside the declared one —
+ * `src/utils/throwawaySchema.js`, used today as `oagen_emailer_fixture_<ms>_<pid>`
+ * (`api_biz/emailer/tests/integration/fixtureSchema.js`) and
+ * `oagen_meta_platformseedtest` (`api_biz/meta`). A grant on `oagen_emailer`
+ * alone refuses every one of them, which is why `ciThrowaway: true` adds a
+ * second grant over the service's own namespace.
+ *
+ * It does NOT widen the account's reach to another service: the pattern is
+ * anchored on this schema's name, and the `_` is ESCAPED. Unescaped, `_` is a
+ * single-character LIKE wildcard, so `oagen_meta_%` would also match
+ * `oagen_metadata` — a neighbouring service handed over whole. The backslash is
+ * what keeps the grant inside one service, and it is the difference
+ * `tests/unit/dbAccountGrants.test.js` measures.
+ *
+ * Production never gets that grant: it installs one schema, and a wildcard there
+ * would be a standing privilege nobody asked for.
+ *
+ * ## What is deliberately NOT here
+ *
+ * `GRANT SELECT ON information_schema.*` — the privilege
+ * `setupDatabase.assertTargetIsEmpty` names in its own error message. The server
+ * refuses to grant it at all (measured 2026-09-16, dev `gen_mariadb10.5`,
+ * MariaDB 10.5.17: `ERROR 1044 (42000): Access denied for user 'root'@'localhost'
+ * to database 'information_schema'`). Every account reads that catalogue
+ * already, filtered to the schemas it is granted — which is precisely the answer
+ * the emptiness probe needs.
+ *
+ * @see api/docs/governance/confirmations/db-accounts-per-service.md
+ * @see api/docs/governance/confirmations/db-migrations-first-deploy.md
+ * @see src/utils/setupDatabase.js
+ */
+
+/**
+ * The host part of every account. One value, because a second spelling is a
+ * second account: `'x'@'%'` and `'x'@'localhost'` are different rows in
+ * `mysql.user`, with different grants, and an installer that picked one while
+ * the gate created the other would report an account the service cannot use.
+ */
+const ACCOUNT_HOST = '%';
+
+/**
+ * Identifiers and passwords reach the server as TEXT, so they are checked rather
+ * than escaped: an identifier in this platform is `oagen_<shortname>`, and
+ * anything carrying a quote, a backslash or a backtick is not one.
+ *
+ * Refusing is the whole of the answer (`architecture-principles.md` §3): a value
+ * that needs escaping here came from somewhere it should not have.
+ */
+const FORBIDDEN_IN_VALUE = /['"`\\;\n\r]/;
+
+function requireValue(value, name, fix) {
+  if (typeof value !== 'string' || value === '') {
+    throw new Error(`[DbAccountGrants] Missing ${name} - Expected a non-empty value.\n`
+      + `       Fix: ${fix}`);
+  }
+  if (FORBIDDEN_IN_VALUE.test(value)) {
+    throw new Error(`[DbAccountGrants] ${name} carries a character these statements cannot contain: `
+      + `${JSON.stringify(value)}.\n`
+      + '       The statements are text handed to the SQL client, so a quote, backslash, backtick, '
+      + 'semicolon or newline would end one statement and start another.\n'
+      + `       Fix: ${fix}`);
+  }
+  return value;
+}
+
+/**
+ * Every statement that creates this service's account and grants it what it
+ * needs, in the order they must run.
+ *
+ * @param {object} options
+ * @param {string} options.schema the schema the service declares
+ *   (`database.schema` of `config/service/integration-contract.json`)
+ * @param {string} options.account the account the service declares
+ *   (`DB_USER` of `config/env-templates/<service>.env`)
+ * @param {string} options.password the password the account is created with
+ * @param {boolean} [options.ciThrowaway] also grant the throwaway namespace
+ *   `<schema>\_%`, which only an integration tier builds into
+ * @returns {string[]} the statements, in order
+ */
+function databaseAccountSql({ schema, account, password, ciThrowaway = false } = {}) {
+  requireValue(schema, 'schema', 'pass database.schema from config/service/integration-contract.json.');
+  requireValue(account, 'account', 'pass DB_USER from this service\'s config/env-templates/<service>.env.');
+  requireValue(password, 'password', 'pass the password the account is created with; an account created '
+    + 'with an empty password is one anybody on the network can use.');
+
+  const identity = `'${account}'@'${ACCOUNT_HOST}'`;
+
+  const statements = [
+    `CREATE USER IF NOT EXISTS ${identity} IDENTIFIED BY '${password}';`,
+    `GRANT ALL PRIVILEGES ON \`${schema}\`.* TO ${identity};`
+  ];
+
+  if (ciThrowaway === true) {
+    // The backslash escapes `_` so the pattern stays inside this service; see
+    // the head of this file for the neighbour it would otherwise reach.
+    statements.push(`GRANT ALL PRIVILEGES ON \`${schema}\\_%\`.* TO ${identity};`);
+  }
+
+  // Last, always: a grant is not live for a connection opened before it.
+  statements.push('FLUSH PRIVILEGES;');
+
+  return statements;
+}
+
+module.exports = { databaseAccountSql, ACCOUNT_HOST };

package/src/utils/deployContract.js

@@ -8,7 +8,8 @@
  * R8 permits and their reasons: api/docs/standards/tenant-allocation.md § Enforcement
  *
  *   R1  the production compose pins its image immutably
- *   R2  the deploy resets to origin/production rather than merging
+ *   R2  the deploy never merges: it resets to the commit the pipeline measured,
+ *       after verifying that commit is an ancestor of origin/production
  *   R3  CI Node major == Dockerfile Node major == engines.node major
  *   R4  no published ports — the only public entrypoint is doorman
  *   R5  images tagged with the full commit SHA, never the short one
@@ -138,15 +139,124 @@ function checkPublishedPorts(compose, add) {
   }
 }
 
+// ── R2 — the deploy sequence ────────────────────────────────────────────────
+//
+// The rule, stated once and in full: a deploy on the box NEVER merges; it forces
+// the checkout to the commit THIS PIPELINE MEASURED, and before it does, it
+// verifies that commit is an ancestor of origin/production.
+//
+// Both halves are load-bearing, and each answers a different way a box ends up
+// running something nobody measured:
+//
+//   the measured commit — the runner read config/service/integration-contract.json
+//   at $CI_COMMIT_SHA and derived the migration directory and the seed list from
+//   it THERE. Resetting to origin/production instead lands the box on whatever
+//   the branch points at by the time the ssh step opens, so a push that arrives
+//   while the job runs leaves it applying a declaration no run ever measured.
+//
+//   the ancestor check — a commit that is not on the branch this box follows is
+//   a pipeline for a different history, and resetting to it puts the box on code
+//   production never took. Fail-fast, before anything is touched.
+//
+// Until 2026-09-17 this function demanded the literal `git reset --hard
+// origin/production`, which is the FIRST half's opposite. The packaged template
+// had carried the two-step form since d.589b, so a repository that synced the
+// block failed the gate byte-for-byte conformant — measured in pdfgen and
+// hello-service, both of which run `ci:gate:contract` as the first before_script
+// step of `test` and would therefore have failed before their first test. A rule
+// that states yesterday's TEXT rather than the requirement is exactly what
+// `.claude/rules/doc-code-binding.md` §1 calls a descriptive fact written by
+// hand; `tests/unit/deployContractTemplate.test.js` is what now re-derives it,
+// by running this gate over the template this package ships.
+//
+// There is no transition tolerance for the old form, and there must not be
+// (`architecture-principles.md` §11): the six repositories still carrying it get
+// a message naming today's form and the one command that writes it.
+
+/** The branch a production box follows — the only ref an ancestor check may name. */
+const PRODUCTION_BRANCH = 'origin/production';
+
+/** `git reset --hard <ref>`, tolerant of the spacing a shell allows. */
+const RESET_HARD = /(?:^|[^\w-])git\s+reset\s+--hard\s+(\S+)/g;
+
+/** `git merge-base --is-ancestor <commit> <ref>` — the guard, same tolerance. */
+const ANCESTOR_CHECK = /(?:^|[^\w-])git\s+merge-base\s+--is-ancestor\s+(\S+)\s+(\S+)/g;
+
+/** `git merge …`. `git merge-base` is a different command, so it must not match. */
+const GIT_MERGE = /(?:^|[^\w-])git\s+merge(?![-\w])/;
+
+/** `git pull …` */
+const GIT_PULL = /(?:^|[^\w-])git\s+pull(?:[^\w-]|$)/m;
+
+/** The block this package ships, named in every fix so nobody has to retype it. */
+const DEPLOY_SEQUENCE_FIX =
+  '       Fix: npx oa-sync-template .gitlab-ci.yml --target . — the packaged block `oa-ci v1`\n'
+  + '       carries the sequence: git fetch origin production, then\n'
+  + '       `if ! git merge-base --is-ancestor "$COMMIT_SHA" origin/production; then exit 1; fi`,\n'
+  + '       then `git reset --hard "$COMMIT_SHA"`.';
+
+/**
+ * One shell word as this rule reads it: the separators a shell puts after an
+ * argument (`; then`, `&& …`) dropped, then the quotes.
+ *
+ * Tolerant, deliberately not lenient: what it normalises away is punctuation
+ * that cannot change which commit the command names.
+ */
+function shellWord(raw) {
+  return unquote(raw.replace(/[;&|)]+$/, ''));
+}
+
 function checkDeploySequence(ci, add) {
-  if (/(^|[^\w-])git\s+pull([^\w-]|$)/m.test(ci)) {
+  if (GIT_PULL.test(ci)) {
     add('R2', "'git pull' in the deploy path.\n"
       + '       A local modification on the server turns the merge into a conflict and aborts the deploy halfway.\n'
-      + '       Fix: git fetch origin production && git reset --hard origin/production');
+      + DEPLOY_SEQUENCE_FIX);
   }
-  if (!/git\s+reset\s+--hard\s+origin\/production/.test(ci)) {
-    add('R2', "No 'git reset --hard origin/production' found in .gitlab-ci.yml.\n"
-      + '       Fix: the deploy must force the working tree to the pushed commit, matching the infra contract.');
+  if (GIT_MERGE.test(ci)) {
+    add('R2', "'git merge' in the deploy path.\n"
+      + '       A deploy that merges builds a commit that exists on no branch, so what the box runs\n'
+      + '       is no longer any commit a pipeline measured.\n'
+      + DEPLOY_SEQUENCE_FIX);
+  }
+
+  const resets = [...ci.matchAll(RESET_HARD)]
+    .map((match) => ({ at: match.index, target: shellWord(match[1]) }));
+
+  if (resets.length === 0) {
+    add('R2', "No 'git reset --hard' found in .gitlab-ci.yml.\n"
+      + '       The deploy has to force the working tree to the commit this pipeline measured;\n'
+      + '       nothing here does.\n'
+      + DEPLOY_SEQUENCE_FIX);
+    return;
+  }
+
+  // Ordering is read over the whole file rather than per job: which YAML key a
+  // line sits under is the service's own half of the pipeline, and a gate that
+  // parsed jobs would be judging that half too. What it does measure is the
+  // thing that can go wrong — a guard that names another commit, another branch,
+  // or runs after the reset it is supposed to protect.
+  const guards = [...ci.matchAll(ANCESTOR_CHECK)]
+    .map((match) => ({ at: match.index, commit: shellWord(match[1]), branch: shellWord(match[2]) }))
+    .filter((guard) => guard.branch === PRODUCTION_BRANCH);
+
+  for (const reset of resets) {
+    if (reset.target === PRODUCTION_BRANCH) {
+      add('R2', `The deploy resets to ${PRODUCTION_BRANCH}, not to the commit this pipeline measured.\n`
+        + '       origin/production is whatever the branch points at by the time the ssh step opens:\n'
+        + '       a push landing while this job runs leaves the box applying a declaration no run\n'
+        + '       ever measured, because the migration set was derived at the pipeline commit.\n'
+        + DEPLOY_SEQUENCE_FIX);
+      continue;
+    }
+    if (!guards.some((guard) => guard.at < reset.at && guard.commit === reset.target)) {
+      add('R2', `The deploy resets to ${reset.target}, which is not verified to be an ancestor of `
+        + `${PRODUCTION_BRANCH} first.\n`
+        + '       A commit that is not on the branch this box follows belongs to a different history,\n'
+        + '       and resetting to it puts the box on code production never took.\n'
+        + `       Expected: git merge-base --is-ancestor ${reset.target} ${PRODUCTION_BRANCH}, on a line\n`
+        + '       BEFORE the reset, naming that same commit.\n'
+        + DEPLOY_SEQUENCE_FIX);
+    }
   }
 }
 

package/src/utils/envContract.js

@@ -378,17 +378,26 @@ function assertScannableServiceRoot(serviceRoot) {
 }
 
 /**
- * COMPLETENESS: every environment name the repository visibly reads is either
- * declared in the env block or covered by M1/M2.
+ * The names this service's environment is ALLOWED to be judged by: everything
+ * the declaration names, plus everything M1/M2 already cover.
+ *
+ * It is the set `verifyEnvCompleteness` measures the repository against, lifted
+ * out of it so a second caller cannot grow a second definition of it (d.533c;
+ * `change-discipline.md` § One rail per concern). The completeness check below
+ * asks the same question from the other side — which read is NOT in this set —
+ * and `oa-validate --env-reads` prints the set itself, for the deploy gate that
+ * must not demand a value for a name this service never reads.
+ *
+ * Sorted with the default comparator rather than `localeCompare`: the order is
+ * read by a machine, and a collation that depends on the host's locale data is
+ * the ambient state `automation-gates.md` §1.1 forbids.
  *
  * @param {object} args
  * @param {string} args.serviceRoot
  * @param {object} args.contract normalized integration contract
- * @returns {{ok: boolean, violations: Array<{name: string, sources: string[]}>, declaredCount: number,
- *            coveredCount: number, readCount: number, filesScanned: number,
- *            dynamicSites: Array<{file: string, line: number}>}}
+ * @returns {{names: string[], coverage: Map<string,string>, declared: Set<string>}}
  */
-function verifyEnvCompleteness({ serviceRoot, contract }) {
+function collectDeclaredEnvNames({ serviceRoot, contract }) {
   assertScannableServiceRoot(serviceRoot);
   assertNormalizedContract(contract);
 
@@ -409,6 +418,26 @@ function verifyEnvCompleteness({ serviceRoot, contract }) {
     for (const item of declaration?.[listKey] ?? []) declared.add(item.name);
   }
 
+  const names = new Set(coverage.keys());
+  for (const name of declared) names.add(name);
+
+  return { names: [...names].sort(), coverage, declared };
+}
+
+/**
+ * COMPLETENESS: every environment name the repository visibly reads is either
+ * declared in the env block or covered by M1/M2.
+ *
+ * @param {object} args
+ * @param {string} args.serviceRoot
+ * @param {object} args.contract normalized integration contract
+ * @returns {{ok: boolean, violations: Array<{name: string, sources: string[]}>, declaredCount: number,
+ *            coveredCount: number, readCount: number, filesScanned: number,
+ *            dynamicSites: Array<{file: string, line: number}>}}
+ */
+function verifyEnvCompleteness({ serviceRoot, contract }) {
+  const { coverage, declared } = collectDeclaredEnvNames({ serviceRoot, contract });
+
   const { reads, dynamicSites, filesScanned } = collectEnvReads({ serviceRoot });
 
   const violations = [];
@@ -467,6 +496,7 @@ module.exports = {
   ENV_SCAN_BLIND_SPOTS,
   normalizeEnvDeclaration,
   collectEnvCoverage,
+  collectDeclaredEnvNames,
   collectEnvReads,
   verifyEnvCompleteness,
   verifyEnvPresence