@onlineapps/conn-orch-validator 6.0.1 → 8.0.0

package/src/manifest/manifestShape.js

@@ -0,0 +1,446 @@
+'use strict';
+
+/**
+ * The manifest's test on itself.
+ *
+ * Confirmation `biz-service-manifest` 004:
+ *   - a row may carry only facts the manifest owns — categories, duties, row
+ *     ids, severities, `fix` commands, discovery patterns, `doc` pointers;
+ *   - every other fact is a `from:` reference to the file that owns it;
+ *   - bearers are discovered, never enumerated;
+ *   - the version of the manifest is the validator pin, never a field;
+ *   - point 5: every array of names is either a row/category definition or a
+ *     `from:` reference — a copied list cannot be committed.
+ * 002 §16.1: a row without `doc` is a finding of the manifest itself.
+ *
+ * The result is data, not a throw: `manifestShape.test.js` asserts the exact
+ * violations, and `runManifest` turns them into a fail-fast error.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-004
+ */
+
+const { walkManifest, collectRows, isPlainObject } = require('./walk');
+
+/**
+ * The consequences a row may carry, and no others. `boot` and `deploy` are the
+ * service uniform's (001 §4); `publish` is the library uniform's — a library has
+ * no boot, and the choke point nothing reaches a service past is
+ * `scripts/publish-library.sh` (002 §10).
+ */
+const SEVERITIES = Object.freeze(['boot', 'deploy', 'publish', 'warn']);
+
+/** The one severity that stops nothing: it is printed in the table and nowhere else. */
+const WARN_SEVERITY = 'warn';
+
+/** Which severities a uniform may declare as blocking — every consequence except `warn`. */
+const BLOCKING_CANDIDATES = Object.freeze(SEVERITIES.filter((severity) => severity !== WARN_SEVERITY));
+
+/**
+ * The three sentences every verdict is printed with, whichever uniform prints
+ * it: the word for a run something blocked, the word for a clear one, and — the
+ * third since d.230 — what a clear run says when it could not look at every row
+ * that CAN block. That last one is a sentence rather than a word because it
+ * names a count and a list, so it carries the two placeholders below.
+ *
+ * It belongs to the uniform for the same reason the first two do: a service
+ * skips `deploy` rows and a library `publish` ones, and the renderer knows
+ * neither word (`api/shared/TODO.md` §0.2b-15).
+ */
+const VERDICT_WORDS = Object.freeze(['blocked', 'clear', 'incomplete']);
+
+/** What the `incomplete` sentence must be able to say: how many rows, and which. */
+const VERDICT_PLACEHOLDERS = Object.freeze(['{count}', '{ids}']);
+
+/** Every row states these, whatever its check. */
+const REQUIRED_ROW_FIELDS = Object.freeze(['id', 'check', 'severity', 'owner', 'fix', 'doc']);
+
+/**
+ * What a check needs in order to look, and therefore where it runs. Three
+ * words, because there are three genuinely different needs — and the third one
+ * was missing until d.223, with a measured cost.
+ *
+ *   - `service`   — the bearer's own root is enough. Inside a container that is
+ *                   all there is, and these rows are the ones that still work
+ *                   there.
+ *   - `workspace` — the check reports ABOUT the workspace: `U-ORPHAN` names a
+ *                   directory that is nobody's service. It has no bearer, so a
+ *                   run without a service root is its HOME, not its handicap.
+ *   - `bearer`    — the check reports about ONE bearer, and needs the workspace
+ *                   only to READ the file its `from:` reference names (the
+ *                   template, `config/shared-env.json`, `api/.nvmrc`). It runs
+ *                   once per bearer: for the one given in service mode, for
+ *                   every discovered one in workspace mode.
+ *
+ * Before the third word existed, `F-INIT`, `F-JEST`, `G-SHARED-ENV`, `R-NODE`,
+ * `L-ENGINES` and `L-PINS` had to borrow `workspace`, whose contract is "there
+ * is no service to read" — so each of them opened with `if (serviceRoot ===
+ * null) return []` and the workspace run printed "no findings" over a workspace
+ * with five real violations in it (measured over the `service-workspace`
+ * fixture, 2026-09-09). A silent pass is the false guarantee of
+ * `automation-gates.md` §5, and it came from a vocabulary that could not say
+ * what those rows needed.
+ */
+const CHECK_SCOPES = Object.freeze(['service', 'workspace', 'bearer']);
+
+/** The scopes whose check cannot look without the workspace root resolved. */
+const WORKSPACE_DEPENDENT_SCOPES = Object.freeze(['workspace', 'bearer']);
+
+/**
+ * Whether THIS row can be answered without the workspace.
+ *
+ * The scope says it for most rows: a `workspace` check reports about the
+ * workspace, and a `bearer` check needs it to READ the file its `from:`
+ * reference names. But which file that is, is the row's business, and since
+ * d.229 a row may reference a file this package carries itself
+ * (`manifestShape.js` § describeFromProblem, the fourth shape). Such a row needs
+ * no workspace at all: the reference travels with the pin.
+ *
+ * The check answers, because the check is what reads — a rule written here
+ * would have to know which rows reference what, which is the manifest's fact,
+ * not the runner's (`change-discipline.md` § One rail per concern). A check that
+ * does not answer keeps the scope's default, so nothing had to change for the
+ * rows whose reference is still a workspace file (`R-NODE` reads `api/.nvmrc`)
+ * or which read the workspace for something other than a reference (the `D-*`
+ * rows run the documentation lint out of `api/scripts`).
+ *
+ * @param {{check: object, row: object, block: object}} params
+ * @returns {boolean}
+ */
+function rowNeedsWorkspace({ check, row, block }) {
+  if (!WORKSPACE_DEPENDENT_SCOPES.includes(check.scope)) return false;
+  return check.needsWorkspace ? check.needsWorkspace({ row, block }) : true;
+}
+
+/**
+ * The only keys under which an array of strings is a fact the manifest OWNS
+ * (004 point 1: categories, duties, discovery patterns). An array of strings
+ * anywhere else is a copied list, whoever wrote it and however true it is today.
+ *
+ *   - `exclude`, `consumer_patterns` — discovery patterns;
+ *   - `may_depend_on` — the category graph, which is the duty itself;
+ *   - `forbidden_packages` — the packages a duty forbids by name. These have no
+ *     SSOT in this repository to reference: the rule is prose
+ *     (`api/.claude/rules/package-management.md` § Storage Architecture) and the
+ *     row is its only machine-readable form;
+ *   - `blocking_severities` — which consequences stop this uniform's bearer. The
+ *     uniform is the only thing that knows: a service raises no `publish`
+ *     finding and a library no `boot` one;
+ *   - `allowed` — the paths a duty exempts, each either a directory prefix
+ *     ending in `/` or one file. The duty IS the exemption, so nothing else owns
+ *     the list.
+ */
+const OWNED_STRING_ARRAY_KEYS = Object.freeze([
+  'exclude',
+  'may_depend_on',
+  'consumer_patterns',
+  'forbidden_packages',
+  'blocking_severities',
+  'allowed'
+]);
+
+/** A version written into the manifest would be a second owner of the pin (004 point 2). */
+const VERSION_KEY = /^(manifest_)?version$/;
+
+/** The `applies_to` value that means every bearer of the uniform. */
+const ALL_CATEGORIES = '*';
+
+/**
+ * The four shapes a `from:` reference may take.
+ *
+ * The first three point OUT of this package, at files owned by other concerns
+ * that are not going to be rewritten for the manifest:
+ *
+ *   - `{ path, list, key }`           an array of objects (api/config/services.json)
+ *   - `{ path, list, names: "keys" }` an object map (api/config/libraries.json)
+ *   - `{ path, text: true }`          the whole file as one value (api/.nvmrc)
+ *
+ * The fourth points INTO it:
+ *
+ *   - `{ package, text: true }`       a file this package carries itself
+ *                                     (templates/business-service/jest.config.js)
+ *
+ * It exists because for some facts the owner IS this package. The template moved
+ * inside it in d.215a — `api/templates/business-service` is the generator's
+ * OUTPUT, committed for reading (001 §5) — so a row referencing that directory
+ * referenced the output rather than the owner, which 004 point 2 forbids. The
+ * practical consequence was measured on 2026-09-09: inside a service container
+ * and in the service's own CI there is no workspace, so every row whose
+ * reference was `api/templates/…` reported NOT RUN — precisely the rows the
+ * uniform exists for. A packaged reference travels with the pin, so those rows
+ * run wherever the package is installed.
+ *
+ * A reference names one owner: `path` or `package`, never both.
+ *
+ * @param {*} from the reference as written
+ * @returns {string|null} what is wrong with it, or null when it is usable
+ */
+function describeFromProblem(from) {
+  if (!isPlainObject(from)) return 'it is not an object.';
+
+  const packaged = typeof from.package === 'string' && from.package.length > 0;
+  if (packaged && typeof from.path === 'string') {
+    return 'it names both a workspace "path" and a "package" file, so the fact would have two owners.';
+  }
+  if (packaged) {
+    return from.text === true
+      ? null
+      : 'it names a "package" file without text: true — a file this package carries is read whole.';
+  }
+
+  if (typeof from.path !== 'string' || from.path.length === 0) {
+    return 'it names neither a workspace "path" nor a "package" file.';
+  }
+  if (from.text === true) return null;
+  if (typeof from.list !== 'string' || from.list.length === 0) {
+    return 'it names no "list", and is not a { path, text: true } reference.';
+  }
+  if (from.names === 'keys') return null;
+  if (typeof from.key === 'string' && from.key.length > 0) return null;
+  return 'it names a "list" but neither a "key" (array of objects) nor names: "keys" (object map).';
+}
+
+/**
+ * Every category any discovery block of this manifest defines.
+ *
+ * @param {object} manifest parsed manifest
+ * @returns {Set<string>}
+ */
+function collectCategories(manifest) {
+  const names = new Set();
+  for (const block of Object.values(manifest.discovery || {})) {
+    for (const category of Object.keys(block.categories || {})) names.add(category);
+  }
+  return names;
+}
+
+
+/**
+ * The consequence of the uniform, which only the uniform knows.
+ *
+ * `boot` and `deploy` stop a service; `publish` stops a library (002 §10). A
+ * single global list made every verdict name all three, so a service run offered
+ * `publish` as a reason it was not deployable — a consequence no service row can
+ * raise (`api/shared/TODO.md` §0.2b-15). The severities and the two words the
+ * verdict is printed with are therefore declared by the manifest, and required
+ * here: a manifest that does not say what stops its bearer cannot be run at all.
+ *
+ * @param {object} manifest parsed manifest
+ * @param {(id: string, message: string) => void} add collector of violations
+ * @returns {void}
+ */
+function verifyConsequence(manifest, add) {
+  const blocking = manifest.blocking_severities;
+  if (!Array.isArray(blocking) || blocking.length === 0) {
+    add('M-BLOCKING', 'The manifest does not declare "blocking_severities". '
+      + `Fix: state which severities stop this uniform's bearer, e.g. ["boot", "deploy"] for a service `
+      + 'and ["publish"] for a library (confirmation biz-service-manifest 001 §4, 002 §10).');
+  } else {
+    const unusable = blocking.filter((severity) => !BLOCKING_CANDIDATES.includes(severity));
+    if (unusable.length > 0) {
+      add('M-BLOCKING', `"blocking_severities" names ${unusable.join(', ')}. `
+        + `Fix: use one or more of ${BLOCKING_CANDIDATES.join(', ')} — "${WARN_SEVERITY}" is table-only and `
+        + 'stops nothing (confirmation biz-service-manifest 001 §4).');
+    }
+  }
+
+  const verdict = manifest.verdict;
+  if (!isPlainObject(verdict)) {
+    add('M-VERDICT', 'The manifest does not declare "verdict". '
+      + 'Fix: state the two words this uniform is judged with, e.g. '
+      + '{ "blocked": "NOT DEPLOYABLE", "clear": "DEPLOYABLE" } — the word belongs to the uniform, '
+      + 'never to an if in the renderer.');
+    return;
+  }
+
+  const missing = VERDICT_WORDS.filter((word) => typeof verdict[word] !== 'string' || verdict[word].length === 0);
+  if (missing.length > 0) {
+    add('M-VERDICT', `"verdict" is missing: ${missing.join(', ')}. `
+      + `Fix: every uniform states all three — ${VERDICT_WORDS.join(', ')}; "incomplete" is the sentence a `
+      + 'clear run adds when a row that can block it did not run (d.230).');
+    return;
+  }
+
+  const withoutPlaceholder = VERDICT_PLACEHOLDERS.filter((token) => !verdict.incomplete.includes(token));
+  if (withoutPlaceholder.length > 0) {
+    add('M-VERDICT', `"verdict"."incomplete" carries no ${withoutPlaceholder.join(', ')}. `
+      + 'Fix: the sentence names HOW MANY rows did not run and WHICH — a reader who cannot see the ids '
+      + 'cannot run the missing half.');
+  }
+}
+
+/**
+ * @param {object} manifest parsed manifest
+ * @param {{ checkRegistry: object }} deps the registered checks, injected
+ * @returns {{ ok: boolean, violations: Array<{id: string, message: string}>, rowIds: string[] }}
+ */
+function verifyManifestShape(manifest, { checkRegistry } = {}) {
+  if (!isPlainObject(manifest)) {
+    throw new Error('[ManifestShape] Manifest object is required - verifyManifestShape(manifest, deps) '
+      + `got ${JSON.stringify(manifest)}. Fix: pass the result of loadManifest().`);
+  }
+  if (!isPlainObject(checkRegistry)) {
+    throw new Error('[ManifestShape] Check registry is required - verifyManifestShape(manifest, { checkRegistry }) '
+      + 'got none. Fix: pass CHECK_REGISTRY from src/manifest/checks.');
+  }
+
+  const violations = [];
+  const add = (id, message) => violations.push({ id, message });
+
+  const { arrays, scalars } = walkManifest(manifest);
+
+  for (const scalar of scalars) {
+    if (VERSION_KEY.test(scalar.key)) {
+      add('M-VERSION', `"${scalar.at}" states a version. The manifest version IS the validator pin `
+        + '(SSOT api/config/libraries.json, gate R6). Fix: remove the field.');
+    }
+  }
+
+  for (const entry of arrays) {
+    const rowArray = entry.value.length > 0
+      && entry.value.every((element) => isPlainObject(element) && 'id' in element);
+    if (rowArray) continue;
+
+    const objectArray = entry.value.length > 0 && entry.value.every(isPlainObject);
+    if (objectArray) {
+      add('M-ROW-FIELD', `"${entry.at}" is an array of objects that are not rows — an element has no "id". `
+        + 'Fix: give every row an id, or move the data to the file that owns it and reference it with "from".');
+      continue;
+    }
+
+    if (OWNED_STRING_ARRAY_KEYS.includes(entry.key) && entry.value.every((e) => typeof e === 'string')) {
+      continue;
+    }
+
+    add('M-COPY', `"${entry.at}" is a list of names the manifest does not own. `
+      + 'Fix: replace it with a "from" reference to the file that owns the list, or make it a row definition.');
+  }
+
+  verifyConsequence(manifest, add);
+
+  const rows = collectRows(manifest);
+  const seen = new Map();
+
+  for (const { row, at } of rows) {
+    const missing = REQUIRED_ROW_FIELDS.filter((field) => typeof row[field] !== 'string' || row[field].length === 0);
+    if (missing.length > 0) {
+      add('M-ROW-FIELD', `Row ${row.id || at} is missing: ${missing.join(', ')}. `
+        + `Fix: every row states ${REQUIRED_ROW_FIELDS.join(', ')} — "doc" is where its "why" lives.`);
+      continue;
+    }
+
+    if (seen.has(row.id)) {
+      add('M-ROW-ID', `Row id ${row.id} is used twice (${seen.get(row.id)} and ${at}). `
+        + 'Fix: a finding is named by its row; give the second row its own id.');
+    }
+    seen.set(row.id, at);
+
+    if (!SEVERITIES.includes(row.severity)) {
+      add('M-SEVERITY', `Row ${row.id} has severity "${row.severity}". `
+        + `Fix: use one of ${SEVERITIES.join(', ')} (confirmation biz-service-manifest 001 §4).`);
+      continue;
+    }
+
+    const check = checkRegistry[row.check];
+    if (!check) {
+      add('M-CHECK', `Row ${row.id} names check "${row.check}", which nothing registers. `
+        + `Fix: register it in src/manifest/checks, or use one of: ${Object.keys(checkRegistry).join(', ')}.`);
+      continue;
+    }
+
+    if (!CHECK_SCOPES.includes(check.scope)) {
+      add('M-SCOPE', `Row ${row.id} names check "${row.check}", which declares scope `
+        + `${JSON.stringify(check.scope)}. `
+        + `Fix: a check declares one of ${CHECK_SCOPES.join(', ')} — the runner decides where to run it `
+        + 'from that word alone, and an unknown one would run nowhere and say nothing.');
+      continue;
+    }
+
+    const missingParams = (check.requires || []).filter((param) => row[param] === undefined);
+    if (missingParams.length > 0) {
+      add('M-PARAM', `Row ${row.id} does not give check "${row.check}" its parameters: ${missingParams.join(', ')}. `
+        + 'Fix: add them to the row.');
+    }
+  }
+
+  for (const { row, at } of rows) {
+    if (row.from === undefined) continue;
+    const problem = describeFromProblem(row.from);
+    if (problem !== null) add('M-FROM', `Row ${row.id || at} has an unusable "from" reference — ${problem} `
+      + 'Fix: reference the file that owns the fact; the manifest never copies it.');
+  }
+
+  const categories = collectCategories(manifest);
+
+  for (const [name, block] of Object.entries(manifest.discovery || {})) {
+    if (typeof block.pattern !== 'string' || block.pattern.length === 0) {
+      add('M-DISCOVERY', `Discovery block "${name}" has no "pattern". `
+        + 'Fix: bearers are discovered, never enumerated — state the pattern that finds them.');
+    }
+    const problem = describeFromProblem(block.from);
+    if (problem !== null) {
+      add('M-DISCOVERY', `Discovery block "${name}" has no usable "from" reference — ${problem} `
+        + 'Fix: name the file that owns the list of bearers; the manifest never copies it.');
+    }
+
+    for (const [category, definition] of Object.entries(block.categories || {})) {
+      const missing = ['layer', 'concern', 'doc'].filter((field) => typeof definition[field] !== 'string');
+      if (missing.length > 0) {
+        add('M-CATEGORY', `Category "${category}" is missing: ${missing.join(', ')}. `
+          + 'Fix: a category states which layer it is, what it is for, and where its why lives.');
+      }
+      if (!Array.isArray(definition.may_depend_on)) {
+        add('M-CATEGORY', `Category "${category}" has no "may_depend_on" list. `
+          + 'Fix: state the categories it may depend on — an empty list is a decision, an absent one is not.');
+        continue;
+      }
+      for (const target of definition.may_depend_on) {
+        if (!categories.has(target)) {
+          add('M-CATEGORY', `Category "${category}" may_depend_on "${target}", which this manifest does not define. `
+            + `Fix: use one of ${[...categories].join(', ')}.`);
+        }
+      }
+    }
+  }
+
+  for (const [name, block] of Object.entries(manifest.duties || {})) {
+    const target = block.applies_to;
+    if (target === ALL_CATEGORIES) continue;
+    if (typeof target !== 'string' || !categories.has(target)) {
+      add('M-DUTY', `Duty section "${name}" applies_to ${JSON.stringify(target)}, which is neither `
+        + `"${ALL_CATEGORIES}" nor a defined category. Fix: use one of ${[...categories].join(', ')}.`);
+    }
+  }
+
+  for (const [id, entry] of Object.entries(manifest.guidance || {})) {
+    if (!isPlainObject(entry)) {
+      add('M-GUIDANCE', `Guidance "${id}" is not an object. Fix: state why it is not a row, and where its why lives.`);
+      continue;
+    }
+    const missing = ['why', 'doc'].filter((field) => typeof entry[field] !== 'string' || entry[field].length === 0);
+    if (missing.length > 0) {
+      add('M-GUIDANCE', `Guidance "${id}" is missing: ${missing.join(', ')}. `
+        + 'Fix: guidance says WHY there is no row and points at the decision — that is the whole of it.');
+    }
+    if (entry.check !== undefined || entry.severity !== undefined) {
+      add('M-GUIDANCE', `Guidance "${id}" carries "check" or "severity". `
+        + 'Fix: guidance never produces a finding; if it can be decided, make it a row.');
+    }
+  }
+
+  return { ok: violations.length === 0, violations, rowIds: rows.map(({ row }) => row.id) };
+}
+
+module.exports = {
+  verifyManifestShape,
+  rowNeedsWorkspace,
+  describeFromProblem,
+  SEVERITIES,
+  CHECK_SCOPES,
+  WORKSPACE_DEPENDENT_SCOPES,
+  BLOCKING_CANDIDATES,
+  VERDICT_WORDS,
+  VERDICT_PLACEHOLDERS,
+  REQUIRED_ROW_FIELDS,
+  OWNED_STRING_ARRAY_KEYS,
+  ALL_CATEGORIES
+};

