@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

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 }
   ]
 };

package/src/manifest/checks/serviceFiles.js

@@ -27,9 +27,10 @@ const path = require('path');
 
 const { readReferencedFile, isPackageReference, referenceOwner } = require('../discovery');
 const { whereOf } = require('./libraryContext');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 const { readComposeServices, scalarAt, declares, declarationOf } = require('./composeShape');
 const {
-  SHARED_DECLARATIONS, CONTAINER_PLACEHOLDER, SERVICE_PLACEHOLDER, normalizeRunnerBlock
+  SHARED_DECLARATIONS, renderRunnerIdentity, stripDeclarations
 } = require('./composeRunnerBlock');
 const { renderText, topLevelKeys } = require('../../sync/serviceTemplate');
 const { readIdentity, requireIdentity, IDENTITY_FILE } = require('../serviceIdentity');
@@ -51,7 +52,8 @@ const READS_ITS_REFERENCE_ONLY = Object.freeze({
   needsWorkspace: ({ row }) => !isPackageReference(row.from),
 
   describeNotRun({ row }) {
-    return `the workspace root is not reachable, so ${referenceOwner(row.from)} cannot be read`;
+    const owner = referenceOwner(row.from);
+    return `the workspace root is not reachable, so ${owner} cannot be read. ${describeWorkspaceFix(owner)}`;
   }
 });
 
