@onlineapps/conn-orch-validator 12.2.0 → 13.0.0

package/src/lint/scripts/lintScripts.js

@@ -54,6 +54,8 @@
 const fs = require('fs');
 const path = require('path');
 
+const { API_PREFIX } = require('../../manifest/workspaceRoot');
+
 /** The five header fields, in the order SCRIPTS-STANDARD §1 writes them. */
 const ORDER = Object.freeze(['Owns', 'Usage', 'Shell', 'Exit', 'Status']);
 
@@ -142,8 +144,13 @@ const COMMENT_LINE = /^\s*#/;
  */
 const INERT_ASSERTION = Object.freeze([/^\s*!\s/, /\|\|\s*!\s/]);
 
-/** The prefix a citation of the api checkout opens with, as every document writes it. */
-const API_PREFIX = 'api/';
+/**
+ * The prefix a citation of the api checkout opens with, as every document writes
+ * it: the checkout's conventional name from its one owner
+ * (`src/manifest/workspaceRoot.js` § `API_PREFIX`), and the separator that makes
+ * it a path head rather than a word a file name could start with.
+ */
+const API_CITATION_PREFIX = `${API_PREFIX}/`;
 
 /**
  * Every file under `dir` whose name matches, depth first, as `/`-separated
@@ -175,9 +182,9 @@ function walk(dir, root, matches) {
  * @returns {string|null} the absolute path to test, or null when unresolvable here
  */
 function resolveSeeTarget({ target, root, apiRoot }) {
-  if (!target.startsWith(API_PREFIX)) return path.join(root, target);
+  if (!target.startsWith(API_CITATION_PREFIX)) return path.join(root, target);
   if (apiRoot === null) return null;
-  return path.join(apiRoot, target.slice(API_PREFIX.length));
+  return path.join(apiRoot, target.slice(API_CITATION_PREFIX.length));
 }
 
 /**

package/src/manifest/checks/libraryContext.js

@@ -15,6 +15,7 @@ const fs = require('fs');
 const path = require('path');
 
 const { CHECK_SCOPES } = require('../manifestShape');
+const { workspaceRelativeOf } = require('../workspaceRoot');
 
 /** The scopes whose `where` is read from the workspace root — every one but `service`. */
 const WORKSPACE_RELATIVE_SCOPES = Object.freeze(CHECK_SCOPES.filter((scope) => scope !== 'service'));
@@ -107,6 +108,10 @@ function readPackage(serviceRoot) {
  * A `scope: workspace` check keeps the strict rule — it reports ABOUT the
  * workspace, so without one it must not report at all.
  *
+ * How the path is SPELLED is not this function's to decide: a bearer inside the
+ * api checkout is written `api/…` whatever that checkout is named, and
+ * `workspaceRoot.js` § workspaceRelativeOf owns that rule for every reader of it.
+ *
  * @param {{ scope: string, serviceRoot: string, workspaceRoot: string|null, relative?: string }} params
  * @returns {string}
  */
@@ -122,9 +127,7 @@ function whereOf({ scope, serviceRoot, workspaceRoot, relative = '' }) {
       + 'place it. Fix: such a check runs only when the workspace root resolved.');
   }
 
-  const dir = placeable
-    ? path.relative(workspaceRoot, path.resolve(serviceRoot)).split(path.sep).join('/')
-    : '';
+  const dir = placeable ? workspaceRelativeOf(workspaceRoot, serviceRoot) : '';
   if (dir === '' || dir.startsWith('..')) return relative;
   return relative ? `${dir}/${relative}` : dir;
 }

package/src/manifest/checks/libraryDocs.js

@@ -14,6 +14,7 @@ const fs = require('fs');
 const path = require('path');
 
 const { readPackage, readText, whereOf, appliesTo } = require('./libraryContext');
