@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/manifest/runManifest.js

@@ -0,0 +1,449 @@
+'use strict';
+
+/**
+ * Running the manifest: rows in, findings out.
+ *
+ * Pure module — it reads the repository and returns a structured result. It
+ * renders nothing and exits nothing; `report.js` owns presentation and the CLI
+ * owns the exit code. The same split `deployContract.js` already keeps, and for
+ * the same reason: the boot step of d.212 will call this function, not a CLI.
+ *
+ * Every finding carries the columns confirmation `biz-service-manifest` 001
+ * §3.1 names — `id · severity · where · what · fix · owner` — plus the `doc`
+ * pointer 002 §16.1 requires the message to cite.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { verifyManifestShape, rowNeedsWorkspace } = require('./manifestShape');
+const { collectRows } = require('./walk');
+const { discoverBearers, rootOfPattern } = require('./discovery');
+const { resolveWorkspacePath, canonicalRoot } = require('./workspaceRoot');
+const { CHECK_REGISTRY } = require('./checks');
+
+/** The three scopes, by the name the runner branches on. */
+const SCOPE_SERVICE = 'service';
+const SCOPE_WORKSPACE = 'workspace';
+const SCOPE_BEARER = 'bearer';
+
+/**
+ * The two modes, and why a workspace row is filtered in one of them.
+ *
+ * A `scope: workspace` check looks at the whole workspace, so it can raise a
+ * finding about a directory that is not the service being checked — `U-ORPHAN`
+ * over `api_biz/*` is exactly that. Putting a neighbour's row in this service's
+ * table would give the service a blocker it cannot fix and cannot even see the
+ * cause of, so:
+ *
+ *   - **service mode** (`serviceRoot` given): a workspace row reports only the
+ *     findings whose `where` lies under this service's root. The rest belong to
+ *     their own service's table, and to the workspace run below. A service root
+ *     that is NOT under the given workspace root is the one case where filtering
+ *     would be a lie — every finding would be dropped and the empty table would
+ *     read as "the row looked and found nothing" — so the row is reported NOT
+ *     RUN with that reason instead (`automation-gates.md` §5; lead decision
+ *     2026-09-09).
+ *   - **workspace mode** (no `serviceRoot`, `workspaceRoot` given): every
+ *     workspace row reports in full — that run is the home of those checks —
+ *     and every `scope: service` row is NOT RUN, because there is no repository
+ *     to look in. NOT RUN, never a silent pass (`automation-gates.md` §5).
+ *
+ * Lead decision, `api/shared/TODO.md` §0.2b-8 points 1–2.
+ *
+ * A workspace check therefore reports `where` relative to the WORKSPACE root; a
+ * service check reports it relative to the service root. That is what makes the
+ * filter below meaningful, and it is the one convention a new check must keep.
+ *
+ * **The third scope, `bearer`** (d.223). A row such as `F-JEST` is neither: it
+ * is a fact of ONE service, and it needs the workspace only to read the
+ * template its `from:` reference names. Made `workspace`, it had to answer "no
+ * findings" in workspace mode — there is no service to read — and that answer
+ * is indistinguishable from a clean workspace. Measured over the
+ * `service-workspace` fixture on 2026-09-09: the workspace run printed
+ * `DEPLOYABLE — no findings` while two of its four services violated four of
+ * those rows between them.
+ *
+ * So a `bearer` row runs once per bearer, and which bearers exist is the
+ * manifest's own `discovery` block — the same pattern and the same exclusions
+ * that decide who wears the uniform, never a second walk
+ * (`.claude/rules/change-discipline.md` § One rail per concern):
+ *
+ *   - **service mode**: the one bearer given, exactly as before — the service
+ *     table does not change, and the `where` stays workspace-relative so a
+ *     reader can paste it from either report;
+ *   - **workspace mode**: every discovered bearer, so the run finally IS the
+ *     cross-service list it always claimed to be.
+ *
+ * No filter applies to a `bearer` row: every finding it raises is about the
+ * bearer it was just run against, so there is nothing belonging to a neighbour
+ * to drop.
+ *
+ * **A checkout that does not carry its siblings.** CI checks out `api/` alone,
+ * so `<workspace>/api_biz` is not there at all. A check reading it — `L-CONSUMER`
+ * asks who pins this package, `L-TOOLING` which service carries it, `U-ORPHAN`
+ * which directory nobody declared — then walks an absent directory, gets the
+ * empty set, and reports it as an ANSWER: measured 2026-09-09, `lib-tooling`
+ * gained a blocking `L-CONSUMER` ("pinned by nothing") that is false, and lost
+ * one of its two `L-TOOLING` findings in silence.
+ *
+ * So a check declares the directories it will read, `requiresSiblings({ row,
+ * block })`, and the runner verifies them BEFORE running it; a missing one is
+ * `NOT RUN — sibling root <path> is not present in this checkout`. The runner
+ * owns the judgement because it is one judgement: a check deciding it for
+ * itself would be the same three lines written once per check, and the tenth
+ * check would forget them (`change-discipline.md` § One rail per concern). It
+ * is the same rule `lint-biz-docs --allow-missing-siblings` already follows.
+ *
+ * A `bearer` row in workspace mode inherits the manifest's own discovery roots:
+ * enumerating no bearers because `api_biz` is absent would print "no findings"
+ * for eight services nobody looked at.
+ */
+
+/**
+ * @param {object} params
+ * @param {object} params.manifest parsed manifest (loadManifest)
+ * @param {string|null} [params.serviceRoot] the repository being checked; null = workspace mode
+ * @param {string|null} params.workspaceRoot resolved workspace root, or null
+ * @param {object} [params.checkRegistry] injected registry; defaults to the packaged one
+ * @returns {{ uniform: string, mode: string, serviceRoot: string|null, workspaceRoot: string|null,
+ *             findings: Array<object>, notRun: Array<{id: string, reason: string}>, ok: boolean,
+ *             blockingSeverities: string[], verdict: {blocked: string, clear: string} }}
+ */
+function runManifest({ manifest, serviceRoot = null, workspaceRoot = null, checkRegistry = CHECK_REGISTRY }) {
+  const mode = serviceRoot === null || serviceRoot === undefined ? 'workspace' : 'service';
+
+  if (mode === 'workspace' && workspaceRoot === null) {
+    throw new Error('[Manifest] A run without a service root needs a workspace root - runManifest() got '
+      + 'neither, so it would check nothing. Fix: pass serviceRoot to check one repository, '
+      + 'or workspaceRoot to run the workspace-wide rows.');
+  }
+
+  // Both roots, in one spelling. They arrive by two routes — one derived from
+  // this package's own location, one typed by the caller — and everything below
+  // compares them as strings (`buildScopeFilter`, `outsideWorkspace`,
+  // `path.relative` in every `where`). A symlink in one of the two makes that
+  // comparison answer about the spelling instead of about the directory
+  // (`workspaceRoot.js` § canonicalRoot).
+  const workspace = workspaceRoot === null ? null : canonicalRoot(workspaceRoot);
+
+  let root = null;
+  if (mode === 'service') {
+    if (typeof serviceRoot !== 'string' || serviceRoot.length === 0) {
+      throw new Error('[Manifest] Service root is required - runManifest({ serviceRoot }) got '
+        + `${JSON.stringify(serviceRoot)}. Fix: pass the repository directory to check.`);
+    }
+
+    root = path.resolve(serviceRoot);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+      throw new Error(`[Manifest] Service root not found - ${root}. `
+        + 'Fix: pass an existing repository directory.');
+    }
+    root = canonicalRoot(root);
+  }
+
+  const shape = verifyManifestShape(manifest, { checkRegistry });
+  if (!shape.ok) {
+    const detail = shape.violations.map((v) => `${v.id}: ${v.message}`).join(' | ');
+    const error = new Error(`[Manifest] Manifest failed its own shape check - ${shape.violations.length} `
+      + `violation(s): ${detail} Fix: repair manifests/biz-service.manifest.json.`);
+    error.violations = shape.violations;
+    throw error;
+  }
+
+  const findings = [];
+  const notRun = [];
+
+  const outsideWorkspace = mode === 'service' && workspace !== null
+    && path.relative(workspace, root).startsWith('..');
+  const underServiceRoot = buildScopeFilter({ mode, root, workspaceRoot: workspace });
+
+  const bearers = memoize(() => discoverEveryBearer({ manifest, workspaceRoot: workspace }));
+
+  for (const { row, block } of collectRows(manifest)) {
+    const check = checkRegistry[row.check];
+    const needsWorkspace = rowNeedsWorkspace({ check, row, block });
+
+    if (needsWorkspace && workspace === null) {
+      notRun.push({
+        id: row.id,
+        severity: row.severity,
+        reason: check.describeNotRun
+          ? check.describeNotRun({ row, block })
+          : 'the workspace root is not reachable'
+      });
+      continue;
+    }
+
+    if (needsWorkspace && outsideWorkspace) {
+      notRun.push({
+        id: row.id,
+        severity: row.severity,
+        reason: `service root is outside the workspace root ${workspace}`
+      });
+      continue;
+    }
+
+    if (check.scope === SCOPE_SERVICE && mode === 'workspace') {
+      notRun.push({
+        id: row.id,
+        severity: row.severity,
+        reason: 'the run has no service root — this row is checked inside a service repository'
+      });
+      continue;
+    }
+
+    const missing = missingRoots({
+      roots: requiredRoots({ check, row, block, manifest, mode }),
+      workspaceRoot: workspace
+    });
+    if (missing.length > 0) {
+      notRun.push({ id: row.id, severity: row.severity, reason: describeMissingRoots(missing) });
+      continue;
+    }
+
+    const raised = rowFindings({
+      check, row, block, mode, root, workspaceRoot: workspace, bearers, underServiceRoot
+    });
+
+    // A check may also report that it could not DECIDE the row — not because
+    // the workspace is unreachable (that is judged above, before it runs) but
+    // because the thing it delegates to said so. `docs-lint` is the case: the
+    // linter has its own NOT RUN channel, and a ban whose evidence probe reads a
+    // sibling checkout is undecidable in a run that has none. Reported as a
+    // finding it would be a blocker nobody can clear; dropped it would be a
+    // silent pass. It is the same word every other unanswered row gets
+    // (`.claude/rules/automation-gates.md` §5).
+    if (raised.notRun !== null) {
+      notRun.push({ id: row.id, severity: row.severity, reason: raised.notRun });
+    }
+
+    for (const one of raised.findings) {
+      findings.push({
+        id: row.id,
+        severity: row.severity,
+        where: one.where,
+        what: one.what,
+        fix: row.fix,
+        owner: row.owner,
+        doc: row.doc
+      });
+    }
+  }
+
+  // Which severities stop this bearer is a property of the UNIFORM, not of the
+  // runner: a service raises no `publish` finding and a library no `boot` one,
+  // so a global list made every verdict name severities its uniform cannot
+  // raise (`api/shared/TODO.md` §0.2b-15). The manifest declares it, the shape
+  // check above has already refused a manifest that does not, and the run
+  // carries both the list and the two verdict words so no consumer recomputes
+  // them (`.claude/rules/change-discipline.md` § One rail per concern).
+  const blockingSeverities = manifest.blocking_severities;
+  const blocking = findings.filter((finding) => blockingSeverities.includes(finding.severity));
+
+  const result = {
+    uniform: manifest.uniform,
+    mode,
+    serviceRoot: root,
+    workspaceRoot: workspace,
+    blockingSeverities,
+    verdict: manifest.verdict,
+    findings,
+    notRun,
+    ok: blocking.length === 0
+  };
+
+  // Two different questions, and until d.230 only one of them had an answer:
+  // `ok` says whether anything blocked, over the rows that RAN; `complete` says
+  // whether every row that CAN block was looked at. Inside a service container
+  // the workspace-reading rows cannot run, so a signal is routinely deployable
+  // and incomplete at once — and a deploy gate reading only the first was
+  // taking a `--skip` nobody had flagged (`automation-gates.md` §1.5).
+  return { ...result, complete: incompleteRows(result).length === 0 };
+}
+
+/**
+ * The rows a run did NOT get to, and whose absence matters: the ones whose
+ * severity stops this uniform's bearer. A `warn` row that could not run leaves
+ * the run complete — it could not have stopped anything.
+ *
+ * One owner, two readers: the run itself computes `complete` from it, and
+ * `report.js` names the rows in the sentence a human reads
+ * (`change-discipline.md` § One rail per concern).
+ *
+ * @param {{notRun: Array<{id: string, severity: string}>, blockingSeverities: string[]}} result
+ * @returns {Array<{id: string, severity: string, reason: string}>}
+ */
+function incompleteRows(result) {
+  if (!Array.isArray(result.blockingSeverities) || result.blockingSeverities.length === 0) {
+    throw new Error('[Manifest] The run does not declare its blocking severities - completeness cannot be '
+      + 'judged without them. Fix: pass the value runManifest() returned; it carries blockingSeverities '
+      + 'from the manifest.');
+  }
+  return (result.notRun || []).filter((one) => result.blockingSeverities.includes(one.severity));
+}
+
+/**
+ * Which directories must exist before this row's check can look.
+ *
+ * The check names the ones its own rule reads, derived from the row rather than
+ * restated beside it — `L-CONSUMER` already carries `consumer_patterns`, and a
+ * second list saying "and by the way that means api_biz" is a second owner of
+ * one fact. A workspace-mode `bearer` row adds the manifest's discovery roots,
+ * because enumerating the bearers is how it runs at all.
+ *
+ * @param {{ check: object, row: object, block: object, manifest: object, mode: string }} params
+ * @returns {string[]} workspace-relative directories, no duplicates
+ */
+function requiredRoots({ check, row, block, manifest, mode }) {
+  const declared = check.requiresSiblings ? check.requiresSiblings({ row, block }) : [];
+  const discovery = check.scope === SCOPE_BEARER && mode === 'workspace'
+    ? Object.values(manifest.discovery || {})
+      .filter((entry) => typeof entry.pattern === 'string')
+      .map((entry) => rootOfPattern(entry.pattern))
+    : [];
+
+  return [...new Set([...declared, ...discovery])].filter((relative) => relative.length > 0);
+}
+
+/**
+ * @param {{ roots: string[], workspaceRoot: string|null }} params
+ * @returns {string[]} those of `roots` that are not directories under the workspace
+ */
+function missingRoots({ roots, workspaceRoot }) {
+  if (workspaceRoot === null) return [];
+
+  return roots.filter((relative) => {
+    const target = resolveWorkspacePath(workspaceRoot, relative);
+    return !fs.existsSync(target) || !fs.statSync(target).isDirectory();
+  });
+}
+
+/**
+ * @param {string[]} missing the roots that are not there
+ * @returns {string} the NOT RUN reason, naming every one of them
+ */
+function describeMissingRoots(missing) {
+  return missing.length === 1
+    ? `sibling root ${missing[0]} is not present in this checkout`
+    : `sibling roots ${missing.join(', ')} are not present in this checkout`;
+}
+
+/**
+ * What one check's `run()` returned, in one shape.
+ *
+ * A check returns either an array of findings — which is what almost all of
+ * them do — or `{ findings, notRun }`, where `notRun` is the reason it could not
+ * decide the row at all. The second shape exists for a check that DELEGATES:
+ * `docs-lint` asks a linter which has its own NOT RUN channel, and an answer of
+ * "I could not evaluate this rule" is neither a finding nor a pass.
+ *
+ * @param {Array|object} returned
+ * @returns {{findings: Array<{where: string, what: string}>, notRun: string|null}}
+ */
+function readAnswer(returned) {
+  if (Array.isArray(returned)) return { findings: returned, notRun: null };
+  return {
+    findings: Array.isArray(returned.findings) ? returned.findings : [],
+    notRun: typeof returned.notRun === 'string' && returned.notRun.length > 0 ? returned.notRun : null
+  };
+}
+
+/**
+ * Run one row's check wherever its scope says it belongs, and return what it
+ * raised. The three branches are the three scopes and nothing else — a caller
+ * that had to know which rows are per-bearer would be a second owner of the
+ * vocabulary.
+ *
+ * @param {object} params the check, its row and block, and the run's roots
+ * @returns {{findings: Array<{where: string, what: string}>, notRun: string|null}}
+ */
+function rowFindings({ check, row, block, mode, root, workspaceRoot, bearers, underServiceRoot }) {
+  if (check.scope === SCOPE_WORKSPACE) {
+    const answer = readAnswer(check.run({ row, block, serviceRoot: root, workspaceRoot }));
+    return { ...answer, findings: answer.findings.filter(underServiceRoot) };
+  }
+
+  if (check.scope === SCOPE_BEARER && mode === 'workspace') {
+    // One row, several bearers: the findings add up, and the row is NOT RUN as
+    // soon as ONE bearer could not be decided — the run did not reach every
+    // bearer of it, and saying otherwise is the silence this reports.
+    const answers = bearers().map((bearer) => readAnswer(check.run({
+      row, block, serviceRoot: bearer.dir, workspaceRoot
+    })));
+    const undecided = answers.find((answer) => answer.notRun !== null);
+    return {
+      findings: answers.flatMap((answer) => answer.findings),
+      notRun: undecided === undefined ? null : undecided.notRun
+    };
+  }
+
+  return readAnswer(check.run({ row, block, serviceRoot: root, workspaceRoot }));
+}
+
+/**
+ * Every bearer of this uniform, from the manifest's own discovery blocks.
+ *
+ * A manifest declares one block today, but the shape check allows several and
+ * the runner has no business assuming otherwise; a directory found by two
+ * blocks is one bearer, so the same row is never run against it twice.
+ *
+ * @param {{ manifest: object, workspaceRoot: string|null }} params
+ * @returns {Array<{name: string, relativeDir: string, dir: string, file: string}>}
+ */
+function discoverEveryBearer({ manifest, workspaceRoot }) {
+  if (workspaceRoot === null) return [];
+
+  const seen = new Set();
+  const bearers = [];
+  for (const block of Object.values(manifest.discovery || {})) {
+    for (const bearer of discoverBearers({ block, workspaceRoot }).bearers) {
+      if (seen.has(bearer.dir)) continue;
+      seen.add(bearer.dir);
+      bearers.push(bearer);
+    }
+  }
+  return bearers;
+}
+
+/**
+ * Call `produce` at most once per run. Discovery walks the disk, and four
+ * bearer rows asking for the same list would walk it four times.
+ *
+ * @param {() => *} produce
+ * @returns {() => *}
+ */
+function memoize(produce) {
+  let value;
+  let done = false;
+  return () => {
+    if (!done) {
+      value = produce();
+      done = true;
+    }
+    return value;
+  };
+}
+
+/**
+ * Which findings of a workspace-scoped check belong to THIS run's table.
+ *
+ * @param {{mode: string, root: string|null, workspaceRoot: string|null}} params
+ * @returns {(finding: {where: string}) => boolean}
+ */
+function buildScopeFilter({ mode, root, workspaceRoot }) {
+  // Workspace mode reports every workspace row in full; and with no workspace
+  // root no workspace check runs at all (they are NOT RUN above), so there is
+  // nothing to filter and nothing to resolve a relative path against. A service
+  // root outside the workspace root never reaches here either — those rows are
+  // NOT RUN, not filtered.
+  if (mode === 'workspace' || workspaceRoot === null) return () => true;
+
+  const relative = path.relative(workspaceRoot, root);
+  if (relative === '') return () => true;
+
+  const prefix = relative.split(path.sep).join('/');
+  return (finding) => finding.where === prefix || finding.where.startsWith(`${prefix}/`);
+}
+
+module.exports = { runManifest, incompleteRows };

