@onlineapps/conn-orch-validator 7.0.0 → 8.0.0

package/src/sync/docsRegion.js

@@ -0,0 +1,463 @@
+'use strict';
+
+/**
+ * The generated regions of the documentation tree.
+ *
+ * Confirmation `biz-service-manifest` 002 §16.2: the list of required files,
+ * scripts, limits, categories and duties that `docs/biz/60-templates/…`,
+ * `docs/guides/library-publishing-process.md` and `docs/guides/DEVELOPMENT.md`
+ * copy by hand becomes a generated region fed by the manifests, and `--check`
+ * fails the run when a region is stale. Three documents were measured copying
+ * the same repository tree, and two copying the same script table; a copy is
+ * kept true by review only, so it is a descriptive fact written by hand -
+ * exactly what `.claude/rules/doc-code-binding.md` §1 forbids.
+ *
+ * What the region carries and what it deliberately does not:
+ *
+ *   * the row's OBSERVABLE - its id, its check, the paths and values its own
+ *     parameters name. Those are facts of the manifest, which is their single
+ *     owner, so rendering them creates no second copy.
+ *   * NEVER the row's `why` or `fix`. Those are prose with an owner, and a
+ *     rendered copy of them in five documents is the duplication this mechanism
+ *     exists to remove (d.216 established the shape in the library READMEs: a
+ *     region of ids and links, not of paragraphs).
+ *   * a `from:` reference renders as the PATH THAT OWNS the value, never as the
+ *     value itself (confirmation 004). "Node major: `api/.nvmrc`" stays true when
+ *     the platform moves to the next major; "Node 24" does not.
+ *
+ * Pure text: nothing here opens a file, reads the environment or resolves a
+ * workspace. The caller loads both manifests, lists the packaged template and
+ * says which document the region is going into
+ * (`.claude/rules/architecture-principles.md` §1).
+ *
+ * Deliberately absent from every region: a date, a count and a version. A count
+ * makes the region drift the day a row is added without anything else changing,
+ * and a date makes two runs render different bytes - which is precisely what
+ * stops a generator from being a gate.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-002
+ */
+
+const path = require('path');
+
+const { markersFor, hasRegion, replaceRegion, checkRegion: checkAgainst } = require('./generatedRegion');
+const { isPackageReference, referenceOwner } = require('../manifest/discovery');
+
+/** The five regions the confirmation names. Adding a sixth is a change to it. */
+const REGION_IDS = Object.freeze([
+  'biz-service-tree',
+  'biz-service-scripts',
+  'biz-service-runtime',
+  'biz-service-alignment',
+  'library-duties'
+]);
+
+/** What each region renders from - the one sentence `--list` prints. */
+const DESCRIPTIONS = Object.freeze({
+  'biz-service-tree': 'the packaged service template, annotated with the biz-service manifest row owning each path',
+  'biz-service-scripts': 'scripts.required and scripts.forbidden of the biz-service manifest, bodies included',
+  'biz-service-runtime': 'the runtime rows of the biz-service manifest and every row carrying a memory limit',
+  'biz-service-alignment': 'every row of the biz-service manifest - id, severity, what it checks',
+  'library-duties': 'the categories and duty sections of the library manifest, guidance marked apart'
+});
+
+/** Which manifest a region reads, for the diff header of a failed check. */
+const SOURCES = Object.freeze({
+  'biz-service-tree': 'manifests/biz-service.manifest.json',
+  'biz-service-scripts': 'manifests/biz-service.manifest.json',
+  'biz-service-runtime': 'manifests/biz-service.manifest.json',
+  'biz-service-alignment': 'manifests/biz-service.manifest.json',
+  'library-duties': 'manifests/library.manifest.json'
+});
+
+/**
+ * The keys every row carries as metadata. Everything else on a row is a
+ * PARAMETER - the value that row fixes - and the runtime region renders those
+ * without knowing their names in advance, so a parameter added to the manifest
+ * appears without this file being edited.
+ */
+const ROW_METADATA = Object.freeze(['id', 'check', 'severity', 'owner', 'why', 'fix', 'doc']);
+
+function requireKnownId(id) {
+  if (!REGION_IDS.includes(id)) {
+    throw new Error(`[DocsRegion] Unknown region id "${id}" - this package renders ${REGION_IDS.join(', ')}. `
+      + 'Fix: name one of those, or add the region here before a document declares it.');
+  }
+}
+
+/** What the marker tells the reader to run. Names the file, so it can be copied as it stands. */
+function regenerateCommand(id, targetLabel) {
+  if (typeof targetLabel !== 'string' || targetLabel.length === 0) {
+    throw new Error('[DocsRegion] targetLabel is required - the marker names the file that regenerates the '
+      + 'region, and a marker with no file in it cannot be run. '
+      + 'Fix: pass the path of the document as the workspace knows it.');
+  }
+  return `npx oa-sync-template docs-region --id ${id} --file ${targetLabel}`;
+}
+
+/**
+ * The two markers of one region in one document.
+ *
+ * @param {string} id
+ * @param {string} targetLabel the document, as the workspace root names it
+ * @returns {{begin: string, end: string}}
+ */
+function markersForRegion(id, targetLabel) {
+  requireKnownId(id);
+  return markersFor(id, regenerateCommand(id, targetLabel));
+}
+
+/** @param {string} id @returns {string} */
+function describeRegion(id) {
+  requireKnownId(id);
+  return DESCRIPTIONS[id];
+}
+
+/**
+ * Which regions of this package a document declares, in a fixed order.
+ *
+ * The question goes through `generatedRegion.hasRegion`, which knows that a
+ * marker inside a fence is an example: these documents are the ones that teach
+ * the shape, and matching the marker string here would be a second, fence-blind
+ * copy of the module's own rule (d.319).
+ */
+function regionIdsIn(text, targetLabel) {
+  return REGION_IDS.filter((id) => hasRegion(text, markersForRegion(id, targetLabel)));
+}
+
+/** A markdown link from the document to a file, computed from the two paths. */
+function linkTo(targetPath, filePath) {
+  if (typeof targetPath !== 'string' || targetPath.length === 0
+    || typeof filePath !== 'string' || filePath.length === 0) {
+    throw new Error('[DocsRegion] targetPath and the manifest path are required - the link is computed from '
+      + 'them and never written by hand. Fix: pass both absolute paths.');
+  }
+  const relative = path.relative(path.dirname(targetPath), filePath).split(path.sep).join('/');
+  return relative.startsWith('.') ? relative : `./${relative}`;
+}
+
+const code = (value) => `\`${value}\``;
+
+/** A table cell never breaks the table: a pipe in a value is escaped, not dropped. */
+const cell = (value) => String(value).split('|').join('\\|');
+
+/** Every row of a manifest, in the order the file declares them. */
+function allRows(manifest) {
+  const rows = [];
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        if (item !== null && typeof item === 'object' && typeof item.id === 'string') rows.push(item);
+        else walk(item);
+      }
+      return;
+    }
+    if (node !== null && typeof node === 'object') for (const value of Object.values(node)) walk(value);
+  };
+  walk(manifest);
+  return rows;
+}
+
+/**
+ * A parameter as the region prints it: a `from` reference names the file that
+ * owns the value (004), anything else is the row's own literal.
+ */
+function parameterValue(key, value) {
+  if (key === 'from') {
+    // A reference into this package (d.229) names its owner the way the package
+    // carries it; a reference out of it names the workspace path. One function
+    // decides which, in `manifest/discovery.js`.
+    if (value === null || typeof value !== 'object'
+      || (typeof value.path !== 'string' && !isPackageReference(value))) {
+      throw new Error('[DocsRegion] A "from" reference with no path - the region renders the owner of the value, '
+        + `and this row offers ${JSON.stringify(value)}. Fix: repair the manifest row.`);
+    }
+    return code(referenceOwner(value));
+  }
+  if (Array.isArray(value)) return value.map((item) => code(item)).join(', ');
+  if (value !== null && typeof value === 'object') return code(JSON.stringify(value));
+  return code(value);
+}
+
+function parametersOf(row) {
+  return Object.entries(row)
+    .filter(([key]) => !ROW_METADATA.includes(key))
+    .map(([key, value]) => `${code(key)}: ${parameterValue(key, value)}`);
+}
+
+/** The subject a row is about, when it names one; a row can check a whole repository. */
+function subjectOf(row) {
+  if (typeof row.path === 'string') return row.path;
+  if (typeof row.name === 'string') return row.name;
+  return null;
+}
+
+/* ------------------------------------------------------------------ regions */
+
+function renderAlignment({ serviceManifest, link }) {
+  const rows = allRows(serviceManifest);
+  return [
+    `Every row of the [biz-service uniform](${link}); \`oa-validate\` blocks on severity `
+      + `${serviceManifest.blocking_severities.map((severity) => code(severity)).join(' and ')}.`,
+    '',
+    '| row | severity | what |',
+    '|---|---|---|',
+    ...rows.map((row) => {
+      const subject = subjectOf(row);
+      const what = subject === null ? code(row.check) : `${code(row.check)} over ${code(subject)}`;
+      return `| ${code(row.id)} | ${cell(row.severity)} | ${cell(what)} |`;
+    })
+  ];
+}
+
+function renderScripts({ serviceManifest, link }) {
+  const scripts = serviceManifest.scripts;
+  if (scripts === undefined) {
+    throw new Error('[DocsRegion] The service manifest declares no scripts block - the region renders it and '
+      + 'knows no list of its own. Fix: repair manifests/biz-service.manifest.json.');
+  }
+  const forbidden = scripts.forbidden.map((row) => {
+    const subject = subjectOf(row);
+    return `${subject === null ? code(row.check) : code(subject)} (${code(row.id)})`;
+  });
+
+  return [
+    `The \`package.json\` scripts of the [biz-service uniform](${link}). A body is the row's own, `
+      + 'and `${runner}` stays unexpanded: the name of the one-shot test runner is per repository.',
+    '',
+    '| script | body | only with | row |',
+    '|---|---|---|---|',
+    ...scripts.required.map((row) => `| ${code(row.name)} | ${cell(code(row.body))} | `
+      + `${typeof row.only_with === 'string' ? code(row.only_with) : '—'} | ${code(row.id)} |`),
+    '',
+    `Never declared: ${forbidden.join(', ')}.`
+  ];
+}
+
+function renderRuntime({ serviceManifest, link }) {
+  const isMemory = (row) => Object.keys(row).some((key) => key.endsWith('_memory'));
+  const runtimeIds = new Set((serviceManifest.runtime.rows || []).map((row) => row.id));
+  const rows = allRows(serviceManifest).filter((row) => runtimeIds.has(row.id) || isMemory(row));
+
+  if (rows.length === 0) {
+    throw new Error('[DocsRegion] The service manifest declares no runtime rows - the region renders what the '
+      + 'platform fixes at run time. Fix: repair manifests/biz-service.manifest.json.');
+  }
+
+  return [
+    `What the [biz-service uniform](${link}) fixes at run time. Every value is a parameter of the row `
+      + 'beside it; a `from` parameter names the file that owns the value, which is where it is read.',
+    '',
+    '| row | check | parameters |',
+    '|---|---|---|',
+    ...rows.map((row) => `| ${code(row.id)} | ${code(row.check)} | ${cell(parametersOf(row).join(', ') || '—')} |`)
+  ];
+}
+
+/**
+ * The template's files as a tree, each node annotated with the rows that own it.
+ *
+ * The unannotated paths are NOT invented here: they are the files of the
+ * template that ships inside this package, which is the shape a service is
+ * created from. A hard-coded list beside it would be a second owner of the same
+ * fact (004 - a bearer's shape is read, never enumerated).
+ */
+function renderTree({ serviceManifest, templateFiles, link }) {
+  if (!Array.isArray(templateFiles) || templateFiles.length === 0) {
+    throw new Error(`[DocsRegion] templateFiles is required - the tree is the packaged template's own file list, `
+      + 'never a list written here. Fix: pass listTemplateFiles(TEMPLATE_ROOT).map(outputRelative).');
+  }
+
+  const forbidden = serviceManifest.files.forbidden || [];
+  const forbiddenIds = new Set(forbidden.map((row) => row.id));
+
+  const owners = new Map();
+  for (const row of allRows(serviceManifest)) {
+    if (typeof row.path !== 'string' || forbiddenIds.has(row.id)) continue;
+    const key = row.path.replace(/\/+$/, '');
+    if (!owners.has(key)) owners.set(key, { ids: [], declared: row.path });
+    owners.get(key).ids.push(row.id);
+  }
+
+  const tree = new Map();
+  const insert = (segments, node) => {
+    const [head, ...rest] = segments;
+    if (!node.has(head)) node.set(head, new Map());
+    if (rest.length > 0) insert(rest, node.get(head));
+  };
+  for (const file of [...templateFiles].sort()) insert(file.split('/'), tree);
+
+  const covered = new Set();
+  const lines = [];
+  const walk = (node, prefix, parentPath) => {
+    const names = [...node.keys()].sort();
+    names.forEach((name, index) => {
+      const child = node.get(name);
+      const isDirectory = child.size > 0;
+      const full = parentPath === '' ? name : `${parentPath}/${name}`;
+      const last = index === names.length - 1;
+      const owned = owners.get(full);
+      if (owned !== undefined) covered.add(full);
+      lines.push(`${prefix}${last ? '└── ' : '├── '}${name}${isDirectory ? '/' : ''}`
+        + (owned === undefined ? '' : `    # ${owned.ids.join(', ')}`));
+      if (isDirectory) walk(child, `${prefix}${last ? '    ' : '│   '}`, full);
+    });
+  };
+  walk(tree, '', '');
+
+  const outside = [...owners.entries()].filter(([key]) => !covered.has(key));
+
+  return [
+    `The shape of a service repository: the files the packaged template carries, each annotated with the `
+      + `row of the [biz-service uniform](${link}) that owns it. An unannotated path is shape, not a check.`,
+    '',
+    '```text',
+    ...lines,
+    '```',
+    '',
+    `Never present: ${forbidden.map((row) => `${code(row.path)} (${code(row.id)})`).join(', ')}.`,
+    ...(outside.length === 0 ? [] : [
+      '',
+      `Owned by a row, outside the template: ${outside
+        .map(([, value]) => `${code(value.declared)} (${value.ids.map((id) => code(id)).join(', ')})`)
+        .join(', ')}.`
+    ])
+  ];
+}
+
+function renderLibraryDuties({ libraryManifest, link }) {
+  const discovery = libraryManifest.discovery.library;
+  const categories = Object.entries(discovery.categories);
+  const duties = Object.entries(libraryManifest.duties);
+  const guidance = Object.keys(libraryManifest.guidance || {});
+
+  return [
+    `The categories of the [library uniform](${link}) and the duty sections each one wears. `
+      + 'Row ids only: what a row demands and how it is repaired stays in the manifest.',
+    '',
+    '| category | layer | may depend on |',
+    '|---|---|---|',
+    ...categories.map(([name, block]) => `| ${code(name)} | ${cell(block.layer)} | `
+      + `${block.may_depend_on.length === 0 ? '—' : block.may_depend_on.map((item) => code(item)).join(', ')} |`),
+    '',
+    '| duty section | applies to | rows |',
+    '|---|---|---|',
+    ...duties.map(([name, block]) => `| ${code(name)} | ${code(block.applies_to)} | `
+      + `${block.rows.map((row) => code(row.id)).join(', ')} |`),
+    ...(guidance.length === 0 ? [] : [
+      '',
+      `Guidance — named by the manifest, checked by nothing, so not a rule: `
+        + `${guidance.map((key) => code(key)).join(', ')}.`
+    ])
+  ];
+}
+
+const RENDERERS = Object.freeze({
+  'biz-service-tree': renderTree,
+  'biz-service-scripts': renderScripts,
+  'biz-service-runtime': renderRuntime,
+  'biz-service-alignment': renderAlignment,
+  'library-duties': renderLibraryDuties
+});
+
+/** Which manifest a region needs, so a run without it fails by name and not by `undefined`. */
+const NEEDS_LIBRARY = Object.freeze(['library-duties']);
+
+/**
+ * The text of one region, markers included, LF-terminated lines and no trailing
+ * newline - the caller places it in the file.
+ *
+ * @param {string} id one of REGION_IDS
+ * @param {object} params the manifests, where they lie, and which document this is
+ * @returns {string}
+ */
+function renderRegion(id, {
+  serviceManifest,
+  libraryManifest,
+  serviceManifestPath,
+  libraryManifestPath,
+  targetPath,
+  targetLabel,
+  templateFiles
+} = {}) {
+  requireKnownId(id);
+
+  const usesLibrary = NEEDS_LIBRARY.includes(id);
+  const manifest = usesLibrary ? libraryManifest : serviceManifest;
+  if (manifest === null || typeof manifest !== 'object') {
+    throw new Error(`[DocsRegion] Region "${id}" renders from the ${usesLibrary ? 'library' : 'biz-service'} `
+      + `manifest and got ${JSON.stringify(manifest)}. `
+      + 'Fix: load the manifest with loadManifest() and pass it in.');
+  }
+
+  const link = linkTo(targetPath, usesLibrary ? libraryManifestPath : serviceManifestPath);
+  const markers = markersForRegion(id, targetLabel);
+  const body = RENDERERS[id]({ serviceManifest, libraryManifest, templateFiles, link });
+
+  return [markers.begin, ...body, markers.end].join('\n');
+}
+
+/**
+ * The document with the region replaced. Everything outside the markers comes
+ * back byte-identical.
+ *
+ * A document carrying no markers is a FAILURE, never an insertion: these regions
+ * land in `api/docs/**`, a tree owned by other threads, and a generator that
+ * decides on its own where a section belongs in somebody else's document is
+ * exactly the unsafe side effect `.claude/rules/automation-gates.md` §1
+ * requirement 3 forbids. The message carries the two lines to paste.
+ *
+ * @param {string} fileText
+ * @param {string} id
+ * @param {string} regionText what renderRegion produced
+ * @param {{targetLabel: string}} where
+ * @returns {string}
+ */
+function applyRegion(fileText, id, regionText, { targetLabel } = {}) {
+  if (typeof fileText !== 'string' || typeof regionText !== 'string') {
+    throw new Error('[DocsRegion] applyRegion(fileText, id, regionText) needs two strings - got '
+      + `${typeof fileText} and ${typeof regionText}. Fix: read the document before applying the region.`);
+  }
+  const markers = markersForRegion(id, targetLabel);
+  const applied = replaceRegion(fileText, markers, regionText, { file: targetLabel });
+
+  if (applied === null) {
+    throw new Error(`[DocsRegion] ${targetLabel} carries no region "${id}" - this run replaces a region, and `
+      + 'never decides on its own where one belongs in a document it does not own. '
+      + `Fix: put these two lines where the region belongs, then run the command again:\n`
+      + `${markers.begin}\n${markers.end}`);
+  }
+  return applied;
+}
+
+/**
+ * Whether the region in the document is what the manifests render, and the diff
+ * when it is not. Prose outside the markers is never compared.
+ *
+ * @returns {{ok: boolean, diff: string}}
+ */
+function checkRegion(fileText, id, regionText, { targetLabel } = {}) {
+  if (typeof fileText !== 'string' || typeof regionText !== 'string') {
+    throw new Error('[DocsRegion] checkRegion(fileText, id, regionText) needs two strings - got '
+      + `${typeof fileText} and ${typeof regionText}. Fix: read the document before checking it.`);
+  }
+  requireKnownId(id);
+  return checkAgainst({
+    text: fileText,
+    markers: markersForRegion(id, targetLabel),
+    regionText,
+    source: SOURCES[id]
+  });
+}
+
+module.exports = {
+  REGION_IDS,
+  DESCRIPTIONS,
+  describeRegion,
+  markersForRegion,
+  regenerateCommand,
+  regionIdsIn,
+  renderRegion,
+  applyRegion,
+  checkRegion
+};