+const { README_FILE } = require('../../sync/readmeFile');
 
 /**
  * The node header, in the blockquote shape the infra standard fixes. `Owns:` must
@@ -25,6 +26,32 @@ const OWNS = /^>[ \t]*Owns:[ \t]*\S/m;
 const STATUS = /^>[ \t]*Status:[ \t]*(\S+)/m;
 const STATUS_VALUES = Object.freeze(['current', 'draft', 'archived']);
 
+/**
+ * A package version written into a README by hand.
+ *
+ * A version is a DESCRIPTIVE fact, and a descriptive fact written by hand is a
+ * lie with a commencement date (`.claude/rules/doc-code-binding.md` §1). It has
+ * ONE owner, `package.json`, and the publish path reads it from there. Measured
+ * 2026-09-20: `error-handler-core`'s README footer said `Version: 1.0.0` while
+ * the package was `3.0.0` — two majors stale, and no mechanism on the platform
+ * said a word.
+ *
+ * Two shapes, and both are narrow ON PURPOSE:
+ *   - `Version: 1.2.3` — the digits must follow the label directly, so a
+ *     configuration example (`serviceVersion: '1.0.0'`, quoted) does not light
+ *     up. A README teaching an API shows values, and a gate that fires on the
+ *     teaching is a gate people learn to work around;
+ *   - a standalone `v1.2.3` — the footer spelling, bounded on both sides, so
+ *     `@onlineapps/lib-v2` and prose like "serverv1.2.3" are not matches.
+ * A dotted triple with no label at all is NOT matched: `docs/biz/…` paths,
+ * dates and dependency tables carry those, and the false finding would cost more
+ * than the fact is worth.
+ */
+const README_VERSION_SHAPES = Object.freeze([
+  /[Vv]ersion:[ \t]*\d+\.\d+\.\d+/,
+  /(^|[\s(*_])v\d+\.\d+\.\d+([\s)*_.,]|$)/m
+]);
+
 const filePresent = Object.freeze({
   scope: 'service',
   requires: Object.freeze(['path']),
@@ -49,9 +76,13 @@ const libraryReadme = Object.freeze({
     const { json } = readPackage(serviceRoot);
     if (json === null || !appliesTo(block, json)) return [];
 
-    const where = whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative: 'README.md' });
-    const body = readText(path.join(serviceRoot, 'README.md'));
-    if (body === null) return [{ where, what: 'README.md is absent — the package documents nothing' }];
+    // The file name is `readmeFile.js`'s fact, not this row's: row `L-README`
+    // declares no `path` (unlike `L-README-REGION` one row down), so there is
+    // nothing here to read it off, and a literal would be the package's fifth
+    // copy of one name (`.claude/rules/change-discipline.md` § One rail).
+    const where = whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative: README_FILE });
+    const body = readText(path.join(serviceRoot, README_FILE));
+    if (body === null) return [{ where, what: `${README_FILE} is absent — the package documents nothing` }];
 
     const problems = [];
     if (!OWNS.test(body)) problems.push('no "> Owns:" line');
@@ -62,14 +93,153 @@ const libraryReadme = Object.freeze({
       problems.push(`Status "${status[1]}" is not one of ${STATUS_VALUES.join(', ')}`);
     }
 
+    for (const shape of README_VERSION_SHAPES) {
+      const written = shape.exec(body);
+      if (written !== null) {
+        problems.push(`writes the package version by hand ("${written[0].trim()}") — package.json owns it`);
+      }
+    }
+
     if (problems.length === 0) return [];
     return [{ where, what: `the node header does not hold: ${problems.join('; ')}` }];
   }
 });
 
