@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

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

@@ -33,8 +33,11 @@ const {
   PLATFORM_TEST_FILE_PATTERN,
 } = require('../utils/testCoverageContract');
 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 = {
@@ -89,7 +92,7 @@ Commands:
                              contract's closed vocabularies on every live migrations/**/*.sql
                              (archive/ and superseded/ excluded), and each BASELINE manifest
                              naming exactly the files the installer applies, in that order.
-  run-prevalidation          Run the service's cookbooks offline against mocked infrastructure
+  run-prevalidation          Run the service's cookbooks in-process (no transport, real database)
                              and write conn-runtime/validation-proof.json. Replaces the
                              per-service scripts/run-pre-validation.js.
   verify-lib-compat          Compare @onlineapps/* pins against the platform library SSOT (R6).
@@ -100,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.
@@ -130,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 -
@@ -257,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).
@@ -382,18 +541,6 @@ async function runVerifyContract(options) {
 }
 
 
-/**
- * Running cookbooks needs `tests/cookbooks/`, `operations.json` and the handler
- * modules — nothing else. This command used to resolve the service's own
- * `@onlineapps/service-wrapper`, run `ConfigLoader.loadAll()` and pass
- * `service.url` to the runner, which never read it (`this.serviceUrl` appears
- * nowhere in CookbookTestRunner). `ConfigLoader.loadAll` no longer returns that
- * field either — the owner removed `port` and `url` from the service shape
- * (docs/governance/confirmations/biz-service-port-url.md 001), so the value had
- * been `undefined` for every service on the platform. What the load still did
- * was make a readable config, an installed wrapper and a resolvable `${ENV}`
- * placeholder preconditions of a cookbook run that depends on none of them.
- */
 /**
  * End the process with this code, once everything written has left the buffers.
  *
@@ -434,6 +581,27 @@ function exitWhenFlushed(code) {
   done();
 }
 
+/**
+ * What a cookbook run reads, and what it does NOT.
+ *
+ * It reads `tests/cookbooks/`, `config/service/operations.json` and the
+ * service's `package.json`, and it dispatches the service's own v3 handler
+ * modules IN THIS PROCESS. So it needs whatever those handlers need: a handler
+ * that reaches its schema opens the service's real pool here, which is the
+ * subject of `exitWhenFlushed` above. "Nothing else" is what this sentence used
+ * to say, and the paragraph below it said the opposite (d.523).
+ *
+ * What it does not do is load the service CONFIG. This command used to resolve
+ * the service's own `@onlineapps/service-wrapper`, run `ConfigLoader.loadAll()`
+ * and pass `service.url` to the runner, which never read it (`this.serviceUrl`
+ * appears nowhere in CookbookTestRunner). `ConfigLoader.loadAll` no longer
+ * returns that field either — the owner removed `port` and `url` from the
+ * service shape (docs/governance/confirmations/biz-service-port-url.md 001), so
+ * the value had been `undefined` for every service on the platform. What the
+ * load still did was make a readable config, an installed wrapper and a
+ * resolvable `${ENV}` placeholder preconditions of a cookbook run that depends
+ * on none of them.
+ */
 async function runRunPreValidation(options) {
   const outcome = await runPreValidation({
     serviceRoot: path.resolve(options.serviceRoot),
@@ -451,7 +619,11 @@ async function runRunPreValidation(options) {
 
   if (!outcome.ok) {
     for (const step of outcome.failedSteps) {
-      process.stderr.write(`[BizCiGate] FAIL run-prevalidation — ${step.step_id}: ${step.error}\n`);
+      // The record names itself: `results.steps` carries two kinds and this
+      // line printed `step_id` for both, so a rejected cookbook read as
+      // `undefined` (d.523). The identity comes from the one owner of it,
+      // through `runPreValidation`'s outcome.
+      process.stderr.write(`[BizCiGate] FAIL run-prevalidation — ${describeRecordIdentity(step)}: ${step.error}\n`);
       for (const validationError of step.validationErrors) {
         process.stderr.write(`[BizCiGate]   * ${validationError}\n`);
       }
@@ -689,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-sync-template.js

@@ -11,8 +11,9 @@
  *   * bare paths - the uniform sync of confirmation 001 §3.2. It writes the
  *     files of the manifest classes `identical` and `generated` from the very
  *     `from:` reference those rows already point the conformance CHECK at, and
- *     never touches a file of the `own` class. A row the manifest does not make
- *     renderable is reported NOT RUN by name, never filled from a guess.
+ *     never touches a file of the `own` class. A row that names no `from:`
+ *     reference is not a row of this run — it is a requirement about the
+ *     repository, and `npx oa-validate` is what answers it (d.507).
  *   * `--new <name>` - the whole service tree, from the template that ships
  *     inside this package (001 §2). It is what `api/scripts/add-service.sh
  *     --scaffold` runs; that script keeps the platform facts (the registry
@@ -48,7 +49,7 @@ const {
   SSOT_PIN,
   TEMPLATE_ROOT
 } = require('../sync/serviceTemplate');
-const { planSync, uniformRows } = require('../sync/uniformFiles');
+const { planSync, uniformRows, isSyncRow } = require('../sync/uniformFiles');
 const { loadManifest: loadUniformManifest, DEFAULT_MANIFEST_PATH } = require('../manifest/loadManifest');
 const {
   applyUniformRegion,
@@ -107,10 +108,11 @@ Usage:
   is: generated output, committed for reading (001 §5). --check is the gate.
 
   With bare paths (or none, meaning all of them) the run rewrites the files the
-  manifest declares in the classes "identical" and "generated", from the same
-  reference the conformance check reads. Files of the "own" class - src/**,
-  tests/**, the content of docs/** - are never written. A row the manifest does
-  not make renderable is printed NOT RUN with the reason.
+  manifest declares in the classes "identical" and "generated" that name a
+  "from" reference, from that same reference the conformance check reads. Files
+  of the "own" class - src/**, tests/**, the content of docs/** - are never
+  written. A row naming no reference is a requirement about the repository
+  rather than a file, and npx oa-validate <serviceRoot> is what answers it.
 
   --new <name>        create a service tree from the packaged template
   --into <dir>        where that tree is written; it must not exist yet
@@ -721,9 +723,22 @@ function runSync(options) {
   // The positionals are judged FIRST, against the manifest, and before anything
   // that touches the disk: a mistyped subcommand must be named as what it is,
   // not reported as a missing workspace three steps later.
-  const declared = uniformRows(loadUniformManifest(DEFAULT_MANIFEST_PATH)).map((row) => row.path);
+  const rows = uniformRows(loadUniformManifest(DEFAULT_MANIFEST_PATH));
+  const declared = rows.filter(isSyncRow).map((row) => row.path);
   for (const wanted of options.paths) {
     if (declared.includes(wanted)) continue;
+
+    // A path the uniform DOES declare, as a requirement rather than as a file
+    // this run renders, is refused by what it is and not as a typo: the reader
+    // named a real row, and what they need is the run that answers it.
+    const requirement = rows.find((row) => row.path === wanted);
+    if (requirement !== undefined) {
+      throw new Error(`[oa-sync-template] "${wanted}" is declared by ${requirement.id}, which names no "from" `
+        + 'reference - it is a requirement about the repository, not a file this run renders. '
+        + 'Fix: check it with npx oa-validate <serviceRoot>; the paths this run writes are '
+        + `(${declared.join(', ')}).`);
+    }
+
     throw new Error(`[oa-sync-template] Unknown argument "${wanted}" - it is neither a subcommand this run `
       + `has (${SUBCOMMAND_NAMES.join(', ')}) nor a path the uniform declares (${declared.join(', ')}). `
       + 'Fix: name one of those, or leave the paths out to write them all.');

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);
@@ -433,7 +494,13 @@ function main(argv) {
   }
   const serviceRoot = canonicalRoot(given);
 
-  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace });
+  // The workspace this SERVICE lies in, not the one this package lies in
+  // (d.540): the copy a service runs is the one it installed, and an installed
+  // copy is part of no checkout — `oa-validate .` inside a complete workspace
+  // printed NOT RESOLVED and reported every workspace row NOT RUN. The root is
+  // the one the caller named, never `process.cwd()`
+  // (`workspaceRoot.js` § The service a run is ABOUT).
+  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace, serviceRoot });
   const result = runManifest({ manifest, serviceRoot, workspaceRoot });
 
   process.stdout.write(options.json ? renderJson(result) : renderReport(result));
@@ -465,6 +532,7 @@ if (require.main === module) {
 module.exports = {
   main,
   parseArgs,
+  runEnvReads,
   runLibrary,
   checkOnePackage,
   checkEveryPackage,

package/src/index.js

@@ -12,10 +12,6 @@
  * @see /api/docs/architecture/validator.md (validator architecture)
  */
 
-const MockMQClient = require('./mocks/MockMQClient');
-const MockRegistry = require('./mocks/MockRegistry');
-const MockStorage = require('./mocks/MockStorage');
-
 const CookbookTestUtils = require('./CookbookTestUtils');
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const ValidationProofGenerator = require('./validators/ValidationProofGenerator');
@@ -34,11 +30,16 @@ const ValidationOrchestrator = require('./ValidationOrchestrator');
 
 const { createServiceReadinessTests } = require('./helpers/createServiceReadinessTests');
 
+// No infrastructure doubles are published. `MockMQClient`, `MockRegistry` and
+// `MockStorage` were the furniture of `mockInfrastructure`, retired in d.576:
+// pre-validation dispatches a step in-process against the service's own v3
+// handler, so there is no transport to stand in for, and the database a handler
+// reaches is the real one. `MockRegistry` stays inside the package as the
+// registry stand-in of `helpers/createServiceReadinessTests`, which is a
+// different concern and keeps its own consumer; `MockMQClient` as the double of
+// `tests/unit/RegistrationFlow.test.js`. `MockStorage` had neither, so d.583
+// deleted the file as well as the export (`tests/unit/mockInfrastructureRetired.test.js`).
 module.exports = {
-  get MockMQClient() { return MockMQClient; },
-  get MockRegistry() { return MockRegistry; },
-  get MockStorage() { return MockStorage; },
-
   get CookbookTestUtils() { return CookbookTestUtils; },
   get ServiceReadinessValidator() { return ServiceReadinessValidator; },
   get CookbookTestRunner() { return CookbookTestRunner; },
@@ -82,11 +83,18 @@ module.exports = {
   get parseHandlerRef() { return require('./utils/handlerRef').parseHandlerRef; },
   get resolveHandlerModule() { return require('./utils/handlerRef').resolveHandlerModule; },
 
+  // The other half of what a service's integration harness needs to build its
+  // throwaway schema: which .sql files make up the set, and in which order.
+  // `createThrowawaySchema` above resolves the plan itself; a harness that
+  // builds its own schema step by step reads the plan directly, and had to
+  // reach into `src/utils/setupDatabase` to get it — a path inside the package
+  // is not a contract, and every move of `src/utils/` would break a consumer
+  // that never agreed to one. Exported as the identical function, not a
+  // wrapper: one definition, one behaviour (`change-discipline.md` § One rail
+  // per concern).
+  get resolveMigrationPlan() { return require('./utils/setupDatabase').resolveMigrationPlan; },
+
   get createServiceReadinessTests() { return createServiceReadinessTests; },
   get BizCiGateContract() { return BizCiGateContract; },
-  get IntegrationRun() { return require('./utils/integrationRun'); },
-
-  createMockMQ: () => new MockMQClient(),
-  createMockRegistry: () => new MockRegistry(),
-  createMockStorage: () => new MockStorage()
+  get IntegrationRun() { return require('./utils/integrationRun'); }
 };

package/src/lint/scripts/lintScripts.js

@@ -30,12 +30,22 @@
  * biz repositories: 47 `@see` lines under their scripts directories, of which 4
  * open with the `api/` prefix.
  *
- * Two scopes, two rules. S001-S008 read the HEADER of every script under
- * `scripts/`. S009 reads the COMMENTS of every test under `tests/scripts/` and
- * nothing else in them: a `<path>.<ext>:<line>` citation in prose has no
- * mechanism keeping it true (`doc-code-binding.md` §1), while the same shape on
- * a CODE line is a fixture assertion whose target the test creates itself and
- * which therefore cannot rot.
+ * Two scopes, three rules. S001-S008 read the HEADER of every script under
+ * `scripts/`. S009 and S010 read the tests, and they read opposite halves of
+ * them. S009 reads the COMMENTS and nothing else: a `<path>.<ext>:<line>`
+ * citation in prose has no mechanism keeping it true (`doc-code-binding.md`
+ * §1), while the same shape on a CODE line is a fixture assertion whose target
+ * the test creates itself and which therefore cannot rot. S010 reads the CODE
+ * lines and nothing else: an inverted command is exempt from `errexit`, so an
+ * assertion written that way asserts nothing unless it happens to be the last
+ * command of the body.
+ *
+ * The test scope is `tests/`, not the one directory S009 was born in. A rule
+ * that reads `tests/scripts/` and not `tests/scripts-docker/` beside it has a
+ * hole nobody can see: the run reports `0 finding(s)` and never says which
+ * files it did not open. Widened in d.482 (2026-09-15) together with S010, over
+ * a scope measured clean for both rules first — no baseline
+ * (`automation-gates.md` §3).
  *
  * @see api/docs/standards/SCRIPTS-STANDARD.md
  * @see api/docs/governance/confirmations/biz-service-manifest.md
@@ -54,8 +64,8 @@ const SHELL_VOCAB = new Set(['bash>=4', 'bash>=3.2', 'sh', 'node>=18', 'node>=24
 /** The directory whose scripts carry the header. */
 const SCRIPT_SCOPE = 'scripts';
 
-/** The directory whose COMMENTS S009 reads, and nothing else in it. */
-const CITATION_SCOPE = 'tests/scripts';
+/** The directory whose tests S009 and S010 read, each one half of them. */
+const CITATION_SCOPE = 'tests';
 
 /**
  * The directories whose files are libraries rather than entry points.
@@ -111,6 +121,27 @@ const LINE_CITATION = /[A-Za-z0-9_/.-]+\.(?:js|mjs|cjs|ts|mts|sh|bash|bats|yml|j
 /** A comment line of a shell-family test. */
 const COMMENT_LINE = /^\s*#/;
 
+/**
+ * An assertion written as an inverted command, in the two shapes bats carries.
+ *
+ * Measured on bats 1.13.0: under `set -e` a command whose exit code is inverted
+ * is exempt from errexit, so `! cmd` in the middle of a test body fails nothing
+ * — the test stays green whatever `cmd` returns. Only the LAST command of the
+ * body decides the verdict, which is why the defect survives review: the line
+ * reads like an assertion and is one exactly when it happens to sit last.
+ *
+ * The rule does not try to tell the last command from the others. It reports
+ * every occurrence, because the position is a property of the file's current
+ * shape rather than of the assertion's intent: a line inserted below turns a
+ * working assertion into an inert one with no edit to the assertion itself.
+ * INFRA rewrote all 32 occurrences this platform carried before the rule landed
+ * (`572488c4`, `6100477e`, `d212d3c6`), so the stricter reading costs nothing.
+ *
+ * `if ! cmd; then … fi` is NOT this defect and matches neither pattern: there
+ * the `if` consumes the exit code on purpose, which is the shape the fix uses.
+ */
+const INERT_ASSERTION = Object.freeze([/^\s*!\s/, /\|\|\s*!\s/]);
+
 /** The prefix a citation of the api checkout opens with, as every document writes it. */
 const API_PREFIX = 'api/';
 
@@ -265,22 +296,38 @@ function lintScripts({ root, apiRoot = null }) {
     );
   }
 
-  // S009: a comment under tests/scripts/ cites a symbol or a literal string, and
-  // a covered defect cites the commit hash — never a line number.
+  // S009 on the comment lines, S010 on the code lines. One pass, because they
+  // partition the same file: a line is prose or it is a command, never both.
   for (const relative of citationScanned) {
     const lines = fs.readFileSync(path.join(root, ...relative.split('/')), 'utf8').split('\n');
     for (let n = 0; n < lines.length; n += 1) {
-      if (!COMMENT_LINE.test(lines[n])) continue;
-      const hit = lines[n].match(LINE_CITATION);
-      if (hit === null) continue;
+      // S009: a comment cites a symbol or a literal string, and a covered
+      // defect cites the commit hash — never a line number.
+      if (COMMENT_LINE.test(lines[n])) {
+        const hit = lines[n].match(LINE_CITATION);
+        if (hit === null) continue;
+        findings.push({
+          id: 'S009',
+          file: relative,
+          line: n + 1,
+          message: `Comment cites a line number - "${hit[0]}". A line number has no mechanism keeping it true: `
+            + 'the file moves and the number stays (doc-code-binding.md §1). Fix: cite a symbol or a literal '
+            + 'string; a covered defect cites the commit hash that introduced or repaired it '
+            + "(git log -S'<string>' --format=%h -- <file>) - DOC-STANDARD rule 11."
+        });
+        continue;
+      }
+
+      // S010: an assertion whose exit code is inverted is exempt from errexit.
+      if (!INERT_ASSERTION.some((shape) => shape.test(lines[n]))) continue;
       findings.push({
-        id: 'S009',
+        id: 'S010',
         file: relative,
         line: n + 1,
-        message: `Comment cites a line number - "${hit[0]}". A line number has no mechanism keeping it true: `
-          + 'the file moves and the number stays (doc-code-binding.md §1). Fix: cite a symbol or a literal '
-          + 'string; a covered defect cites the commit hash that introduced or repaired it '
-          + "(git log -S'<string>' --format=%h -- <file>) - DOC-STANDARD rule 11."
+        message: `Inert assertion - "${lines[n].trim()}". Under set -e a command with an inverted exit code `
+          + 'is exempt from errexit, so it fails nothing unless it is the last command of the test body. '
+          + 'Fix: if <what must not hold>; then echo "[ctx] problem - found: …" >&2; return 1; fi '
+          + '— SCRIPTS-STANDARD.md § Enforcement'
       });
     }
   }