@@ -433,9 +435,14 @@ const composeRunner = Object.freeze({
       return findings;
     }
 
+    // The reference is rendered for THIS repository and compared with the file
+    // as it stands — the direction the generator writes in, and the only one
+    // that is exact (`composeRunnerBlock.js` § renderRunnerIdentity, d.531).
+    // The three shared declarations come off both sides, because the rows above
+    // compare those against the service this runner tests.
     const difference = firstDifference(
-      normalizeRunnerBlock({ lines: mine, containerName, serviceName }),
-      normalizeRunnerBlock({ lines: reference, containerName: CONTAINER_PLACEHOLDER, serviceName: SERVICE_PLACEHOLDER })
+      stripDeclarations(mine, SHARED_DECLARATIONS),
+      stripDeclarations(renderRunnerIdentity({ lines: reference, containerName, serviceName }), SHARED_DECLARATIONS)
     );
     if (difference !== null) {
       say(`the "${row.block}" block differs from the template at block line ${difference.line}: `
@@ -600,6 +607,25 @@ const DOCKERIGNORE_BLOCK = 'oa-dockerignore v1';
  */
 const DOCKER_IMPLICIT = Object.freeze(['.git']);
 
+/**
+ * The test tree, which `.gitignore` must NOT declare and the image must not
+ * carry: tests live in the repository and never in the artefact that runs. It is
+ * the same decision the library uniform makes one row over as `L-PACK-TESTS`,
+ * applied to an image instead of a tarball — the reason is one, so the sentence
+ * is one (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * The exception is the reason this is a list and not a line. `tests/cookbooks`
+ * is NOT a test: it is a declaration the RUNTIME reads. Tier-1 of the boot runs
+ * those cookbooks at phase 0.2, and an image without the directory measures zero
+ * of them, so `ValidationProofGenerator` refuses the proof as NO_TESTS
+ * (`src/validators/ValidationProofGenerator.js`) and the service never starts.
+ * Measured on 2026-09-16 against the wrapper's boot path.
+ *
+ * Order carries the meaning: in a `.dockerignore` a later line wins, so the
+ * re-inclusion stands AFTER the two exclusions and never before them.
+ */
+const DOCKER_TEST_TREE = Object.freeze(['tests', '**/tests', '!tests/cookbooks']);
+
 /**
  * The exclusions a `.dockerignore` must carry, DERIVED from the very declaration
  * the `.gitignore` row reads. One list, two consumers
@@ -619,9 +645,9 @@ const DOCKER_IMPLICIT = Object.freeze(['.git']);
  * A negation keeps its `!` in front of the pattern rather than inside it, and
  * keeps its place in the order — in both formats a later line wins.
  *
- * What the derivation does NOT do is exclude anything `.gitignore` does not:
- * `tests/` is the measured trap on that side, because Tier-1 of the boot reads
- * `tests/cookbooks` and an image without it fails at phase 0.2.
+ * What the derivation adds to the declaration is the test tree, and exactly one
+ * exception inside it — see `DOCKER_TEST_TREE` above. Nothing else: an entry the
+ * `.gitignore` does not declare has no business being invented here.
  *
  * @param {string} gitignoreText the declaration both rows read
  * @returns {string[]}
@@ -640,6 +666,7 @@ function dockerignoreEntries(gitignoreText) {
     if (!pattern.includes('/')) add(mark(`**/${pattern}`));
   }
 
+  for (const entry of DOCKER_TEST_TREE) add(entry);
   for (const entry of DOCKER_IMPLICIT) add(entry);
   return entries;
 }

package/src/manifest/checks/serviceIdentityRows.js

@@ -46,6 +46,7 @@ const { readComposeServices } = require('./composeShape');
 const { readIdentity, IDENTITY_FILE } = require('../serviceIdentity');
 const { PLACEHOLDERS } = require('../../sync/serviceTemplate');
 const { resolveFromMap } = require('../discovery');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 
 /** Where a service declares the name npm knows it by. */
 const PACKAGE_FILE = 'package.json';
@@ -271,7 +272,8 @@ const ssotIdentity = Object.freeze({
   requires: Object.freeze([]),
 
   describeNotRun({ block }) {
-    return `the workspace root is not reachable, so ${block.from.path} cannot be read`;
+    return `the workspace root is not reachable, so ${block.from.path} cannot be read. `
+      + describeWorkspaceFix(block.from.path);
   },
 
   run({ block, serviceRoot, workspaceRoot }) {

package/src/manifest/checks/serviceRuntime.js

@@ -44,6 +44,7 @@ const path = require('path');
 
 const { resolveFromValue, isPackageReference, referenceOwner } = require('../discovery');
 const { whereOf } = require('./libraryContext');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 const { readComposeServices, scalarAt, declares, declarationOf } = require('./composeShape');
 
 /** Where a service block states its own budget, in both compose files. */
@@ -52,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;
@@ -106,7 +110,8 @@ const nodeMajor = Object.freeze({
   needsWorkspace: ({ row }) => !isPackageReference(row.from),
 
   describeNotRun({ row }) {
-    return `the workspace root is not reachable, so ${referenceOwner(row.from)} cannot be read`;
+    const owner = referenceOwner(row.from);
+    return `the workspace root is not reachable, so ${owner} cannot be read. ${describeWorkspaceFix(owner)}`;
   },
 
   run({ row, serviceRoot, workspaceRoot }) {
@@ -267,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']),
@@ -289,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

@@ -237,21 +237,38 @@ function resolveFromValue({ from, workspaceRoot }) {
 }
 
 /**
- * The node a `from.list` path points at, as the owner file writes it.
+ * The whole referenced file as the document it is: `{ path, text: true }` over a
+ * JSON SSOT, for a row that does not take a value out of it but hands it to the
+ * module that owns its shape (`G-SHARED-ENV` renders `api/config/shared-env.json`
+ * through `src/sync/sharedEnv.js`).
  *
- * @param {{ from: {path: string, list: string}, workspaceRoot: string }} params
- * @returns {Array|object} the array or the object map the reference names
+ * It is the same read and the same refusal `resolveFromMap` makes, said once:
+ * a broken SSOT is reported as a broken SSOT wherever a row reads it, and the
+ * second call site is the one that would have written its own sentence
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * @param {{ from: {path: string}, workspaceRoot: string }} params
+ * @returns {object|Array} the parsed document
  */
-function resolveFromMap({ from, workspaceRoot }) {
+function resolveFromDocument({ from, workspaceRoot }) {
   const raw = readReferencedFile({ from, workspaceRoot });
 
-  let document;
   try {
-    document = JSON.parse(raw);
+    return JSON.parse(raw);
   } catch (cause) {
-    throw new Error(`[ManifestDiscovery] Referenced file is not valid JSON - ${from.path}. `
+    throw new Error(`[ManifestDiscovery] Referenced file is not valid JSON - ${referenceOwner(from)}. `
       + 'Fix: repair the file; it is the SSOT this row reads.', { cause });
   }
+}
+
+/**
+ * The node a `from.list` path points at, as the owner file writes it.
+ *
+ * @param {{ from: {path: string, list: string}, workspaceRoot: string }} params
+ * @returns {Array|object} the array or the object map the reference names
+ */
+function resolveFromMap({ from, workspaceRoot }) {
+  const document = resolveFromDocument({ from, workspaceRoot });
 
   const node = from.list.split('.').reduce((current, key) => (current == null ? undefined : current[key]), document);
   if (node === null || node === undefined || typeof node !== 'object') {
@@ -378,6 +395,7 @@ module.exports = {
   resolveFromValue,
   resolveFromMap,
   readReferencedFile,
+  resolveFromDocument,
   expandPattern,
   rootOfPattern,
   containerOf,

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 };