package/src/manifest/serviceIdentity.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * WHO the repository under check is — read from the file that DECLARES it,
+ * never from the name of the directory it happens to lie in.
+ *
+ * The directory name is a fact of the WORKSPACE. `api_biz/<name>` is what the
+ * discovery pattern walks and what `U-ORPHAN` holds against
+ * `api/config/services.json`; there it is the right answer, and it stays there.
+ * Inside the image built FROM that repository it means nothing at all: the
+ * Dockerfile declares `WORKDIR /app` (`templates/business-service/Dockerfile`),
+ * so every service on the platform is called "app" in the one run d.229 was
+ * about — the production stage, where the rows finally answer because their
+ * reference travels with the package.
+ *
+ * Measured 2026-09-09 over the conforming fixture copied into a directory named
+ * `app`: `F-RUNNER` rendered the template for a service called "app" and
+ * reported a conformant file as drifted, quoting a line the substitution had
+ * mangled ("It __SERVICE_NAME__lies in dev and CI only"), because "app" is a
+ * substring of "applies". The production stage then fails the build of every
+ * conformant service. A directory called `My Service` did worse: the derivation
+ * threw, and `oa-validate` exited 2 with no table at all.
+ *
+ * The one thing INSIDE the repository that says who it is, is
+ * `config/service/config.json` → `service.name`: the identity the platform
+ * registers the service under, and the key row `C-SERVICE` owns. On the eight
+ * live services it reads `biz-<name>`, which is exactly what `deriveParams`
+ * writes into `registry_name`, so the parameters of every rendered row come back
+ * out of it.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §2
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { deriveParams, PLACEHOLDERS, IDENTITY_PARAMS } = require('../sync/serviceTemplate');
+
+/** The file a service declares its platform identity in; row `C-SERVICE` owns it. */
+const IDENTITY_FILE = 'config/service/config.json';
+
+/**
+ * The declared identity, read back into the short name every per-service path is
+ * built from — the exact inverse of what `deriveParams` writes.
+ *
+ * `deriveParams` only ever ADDS the platform prefix (`registry_name =
+ * biz-${name}`), so reading it back means taking that prefix off when it is
+ * there. It is not a rule about how a service must be called: whether
+ * `service.name` has to read `biz-<name>` is a conformance question with no row
+ * behind it today, and this module is not the place a new rule appears as a side
+ * effect (`.claude/rules/truth-over-agreement.md` §6). Measured: the eight live
+ * services all declare `biz-<name>`, and this package's own conformant fixture
+ * declares `v3-cookbook-service`.
+ */
+const REGISTERED_NAME = /^(?:biz-)?([a-z][a-z0-9-]*)$/;
+
+/**
+ * A problem `C-SERVICE` already puts on the table with its own fix. The rendered
+ * rows stay silent about it: one defect, one owner, one fix sentence
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * @param {string} problem what is wrong, as the message says it
+ * @returns {{problem: string, undecided: null}}
+ */
+const alreadyReported = (problem) => ({ problem: message(problem), undecided: null });
+
+/**
+ * The fail-fast message, in the one shape `architecture-principles.md` §5 asks
+ * for. It is what the generator throws: `oa-sync-template` was asked to render
+ * this repository's files and cannot say whose they are.
+ *
+ * @param {string} problem
+ * @returns {string}
+ */
+function message(problem) {
+  return `[ServiceIdentity] ${problem} - every rendered row derives this repository's parameters from it, `
+    + 'and the directory name says nothing inside the image the service is built into (WORKDIR /app). '
+    + `Fix: declare service.name as "biz-<name>" in ${IDENTITY_FILE}.`;
+}
+
+/**
+ * The identity of one repository, or why it cannot be read.
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {{params: object}|{problem: string, undecided: string|null}}
+ *   `undecided` is the clause a row prints when NOTHING else reports the
+ *   problem, and null when `C-SERVICE` already does.
+ */
+function readIdentity(serviceRoot) {
+  const file = path.join(serviceRoot, ...IDENTITY_FILE.split('/'));
+  if (!fs.existsSync(file)) return alreadyReported(`${IDENTITY_FILE} is absent`);
+
+  let declared;
+  try {
+    declared = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    return alreadyReported(`${IDENTITY_FILE} is not valid JSON — ${error.message}`);
+  }
+
+  const name = declared && declared.service ? declared.service.name : undefined;
+  if (typeof name !== 'string' || name.length === 0) {
+    return alreadyReported(`${IDENTITY_FILE} declares no service.name`);
+  }
+
+  // The TEMPLATE is a bearer too, and it declares its identity the only way a
+  // template can: as the placeholder. Rendering it with `IDENTITY_PARAMS`
+  // substitutes every placeholder by itself, which is precisely the claim
+  // confirmation 001 §9 makes about `api/templates/business-service` — so the
+  // rows compare the template against itself and it stays DEPLOYABLE.
+  if (name === PLACEHOLDERS.registry_name) return { params: IDENTITY_PARAMS };
+
+  const registered = REGISTERED_NAME.exec(name);
+  if (registered === null) {
+    // `C-SERVICE` demands a non-empty name and got one, so this is the one
+    // problem no other row would say a word about: the row that needed it says
+    // so itself, rather than reporting a pass it did not measure.
+    return {
+      problem: message(`${IDENTITY_FILE} declares service.name ${JSON.stringify(name)}`),
+      undecided: `service.name is ${JSON.stringify(name)} here, and the short name every rendered row is `
+        + 'built from reads "[biz-]<lower-case letters, digits and hyphens>"'
+    };
+  }
+
+  return { params: deriveParams({ name: registered[1] }) };
+}
+
+/**
+ * The identity, or a fail-fast. What a generator uses: it was asked to write
+ * this repository's files and must not guess whose they are.
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {object} the parameters `renderText` substitutes
+ */
+function requireIdentity(serviceRoot) {
+  const read = readIdentity(serviceRoot);
+  if (read.problem !== undefined) throw new Error(read.problem);
+  return read.params;
+}
+
+module.exports = { IDENTITY_FILE, REGISTERED_NAME, readIdentity, requireIdentity };

