@onlineapps/conn-orch-validator 10.0.0 → 11.0.0

package/src/cli/biz-ci-gate.js

@@ -35,7 +35,9 @@ const {
 const { runPreValidation } = require('../utils/preValidation');
 const { describeRecordIdentity } = require('../utils/stepFailure');
 const { checkLibCompat, loadLibrarySet } = require('../utils/libCompat');
-const { buildSchema } = require('../utils/setupDatabase');
+const { buildSchema, defaultExec } = require('../utils/setupDatabase');
+const { databaseAccountSql, ACCOUNT_HOST } = require('../utils/dbAccountGrants');
+const { readDeclaredAccount, ACCOUNT_KEY, ENV_TEMPLATE_DIR } = require('../manifest/checks/serviceDb');
 
 function parseArgs(argv) {
   const parsed = {
@@ -101,6 +103,10 @@ Commands:
                              skipped; this reads the runner's own JSON report.
   emit-ci-env                Emit connector-aware CI environment exports.
   wait-connectors            Wait for required connector TCP endpoints.
+  setup-db-account           Create this service's database account and grant it its own schemas.
+                             The ONE step of a biz pipeline that runs under the database root
+                             account, and the last one that does: every step after it connects
+                             as the service, the way production does.
   setup-db                   Build the schema from the declared migrations (contract database block).
   run-setup                  Run optional connector setup commands from contract.
   write-summary              Write normalized integration signal artifact JSON.
@@ -131,6 +137,18 @@ wait-connectors options:
   --attempts <number>             Maximum connection attempts per connector (default: 60)
   --interval-ms <number>          Delay between attempts in milliseconds (default: 1000)
 
+setup-db-account environment:
+  DB_HOST, DB_PORT                The database this job stands up.
+  CI_DB_ROOT_USER                 The administrative account of that database — the sidecar's
+  CI_DB_ROOT_PASSWORD             root, under its OWN name. It is never taken from DB_USER:
+                                  DB_USER is who the job connects AS, and the two being one
+                                  value is the thing this command exists to end.
+  DB_USER                         The account every later step connects as. It must be the one
+                                  the repository declares in ${ENV_TEMPLATE_DIR}/<service>.env.
+  DB_PASSWORD                     The password that account is CREATED with and connects with.
+                                  A throwaway value of the job; the env template declares the
+                                  key, never the secret.
+
 write-summary options:
   --output <path>                 Summary artifact path. Default: <service-root>/ci/integration-signal.json
   --gate-verdict <pass|fail>      Report a failure this summary cannot see for itself -
@@ -258,6 +276,146 @@ function reportInstallContract(result) {
   return false;
 }
 
+/**
+ * Fail with the one shape `architecture-principles.md` §5 asks for, and the
+ * prefix every other step of this gate prints.
+ *
+ * @param {string} subject what was checked
+ * @param {string} problem what was found and what was expected
+ * @param {string} fix the command or edit that satisfies it
+ */
+function failSetupDbAccount(subject, problem, fix) {
+  process.stderr.write(`[BizCiGate] FAIL setup-db-account — ${subject} — ${problem}\n`
+    + `       Fix: ${fix}\n`);
+  process.exit(1);
+}
+
+/**
+ * Create this service's database account, and grant it its own schemas.
+ *
+ * This is the ONE step of a biz pipeline that runs under the database root
+ * account, and the last one that does. Everything after it — `setup-db`, the
+ * integration tier, the cookbooks — connects as the service, which is what makes
+ * CI prove the migration set under the rights production actually has
+ * (`db-migrations-first-deploy` 001: "migrace nikdy pod rootem"). Until d.567
+ * seven pipelines set `DB_USER: "root"` and proved it under rights no production
+ * box grants.
+ *
+ * Three facts, three owners, none of them invented here:
+ *   - the SCHEMA is `database.schema` of the integration contract, the same
+ *     value `setup-db` builds;
+ *   - the ACCOUNT is `DB_USER` of the repository's own env template — the
+ *     declaration uniform row `D-DB-ACCOUNT` measures, read through the one
+ *     function that knows where it lives;
+ *   - the STATEMENTS are `utils/dbAccountGrants.js`, the same definition the
+ *     production runbook installs from.
+ *
+ * The password is the job's own throwaway value (`DB_PASSWORD`), never the
+ * `CHANGE_ME` placeholder an env template carries: a template declares the key,
+ * not the secret.
+ */
+function runSetupDbAccount(options) {
+  const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
+  const database = contractInfo.contract.database;
+
+  if (!database) {
+    // NOT APPLICABLE, not OK — the same distinction `setup-db` draws one
+    // function down, and for the same reason: a step that prints OK for work it
+    // never did is the false guarantee `automation-gates.md` §5 names.
+    process.stdout.write(`[BizCiGate] NOT APPLICABLE setup-db-account — ${contractInfo.contractPath} declares no `
+      + '"database" block, so this service has no schema and needs no account. Nothing was done, and nothing '
+      + 'was expected to be.\n');
+    return;
+  }
+
+  const serviceRoot = contractInfo.serviceRoot;
+  const { relative, declared } = readDeclaredAccount(serviceRoot);
+
+  if (relative === null || declared === null) {
+    failSetupDbAccount(ACCOUNT_KEY,
+      `this repository declares a database, and ${relative === null
+        ? `no env template of its own under ${ENV_TEMPLATE_DIR}/ declares ${ACCOUNT_KEY}`
+        : `${relative} declares no ${ACCOUNT_KEY}`} — the account is not this command's to invent`,
+      `declare ${ACCOUNT_KEY}=oagen_<service> in ${relative === null ? `${ENV_TEMPLATE_DIR}/<service>.env` : relative}`
+      + '; uniform row D-DB-ACCOUNT measures the same key.');
+  }
+
+  const connecting = process.env.DB_USER;
+  if (connecting !== declared) {
+    failSetupDbAccount('DB_USER',
+      `this job connects as ${JSON.stringify(connecting ?? null)} and the repository declares `
+      + `${JSON.stringify(declared)} in ${relative} — creating one account and using another would report `
+      + 'a success nothing consumes, and fail two steps later as an access denial',
+      `set DB_USER: "${declared}" in the job's variables, the value ${relative} declares.`);
+  }
+
+  const required = {
+    DB_HOST: process.env.DB_HOST,
+    CI_DB_ROOT_USER: process.env.CI_DB_ROOT_USER,
+    CI_DB_ROOT_PASSWORD: process.env.CI_DB_ROOT_PASSWORD,
+    DB_PASSWORD: process.env.DB_PASSWORD
+  };
+  const fixes = {
+    DB_HOST: 'set it in the job variables to the alias of the database service container.',
+    CI_DB_ROOT_USER: 'set it in the job variables to the administrative account of the database '
+      + 'sidecar (root). It is named separately from DB_USER on purpose: DB_USER is who the job '
+      + 'connects as afterwards.',
+    CI_DB_ROOT_PASSWORD: 'set it in the job variables to the sidecar\'s MARIADB_ROOT_PASSWORD. '
+      + 'The sidecar is thrown away with the job, so the value is a throwaway of the job too.',
+    DB_PASSWORD: 'set it in the job variables to a throwaway password; the account is CREATED with '
+      + 'it here and connects with it in every later step. The env template declares the key, never '
+      + 'the secret.'
+  };
+
+  for (const [name, value] of Object.entries(required)) {
+    if (value === undefined || value === '') {
+      failSetupDbAccount(name, 'not set, and this step cannot run without it', fixes[name]);
+    }
+  }
+
+  const connection = {
+    host: required.DB_HOST,
+    port: Number.parseInt(process.env.DB_PORT || '3306', 10),
+    user: required.CI_DB_ROOT_USER,
+    password: required.CI_DB_ROOT_PASSWORD,
+    requireTls: process.env.DB_REQUIRE_TLS === '1'
+  };
+
+  // Said before any statement runs, pass or fail — the way `verify-env-contract`
+  // prints its scope. A step that names nothing until it succeeds leaves the
+  // reader of a failed job log with a refused statement and no idea which
+  // account it was for.
+  process.stdout.write(`[BizCiGate] setup-db-account scope: '${declared}'@'${ACCOUNT_HOST}' on `
+    + `${connection.host}:${connection.port}, schema \`${database.schema}\` — the account declared in `
+    + `${relative}, created by ${JSON.stringify(connection.user)}\n`);
+
+  const statements = databaseAccountSql({
+    schema: database.schema,
+    account: declared,
+    password: required.DB_PASSWORD,
+    // The integration tier builds throwaway schemas beside the declared one
+    // (`utils/throwawaySchema.js`); production installs exactly one and gets no
+    // such grant. The difference is named here, at its one caller.
+    ciThrowaway: true
+  });
+
+  statements.forEach((sql, index) => {
+    const result = defaultExec({ connection, sql });
+    if (result.status !== 0) {
+      // The statement is identified by its ORDINAL, never quoted: the first one
+      // carries the account's password.
+      failSetupDbAccount(`statement ${index + 1} of ${statements.length}`,
+        `the database at ${connection.host}:${connection.port} refused it:\n       ${result.stderr}`,
+        `check that ${JSON.stringify(connection.user)} is the administrative account of that database, `
+        + 'and that a mariadb/mysql client is on PATH in this job image.');
+    }
+  });
+
+  process.stdout.write(`[BizCiGate] OK setup-db-account — '${declared}'@'${ACCOUNT_HOST}': `
+    + `${statements.length} statement(s), granted \`${database.schema}\` and its throwaway namespace `
+    + `\`${database.schema}_*\`. Every step after this one connects as that account.\n`);
+}
+
 /**
  * Build the schema the contract declares. One implementation for every service:
  * the repo declares WHAT, this decides HOW (docs/biz/00-model/uniformity-principle.md).
@@ -703,6 +861,10 @@ async function main() {
       await runWaitConnectors(options);
       return;
     }
+    if (command === 'setup-db-account') {
+      runSetupDbAccount(options);
+      return;
+    }
     if (command === 'setup-db') {
       runSetupDb(options);
       return;

package/src/cli/oa-validate.js

@@ -42,6 +42,7 @@ const { discoverBearers } = require('../manifest/discovery');
 const { collectRows } = require('../manifest/walk');
 const { CHECK_REGISTRY } = require('../manifest/checks');
 const { declaredCategory, readPackage } = require('../manifest/checks/libraryContext');
+const { listEnvReads } = require('../utils/envReads');
 
 /** Exit code for a run that could not start at all — distinct from a finding. */
 const USAGE_EXIT = 2;
@@ -84,6 +85,7 @@ Usage:
   oa-validate --workspace <root> [--json]
   oa-validate --library <packageDir> [--workspace <root>] [--json]
   oa-validate --library --all [--workspace <root>] [--json]
+  oa-validate --env-reads [<serviceRoot>]
 
   Checks a repository against the uniform manifest shipped in
   @onlineapps/conn-orch-validator. The manifest version IS this package's
@@ -120,6 +122,15 @@ Options:
                            → the rows that need it are reported NOT RUN, never as
                            passing.
   --json                   Print the run as JSON instead of the table.
+  --env-reads              Print the environment names this service reads — one per
+                           line, sorted, nothing else — and exit 0. No table, no
+                           banner, no verdict file: the output is read by a deploy
+                           gate (mapfile), so it combines with no other mode. The set
+                           is the one row C-ENV-READS measures against: the contract's
+                           env block, the \${VAR} placeholders of config/service/*.json,
+                           and the endpoint variables of the required connectors. A
+                           name only the source reads is NOT here — that is a blocking
+                           finding of C-ENV-READS with its own fix.
   --help                   Print this and exit 0.
 
 Output:
@@ -136,7 +147,9 @@ Exit codes:
 `;
 
 function parseArgs(argv) {
-  const parsed = { serviceRoot: null, workspace: null, json: false, help: false, library: false, all: false };
+  const parsed = {
+    serviceRoot: null, workspace: null, json: false, help: false, library: false, all: false, envReads: false
+  };
   const args = [...argv];
 
   while (args.length > 0) {
@@ -149,6 +162,8 @@ function parseArgs(argv) {
       parsed.library = true;
     } else if (token === '--all') {
       parsed.all = true;
+    } else if (token === '--env-reads') {
+      parsed.envReads = true;
     } else if (token === '--workspace') {
       const value = args.shift();
       if (!value || value.startsWith('--')) {
@@ -166,6 +181,27 @@ function parseArgs(argv) {
     }
   }
 
+  // Not a verdict and not combinable with one: the gate reads stdout as a list
+  // of names, so a table, a JSON document or a NOT RUN banner printed beside
+  // them would reach it as environment variables. The option that WOULD be
+  // harmless — `--workspace` — is refused with the rest, because this answer
+  // comes from the service's own contract and a workspace root would suggest it
+  // does not (`automation-gates.md` §1 requirement 1).
+  if (parsed.envReads && !parsed.help) {
+    const combined = [
+      parsed.json ? '--json' : null,
+      parsed.library ? '--library' : null,
+      parsed.all ? '--all' : null,
+      parsed.workspace !== null ? '--workspace' : null
+    ].filter((token) => token !== null);
+
+    if (combined.length > 0) {
+      throw new Error(`[oa-validate] --env-reads cannot be combined with ${combined.join(', ')} - it prints `
+        + 'environment names for a machine to read, and every other mode prints a verdict into the same '
+        + 'stdout. Fix: run oa-validate --env-reads [<serviceRoot>] on its own.');
+    }
+  }
+
   if (parsed.all && !parsed.library) {
     throw new Error('[oa-validate] Option --all needs --library - a service is checked one repository at a time. '
       + 'Fix: oa-validate --library --all');
@@ -403,6 +439,29 @@ function runLibrary(options) {
   return blockingOf(report).length > 0 ? 1 : 0;
 }
 
+/**
+ * `--env-reads`: the question a deploy gate asks before it judges a `.env`.
+ *
+ * Nothing but the names reaches stdout, and nothing is written to the tree: the
+ * caller is `mapfile -t reads < <(oa-validate --env-reads "$repo")` in
+ * `api/scripts/validate-env.sh`, which took `KEY=CHANGE_ME` in a key the biz
+ * image never opens for a reason to refuse a deploy. The set, and why it is not
+ * a grep for `process.env`, belong to `utils/envReads.js`.
+ *
+ * An empty answer is an answer, and it exits 0: a contract that declares no env
+ * block, uses no placeholder and requires no connector reads nothing this
+ * package can see. Whether that is true of the repository is row `C-ENV-READS`'s
+ * question, not this one's.
+ *
+ * @param {object} options parsed arguments
+ * @returns {number} exit code
+ */
+function runEnvReads(options) {
+  const names = listEnvReads(options.serviceRoot === null ? process.cwd() : options.serviceRoot);
+  if (names.length > 0) process.stdout.write(`${names.join('\n')}\n`);
+  return 0;
+}
+
 function main(argv) {
   const options = parseArgs(argv);
 
@@ -411,6 +470,8 @@ function main(argv) {
     return 0;
   }
 
+  if (options.envReads) return runEnvReads(options);
+
   if (options.library) return runLibrary(options);
 
   const manifest = loadManifest(DEFAULT_MANIFEST_PATH);
@@ -471,6 +532,7 @@ if (require.main === module) {
 module.exports = {
   main,
   parseArgs,
+  runEnvReads,
   runLibrary,
   checkOnePackage,
   checkEveryPackage,

package/src/manifest/checks/gitTracked.js

@@ -45,7 +45,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execFileSync } = require('child_process');
+const { gitCommand, listTrackedFiles, NOT_A_CHECKOUT } = require('../gitCheckout');
 
 /** Never walked: neither is part of a repository's declared shape. */
 const NEVER_WALKED = Object.freeze(['node_modules', '.git']);
@@ -53,29 +53,6 @@ const NEVER_WALKED = Object.freeze(['node_modules', '.git']);
 /** The file classes whose rows REQUIRE a path to be there. */
 const REQUIRING_CLASSES = Object.freeze(['identical', 'contains', 'generated']);
 
-/**
- * Run one git command in the repository, or return null when git itself could
- * not answer. Nothing here guesses: the caller turns a null into NOT RUN.
- *
- * @param {string} serviceRoot
- * @param {string[]} args
- * @param {string} [input]
- * @returns {string|null}
- */
-function git(serviceRoot, args, input = undefined) {
-  try {
-    return execFileSync('git', ['-C', serviceRoot, ...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;
-  }
-}
-
 /**
  * Does the path exist under EXACTLY this spelling?
  *
@@ -161,7 +138,7 @@ const check = Object.freeze({
    * @returns {{findings: Array<{where: string, what: string}>, notRun: string|null}}
    */
   run({ block, serviceRoot }) {
-    const listed = git(serviceRoot, ['ls-files', '-z']);
+    const listed = listTrackedFiles(serviceRoot);
     if (listed === null) {
       return {
         findings: [],
@@ -174,10 +151,8 @@ const check = Object.freeze({
         // (`.claude/rules/change-discipline.md` § One rail per concern).
         // Until d.518 it stopped at the absence, which is the dead end
         // `.claude/rules/automation-gates.md` §1 requirement 4 forbids.
-        notRun: '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. '
-          + 'Fix: run this row over a git checkout — a clone of the repository, never an export, a tarball '
-          + 'or a built image.'
+        notRun: `${NOT_A_CHECKOUT} Fix: run this row over a git checkout — a clone of the repository, `
+          + 'never an export, a tarball or a built image.'
       };
     }
 
@@ -191,7 +166,7 @@ const check = Object.freeze({
 
     // Only now, and only for those: which of them a .gitignore rule covers is
     // what turns the finding into an edit the reader can make.
-    const answered = git(serviceRoot, ['check-ignore', '--stdin', '-z'], missing.map(({ file }) => file).join('\0'));
+    const answered = gitCommand(serviceRoot, ['check-ignore', '--stdin', '-z'], missing.map(({ file }) => file).join('\0'));
     const ignored = new Set((answered === null ? '' : answered).split('\0').filter((entry) => entry.length > 0));
 
     return {

package/src/manifest/checks/serviceDb.js

@@ -37,6 +37,7 @@ const path = require('path');
 
 const { readIdentity, IDENTITY_FILE } = require('../serviceIdentity');
 const { DATABASE_PREFIX } = require('./serviceIdentityRows');
+const { blockLines } = require('./serviceFiles');
 
 /** Where the fact lives, and the key that carries it. */
 const CONTRACT_PATH = 'config/service/integration-contract.json';
@@ -200,6 +201,39 @@ function ownEnvTemplate(serviceRoot, shortName) {
   return { relative: only, text: fs.readFileSync(path.join(serviceRoot, ...only.split('/')), 'utf8') };
 }
 
+/**
+ * WHICH account this repository declares, and where it said so.
+ *
+ * Exported because `D-DB-ACCOUNT` is not the only reader: `biz-ci-gate
+ * setup-db-account` CREATES that account in CI, and it must create the one the
+ * repository declares rather than one derived a second way. Which file carries
+ * the fact and under which key is therefore said ONCE
+ * (`change-discipline.md` § One rail per concern); the row below and the CLI
+ * command each phrase their own finding from the same reading.
+ *
+ * It is deliberately NOT the derived `oagen_<shortname>` — that is the row's
+ * comparison, and a caller that wanted the derivation instead of the
+ * declaration would be reading past the repository. Measured reason: the meta
+ * runbook names `oagen_meta_app` where the repository declares `oagen_meta`
+ * (`api/docs/setup/INSTALL.md`, open finding with an INFRA owner), so the two
+ * answers are not interchangeable today.
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {{shortName: string|null, relative: string|null, declared: string|null}}
+ *   `shortName` null when the repository does not say who it is (`C-SERVICE`'s
+ *   finding), `relative` null when it owns no env template, `declared` null when
+ *   that template carries no such key
+ */
+function readDeclaredAccount(serviceRoot, key = ACCOUNT_KEY) {
+  const shortName = shortNameOf(serviceRoot);
+  if (shortName === null) return { shortName: null, relative: null, declared: null };
+
+  const template = ownEnvTemplate(serviceRoot, shortName);
+  if (template === null) return { shortName, relative: null, declared: null };
+
+  return { shortName, relative: template.relative, declared: declaredValue(template.text, key) };
+}
+
 /**
  * The three rows below ask their question only of a repository that DECLARES a
  * database, and say nothing about a declaration they could not read — that one
@@ -293,12 +327,11 @@ const dbAccount = Object.freeze({
   run({ row, serviceRoot }) {
     if (!hasDatabase(serviceRoot)) return [];
 
-    const shortName = shortNameOf(serviceRoot);
+    const { shortName, relative, declared } = readDeclaredAccount(serviceRoot, row.key);
     if (shortName === null) return [];
 
     const expected = `${DATABASE_PREFIX}${shortName}`;
-    const template = ownEnvTemplate(serviceRoot, shortName);
-    if (template === null) {
+    if (relative === null) {
       return [{
         where: row.path,
         what: `no env template of this service's own declares ${row.key}, and this service's account is `
@@ -306,23 +339,155 @@ const dbAccount = Object.freeze({
       }];
     }
 
-    const declared = declaredValue(template.text, row.key);
     if (declared === null) {
       return [{
-        where: template.relative,
+        where: relative,
         what: `declares no ${row.key}, and this service's account is ${JSON.stringify(expected)}`
       }];
     }
     if (declared === expected) return [];
 
     return [{
-      where: template.relative,
+      where: relative,
       what: `${row.key} is ${JSON.stringify(declared)}, and the account derived from ${IDENTITY_FILE} `
         + `is ${JSON.stringify(expected)}`
     }];
   }
 });
 
+/**
+ * `D-DB-CI-ACCOUNT` — the pipeline reaches the database as the SERVICE.
+ *
+ * `D-DB-ACCOUNT` one row up measures the DECLARATION: `DB_USER` in the env
+ * template, the account production installs. Nothing measured the ONE
+ * environment where that migration set is applied every day. Measured
+ * 2026-09-16 over the eight biz repositories: seven set `DB_USER: "root"` in
+ * their `test` job while declaring `oagen_<service>` in the template, so CI
+ * proved the set under rights no production box grants — the gap
+ * `db-migrations-first-deploy` 001 :32 names ("migrace nikdy pod rootem") in the
+ * only place it can be tried before a deploy.
+ *
+ * A SEPARATE row rather than a wider `D-DB-ACCOUNT`: another file, another fix,
+ * and one row with two fixes is two mechanisms under one name
+ * (`automation-gates.md` §1.2).
+ *
+ * ## What it reads, and what it leaves alone
+ *
+ * Only the lines OUTSIDE the `oa-ci v1` block. That block is the platform's and
+ * `G-CI` compares it to the template byte for byte; a second row reporting an
+ * edit there would be the duplicate `change-discipline.md` § One rail per
+ * concern forbids. Reading a REGION and not the whole file is also what keeps it
+ * clear of the defect that had the whole-file row over `.gitlab-ci.yml`
+ * withdrawn after three days: the other half of this file genuinely is the
+ * service's (`serviceFiles.js`, `delimited-block-render`).
+ *
+ * It asks WHO the database steps run as. It does NOT ask whether a repository
+ * runs them: a job that builds no schema has no account for the step to create,
+ * and demanding one would be this row inventing a rule
+ * (`truth-over-agreement.md` §6). Said out loud because a boundary nobody states
+ * is read as coverage (`automation-gates.md` §5).
+ *
+ * Silent for a service with no `database` block, by construction — `pdfgen` is
+ * the live case.
+ *
+ * @see api/docs/governance/confirmations/db-accounts-per-service.md
+ * @see api/docs/governance/confirmations/db-migrations-first-deploy.md
+ */
+
+/**
+ * The step that CREATES the account, and the step that first connects as it.
+ *
+ * Both are read on lines that are not comments. Measured in `api_biz/meta`: the
+ * `before_script` opens with a comment explaining why the job installs
+ * mariadb-client, and that comment NAMES `ci:gate:setup` — so a finding would
+ * have pointed the reader at a sentence instead of at the step, and a comment
+ * naming `setup-db-account` would have counted as running it.
+ */
+const ACCOUNT_STEP = /\bsetup-db-account\b/;
+const SCHEMA_STEP = /\bci:gate:setup(?![\w:-])/;
+const COMMENT = /^\s*#/;
+
+/** `KEY: value`, as a YAML mapping line reads it — a `#` line declares nothing. */
+const DECLARATION = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$/;
+
+const unquoted = (value) => value.trim().replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '');
+
+/**
+ * The other spelling of the same thing: `DB_USER=root` as a shell prefix on the
+ * step itself, so root is never left standing in the job environment.
+ *
+ * Measured shape, `api_biz/hello-service`:
+ *   `- DB_USER=root DB_PASSWORD="$MYSQL_ROOT_PASSWORD" npm run ci:gate:setup`
+ * The intent is the better one, and the migration set is still applied by the
+ * superuser — which is the whole of what this row is about. A check reading only
+ * the `variables:` block would call that green, and a gate that is silent where
+ * it should speak is the false guarantee `automation-gates.md` §5 names.
+ *
+ * @param {string} line one line of the file
+ * @param {string} key the variable name the row measures
+ * @returns {string|null} the value, or null when the line assigns nothing
+ */
+function inlineAssignment(line, key) {
+  if (/^\s*#/.test(line)) return null;
+  const match = line.match(new RegExp(`(?:^|[\\s;&|])${key}=(\\S*)`));
+  return match === null ? null : match[1].replace(/^["']|["']$/g, '');
+}
+
+const dbCiAccount = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'block', 'key', 'account']),
+
+  run({ row, serviceRoot }) {
+    if (!hasDatabase(serviceRoot)) 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 lines = fs.readFileSync(file, 'utf8').split('\n');
+    const block = blockLines(fs.readFileSync(file, 'utf8'), row.block);
+    const blockStart = block.length === 0 ? -1 : lines.indexOf(block[0]);
+    const inBlock = (index) => blockStart !== -1 && index >= blockStart && index < blockStart + block.length;
+
+    const shortName = shortNameOf(serviceRoot);
+    const account = shortName === null ? null : `${DATABASE_PREFIX}${shortName}`;
+    const findings = [];
+
+    let accountStepAt = -1;
+    let schemaStepAt = -1;
+
+    lines.forEach((line, index) => {
+      if (inBlock(index)) return;
+      const isStep = !COMMENT.test(line);
+      if (isStep && accountStepAt === -1 && ACCOUNT_STEP.test(line)) accountStepAt = index;
+      if (isStep && schemaStepAt === -1 && SCHEMA_STEP.test(line)) schemaStepAt = index;
+
+      const declaration = line.match(DECLARATION);
+      const declared = declaration !== null && declaration[1] === row.key
+        ? unquoted(declaration[2])
+        : inlineAssignment(line, row.key);
+      if (declared !== row.account) return;
+
+      findings.push({
+        where: `${row.path}:${index + 1}`,
+        what: `${row.key} is ${JSON.stringify(row.account)} — this pipeline applies the migration set as `
+          + 'the database superuser, and production applies it as '
+          + `${account === null ? 'the service account' : `the service account ${JSON.stringify(account)}`}`
+      });
+    });
+
+    if (schemaStepAt !== -1 && (accountStepAt === -1 || accountStepAt > schemaStepAt)) {
+      findings.push({
+        where: `${row.path}:${schemaStepAt + 1}`,
+        what: `ci:gate:setup connects as ${row.key}, and no setup-db-account step runs before it — the `
+          + 'account it connects as is created by nothing'
+      });
+    }
+
+    return findings;
+  }
+});
+
 /**
  * `D-DB-COLLATION` — the schema is created with a collation this service CHOSE.
  *
@@ -378,11 +543,15 @@ const dbCollation = Object.freeze({
 });
 
 module.exports = {
+  readDeclaredAccount,
+  ACCOUNT_KEY,
+  ENV_TEMPLATE_DIR,
   checks: [
     { name: 'db-consistent', check: dbConsistent },
     { name: 'db-collation', check: dbCollation },
     { name: 'db-migration-naming', check: dbMigrationNaming },
     { name: 'db-readme', check: dbReadme },
-    { name: 'db-account', check: dbAccount }
+    { name: 'db-account', check: dbAccount },
+    { name: 'db-ci-account', check: dbCiAccount }
   ]
 };