@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/param-names.d.mts

@@ -0,0 +1,3 @@
+import type { Parsed } from './manifest-shape.mjs';
+/** True when `list` is a well-formed paramNames table. */
+export declare function paramNamesOk(list: Parsed): boolean;

package/runtime/scripts/hfs/param-names.mjs

@@ -1,18 +1,13 @@
-// param-names.mjs - the one shape of `ruleParams.be.paramNames` of knowledge/hfs/slots.yaml (R85 injected-param-name): a non-empty list of unique
-// entries `{type | typeSuffix, names, nameSuffix?}`. The loader of scripts/hfs/slots.mjs calls it; the schema (modules/schemas/hfs-slots.schema.yaml)
-// states the same shape.
 import { isPlainObject } from '../../engine/plain-object.mjs';
-
 const UPPER = /^[A-Z][A-Za-z0-9]*$/u;
 const LOWER = /^[a-z][A-Za-z0-9]*$/u;
-
 const entryOk = (e) => isPlainObject(e) && ((e.type === undefined) !== (e.typeSuffix === undefined)) && UPPER.test(String(e.type ?? e.typeSuffix))
-  && Array.isArray(e.names) && e.names.length > 0 && new Set(e.names).size === e.names.length && e.names.every((n) => LOWER.test(String(n)))
-  && (e.nameSuffix === undefined || UPPER.test(String(e.nameSuffix))) && Object.keys(e).every((k) => ['type', 'typeSuffix', 'names', 'nameSuffix'].includes(k));
-
+    && Array.isArray(e.names) && e.names.length > 0 && new Set(e.names).size === e.names.length && e.names.every((n) => LOWER.test(String(n)))
+    && (e.nameSuffix === undefined || UPPER.test(String(e.nameSuffix))) && Object.keys(e).every((k) => ['type', 'typeSuffix', 'names', 'nameSuffix'].includes(k));
 /** True when `list` is a well-formed paramNames table. */
 export function paramNamesOk(list) {
-  if (!Array.isArray(list) || list.length === 0 || !list.every(entryOk)) return false;
-  const keys = list.map((e) => (e.type !== undefined ? `type:${e.type}` : `typeSuffix:${e.typeSuffix}`));
-  return new Set(keys).size === keys.length;
+    if (!Array.isArray(list) || list.length === 0 || !list.every(entryOk))
+        return false;
+    const keys = list.map((e) => (e.type !== undefined ? `type:${e.type}` : `typeSuffix:${e.typeSuffix}`));
+    return new Set(keys).size === keys.length;
 }

package/runtime/scripts/hfs/path-findings.d.mts

@@ -0,0 +1,22 @@
+import type { Resolver } from './slots.mjs';
+/** A finding of the slot manifest over one path; the keys beyond the four every finding carries depend on its code. */
+export interface PathFinding {
+    code: string;
+    level: string;
+    path: string;
+    message: string;
+    origin?: string;
+    [detail: string]: unknown;
+}
+/** The lite Work boundary, read from app.starciwork's edition-specific admission list, including paths a narrower slot owns. */
+export declare function liteStarciworkFinding(file: string, resolver: Resolver, { dir }?: {
+    dir?: boolean;
+}): PathFinding | null;
+/** Local lite Work leftovers, including metadata ignored by an old full-edition .gitignore. */
+export declare function liteStarciworkTreeFindings(repoRoot: string, resolver: Resolver, tracked: string[]): PathFinding[];
+/** The findings of the slot manifest over `files` (repository-relative tracked paths) of a repository of `profile`. */
+export declare function pathFindings({ files, resolver, profile }: {
+    files: string[];
+    resolver: Resolver;
+    profile: string;
+}): PathFinding[];

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

@@ -10,7 +10,6 @@ import { isFeTestPath } from './rules/fe-no-tests.mjs';
 import { slotOwnsSecrets } from './rules/secrets.mjs';
 import { specPlacementFindings } from './rules/spec-placement.mjs';
 import { APP_SCOPE } from './slots.mjs';
-
 const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const SOURCE_ROOT = /^(?:src|apps)\//;
 const FREE_NAMES = new Set(['index.ts', 'main.ts']);