+/**
+ * A version heading of a CHANGELOG, in either shape this tree writes:
+ * `## [1.0.3] — 2026-09-15`, `## [Unreleased]`, or the bare `## 1.0.0`.
+ *
+ * The shape is NOT what this row is about, so both are read. Demanding brackets
+ * would smuggle a second rule — a formatting one — into a row whose `why` is
+ * about content, and a rule nobody decided is not a rule a gate may enforce.
+ */
+const CHANGELOG_HEADING = /^##[ \t]+(\S.*?)[ \t]*$/;
+/** A prerelease version (`1.2.3-rc.4`): its entry may still stand under `[Unreleased]`. */
+const PRERELEASE = /^\d+\.\d+\.\d+-[0-9A-Za-z.]+$/;
+const BRACKETED_NAME = /^\[([^\]]+)\]/;
+/** ` — `, ` – ` or ` - ` separating the version from the date behind it. */
+const NAME_AND_DATE = /[ \t]+[—–-][ \t]+/;
+
+/** @returns {string|null} the version a heading line names, or `null` if it is not one */
+function headingName(line) {
+  const heading = CHANGELOG_HEADING.exec(line);
+  if (heading === null) return null;
+
+  const bracketed = BRACKETED_NAME.exec(heading[1]);
+  if (bracketed !== null) return bracketed[1].trim();
+
+  return heading[1].split(NAME_AND_DATE)[0].trim();
+}
+
+/**
+ * The sections of a CHANGELOG in file order: `{ name, body }`, where `body` is
+ * every line up to the next version heading.
+ */
+function changelogSections(text) {
+  const sections = [];
+  let current = null;
+
+  for (const line of text.split('\n')) {
+    const name = headingName(line);
+    if (name !== null) {
+      if (current !== null) sections.push(current);
+      current = { name, body: [] };
+    } else if (current !== null) {
+      current.body.push(line);
+    }
+  }
+  if (current !== null) sections.push(current);
+
+  return sections;
+}
+
+/**
+ * Whether a section SAYS anything. One non-blank line that is not itself a
+ * sub-heading is enough — a pin-only release writes a sentence about the pin and
+ * no `### Changed` above it, and that sentence IS the entry. A lone `### Changed`
+ * with nothing under it is not.
+ */
+function hasContent(section) {
+  return section.body.some((line) => {
+    const trimmed = line.trim();
+    return trimmed !== '' && !/^#{1,6}[ \t]/.test(trimmed);
+  });
+}
+
+/**
+ * `L-CHANGELOG` measures what its `why` says: not that the file exists, but that
+ * the version being published has an entry, and that the entry is not an empty
+ * heading.
+ *
+ * `file-present` was the check here until d.731b, and a file carrying a bare
+ * `## [2.0.1] — 2026-09-15` with nothing under it passed it — the version was
+ * still one nobody can reason about afterwards, which is the row's own reason
+ * for existing. Measured 2026-09-20 over the 28 platform packages: three were in
+ * exactly that state while the row was green (`automation-gates.md` §5 — a
+ * mechanism that checks less than it announces is a false guarantee). The row is
+ * sharpened only now, after those three were written (§3 — a gate lands with
+ * compliance, never ahead of it).
+ *
+ * A prerelease is the one case where the entry may live elsewhere: an rc wave
+ * publishes `X.Y.Z-rc.N` without moving the `[Unreleased]` body into a section of
+ * its own (`.claude/rules/architecture-principles.md` § Release channels), so a
+ * non-empty `[Unreleased]` answers for it.
+ *
+ * WHICH VERSION IS JUDGED — two legitimate questions, not a value and its fallback
+ * (d.1040). A publish asks about the version it is ABOUT to write: the gate's dry
+ * run hands it as `asVersion` (`oa-validate --as-version`), because package.json
+ * still carries the old one until the wave bumps it — judged by that, the row let a
+ * missing `## [NEW]` through and refused a package for an old version nobody was
+ * publishing (d.1033, d.1038). An audit of the tree as it stands asks about the
+ * version package.json names, and passes no `asVersion`. The finding says which of
+ * the two it answered.
+ */
+const libraryChangelogEntry = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path']),
+
+  run({ row, block, serviceRoot, workspaceRoot, asVersion = null }) {
+    const { json } = readPackage(serviceRoot);
+    if (json === null || !appliesTo(block, json)) return [];
+
+    const where = whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative: row.path });
+    const body = readText(path.join(serviceRoot, ...row.path.split('/')));
+    if (body === null) {
+      const because = row.why ? `: ${row.why}` : '';
+      return [{ where, what: `file absent — this uniform requires it${because}` }];
+    }
+
+    const version = asVersion === null ? json.version : asVersion;
+    if (typeof version !== 'string' || version.trim() === '') {
+      return [{ where, what: 'package.json names no version, so there is no entry to look for' }];
+    }
+    // Where the judged version came from, said only for a publish, so nobody reads
+    // the finding against package.json.
+    const source = asVersion === null ? null : `given by --as-version; package.json says ${json.version}`;
+
+    const sections = changelogSections(body);
+    const own = sections.find((section) => section.name === version);
+
+    if (own !== undefined) {
+      if (hasContent(own)) return [];
+      const which = source === null ? version : `${version} (${source})`;
+      return [{ where, what: `the entry for ${which} is an empty heading — the published version says nothing` }];
+    }
+
+    if (PRERELEASE.test(version)) {
+      const unreleased = sections.find((section) => section.name === 'Unreleased');
+      if (unreleased !== undefined && hasContent(unreleased)) return [];
+    }
+
+    const named = source === null ? version : `${version}, ${source}`;
+    return [{ where, what: `no entry for the version being published (${named})` }];
+  }
+});
+
 module.exports = {
   checks: [
     { name: 'file-present', check: filePresent },
-    { name: 'library-readme', check: libraryReadme }
+    { name: 'library-readme', check: libraryReadme },
+    { name: 'library-changelog-entry', check: libraryChangelogEntry }
   ]
 };