package/src/manifest/walk.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * One walk over the manifest tree, used by everything that has to reason about
+ * the whole file: the shape check (which arrays are copied lists?) and the
+ * runner (which rows are there, and what block do they belong to?).
+ *
+ * A row is any object carrying an `id` inside an array of objects. Its BLOCK is
+ * the object that contains that array — the row is the definition, the block
+ * carries the parameters of the concern (a discovery pattern, its `from:`
+ * reference). That split is what lets a future row cite an existing checker
+ * without either side learning about the other.
+ */
+
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * @typedef {object} ManifestArray
+ * @property {string} at dotted path of the array inside the manifest
+ * @property {string} key the key holding it
+ * @property {Array} value the array itself
+ * @property {object} parent the object that holds it (the block)
+ */
+
+/**
+ * @param {object} manifest parsed manifest
+ * @returns {{ arrays: ManifestArray[], scalars: Array<{at: string, key: string, value: *}> }}
+ */
+function walkManifest(manifest) {
+  const arrays = [];
+  const scalars = [];
+
+  const visit = (node, prefix) => {
+    for (const [key, value] of Object.entries(node)) {
+      const at = prefix ? `${prefix}.${key}` : key;
+      if (Array.isArray(value)) {
+        arrays.push({ at, key, value, parent: node });
+        value.forEach((element, index) => {
+          if (isPlainObject(element)) visit(element, `${at}[${index}]`);
+        });
+      } else if (isPlainObject(value)) {
+        visit(value, at);
+      } else {
+        scalars.push({ at, key, value });
+      }
+    }
+  };
+
+  visit(manifest, '');
+  return { arrays, scalars };
+}
+
+/**
+ * Every row in the manifest, in file order, with the block it belongs to.
+ *
+ * @param {object} manifest parsed manifest
+ * @returns {Array<{ row: object, block: object, at: string }>}
+ */
+function collectRows(manifest) {
+  const { arrays } = walkManifest(manifest);
+  const rows = [];
+
+  for (const entry of arrays) {
+    if (entry.value.length === 0) continue;
+    if (!entry.value.every((element) => isPlainObject(element) && 'id' in element)) continue;
+    entry.value.forEach((row, index) => {
+      rows.push({ row, block: entry.parent, at: `${entry.at}[${index}]` });
+    });
+  }
+
+  return rows;
+}
+
+module.exports = { walkManifest, collectRows, isPlainObject };