@@ -21,43 +20,49 @@ 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);
-  // A file slot declares its one file by its path (be.platform.database.entities: src/modules/platform/database/entities.ts).
-  if (slot?.path === c.path) return null;
-  if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].includes(base)) return null;
-  const admitted = allowsFile(resolver, file);
-  // Environment parsing is an app slot role, not a source suffix admitted outside that matching app file.
-  if (c.slot.startsWith('be.app.') && admitted?.allowed && admitted.entry === '<app>.env.ts') return null;
-  if (admitted?.allowed && admitted.entry?.includes('/') && path.posix.basename(admitted.entry) === base) return null;
-  // A plain entry names its file by a variable only (`<x>.ts`, or `compose/<area>.ts` of an app slot): a kebab name is its form.
-  if (admitted?.allowed && PLAIN_ENTRY.test(path.posix.basename(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 };
+    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);
+    // A file slot declares its one file by its path (be.platform.database.entities: src/modules/platform/database/entities.ts).
+    if (slot?.path === c.path)
+        return null;
+    if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].includes(base))
+        return null;
+    const admitted = allowsFile(resolver, file);
+    // Environment parsing is an app slot role, not a source suffix admitted outside that matching app file.
+    if (c.slot.startsWith('be.app.') && admitted?.allowed && admitted.entry === '<app>.env.ts')
+        return null;
+    if (admitted?.allowed && admitted.entry?.includes('/') && path.posix.basename(admitted.entry) === base)
+        return null;
+    // A plain entry names its file by a variable only (`<x>.ts`, or `compose/<area>.ts` of an app slot): a kebab name is its form.
+    if (admitted?.allowed && PLAIN_ENTRY.test(path.posix.basename(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;
+    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, the one file a file
  * slot names by its path (the lite entity registry src/modules/platform/database/entities.ts), a migration of be.persistence, the matching <app>.env.ts explicitly admitted by its app slot, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
@@ -65,83 +70,98 @@ function sourceFormFinding(file, { c, base, suffixes, bannedSuffixes }, boundSuf
  * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
  */
 function sourceFormFindings({ files, resolver }) {
-  const { suffixes, bannedSuffixes } = resolver.ruleParams();
-  // A suffix a slot names in its own file pattern (`*.builder.ts` of be.tests.fixtures.builders) is that slot's role: a file with it
-  // anywhere else is refused, so a builder cannot live beside a service or in the fixtures root.
-  const boundSuffixes = new Map();
-  for (const slot of resolver.slots()) {
-    const bound = /\*\.([a-z0-9-]+)\.ts$/.exec(slot.path ?? '')?.[1];
-    if (bound && suffixes.includes(bound)) boundSuffixes.set(bound, slot);
-  }
-  const findings = [];
-  for (const file of files) {
-    const context = sourceFormContext(file, resolver, suffixes, bannedSuffixes);
-    if (!context) continue;
-    const finding = sourceFormFinding(file, context, boundSuffixes);
-    if (finding) findings.push(finding);
-  }
-  return findings;
+    const { suffixes, bannedSuffixes } = resolver.ruleParams();
+    // A suffix a slot names in its own file pattern (`*.builder.ts` of be.tests.fixtures.builders) is that slot's role: a file with it
+    // anywhere else is refused, so a builder cannot live beside a service or in the fixtures root.
+    const boundSuffixes = new Map();
+    for (const slot of resolver.slots()) {
+        const bound = /\*\.([a-z0-9-]+)\.ts$/.exec(slot.path ?? '')?.[1];
+        if (bound && suffixes.includes(bound))
+            boundSuffixes.set(bound, slot);
+    }
+    const findings = [];
+    for (const file of files) {
+        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}` };
+    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 liteWork = liteStarciworkFinding(file, resolver);
-  if (liteWork) return liteWork;
-  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;
+    const liteWork = liteStarciworkFinding(file, resolver);
+    if (liteWork)
+        return liteWork;
+    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 lite Work boundary, read from app.starciwork's edition-specific admission list, including paths a narrower slot owns. */
 export function liteStarciworkFinding(file, resolver, { dir = false } = {}) {
-  if (resolver.repo?.edition !== 'lite' || !resolver.slot('app.starciwork')) return null;
-  const p = resolver.classifyPath(file).path;
-  if (!p.startsWith('.starciwork/')) return null;
-  const admitted = allowsFile(resolver, dir ? `${p}/.probe` : p);
-  if (admitted?.slot === 'app.starciwork' && admitted.allowed) return null;
-  return { code: 'HFS_STARCIWORK_LITE_FORBIDDEN', level: 'error', path: p, slot: 'app.starciwork', message: `${p}: lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore); remove this path or use the full edition` };
+    if (resolver.repo?.edition !== 'lite' || !resolver.slot('app.starciwork'))
+        return null;
+    const p = resolver.classifyPath(file).path;
+    if (!p.startsWith('.starciwork/'))
+        return null;
+    const admitted = allowsFile(resolver, dir ? `${p}/.probe` : p);
+    if (admitted?.slot === 'app.starciwork' && admitted.allowed)
+        return null;
+    return { code: 'HFS_STARCIWORK_LITE_FORBIDDEN', level: 'error', path: p, slot: 'app.starciwork', message: `${p}: lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore); remove this path or use the full edition` };
 }
-
 /** Local lite Work leftovers, including metadata ignored by an old full-edition .gitignore. */
 export function liteStarciworkTreeFindings(repoRoot, resolver, tracked) {
-  if (resolver.repo?.edition !== 'lite' || !resolver.slot('app.starciwork')) return [];
-  let entries = [];
-  try { entries = fs.readdirSync(path.join(repoRoot, '.starciwork'), { withFileTypes: true }); } catch { /* Work is optional. */ }
-  const trackedSet = new Set(tracked);
-  return entries.flatMap(entry => {
-    const file = `.starciwork/${entry.name}`;
-    if (trackedSet.has(file)) return [];
-    const finding = liteStarciworkFinding(file, resolver, { dir: entry.isDirectory() });
-    return finding ? [finding] : [];
-  });
+    if (resolver.repo?.edition !== 'lite' || !resolver.slot('app.starciwork'))
+        return [];
+    let entries = [];
+    try {
+        entries = fs.readdirSync(path.join(repoRoot, '.starciwork'), { withFileTypes: true });
+    }
+    catch { /* Work is optional. */ }
+    const trackedSet = new Set(tracked);
+    return entries.flatMap(entry => {
+        const file = `.starciwork/${entry.name}`;
+        if (trackedSet.has(file))
+            return [];
+        const finding = liteStarciworkFinding(file, resolver, { dir: entry.isDirectory() });
+        return finding ? [finding] : [];
+    });
 }
-
 /** 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 finding = pathStatusFinding(file, resolver);
-    if (finding) findings.push(finding);
-  }
-
-  if (profile === 'be') findings.push(...sourceFormFindings({ files, resolver }), ...specPlacementFindings({ files, resolver }));
-  // The app root (scripts/, CI, hooks) holds no test layer: a spec there is the same finding as a spec of an operational script.
-  else if (profile === APP_SCOPE) findings.push(...specPlacementFindings({ files, resolver }));
-  // The lint canon's project graph serves these findings on a TypeScript file; the origin keeps them apart from the machine's.
-  return findings.map((finding) => ({ ...finding, origin: 'repo' }));
+    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 finding = pathStatusFinding(file, resolver);
+        if (finding)
+            findings.push(finding);
+    }
+    if (profile === 'be')
+        findings.push(...sourceFormFindings({ files, resolver }), ...specPlacementFindings({ files, resolver }));
+    // The app root (scripts/, CI, hooks) holds no test layer: a spec there is the same finding as a spec of an operational script.
+    else if (profile === APP_SCOPE)
+        findings.push(...specPlacementFindings({ files, resolver }));
+    // The lint canon's project graph serves these findings on a TypeScript file; the origin keeps them apart from the machine's.
+    return findings.map((finding) => ({ ...finding, origin: 'repo' }));
 }

package/runtime/scripts/hfs/pin-findings.d.mts

@@ -0,0 +1,19 @@
+import type { CanonPins } from './canon-pins.mjs';
+/** One canon-pin drift finding. */
+export interface PinFinding {
+    code: 'HFS_CANON_PIN_DRIFT';
+    level: 'error';
+    path: string;
+    dependency: string;
+    section: string;
+    pinned: string;
+    declared: string;
+    message: string;
+}
+export declare function pinFindings({ repoRoot, files, profile, pins, only }: {
+    repoRoot: string;
+    files: string[];
+    profile: string;
+    pins: CanonPins;
+    only?: Set<string> | null;
+}): PinFinding[];

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

@@ -1,31 +1,36 @@
 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}` });
+    const findings = [];
+    let pkg; // reason: package.json parsed from disk
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, file), 'utf8'));
     }
