@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/sync/readmeLocation.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * WHERE a README's uniform pointer points, for each of the two bearer kinds —
+ * and therefore WHICH region that README should carry.
+ *
+ * `readmePointer.js` renders the region and knows no path of its own; this
+ * module is the half that touches the disk. It exists because since d.215e the
+ * region has TWO readers — the generator (`oa-sync-template readme-uniform`) and
+ * the conformance rows `G-README` / `L-README-REGION` — and a link computed two
+ * ways would be a region that is stale by construction on one of the two
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * The two kinds differ, and the difference is not a preference:
+ *
+ *   * a SERVICE repository is its own checkout, so its region links at the
+ *     manifest as the repository reaches it after `npm install` — the copy the
+ *     pin decides and the one `oa-validate` reads there. Nothing above the
+ *     repository is consulted, which is what lets the row answer in a container;
+ *   * a LIBRARY lies beside this package in one checkout, so its region links at
+ *     the manifest AS IT LIES THERE, found through the manifest's own discovery
+ *     rather than through a path anybody typed.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-005
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadManifest, DEFAULT_MANIFEST_PATH, LIBRARY_MANIFEST_PATH } = require('../manifest/loadManifest');
+const {
+  API_CHECKOUT_ROOT, PACKAGE_ROOT: OWN_ROOT, resolveWorkspacePath
+} = require('../manifest/workspaceRoot');
+const { KINDS, renderUniformRegion } = require('./readmePointer');
+
+/** The file the pointer is a region of. */
+const README_FILE = 'README.md';
+
+/**
+ * This package, by the name a consumer installs it under — read when a link
+ * needs it, never at load time. Only the biz-service pointer names the package
+ * (its link goes through node_modules); a library pointer links inside the
+ * checkout and needs no name. A copy of the engine that carries src/ and
+ * manifests/ but no package.json (the pre-push hook's fixture repo is one) can
+ * therefore judge a library without this file, and a service run that lacks it
+ * fails here with the cause named, not with a module-load stack trace.
+ *
+ * @returns {string}
+ */
+function selfName() {
+  const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    throw new Error(`[ReadmeLocation] This copy of the engine carries no package.json - ${pkgPath} is missing, `
+      + 'so the biz-service pointer cannot say under which name a bearer installs the manifest. '
+      + 'Fix: run the engine from an installed package or a full checkout of api/shared/connector/conn-orch-validator.');
+  }
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).name;
+}
+
+/** This package's own root, from this file's place in it. */
+const PACKAGE_ROOT = path.join(__dirname, '..', '..');
+
+/** Where each manifest sits inside this package — derived, never typed. */
+const SERVICE_MANIFEST_IN_PACKAGE = path.relative(PACKAGE_ROOT, DEFAULT_MANIFEST_PATH);
+const LIBRARY_MANIFEST_IN_PACKAGE = path.relative(PACKAGE_ROOT, LIBRARY_MANIFEST_PATH);
+
+/**
+ * The service uniform's manifest as the service repository reaches it.
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {string} absolute path
+ */
+function serviceManifestPath(serviceRoot) {
+  return path.join(serviceRoot, 'node_modules', ...selfName().split('/'), SERVICE_MANIFEST_IN_PACKAGE);
+}
+
+/**
+ * Where this package lies inside its own workspace, workspace-relative — or null
+ * when it lies in no checkout at all (an installed copy, a service container).
+ *
+ * It is what a row declares through `requiresSiblings`, so a run over a
+ * workspace that carries no copy of this package is reported NOT RUN by the
+ * runner rather than failing inside the render: a library README's link points
+ * at the manifest AS IT LIES IN THAT CHECKOUT, and where there is no copy there
+ * is no link — which is a question the run could not answer, never a package
+ * that passed (`.claude/rules/automation-gates.md` §5).
+ */
+const PACKAGE_IN_WORKSPACE = API_CHECKOUT_ROOT === null
+  ? null
+  : path.relative(path.dirname(API_CHECKOUT_ROOT), OWN_ROOT).split(path.sep).join('/');
+
+/**
+ * The manifest as it lies in the workspace being read, whichever of the two it
+ * is.
+ *
+ * The link a README carries has to resolve for a reader of THAT checkout, so it
+ * cannot point at an installed copy under `node_modules`. The position is this
+ * package's own, workspace-relative — the same string `requiresSiblings`
+ * declares, so what a row says it needs and what this function reads are one
+ * fact, and a workspace missing it is reported NOT RUN by the runner rather than
+ * throwing in the middle of a render.
+ *
+ * @param {{workspaceRoot: string, relativeInPackage?: string}} params
+ * @returns {string} absolute path to the manifest inside that workspace
+ */
+function manifestInWorkspace({ workspaceRoot, relativeInPackage = LIBRARY_MANIFEST_IN_PACKAGE }) {
+  if (PACKAGE_IN_WORKSPACE === null) {
+    throw new Error(`[ReadmeLocation] This copy of ${selfName()} lies in no checkout - the region links at the `
+      + 'manifest as it lies in the repository being read, and an installed copy under node_modules is not '
+      + 'that. Fix: run from the checkout that carries the package sources.');
+  }
+
+  const dir = resolveWorkspacePath(workspaceRoot, PACKAGE_IN_WORKSPACE);
+  if (!fs.existsSync(dir)) {
+    throw new Error(`[ReadmeLocation] Workspace holds no ${selfName()} - the region links at the manifest as `
+      + `it lies in the repository being read, and ${workspaceRoot} carries no ${PACKAGE_IN_WORKSPACE}. `
+      + 'Fix: run over the workspace whose api/shared/ holds that package.');
+  }
+  return path.join(dir, relativeInPackage);
+}
+
+/**
+ * A repository's README, or null when there is none.
+ *
+ * @param {string} dir repository or package root
+ * @returns {string|null}
+ */
+function readReadme(dir) {
+  const file = path.join(dir, README_FILE);
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return null;
+  return fs.readFileSync(file, 'utf8');
+}
+
+/**
+ * The region a SERVICE repository's README should carry, rendered from the
+ * packaged manifest. Nothing above the repository is read, which is what lets
+ * the row that compares it answer inside a container.
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {string} the region, markers included
+ */
+function serviceRegion(serviceRoot) {
+  return renderUniformRegion({
+    kind: KINDS.service,
+    manifest: loadManifest(DEFAULT_MANIFEST_PATH),
+    packageDir: serviceRoot,
+    manifestPath: serviceManifestPath(serviceRoot)
+  });
+}
+
+/**
+ * The region a LIBRARY's README should carry. The manifest it links at is the
+ * copy lying in the same checkout.
+ *
+ * @param {{packageDir: string, pkg: object, workspaceRoot: string, manifest?: object}} params
+ *   `manifest` is passed by a caller that has already read it, so a run over 28
+ *   packages parses it once.
+ * @returns {string} the region, markers included
+ */
+function libraryRegion({ packageDir, pkg, workspaceRoot, manifest }) {
+  return renderUniformRegion({
+    kind: KINDS.library,
+    manifest: manifest === undefined ? loadManifest(LIBRARY_MANIFEST_PATH) : manifest,
+    pkg,
+    packageDir,
+    manifestPath: manifestInWorkspace({ workspaceRoot })
+  });
+}
+
+module.exports = {
+  README_FILE,
+  selfName,
+  PACKAGE_ROOT,
+  PACKAGE_IN_WORKSPACE,
+  SERVICE_MANIFEST_IN_PACKAGE,
+  LIBRARY_MANIFEST_IN_PACKAGE,
+  serviceManifestPath,
+  manifestInWorkspace,
+  serviceRegion,
+  libraryRegion,
+  readReadme
+};