package/src/manifest/report.js

@@ -0,0 +1,245 @@
+'use strict';
+
+/**
+ * Presentation of a manifest run: the table a human reads and the JSON a gate
+ * reads. One table, the columns confirmation `biz-service-manifest` 001 §3.1
+ * fixes: `id · severity · where · what · fix · owner`.
+ *
+ * Two things this module refuses to hide:
+ *   - the `doc` pointer of every reported row, so the reader reaches the *why*
+ *     without asking anybody (002 §16.1);
+ *   - a row that did NOT run, printed above the table. A check that could not
+ *     look is never silence and never a pass (`automation-gates.md` §5).
+ */
+
+const { incompleteRows } = require('./runManifest');
+
+const COLUMNS = Object.freeze(['id', 'severity', 'where', 'what', 'fix', 'owner']);
+
+/**
+ * The blocking findings of a run, judged by the severities THIS run's uniform
+ * declared. Nothing here knows which those are — a service has no `publish` row
+ * and a library no `boot` one, so a constant in this module would print a
+ * consequence the uniform cannot raise (`api/shared/TODO.md` §0.2b-15).
+ *
+ * A result that does not carry them is named, never guessed at
+ * (`.claude/rules/architecture-principles.md` §3, §5).
+ *
+ * @param {object} result the value `runManifest` returned
+ * @returns {object[]} the findings whose severity stops the bearer
+ */
+function blockingOf(result) {
+  if (!Array.isArray(result.blockingSeverities) || result.blockingSeverities.length === 0) {
+    throw new Error('[Report] The run does not declare its blocking severities - a verdict would have to '
+      + 'guess what stops this bearer. Fix: render the value runManifest() returned; it carries '
+      + 'blockingSeverities from the manifest.');
+  }
+  return result.findings.filter((finding) => result.blockingSeverities.includes(finding.severity));
+}
+
+/**
+ * The two words this uniform is judged with — `NOT DEPLOYABLE`/`DEPLOYABLE` for
+ * a service, `NOT PUBLISHABLE`/`PUBLISHABLE` for a library. The word is a
+ * property of the uniform, never an `if` in the renderer.
+ *
+ * @param {object} result the value `runManifest` returned
+ * @returns {{blocked: string, clear: string}}
+ */
+function verdictOf(result) {
+  const verdict = result.verdict;
+  if (verdict === null || typeof verdict !== 'object'
+    || typeof verdict.blocked !== 'string' || typeof verdict.clear !== 'string'
+    || typeof verdict.incomplete !== 'string') {
+    throw new Error('[Report] The run does not declare its verdict words - the sentence a human reads '
+      + 'belongs to the uniform. Fix: render the value runManifest() returned; it carries verdict '
+      + '{ blocked, clear, incomplete } from the manifest.');
+  }
+  return verdict;
+}
+
+/**
+ * What a CLEAR run adds when it could not look at every row that can block: the
+ * uniform's own sentence, with the count and the ids of those rows in it.
+ *
+ * The sentence is the manifest's (`manifestShape.js` § VERDICT_WORDS) and the
+ * rows are `runManifest`'s (§ incompleteRows); this function only fills the two
+ * placeholders. Nothing here knows the word `deploy` — a library says `publish`,
+ * and a renderer that knew either would be a second owner of the consequence
+ * (`api/shared/TODO.md` §0.2b-15).
+ *
+ * @param {object} result the value `runManifest` returned
+ * @returns {string}
+ */
+function describeIncomplete(result) {
+  const rows = incompleteRows(result);
+  return verdictOf(result).incomplete
+    .split('{count}').join(String(rows.length))
+    .split('{ids}').join(rows.map((one) => one.id).join(', '));
+}
+
+/**
+ * The outcome half of a CLEAR verdict — what was found, and always what could
+ * not be looked at.
+ *
+ * One owner, three callers: the banner an init log ends with, the report
+ * `oa-validate` prints, and the library report beside it. Before this, the three
+ * described the same run three ways, and two of them stopped at
+ * `— no findings`. A reader believes that sentence: it reads as a proven clean
+ * bill of health, and over a run where five rows could not look it is not one
+ * (`.claude/rules/automation-gates.md` §5 — a silent NOT RUN is a false
+ * guarantee; `change-discipline.md` § One rail per concern — one sentence, one
+ * owner). Lead decision, d.223 follow-up.
+ *
+ * The count is appended only when there IS one: a run that looked at everything
+ * keeps the short sentence, so the parenthesis always means something.
+ *
+ * @param {object} result the value `runManifest` returned
+ * @returns {string} e.g. `no findings`, `no findings (5 row(s) not run)`,
+ *                   `0 blocking finding(s), 1 warning(s) (1 row(s) not run)`
+ */
+function describeClearOutcome(result) {
+  const warnings = result.findings.length - blockingOf(result).length;
+  const found = warnings > 0
+    ? `0 blocking finding(s), ${warnings} warning(s)`
+    : 'no findings';
+
+  if (result.notRun.length === 0) return found;
+
+  // Three outcomes, because there are three: everything was looked at; a row
+  // that could not have blocked anything was skipped (the count says so, and
+  // nothing more is owed); a row that CAN block was skipped, and then the
+  // verdict is only true of the half that ran (d.230).
+  return incompleteRows(result).length > 0
+    ? `${found}, ${describeIncomplete(result)}`
+    : `${found} (${result.notRun.length} row(s) not run)`;
+}
+
+function renderTable(findings) {
+  const widths = COLUMNS.map((column) => Math.max(
+    column.length,
+    ...findings.map((finding) => String(finding[column]).length)
+  ));
+  const line = (cells) => cells
+    .map((cell, index) => (index === cells.length - 1 ? String(cell) : String(cell).padEnd(widths[index])))
+    .join('  ')
+    .trimEnd();
+
+  return [line(COLUMNS), ...findings.map((finding) => line(COLUMNS.map((column) => finding[column])))];
+}
+
+const notRunLine = (skipped) => `NOT RUN  ${skipped.id} — ${skipped.reason}`;
+
+/**
+ * The banner of confirmation `biz-service-manifest` 001 §4 — what the service
+ * prints at the end of its init log, and what `oa-validate` could print without
+ * the surrounding report.
+ *
+ * A clean run says so in one line INCLUDING how many rows did not run: silence
+ * is the one outcome a reader cannot interpret, and a row that could not look is
+ * not a pass (`.claude/rules/automation-gates.md` §5).
+ *
+ * The table is `renderTable` — the same one `renderReport` prints, because one
+ * concern gets one rail (`.claude/rules/change-discipline.md`).
+ *
+ * @param {object} result the value `runManifest` returned
+ * @returns {string[]} the banner, line by line, unterminated
+ */
+function renderBanner(result) {
+  const blocking = blockingOf(result);
+  const verdict = verdictOf(result);
+  const lines = [];
+
+  if (blocking.length > 0) {
+    lines.push(`${verdict.blocked} — ${blocking.length} finding(s)`);
+  } else {
+    // The banner keeps its subject — it is one line in a long init log — and
+    // takes the outcome from the one place that owns it.
+    lines.push(`${verdict.clear} — manifest conformance: ${describeClearOutcome(result)}`);
+  }
+
+  if (result.findings.length > 0) lines.push(...renderTable(result.findings));
+  lines.push(...result.notRun.map(notRunLine));
+
+  return lines;
+}
+
+/**
+ * One finding as a single sentence in the `[Context] Problem - Expected/Fix`
+ * shape of `architecture-principles.md` §5 — what a `boot` finding reads like in
+ * `results.errors`, where there is no table to carry the columns.
+ *
+ * @param {object} finding one entry of `result.findings`
+ * @returns {string}
+ */
+function describeFinding(finding) {
+  return `[Manifest] ${finding.id} ${finding.where} - ${finding.what}. `
+    + `Fix: ${finding.fix} (owner: ${finding.owner}, doc: ${finding.doc})`;
+}
+
+/**
+ * @param {object} result the value `runManifest` returned
+ * @returns {string} the whole report, newline-terminated
+ */
+function renderReport(result) {
+  const blocking = blockingOf(result);
+  const verdict = verdictOf(result);
+
+  const lines = [
+    `Manifest conformance — uniform ${result.uniform}`,
+    `Service root: ${result.serviceRoot === null ? 'NOT SET — this is a workspace run' : result.serviceRoot}`,
+    `Workspace root: ${result.workspaceRoot === null ? 'NOT RESOLVED' : result.workspaceRoot}`,
+    ''
+  ];
+
+  for (const skipped of result.notRun) {
+    lines.push(notRunLine(skipped));
+  }
+  if (result.notRun.length > 0) lines.push('');
+
+  if (result.findings.length > 0) {
+    lines.push(...renderTable(result.findings), '');
+    lines.push('Doc:');
+    const seen = new Set();
+    for (const finding of result.findings) {
+      if (seen.has(finding.id)) continue;
+      seen.add(finding.id);
+      lines.push(`  ${finding.id}  ${finding.doc}`);
+    }
+    lines.push('');
+  }
+
+  if (blocking.length > 0) {
+    lines.push(`${verdict.blocked} — ${blocking.length} finding(s) of severity `
+      + `${result.blockingSeverities.join('|')}`);
+  } else {
+    lines.push(`${verdict.clear} — ${describeClearOutcome(result)}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * @param {object} result the value `runManifest` returned
+ * @returns {string} the same run as data, newline-terminated
+ */
+function renderJson(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+/** 001 §3.1: exit 0 or 1. A blocking finding is the only thing that fails a run. */
+function exitCodeFor(result) {
+  return result.ok ? 0 : 1;
+}
+
+module.exports = {
+  renderReport,
+  renderBanner,
+  renderJson,
+  describeFinding,
+  describeClearOutcome,
+  describeIncomplete,
+  exitCodeFor,
+  blockingOf,
+  verdictOf,
+  COLUMNS
+};