@starci/hfs 4.0.9 → 4.1.0

package/runtime/scripts/hfs/path-findings.mjs

@@ -21,6 +21,37 @@ const PLAIN_ENTRY = /^<[a-z][a-z0-9-]*>.ts$/;
 const DATA_ACCESS_HOME = 'SQL text is a constant in <name>.sql.ts of the capability persistence/ folder, and data access is the capability *.service.ts (or the application *.handler.ts) calling the shared EntityManager through its Inject<Conn>EntityManager()';
 const BANNED_SUFFIX_HOME = Object.freeze({ repository: DATA_ACCESS_HOME, store: DATA_ACCESS_HOME });
 
+function sourceFormContext(file, resolver, suffixes, bannedSuffixes) {
+  if (!file.endsWith('.ts') || !SOURCE_ROOT.test(file)) return null;
+  const c = resolver.classifyPath(file);
+  if (c.status !== 'owned' || c.tracking === 'ignored') return null;
+  const base = path.posix.basename(file);
+  if (FREE_NAMES.has(base)) return null;
+  const slot = resolver.slot(c.slot);
+  if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].includes(base)) return null;
+  const admitted = allowsFile(resolver, file);
+  if (admitted?.allowed && admitted.entry?.includes('/') && path.posix.basename(admitted.entry) === base) return null;
+  if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) return null;
+  if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') return null;
+  return { c, base, suffixes, bannedSuffixes };
+}
+
+function sourceFormFinding(file, { c, base, suffixes, bannedSuffixes }, boundSuffixes) {
+  const parts = base.slice(0, -'.ts'.length).split('.');
+  const banned = parts.slice(1).find((part) => bannedSuffixes.includes(part));
+  if (banned) {
+    const homeNote = BANNED_SUFFIX_HOME[banned] ? `. ${BANNED_SUFFIX_HOME[banned]}` : '';
+    return { code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})${homeNote}` };
+  }
+  if (boundSuffixes.has(parts.at(-1)) && parts.length >= 2 && boundSuffixes.get(parts.at(-1)).id !== c.slot) {
+    return { code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: parts.at(-1), message: `${file}: the suffix .${parts.at(-1)}.ts belongs to ${boundSuffixes.get(parts.at(-1)).path} only; move the file there` };
+  }
+  if (parts.length < 2 || !parts.every((part) => KEBAB.test(part)) || !suffixes.includes(parts.at(-1))) {
+    return { code: 'BE_SOURCE_FORM', level: 'error', path: file, message: `${file}: the name must be <kebab-name>.<suffix>.ts with a suffix from the closed list (${suffixes.join(', ')}), or index.ts, main.ts or a migration` };
+  }
+  return null;
+}
+
 /**
  * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
  * be.persistence, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
@@ -38,53 +69,42 @@ function sourceFormFindings({ files, resolver }) {
   }
   const findings = [];
   for (const file of files) {
-    if (!file.endsWith('.ts') || !SOURCE_ROOT.test(file)) continue;
-    const c = resolver.classifyPath(file);
-    if (c.status !== 'owned' || c.tracking === 'ignored') continue;
-    const base = path.posix.basename(file);
-    if (FREE_NAMES.has(base)) continue;
-    // A literal file name the owning slot itself requires or allows (persistence/connection.ts, world/global-setup.ts) is its role.
-    const slot = resolver.slot(c.slot);
-    if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].some((entry) => entry === base)) continue;
-    // So is an allows entry below the slot root whose last segment is that literal name (be.tests.world fakes/<provider>/server.ts).
-    const admitted = allowsFile(resolver, file);
-    if (admitted?.allowed && admitted.entry?.includes('/') && path.posix.basename(admitted.entry) === base) continue;
-    // A slot whose `allows` holds a bare <name>.ts entry (be.tests.world.kit) names its files plainly, as platform/primitives does: kebab-case is the whole form.
-    if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) continue;
-    if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') continue;
-    const parts = base.slice(0, -'.ts'.length).split('.');
-    const banned = parts.slice(1).find((part) => bannedSuffixes.includes(part));
-    if (banned) {
-      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})${BANNED_SUFFIX_HOME[banned] ? `. ${BANNED_SUFFIX_HOME[banned]}` : ''}` });
-    } else if (boundSuffixes.has(parts.at(-1)) && parts.length >= 2 && boundSuffixes.get(parts.at(-1)).id !== c.slot) {
-      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: parts.at(-1), message: `${file}: the suffix .${parts.at(-1)}.ts belongs to ${boundSuffixes.get(parts.at(-1)).path} only; move the file there` });
-    } else if (parts.length < 2 || !parts.every((part) => KEBAB.test(part)) || !suffixes.includes(parts.at(-1))) {
-      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, message: `${file}: the name must be <kebab-name>.<suffix>.ts with a suffix from the closed list (${suffixes.join(', ')}), or index.ts, main.ts or a migration` });
-    }
+    const context = sourceFormContext(file, resolver, suffixes, bannedSuffixes);
+    if (!context) continue;
+    const finding = sourceFormFinding(file, context, boundSuffixes);
+    if (finding) findings.push(finding);
   }
   return findings;
 }
 