package/src/sync/readmePointer.js

@@ -0,0 +1,477 @@
+'use strict';
+
+/**
+ * The rendered uniform pointer of a repository README.
+ *
+ * Confirmation `biz-service-manifest` 005 point 2: discoverability is ONE
+ * rendered pointer per repository — a generated region fed by the manifest and
+ * the pin, never typed, rendering which paths of the repository fall under which
+ * duty section. A stale region fails `--check`. Individual files carry no
+ * uniform line; their uniform is their location (005 point 1).
+ *
+ * The confirmation names three bearer kinds in one sentence — `library/<category>`,
+ * `biz-service`, `infra-service` — so the module is parameterised by kind rather
+ * than copied per kind: a second renderer would be two rails under one rule
+ * (`.claude/rules/change-discipline.md` § One rail per concern). What actually
+ * differs is declared as data in `SPECS`: the region id, the command that
+ * regenerates it, the manifest a failed check names, whether the README must
+ * carry a node header, and the body renderer.
+ *
+ * Everything in a region is read from a manifest (and, for a library, from the
+ * one thing a package declares). Nothing is written by hand, which is the whole
+ * point: the section names and the row ids are descriptive facts, and a
+ * hand-kept copy of them in 28 READMEs would rot the day a row moved
+ * (`.claude/rules/doc-code-binding.md` §1).
+ *
+ * Deliberately absent from every region: a date, a package version, a count of
+ * anything. The version a README is checked against IS the pin on this package
+ * (004 — the manifest ships inside it), so a version line would be a second
+ * owner of that fact, and a date would make two runs render different bytes,
+ * which is exactly what stops a generator from being a gate. Equally absent: a
+ * row's `why` and `fix`. Those are prose with an owner, and the region is not it
+ * (the shape d.216 established and d.226 repeated — a region of ids and links,
+ * never of paragraphs).
+ *
+ * Pure functions: nothing here reads `process.env`, opens a file or knows a path
+ * of its own. The caller loads the manifest, reads the README and writes it
+ * (`.claude/rules/architecture-principles.md` §1).
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-005
+ */
+
+const path = require('path');
+
+const { markersFor, replaceRegion, extractRegion: extractBetween, checkRegion } = require('./generatedRegion');
+
+/** The bearer kinds this package renders a pointer for. */
+const KINDS = Object.freeze({ library: 'library', service: 'service' });
+
+/** `applies_to` of the section every library wears, whatever it is for. */
+const ALL_CATEGORIES = '*';
+
+/**
+ * The top-level block naming which repositories wear the uniform. Its rows are
+ * the sentence above the duty sections, so they are not ALSO a section: one fact
+ * reaches the reader once (`api/.claude/rules/single-source-of-truth.md`, applied
+ * to the rendered text).
+ */
+const DISCOVERY_SECTION = 'discovery';
+
+/** The file every error of this module is about; the prefix is generatedRegion.js's own. */
+const WHERE = Object.freeze({ file: 'README.md' });
+
+const code = (value) => `\`${value}\``;
+
+/**
+ * The category the package DECLARES. It is the one fact about a library that
+ * cannot be derived — the intent — so its absence is reported, never defaulted
+ * (005 point 3). A service declares nothing of the sort: the uniform it wears
+ * follows from its location, which is why the service body takes no package.
+ *
+ * @param {object|null} pkg parsed package.json
+ * @returns {string|null}
+ */
+function declaredCategory(pkg) {
+  const declared = pkg && pkg.oa ? pkg.oa.category : undefined;
+  return typeof declared === 'string' && declared.length > 0 ? declared : null;
+}
+
+function categoriesOf(manifest) {
+  const categories = manifest && manifest.discovery && manifest.discovery.library
+    ? manifest.discovery.library.categories
+    : undefined;
+  if (categories === null || typeof categories !== 'object' || Array.isArray(categories)) {
+    throw new Error('[ReadmePointer] Manifest declares no discovery.library.categories - the pointer names '
+      + 'the category the manifest knows and never invents one. '
+      + 'Fix: repair manifests/library.manifest.json.');
+  }
+  return categories;
+}
+
+function dutiesOf(manifest) {
+  const duties = manifest ? manifest.duties : undefined;
+  if (duties === null || typeof duties !== 'object' || Array.isArray(duties)) {
+    throw new Error('[ReadmePointer] Manifest declares no duties - the region renders which duty sections '
+      + 'apply to the package. Fix: repair manifests/library.manifest.json.');
+  }
+  return duties;
+}
+
+/**
+ * The link target as the two paths compute it, `/`-separated and relative, with
+ * `./` in front when it does not already start with a `.` — a bare
+ * `manifests/…` reads as a path, `./manifests/…` reads as a link.
+ */
+function linkTo({ packageDir, manifestPath }) {
+  if (typeof packageDir !== 'string' || packageDir.length === 0
+    || typeof manifestPath !== 'string' || manifestPath.length === 0) {
+    throw new Error('[ReadmePointer] packageDir and manifestPath are required - the link is computed from '
+      + 'them and never written by hand. Fix: pass both absolute paths.');
+  }
+  const relative = path.relative(packageDir, manifestPath).split(path.sep).join('/');
+  return relative.startsWith('.') ? relative : `./${relative}`;
+}
+
+/* ------------------------------------------------------------------- bodies */
+
+/**
+ * The library body: the pointer line, then the duty sections that apply to this
+ * package's declared category, each with the ids of its rows in manifest order.
+ */
+function renderLibraryBody({ manifest, pkg, link }) {
+  const categories = categoriesOf(manifest);
+  const duties = dutiesOf(manifest);
+
+  const category = declaredCategory(pkg);
+  if (category === null) {
+    throw new Error('[ReadmePointer] Package declares no "oa"."category" - the layer a package is meant to '
+      + 'sit in cannot be derived from anything else, so the pointer cannot be rendered. '
+      + 'Fix: declare "oa": { "category": "<core|connector|orchestration|runtime|tooling>" } in package.json.');
+  }
+  if (!Object.prototype.hasOwnProperty.call(categories, category)) {
+    throw new Error(`[ReadmePointer] Unknown category "${category}" - the manifest knows `
+      + `${Object.keys(categories).join(', ')}. `
+      + 'Fix: declare one of those in package.json, or add the category to manifests/library.manifest.json.');
+  }
+
+  const sections = Object.entries(duties)
+    .filter(([, block]) => block && (block.applies_to === ALL_CATEGORIES || block.applies_to === category))
+    .map(([name, block]) => {
+      const rows = Array.isArray(block.rows) ? block.rows : [];
+      if (rows.length === 0) {
+        throw new Error(`[ReadmePointer] Duty section "${name}" has no rows - a section with nothing to `
+          + 'check is not a duty. Fix: repair manifests/library.manifest.json.');
+      }
+      return `- ${code(name)}: ${rows.map((row) => row.id).join(', ')}`;
+    });
+
+  return [
+    `Uniform: [library/${category}](${link})`,
+    '',
+    'Duty sections that apply:',
+    '',
+    ...sections
+  ];
+}
+
+/**
+ * Every row of a manifest, in declaration order, each carrying the top-level
+ * section that holds it and the array it sits in.
+ *
+ * Read rather than enumerated: a row added to the manifest reaches every README
+ * without this file being edited, which is the difference between a generated
+ * region and a hand-kept list (`.claude/rules/doc-code-binding.md` §1).
+ *
+ * @returns {Array<{row: object, section: string, group: string|null}>}
+ */
+function rowsOf(manifest) {
+  const found = [];
+  const walk = (node, section, group) => {
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        if (item !== null && typeof item === 'object' && typeof item.id === 'string') {
+          found.push({ row: item, section, group });
+        } else walk(item, section, group);
+      }
+      return;
+    }
+    if (node !== null && typeof node === 'object') {
+      for (const [key, value] of Object.entries(node)) {
+        walk(value, section, Array.isArray(value) ? key : group);
+      }
+    }
+  };
+  for (const [key, value] of Object.entries(manifest)) walk(value, key, null);
+  return found;
+}
+
+/**
+ * The path that OWNS a row's value, when the row takes one from elsewhere (004).
+ *
+ * A reference into this package (d.229) is rendered as the reader of THIS
+ * repository reaches it: under `node_modules`, beside the manifest the pointer
+ * links at. The prefix is not typed here — it is the link the caller computed,
+ * with the manifest's own position inside the package taken off it — so one
+ * fact (where this package lies, from here) has one owner.
+ *
+ * @param {object} row the manifest row
+ * @param {{link: string, source: string}} where the region's link and the manifest's path in the package
+ * @returns {string|null}
+ */
+function ownerOf(row, { link, source } = {}) {
+  const from = row.from;
+  if (from === null || typeof from !== 'object') return null;
+  if (typeof from.package === 'string' && from.package.length > 0) {
+    return `${packageRootOf({ link, source })}/${from.package}`;
+  }
+  return typeof from.path === 'string' ? from.path : null;
+}
+
+/**
+ * Where this package lies, as the README's own link already says it: the link
+ * minus the manifest's position inside the package.
+ *
+ * @param {{link: string, source: string}} params
+ * @returns {string}
+ */
+function packageRootOf({ link, source } = {}) {
+  if (typeof link !== 'string' || typeof source !== 'string' || !link.endsWith(`/${source}`)) {
+    throw new Error(`[ReadmePointer] The manifest link does not end in ${JSON.stringify(source)} - a row `
+      + 'referencing a file this package carries is rendered relative to where the link says the package '
+      + `lies, and ${JSON.stringify(link)} does not say. `
+      + 'Fix: pass the link this kind\'s manifest was rendered with.');
+  }
+  return link.slice(0, -`/${source}`.length);
+}
+
+/**
+ * The discovery sentence: which repositories wear this uniform, and who says
+ * they exist. Both halves are the discovery block's own — the pattern it
+ * matches and the SSOT it is bound to — so the sentence carries no name this
+ * file knows.
+ */
+function discoverySentence({ manifest }) {
+  const block = manifest[DISCOVERY_SECTION] ? manifest[DISCOVERY_SECTION][manifest.uniform] : undefined;
+  if (block === null || typeof block !== 'object' || typeof block.pattern !== 'string'
+    || ownerOf(block) === null || !Array.isArray(block.rows)) {
+    throw new Error(`[ReadmePointer] Manifest "${manifest.uniform}" names no discovery block with a pattern, `
+      + 'a from: reference and rows - the pointer says which repositories wear the uniform and never '
+      + 'invents that list. Fix: repair manifests/biz-service.manifest.json.');
+  }
+  const rows = block.rows.map((row) => code(row.id)).join(', ');
+  return `Every ${code(block.pattern)} that ${code(ownerOf(block))} lists wears it (${rows}).`;
+}
+
+/**
+ * The service body: the pointer line, who wears the uniform, the row ids grouped
+ * by the section that declares them, and which path falls under which row.
+ *
+ * The paths are the rows' own `path` values — 005 point 2's "which paths of the
+ * repository fall under which duty section" — and a row taking its value from
+ * elsewhere renders the OWNER of that value, never the value (004:
+ * "`api/.nvmrc`" stays true when the platform moves to the next major, "Node 24"
+ * does not).
+ *
+ * A FORBIDDEN row names its path like every other row. Until d.215e it did not,
+ * and the reason was not about the reader: `api/tests/scripts/add-service.bats`
+ * grepped the WHOLE template for `hooks/pre-commit`, so a region mentioning the
+ * retired path failed a test whose subject is whether `init.sh` still INSTALLS
+ * the hook. The test now asks that of the files that could install it, which is
+ * what it always meant, and the region stopped bending around it — a generated
+ * list that omits a row's path because of where the text lands is a list that
+ * says less than the manifest does (`.claude/rules/doc-code-binding.md` §1).
+ */
+function renderServiceBody({ manifest, link, source }) {
+  const rows = rowsOf(manifest);
+  if (rows.length === 0) {
+    throw new Error('[ReadmePointer] Manifest declares no rows - a uniform that checks nothing is not a '
+      + 'uniform. Fix: repair manifests/biz-service.manifest.json.');
+  }
+
+  const sections = new Map();
+  const owned = new Map();
+
+  for (const { row, section } of rows) {
+    if (section !== DISCOVERY_SECTION) {
+      if (!sections.has(section)) sections.set(section, []);
+      sections.get(section).push(row.id);
+    }
+    if (typeof row.path !== 'string') continue;
+    if (!owned.has(row.path)) owned.set(row.path, []);
+    const from = ownerOf(row, { link, source });
+    owned.get(row.path).push(from === null ? row.id : `${row.id} (from ${code(from)})`);
+  }
+
+  const pathLines = [...owned.keys()].sort()
+    .map((relative) => `- ${code(relative)}: ${owned.get(relative).join(', ')}`);
+
+  return [
+    `Uniform: [${manifest.uniform}](${link})`,
+    '',
+    discoverySentence({ manifest }),
+    '',
+    'Duty sections that apply:',
+    '',
+    ...[...sections.entries()].map(([name, ids]) => `- ${code(name)}: ${ids.join(', ')}`),
+    '',
+    'Paths a duty owns:',
+    '',
+    ...pathLines
+  ];
+}
+
+/* -------------------------------------------------------------------- kinds */
+
+/**
+ * What each bearer kind fixes. The marker shape is
+ * `api/scripts/ci/sync-biz-facts.mjs` (`BEGIN`/`END GENERATED`), taken over
+ * verbatim apart from the id and the command, so the workspace has ONE shape of
+ * generated region rather than a second dialect of the same idea. Finding,
+ * replacing, extracting and diffing a region is `generatedRegion.js`, shared
+ * with `docsRegion.js`.
+ *
+ * `header_required` is the one placement decision the kinds do not share. A
+ * library README must open with the node header — d.213b gave all 28 packages
+ * one, and row `L-README` of the library manifest requires it — so its absence
+ * means the run was pointed at something that is not a library README, and the
+ * region is not guessed at. Nothing requires a header of a SERVICE README (no
+ * row does), so there the pointer simply takes the first line of the file, which
+ * is what 005 point 2 asks for.
+ *
+ * The regenerate command differs for the same reason `--all` does: libraries all
+ * live in one checkout, and a service repository is its own.
+ */
+const SPECS = Object.freeze({
+  [KINDS.library]: Object.freeze({
+    region_id: 'library-uniform',
+    regenerate: 'npx oa-sync-template readme-uniform --all',
+    source: 'manifests/library.manifest.json',
+    header_required: true,
+    body: renderLibraryBody
+  }),
+  [KINDS.service]: Object.freeze({
+    region_id: 'biz-service-uniform',
+    regenerate: 'npx oa-sync-template readme-uniform --target .',
+    source: 'manifests/biz-service.manifest.json',
+    header_required: false,
+    body: renderServiceBody
+  })
+});
+
+function specOf(kind) {
+  if (!Object.prototype.hasOwnProperty.call(SPECS, kind)) {
+    throw new Error(`[ReadmePointer] Unknown bearer kind "${kind}" - this package renders `
+      + `${Object.keys(SPECS).join(', ')}. `
+      + 'Fix: name one of those, or declare the kind here before a README asks for it.');
+  }
+  return SPECS[kind];
+}
+
+/**
+ * The two marker lines of one kind's region.
+ *
+ * @param {string} kind one of KINDS
+ * @returns {{begin: string, end: string}}
+ */
+function markersOf(kind) {
+  const spec = specOf(kind);
+  return markersFor(spec.region_id, spec.regenerate);
+}
+
+/**
+ * The region text the manifest describes, markers included. LF endings, no
+ * trailing newline — the caller places it in the file.
+ *
+ * @param {{kind: string, manifest: object, pkg?: object, packageDir: string, manifestPath: string}} params
+ *   `packageDir` and `manifestPath` are what the link is computed from; the
+ *   signature carries them because a pure function cannot look them up. `pkg` is
+ *   read by the library kind only — a service declares no category.
+ * @returns {string}
+ */
+function renderUniformRegion({ kind, manifest, pkg, packageDir, manifestPath } = {}) {
+  const spec = specOf(kind);
+  const markers = markersOf(kind);
+  const link = linkTo({ packageDir, manifestPath });
+
+  return [markers.begin, ...spec.body({ manifest, pkg, link, source: spec.source }), markers.end].join('\n');
+}
+
+/**
+ * Where the node header ends: the run of `>` lines the file opens with, followed
+ * by one blank line (`api/docs/standards/INFRA-DOC-STANDARD.md`; L-README checks
+ * the same block). The region goes immediately after that blank line, so the
+ * header keeps the first lines and the pointer still precedes the heading.
+ *
+ * A file with no header is refused for a kind that requires one, and takes the
+ * region on its first line for a kind that does not (see `SPECS`).
+ *
+ * @returns {number} index of the first line the region may be inserted before
+ */
+function headerEnd(lines, { required }) {
+  if (lines.length === 0 || !lines[0].startsWith('>')) {
+    if (!required) return 0;
+    throw new Error('[ReadmePointer] README has no node header - the file must open with the '
+      + '"> Status:" / "> Owns:" block, and the region is placed after it. '
+      + 'Fix: give README.md the node header (api/docs/standards/INFRA-DOC-STANDARD.md).');
+  }
+
+  let index = 0;
+  while (index < lines.length && lines[index].startsWith('>')) index += 1;
+
+  if (lines[index] !== '') {
+    throw new Error('[ReadmePointer] Node header is not followed by a blank line - the region is placed '
+      + `after it and the shape has to be unambiguous, but line ${index + 1} is `
+      + `${JSON.stringify(lines[index] === undefined ? null : lines[index])}. `
+      + 'Fix: leave one blank line between the "> " block and the rest of README.md.');
+  }
+  return index + 1;
+}
+
+/**
+ * The README with the region in it: replaced where one already exists, inserted
+ * where none does. Everything outside the markers is returned byte-identical — a
+ * README is mostly prose nobody generated.
+ *
+ * @param {string} readmeText the file's current content
+ * @param {string} regionText what `renderUniformRegion` produced
+ * @param {{kind: string}} params which kind's markers this is
+ * @returns {string}
+ */
+function applyUniformRegion(readmeText, regionText, { kind } = {}) {
+  const spec = specOf(kind);
+  if (typeof readmeText !== 'string' || typeof regionText !== 'string') {
+    throw new Error('[ReadmePointer] applyUniformRegion(readmeText, regionText) needs two strings - got '
+      + `${typeof readmeText} and ${typeof regionText}. Fix: read the README before applying the region.`);
+  }
+
+  const replaced = replaceRegion(readmeText, markersOf(kind), regionText, WHERE);
+  if (replaced !== null) return replaced;
+
+  const lines = readmeText.split('\n');
+  const insertAt = headerEnd(lines, { required: spec.header_required });
+  return [...lines.slice(0, insertAt), regionText, '', ...lines.slice(insertAt)].join('\n');
+}
+
+/**
+ * The region on disk, or null when the file carries none of this kind's.
+ */
+function extractRegion(readmeText, { kind } = {}) {
+  return extractBetween(readmeText, markersOf(kind));
+}
+
+/**
+ * Whether the README's region is what the manifest renders, and — when it is not
+ * — the lines that differ, so the failure names the drift instead of announcing
+ * it (`.claude/rules/automation-gates.md` §1 requirement 4).
+ *
+ * Only the region is compared. Prose outside the markers is nobody's generated
+ * output, and a check that failed on it would fight every documentation edit.
+ *
+ * The diff is a plain expected/actual block rather than the prefix-suffix
+ * trimming `sharedEnv.js` does over a 40-key env file: a region is short enough
+ * that trimming it hides more than it saves.
+ *
+ * @param {string} readmeText
+ * @param {string} regionText
+ * @param {{kind: string}} params
+ * @returns {{ok: boolean, diff: string}} `diff` is '' exactly when `ok` is true
+ */
+function checkUniformRegion(readmeText, regionText, { kind } = {}) {
+  const spec = specOf(kind);
+  if (typeof readmeText !== 'string' || typeof regionText !== 'string') {
+    throw new Error('[ReadmePointer] checkUniformRegion(readmeText, regionText) needs two strings - got '
+      + `${typeof readmeText} and ${typeof regionText}. Fix: read the README before checking it.`);
+  }
+
+  return checkRegion({ text: readmeText, markers: markersOf(kind), regionText, source: spec.source });
+}
+
+module.exports = {
+  KINDS,
+  markersOf,
+  renderUniformRegion,
+  applyUniformRegion,
+  checkUniformRegion,
+  extractRegion,
+  declaredCategory
+};