@starci/hfs 4.0.10 → 4.2.0

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 { parseYamlCached } from '../lib/yaml-cached.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 = parseYamlCached(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`;

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

@@ -8,10 +8,10 @@
 // api app into a temp directory through the injected `emit` (packages/hfs/emit) and compares hashes; an emit that cannot run is a finding.
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { found, readText } from './read.mjs';
 import { safeRemove } from '../../api/fs/safe-remove.mjs';
+import { makeTempDir } from '../../api/fs/make-temp-dir.mjs';
 
 export const CONTRACT_SNAPSHOT_DRIFT = 'HFS_CONTRACT_SNAPSHOT_DRIFT';
 const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
@@ -19,7 +19,7 @@ const SNAPSHOT_OF = { graphql: 'schema.graphql', json: 'openapi.json' };
 
 /** sha256 of a file's text with line endings folded, or null when it cannot be read. */
 function contractHash(file) {
-  try { return createHash('sha256').update(fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n')).digest('hex'); } catch { return null; }
+  try { return createHash('sha256').update(fs.readFileSync(file, 'utf8').replaceAll('\r\n', '\n')).digest('hex'); } catch { return null; }
 }
 
 /** The findings of R23 for the be side at `repoRoot` (a side of another profile has none). */
@@ -42,6 +42,36 @@ export function contractFindings({ repoRoot, files, repo, resolver }) {
 /** The first lines of an error, enough to act on. */
 const errorText = (error) => String(error?.message ?? error).split(/\r?\n/).filter(Boolean).slice(0, 4).join(' | ');
 
+function emitFailure(app, artifacts, error, apps, findings) {
+  for (const { artifact } of artifacts) apps.push({ app: app.name, artifact, status: 'emit-failed' });
+  const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
+  findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `contracts/${app.name} cannot be verified: \`starci app emit\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
+}
+
+function artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emitted, apps, findings }) {
+  const snapshot = `contracts/${app.name}/${artifact}`;
+  const committed = tracked.has(snapshot) ? contractHash(path.join(repoRoot, snapshot)) : null;
+  if (!emitted.written.includes(snapshot)) {
+    if (committed === null) {
+      if (artifact === SNAPSHOT_OF.graphql) apps.push({ app: app.name, artifact, status: 'none' });
+      return;
+    }
+    apps.push({ app: app.name, artifact, status: 'left-behind' });
+    findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} is committed but ${app.name} ${what}; delete it`, { app: app.name, drift: 'left-behind' }));
+    return;
+  }
+  const fresh = contractHash(path.join(scratch, snapshot));
+  if (committed === null) {
+    // the uncommitted snapshot itself is reported by contractFindings above; here it only counts as not judged
+    apps.push({ app: app.name, artifact, status: 'not-committed' });
+  } else if (committed === fresh) {
+    apps.push({ app: app.name, artifact, status: 'fresh' });
+  } else {
+    apps.push({ app: app.name, artifact, status: 'stale' });
+    findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} (${committed.slice(0, 12)}) differs from what ${app.name} emits now (${String(fresh).slice(0, 12)}); run \`npm run contract:emit\` and commit the result`, { app: app.name, drift: 'stale' }));
+  }
+}
+
 /**
  * R23, full pass: each committed `contracts/<app>/schema.graphql` and `contracts/<app>/openapi.json` equals what `emit` writes for
  * the app now. `emit({ repoRoot, declaration, outDir })` is `emitContracts` of packages/hfs/emit and answers `{ written, skipped }`;
@@ -56,7 +86,7 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
   const apps = [];
   if (repo.profile !== 'be') return { findings, apps };
   const tracked = new Set(files);
-  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'hfs-contracts-'));
+  const scratch = makeTempDir('hfs-contracts-');
   try {
     for (const app of repo.apps.filter((a) => a.kind === 'api')) {
       const artifacts = [{ artifact: SNAPSHOT_OF.graphql, what: 'serves no GraphQL any more' }, { artifact: SNAPSHOT_OF.json, what: 'declares no operations any more' }];
@@ -64,33 +94,11 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
       try {
         emitted = emit({ repoRoot, declaration: { apps: [app] }, outDir: scratch });
       } catch (error) {
-        for (const { artifact } of artifacts) apps.push({ app: app.name, artifact, status: 'emit-failed' });
-        const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
-        findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `contracts/${app.name} cannot be verified: \`starci app emit\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
+        emitFailure(app, artifacts, error, apps, findings);
         continue;
       }
       for (const { artifact, what } of artifacts) {
-        const snapshot = `contracts/${app.name}/${artifact}`;
-        const committed = tracked.has(snapshot) ? contractHash(path.join(repoRoot, snapshot)) : null;
-        if (!emitted.written.includes(snapshot)) {
-          if (committed === null) {
-            if (artifact === SNAPSHOT_OF.graphql) apps.push({ app: app.name, artifact, status: 'none' });
-            continue;
-          }
-          apps.push({ app: app.name, artifact, status: 'left-behind' });
-          findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} is committed but ${app.name} ${what}; delete it`, { app: app.name, drift: 'left-behind' }));
-          continue;
-        }
-        const fresh = contractHash(path.join(scratch, snapshot));
-        if (committed === null) {
-          // the uncommitted snapshot itself is reported by contractFindings above; here it only counts as not judged
-          apps.push({ app: app.name, artifact, status: 'not-committed' });
-        } else if (committed === fresh) {
-          apps.push({ app: app.name, artifact, status: 'fresh' });
-        } else {
-          apps.push({ app: app.name, artifact, status: 'stale' });
-          findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} (${committed.slice(0, 12)}) differs from what ${app.name} emits now (${String(fresh).slice(0, 12)}); run \`npm run contract:emit\` and commit the result`, { app: app.name, drift: 'stale' }));
-        }
+        artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emitted, apps, findings });
       }
     }
   } finally {

package/runtime/scripts/hfs/rules/database-config.mjs

@@ -3,7 +3,7 @@
 import { sameText } from '../../lib/same-text.mjs';
 import { found, readText } from './read.mjs';
 import { DB_CONFIG_POLICY, DB_TYPES_DRIFT, TYPES_FILE } from './database-constants.mjs';
-const ENV_REF = /^env\([A-Za-z_][A-Za-z0-9_]*\)$/;
+const ENV_REF = /^env\([A-Za-z_]\w*\)$/;
 const PUBLIC_KEYS = new Set(['anon_key', 'publishable_key', 'public_key']);
 
 
@@ -28,17 +28,69 @@ const isCredentialKey = (key) => {
     || (leaf.endsWith('_key') && !PUBLIC_KEYS.has(leaf));
 };
 
+const escapeRegexPart = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+
 const tomlLine = (text, key) => {
-  const expression = new RegExp(`^\\s*["']?${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']?\\s*=`, 'm');
+  const expression = new RegExp(String.raw`^\s*["']?${escapeRegexPart(key)}["']?\s*=`, 'm');
   const match = expression.exec(text);
   return match ? text.slice(0, match.index).split('\n').length : undefined;
 };
 
+function credentialConfigFindings(file, text, toml) {
+  const findings = [];
+  for (const [at, key, value] of tomlEntries(toml)) {
+    if (!isCredentialKey(key)) continue;
+    const line = tomlLine(text, key);
+    if (typeof value !== 'string' || !ENV_REF.test(value)) {
+      const lineNote = line ? `:${line}` : '';
+      findings.push(found(DB_CONFIG_POLICY, file, `${file}${lineNote} ${at} holds a literal credential; a secret in config.toml is written env(NAME), never a value`, { ...(line ? { line } : {}), key: at }));
+    }
+  }
+  return findings;
+}
+
+// A finding for an auth setting of config.toml that differs from what hfs.json supabase.<field> declares; `shown` is the setting as read.
+const settingFinding = (file, key, field, shown, declaredValue, note = '') => found(DB_CONFIG_POLICY, file, `${file} ${key} is ${shown}; hfs.json supabase.${field} declares ${declaredValue}${note}`, { key, declared: declaredValue });
+
+const shownSetting = (value) => JSON.stringify(value ?? 'absent');
+
+function signupFindings(file, auth, declared) {
+  const findings = [];
+  if (declared.enableSignup === undefined) return findings;
+  if (auth.enable_signup !== declared.enableSignup) findings.push(settingFinding(file, 'auth.enable_signup', 'enableSignup', shownSetting(auth.enable_signup), declared.enableSignup, ' - the invite posture is a checked fact, not a doc claim'));
+  if (auth.email?.enable_signup !== undefined && auth.email.enable_signup !== declared.enableSignup) {
+    findings.push(settingFinding(file, 'auth.email.enable_signup', 'enableSignup', JSON.stringify(auth.email.enable_signup), declared.enableSignup));
+  }
+  return findings;
+}
+
+function redirectUrlFindings(file, auth, declared) {
+  const findings = [];
+  if (declared.redirectUrls === undefined) return findings;
+  const configured = Array.isArray(auth.additional_redirect_urls) ? auth.additional_redirect_urls : [];
+  for (const url of configured) {
+    if (!declared.redirectUrls.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls holds ${url}, which hfs.json supabase.redirectUrls does not declare; the config states nothing the app did not declare`, { key: 'auth.additional_redirect_urls', url }));
+  }
+  for (const url of declared.redirectUrls) {
+    if (!configured.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls omits ${url}, which hfs.json supabase.redirectUrls declares; the config and declaration must carry the same redirect set`, { key: 'auth.additional_redirect_urls', url }));
+  }
+  return findings;
+}
+
+function declarationConfigFindings(file, auth, declared) {
+  const findings = [];
+  if (declared.jwtExpiry !== undefined && auth.jwt_expiry !== declared.jwtExpiry) findings.push(settingFinding(file, 'auth.jwt_expiry', 'jwtExpiry', shownSetting(auth.jwt_expiry), declared.jwtExpiry));
+  findings.push(...signupFindings(file, auth, declared));
+  if (declared.siteUrl !== undefined && auth.site_url !== declared.siteUrl) findings.push(settingFinding(file, 'auth.site_url', 'siteUrl', shownSetting(auth.site_url), declared.siteUrl));
+  findings.push(...redirectUrlFindings(file, auth, declared));
+  return findings;
+}
+
 /** The parsed TOML of `text`, or null when it does not parse. */
 export async function parseToml(text) {
   try {
     const module = await import('smol-toml');
-    return (module.default?.parse ?? module.parse)(text);
+    return module.parse(text);
   } catch {
     return null;
   }
@@ -46,14 +98,7 @@ export async function parseToml(text) {
 
 /** L08 policy findings in one already-parsed supabase/config.toml. */
 export function configFindings({ file, text, toml, supabase }) {
-  const findings = [];
-  for (const [at, key, value] of tomlEntries(toml)) {
-    if (!isCredentialKey(key)) continue;
-    const line = tomlLine(text, key);
-    if (typeof value !== 'string' || !ENV_REF.test(value)) {
-      findings.push(found(DB_CONFIG_POLICY, file, `${file}${line ? `:${line}` : ''} ${at} holds a literal credential; a secret in config.toml is written env(NAME), never a value`, { ...(line ? { line } : {}), key: at }));
-    }
-  }
+  const findings = credentialConfigFindings(file, text, toml);
   const auth = toml?.auth ?? {};
   if (auth.jwt_expiry !== undefined && (typeof auth.jwt_expiry !== 'number' || auth.jwt_expiry > 3600)) {
     findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.jwt_expiry is ${JSON.stringify(auth.jwt_expiry)}; the access token lives at most 3600 seconds`, { key: 'auth.jwt_expiry' }));
@@ -63,27 +108,7 @@ export function configFindings({ file, text, toml, supabase }) {
     enableSignup: supabase.enableSignup, jwtExpiry: supabase.jwtExpiry, siteUrl: supabase.siteUrl,
     redirectUrls: Array.isArray(supabase.redirectUrls) ? supabase.redirectUrls : undefined,
   };
-  if (declared.jwtExpiry !== undefined && auth.jwt_expiry !== declared.jwtExpiry) {
-    findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.jwt_expiry is ${JSON.stringify(auth.jwt_expiry ?? 'absent')}; hfs.json supabase.jwtExpiry declares ${declared.jwtExpiry}`, { key: 'auth.jwt_expiry', declared: declared.jwtExpiry }));
-  }
-  if (declared.enableSignup !== undefined) {
-    if (auth.enable_signup !== declared.enableSignup) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.enable_signup is ${JSON.stringify(auth.enable_signup ?? 'absent')}; hfs.json supabase.enableSignup declares ${declared.enableSignup} - the invite posture is a checked fact, not a doc claim`, { key: 'auth.enable_signup', declared: declared.enableSignup }));
-    if (auth.email?.enable_signup !== undefined && auth.email.enable_signup !== declared.enableSignup) {
-      findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.email.enable_signup is ${JSON.stringify(auth.email.enable_signup)}; hfs.json supabase.enableSignup declares ${declared.enableSignup}`, { key: 'auth.email.enable_signup', declared: declared.enableSignup }));
-    }
-  }
-  if (declared.siteUrl !== undefined && auth.site_url !== declared.siteUrl) {
-    findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.site_url is ${JSON.stringify(auth.site_url ?? 'absent')}; hfs.json supabase.siteUrl declares ${declared.siteUrl}`, { key: 'auth.site_url', declared: declared.siteUrl }));
-  }
-  if (declared.redirectUrls !== undefined) {
-    const configured = Array.isArray(auth.additional_redirect_urls) ? auth.additional_redirect_urls : [];
-    for (const url of configured) {
-      if (!declared.redirectUrls.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls holds ${url}, which hfs.json supabase.redirectUrls does not declare; the config states nothing the app did not declare`, { key: 'auth.additional_redirect_urls', url }));
-    }
-    for (const url of declared.redirectUrls) {
-      if (!configured.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls omits ${url}, which hfs.json supabase.redirectUrls declares; the config and declaration must carry the same redirect set`, { key: 'auth.additional_redirect_urls', url }));
-    }
-  }
+  findings.push(...declarationConfigFindings(file, auth, declared));
   return findings;
 }