package/src/manifest/checks/libraryTests.js

@@ -11,6 +11,14 @@
  * miss the ninth that has the file and lists nothing. So the check reproduces
  * npm's own precedence — `files` allowlist first, then `.npmignore`, then
  * `.gitignore` — and asks one question: does `tests/` end up in the tarball.
+ * An ignore file is read as npm walks it, negations included (d.1006,
+ * `testsShippedBy`), not as a list of excluding shapes.
+ *
+ * WHICH `tests/`: the package's own tier, at the package root. A `tests/` under
+ * `templates/**` is not a tier of the package but content of a template it ships
+ * on purpose — `templates/business-service/tests/**` is what `oa-sync-template
+ * --new` renders into a new service — so it must travel, and this row never
+ * looks at it (d.1002).
  *
  * @see .claude/rules/architecture-principles.md § Shared Packages
  */
@@ -28,30 +36,196 @@ const UNIT_DIR = path.join('tests', 'unit');
 const TEST_FILE = /\.(test|spec)\.js$/;
 
 /**
- * Does an ignore-file line take `tests/` out of the tarball? npm reads these
- * with gitignore semantics; the shapes that actually occur are the bare name,
- * the anchored name, and the name with a trailing slash or glob.
+ * One line of an ignore file, read the way npm reads it (`ignore-walk`, gitignore
+ * syntax): a leading `!` negates, a trailing `/` matches directories only, a
+ * pattern with a `/` in it is anchored at the package root, and one without is
+ * matched against the last path segment at any depth.
+ *
+ * @param {string} line a trimmed, non-comment line
+ * @param {number} index its position in the file — the last matching line wins
+ * @returns {{index: number, line: string, negate: boolean, dirOnly: boolean, anchored: boolean, segments: string[]}}
+ */
+function parseIgnoreLine(line, index) {
+  const negate = line.startsWith('!');
+  let pattern = negate ? line.slice(1) : line;
+  const dirOnly = pattern.endsWith('/');
+  if (dirOnly) pattern = pattern.slice(0, -1);
+  const anchored = pattern.includes('/');
+  pattern = pattern.replace(/^\//, '');
+  return { index, line, negate, dirOnly, anchored, segments: pattern.split('/') };
+}
+
+/**
+ * Do `patternSegments` match all of `pathSegments`? `**` matches any number of
+ * segments, except as the LAST segment, where it matches at least one — `tests/**`
+ * is everything inside `tests`, not `tests` itself.
+ *
+ * @param {string[]} patternSegments
+ * @param {string[]} pathSegments
+ * @returns {boolean}
+ */
+function segmentsMatch(patternSegments, pathSegments) {
+  if (patternSegments.length === 0) return pathSegments.length === 0;
+  const [head, ...rest] = patternSegments;
+  if (head === '**') {
+    const from = rest.length === 0 ? 1 : 0;
+    for (let skip = from; skip <= pathSegments.length; skip += 1) {
+      if (segmentsMatch(rest, pathSegments.slice(skip))) return true;
+    }
+    return false;
+  }
+  if (pathSegments.length === 0 || !segmentMatches(head, pathSegments[0])) return false;
+  return segmentsMatch(rest, pathSegments.slice(1));
+}
+
+/**
+ * Could an anchored pattern match something strictly INSIDE the directory
+ * `dirSegments`? This is the question npm asks before it walks into a directory an
+ * earlier line excluded: a later `!` pattern that starts with the directory's name
+ * — or with `**` — reopens it, and a pattern without a `/` never does (measured,
+ * d.1006: `/tests/` then `!*.js` ships nothing, `/tests/` then `!**\/*.test.js`
+ * ships the tier).
+ *
+ * @param {string[]} patternSegments
+ * @param {string[]} dirSegments
+ * @returns {boolean}
+ */
+function couldMatchInside(patternSegments, dirSegments) {
+  if (patternSegments.length === 0) return false;
+  const [head, ...rest] = patternSegments;
+  if (head === '**') return true;
+  if (dirSegments.length === 0) return true;
+  if (!segmentMatches(head, dirSegments[0])) return false;
+  return couldMatchInside(rest, dirSegments.slice(1));
+}
+
+/**
+ * Does `rule` match the path `segments` (a directory when `isDir`)?
  *
- * @param {string} body the contents of .npmignore or .gitignore
  * @returns {boolean}
  */
-function ignoresTests(body) {
-  return body
+function ruleMatches(rule, segments, isDir) {
+  if (rule.dirOnly && !isDir) return false;
+  if (!rule.anchored) return segmentMatches(rule.segments[0], segments[segments.length - 1]);
+  return segmentsMatch(rule.segments, segments);
+}
+
+/** The last rule matching the path, or `null` — the last matching line wins. */
+function lastMatch(rules, segments, isDir) {
+  let found = null;
+  for (const rule of rules) {
+    if (ruleMatches(rule, segments, isDir)) found = rule;
+  }
+  return found;
+}
+
+/**
+ * Which of the tier's files an ignore file lets into the tarball, reproducing
+ * npm's walk (d.1006, measured against `npm pack --dry-run --json`, npm 11):
+ * every directory on the way down is judged by the last line matching it; an
+ * EXCLUDED directory is walked into anyway when a later `!` line could match
+ * inside it (`couldMatchInside`), and is otherwise dropped whole; a file is
+ * judged by the last line matching it, and ships when none excludes it.
+ *
+ * Until d.1006 the row read only the excluding shapes and none of the negations,
+ * so `/tests/` followed by `!tests/**` — which npm packs — passed as excluded.
+ *
+ * @param {string} body the contents of .npmignore or .gitignore
+ * @param {string[]} testFiles the tier's files, relative, `/`-separated (`tests/unit/a.test.js`)
+ * @returns {{shipped: string[], reincludedBy: string|null}} what ships, and the
+ *   `!` line that brought the tier back after a line had excluded it
+ */
+function testsShippedBy(body, testFiles) {
+  const rules = body
     .split('\n')
     .map((line) => line.trim())
     .filter((line) => line.length > 0 && !line.startsWith('#'))
-    .some((line) => /^\/?tests(\/(\*\*?)?)?$/.test(line));
+    .map(parseIgnoreLine);
+
+  const shipped = [];
+  let reincludedBy = null;
+  for (const file of testFiles) {
+    const segments = file.split('/');
+    let dropped = false;
+    for (let depth = 1; depth < segments.length && !dropped; depth += 1) {
+      const dir = segments.slice(0, depth);
+      const last = lastMatch(rules, dir, true);
+      if (last === null) continue;
+      if (last.negate) {
+        reincludedBy = reincludedBy || last.line;
+        continue;
+      }
+      const opener = rules.find((rule) => rule.negate && rule.index > last.index && rule.anchored
+        && couldMatchInside(rule.segments, dir));
+      if (opener === undefined) dropped = true;
+      else reincludedBy = reincludedBy || opener.line;
+    }
+    if (dropped) continue;
+    const last = lastMatch(rules, segments, false);
+    if (last !== null && !last.negate) continue;
+    if (last !== null) reincludedBy = reincludedBy || last.line;
+    shipped.push(file);
+  }
+  return { shipped, reincludedBy };
 }
 
 /**
- * Does a `files` allowlist entry let `tests/` in? An entry is a path or a glob;
- * it reaches the directory only when its first segment is the directory itself.
+ * Every file under the tier, relative to the package root, `/`-separated.
  *
- * @param {string[]} files the allowlist
+ * @param {string} serviceRoot
+ * @returns {string[]}
+ */
+function listTestFiles(serviceRoot) {
+  const out = [];
+  const walk = (relative) => {
+    for (const entry of fs.readdirSync(path.join(serviceRoot, relative), { withFileTypes: true })) {
+      const child = `${relative}/${entry.name}`;
+      if (entry.isDirectory()) walk(child);
+      else out.push(child);
+    }
+  };
+  walk(TEST_DIR);
+  return out;
+}
+
+/**
+ * Does ONE segment of an allowlist glob match `name`? `*` and `?` stay inside a
+ * segment, as npm's globbing has them; `**` matches any segment.
+ *
+ * @param {string} segment one `/`-separated part of an allowlist entry
+ * @param {string} name the directory name asked about
  * @returns {boolean}
  */
-function allowsTests(files) {
-  return files.some((entry) => String(entry).replace(/^\.?\//, '').split('/')[0] === TEST_DIR);
+function segmentMatches(segment, name) {
+  if (segment === '**') return true;
+  const pattern = segment
+    .split('')
+    .map((ch) => {
+      if (ch === '*') return '[^/]*';
+      if (ch === '?') return '[^/]';
+      return ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    })
+    .join('');
+  return new RegExp(`^${pattern}$`).test(name);
+}
+
+/**
+ * The allowlist entry that lets `tests/` in, or `null`. An entry reaches the
+ * directory when its FIRST segment matches `tests` — the name itself, a glob
+ * such as `*` or `t*`, or `**`, which matches at any depth. Until d.1002 only the
+ * literal name counted, so `["**\/*.js"]` and `["*"]` shipped the tier (measured
+ * with `npm pack --dry-run`) and the row said nothing. A glob confined to the
+ * root (`*.js`) cannot match a directory and does not reach it.
+ *
+ * @param {string[]} files the allowlist
+ * @returns {string|null}
+ */
+function allowlistEntryReachingTests(files) {
+  const reaching = files.find((entry) => {
+    const firstSegment = String(entry).replace(/^\.?\//, '').split('/')[0];
+    return segmentMatches(firstSegment, TEST_DIR);
+  });
+  return reaching === undefined ? null : String(reaching);
 }
 
 const libraryTests = Object.freeze({
@@ -90,16 +264,25 @@ const libraryPackTests = Object.freeze({
     if (!fs.existsSync(path.join(serviceRoot, TEST_DIR))) return [];
 
     if (Array.isArray(json.files)) {
-      if (!allowsTests(json.files)) return [];
-      return [{ where, what: `the files allowlist names ${TEST_DIR} — the tier would ship to every consumer` }];
+      const entry = allowlistEntryReachingTests(json.files);
+      if (entry === null) return [];
+      return [{ where, what: `the files allowlist entry ${JSON.stringify(entry)} reaches ${TEST_DIR} — the tier would ship to every consumer` }];
     }
 
     for (const name of ['.npmignore', '.gitignore']) {
       const body = readText(path.join(serviceRoot, name));
       if (body === null) continue;
-      if (ignoresTests(body)) return [];
+      const { shipped, reincludedBy } = testsShippedBy(body, listTestFiles(serviceRoot));
+      if (shipped.length === 0) return [];
+      const ignoreFile = whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative: name });
+      if (reincludedBy !== null) {
+        return [{
+          where: ignoreFile,
+          what: `excludes ${TEST_DIR}/, then re-includes it with ${JSON.stringify(reincludedBy)} — the tier would ship to every consumer`
+        }];
+      }
       return [{
-        where: whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative: name }),
+        where: ignoreFile,
         what: `does not exclude ${TEST_DIR}/, and no files allowlist does either — the tier would ship to every consumer`
       }];
     }
@@ -115,7 +298,5 @@ module.exports = {
   checks: [
     { name: 'library-tests', check: libraryTests },
     { name: 'library-pack-tests', check: libraryPackTests }
-  ],
-  ignoresTests,
-  allowsTests
+  ]
 };

package/src/manifest/checks/scriptHeaders.js

@@ -31,15 +31,8 @@
 
 const fs = require('fs');
 
-const { lintScripts, SCRIPT_SCOPE } = require('../../lint/scripts/lintScripts');
-const { resolveWorkspacePath, WORKSPACE_MARKER } = require('../workspaceRoot');
-
-/**
- * The api checkout, by the name the workspace marker already spells. Written
- * once, from the marker, so "which directory is the api one" has one owner
- * (`api/.claude/rules/single-source-of-truth.md`).
- */
-const API_CHECKOUT = WORKSPACE_MARKER.split('/')[0];
+const { lintScripts } = require('../../lint/scripts/lintScripts');
+const { resolveWorkspacePath, API_PREFIX } = require('../workspaceRoot');
 
 /**
  * Where the citations of one repository can be resolved, or null.
@@ -49,7 +42,7 @@ const API_CHECKOUT = WORKSPACE_MARKER.split('/')[0];
  */
 function apiCheckout(workspaceRoot) {
   if (workspaceRoot === null || workspaceRoot === undefined) return null;
-  const target = resolveWorkspacePath(workspaceRoot, API_CHECKOUT);
+  const target = resolveWorkspacePath(workspaceRoot, API_PREFIX);
   return fs.existsSync(target) && fs.statSync(target).isDirectory() ? target : null;
 }
 
@@ -69,11 +62,11 @@ const scriptsLint = Object.freeze({
 
     return {
       findings,
-      notRun: `${result.unresolved.length} @see target(s) name the ${API_CHECKOUT} checkout, which this run `
+      notRun: `${result.unresolved.length} @see target(s) name the ${API_PREFIX} checkout, which this run `
         + `cannot reach: ${result.unresolved.join(', ')}. Run the uniform from a workspace that carries `
-        + `${API_CHECKOUT}/.`
+        + `${API_PREFIX}/.`
     };
   }
 });
 
-module.exports = { checks: [{ name: 'scripts-lint', check: scriptsLint }], SCRIPT_SCOPE, API_CHECKOUT };
+module.exports = { checks: [{ name: 'scripts-lint', check: scriptsLint }] };

package/src/manifest/checks/serviceConfig.js

@@ -3,16 +3,22 @@
 /**
  * The files a service is configured by.
  *
- * Two of these rows overlap deliberately with the boot validation: step 2 of
- * `ValidationOrchestrator` already refuses a `config.json` without
- * `service.name` and an `operations.json` with no operations, and it does that
- * INSIDE a boot. The rows exist because `npx oa-validate` is asked the same
- * question outside one — in CI, in the image build, in a repository nobody has
- * started — and because the manifest is where a rule of service shape is
- * declared (003 §20: an `Enforced by` cell names a row id). The honest end state
- * is one implementation: step 2 extracting its rule into a pure module that both
- * call. That refactor touches `ValidationOrchestrator.js`, which d.210a does not
- * own, so it is recorded for the lead rather than done here.
+ * Three of these rows ARE the boot's step 2: `ValidationOrchestrator` names them
+ * in `CONFIG_STEP_ROWS` and reports what they found. The split between step 2
+ * and step 7 is stated at that symbol and nowhere else, this comment included.
+ *
+ * The rows are asked outside a boot as well — `npx oa-validate` in CI, in the
+ * image build, in a repository nobody has started — and the manifest is where a
+ * rule of service shape is declared (003 §20: an `Enforced by` cell names a row
+ * id).
+ *
+ * Until d.720 this paragraph said something else: that step 2 kept hand-written
+ * sentences of its own, that the rows therefore "overlap deliberately" with it,
+ * and that unifying the two was work still owed and "recorded for the lead". The
+ * unification had already landed — step 2 runs the manifest — so the sentence
+ * outlived what it described, and a promise of work that was done read as a gap
+ * that was open (`.claude/rules/doc-code-binding.md` §5). Kept as a line about
+ * THIS file's own history, which is the only thing a comment here can keep true.
  *
  * `G-SHARED-ENV` is a different kind: `shared.env` is GENERATED from the
  * platform manifest `api/config/shared-env.json` (003 §18), so the row does not
@@ -30,6 +36,8 @@ const { describeWorkspaceFix } = require('../workspaceRoot');
 const { whereOf } = require('./libraryContext');
 const { diffAgainst, renderSharedEnv } = require('../../sync/sharedEnv');
 const { loadAndValidateIntegrationContract } = require('../../utils/bizCiGateContract');
+const { operationsRuleSentences } = require('../../utils/operationsRules');
+const { operationsDocumentFindings } = require('../../utils/operationsDocumentRules');
 
 /** The generated platform file every service carries a copy of. */
 const SHARED_ENV = 'shared.env';
@@ -281,13 +289,25 @@ const configOperations = Object.freeze({
     if (read.absent) return [{ where: row.path, what: 'absent — this uniform requires it' }];
     if (read.broken) return [{ where: row.path, what: `is not valid JSON — ${read.broken}` }];
 
+    // The rules about the document — `schema_version`, and an operations map
+    // with nothing in it — are not decided here either: they are
+    // `src/utils/operationsDocumentRules.js`, the one definition every rail of
+    // this package asks. The row's `what` carries the problem; the row's own
+    // `fix` column carries the remedy, so the sentence is not repeated into it.
+    const documentFindings = operationsDocumentFindings(read.json)
+      .map((finding) => ({ where: row.path, what: `${finding.field}: ${finding.what}` }));
+    if (documentFindings.length > 0) return documentFindings;
+
     const operations = read.json.operations;
-    const declared = operations && typeof operations === 'object' ? Object.keys(operations) : [];
-    if (declared.length > 0) return [];
-    return [{
-      where: row.path,
-      what: 'declares no operations — a service that dispatches nothing has no reason to boot'
-    }];
+
+    // What each declared operation must BE is not decided here: it is decided by
+    // `@onlineapps/service-validator-core`, which mirrors the rules the Registry
+    // applies on registration (owner decision
+    // `api/docs/governance/confirmations/operations-schema-mirror.md` 001). The
+    // row asks that one definition, so `oa-validate` refuses outside a boot
+    // exactly what a registration refuses inside one.
+    return operationsRuleSentences(operations).sentences
+      .map((sentence) => ({ where: row.path, what: sentence }));
   }
 });