@starci/hfs 1.0.1 → 2.0.1

package/runtime/scripts/lib/hfs-slots.mjs

@@ -12,8 +12,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-import { braceVariants } from './glob.mjs';
+import { braceVariants, globExpression } from './glob.mjs';
 import { posixPath } from './path-key.mjs';
+import { isPlainObject } from '../../engine/plain-object.mjs';
 
 export const HFS_MANIFEST_FILE = 'knowledge/hfs/slots.yaml';
 export const HFS_DECLARATION_FILE = 'hfs.json';
@@ -30,12 +31,12 @@ export class HfsSlotsError extends Error {
 
 const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
 const NAME = /^[a-z][a-z0-9-]*$/;
+const ENV_PREFIX = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/;
 const SLOT_ID = /^(repo|be|fe)\.[a-z0-9-]+(\.[a-z0-9-]+)*$/;
 const PRESENCE = ['required', 'optional', 'opt-in', 'forbidden'];
 const TRACKED = ['tracked', 'ignored', 'external'];
 const TESTS = ['unit-beside', 'e2e', 'none'];
 const PROFILES = ['be', 'fe'];
-const isMap = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const strList = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0);
 
 // ------------------------------------------------------------------------------------------------ patterns
@@ -118,17 +119,17 @@ const fail = (code, message, details) => { throw new HfsSlotsError(code, message
 /** Shape problems of a parsed manifest, in the words of modules/schemas/hfs-slots.schema.yaml. */
 function manifestShapeProblems(m) {
   const bad = [];
-  if (!isMap(m)) return ['the manifest is not a map'];
+  if (!isPlainObject(m)) return ['the manifest is not a map'];
   const allowed = new Set(['schema', 'version', 'versioning', 'presenceValues', 'trackedValues', 'testValues', 'appKinds', 'tiers', 'ruleParams', 'crossOwner', 'crossApp', 'slots', 'consumers']);
   for (const key of Object.keys(m)) if (!allowed.has(key)) bad.push(`unknown top-level key ${key}`);
   if (!/^starci\/hfs-slots@\d+$/.test(String(m.schema))) bad.push('schema must be starci/hfs-slots@<major>');
   if (!SEMVER.test(String(m.version))) bad.push('version must be MAJOR.MINOR.PATCH');
-  if (!isMap(m.versioning) || !['patch', 'minor', 'major', 'retire', 'pins'].every((k) => typeof m.versioning[k] === 'string')) bad.push('versioning needs patch, minor, major, retire and pins text');
+  if (!isPlainObject(m.versioning) || !['patch', 'minor', 'major', 'retire', 'pins'].every((k) => typeof m.versioning[k] === 'string')) bad.push('versioning needs patch, minor, major, retire and pins text');
   if (JSON.stringify(m.presenceValues) !== JSON.stringify(PRESENCE)) bad.push(`presenceValues must be ${PRESENCE.join(', ')}`);
   if (JSON.stringify(m.trackedValues) !== JSON.stringify(TRACKED)) bad.push(`trackedValues must be ${TRACKED.join(', ')}`);
   if (JSON.stringify(m.testValues) !== JSON.stringify(TESTS)) bad.push(`testValues must be ${TESTS.join(', ')}`);
   for (const key of ['appKinds', 'tiers']) {
-    if (!isMap(m[key])) { bad.push(`${key} must be a map with be and fe`); continue; }
+    if (!isPlainObject(m[key])) { bad.push(`${key} must be a map with be and fe`); continue; }
     for (const extra of Object.keys(m[key])) if (!PROFILES.includes(extra)) bad.push(`${key}.${extra} is not a profile`);
     for (const profile of PROFILES) if (!(profile in m[key])) bad.push(`${key}.${profile} is missing`);
   }
@@ -137,26 +138,40 @@ function manifestShapeProblems(m) {
     if (kinds !== undefined && (!Array.isArray(kinds) || !kinds.length || !kinds.every((k) => NAME.test(String(k))) || new Set(kinds).size !== kinds.length)) bad.push(`appKinds.${profile} must be a non-empty list of unique names`);
     const tiers = m.tiers?.[profile];
     if (tiers === undefined) continue;
-    if (!isMap(tiers) || !Object.keys(tiers).length) { bad.push(`tiers.${profile} must be a non-empty map`); continue; }
+    if (!isPlainObject(tiers) || !Object.keys(tiers).length) { bad.push(`tiers.${profile} must be a non-empty map`); continue; }
     for (const [tier, def] of Object.entries(tiers)) {
       if (!NAME.test(tier)) bad.push(`tiers.${profile}.${tier} is not a tier name`);
-      if (!isMap(def) || !Array.isArray(def.mayImport) || !def.mayImport.every((t) => NAME.test(String(t)))) bad.push(`tiers.${profile}.${tier}.mayImport must be a list of tier names`);
+      if (!isPlainObject(def) || !Array.isArray(def.mayImport) || !def.mayImport.every((t) => NAME.test(String(t)))) bad.push(`tiers.${profile}.${tier}.mayImport must be a list of tier names`);
       for (const key of Object.keys(def ?? {})) if (!['mayImport', 'acyclic', 'lowerLayerOnly'].includes(key)) bad.push(`tiers.${profile}.${tier}.${key} is not a tier field`);
     }
   }
-  const blockOk = (v) => isMap(v) && Number.isInteger(v.lines) && v.lines >= 2 && Number.isInteger(v.tokens) && v.tokens >= 1 && Object.keys(v).length === 2;
-  const fileLinesOk = (v) => isMap(v) && Number.isInteger(v.soft) && v.soft >= 1 && typeof v.hardGrowth === 'boolean' && Object.keys(v).length === 2;
+  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 (!isMap(rp) || Object.keys(rp).some((k) => !PROFILES.includes(k)) || !PROFILES.every((p) => isMap(rp[p]))) bad.push('ruleParams must be a map with be and fe');
+  if (!isPlainObject(rp) || Object.keys(rp).some((k) => !PROFILES.includes(k)) || !PROFILES.every((p) => isPlainObject(rp[p]))) bad.push('ruleParams must be a map with be and fe');
   else {
-    if (!(strList(rp.be.globalModules) && new Set(rp.be.globalModules).size === rp.be.globalModules.length) || !fileLinesOk(rp.be.fileLines) || !blockOk(rp.be.duplicateBlock) || Object.keys(rp.be).length !== 3) bad.push('ruleParams.be needs globalModules (unique paths), fileLines {soft, hardGrowth} and duplicateBlock {lines >= 2, tokens >= 1}');
-    if (!fileLinesOk(rp.fe.fileLines) || typeof rp.fe.clientModule !== 'string' || !rp.fe.clientModule || !blockOk(rp.fe.duplicateBlock) || Object.keys(rp.fe).length !== 3) bad.push('ruleParams.fe needs fileLines {soft, hardGrowth}, clientModule and duplicateBlock {lines >= 2, tokens >= 1}');
+    if (!fileLinesOk(rp.be.fileLines) || !blockOk(rp.be.duplicateBlock) || Object.keys(rp.be).length !== 7) bad.push('ruleParams.be needs fileLines {soft, hardGrowth}, duplicateBlock {lines >= 2, tokens >= 1}, infraOwners, specDoubles, suffixes, bannedSuffixes and contractShape {helper}');
+    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 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');
+    if (!fileLinesOk(rp.fe.fileLines) || !blockOk(rp.fe.duplicateBlock) || Object.keys(rp.fe).length !== 2) bad.push('ruleParams.fe needs fileLines {soft, hardGrowth} and duplicateBlock {lines >= 2, tokens >= 1}');
   }
   if (!Array.isArray(m.slots) || !m.slots.length) { bad.push('slots must be a non-empty list'); return bad; }
-  const slotKeys = new Set(['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'allows', 'forbids', 'layers', 'budget', 'managedBy', 'rules', 'goesTo', 'why', 'since', 'retiredIn', 'successor']);
+  const slotKeys = new Set(['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'rules', 'goesTo', 'why', 'since', 'retiredIn', 'successor']);
   m.slots.forEach((slot, index) => {
-    const at = isMap(slot) && typeof slot.id === 'string' ? `slot ${slot.id}` : `slots[${index}]`;
-    if (!isMap(slot)) { bad.push(`${at} is not a map`); return; }
+    const at = isPlainObject(slot) && typeof slot.id === 'string' ? `slot ${slot.id}` : `slots[${index}]`;
+    if (!isPlainObject(slot)) { bad.push(`${at} is not a map`); return; }
     for (const key of Object.keys(slot)) if (!slotKeys.has(key)) bad.push(`${at}: unknown field ${key}`);
     if (!SLOT_ID.test(String(slot.id))) bad.push(`${at}: id must look like be.transport.http`);
     if (!Array.isArray(slot.profiles) || !slot.profiles.length || !slot.profiles.every((p) => PROFILES.includes(p)) || new Set(slot.profiles).size !== slot.profiles.length) bad.push(`${at}: profiles must be a unique non-empty subset of be, fe`);
@@ -169,9 +184,12 @@ function manifestShapeProblems(m) {
     if (slot.appKind !== undefined && !NAME.test(String(slot.appKind))) bad.push(`${at}: appKind must be a name`);
     if (slot.minInstances !== undefined && !(Number.isInteger(slot.minInstances) && slot.minInstances >= 1)) bad.push(`${at}: minInstances must be a positive integer`);
     if (slot.requiredWhen !== undefined && slot.requiredWhen !== 'connections') bad.push(`${at}: requiredWhen may only be connections`);
-    if (slot.requiredInstances !== undefined && !(isMap(slot.requiredInstances) && Object.values(slot.requiredInstances).every((v) => strList(v) && v.length))) bad.push(`${at}: requiredInstances must map a variable to a non-empty list of names`);
-    for (const key of ['requires', 'allows', 'forbids', 'layers']) if (slot[key] !== undefined && !strList(slot[key])) bad.push(`${at}: ${key} must be a list of strings`);
-    if (slot.budget !== undefined && !(isMap(slot.budget) && Object.keys(slot.budget).length && Object.values(slot.budget).every((v) => Number.isInteger(v) && v >= 1))) bad.push(`${at}: budget must map names to positive integers`);
+    if (slot.requiredInstances !== undefined && !(isPlainObject(slot.requiredInstances) && Object.values(slot.requiredInstances).every((v) => strList(v) && v.length))) bad.push(`${at}: requiredInstances must map a variable to a non-empty list of names`);
+    for (const key of ['requires', 'allows', 'forbids', 'layers', 'kinds']) if (slot[key] !== undefined && !strList(slot[key])) bad.push(`${at}: ${key} must be a list of strings`);
+    if (slot.kinds !== undefined && strList(slot.kinds) && (!slot.kinds.length || new Set(slot.kinds).size !== slot.kinds.length || slot.kinds.some((k) => !NAME.test(k) || (slot.layers ?? []).includes(k)))) bad.push(`${at}: kinds must be a non-empty list of unique folder names that are not layers`);
+    if (slot.roles !== undefined && !(isPlainObject(slot.roles) && Object.keys(slot.roles).length && Object.entries(slot.roles).every(([role, file]) => NAME.test(role) && typeof file === 'string' && file && !file.includes('/')))) bad.push(`${at}: roles must map a role name to a file name`);
+    if (slot.composedBy !== undefined && !(strList(slot.composedBy) && slot.composedBy.length && new Set(slot.composedBy).size === slot.composedBy.length)) bad.push(`${at}: composedBy must be a non-empty list of unique app kinds`);
+    if (slot.budget !== undefined && !(isPlainObject(slot.budget) && Object.keys(slot.budget).length && Object.values(slot.budget).every((v) => Number.isInteger(v) && v >= 1))) bad.push(`${at}: budget must map names to positive integers`);
     if (slot.managedBy !== undefined && !NAME.test(String(slot.managedBy))) bad.push(`${at}: managedBy must be a template id`);
     if (slot.rules !== undefined && !(Array.isArray(slot.rules) && slot.rules.every((r) => /^[A-Z][A-Z0-9_]*\*?$/.test(String(r))) && new Set(slot.rules).size === slot.rules.length)) bad.push(`${at}: rules must be unique rule ids`);
     if (slot.since !== undefined && !SEMVER.test(String(slot.since))) bad.push(`${at}: since must be a version`);
@@ -207,11 +225,13 @@ function manifestSemanticProblems(m) {
     if (slot.appKind !== undefined && !pathVars.has('app')) bad.push(`slot ${slot.id}: an app-kind slot binds <app> in its path`);
     if (slot.requiredWhen !== undefined && slot.presence !== 'required') bad.push(`slot ${slot.id}: requiredWhen belongs to a required slot`);
     for (const name of Object.keys(slot.requiredInstances ?? {})) if (!pathVars.has(name)) bad.push(`slot ${slot.id}: requiredInstances names <${name}>, which the path does not bind`);
+    for (const file of Object.values(slot.roles ?? {})) for (const name of varsOf(file)) if (!pathVars.has(name)) bad.push(`slot ${slot.id}: roles names <${name}> in ${file}, which the path does not bind`);
     for (const entry of slot.requires ?? []) for (const name of varsOf(entry)) if (!pathVars.has(name)) bad.push(`slot ${slot.id}: requires ${entry} uses <${name}>, which the path does not bind`);
     for (const variant of braceVariants(slot.path)) {
       try { compileVariant(slot, variant); } catch (error) { bad.push(`slot ${slot.id}: pattern ${variant} does not compile (${error.message})`); }
     }
     if (slot.successor !== undefined && !m.slots.some((s) => s.id === slot.successor)) bad.push(`slot ${slot.id}: successor ${slot.successor} is not a slot`);
+    for (const kind of slot.composedBy ?? []) if (!slot.profiles.every((p) => m.appKinds[p].includes(kind))) bad.push(`slot ${slot.id}: composedBy names ${kind}, which is not an app kind of every profile of the slot`);
     if (slot.layers !== undefined && slot.tier !== 'none' && !slot.profiles.every((p) => m.tiers[p][slot.tier]?.lowerLayerOnly)) bad.push(`slot ${slot.id}: layers need a lowerLayerOnly tier`);
   }
   for (const profile of PROFILES) {
@@ -247,20 +267,25 @@ export function loadSlotManifest({ root = skillRoot, file = path.join(root, HFS_
 /** Shape problems of a parsed hfs.json, in the words of modules/schemas/hfs-repo.schema.yaml. */
 function declarationShapeProblems(d) {
   const bad = [];
-  if (!isMap(d)) return ['hfs.json is not an object'];
+  if (!isPlainObject(d)) return ['hfs.json is not an object'];
   for (const key of Object.keys(d)) if (!['hfs', 'profile', 'project', 'apps', 'optionalSlots', 'connections', 'stacks'].includes(key)) bad.push(`unknown key ${key}`);
   if (!(Number.isInteger(d.hfs) && d.hfs >= 1)) bad.push('hfs must be the pinned manifest major (an integer, 1 or more)');
   if (!PROFILES.includes(d.profile)) bad.push('profile must be be or fe');
   if (!NAME.test(String(d.project))) bad.push('project must be a project name');
   if (!Array.isArray(d.apps) || !d.apps.length) bad.push('apps must list every apps/<name> with its kind');
   else d.apps.forEach((app, i) => {
-    if (!isMap(app) || !NAME.test(String(app.name)) || !NAME.test(String(app.kind)) || Object.keys(app).some((k) => k !== 'name' && k !== 'kind')) bad.push(`apps[${i}] must be {name, kind}`);
+    if (!isPlainObject(app) || !NAME.test(String(app.name)) || !NAME.test(String(app.kind)) || Object.keys(app).some((k) => k !== 'name' && k !== 'kind')) bad.push(`apps[${i}] must be {name, kind}`);
   });
   if (d.stacks !== undefined && (d.profile !== 'fe' || typeof d.stacks !== 'string' || !d.stacks || /^([a-zA-Z]:)?[\/]/.test(d.stacks))) bad.push('stacks is front end only and must be a relative path to the sibling back-end repository');
-  for (const key of ['optionalSlots', 'connections']) {
-    if (d[key] === undefined) continue;
-    const pattern = key === 'optionalSlots' ? SLOT_ID : NAME;
-    if (!Array.isArray(d[key]) || !d[key].every((v) => pattern.test(String(v))) || new Set(d[key]).size !== d[key].length) bad.push(`${key} must be a unique list of ${key === 'optionalSlots' ? 'slot ids' : 'connection names'}`);
+  if (d.optionalSlots !== undefined && (!Array.isArray(d.optionalSlots) || !d.optionalSlots.every((v) => SLOT_ID.test(String(v))) || new Set(d.optionalSlots).size !== d.optionalSlots.length)) bad.push('optionalSlots must be a unique list of slot ids');
+  if (d.connections !== undefined) {
+    // One physical database = one entry (R84): {name, envPrefix}; names and env prefixes unique, no prefix inside another's keys.
+    const list = Array.isArray(d.connections) ? d.connections : null;
+    if (!list || !list.every((c) => isPlainObject(c) && NAME.test(String(c.name)) && ENV_PREFIX.test(String(c.envPrefix)) && Object.keys(c).length === 2)) bad.push('connections must be a list of {name: kebab-case database name, envPrefix: UPPER_SNAKE prefix of its env keys}');
+    else {
+      if (new Set(list.map((c) => c.name)).size !== list.length) bad.push('connections names must be unique');
+      for (const a of list) for (const b of list) if (a !== b && `${b.envPrefix}_`.startsWith(`${a.envPrefix}_`)) bad.push(`connections ${a.name} and ${b.name} share env keys (${a.envPrefix}_ covers ${b.envPrefix}_)`);
+    }
   }
   if (d.profile === 'fe' && d.connections !== undefined) bad.push('connections belong to a backend repository');
   return bad;
@@ -305,7 +330,7 @@ export function resolveRepoDeclaration(manifest, declaration, { file = HFS_DECLA
     project: declaration.project,
     apps: Object.freeze(declaration.apps.map((a) => Object.freeze({ name: a.name, kind: a.kind }))),
     optionalSlots: Object.freeze([...(declaration.optionalSlots ?? [])]),
-    connections: Object.freeze([...connections]),
+    connections: Object.freeze(connections.map((c) => Object.freeze({ name: c.name, envPrefix: c.envPrefix }))),
     manifestVersion: manifest.version,
   });
 }
@@ -389,18 +414,41 @@ export function createSlotResolver(manifest, repo) {
     };
   }
 
+  /**
+   * The folder kind of a file: the layer or kind folder its slot names (`layers`, `kinds`) that the file sits in. A slot whose
+   * path spells the choice (`components/{blocks,leaves}/<name>/`) answers from the matched pattern; a slot that owns a whole
+   * directory (`packages/<family>-ui/`) answers from the first folder below its root that the list names.
+   */
+  function kindOf({ variant, slot, root }, p) {
+    const names = [...(slot.layers ?? []), ...(slot.kinds ?? [])];
+    if (!names.length) return null;
+    const literal = variant.segments.find((segment) => names.includes(segment));
+    if (literal) return literal;
+    const below = root ? p.slice(root.length + 1) : p;
+    return below.split('/').slice(0, -1).find((segment) => names.includes(segment)) ?? null;
+  }
+
+  /** The role of a file in its slot: the entry of `roles` whose file name (variables filled from the path, `*` a wildcard inside the name) matches the file's name. */
+  function roleOf(slot, bindings, p) {
+    const name = p.split('/').pop();
+    for (const [role, file] of Object.entries(slot.roles ?? {})) if (globExpression(fillVars(file, bindings)).test(name)) return role;
+    return null;
+  }
+
   /**
    * status: owned | forbidden (external slot) | not-enabled (opt-in slot the repository did not declare) | ambiguous
-   * (two slots of equal specificity; a manifest gap) | no-slot (code HFS_PATH_NO_SLOT, with the nearest slot).
+   * (two slots of equal specificity; a manifest gap) | no-slot (code HFS_SLOT_UNDECLARED, with the nearest slot).
    */
   function classifyPath(input) {
     const p = clean(input);
     const { hit, ambiguous } = best(matches(p));
     if (ambiguous.length) return { path: p, status: 'ambiguous', candidates: ambiguous };
-    if (!hit) return { path: p, status: 'no-slot', code: 'HFS_PATH_NO_SLOT', nearest: nearest(p) };
+    if (!hit) return { path: p, status: 'no-slot', code: 'HFS_SLOT_UNDECLARED', nearest: nearest(p) };
     const { slot, root, bindings } = hit;
     const status = slot.presence === 'forbidden' ? 'forbidden' : (slotEnabled(slot) ? 'owned' : 'not-enabled');
-    return { path: p, status, slot: slot.id, root, bindings, presence: slot.presence, tracking: slot.tracked, ...(status === 'forbidden' ? { goesTo: slot.goesTo } : {}) };
+    const kind = kindOf(hit, p);
+    const role = roleOf(slot, bindings, p);
+    return { path: p, status, slot: slot.id, root, bindings, ...(kind ? { kind } : {}), ...(role ? { role } : {}), presence: slot.presence, tracking: slot.tracked, ...(status === 'forbidden' ? { goesTo: slot.goesTo } : {}) };
   }
 
   const slotOf = (p) => { const c = classifyPath(p); return c.slot ? byId.get(c.slot) : null; };
@@ -426,7 +474,7 @@ export function createSlotResolver(manifest, repo) {
 
   /**
    * Whether `fromPath` may import `toPath`: {allowed, reason, ...}. Reasons: sameOwner, untiered, crossApp,
-   * tierDirection, layerOrder, notPublicEntry, allowed, slotForbidden, slotNotEnabled, slotAmbiguous, and unowned (HFS_PATH_NO_SLOT for the path no slot owns).
+   * tierDirection, layerOrder, notPublicEntry, allowed, slotForbidden, slotNotEnabled, slotAmbiguous, and unowned (HFS_SLOT_UNDECLARED for the path no slot owns).
    * Cycles are a graph property and belong to the architecture check, not to one edge.
    */
   function importAllowed(fromPath, toPath) {
@@ -535,7 +583,7 @@ export function createSlotResolver(manifest, repo) {
   });
 }
 
-/** The rule parameters of one profile (be: globalModules, fileLines, duplicateBlock; fe: fileLines, clientModule, duplicateBlock), as a frozen deep copy. */
+/** The rule parameters of one profile (be: fileLines, duplicateBlock, infraOwners, suffixes, bannedSuffixes; fe: fileLines, duplicateBlock), as a frozen deep copy. */
 export function ruleParams(manifest, profile) {
   if (!PROFILES.includes(profile)) fail('HFS_MANIFEST_INVALID', `ruleParams has no profile ${profile}`, { profile });
   const deepFreeze = (v) => { if (v && typeof v === 'object') Object.values(v).forEach(deepFreeze); return Object.freeze(v); };
@@ -561,14 +609,14 @@ const FILE_ENFORCERS = ['machine', 'hfs', 'work-validate', 'sonar'];
 /** Shape and semantic problems of a parsed knowledge/hfs/rules.yaml, in the words of modules/schemas/hfs-rules.schema.yaml. */
 function ruleCatalogProblems(d) {
   const bad = [];
-  if (!isMap(d)) return ['the rule catalog is not a map'];
+  if (!isPlainObject(d)) return ['the rule catalog is not a map'];
   for (const key of Object.keys(d)) if (!['schema', 'version', 'gates', 'enforcerKinds', 'rules'].includes(key)) bad.push(`unknown top-level key ${key}`);
   const schemaOk = /^starci\/hfs-rules@\d+$/.test(String(d.schema));
   if (!schemaOk) bad.push('schema must be starci/hfs-rules@<major>');
   if (!SEMVER.test(String(d.version))) bad.push('version must be MAJOR.MINOR.PATCH');
   else if (schemaOk && d.schema.split('@')[1] !== d.version.split('.')[0]) bad.push('the major of version must equal the number after @ in schema');
   const vocabulary = (key, names) => {
-    if (!isMap(d[key])) { bad.push(`${key} must be a map`); return; }
+    if (!isPlainObject(d[key])) { bad.push(`${key} must be a map`); return; }
     if (JSON.stringify(Object.keys(d[key])) !== JSON.stringify(names)) bad.push(`${key} must list exactly ${names.join(', ')} in that order`);
     for (const [name, text] of Object.entries(d[key])) if (typeof text !== 'string' || !text.trim()) bad.push(`${key}.${name} needs a description`);
   };
@@ -578,14 +626,14 @@ function ruleCatalogProblems(d) {
   const codeOwner = new Map();
   d.rules.forEach((r, index) => {
     const at = `rules[${index}]`;
-    if (!isMap(r)) { bad.push(`${at} is not a map`); return; }
+    if (!isPlainObject(r)) { bad.push(`${at} is not a map`); return; }
     const label = typeof r.id === 'string' ? r.id : at;
-    for (const key of Object.keys(r)) if (!['id', 'code', 'title_vi', 'law', 'kinds', 'gates', 'failureCodes', 'enforcers'].includes(key)) bad.push(`${label} has unknown key ${key}`);
-    const expectedId = `R${String(index + 1).padStart(2, '0')}`;
-    if (!/^R\d{2}$/.test(String(r.id))) bad.push(`${at}.id must be R<two digits>`);
-    else if (r.id !== expectedId) bad.push(`${label} is out of order: ${at} must be ${expectedId}`);
+    for (const key of Object.keys(r)) if (!['id', 'code', 'law', 'kinds', 'gates', 'failureCodes', 'enforcers'].includes(key)) bad.push(`${label} has unknown key ${key}`);
+    // A retired rule leaves its id unused for good (never reused), so ids only have to increase.
+    if (!/^R\d{2,3}$/.test(String(r.id))) bad.push(`${at}.id must be R<two or three digits>`);
+    else if (index > 0 && typeof d.rules[index - 1]?.id === 'string' && Number(r.id.slice(1)) <= Number(d.rules[index - 1].id.slice(1))) bad.push(`${label} is out of order: ids must increase, and ${d.rules[index - 1].id} comes before it`);
     if (!FINDING_CODE.test(String(r.code))) bad.push(`${label}.code must be an UPPER_SNAKE finding code`);
-    for (const key of ['title_vi', 'law']) if (typeof r[key] !== 'string' || !r[key].trim()) bad.push(`${label}.${key} is missing`);
+    if (typeof r.law !== 'string' || !r.law.trim()) bad.push(`${label}.law is missing`);
     if (typeof r.law === 'string' && r.law.includes('\n')) bad.push(`${label}.law must be one line`);
     const enumList = (key, allowed) => {
       if (!Array.isArray(r[key]) || !r[key].length) { bad.push(`${label}.${key} must be a non-empty list`); return []; }
@@ -612,7 +660,7 @@ function ruleCatalogProblems(d) {
     const seen = new Set();
     r.enforcers.forEach((e, n) => {
       const eat = `${label}.enforcers[${n}]`;
-      if (!isMap(e)) { bad.push(`${eat} is not a map`); return; }
+      if (!isPlainObject(e)) { bad.push(`${eat} is not a map`); return; }
       for (const key of Object.keys(e)) if (!['kind', 'id', 'status', 'at'].includes(key)) bad.push(`${eat} has unknown key ${key}`);
       if (!ENFORCER_FAMILIES.includes(e.kind)) bad.push(`${eat}.kind must be one of ${ENFORCER_FAMILIES.join(', ')}`);
       if (!ENFORCER_ID.test(String(e.id))) bad.push(`${eat}.id must be kebab-case`);
@@ -626,7 +674,7 @@ function ruleCatalogProblems(d) {
       } else if (FILE_ENFORCERS.includes(e.kind) && e.status !== 'planned') bad.push(`${eat} exists, so it names the file (at) that emits its code`);
     });
     if (Array.isArray(r.gates)) {
-      const hasSonar = r.enforcers.some((e) => isMap(e) && e.kind === 'sonar');
+      const hasSonar = r.enforcers.some((e) => isPlainObject(e) && e.kind === 'sonar');
       if (r.gates.includes('sonar') !== hasSonar) bad.push(`${label}: the sonar gate and a sonar enforcer go together`);
     }
   });

package/runtime/scripts/lib/hfs-tree.mjs

@@ -0,0 +1,80 @@
+// hfs-tree.mjs - the facts about the work tree that `git ls-files` cannot show: directories with no file below them, sibling
+// directories one typo apart (a renamed structure whose old copy was never removed), and entries git neither tracks nor
+// ignores. hfs-check.mjs turns these facts into HFS_EMPTY_DIR, HFS_GHOST_TREE and HFS_UNTRACKED_ROOT_ENTRY findings (R03).
+// Read-only: it walks the file system and asks git, nothing else.
+import fs from 'node:fs';
+import path from 'node:path';
+import { gitOutput } from './git.mjs';
+import { posixPath } from './path-key.mjs';
+
+/** Directory names no tree check enters: git's own store and installed packages. */
+const NEVER_WALKED = new Set(['.git', 'node_modules']);
+/** Two sibling names this close (Levenshtein) are the same name misspelt. */
+export const GHOST_DISTANCE = 2;
+
+/** Levenshtein distance of two names. */
+export function editDistance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j += 1) row[j] = Math.min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    previous = row;
+  }
+  return previous[b.length];
+}
+
+/**
+ * The directory tree of `repoRoot` below any `ignored` slot: {name, rel, files, dirs: [node]}. A directory in an
+ * ignored slot is not entered and counts as holding a file (its content is build output the repository does not own).
+ * Links are not followed.
+ */
+export function readTree(repoRoot, { isIgnored }) {
+  const walk = (abs, rel) => {
+    const node = { name: path.basename(abs), rel, files: 0, dirs: [] };
+    let entries;
+    try { entries = fs.readdirSync(abs, { withFileTypes: true }); } catch { return node; }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (!entry.isDirectory()) { node.files += 1; continue; }
+      if (NEVER_WALKED.has(entry.name)) continue;
+      if (isIgnored(childRel)) { node.files += 1; continue; }
+      node.dirs.push(walk(path.join(abs, entry.name), childRel));
+    }
+    return node;
+  };
+  return walk(repoRoot, '');
+}
+
+const holdsNoFile = (node) => node.files === 0 && node.dirs.every(holdsNoFile);
+const countDirs = (node) => node.dirs.reduce((sum, child) => sum + 1 + countDirs(child), 0);
+
+/**
+ * The tree's own findings: `empty` are the topmost directories with no file anywhere below them (each with the number of
+ * directories it holds); `ghosts` are pairs of sibling directories within GHOST_DISTANCE edits where `ghost` has no file
+ * below it and `of` is its lookalike.
+ */
+export function treeFacts(tree) {
+  const empty = [];
+  const ghosts = [];
+  const visit = (node) => {
+    for (const child of node.dirs) {
+      if (holdsNoFile(child)) empty.push({ path: child.rel, below: countDirs(child) });
+      else visit(child);
+    }
+    for (const [i, a] of node.dirs.entries()) {
+      for (const b of node.dirs.slice(i + 1)) {
+        if (editDistance(a.name, b.name) > GHOST_DISTANCE) continue;
+        if (holdsNoFile(a)) ghosts.push({ path: a.rel, of: b.rel, distance: editDistance(a.name, b.name) });
+        if (holdsNoFile(b)) ghosts.push({ path: b.rel, of: a.rel, distance: editDistance(a.name, b.name) });
+      }
+    }
+  };
+  visit(tree);
+  return { empty, ghosts };
+}
+
+/** Entries git neither tracks nor ignores, as it prints them (a wholly untracked directory is one entry ending in '/'). */
+export function untrackedEntries(repoRoot) {
+  const out = gitOutput(['ls-files', '-z', '--others', '--exclude-standard', '--directory', '--no-empty-directory'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 });
+  return out.split('\0').filter(Boolean).map(posixPath);
+}

package/runtime/scripts/lib/hfs-view.mjs

@@ -0,0 +1,68 @@
+// hfs-view.mjs - the frozen view of one repository's HFS slots that the lint factories hand their rules
+// (`settings.starci.hfs`). Both @starci/eslint-canon-be and @starci/eslint-canon-fe ship a byte copy of this file in their
+// runtime/ bundle (packages/hfs/scripts/sync-runtime.mjs), so a path-scoped rule in either package asks the SAME resolver the
+// architecture machine and `hfs check` use, and never tests a path with a regular expression of its own.
+import path from 'node:path';
+import { allowsFile } from './hfs-allows.mjs';
+import { openHfs } from './hfs-slots.mjs';
+
+const posix = (p) => String(p).replace(/\\/g, '/');
+const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(text);
+
+/**
+ * The view rules read, over an opened resolver.
+ *
+ * @param {object} opened - The result of `openHfs` (manifest, repo and resolver methods).
+ * @param {string} repoRoot - The absolute repository root.
+ * @returns {object} The frozen view: profile, apps, connections, ruleParams, relative, classify, slotOf, tierOf, ownerOf, slot.
+ */
+export function hfsView(opened, repoRoot) {
+  const rel = (file) => {
+    const text = posix(file);
+    if (!isAbsoluteAny(text)) return text.replace(/^\.\//, '');
+    return posix(path.relative(repoRoot, file));
+  };
+  const slotCache = new Map();
+  const classify = (file) => {
+    const key = rel(file);
+    if (!slotCache.has(key)) slotCache.set(key, opened.classifyPath(key));
+    return slotCache.get(key);
+  };
+  return Object.freeze({
+    repoRoot,
+    profile: opened.repo.profile,
+    apps: opened.repo.apps,
+    connections: opened.repo.connections,
+    ruleParams: opened.ruleParams(),
+    /** The repository-relative, forward-slash form of a linted filename. */
+    relative: rel,
+    /** The classification of a file: `{ slot, tier, owner?, bindings? ... }` or a no-slot status. */
+    classify,
+    /** The slot id that owns a file, or null when no slot does. */
+    slotOf: (file) => classify(file).slot ?? null,
+    /** The tier of a file, or null. */
+    tierOf: (file) => opened.tierOf(rel(file)) ?? null,
+    /** The owner root of a file, or null. */
+    ownerOf: (file) => opened.ownerOf(rel(file))?.root ?? null,
+    /** What the slot that owns a file says about it: `{ slot, root, relative, allowed, entry?, forbiddenBy?, allows }`, or null when the slot names no `allows`. */
+    allows: (file) => allowsFile(opened, rel(file)),
+    /** A slot definition by id. */
+    slot: (id) => opened.slot(id),
+  });
+}
+
+/**
+ * The view of the repository on disk whose root is `repoRoot`, against the manifest under `runtimeRoot`.
+ *
+ * @param {{ runtimeRoot: string, repoRoot: string }} input - Where the manifest copy lives and the repository root.
+ * @returns {object} The frozen view.
+ */
+export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root: runtimeRoot, repoRoot }), repoRoot);
+
+/**
+ * The view of an in-memory declaration (rule tests): no file is read except the manifest.
+ *
+ * @param {{ runtimeRoot: string, declaration: object, repoRoot: string }} input - Manifest root, hfs.json object, linted root.
+ * @returns {object} The frozen view.
+ */
+export const declaredHfsView = ({ runtimeRoot, declaration, repoRoot }) => hfsView(openHfs({ root: runtimeRoot, declaration }), repoRoot);

package/runtime/scripts/lib/json.mjs

@@ -0,0 +1,22 @@
+// json.mjs — the ledger's forgiving JSON read. Every one of these rows may hold text a peer wrote or a
+// truncated payload, so a malformed column is the caller's fallback, never a throw. The parse of the
+// literal 'null' is kept as null (callers that want {} instead write `parseJsonOr`).
+import fs from 'node:fs';
+
+/** `text` as JSON, or `fallback` when it does not parse. */
+export const parseJson = (text, fallback = null) => {
+  try { return JSON.parse(text); } catch { return fallback; }
+};
+
+/** `text` as JSON, or `fallback` when it does not parse OR parses to null/undefined. Rows written
+ * as the literal 'null' read back as the fallback too, so a caller that wants an object gets one. */
+export const parseJsonOr = (text, fallback = {}) => parseJson(text) ?? fallback;
+
+/** A jobs/events row spread with `payload`: the row's payload_json parsed via parseJsonOr
+ * (`fallback` defaults to {}). Pass fallback null to keep a raw parseJson result, nulls included. */
+export const withPayload = (row, fallback = {}) => (row ? { ...row, payload: parseJsonOr(row.payload_json, fallback) } : row);
+
+/** `file` read and parsed as JSON, or `fallback` when the file is missing, unreadable or malformed. */
+export const readJsonFile = (file, fallback = null) => {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+};

package/runtime/scripts/lib/language.mjs

@@ -0,0 +1,107 @@
+// language.mjs - the one home of "is this text English?" for source, comments, tests and docs (HFS_LANGUAGE_NOT_ENGLISH,
+// BE_SOURCE_FORM, FE_SOURCE_FORM). Shared by the architecture machine (docs) and by both lint canons (each ships a byte
+// copy in its runtime/ bundle, kept by packages/hfs/scripts/sync-runtime.mjs).
+//
+// Detection is structural on characters, never a word list: the letters Vietnamese adds to the Latin alphabet (a-breve, a-circumflex,
+// d-stroke, e-circumflex, o-circumflex, o-horn, u-horn) and every vowel carrying a tone mark. Text is folded to NFC first, so a
+// decomposed spelling (base letter + combining mark) is caught exactly like the precomposed one, and a loanword such as
+// `naive`, `facade` or `Muller` (no tone mark, no Vietnamese letter) is never a hit.
+import path from 'node:path';
+
+/** One Vietnamese letter, precomposed (NFC): the Vietnamese-specific base letters, tone-marked vowels and the Latin Extended Additional block. */
+export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìíò-õùúýĂăĐđĨĩŨũƠơƯưẠ-ỿ]/;
+
+/** Whether `text` holds a Vietnamese letter, in NFC or NFD spelling. */
+export const hasSecondLanguage = (text) => typeof text === 'string' && SECOND_LANGUAGE_LETTER.test(text.normalize('NFC'));
+
+/** Every line of `text` with a Vietnamese letter: `[{ line, column }]`, both 1-based. */
+export function secondLanguageHits(text) {
+  const hits = [];
+  String(text).split(/\r?\n/).forEach((raw, index) => {
+    const match = SECOND_LANGUAGE_LETTER.exec(raw.normalize('NFC'));
+    if (match) hits.push({ line: index + 1, column: match.index + 1 });
+  });
+  return hits;
+}
+
+/**
+ * The Vietnamese fields of one failure-code entry: the operator text the owner mandated for the failure-code catalog
+ * (scripts/checks/failure-codes.mjs types the entry with exactly these). causes_vi is the list companion of the three scalar fields.
+ */
+export const FAILURE_CODE_VIETNAMESE_FIELDS = Object.freeze(['title_vi', 'meaning_vi', 'nextStep_vi', 'causes_vi']);
+
+/**
+ * The fields of a document that carry deliberate Vietnamese text, keyed by file: a declared field-level exception of that file's
+ * typed content, never a path pattern over content. `fields` are block keys (the key's own value and its list items are exempt);
+ * `flowFields` are keys inside an inline flow map (`{ vi: ..., en: ... }`), where only that key's value is exempt. A Vietnamese
+ * value under any other key of the same file is still a finding.
+ *  - modules/kernel/failure-codes.yaml: the operator text the owner mandated for the failure-code catalog.
+ *  - modules/ops/_labels.yaml: the op-label catalogue, one `{ vi, en }` pair per op (the `vi` field is the localized label).
+ *  - modules/goal/archetypes.yaml: the Vietnamese phrase lexicons matched against owner input (the signal phrase sets, and the
+ *    phrase lists of the archetype recognisers).
+ */
+export const DECLARED_VIETNAMESE_FIELDS = Object.freeze({
+  'modules/kernel/failure-codes.yaml': Object.freeze({ fields: FAILURE_CODE_VIETNAMESE_FIELDS }),
+  'modules/ops/_labels.yaml': Object.freeze({ flowFields: Object.freeze(['vi']) }),
+  'modules/goal/archetypes.yaml': Object.freeze({
+    fields: Object.freeze([
+      'buildIntent', 'canonIntent', 'e2eIntent', 'uatIntent', 'proofNegation', 'integrationIntent', 'integrationNegation', 'brandIntent',
+      'phrases', 'requires', 'excludes', 'backend', 'frontend', 'package',
+    ]),
+  }),
+});
+
+/**
+ * The slots whose files may carry another language, and why: a catalog is product copy in two languages, and an i18n
+ * fixture reproduces a real localized string a parser or formatter must accept. Placement is the whole marker - there is no
+ * comment pragma and no path pattern. The slots are declared in knowledge/hfs/slots.yaml.
+ */
+export const LOCALIZED_TEXT_SLOTS = Object.freeze([
+  'be.domain.messages', 'be.feature.messages', 'be.tests.fixtures.i18n',
+  'fe.modules.i18n', 'fe.package.i18n',
+]);
+
+/** Whether a document (Markdown or YAML) of `slot` is exempt: only catalogue and fixture DATA (YAML) is; Markdown is prose and never is. */
+export const isLocalizedDataFile = (rel, slot) => LOCALIZED_TEXT_SLOTS.includes(slot) && /\.ya?ml$/.test(rel);
+
+/**
+ * The key each line of a YAML text belongs to: a `key:` line owns itself, and every deeper-indented line after it (a list item,
+ * a folded block, a wrapped scalar) belongs to the same key. A line at or above the key's indent that is not a key belongs to none.
+ */
+export function yamlKeyOfEachLine(text) {
+  let key = null;
+  let keyIndent = -1;
+  return String(text).split(/\r?\n/).map((raw) => {
+    if (raw.trim() === '') return key;
+    const indent = raw.length - raw.trimStart().length;
+    const own = /^(\s*(?:-\s+)?)([A-Za-z_][\w-]*)\s*:(?:\s|$)/.exec(raw);
+    if (own) { key = own[2]; keyIndent = own[1].length; return key; }
+    // a list item may sit at the key's own indent (`key:` then `- item` at the same column)
+    if (indent > keyIndent || (indent === keyIndent && /^\s*-\s/.test(raw))) return key;
+    key = null;
+    keyIndent = -1;
+    return null;
+  });
+}
+
+/** The Vietnamese hits of a document, minus the declared field-level exceptions of `rel` (a repository-relative POSIX path). */
+export function documentLanguageHits(rel, text) {
+  const declared = DECLARED_VIETNAMESE_FIELDS[rel];
+  const hits = secondLanguageHits(text);
+  if (!declared) return hits;
+  const keys = yamlKeyOfEachLine(text);
+  const lines = String(text).split(/\r?\n/);
+  return hits.filter((hit) => {
+    if (declared.fields?.includes(keys[hit.line - 1])) return false;
+    if (!declared.flowFields) return true;
+    // an inline flow map: drop the declared fields' values and judge what is left of the line
+    const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(`\\b${field}\\s*:\\s*[^,}]*`, 'g'), ''), lines[hit.line - 1]);
+    return hasSecondLanguage(rest);
+  });
+}
+
+/** The file extensions of a prose document (Markdown and YAML). */
+export const DOCUMENT_EXTENSIONS = Object.freeze(['.md', '.yaml', '.yml']);
+
+/** Whether `rel` is a document a language check reads. */
+export const isDocument = (rel) => DOCUMENT_EXTENSIONS.includes(path.posix.extname(rel));

package/runtime/scripts/lib/path-key.mjs

@@ -7,6 +7,8 @@ const WIN = process.platform === 'win32';
 export const slash = (p) => String(p ?? '').replaceAll('\\', '/');
 /** A relative path in git's spelling: forward slashes, no leading './'. */
 export const posixPath = (p) => slash(p).replace(/^\.\//, '');
+/** Whether posix `file` is `prefix` itself or under it (`file === prefix || file` starts with `prefix/`). */
+export const sameOrUnder = (file, prefix) => file === prefix || file.startsWith(`${prefix}/`);
 /** `p` case-folded where the filesystem ignores case (Windows). */
 export const foldCase = (p) => (WIN ? p.toLowerCase() : p);
 /** Whether two spellings name the same path on this host's filesystem. */