+function forbiddenPathFinding(file, c, resolver) {
+  const slot = resolver.slot(c.slot);
+  if (slotOwnsSecrets(slot)) return null;
+  const own = slot.rules?.includes('HFS_TOOL_CONFIG_LOCAL') ? 'HFS_TOOL_CONFIG_LOCAL' : 'HFS_FORBIDDEN_PRESENT';
+  const goesToNote = c.goesTo ? `; it belongs at ${c.goesTo}` : '';
+  return { code: own, level: 'error', path: file, slot: c.slot, goesTo: c.goesTo, message: `${file} is tracked but ${c.slot} is forbidden in the tree${goesToNote}` };
+}
+
+function pathStatusFinding(file, resolver) {
+  const c = resolver.classifyPath(file);
+  if (c.status === 'no-slot') {
+    const nearestNote = c.nearest ? `; nearest slot ${c.nearest.slot} (${c.nearest.pattern}), matched ${c.nearest.matchedPrefix || '.'} then expected ${c.nearest.expectedNext ?? 'nothing'}` : '';
+    return { code: 'HFS_SLOT_UNDECLARED', level: 'error', path: file, nearest: c.nearest, message: `${file} matches no slot${nearestNote}` };
+  }
+  if (c.status === 'ambiguous') return { code: 'HFS_SLOT_AMBIGUOUS', level: 'error', path: file, candidates: c.candidates, message: `${file} is owned equally by ${c.candidates.map((x) => x.slot ?? x).join(', ')}` };
+  if (c.status === 'not-enabled') return { code: 'HFS_SLOT_NOT_ENABLED', level: 'error', path: file, slot: c.slot, message: `${file} belongs to ${c.slot}, an opt-in slot hfs.json neither lists in optionalSlots nor implies through an app kind` };
+  if (c.status === 'forbidden') return forbiddenPathFinding(file, c, resolver);
+  if (c.tracking === 'ignored') return { code: 'HFS_TRACKED_MUST_BE_IGNORED', level: 'error', path: file, slot: c.slot, message: `${file} is tracked but ${c.slot} must be gitignored` };
+  return null;
+}
+
 /** The findings of the slot manifest over `files` (repository-relative tracked paths) of a repository of `profile`. */
 export function pathFindings({ files, resolver, profile }) {
   const findings = [];
   for (const file of files) {
     if (profile === 'fe' && isFeTestPath(file)) continue;   // a test path of a front end is FE_NO_TESTS's, the one finding of that file
-    const c = resolver.classifyPath(file);
-    if (c.status === 'no-slot') {
-      findings.push({ code: 'HFS_SLOT_UNDECLARED', level: 'error', path: file, nearest: c.nearest, message: `${file} matches no slot${c.nearest ? `; nearest slot ${c.nearest.slot} (${c.nearest.pattern}), matched ${c.nearest.matchedPrefix || '.'} then expected ${c.nearest.expectedNext ?? 'nothing'}` : ''}` });
-    } else if (c.status === 'ambiguous') {
-      findings.push({ code: 'HFS_SLOT_AMBIGUOUS', level: 'error', path: file, candidates: c.candidates, message: `${file} is owned equally by ${c.candidates.map((x) => x.slot ?? x).join(', ')}` });
-    } else if (c.status === 'not-enabled') {
-      findings.push({ code: 'HFS_SLOT_NOT_ENABLED', level: 'error', path: file, slot: c.slot, message: `${file} belongs to ${c.slot}, an opt-in slot hfs.json neither lists in optionalSlots nor implies through an app kind` });
-    } else if (c.status === 'forbidden') {
-      const slot = resolver.slot(c.slot);
-      if (slotOwnsSecrets(slot)) continue;   // the secret scan reports the file (R06): one finding per file
-      const own = slot.rules?.includes('HFS_TOOL_CONFIG_LOCAL') ? 'HFS_TOOL_CONFIG_LOCAL' : 'HFS_FORBIDDEN_PRESENT';
-      findings.push({ code: own, level: 'error', path: file, slot: c.slot, goesTo: c.goesTo, message: `${file} is tracked but ${c.slot} is forbidden in the tree${c.goesTo ? `; it belongs at ${c.goesTo}` : ''}` });
-    } else if (c.tracking === 'ignored') {
-      findings.push({ code: 'HFS_TRACKED_MUST_BE_IGNORED', level: 'error', path: file, slot: c.slot, message: `${file} is tracked but ${c.slot} must be gitignored` });
-    }
+    const finding = pathStatusFinding(file, resolver);
+    if (finding) findings.push(finding);
   }
 
   if (profile === 'be') findings.push(...sourceFormFindings({ files, resolver }), ...specPlacementFindings({ files, resolver }));

package/runtime/scripts/hfs/pin-findings.mjs

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { APP_SCOPE } from './slots.mjs';
+
+const DEP_SECTIONS = ['dependencies', 'devDependencies'];
+const pinnedSpec = (spec, pin) => (spec === pin.version ? null : `declared ${spec}, pinned ${pin.version}`);
+
+function pinFileFindings(repoRoot, file, profile, pins) {
+  const findings = [];
+  let pkg;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, file), 'utf8')); } catch { return findings; }
+  for (const [name, pin] of Object.entries(pins)) {
+    // The app root's one package.json carries the pins of both sides.
+    if (profile !== APP_SCOPE && pin.side !== 'both' && pin.side !== profile) continue;
+    for (const section of DEP_SECTIONS) {
+      const spec = pkg[section]?.[name];
+      if (spec === undefined) continue;
+      const drift = pinnedSpec(spec, pin);
+      if (drift) findings.push({ code: 'HFS_CANON_PIN_DRIFT', level: 'error', path: file, dependency: name, section, pinned: pin.version, declared: spec, message: `${name} in ${file} ${section}: ${drift}` });
+    }
+  }
+  return findings;
+}
+
+export function pinFindings({ repoRoot, files, profile, pins, only }) {
+  const findings = [];
+  for (const file of files.filter((f) => (f === 'package.json' || f.endsWith('/package.json')) && (!only || only.has(f)))) {
+    findings.push(...pinFileFindings(repoRoot, file, profile, pins));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/repo-identity.mjs

@@ -6,10 +6,13 @@ import path from 'node:path';
 import { revParseQuery } from '../api/git/rev-parse-query.mjs';
 import { remote as gitRemote } from '../api/git/remote.mjs';
 import { gitOutputOf } from '../lib/git.mjs';
+import { trimTrailingSlashes } from './trailing-slashes.mjs';
 
 /** One git call (a scripts/api/git call file) in `root`: its trimmed stdout; throws unless git exits 0. */
 const git = (call, root, args) => gitOutputOf(call(args, { cwd: root })).trim();
 const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+const GIT_SUFFIX_SOURCE = String.raw`\.git$`;
+const GIT_SUFFIX = new RegExp(GIT_SUFFIX_SOURCE, 'iu');
 
 /** { repositoryRoot, inWorkTree, home } for `root`: home is the main checkout folder when root is a repository top level. */
 function identityOf(root) {
@@ -34,8 +37,8 @@ export function repositoryName(root) {
   if (home) return path.basename(home);
   if (repositoryRoot) {
     try {
-      const remote = git(gitRemote, root, ['get-url', 'origin']).replace(/[\/]+$/u, '').replace(/\.git$/iu, '');
-      const name = remote.split(/[\/:]/u).pop();
+      const remote = trimTrailingSlashes(git(gitRemote, root, ['get-url', 'origin'])).replace(GIT_SUFFIX, '');
+      const name = remote.split(/[/:]/u).pop();
       if (name) return name;
     } catch { /* No origin remote. */ }
   }

package/runtime/scripts/hfs/rule-catalog.mjs

@@ -0,0 +1,194 @@
+// rule-catalog.mjs - the parsed and validated HFS rule catalog.
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { SEMVER } from './manifest-shape.mjs';
+import { enforcerJudgedInEdition, judgedInEdition, ruleEditionProblems } from './edition-slots.mjs';
+import { fail } from './slot-errors.mjs';
+
+const HFS_RULES_FILE = 'knowledge/hfs/rules.yaml';
+const RULE_GATES = Object.freeze(['pre-commit', 'pre-push', 'settle', 'land', 'ci', 'sonar', 'runtime']);
+const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
+const RULE_KINDS = Object.freeze(['codemod', 'lint', 'check', 'design']);
+const FINDING_CODE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
+const ENFORCER_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const FILE_ENFORCERS = new Set(['machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
+const RULE_KEYS = new Set(['id', 'code', 'law', 'scope', 'kinds', 'gates', 'failureCodes', 'editions', 'enforcers']);
+const ENFORCER_KEYS = new Set(['kind', 'id', 'status', 'at', 'editions']);
+
+function vocabularyProblems(catalog, key, names, bad) {
+  if (!isPlainObject(catalog[key])) { bad.push(`${key} must be a map`); return; }
+  if (JSON.stringify(Object.keys(catalog[key])) !== JSON.stringify(names)) bad.push(`${key} must list exactly ${names.join(', ')} in that order`);
+  for (const [name, text] of Object.entries(catalog[key])) {
+    if (typeof text !== 'string' || !text.trim()) bad.push(`${key}.${name} needs a description`);
+  }
+}
+
+function checkCatalogHeader(catalog, bad) {
+  for (const key of Object.keys(catalog)) {
+    if (!['schema', 'version', 'gates', 'enforcerKinds', 'rules'].includes(key)) bad.push(`unknown top-level key ${key}`);
+  }
+  const schemaOk = /^starci\/hfs-rules@\d+$/.test(String(catalog.schema));
+  if (!schemaOk) bad.push('schema must be starci/hfs-rules@<major>');
+  if (!SEMVER.test(String(catalog.version))) bad.push('version must be MAJOR.MINOR.PATCH');
+  else if (schemaOk && catalog.schema.split('@')[1] !== catalog.version.split('.')[0]) bad.push('the major of version must equal the number after @ in schema');
+  vocabularyProblems(catalog, 'gates', RULE_GATES, bad);
+  vocabularyProblems(catalog, 'enforcerKinds', ENFORCER_FAMILIES, bad);
+}
+
+function enumListProblems(rule, label, key, allowed, bad) {
+  if (!Array.isArray(rule[key]) || !rule[key].length) { bad.push(`${label}.${key} must be a non-empty list`); return []; }
+  for (const value of rule[key]) {
+    if (!allowed.includes(value)) bad.push(`${label}.${key} has ${JSON.stringify(value)}, not one of ${allowed.join(', ')}`);
+  }
+  if (new Set(rule[key]).size !== rule[key].length) bad.push(`${label}.${key} repeats a value`);
+  return rule[key];
+}
+
+function checkRuleIdentity(rule, index, catalog, at, label, bad) {
+  if (!/^R\d{2,3}$/.test(String(rule.id))) bad.push(`${at}.id must be R<two or three digits>`);
+  else if (index > 0 && typeof catalog.rules[index - 1]?.id === 'string' && Number(rule.id.slice(1)) <= Number(catalog.rules[index - 1].id.slice(1))) bad.push(`${label} is out of order: ids must increase, and ${catalog.rules[index - 1].id} comes before it`);
+  if (!FINDING_CODE.test(String(rule.code))) bad.push(`${label}.code must be an UPPER_SNAKE finding code`);
+}
+
+function checkRuleText(rule, label, bad) {
+  if (typeof rule.law !== 'string' || !rule.law.trim()) bad.push(`${label}.law is missing`);
+  if (typeof rule.law === 'string' && rule.law.includes('\n')) bad.push(`${label}.law must be one line`);
+  if (rule.scope !== undefined && rule.scope !== 'runtime') bad.push(`${label}.scope is absent or runtime`);
+}
+
+function checkRuleGates(label, gates, bad) {
+  if (!gates.length) return;
+  if (!gates.includes('land')) bad.push(`${label} must run at the land gate (every rule does)`);
+  if (gates.includes('pre-commit') && !gates.includes('pre-push')) bad.push(`${label} runs at pre-commit, so it also runs at pre-push`);
+}
+
+function checkRuleFailureCodes(rule, label, codeOwner, bad) {
+  if (!Array.isArray(rule.failureCodes) || !rule.failureCodes.length || !rule.failureCodes.every((code) => FINDING_CODE.test(String(code)))) {
+    bad.push(`${label}.failureCodes must be a non-empty list of UPPER_SNAKE codes`);
+    return;
+  }
+  if (rule.failureCodes[0] !== rule.code) bad.push(`${label}.failureCodes must start with the rule's own code ${rule.code}`);
+  if (new Set(rule.failureCodes).size !== rule.failureCodes.length) bad.push(`${label}.failureCodes repeats a code`);
+  for (const code of rule.failureCodes) {
+    if (codeOwner.has(code) && codeOwner.get(code) !== label) bad.push(`${label} names ${code}, which ${codeOwner.get(code)} already owns`);
+    codeOwner.set(code, label);
+  }
+}
+
+function checkEnforcerIdentity(enforcer, label, seen, bad) {
+  if (!ENFORCER_FAMILIES.includes(enforcer.kind)) bad.push(`${label}.kind must be one of ${ENFORCER_FAMILIES.join(', ')}`);
+  if (!ENFORCER_ID.test(String(enforcer.id))) bad.push(`${label}.id must be kebab-case`);
+  if (seen.has(`${enforcer.kind}:${enforcer.id}`)) bad.push(`${label} repeats ${enforcer.kind}:${enforcer.id}`);
+  seen.add(`${enforcer.kind}:${enforcer.id}`);
+}
+
+function checkEnforcerLocation(enforcer, label, bad) {
+  if (enforcer.at !== undefined) {
+    if (typeof enforcer.at !== 'string' || !enforcer.at.trim() || enforcer.at.startsWith('/') || enforcer.at.includes('..')) bad.push(`${label}.at must be a repository-relative path`);
+    if (enforcer.status === 'planned') bad.push(`${label} is planned, so it has no file yet (at)`);
+    if (!FILE_ENFORCERS.has(enforcer.kind)) bad.push(`${label}.at belongs to a machine, hfs, work-validate, sonar or runtime enforcer only`);
+  } else if (FILE_ENFORCERS.has(enforcer.kind) && enforcer.status !== 'planned') bad.push(`${label} exists, so it names the file (at) that emits its code`);
+}
+
+function checkEnforcer(enforcer, index, ruleLabel, seen, bad) {
+  const label = `${ruleLabel}.enforcers[${index}]`;
+  if (!isPlainObject(enforcer)) { bad.push(`${label} is not a map`); return; }
+  for (const key of Object.keys(enforcer)) {
+    if (!ENFORCER_KEYS.has(key)) bad.push(`${label} has unknown key ${key}`);
+  }
+  bad.push(...ruleEditionProblems(enforcer, label));
+  checkEnforcerIdentity(enforcer, label, seen, bad);
+  if (enforcer.status !== undefined && enforcer.status !== 'planned') bad.push(`${label}.status is either absent or planned`);
+  checkEnforcerLocation(enforcer, label, bad);
+}
+
+function checkRuleEnforcers(rule, label, bad) {
+  if (!Array.isArray(rule.enforcers) || !rule.enforcers.length) { bad.push(`${label}.enforcers must name at least one enforcer`); return; }
+  const seen = new Set();
+  rule.enforcers.forEach((enforcer, index) => checkEnforcer(enforcer, index, label, seen, bad));
+}
+
+function checkRule(rule, index, catalog, codeOwner, bad) {
+  const at = `rules[${index}]`;
+  if (!isPlainObject(rule)) { bad.push(`${at} is not a map`); return; }
+  const label = typeof rule.id === 'string' ? rule.id : at;
+  for (const key of Object.keys(rule)) {
+    if (!RULE_KEYS.has(key)) bad.push(`${label} has unknown key ${key}`);
+  }
+  checkRuleIdentity(rule, index, catalog, at, label, bad);
+  checkRuleText(rule, label, bad);
+  enumListProblems(rule, label, 'kinds', RULE_KINDS, bad);
+  bad.push(...ruleEditionProblems(rule, label));
+  const gates = enumListProblems(rule, label, 'gates', RULE_GATES, bad);
+  checkRuleGates(label, gates, bad);
+  checkRuleFailureCodes(rule, label, codeOwner, bad);
+  checkRuleEnforcers(rule, label, bad);
+  if (Array.isArray(rule.gates)) {
+    const hasSonar = rule.enforcers.some((enforcer) => isPlainObject(enforcer) && enforcer.kind === 'sonar');
+    if (rule.gates.includes('sonar') !== hasSonar) bad.push(`${label}: the sonar gate and a sonar enforcer go together`);
+  }
+}
+
+/** Shape and semantic problems of a parsed knowledge/hfs/rules.yaml, in the words of modules/schemas/hfs-rules.schema.yaml. */
+function ruleCatalogProblems(catalog) {
+  const bad = [];
+  if (!isPlainObject(catalog)) return ['the rule catalog is not a map'];
+  checkCatalogHeader(catalog, bad);
+  if (!Array.isArray(catalog.rules) || !catalog.rules.length) { bad.push('rules must be a non-empty list'); return bad; }
+  const codeOwner = new Map();
+  catalog.rules.forEach((rule, index) => checkRule(rule, index, catalog, codeOwner, bad));
+  return bad;
+}
+
+const deepFreeze = (value) => { if (value && typeof value === 'object') { Object.values(value).forEach(deepFreeze); } return Object.freeze(value); };
+
+/**
+ * The parsed and validated HFS rule catalog. `text` (or `file`, or `root`) selects the source; the default is the runtime's
+ * own knowledge/hfs/rules.yaml. A catalog that breaks its shape or a semantic rule is refused whole (HFS_RULES_INVALID), and
+ * so is one whose major differs from the slot manifest passed as `manifest` (HFS_MANIFEST_MAJOR_MISMATCH).
+ * Answers: rule(id), byCode(code), forGate(gate), forEnforcer(kind, id), planned() and unbuilt().
+ */
+export function loadRuleCatalog({ root = skillRoot, file = path.join(root, HFS_RULES_FILE), text, manifest } = {}) {
+  let doc;
+  try { doc = parseYaml(text ?? fs.readFileSync(file, 'utf8')); } catch (error) { fail('HFS_RULES_INVALID', `the rule catalog cannot be read (${String(error?.message ?? error).split('\n')[0]})`, { file }); }
+  const problems = ruleCatalogProblems(doc);
+  if (problems.length) { fail('HFS_RULES_INVALID', `the rule catalog breaks its schema: ${problems.slice(0, 5).join('; ')}${problems.length > 5 ? '; and ' + (problems.length - 5) + ' more' : ''}`, { file, problems }); }
+  const [major, minor, patch] = doc.version.split('.').map(Number);
+  if (manifest && manifest.major !== major) fail('HFS_MANIFEST_MAJOR_MISMATCH', `the rule catalog is major ${major} but the slot manifest is major ${manifest.major}`, { catalog: major, manifest: manifest.major });
+  const list = deepFreeze(doc.rules.map((rule) => ({ ...rule, enforcers: rule.enforcers.map((enforcer) => ({ ...enforcer, planned: enforcer.status === 'planned' })) })));
+  const byId = new Map(list.map((rule) => [rule.id, rule]));
+  const byCode = new Map(list.flatMap((rule) => rule.failureCodes.map((code) => [code, rule])));
+  return Object.freeze({
+    version: doc.version, major, minor, patch,
+    gates: deepFreeze(structuredClone(doc.gates)),
+    enforcerKinds: deepFreeze(structuredClone(doc.enforcerKinds)),
+    rules: list,
+    /** The rule with this id (R01..), or null. */
+    rule: (id) => byId.get(id) ?? null,
+    /** The rule that owns this failure code (its own or a sub-check code), or null. */
+    byCode: (code) => byCode.get(code) ?? null,
+    /** Whether a finding code is judged under `edition`: a code of a rule that names `editions` without it is not (a code outside the catalog always is). */
+    judgedIn: (code, edition = 'full') => judgedInEdition(byCode.get(code), edition),
+    enforcerJudgedIn: (kind, id, edition = 'full') => enforcerJudgedInEdition(list, kind, id, edition),
+    /** The rules that run at a gate. */
+    forGate: (gate) => list.filter((rule) => rule.gates.includes(gate)),
+    /** The catalogued why code of a lint finding's rule id (`starci-be/<id>`, `starci-fe/<id>`), or undefined. */
+    lintCode: (ruleId) => {
+      const [plugin, id] = String(ruleId ?? '').split('/');
+      const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || null;
+      return kind ? list.find((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id))?.code : undefined;
+    },
+    /** The rules one enforcer judges, e.g. forEnforcer('eslint-be', 'error-home'). */
+    forEnforcer: (kind, id) => list.filter((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id)),
+    /** Every enforcer still owed, as {rule, kind, id}. */
+    planned: () => list.flatMap((rule) => rule.enforcers.filter((enforcer) => enforcer.planned).map((enforcer) => ({ rule: rule.id, kind: enforcer.kind, id: enforcer.id }))),
+    /** The rules with no existing enforcer at all. */
+    unbuilt: () => list.filter((rule) => rule.enforcers.every((enforcer) => enforcer.planned)),
+  });
+}
+
+/** The rules of this runtime's catalog, frozen, in id order. */
+export const rules = (options) => loadRuleCatalog(options).rules;

package/runtime/scripts/hfs/rule-params-shape.mjs

@@ -5,45 +5,51 @@ import { isPlainObject } from '../../engine/plain-object.mjs';
 import { paramNamesOk } from './param-names.mjs';
 import { kindParamProblems, scenarioProblem } from './declaration-slots.mjs';
 import { roleListProblems, SCHEMA_AUTHORITIES, unitRolesProblems } from './manifest-shape.mjs';
+import { byCodeUnit } from '../lib/list.mjs';
 
 const PROFILES = ['be', 'fe'];
+const BE_OWN = ['infraOwners', 'eventBus', 'specDoubles', 'paramNames', 'suffixes', 'bannedSuffixes', 'contractShape', 'unitRoles', 'logicRoles', 'thinRoles', 'patternScenarios', 'kindPatterns', 'addKinds'];
+const FORM_NAMES = new Set(['call', 'new', 'curried', 'object', 'primitive', 'array']);
+const blockOk = (v) => isPlainObject(v) && Number.isInteger(v.lines) && v.lines >= 2 && Number.isInteger(v.tokens) && v.tokens >= 1 && Object.keys(v).length === 2;
+const fileLinesOk = (v) => isPlainObject(v) && Number.isInteger(v.soft) && v.soft >= 1 && typeof v.hardGrowth === 'boolean' && Object.keys(v).length === 2;
+const sharedParam = (key, v) => (key === 'fileLines' ? fileLinesOk(v) : blockOk(v));
+const sideOk = (side, own, extra = []) => own.every((k) => side[k] !== undefined) && Object.entries(side).every(([k, v]) => own.includes(k) || extra.includes(k) || (['fileLines', 'duplicateBlock'].includes(k) && sharedParam(k, v)));
+const liteOk = (lite, keys) => lite === undefined || (isPlainObject(lite) && Object.keys(lite).length > 0 && Object.keys(lite).every((k) => k !== 'lite' && keys.includes(k)));
+const memberMap = (v, allowEmpty) => isPlainObject(v) && Object.keys(v).length > 0 && Object.values(v).every((list) => Array.isArray(list) && (allowEmpty || list.length > 0) && list.every((x) => /^[A-Z][A-Za-z0-9]*$/.test(String(x))) && new Set(list).size === list.length);
+const roleList = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => /^[a-z][a-z0-9-]*$/.test(String(x))) && new Set(v).size === v.length;
+const formsOk = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => FORM_NAMES.has(x)) && new Set(v).size === v.length;
+const doubleOk = (v) => isPlainObject(v) && /^[A-Za-z][A-Za-z0-9]*$/.test(String(v.double)) && formsOk(v.forms);
+const regexOk = (v) => { try { return typeof v === 'string' && v.length > 0 && Boolean(new RegExp(v)); } catch { return false; } };
+
+function beSpecificProblems(be, manifest) {
+  const bad = [];
+  bad.push(...scenarioProblem(be.patternScenarios), ...kindParamProblems(be, manifest.triggerKinds));
+  if (!isPlainObject(be.contractShape) || Object.keys(be.contractShape).length !== 1 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(String(be.contractShape.helper))) bad.push('ruleParams.be.contractShape must be {helper: <identifier>}');
+  const owners = be.infraOwners;
+  const ownerId = /^(platform|integrations)\/[a-z][a-z0-9-]*$/;
+  if (!isPlainObject(owners) || !Object.keys(owners).length || !Object.entries(owners).every(([key, list]) => key && Array.isArray(list) && list.every((o) => ownerId.test(String(o))) && new Set(list).size === list.length)) bad.push('ruleParams.be.infraOwners must map a non-empty specifier to a list of unique platform/<capability> or integrations/<provider> owners ([] means nowhere)');
+  const eventBus = be.eventBus;
+  if (!isPlainObject(eventBus) || Object.keys(eventBus).sort(byCodeUnit).join() !== 'classes,imports' || !memberMap(eventBus.imports, true) || !memberMap(eventBus.classes, false)) bad.push('ruleParams.be.eventBus must be {imports: {<module>: [unique PascalCase members]}, classes: {<module>: [non-empty unique PascalCase classes]}}');
+  if (!paramNamesOk(be.paramNames)) bad.push('ruleParams.be.paramNames must be a non-empty list of unique {type | typeSuffix, names, nameSuffix?} entries');
+  if (!roleList(be.suffixes)) bad.push('ruleParams.be.suffixes must be a non-empty list of unique kebab-case role suffixes');
+  if (!roleList(be.bannedSuffixes)) bad.push('ruleParams.be.bannedSuffixes must be a non-empty list of unique kebab-case suffixes');
+  else if (roleList(be.suffixes) && be.suffixes.some((x) => be.bannedSuffixes.includes(x))) bad.push('ruleParams.be.suffixes and bannedSuffixes must be disjoint');
+  const sd = be.specDoubles;
+  if (!isPlainObject(sd) || Object.keys(sd).sort(byCodeUnit).join() !== 'doubles,fallback,kit' || typeof sd.kit !== 'string' || !sd.kit || !Array.isArray(sd.doubles) || !sd.doubles.length || !sd.doubles.every((e) => doubleOk(e) && regexOk(e.token) && Object.keys(e).length === 3) || !doubleOk(sd.fallback) || Object.keys(sd.fallback).length !== 2) bad.push('ruleParams.be.specDoubles must be {kit, doubles: [{token: regex, double, forms}], fallback: {double, forms}} with forms drawn from call, new, curried, object, primitive, array');
+  return bad;
+}
 
 /** The shape problems of `m.ruleParams`. */
 export function ruleParamsProblems(m) {
   const bad = [];
-  const blockOk = (v) => isPlainObject(v) && Number.isInteger(v.lines) && v.lines >= 2 && Number.isInteger(v.tokens) && v.tokens >= 1 && Object.keys(v).length === 2;
-  const fileLinesOk = (v) => isPlainObject(v) && Number.isInteger(v.soft) && v.soft >= 1 && typeof v.hardGrowth === 'boolean' && Object.keys(v).length === 2;
   const rp = m.ruleParams;
-  if (!isPlainObject(rp) || Object.keys(rp).some((k) => ![...PROFILES, 'common'].includes(k)) || !isPlainObject(rp.common) || !isPlainObject(rp.be) || (rp.fe !== undefined && !isPlainObject(rp.fe))) bad.push('ruleParams must be a map with common, be and optionally fe');
+  if (!isPlainObject(rp) || Object.keys(rp).some((k) => ![...PROFILES, 'common'].includes(k)) || !isPlainObject(rp.common) || !isPlainObject(rp.be) || (rp.fe !== undefined && !isPlainObject(rp.fe))) return ['ruleParams must be a map with common, be and optionally fe'];
   else {
     // common holds the parameters both sides share; a side may restate one of them (a valid value) as an override, nothing else.
-    const sharedParam = (key, v) => (key === 'fileLines' ? fileLinesOk(v) : blockOk(v));
-    const sideOk = (side, own, extra = []) => own.every((k) => side[k] !== undefined) && Object.entries(side).every(([k, v]) => own.includes(k) || extra.includes(k) || (['fileLines', 'duplicateBlock'].includes(k) && sharedParam(k, v)));
     // Edition lite: a side's optional `lite` map overrides keys of the same side (never `lite` itself) when the app declares edition lite.
-    const liteOk = (lite, keys) => lite === undefined || (isPlainObject(lite) && Object.keys(lite).length > 0 && Object.keys(lite).every((k) => k !== 'lite' && keys.includes(k)));
-    const BE_OWN = ['infraOwners', 'eventBus', 'specDoubles', 'paramNames', 'suffixes', 'bannedSuffixes', 'contractShape', 'unitRoles', 'logicRoles', 'thinRoles', 'patternScenarios', 'kindPatterns', 'addKinds'];
     if (Object.keys(rp.common).length !== 2 || !fileLinesOk(rp.common.fileLines) || !blockOk(rp.common.duplicateBlock)) bad.push('ruleParams.common needs exactly fileLines {soft, hardGrowth} and duplicateBlock {lines >= 2, tokens >= 1}');
     if (!sideOk(rp.be, BE_OWN, ['schemaAuthority', 'lite']) || (rp.be.schemaAuthority !== undefined && !SCHEMA_AUTHORITIES.includes(rp.be.schemaAuthority)) || !liteOk(rp.be.lite, [...BE_OWN, 'fileLines', 'duplicateBlock', 'schemaAuthority'])) bad.push('ruleParams.be needs infraOwners, eventBus, specDoubles, paramNames, suffixes, bannedSuffixes, contractShape {helper}, unitRoles, logicRoles, thinRoles, patternScenarios, kindPatterns and addKinds (fileLines and duplicateBlock live in ruleParams.common, a side may override them); optional: schemaAuthority (' + SCHEMA_AUTHORITIES.join(' | ') + ') and lite (overrides of the same keys)'); else bad.push(...unitRolesProblems(rp.be), ...roleListProblems(rp.be));
-    bad.push(...scenarioProblem(rp.be.patternScenarios), ...kindParamProblems(rp.be, m.triggerKinds));
-    if (!isPlainObject(rp.be.contractShape) || Object.keys(rp.be.contractShape).length !== 1 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(String(rp.be.contractShape.helper))) bad.push('ruleParams.be.contractShape must be {helper: <identifier>}');
-    const owners = rp.be.infraOwners;
-    const ownerId = /^(platform|integrations)\/[a-z][a-z0-9-]*$/;
-    if (!isPlainObject(owners) || !Object.keys(owners).length || !Object.entries(owners).every(([key, list]) => key && Array.isArray(list) && list.every((o) => ownerId.test(String(o))) && new Set(list).size === list.length)) bad.push('ruleParams.be.infraOwners must map a non-empty specifier to a list of unique platform/<capability> or integrations/<provider> owners ([] means nowhere)');
-    const className = /^[A-Z][A-Za-z0-9]*$/;
-    const memberMap = (v, allowEmpty) => isPlainObject(v) && Object.keys(v).length > 0 && Object.values(v).every((list) => Array.isArray(list) && (allowEmpty || list.length > 0) && list.every((x) => className.test(String(x))) && new Set(list).size === list.length);
-    const eventBus = rp.be.eventBus;
-    if (!isPlainObject(eventBus) || Object.keys(eventBus).sort().join() !== 'classes,imports' || !memberMap(eventBus.imports, true) || !memberMap(eventBus.classes, false)) bad.push('ruleParams.be.eventBus must be {imports: {<module>: [unique PascalCase members]}, classes: {<module>: [non-empty unique PascalCase classes]}}');
-    if (!paramNamesOk(rp.be.paramNames)) bad.push('ruleParams.be.paramNames must be a non-empty list of unique {type | typeSuffix, names, nameSuffix?} entries');
-    const roleList = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => /^[a-z][a-z0-9-]*$/.test(String(x))) && new Set(v).size === v.length;
-    if (!roleList(rp.be.suffixes)) bad.push('ruleParams.be.suffixes must be a non-empty list of unique kebab-case role suffixes');
-    if (!roleList(rp.be.bannedSuffixes)) bad.push('ruleParams.be.bannedSuffixes must be a non-empty list of unique kebab-case suffixes');
-    else if (roleList(rp.be.suffixes) && rp.be.suffixes.some((x) => rp.be.bannedSuffixes.includes(x))) bad.push('ruleParams.be.suffixes and bannedSuffixes must be disjoint');
-    const formNames = ['call', 'new', 'curried', 'object', 'primitive', 'array'];
-    const formsOk = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => formNames.includes(x)) && new Set(v).size === v.length;
-    const doubleOk = (v) => isPlainObject(v) && /^[A-Za-z][A-Za-z0-9]*$/.test(String(v.double)) && formsOk(v.forms);
-    const regexOk = (v) => { try { return typeof v === 'string' && v.length > 0 && Boolean(new RegExp(v)); } catch { return false; } };
-    const sd = rp.be.specDoubles;
-    if (!isPlainObject(sd) || Object.keys(sd).sort().join() !== 'doubles,fallback,kit' || typeof sd.kit !== 'string' || !sd.kit || !Array.isArray(sd.doubles) || !sd.doubles.length || !sd.doubles.every((e) => doubleOk(e) && regexOk(e.token) && Object.keys(e).length === 3) || !doubleOk(sd.fallback) || Object.keys(sd.fallback).length !== 2) bad.push('ruleParams.be.specDoubles must be {kit, doubles: [{token: regex, double, forms}], fallback: {double, forms}} with forms drawn from call, new, curried, object, primitive, array');
+    bad.push(...beSpecificProblems(rp.be, m));
     if (rp.fe !== undefined && (!sideOk(rp.fe, [], ['lite']) || !liteOk(rp.fe.lite, ['fileLines', 'duplicateBlock']))) bad.push('ruleParams.fe may only restate fileLines and duplicateBlock of ruleParams.common, and carry a lite override of them');
   }
   return bad;

package/runtime/scripts/hfs/rules/cli.mjs

@@ -29,7 +29,11 @@ export function cliFindings({ files, repo, resolver }) {
   // Where the cli app is only optional (litePresence: schema migration is the Supabase CLI's job) a connection no longer forces it; a tracked command still does.
   const migrates = (be.connections ?? []).length > 0 && beResolver.slot(CLI_APP_SLOT)?.presence !== 'optional';
   const needs = migrates || commandFiles.length > 0;
-  const why = migrates ? `it declares the connection${be.connections.length === 1 ? '' : 's'} ${be.connections.map((c) => c.name).join(', ')} (their migrations run as \`cli migrate run\`)` : 'it tracks commands under be/src/features/cli/';
+  let why = 'it tracks commands under be/src/features/cli/';
+  if (migrates) {
+    const plural = be.connections.length === 1 ? '' : 's';
+    why = `it declares the connection${plural} ${be.connections.map((c) => c.name).join(', ')} (their migrations run as \`cli migrate run\`)`;
+  }
   if (needs && cliApps.length === 0) findings.push(found(CLI_REQUIRED, 'hfs.json', `the back end declares no cli app, but ${why}; declare { "name": "${CLI_APP}", "kind": "${CLI_KIND}" } in sides.be.apps and build be/apps/${CLI_APP} on nest-commander: every one-off action of the back end is one of its commands.`, { needs: why }));
   for (const app of cliApps.filter((entry) => entry.name !== CLI_APP)) findings.push(found(CLI_REQUIRED, 'hfs.json', `the cli app is named ${app.name}; the back end has ONE cli app, be/apps/${CLI_APP}, so its image and its command line are the same in every app.`, { app: app.name }));
   if (cliApps.length > 0 && !tracked.has(`apps/${CLI_APP}/${IMAGE}`) && cliApps.some((app) => app.name === CLI_APP)) findings.push(found(CLI_REQUIRED, `be/apps/${CLI_APP}/${IMAGE}`, `be/apps/${CLI_APP} has no image: track be/apps/${CLI_APP}/${IMAGE}, the one cli image every one-off action runs from (\`cli <group> <command>\`).`, { app: CLI_APP }));

package/runtime/scripts/hfs/rules/contract-compat.mjs

@@ -12,6 +12,7 @@
 import path from 'node:path';
 import { isPlainObject } from '../../../engine/plain-object.mjs';
 import { found, readJson } from './read.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 export const CONTRACT_BREAKING = 'BE_CONTRACT_BREAKING';
 
@@ -21,43 +22,60 @@ const same = (a, b) => JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b
 function sortKeys(value) {
   if (Array.isArray(value)) return value.map(sortKeys);
   if (!isPlainObject(value)) return value;
-  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortKeys(value[key])]));
+  return Object.fromEntries(Object.keys(value).sort(byCodeUnit).map((key) => [key, sortKeys(value[key])]));
 }
 /** {type, optional} of a payload field spelling (`string`, `number?`, `string[]`). */
 const fieldOf = (spelling) => (typeof spelling === 'string' && spelling.endsWith('?') ? { type: spelling.slice(0, -1), optional: true } : { type: spelling, optional: false });
 
+function eventMetadataChanges(name, before, after) {
+  const problems = [];
+  for (const key of Object.keys(before)) {
+    if (key === 'payload') continue;
+    if (!same(before[key], after[key])) problems.push({ event: name, message: `event ${name} changed its ${key} from ${JSON.stringify(before[key])} to ${JSON.stringify(after[key] ?? null)}; a published event keeps its ${key}. Add ${name}.v2 for the new shape.` });
+  }
+  return problems;
+}
+
+function existingPayloadChanges(name, was, now) {
+  const problems = [];
+  for (const [field, spelling] of Object.entries(was)) {
+    if (!(field in now)) { problems.push({ event: name, message: `event ${name} lost payload field ${field}; fields are only ever added. Keep it, and add ${name}.v2 for the new shape.` }); continue; }
+    const a = fieldOf(spelling);
+    const b = fieldOf(now[field]);
+    if (a.type !== b.type) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.type} to ${b.type}; a field keeps its type. Add ${name}.v2 for the new shape.` });
+    else if (a.optional !== b.optional) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.optional ? 'optional' : 'required'} to ${b.optional ? 'optional' : 'required'}; a field keeps its optionality. Add ${name}.v2 for the new shape.` });
+  }
+  return problems;
+}
+
+function addedRequiredPayloadChanges(name, was, now) {
+  const problems = [];
+  for (const [field, spelling] of Object.entries(now)) {
+    if (!(field in was) && !fieldOf(spelling).optional) problems.push({ event: name, message: `event ${name} gained required payload field ${field}; events already on the wire do not carry it, so a new field is optional (${field}?). Make it optional, or add ${name}.v2.` });
+  }
+  return problems;
+}
+
+function eventChanges(name, before, after) {
+  if (!isPlainObject(after)) return [{ event: name, message: `event ${name} was removed; a published event is never deleted while it can still be on the wire. Keep it, and add ${name}.v2 for the new shape.` }];
+  const was = isPlainObject(before.payload) ? before.payload : {};
+  const now = isPlainObject(after.payload) ? after.payload : {};
+  return [...eventMetadataChanges(name, before, after), ...existingPayloadChanges(name, was, now), ...addedRequiredPayloadChanges(name, was, now)];
+}
+
 /** The breaking changes of `current` against `pinned`: [{event, message}]. */
 export function breakingChanges(pinned, current) {
   const problems = [];
   const pinnedEvents = isPlainObject(pinned?.events) ? pinned.events : {};
   const currentEvents = isPlainObject(current?.events) ? current.events : {};
-  for (const [name, before] of Object.entries(pinnedEvents)) {
-    const after = currentEvents[name];
-    if (!isPlainObject(after)) { problems.push({ event: name, message: `event ${name} was removed; a published event is never deleted while it can still be on the wire. Keep it, and add ${name}.v2 for the new shape.` }); continue; }
-    for (const key of Object.keys(before)) {
-      if (key === 'payload') continue;
-      if (!same(before[key], after[key])) problems.push({ event: name, message: `event ${name} changed its ${key} from ${JSON.stringify(before[key])} to ${JSON.stringify(after[key] ?? null)}; a published event keeps its ${key}. Add ${name}.v2 for the new shape.` });
-    }
-    const was = isPlainObject(before.payload) ? before.payload : {};
-    const now = isPlainObject(after.payload) ? after.payload : {};
-    for (const [field, spelling] of Object.entries(was)) {
-      if (!(field in now)) { problems.push({ event: name, message: `event ${name} lost payload field ${field}; fields are only ever added. Keep it, and add ${name}.v2 for the new shape.` }); continue; }
-      const a = fieldOf(spelling);
-      const b = fieldOf(now[field]);
-      if (a.type !== b.type) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.type} to ${b.type}; a field keeps its type. Add ${name}.v2 for the new shape.` });
-      else if (a.optional !== b.optional) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.optional ? 'optional' : 'required'} to ${b.optional ? 'optional' : 'required'}; a field keeps its optionality. Add ${name}.v2 for the new shape.` });
-    }
-    for (const [field, spelling] of Object.entries(now)) {
-      if (!(field in was) && !fieldOf(spelling).optional) problems.push({ event: name, message: `event ${name} gained required payload field ${field}; events already on the wire do not carry it, so a new field is optional (${field}?). Make it optional, or add ${name}.v2.` });
-    }
-  }
+  for (const [name, before] of Object.entries(pinnedEvents)) problems.push(...eventChanges(name, before, currentEvents[name]));
   return problems;
 }
 
 /** R177: the findings of every service whose contract is pinned. `files` are the repository-relative tracked paths. */
 export function contractCompatFindings({ repoRoot, files }) {
   const findings = [];
-  for (const rel of [...files].sort()) {
+  for (const rel of [...files].sort(byCodeUnit)) {
     const match = CONTRACTS.exec(rel);
     if (!match) continue;
     const current = `be/contracts/${match[1]}/events.json`;