@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/sync/sharedEnv.js

@@ -0,0 +1,162 @@
+'use strict';
+
+/**
+ * `shared.env` is generated, never written: the platform manifest
+ * `api/config/shared-env.json` owns the shared key set, and every copy of the
+ * file - the platform template and each service's - is rendered from it
+ * (confirmation `biz-service-manifest` 003 §18, 004).
+ *
+ * Two functions, both pure: nothing here reads `process.env`, opens a file or
+ * knows a path. The caller loads the manifest, the caller reads the target, the
+ * caller writes it (`.claude/rules/architecture-principles.md` §1).
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §18
+ */
+
+/** What every env parser in this repository accepts as a key (`^[A-Z_][A-Z0-9_]*=`). */
+const KEY_NAME = /^[A-Z_][A-Z0-9_]*$/;
+
+const HEADER = Object.freeze([
+  '# GENERATED FILE - do not edit. Edit the manifest instead:',
+  '# api/config/shared-env.json, then run `npx oa-sync-template shared-env --target <dir>`.'
+]);
+
+const DIFF_HEADER = Object.freeze([
+  '--- generated from api/config/shared-env.json',
+  '+++ on disk'
+]);
+
+function assertManifest(manifest) {
+  const keys = manifest && manifest.keys;
+  if (!Array.isArray(keys) || keys.length === 0) {
+    throw new Error('[SharedEnv] Manifest has no keys - expected { keys: [ { name, value, why } ] }. '
+      + 'Fix: declare the shared key set in api/config/shared-env.json.');
+  }
+
+  keys.forEach((key) => {
+    const name = key && key.name;
+    if (typeof name !== 'string' || !KEY_NAME.test(name)) {
+      throw new Error(`[SharedEnv] Invalid key name ${JSON.stringify(name)} - expected UPPER_SNAKE_CASE, `
+        + 'so every env parser reads it. Fix: rename the key in api/config/shared-env.json.');
+    }
+    if (typeof key.value !== 'string') {
+      throw new Error(`[SharedEnv] Key ${name} has no "value" - the template value is required, `
+        + 'CHANGE_ME where the value is a per-machine secret. Fix: add "value" to that key in '
+        + 'api/config/shared-env.json.');
+    }
+    if (typeof key.why !== 'string' || key.why.trim() === '') {
+      throw new Error(`[SharedEnv] Key ${name} has no "why" - every shared key states why the platform `
+        + 'shares it (docs/biz/70-contracts/env-contract.md). Fix: add "why" to that key in '
+        + 'api/config/shared-env.json.');
+    }
+    if (/[\r\n]/.test(key.why)) {
+      throw new Error(`[SharedEnv] Key ${name} has a multi-line "why" - the generated file carries one `
+        + 'comment line per key. Fix: write it as a single sentence in api/config/shared-env.json.');
+    }
+    if (/[\r\n]/.test(key.value)) {
+      throw new Error(`[SharedEnv] Key ${name} has a multi-line "value" - an env file carries one line `
+        + 'per key. Fix: correct the value in api/config/shared-env.json.');
+    }
+  });
+}
+
+/**
+ * The file text the manifest describes: header, then one commented key per
+ * declaration, in manifest order. LF endings, exactly one trailing newline, and
+ * nothing that varies between two runs - the same manifest always renders the
+ * same bytes, which is what makes `--check` a gate rather than a diff of noise.
+ *
+ * `consumers` is deliberately NOT rendered: who reads a key is a fact the code
+ * owns and a check measures, and a hand-maintained copy of it inside every
+ * service's env file would rot the moment a reader moved
+ * (`.claude/rules/doc-code-binding.md` §1).
+ *
+ * @param {{keys: Array<{name: string, value: string, why: string}>}} manifest
+ * @returns {string}
+ */
+function renderSharedEnv(manifest) {
+  assertManifest(manifest);
+
+  const lines = [...HEADER];
+  manifest.keys.forEach((key) => {
+    lines.push('', `# ${key.why}`, `${key.name}=${key.value}`);
+  });
+
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * How many lines at the end of both arrays are identical.
+ * Measured from the end first, so an appended block reads as an insertion at
+ * the place it was appended rather than as a rewrite of the last line.
+ */
+function commonSuffix(expected, actual) {
+  let count = 0;
+  while (count < expected.length
+    && count < actual.length
+    && expected[expected.length - 1 - count] === actual[actual.length - 1 - count]) {
+    count += 1;
+  }
+  return count;
+}
+
+function commonPrefix(expected, actual) {
+  let count = 0;
+  while (count < expected.length && count < actual.length && expected[count] === actual[count]) {
+    count += 1;
+  }
+  return count;
+}
+
+/**
+ * The lines that differ between what the key set renders and what is on disk,
+ * so a failure names the drift instead of announcing it
+ * (`.claude/rules/automation-gates.md` §1 requirement 4).
+ *
+ * Two callers, one shape: the CLI compares the target against what the manifest
+ * renders here and now, and the manifest row `G-SHARED-ENV` compares it against
+ * the render this package carries (d.229). Both are the same generated text and
+ * both name the same owner, so the diff has one owner too
+ * (`change-discipline.md` § One rail per concern).
+ *
+ * @param {string} expectedText the generated text
+ * @param {string} fileText the target file's current content
+ * @returns {string} the two header lines, then the differing lines
+ */
+function diffAgainst(expectedText, fileText) {
+  const expected = expectedText.split('\n');
+  const actual = fileText.split('\n');
+
+  const suffix = commonSuffix(expected, actual);
+  const expectedBody = expected.slice(0, expected.length - suffix);
+  const actualBody = actual.slice(0, actual.length - suffix);
+  const prefix = commonPrefix(expectedBody, actualBody);
+
+  return [
+    ...DIFF_HEADER,
+    ...expectedBody.slice(prefix).map((line) => `-${line}`),
+    ...actualBody.slice(prefix).map((line) => `+${line}`)
+  ].join('\n');
+}
+
+/**
+ * Whether a file on disk is what the manifest renders, and - when it is not -
+ * the lines that differ.
+ *
+ * @param {object} manifest
+ * @param {string} fileText the target file's current content
+ * @returns {{ok: boolean, diff: string}} `diff` is '' exactly when `ok` is true
+ */
+function checkSharedEnv(manifest, fileText) {
+  if (typeof fileText !== 'string') {
+    throw new Error(`[SharedEnv] File text is required - checkSharedEnv(manifest, fileText) got ${
+      fileText === null ? 'null' : typeof fileText}. Fix: read the target file before checking it.`);
+  }
+
+  const expectedText = renderSharedEnv(manifest);
+  if (expectedText === fileText) return { ok: true, diff: '' };
+
+  return { ok: false, diff: diffAgainst(expectedText, fileText) };
+}
+
+module.exports = { renderSharedEnv, checkSharedEnv, diffAgainst };

package/src/sync/uniformFiles.js

@@ -0,0 +1,474 @@
+'use strict';
+
+/**
+ * The generator half of the manifest (confirmation `biz-service-manifest` 001
+ * §3.2): `npx oa-sync-template [path…]` rewrites the files of the classes
+ * `identical` and `generated`, and never touches `own`.
+ *
+ * ONE DEFINITION, READ TWICE. This module holds no list of files, no template
+ * path and no block name of its own: it walks the same rows the conformance
+ * check walks, and renders each from the same `from:` reference that row already
+ * points the check at. A second list here would be a second owner of the shape,
+ * and the two would diverge exactly the way the nine copies of `init.sh` did.
+ *
+ * The corollary is that a row the manifest does not make renderable is NOT
+ * rendered. `G-PROD-IMAGE` names no reference — it is a requirement about a
+ * file, not a file — so it is reported NOT RUN, with the reason, rather than
+ * being filled from something this module decided
+ * (`.claude/rules/automation-gates.md` §5: silence is a defect, and so is a
+ * mechanism that quietly covers less than it claims).
+ *
+ * WHERE A ROW NEEDS MORE THAN A SPLICE, THE MODULE THAT OWNS THE RULE RENDERS
+ * IT. Two rows are not "the reference, verbatim": the runner block carries three
+ * declarations it takes from the service beside it, and an installation document
+ * is created from a skeleton and never rewritten over its prose. Both are
+ * rendered by the check module that decides them (`RENDERERS` below), so the
+ * generator cannot produce a file its own check rejects.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §3.2
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { readReferencedFile, isPackageReference, referenceOwner } = require('../manifest/discovery');
+const { readComposeServices } = require('../manifest/checks/composeShape');
+const { renderRunnerBlock, replaceServiceNode } = require('../manifest/checks/composeRunnerBlock');
+const {
+  blockLines, headingsOf, skeletonOf, renderedReference, ignoreEntries, dockerignoreEntries,
+  withoutBlock, IGNORE_BLOCK, DOCKERIGNORE_BLOCK
+} = require('../manifest/checks/serviceFiles');
+const {
+  spliceBlock, insertBlockUnder, topLevelKeys, replaceTopLevelKeys
+} = require('./serviceTemplate');
+const { requireIdentity } = require('../manifest/serviceIdentity');
+const { rowNeedsWorkspace } = require('../manifest/manifestShape');
+const { KINDS, applyUniformRegion } = require('./readmePointer');
+const { serviceRegion } = require('./readmeLocation');
+const { CHECK_REGISTRY } = require('../manifest/checks');
+
+/** What the `test` profile is called; the runner is the compose service declaring it. */
+const TEST_PROFILE = 'test';
+
+/** The mapping a compose service is an entry of, and the one the runner belongs under. */
+const COMPOSE_SERVICES_KEY = 'services';
+
+/**
+ * The runner block, rendered for THIS repository: the template's block with this
+ * repository's identity in it and its own build, env_file and networks grafted
+ * in — the inverse of what `compose-runner` removes before it compares.
+ *
+ * A compose file that is not there is refused rather than created: a service is
+ * created by `oa-sync-template --new`, which renders the whole tree from one
+ * name. Rendering a single compose file for a service that does not exist would
+ * have to invent the container name, and the one measured counter-example says
+ * it cannot be derived — `api_biz/hello-service` is `api_service_hello`, not
+ * `api_service_hello_service`.
+ *
+ * @param {{row: object, current: string|null, serviceRoot: string, workspaceRoot: string}} args
+ * @returns {string}
+ */
+function renderRunner({ row, current, serviceRoot, workspaceRoot }) {
+  if (current === null) {
+    throw new Error(`[UniformSync] ${row.path} is absent - the runner block is spliced into the compose file `
+      + 'this repository is built from, and this run has no container name to invent one with. '
+      + 'Fix: create the service with oa-sync-template --new <name> --into <dir>.');
+  }
+
+  const services = readComposeServices(current);
+  const runners = [...services.entries()]
+    .filter(([, node]) => (node.sequences.get('profiles') || []).includes(TEST_PROFILE));
+  const resident = [...services.entries()]
+    .filter(([, node]) => !(node.sequences.get('profiles') || []).includes(TEST_PROFILE));
+  if (resident.length !== 1) {
+    throw new Error(`[UniformSync] ${row.path} declares ${resident.length} services beside the runner - `
+      + 'the uniform is one service and its runner, and the block is rendered against that one service. '
+      + 'Fix: reduce the file to the service and its runner, then run the sync again.');
+  }
+
+  const reference = blockLines(readReferencedFile({ from: row.from, workspaceRoot }), row.block);
+  if (reference.length === 0) {
+    throw new Error(`[UniformSync] Reference block "${row.block}" not found in ${referenceOwner(row.from)} - the row `
+      + 'names a block the template does not carry. Fix: restore the block in the template, or correct the row.');
+  }
+
+  const replacement = renderRunnerBlock({
+    reference,
+    composeText: current,
+    containerName: resident[0][0],
+    serviceName: requireIdentity(serviceRoot).service_name
+  });
+
+  // Three states, and the third one is why this is not two lines.
+  //
+  //   * the file HAS the block          → it is rewritten between its markers;
+  //   * it has a runner but NO markers  → that runner's declaration is REPLACED
+  //     where it stands. Measured 2026-09-10 over a copy of api_biz/converter:
+  //     seven of the eight repositories are in this state (d.220), and a run
+  //     that only inserted gave them a SECOND `<container>_tests:` key — a
+  //     duplicate mapping key, which compose either refuses or resolves by
+  //     taking the last one;
+  //   * it has neither                  → the block is inserted under
+  //     `services:`. That position is not a judgement about this service: a
+  //     mapping has one place its entries can start (lead decision,
+  //     `api/shared/TODO.md` §0.2b-35 point 4). `init.sh` stays refused because
+  //     there the position IS a decision about the service's own install steps.
+  if (blockLines(current, row.block).length > 0) {
+    return spliceBlock({ text: current, block: row.block, replacement });
+  }
+  if (runners.length === 1) {
+    return replaceServiceNode({ text: current, name: runners[0][0], replacement });
+  }
+  return insertBlockUnder({ text: current, key: COMPOSE_SERVICES_KEY, replacement });
+}
+
+/**
+ * An installation document: created from the skeleton when it is missing, left
+ * exactly as it is when it carries every section, and REFUSED when a section is
+ * missing.
+ *
+ * The refusal is the point. What each section says is this service's own fact
+ * (`skeleton_only`, confirmation `biz-service-manifest` 001 §2), so a run that
+ * rewrote an existing document would delete prose somebody wrote in order to add
+ * a heading. The generator names the missing heading and stops.
+ *
+ * @param {{row: object, current: string|null, serviceRoot: string, workspaceRoot: string}} args
+ * @returns {string}
+ */
+function renderSkeleton({ row, current, serviceRoot, workspaceRoot }) {
+  const reference = renderedReference({ row, serviceRoot, workspaceRoot });
+  if (current === null) return skeletonOf(reference);
+
+  const missing = headingsOf(reference).filter((heading) => !headingsOf(current).includes(heading));
+  if (missing.length === 0) return current;
+
+  throw new Error(`[UniformSync] ${row.path} has no section ${missing.map((h) => `"${h}"`).join(', ')} - `
+    + 'this document is a skeleton with this service\'s own prose in it, so the run adds no section over '
+    + 'text it did not write. Fix: add the heading, and under it what this service requires there.');
+}
+
+/**
+ * The README with its uniform pointer current: the region rendered from the
+ * packaged manifest, and every line outside the markers left exactly as it was.
+ *
+ * The file itself is never created. A README is prose somebody wrote, and this
+ * run owns one region of it, not the document — an absent one is the finding
+ * `G-README` raises, with the same sentence.
+ *
+ * @param {{row: object, current: string|null, serviceRoot: string}} args
+ * @returns {string}
+ */
+function renderReadme({ row, current, serviceRoot }) {
+  if (current === null) {
+    throw new Error(`[UniformSync] ${row.path} is absent - the uniform pointer is a generated REGION of that `
+      + 'file, and the rest of it is prose this run has no business writing. '
+      + `Fix: give the repository a ${row.path}, then run the sync again.`);
+  }
+  return applyUniformRegion(current, serviceRegion(serviceRoot), { kind: KINDS.service });
+}
+
+/**
+ * A whole file rendered for THIS repository: the template with the one parameter
+ * a service has in it, its declared name.
+ *
+ * It is the same call the check makes, so the generator cannot write a file its
+ * own row rejects — and it THROWS on a repository that has not said who it is,
+ * which is what a run asked to write that repository's files must do rather than
+ * invent a name (`serviceIdentity.js`).
+ *
+ * @param {{row: object, serviceRoot: string, workspaceRoot: string}} args
+ * @returns {string}
+ */
+function renderRendered({ row, serviceRoot, workspaceRoot }) {
+  return renderedReference({ row, serviceRoot, workspaceRoot });
+}
+
+/**
+ * A file whose PLATFORM half is a delimited block: the block rendered for this
+ * repository, put where the repository already keeps those keys, and every other
+ * line left exactly as it was.
+ *
+ * Three states, and the third is the migration this renderer exists for.
+ *
+ *   * the file HAS the block        → it is rewritten between its markers;
+ *   * it has the platform's keys as UNMARKED top-level keys → those keys are
+ *     REPLACED by the block, in place. Measured over the eight biz repositories
+ *     on 2026-09-11, all eight are in this state: `include:`, `stages:`,
+ *     `variables:`, `build:`, `secret_detection:` and `deploy-production:`
+ *     copied before the markers existed. A run that only inserted would give
+ *     each file a second `build:` and a second `deploy-production:` — duplicate
+ *     mapping keys, which GitLab either refuses or resolves by taking the last
+ *     one;
+ *   * the file is not there at all  → it is created whole, which is the state
+ *     `--new` writes: a repository with no half of its own yet gets the
+ *     template's default `test:` job to own from then on.
+ *
+ * What the block claims is read from the block, never from a list here: the
+ * keys come from `topLevelKeys` over the rendered reference, so adding a job to
+ * the platform's half is one edit to the template
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * @param {{row: object, current: string|null, serviceRoot: string, workspaceRoot: string}} args
+ * @returns {string}
+ */
+function renderDelimitedBlock({ row, current, serviceRoot, workspaceRoot }) {
+  const rendered = renderedReference({ row, serviceRoot, workspaceRoot });
+  if (current === null) return rendered;
+
+  const replacement = blockLines(rendered, row.block);
+  if (replacement.length === 0) {
+    throw new Error(`[UniformSync] Reference block "${row.block}" not found in ${referenceOwner(row.from)} - the row `
+      + 'names a block the template does not carry. Fix: restore the block in the template, or correct the row.');
+  }
+
+  if (blockLines(current, row.block).length > 0) {
+    return spliceBlock({ text: current, block: row.block, replacement });
+  }
+  return replaceTopLevelKeys({ text: current, keys: topLevelKeys(replacement), replacement });
+}
+
+/**
+ * A `contains` file: the repository's own lines, then ONE labelled block holding
+ * the platform entries those lines do not already declare.
+ *
+ * Self-healing rather than append-only, which is what makes it idempotent: the
+ * existing block is taken out FIRST, so what the run compares is the
+ * repository's own half. A second run therefore has nothing to add and writes no
+ * second block, and an entry the repository has since declared by hand drops out
+ * of the block instead of standing beside it twice.
+ *
+ * The block is the FIX's shape, never the check's — `template-entries` compares
+ * a set and never looks for a marker (`serviceFiles.js` § templateEntries). It
+ * exists so a reader can tell the platform's lines from this repository's.
+ *
+ * @param {{row: object, current: string|null, workspaceRoot: string}} args
+ * @returns {string}
+ */
+function renderIgnoreEntries({ row, current, workspaceRoot }) {
+  const reference = ignoreEntries(readReferencedFile({ from: row.from, workspaceRoot }));
+  const own = current === null ? '' : withoutBlock(current, IGNORE_BLOCK);
+  const declared = ignoreEntries(own);
+  const missing = reference.filter((entry) => !declared.includes(entry));
+
+  const head = own === '' ? '' : `${own.replace(/\n+$/, '')}\n`;
+  if (missing.length === 0) return head;
+
+  const block = [
+    `# --- ${IGNORE_BLOCK}`,
+    `# Written by ${referenceOwner(row.from)} — paths this platform generates inside the`,
+    '# repository. Everything above this block is this repository\'s own.',
+    ...missing,
+    `# --- end ${IGNORE_BLOCK}`,
+    ''
+  ].join('\n');
+
+  return head === '' ? block : `${head}\n${block}`;
+}
+
+/**
+ * The build-context half of the same declaration.
+ *
+ * Identical in shape to `renderIgnoreEntries` — the repository's own lines, then
+ * ONE labelled block — and deliberately NOT the same function: what goes in the
+ * block is the DERIVED list (`serviceFiles.js` § dockerignoreEntries), because a
+ * `.dockerignore` does not mean by a slash-less pattern what a `.gitignore`
+ * means by it. The two rows read one declaration and translate it for their own
+ * format; neither carries a list of its own.
+ *
+ * @param {{row: object, current: string|null, workspaceRoot: string}} args
+ * @returns {string}
+ */
+function renderDockerignoreEntries({ row, current, workspaceRoot }) {
+  const reference = dockerignoreEntries(readReferencedFile({ from: row.from, workspaceRoot }));
+  const own = current === null ? '' : withoutBlock(current, DOCKERIGNORE_BLOCK);
+  const declared = ignoreEntries(own);
+  const missing = reference.filter((entry) => !declared.includes(entry));
+
+  const head = own === '' ? '' : `${own.replace(/\n+$/, '')}\n`;
+  if (missing.length === 0) return head;
+
+  const block = [
+    `# --- ${DOCKERIGNORE_BLOCK}`,
+    `# Derived from ${referenceOwner(row.from)}, the declaration .gitignore reads too —`,
+    '# what a LOCAL production build must not copy into the image (being ignored by git',
+    "# excludes nothing from COPY . .). Everything above this block is this repository's own.",
+    ...missing,
+    `# --- end ${DOCKERIGNORE_BLOCK}`,
+    ''
+  ].join('\n');
+
+  return head === '' ? block : `${head}\n${block}`;
+}
+
+/**
+ * The rows whose content the module that owns their check renders, by the check
+ * the row names. One table, in one place: a row is renderable because its rule
+ * says how, never because this module recognised its id.
+ */
+const RENDERERS = Object.freeze({
+  'compose-runner': renderRunner,
+  'template-entries': renderIgnoreEntries,
+  'dockerignore-entries': renderDockerignoreEntries,
+  'template-render': renderRendered,
+  'delimited-block-render': renderDelimitedBlock,
+  'template-skeleton': renderSkeleton,
+  'readme-uniform-current': renderReadme
+});
+
+/**
+ * The file classes the generator owns. `own` and `forbidden` are not written:
+ * one is the repository's, the other must not exist.
+ */
+const SYNCABLE_CLASSES = Object.freeze(['identical', 'generated', 'contains']);
+
+/**
+ * The manifest rows this run is defined by, in manifest order.
+ *
+ * @param {object} manifest
+ * @returns {object[]}
+ */
+function uniformRows(manifest) {
+  const files = (manifest && manifest.files) || {};
+  return SYNCABLE_CLASSES.flatMap((className) => files[className] || []);
+}
+
+/**
+ * Where two texts first differ, what the file says there, and what the run would
+ * put there instead.
+ *
+ * BOTH sides, because one of them alone lies about half the runs. A splice over
+ * existing content is described by what the file says; an INSERTION is not —
+ * measured 2026-09-10, a run that spliced the runner block into
+ * `api_biz/converter` reported `line 2: "api_service_converter:"`, naming the
+ * line the block was pushed down past rather than the block. The reader of a
+ * `wrote` line wants to know where it went.
+ *
+ * @param {string} desired
+ * @param {string} current
+ * @returns {string}
+ */
+function firstDifference(desired, current) {
+  const want = desired.split('\n');
+  const have = current.split('\n');
+  const say = (line) => JSON.stringify(line === undefined ? '<end of file>' : line.trim());
+  const length = Math.max(want.length, have.length);
+  for (let index = 0; index < length; index += 1) {
+    if (want[index] === have[index]) continue;
+    return `line ${index + 1}: ${say(have[index])} → ${say(want[index])}`;
+  }
+  return 'no line differs';
+}
+
+/**
+ * Read a repository-relative file, or null when there is no file there.
+ *
+ * A row may name a directory - `G-SETUP` names `docs/80-setup/` - so "is there
+ * a file" is asked of the entry, not of the path. That row renders nothing
+ * anyway, but reading its content must not be what says so.
+ */
+function readServiceFile(serviceRoot, relative) {
+  const file = path.join(serviceRoot, ...relative.split('/'));
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return null;
+  return fs.readFileSync(file, 'utf8');
+}
+
+/**
+ * What a row's file should contain, or why this run cannot say.
+ *
+ * @returns {{desired: string}|{reason: string}}
+ */
+function desiredContent({ row, current, serviceRoot, workspaceRoot }) {
+  if (!row.from || (typeof row.from.path !== 'string' && !isPackageReference(row.from))) {
+    return {
+      reason: 'the row declares no "from" reference, so nothing says what this file\'s content is rendered from'
+    };
+  }
+
+  const render = RENDERERS[row.check];
+  if (render !== undefined) return { desired: render({ row, current, serviceRoot, workspaceRoot }) };
+
+  const reference = readReferencedFile({ from: row.from, workspaceRoot });
+
+  // A whole-file row: the file IS the reference.
+  if (typeof row.block !== 'string') return { desired: reference };
+
+  // A block row: the reference owns the block, the service owns the rest of the
+  // file — so an existing file is spliced and an absent one is created whole.
+  if (current === null) return { desired: reference };
+
+  const replacement = blockLines(reference, row.block);
+  if (replacement.length === 0) {
+    throw new Error(`[UniformSync] Reference block "${row.block}" not found in ${referenceOwner(row.from)} - the row `
+      + 'names a block the template does not carry. Fix: restore the block in the template, or correct the row.');
+  }
+  return { desired: spliceBlock({ text: current, block: row.block, replacement }) };
+}
+
+/**
+ * One row's plan.
+ *
+ * @param {{row: object, serviceRoot: string, workspaceRoot: string}} args
+ * @returns {{id: string, path: string, outcome: 'unchanged'|'change'|'not-run'|'blocked',
+ *            current: string|null, desired?: string, detail?: string, reason?: string}}
+ */
+function planRow({ row, serviceRoot, workspaceRoot }) {
+  const current = readServiceFile(serviceRoot, row.path);
+  const base = { id: row.id, path: row.path, current };
+
+  // The same question the manifest run asks of the same row, answered by the
+  // same predicate: does THIS row need the workspace? Since d.229 most of them
+  // reference a file this package carries, so the sync answers inside a service
+  // container — which is where the `fix` command of those rows is read
+  // (`.claude/rules/change-discipline.md` § One rail per concern).
+  const check = CHECK_REGISTRY[row.check];
+  if (workspaceRoot === null && check !== undefined && rowNeedsWorkspace({ check, row, block: null })) {
+    return {
+      ...base,
+      outcome: 'not-run',
+      reason: check.describeNotRun
+        ? check.describeNotRun({ row, block: null })
+        : 'the workspace root is not reachable'
+    };
+  }
+
+  let outcome;
+  try {
+    outcome = desiredContent({ row, current, serviceRoot, workspaceRoot });
+  } catch (error) {
+    return { ...base, outcome: 'blocked', reason: error.message };
+  }
+
+  if (outcome.reason !== undefined) return { ...base, outcome: 'not-run', reason: outcome.reason };
+  if (outcome.desired === current) return { ...base, outcome: 'unchanged', desired: outcome.desired };
+
+  return {
+    ...base,
+    outcome: 'change',
+    desired: outcome.desired,
+    detail: current === null ? 'absent' : firstDifference(outcome.desired, current)
+  };
+}
+
+/**
+ * The plan for a whole service, or for the paths the caller named.
+ *
+ * @param {{manifest: object, serviceRoot: string, workspaceRoot: string, paths?: string[]}} args
+ * @returns {object[]} one entry per row, in manifest order
+ */
+function planSync({ manifest, serviceRoot, workspaceRoot, paths = [] }) {
+  const rows = uniformRows(manifest);
+
+  const wanted = paths.length === 0 ? rows : paths.map((wantedPath) => {
+    const row = rows.find((candidate) => candidate.path === wantedPath);
+    if (row === undefined) {
+      throw new Error(`[UniformSync] No manifest row names "${wantedPath}" - the run writes only what the `
+        + `uniform declares. Paths it knows: ${rows.map((candidate) => candidate.path).join(', ')}. `
+        + 'Fix: name one of those, or leave the paths out to plan them all.');
+    }
+    return row;
+  });
+
+  return wanted.map((row) => planRow({ row, serviceRoot, workspaceRoot }));
+}
+
+module.exports = { SYNCABLE_CLASSES, uniformRows, planRow, planSync, firstDifference };