-  }
-  return findings;
+    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;
+    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/refusal-codes.d.mts

@@ -0,0 +1 @@
+export declare const REFUSAL_CODES: readonly string[];

package/runtime/scripts/hfs/refusal-codes.mjs

@@ -1,6 +1,6 @@
 // Infrastructure refusals are shared with the dependency-free runtime copy generator.
 // They describe checks that could not run, rather than catalogued obligations.
 export const REFUSAL_CODES = Object.freeze([
-  'HFS_REPO_UNREADABLE',
-  'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID', 'HFS_FORMAT_TOOL_MISSING', 'HFS_EDITION_INVALID',
+    'HFS_REPO_UNREADABLE',
+    'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID', 'HFS_FORMAT_TOOL_MISSING', 'HFS_EDITION_INVALID',
 ]);

package/runtime/scripts/hfs/repo-identity.d.mts

@@ -0,0 +1,15 @@
+/** What git says about a folder. */
+export interface RepoIdentity {
+    inWorkTree: boolean;
+    repositoryRoot: boolean;
+    home: string | null;
+}
+/**
+ * The product repository name: the origin remote's repository name (one name for every clone and worktree, whatever
+ * folder holds it), else the main checkout's folder name (so a worktree and its main checkout agree), else package.json
+ * name outside Git, else the folder name. A folder inside a larger repository (a nested product, an example) is named by
+ * its own folder.
+ */
+export declare function repositoryName(root: string): string;
+/** The folder whose siblings are this repository's sibling repositories: the main checkout for a worktree, else root. */
+export declare function repositoryHome(root: string): string;

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