package/src/sync/generatedRegion.js

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * One implementation of a generated region in this package.
+ *
+ * The marker shape is `api/scripts/ci/sync-biz-facts.mjs` (`BEGIN`/`END
+ * GENERATED`), taken over verbatim apart from the id and the command. Two
+ * renderers now write regions — `readmePointer.js` (the uniform pointer of a
+ * library README, d.216) and `docsRegion.js` (the descriptive lists of the
+ * documentation tree) — and they find, replace, extract and diff a region
+ * through this module rather than each carrying its own copy of the four
+ * functions (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * What is deliberately NOT here: where a region is placed when the file carries
+ * no markers. That is the one decision the two callers do not share — a library
+ * README gets one inserted after its node header, a document of somebody else's
+ * tree never gets one inserted at all — so it stays with each caller.
+ *
+ * Pure text: nothing here opens a file, reads the environment or knows a path.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-005
+ */
+
+/**
+ * Character offsets of every fenced code block, so a marker shown as an EXAMPLE
+ * is never mistaken for a region.
+ *
+ * Measured on the api side 2026-09-09, hours after the queue generator landed:
+ * `api/docs/standards/INFRA-DOC-STANDARD.md` documents the marker pair inside a
+ * fence (still does, at the section on generated regions), the generator read
+ * raw text, and it took its own documentation for a region naming a queue family
+ * that does not exist — a gate red on the tree it had just been added to
+ * (`.claude/rules/automation-gates.md` §3). `api/scripts/ci/lib/generatedRegion.js`
+ * has carried the fix since; this module, writing the same marker shape into the
+ * same tree, did not, so one input had two answers depending on which module met
+ * it (`automation-gates.md` §1.1, predictable). The documents `docsRegion.js`
+ * writes into are precisely the ones that TEACH the shape.
+ *
+ * @param {string} text
+ * @returns {Array<[number, number]>}
+ */
+function fencedRanges(text) {
+  const ranges = [];
+  let offset = 0;
+  let openedAt = null;
+  for (const line of text.split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      if (openedAt === null) openedAt = offset;
+      else { ranges.push([openedAt, offset + line.length]); openedAt = null; }
+    }
+    offset += line.length + 1;
+  }
+  // An unterminated fence swallows the rest of the document, which is what a
+  // renderer does too.
+  if (openedAt !== null) ranges.push([openedAt, text.length]);
+  return ranges;
+}
+
+function isFenced(ranges, index) {
+  return ranges.some(([from, to]) => index >= from && index < to);
+}
+
+/** First occurrence of `needle` that is not inside a fence, or -1. */
+function indexOutsideFence(text, needle, ranges) {
+  let at = text.indexOf(needle);
+  while (at !== -1 && isFenced(ranges, at)) at = text.indexOf(needle, at + 1);
+  return at;
+}
+
+/**
+ * The two marker lines of one region.
+ *
+ * @param {string} id the region's id, unique within the file it lands in
+ * @param {string} regenerate the command that rewrites it, printed in the marker
+ * @returns {{begin: string, end: string}}
+ */
+function markersFor(id, regenerate) {
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error('[GeneratedRegion] Region id is required - markersFor(id, regenerate) got '
+      + `${JSON.stringify(id)}. Fix: pass the id the document carries in its markers.`);
+  }
+  if (typeof regenerate !== 'string' || regenerate.length === 0) {
+    throw new Error('[GeneratedRegion] Regenerate command is required - a marker that does not say what '
+      + `rewrites the region leaves the reader nothing to run, and markersFor got ${JSON.stringify(regenerate)}. `
+      + 'Fix: pass the exact command.');
+  }
+  return {
+    begin: `<!-- BEGIN GENERATED: ${id} — regenerate: ${regenerate} -->`,
+    end: `<!-- END GENERATED: ${id} -->`
+  };
+}
+
+/**
+ * Where the region sits in the text, or null when the text carries none.
+ *
+ * Damaged markers throw rather than being worked around: a half-written or
+ * inverted pair cannot be replaced in place without eating the file
+ * (`.claude/rules/architecture-principles.md` §3 - no fallbacks).
+ *
+ * The message names THIS module, not the caller: the error-message contract of
+ * this package is checked statically over the source
+ * (`tests/unit/error-message-contract.test.js`), so a prefix passed in as a
+ * parameter would be invisible to it — and `[GeneratedRegion]` is in any case
+ * the honest answer to "what rejected this". Which file the damaged markers are
+ * in is the caller's to say, and it travels in the message.
+ *
+ * @param {string} text
+ * @param {{begin: string, end: string}} markers
+ * @param {{file: string}} where the document the region belongs to, for the fix line
+ * @returns {{start: number, endExclusive: number}|null}
+ */
+function findRegion(text, markers, { file } = {}) {
+  const ranges = fencedRanges(text);
+  // Both markers are searched from the start of the document, NOT the END from
+  // the BEGIN onwards: searching forward from BEGIN can never yield an END
+  // before it, so the inversion branch below would be dead code and a malformed
+  // document would render nothing while the run said nothing
+  // (`automation-gates.md` §5).
+  const begin = indexOutsideFence(text, markers.begin, ranges);
+  const end = indexOutsideFence(text, markers.end, ranges);
+
+  if (begin === -1 && end === -1) return null;
+  if (begin !== -1 && end !== -1 && end < begin) {
+    throw new Error('[GeneratedRegion] Generated region has END before BEGIN - the markers are damaged and '
+      + `replacing in place would eat the file. Fix: repair or delete the region in ${file}.`);
+  }
+  if (begin === -1 || end === -1) {
+    throw new Error('[GeneratedRegion] Generated region has only one marker - a half-written region cannot be '
+      + `replaced in place. Fix: remove the stray marker from ${file} and run the generator again.`);
+  }
+  return { start: begin, endExclusive: end + markers.end.length };
+}
+
+/**
+ * The text with the region replaced, or null when the text carries no region.
+ * Everything outside the markers comes back byte-identical.
+ *
+ * @returns {string|null}
+ */
+function replaceRegion(text, markers, regionText, where) {
+  const found = findRegion(text, markers, where);
+  if (found === null) return null;
+  return text.slice(0, found.start) + regionText + text.slice(found.endExclusive);
+}
+
+/**
+ * The region as it stands in the text, or null when there is none. Tolerant by
+ * design: a check reports "no region" rather than throwing, because the caller
+ * turns that into a finding with a fix.
+ *
+ * @returns {string|null}
+ */
+function extractRegion(text, markers) {
+  const ranges = fencedRanges(text);
+  const begin = indexOutsideFence(text, markers.begin, ranges);
+  const end = indexOutsideFence(text, markers.end, ranges);
+  if (begin === -1 || end === -1 || end < begin) return null;
+  return text.slice(begin, end + markers.end.length);
+}
+
+/**
+ * Whether the document DECLARES the region — the question `--all` asks before it
+ * renders anything.
+ *
+ * It is the only place that question is answered: a caller matching the marker
+ * string itself would be a second, fence-blind copy of this module's rule
+ * (`.claude/rules/change-discipline.md` § One rail per concern), which is what
+ * `docsRegion.regionIdsIn` was until d.319.
+ *
+ * A half-written region answers TRUE: the damage belongs in the report the
+ * caller produces, and answering "not declared" would hide it.
+ *
+ * @param {string} text
+ * @param {{begin: string, end: string}} markers
+ * @returns {boolean}
+ */
+function hasRegion(text, markers) {
+  const ranges = fencedRanges(text);
+  return indexOutsideFence(text, markers.begin, ranges) !== -1
+    || indexOutsideFence(text, markers.end, ranges) !== -1;
+}
+
+/**
+ * The drift, named line by line, so a failing check says what differs instead of
+ * announcing that something does (`.claude/rules/automation-gates.md` §1
+ * requirement 4).
+ *
+ * @param {{expected: string, actual: string|null, source: string}} params
+ * @returns {string}
+ */
+function renderDiff({ expected, actual, source }) {
+  if (actual === null) {
+    return [
+      `--- rendered from ${source}`,
+      '+++ on disk: no generated region',
+      ...expected.split('\n').map((line) => `-${line}`)
+    ].join('\n');
+  }
+  return [
+    `--- rendered from ${source}`,
+    '+++ on disk',
+    ...expected.split('\n').map((line) => `-${line}`),
+    ...actual.split('\n').map((line) => `+${line}`)
+  ].join('\n');
+}
+
+/**
+ * Whether the region on disk is what the renderer produces, and the diff when it
+ * is not. Only the region is compared; prose outside the markers is nobody's
+ * generated output.
+ *
+ * @returns {{ok: boolean, diff: string}} `diff` is '' exactly when `ok` is true
+ */
+function checkRegion({ text, markers, regionText, source }) {
+  const actual = extractRegion(text, markers);
+  if (actual === regionText) return { ok: true, diff: '' };
+  return { ok: false, diff: renderDiff({ expected: regionText, actual, source }) };
+}
+
+module.exports = {
+  markersFor,
+  findRegion,
+  hasRegion,
+  replaceRegion,
+  extractRegion,
+  renderDiff,
+  checkRegion
+};