@onlineapps/conn-orch-validator 7.0.0 → 8.0.0

package/src/manifest/checks/serviceFiles.js

@@ -0,0 +1,754 @@
+'use strict';
+
+/**
+ * The `identical` class: files a service does not get to decide, because the
+ * template already did (confirmation `biz-service-manifest` 001 §2).
+ *
+ * Two shapes of "identical", and the reason there are two: measured over the
+ * eight repositories on 2026-09-09, no whole file is byte-equal across nine
+ * copies, but a delimited BLOCK is (`init.sh`), and a file that carries no
+ * identity at all can be (`jest.config.js`). A row therefore names either a
+ * block or a whole file, and the template is the reference in both cases —
+ * reached through the row's `from:` reference, never copied into the manifest
+ * (004 point 2).
+ *
+ * The runner row is neither: a compose service cannot be byte-equal across
+ * repositories, because its name IS the repository. What the uniform fixes there
+ * is the shape — one profile, one budget, no restart, and the same build, env
+ * and networks as the service it tests — so `compose-runner` compares the two
+ * blocks of ONE file against each other and the two platform numbers against
+ * the row.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §2
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { readReferencedFile, isPackageReference, referenceOwner } = require('../discovery');
+const { whereOf } = require('./libraryContext');
+const { readComposeServices, scalarAt, declares, declarationOf } = require('./composeShape');
+const {
+  SHARED_DECLARATIONS, CONTAINER_PLACEHOLDER, SERVICE_PLACEHOLDER, normalizeRunnerBlock
+} = require('./composeRunnerBlock');
+const { renderText, topLevelKeys } = require('../../sync/serviceTemplate');
+const { readIdentity, requireIdentity, IDENTITY_FILE } = require('../serviceIdentity');
+
+/** What the `test` profile is called. A runner is the service that declares it. */
+const TEST_PROFILE = 'test';
+
+/**
+ * What these checks need the workspace for, and nothing else: to READ the file
+ * the row's `from:` reference names. A reference into this package (d.229 —
+ * `manifestShape.js` § describeFromProblem) is carried by the package itself, so
+ * the row runs wherever the package is installed: in a service container, in the
+ * service's own CI checkout, and in the workspace exactly as before.
+ *
+ * Declared once, spread into every check of this module, because it is one
+ * sentence about all four (`change-discipline.md` § One rail per concern).
+ */
+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`;
+  }
+});
+
+/**
+ * Read a file of the repository under check.
+ *
+ * @param {string} serviceRoot repository root
+ * @param {string} relative repository-relative path
+ * @returns {string|null} null when the file is not there
+ */
+function readServiceFile(serviceRoot, relative) {
+  const target = path.join(serviceRoot, ...relative.split('/'));
+  if (!fs.existsSync(target)) return null;
+  return fs.readFileSync(target, 'utf8');
+}
+
+/**
+ * The lines of a delimited block, markers included.
+ *
+ * The markers are the two lines `api/tests/scripts/infra-init-scripts.bats`
+ * matches on (`GUARD_OPEN` / `GUARD_CLOSE`, its lines 202-203): the block opens
+ * with `# --- <name>` and closes with `# --- end <name>`. That bats file guards
+ * `api/infra/*` and says in its own comment that the `api_biz/*` copies are kept
+ * in sync by review only — this row is that reach extended to the biz
+ * repositories, which is why it reads the same two markers rather than
+ * inventing a third spelling.
+ *
+ * The marker is read TRIMMED, because the second block the manifest declares
+ * lives in a compose file: `oa-test-runner v1` sits inside `services:`, so its
+ * two markers are indented by two spaces. A YAML comment is a comment at any
+ * column, and a shell comment at column 0 still matches — `init.sh` is the
+ * control case both directions of this rule are measured against.
+ *
+ * @param {string} text file content
+ * @param {string} name the block name, e.g. `oa-deps-guard v1`
+ * @returns {string[]} the block's lines, or [] when there is none (or it never closes)
+ */
+function blockLines(text, name) {
+  const open = `# --- ${name}`;
+  const close = `# --- end ${name}`;
+  const lines = text.split('\n');
+  const collected = [];
+  let inside = false;
+
+  for (const line of lines) {
+    const marker = line.trim();
+    if (!inside && marker.startsWith(open) && !marker.startsWith(close)) inside = true;
+    if (!inside) continue;
+    collected.push(line);
+    if (marker.startsWith(close)) return collected;
+  }
+  return [];
+}
+
+/**
+ * The first line at which two texts differ, 1-based, and what the service says
+ * there. A quoted line is what makes the finding actionable in a table cell.
+ *
+ * `ended` is what is quoted where the service's side has run out. It is a
+ * parameter rather than a constant because the same comparison serves a block
+ * (`oa-deps-guard v1` inside a longer file) and a whole file, and a finding that
+ * says "<end of block>" about a truncated FILE sends the reader looking for
+ * markers that are not the defect.
+ *
+ * @param {string[]} mine the service's lines
+ * @param {string[]} reference the template's lines
+ * @param {string} ended what to quote where `mine` has no line at all
+ * @returns {{ line: number, text: string }|null} null when they are equal
+ */
+function firstDifference(mine, reference, ended = '<end of block>') {
+  const length = Math.max(mine.length, reference.length);
+  for (let i = 0; i < length; i += 1) {
+    if (mine[i] === reference[i]) continue;
+    return { line: i + 1, text: mine[i] === undefined ? ended : mine[i].trim() };
+  }
+  return null;
+}
+
+const templateBlock = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path', 'block', 'from']),
+
+  ...READS_ITS_REFERENCE_ONLY,
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const text = readServiceFile(serviceRoot, row.path);
+    if (text === null) {
+      return [{ where, what: `absent — the uniform's ${row.path} carries the "${row.block}" block` }];
+    }
+
+    const reference = blockLines(readReferencedFile({ from: row.from, workspaceRoot }), row.block);
+    if (reference.length === 0) {
+      throw new Error(`[ManifestFiles] Reference block "${row.block}" not found in ${referenceOwner(row.from)} - `
+        + 'the template is the reference bearer of this row and carries no such block. '
+        + 'Fix: restore the block in the template, or correct the row.');
+    }
+
+    const mine = blockLines(text, row.block);
+    if (mine.length === 0) {
+      return [{
+        where,
+        what: `carries no "${row.block}" block — the template ships one and every ${row.path} repeats it byte for byte`
+      }];
+    }
+
+    const difference = firstDifference(mine, reference);
+    if (difference === null) return [];
+
+    return [{
+      where,
+      what: `the "${row.block}" block differs from the template at block line ${difference.line}: "${difference.text}"`
+    }];
+  }
+});
+
+const templateFile = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path', 'from']),
+
+  ...READS_ITS_REFERENCE_ONLY,
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const text = readServiceFile(serviceRoot, row.path);
+    if (text === null) {
+      return [{ where, what: `absent — this file is ${referenceOwner(row.from)}, byte for byte` }];
+    }
+
+    const reference = readReferencedFile({ from: row.from, workspaceRoot });
+    if (text === reference) return [];
+
+    return [{ where, what: `differs from ${referenceOwner(row.from)} — this file is the template's, byte for byte` }];
+  }
+});
+
+/**
+ * The `generated` whole-file shape: the file IS the template rendered with this
+ * repository's name, and nothing else (owner decision
+ * `api/docs/governance/confirmations/server-topology.md` 005).
+ *
+ * The difference from `template-file` is the render, and it is the whole reason
+ * a second check exists: `jest.config.js` carries no identity, so the template
+ * IS the file; a compose file names the container, the image repository and the
+ * service's own env file, so the template is the file only after the one
+ * parameter a service has has been put in it. Comparing the raw template there
+ * would report every conformant service as drifted.
+ *
+ * The difference from `template-skeleton` is what is compared: a skeleton row
+ * owns the headings of a document whose prose is the service's, so it compares
+ * sections. Here there is no prose to protect — the measurement behind 005 is
+ * that the seven old-shape files were byte-identical once the name was
+ * normalised, so what a service "decides" about its production compose is its
+ * name and nothing more.
+ */
+const templateRender = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path', 'from']),
+
+  ...READS_ITS_REFERENCE_ONLY,
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const text = readServiceFile(serviceRoot, row.path);
+    if (text === null) {
+      return [{ where, what: `absent — this file is ${referenceOwner(row.from)}, rendered for this service` }];
+    }
+
+    // Nothing can be rendered for a repository that has not said who it is, and
+    // saying so here would give that defect a second owner: `C-SERVICE` puts it
+    // on the table with its own fix (`serviceIdentity.js`).
+    const identity = readIdentity(serviceRoot);
+    if (identity.problem !== undefined) {
+      if (identity.undecided === null) return [];
+      return [{
+        where: whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: IDENTITY_FILE }),
+        what: `${row.path} could not be compared — ${identity.undecided}`
+      }];
+    }
+
+    const reference = renderText(readReferencedFile({ from: row.from, workspaceRoot }), identity.params);
+    if (text === reference) return [];
+
+    // BOTH sides of the first differing line. One of them alone is unreadable
+    // for a whole-file row: "line 1: services:" says the file is wrong without
+    // saying what belongs there, and the fix command is the only other thing
+    // the reader gets.
+    const mine = text.split('\n');
+    const wanted = reference.split('\n');
+    const difference = firstDifference(mine, wanted, '<end of file>');
+    const expected = wanted[difference.line - 1];
+
+    return [{
+      where,
+      what: `differs from ${referenceOwner(row.from)} rendered for this service, `
+        + `at line ${difference.line}: ${JSON.stringify(difference.text)} — expected `
+        + `${JSON.stringify(expected === undefined ? '<end of file>' : expected.trim())}`
+    }];
+  }
+});
+
+/**
+ * The `generated` BLOCK shape: one delimited region of a file is the template's,
+ * rendered with this repository's name, and every line outside the markers is
+ * the repository's own (lead decision `api/shared/TODO.md` §0.2b-49, d.251).
+ *
+ * It is `template-block` plus the render, and `template-render` minus the rest
+ * of the file — and the reason it is neither of them is the defect it replaces.
+ * `.gitlab-ci.yml` carried a whole-file row for three days, and its fix could not
+ * be run: the template is 151 lines and the eight biz pipelines are 176 to 198,
+ * because each declares the service containers, the `ci:gate:*` steps and the
+ * artefact ITS integration needs. Syncing the whole file would have deleted
+ * those, which is a finding a gate can report and nobody can fix
+ * (`.claude/rules/automation-gates.md` §3, last bullet). The block is the same
+ * split `docker-compose.yml` already lives under, one level up: there a compose
+ * SERVICE is the platform's, here a set of top-level jobs is.
+ *
+ * The render is what separates it from `template-block`: the platform's half
+ * names the service once, in `GIT_CLONE_PATH`, which is what puts the CI
+ * checkout in the layout the engine needs. A byte comparison against the raw
+ * template would report every conformant service as drifted.
+ */
+const delimitedBlockRender = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path', 'block', 'from']),
+
+  ...READS_ITS_REFERENCE_ONLY,
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const text = readServiceFile(serviceRoot, row.path);
+    if (text === null) {
+      return [{
+        where,
+        what: `absent — this file is ${referenceOwner(row.from)}, `
+          + 'and the platform half of it is rendered for this service'
+      }];
+    }
+
+    // Nothing can be rendered for a repository that has not said who it is, and
+    // saying so here would give that defect a second owner: `C-SERVICE` puts it
+    // on the table with its own fix (`serviceIdentity.js`).
+    const identity = readIdentity(serviceRoot);
+    if (identity.problem !== undefined) {
+      if (identity.undecided === null) return [];
+      return [{
+        where: whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: IDENTITY_FILE }),
+        what: `${row.path} could not be compared — ${identity.undecided}`
+      }];
+    }
+
+    const rendered = renderText(readReferencedFile({ from: row.from, workspaceRoot }), identity.params);
+    const reference = blockLines(rendered, row.block);
+    if (reference.length === 0) {
+      throw new Error(`[ManifestFiles] Reference block "${row.block}" not found in ${referenceOwner(row.from)} - `
+        + 'the template is the reference bearer of this row and carries no such block. '
+        + 'Fix: restore the block in the template, or correct the row.');
+    }
+
+    const mine = blockLines(text, row.block);
+    if (mine.length === 0) {
+      return [{
+        where,
+        what: `carries no "${row.block}" block — the platform's half of this pipeline `
+          + `(${topLevelKeys(reference).join(', ')}) is what the template owns`
+      }];
+    }
+
+    const difference = firstDifference(mine, reference);
+    if (difference === null) return [];
+
+    const expected = reference[difference.line - 1];
+    return [{
+      where,
+      what: `the "${row.block}" block differs from ${referenceOwner(row.from)} rendered for this service, `
+        + `at block line ${difference.line}: ${JSON.stringify(difference.text)} — expected `
+        + `${JSON.stringify(expected === undefined ? '<end of block>' : expected.trim())}`
+    }];
+  }
+});
+
+const composeRunner = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path', 'runner_memory', 'block', 'from']),
+
+  ...READS_ITS_REFERENCE_ONLY,
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    // The locator names the repository, not just the file: this row runs once
+    // per bearer in a workspace run, and five services reporting
+    // "docker-compose.yml" are five findings nobody can tell apart.
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const text = readServiceFile(serviceRoot, row.path);
+    if (text === null) {
+      return [{ where, what: 'absent — the service is built and run from this file' }];
+    }
+
+    const services = readComposeServices(text);
+    const runners = [...services.entries()]
+      .filter(([, node]) => (node.sequences.get('profiles') || []).includes(TEST_PROFILE));
+
+    if (runners.length === 0) {
+      return [{
+        where,
+        what: `declares no service with profiles: [${TEST_PROFILE}] — the one-shot test runner is missing`
+      }];
+    }
+    if (runners.length > 1) {
+      return [{
+        where,
+        what: `declares ${runners.length} services with profiles: [${TEST_PROFILE}] — the uniform has one runner`
+      }];
+    }
+
+    const [runnerName, runner] = runners[0];
+    const others = [...services.entries()].filter(([name]) => name !== runnerName);
+    if (others.length !== 1) {
+      return [{
+        where,
+        what: `declares ${others.length} services beside the runner — the uniform is one service and its runner`
+      }];
+    }
+
+    const [, service] = others[0];
+    const findings = [];
+    // Every sentence of this row is about the compose file, apart from the one
+    // that is about the file this repository's identity is declared in.
+    const say = (what, relative = row.path) => findings.push({
+      where: relative === row.path
+        ? where
+        : whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative }),
+      what
+    });
+
+    const memory = scalarAt(runner, 'mem_limit');
+    if (memory !== row.runner_memory) {
+      say(`the runner ${runnerName} declares mem_limit ${JSON.stringify(memory)}, `
+        + `the uniform's runner budget is ${JSON.stringify(row.runner_memory)}`);
+    }
+    for (const forbidden of ['restart', 'healthcheck']) {
+      if (declares(runner, forbidden)) {
+        say(`the runner ${runnerName} declares "${forbidden}" — it runs once and exits`);
+      }
+    }
+    for (const shared of SHARED_DECLARATIONS) {
+      if (declarationOf(runner, shared) !== declarationOf(service, shared)) {
+        say(`the runner ${runnerName} declares a different "${shared}" than the service it tests`);
+      }
+    }
+
+    // The rest of the runner is the template's, byte for byte. What is compared
+    // and what is deliberately not is one definition, in composeRunnerBlock.js,
+    // and the generator renders from that same definition.
+    const reference = blockLines(readReferencedFile({ from: row.from, workspaceRoot }), row.block);
+    if (reference.length === 0) {
+      throw new Error(`[ManifestFiles] Reference block "${row.block}" not found in ${referenceOwner(row.from)} - `
+        + 'the template is the reference bearer of this row and carries no such block. '
+        + 'Fix: restore the block in the template, or correct the row.');
+    }
+
+    // Who this repository is, as it declares it. NOT the directory name: inside
+    // the image the row now runs in, every service lies in `/app`
+    // (`serviceIdentity.js`).
+    const identity = readIdentity(serviceRoot);
+    if (identity.problem !== undefined) {
+      if (identity.undecided !== null) {
+        say(`the "${row.block}" block could not be compared — ${identity.undecided}`, IDENTITY_FILE);
+      }
+      return findings;
+    }
+
+    const [containerName] = others[0];
+    const serviceName = identity.params.service_name;
+    const mine = blockLines(text, row.block);
+
+    if (mine.length === 0) {
+      say(`carries no "${row.block}" block — the template ships one and every ${row.path} repeats it, `
+        + 'apart from what the runner shares with its service');
+      return findings;
+    }
+
+    const difference = firstDifference(
+      normalizeRunnerBlock({ lines: mine, containerName, serviceName }),
+      normalizeRunnerBlock({ lines: reference, containerName: CONTAINER_PLACEHOLDER, serviceName: SERVICE_PLACEHOLDER })
+    );
+    if (difference !== null) {
+      say(`the "${row.block}" block differs from the template at block line ${difference.line}: `
+        + `"${difference.text}" (compared without ${SHARED_DECLARATIONS.join(', ')}, which the rows above `
+        + 'compare against the service this runner tests)');
+    }
+
+    return findings;
+  }
+});
+
+/**
+ * A document's level-2 headings, in file order — the shape of a document, with
+ * none of its prose in it.
+ *
+ * Level 2 and no deeper on purpose: `##` is the section an operator navigates
+ * by, and the template's own `###` sub-headings are the way ONE service happens
+ * to have written a section. A rule that demanded those would be prescribing
+ * prose, which the `generated` class explicitly does not do (confirmation
+ * `biz-service-manifest` 001 §2: `skeleton_only` compares headings and required
+ * sections, not prose).
+ *
+ * @param {string} text the document
+ * @returns {string[]}
+ */
+function headingsOf(text) {
+  return text.split('\n')
+    .filter((line) => /^## +\S/.test(line))
+    .map((line) => line.replace(/^##\s+/, '').trim());
+}
+
+/**
+ * The reference document with this repository's parameters in it.
+ *
+ * The parameters are the repository's DECLARED identity (`serviceIdentity.js`);
+ * a repository that cannot say who it is gets the fail-fast that module writes,
+ * which is what a generator run must see. The check below asks the same question
+ * without throwing, because a run reports every row before it stops.
+ *
+ * @param {{row: object, serviceRoot: string, workspaceRoot: string}} args
+ * @returns {string}
+ */
+function renderedReference({ row, serviceRoot, workspaceRoot }) {
+  return renderText(readReferencedFile({ from: row.from, workspaceRoot }), requireIdentity(serviceRoot));
+}
+
+/**
+ * The skeleton of a document: its header, its title and its sections — and not
+ * one sentence of what any of them says.
+ *
+ * This is what the generator CREATES a missing installation document from. It
+ * deliberately writes no prose: what this service's installation actually
+ * requires is the service's own fact, and a generated paragraph describing a
+ * different service is exactly the sentence nobody re-derives
+ * (`.claude/rules/doc-code-binding.md` §1).
+ *
+ * @param {string} reference the rendered reference document
+ * @returns {string}
+ */
+function skeletonOf(reference) {
+  const lines = reference.split('\n');
+  const titleAt = lines.findIndex((line) => /^# +\S/.test(line));
+  if (titleAt === -1) {
+    throw new Error('[ManifestFiles] Reference document has no title - a skeleton is its header, its title '
+      + 'and its sections, and this document declares no "# " line. '
+      + 'Fix: restore the title in the template document.');
+  }
+
+  const header = lines.slice(0, titleAt).filter((line) => line.trim() !== '');
+  const sections = headingsOf(reference)
+    .map((heading) => `## ${heading}\n\nTODO — this section is this service's own.`)
+    .join('\n\n');
+  return `${[...header, '', lines[titleAt], '', sections].join('\n')}\n`;
+}
+
+const templateSkeleton = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path', 'from', 'skeleton_only']),
+
+  ...READS_ITS_REFERENCE_ONLY,
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const text = readServiceFile(serviceRoot, row.path);
+
+    // An absent document is NOT this row's finding. The installation contract
+    // raises SETUP_DOCS for exactly that, and `G-SETUP` puts it on the table
+    // with its own fix; saying it twice would give one defect two owners
+    // (`.claude/rules/change-discipline.md` § One rail per concern).
+    if (text === null) return [];
+
+    // The document is rendered for THIS repository, so it cannot be compared
+    // before the repository has said who it is (`serviceIdentity.js`).
+    const identity = readIdentity(serviceRoot);
+    if (identity.problem !== undefined) {
+      if (identity.undecided === null) return [];
+      return [{
+        where: whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: IDENTITY_FILE }),
+        what: `the sections of ${row.path} could not be compared — ${identity.undecided}`
+      }];
+    }
+
+    const reference = renderedReference({ row, serviceRoot, workspaceRoot });
+    const missing = headingsOf(reference).filter((heading) => !headingsOf(text).includes(heading));
+    if (missing.length === 0) return [];
+
+    return [{
+      where,
+      what: `has no section ${missing.map((heading) => `"${heading}"`).join(', ')} — `
+        + `${referenceOwner(row.from)} declares it and an operator installs from these headings`
+    }];
+  }
+});
+
+
+/** The block a sync writes the platform's ignore entries into, so a reader can tell them apart. */
+const IGNORE_BLOCK = 'oa-ignore v1';
+
+/**
+ * The entries a `.gitignore`-shaped file DECLARES: every non-blank line that is
+ * not a comment, trimmed. Order is not read, and neither are the comments — a
+ * repository groups its own lines however it likes.
+ *
+ * @param {string} text the file
+ * @returns {string[]} in the order they appear, duplicates kept out
+ */
+function ignoreEntries(text) {
+  const seen = [];
+  for (const line of text.split('\n')) {
+    const entry = line.trim();
+    if (entry === '' || entry.startsWith('#')) continue;
+    if (!seen.includes(entry)) seen.push(entry);
+  }
+  return seen;
+}
+
+/**
+ * The file with the generated block taken out, markers included. What is left is
+ * the repository's own — which is the half a sync never rewrites.
+ *
+ * @param {string} text the file
+ * @param {string} name the block name
+ * @returns {string}
+ */
+function withoutBlock(text, name) {
+  const block = blockLines(text, name);
+  if (block.length === 0) return text;
+  const lines = text.split('\n');
+  const start = lines.indexOf(block[0]);
+  const kept = [...lines.slice(0, start), ...lines.slice(start + block.length)];
+  return kept.join('\n').replace(/\n{3,}$/, '\n');
+}
+
+/** The block a sync writes the platform's build-context exclusions into. */
+const DOCKERIGNORE_BLOCK = 'oa-dockerignore v1';
+
+/**
+ * The one exclusion `.gitignore` cannot declare, because git never has to say it
+ * about itself: `.git`. Without it a LOCAL production build copies the whole
+ * history into the image, and the image stops being what a clean checkout would
+ * have produced — which is the criterion the whole row is measured by.
+ */
+const DOCKER_IMPLICIT = Object.freeze(['.git']);
+
+/**
+ * The exclusions a `.dockerignore` must carry, DERIVED from the very declaration
+ * the `.gitignore` row reads. One list, two consumers
+ * (`.claude/rules/change-discipline.md` § One rail per concern): a second
+ * hand-written list is the drift this row exists to prevent.
+ *
+ * The translation is not a copy, because the two formats do not mean the same
+ * thing by the same line. A `.gitignore` pattern with no slash matches at EVERY
+ * depth; a `.dockerignore` pattern is matched against the path from the context
+ * root, so `*.log` there catches `debug.log` and not `logs/debug.log`. Measured
+ * by BIZ-hello on 2026-09-11: a local production image of hello came to 6.6 GB,
+ * 5.2 GB of it `logs/`, and carried `config/env-active/*.env` with DB_PASSWORD,
+ * JWT_SECRET, the MinIO keys and RABBITMQ_URL. So every slash-less entry is
+ * emitted in both shapes, and an entry that already carries a slash is anchored
+ * in both formats alike and travels unchanged.
+ *
+ * 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.
+ *
+ * @param {string} gitignoreText the declaration both rows read
+ * @returns {string[]}
+ */
+function dockerignoreEntries(gitignoreText) {
+  const entries = [];
+  const add = (entry) => { if (!entries.includes(entry)) entries.push(entry); };
+
+  for (const declared of ignoreEntries(gitignoreText)) {
+    const negated = declared.startsWith('!');
+    const pattern = (negated ? declared.slice(1) : declared).replace(/\/+$/, '');
+    if (pattern === '') continue;
+    const mark = (value) => (negated ? `!${value}` : value);
+
+    add(mark(pattern));
+    if (!pattern.includes('/')) add(mark(`**/${pattern}`));
+  }
+
+  for (const entry of DOCKER_IMPLICIT) add(entry);
+  return entries;
+}
+
+/**
+ * The `contains` class: a file whose platform ENTRIES must all be there, and
+ * whose every other line is the repository's own.
+ *
+ * The class exists because `.gitignore` is neither of the other two. It cannot
+ * be `identical` — a repository ignores its own scratch directories, and
+ * measured 2026-09-10 the eight services carry nine different files. It is not
+ * `generated` either — nothing renders it from a declaration. What must be true
+ * of it is a SET: every path the platform WRITES into a repository is a path git
+ * must not see. `ci/deployability.json` is the measured case — `oa-validate` and
+ * the pre-push hook of confirmation 006 both write it, and in four of the eight
+ * repositories every run left it untracked.
+ *
+ * A narrower pattern does not satisfy the entry it narrows, and that is not
+ * pedantry: `config/env-active/*.env` (property's line) leaves every non-`.env`
+ * file in a directory of live secrets committable.
+ */
+const templateEntries = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path']),
+  ...READS_ITS_REFERENCE_ONLY,
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const reference = ignoreEntries(readReferencedFile({ from: row.from, workspaceRoot }));
+    const text = readServiceFile(serviceRoot, row.path);
+
+    // ONE finding, not one per entry: the repository has no such file, and the
+    // fix is the same single command whichever entry a reader looks at.
+    if (text === null) {
+      return [{
+        where,
+        what: `the repository carries no ${row.path} — every path this platform writes into it `
+          + `(${reference.join(', ')}) is committable`
+      }];
+    }
+
+    const declared = ignoreEntries(text);
+    return reference
+      .filter((entry) => !declared.includes(entry))
+      .map((entry) => ({
+        where,
+        what: `does not ignore ${JSON.stringify(entry)}, which ${referenceOwner(row.from)} declares — `
+          + 'a path this platform writes into the repository, so every run leaves it in git status'
+      }));
+  }
+});
+
+/**
+ * `F-DOCKERIGNORE` — what a LOCAL production build must not copy into the image.
+ *
+ * The same `contains` shape as `F-GITIGNORE`, over the same declaration, and for
+ * the same reason one step further along: `Dockerfile` line `COPY . .` takes
+ * everything `.dockerignore` does not exclude, and being ignored by git excludes
+ * nothing at all. A CI image is clean by accident — a fresh checkout has no
+ * ignored file to copy — so the defect is invisible exactly where it is built:
+ * on a developer's machine.
+ */
+const dockerignoreEntriesCheck = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path']),
+  ...READS_ITS_REFERENCE_ONLY,
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const reference = dockerignoreEntries(readReferencedFile({ from: row.from, workspaceRoot }));
+    const text = readServiceFile(serviceRoot, row.path);
+
+    if (text === null) {
+      return [{
+        where,
+        what: `the repository carries no ${row.path} — a local production build copies the whole working `
+          + 'tree into the image, live secrets in config/env-active/ and the log directory with them'
+      }];
+    }
+
+    const declared = ignoreEntries(text);
+    return reference
+      .filter((entry) => !declared.includes(entry))
+      .map((entry) => ({
+        where,
+        what: `does not exclude ${JSON.stringify(entry)}, derived from ${referenceOwner(row.from)} — `
+          + 'a local production build copies it into the image, where a clean checkout would not have'
+      }));
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'template-block', check: templateBlock },
+    { name: 'template-file', check: templateFile },
+    { name: 'template-render', check: templateRender },
+    { name: 'delimited-block-render', check: delimitedBlockRender },
+    { name: 'compose-runner', check: composeRunner },
+    { name: 'template-skeleton', check: templateSkeleton },
+    { name: 'template-entries', check: templateEntries },
+    { name: 'dockerignore-entries', check: dockerignoreEntriesCheck }
+  ],
+  blockLines,
+  headingsOf,
+  skeletonOf,
+  renderedReference,
+  ignoreEntries,
+  dockerignoreEntries,
+  withoutBlock,
+  IGNORE_BLOCK,
+  DOCKERIGNORE_BLOCK
+};