@@ -7,40 +7,48 @@ 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 = (call, root, args) => gitOutputOf(call(args, { cwd: root })).trim(); // gitOutputOf threw unless git exited 0, whose stdout is text
+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');
-
-// The identity of a folder that has its own .git entry holds while that entry is the same file system object (same inode, same modification time), so a
-// process asks Git once per such folder state instead of at every check. A folder with no .git entry of its own is asked every time.
 const known = new Map();
-const stateOf = (root) => { try { const stat = fs.statSync(path.join(root, '.git')); return `${real(root)}|${stat.ino}|${stat.mtimeMs}`; } catch { return null; } };
-
+const stateOf = (root) => { try {
+    const stat = fs.statSync(path.join(root, '.git'));
+    return `${real(root)}|${stat.ino}|${stat.mtimeMs}`;
+}
+catch {
+    return null;
+} };
 /** { repositoryRoot, inWorkTree, home } for `root`: home is the main checkout folder when root is a repository top level. */
 function identityOf(root) {
-  const state = stateOf(root);
-  if (state === null) return askGit(root);
-  if (!known.has(state)) known.set(state, askGit(root));
-  return known.get(state);
+    const state = stateOf(root);
+    if (state === null)
+        return askGit(root);
+    if (!known.has(state))
+        known.set(state, askGit(root));
+    return known.get(state);
 }
-
 function askGit(root) {
-  let inWorkTree = false, repositoryRoot = false, home = null;
-  try {
-    // Identity comes from Git only when root IS a repository (or worktree) top level, never a folder inside one.
-    // One git call answers both questions: the top level on the first line, the common git dir on the second.
-    const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir']).split(String.fromCodePoint(10)).map((line) => line.trim());
-    repositoryRoot = real(top) === real(root);
-    inWorkTree = true;
-    const common = path.resolve(root, commonDir);
-    if (repositoryRoot && path.basename(common) === '.git') home = path.dirname(common);
-  } catch { /* Not a Git work tree; the caller falls back to the folder and package name. */ }
-  return { inWorkTree, repositoryRoot, home };
+    let inWorkTree = false, repositoryRoot = false, home = null;
+    try {
+        // Identity comes from Git only when root IS a repository (or worktree) top level, never a folder inside one.
+        // One git call answers both questions: the top level on the first line, the common git dir on the second.
+        const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir']).split(String.fromCodePoint(10)).map((line) => line.trim());
+        repositoryRoot = real(top) === real(root);
+        inWorkTree = true;
+        const common = path.resolve(root, commonDir);
+        if (repositoryRoot && path.basename(common) === '.git')
+            home = path.dirname(common);
+    }
+    catch { /* Not a Git work tree; the caller falls back to the folder and package name. */ }
+    return { inWorkTree, repositoryRoot, home };
 }
-
 /**
  * The product repository name: the origin remote's repository name (one name for every clone and worktree, whatever
  * folder holds it), else the main checkout's folder name (so a worktree and its main checkout agree), else package.json
@@ -48,24 +56,29 @@ function askGit(root) {
  * its own folder.
  */
 export function repositoryName(root) {
-  const { inWorkTree, repositoryRoot, home } = identityOf(root);
-  if (repositoryRoot) {
+    const { inWorkTree, repositoryRoot, home } = identityOf(root);
+    if (repositoryRoot) {
+        try {
+            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. */ }
+    }
+    if (home)
+        return path.basename(home);
+    if (inWorkTree && !repositoryRoot)
+        return path.basename(root);
     try {
-      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. */ }
-  }
-  if (home) return path.basename(home);
-  if (inWorkTree && !repositoryRoot) return path.basename(root);
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
-    if (typeof pkg.name === 'string' && pkg.name) return pkg.name.replace(/^@[^/]+\//u, '');
-  } catch { /* No readable package.json. */ }
-  return path.basename(root);
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+        if (typeof pkg.name === 'string' && pkg.name)
+            return pkg.name.replace(/^@[^/]+\//u, '');
+    }
+    catch { /* No readable package.json. */ }
+    return path.basename(root);
 }
-
 /** The folder whose siblings are this repository's sibling repositories: the main checkout for a worktree, else root. */
 export function repositoryHome(root) {
-  return identityOf(root).home ?? path.resolve(root);
+    return identityOf(root).home ?? path.resolve(root);
 }

package/runtime/scripts/hfs/rule-catalog.d.mts

@@ -0,0 +1,77 @@
+import type { Parsed, SlotManifest } from './manifest-shape.mjs';
+/**
+ * The enforcer kinds that run only inside the StarCi runtime repository (`starci runtime check`, `starci work`): no published package carries
+ * them, so no package spec can hold them (owner ruling no-runtime-specs: the runtime has no specs of its own; the package clean-test and the
+ * scaffold e2e are its tests), and no example app is a product they judge. A rule is runtime-judged when every enforcer it has is of these kinds.
+ */
+export declare const RUNTIME_ONLY_ENFORCERS: readonly string[];
+/** One enforcer of a rule, as loadRuleCatalog returns it: the parsed row plus `planned`. */
+export interface CatalogEnforcer {
+    kind: string;
+    id: string;
+    status?: string;
+    at?: string;
+    editions?: string[];
+    editionWhy?: string;
+    planned: boolean;
+}
+/** One rule of knowledge/hfs/rules.yaml, as loadRuleCatalog returns it (frozen). */
+export interface CatalogRule {
+    id: string;
+    code: string;
+    law: string;
+    scope?: string;
+    kinds: string[];
+    gates: string[];
+    failureCodes: string[];
+    editions?: string[];
+    codeEditions?: Record<string, string[]>;
+    enforcers: CatalogEnforcer[];
+    cases?: Parsed;
+    docs?: Parsed;
+    exemplifiedBy?: Parsed;
+    proves?: Parsed;
+    witness?: Parsed;
+    editionWhy?: string;
+    amendedBy?: Parsed;
+    templateNa?: string;
+}
+/** Which catalog loadRuleCatalog reads: `text`, else `file`, else the runtime's own under `root`; `manifest` pins the major. */
+export interface RuleCatalogOptions {
+    root?: string | undefined;
+    file?: string | undefined;
+    text?: string | undefined;
+    manifest?: Pick<SlotManifest, 'major'> | undefined;
+}
+/** The frozen rule catalog loadRuleCatalog answers with. */
+export interface RuleCatalog {
+    version: string;
+    major: number;
+    minor: number;
+    patch: number;
+    gates: Record<string, string>;
+    enforcerKinds: Record<string, string>;
+    rules: readonly CatalogRule[];
+    rule: (id: string) => CatalogRule | null;
+    byCode: (code: string) => CatalogRule | null;
+    judgedIn: (code: string, edition?: string) => boolean;
+    enforcerJudgedIn: (kind: string, id: string, edition?: string) => boolean;
+    forGate: (gate: string) => CatalogRule[];
+    lintCode: (ruleId?: string | null) => string | undefined;
+    forEnforcer: (kind: string, id: string) => CatalogRule[];
+    planned: () => Array<{
+        rule: string;
+        kind: string;
+        id: string;
+    }>;
+    unbuilt: () => CatalogRule[];
+}
+/**
+ * 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 declare function loadRuleCatalog({ root, file, text, manifest }?: RuleCatalogOptions): RuleCatalog;
+/** The rules of this runtime's catalog, frozen, in id order. */
+export declare const rules: (options: Parsed) => readonly CatalogRule[];