@starci/eslint-canon-fe 8.0.7 → 8.0.8

package/runtime/scripts/{checks → hfs}/architecture/next-data.mjs

@@ -1,107 +1,14 @@
-import fs from 'node:fs';
 import path from 'node:path';
-import { createRequire } from 'node:module';
-import { canonical, exactKeys, isInside, slash } from './config.mjs';
+import { canonical, isInside } from './config.mjs';
+import { parseContract, installedSWR } from './next-data-contract.mjs';
 import { relativePath, sourceLocation, unwrapExpression } from './typescript.mjs';
 
 export const SWR_KEY_RULE_ID = 'FE_SWR_KEY_IDENTITY';
 export const SWR_MUTATION_RULE_ID = 'FE_SWR_MUTATION_RESOURCE_IDENTITY';
 export const SWR_DATA_RULE_IDS = [SWR_KEY_RULE_ID, SWR_MUTATION_RULE_ID];
 
-const CONTRACT_SCHEMA = 'starci/next-data-lifecycle@1';
-const SOURCE = /\.[cm]?[jt]sx?$/i;
-const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
-const BINDING = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/;
-const TOP_KEYS = new Set(['schema', 'swr', 'hooks']);
-const SWR_KEYS = new Set(['package', 'major']);
-const HOOK_KEYS = new Set(['id', 'path', 'export', 'kind', 'resultBinding', 'identities']);
-const IDENTITY_KEYS = new Set(['id', 'binding', 'gatesRequest', 'resource']);
 const SWR_SPECIFIERS = new Set(['swr', 'swr/immutable', 'swr/mutation']);
 
-function relativeSource(repository, value, label) {
-  repository = path.resolve(repository);
-  if (typeof value !== 'string' || !value.trim() || path.isAbsolute(value)) throw Error(`${label} must be a non-empty repository-relative source path.`);
-  const relative = slash(value.trim()).replace(/^\.\//, '');
-  if (relative.split('/').includes('..') || !SOURCE.test(relative) || /\.d\.[cm]?[jt]s$/i.test(relative)) {
-    throw Error(`${label} must be a production TypeScript or JavaScript source path.`);
-  }
-  const absolute = path.resolve(repository, ...relative.split('/'));
-  if (!isInside(repository, absolute)) throw Error(`${label} must stay inside the repository.`);
-  for (let current = absolute; current !== repository; current = path.dirname(current)) {
-    const stat = fs.lstatSync(current);
-    if (stat.isSymbolicLink()) throw Error(`${label} must not cross a symbolic-link or junction ancestor.`);
-  }
-  const stat = fs.lstatSync(absolute);
-  if (!stat.isFile() || !isInside(canonical(repository), canonical(absolute))) throw Error(`${label} must be a regular source file inside the repository.`);
-  return relative;
-}
-
-function parseContract(config) {
-  // The contract is declared in the app's one package.json (the app root; config.root is the fe side folder).
-  const manifest = JSON.parse(fs.readFileSync(path.join(config.packageRoot ?? config.root, 'package.json'), 'utf8'));
-  const next = manifest?.starci?.codePatterns?.next;
-  const value = next?.dataLifecycle;
-  if (value === undefined) return null;
-  if (next.schema !== 'starci/next-code-pattern-contract@1') throw Error('package.json#starci.codePatterns.next must use starci/next-code-pattern-contract@1.');
-  exactKeys(value, TOP_KEYS, 'package.json#starci.codePatterns.next.dataLifecycle');
-  if (value.schema !== CONTRACT_SCHEMA) throw Error(`dataLifecycle.schema must be ${CONTRACT_SCHEMA}.`);
-  exactKeys(value.swr, SWR_KEYS, 'dataLifecycle.swr');
-  if (value.swr.package !== 'swr' || !Number.isInteger(value.swr.major) || value.swr.major < 1) {
-    throw Error('dataLifecycle.swr must bind package swr and one positive integer major version.');
-  }
-  if (!Array.isArray(value.hooks) || value.hooks.length === 0) throw Error('dataLifecycle.hooks must contain at least one declared lifecycle call.');
-  const ids = new Set();
-  const hooks = value.hooks.map((hook, index) => {
-    const label = `dataLifecycle.hooks[${index}]`;
-    exactKeys(hook, HOOK_KEYS, label);
-    if (typeof hook.id !== 'string' || !hook.id.trim() || ids.has(hook.id.trim())) throw Error(`${label}.id must be unique and non-empty.`);
-    ids.add(hook.id.trim());
-    const source = relativeSource(config.root, hook.path, `${label}.path`);
-    if (typeof hook.export !== 'string' || !/^use[A-Z0-9_$][\w$]*$/.test(hook.export)) throw Error(`${label}.export must name one exported use* hook.`);
-    if (!['query', 'mutation'].includes(hook.kind)) throw Error(`${label}.kind must be query or mutation.`);
-    if (hook.resultBinding !== undefined && (typeof hook.resultBinding !== 'string' || !IDENTIFIER.test(hook.resultBinding))) {
-      throw Error(`${label}.resultBinding must be one local identifier.`);
-    }
-    if (!Array.isArray(hook.identities)) throw Error(`${label}.identities must be an array.`);
-    const identityIds = new Set(), bindings = new Set();
-    const identities = hook.identities.map((identity, identityIndex) => {
-      const identityLabel = `${label}.identities[${identityIndex}]`;
-      exactKeys(identity, IDENTITY_KEYS, identityLabel);
-      if (typeof identity.id !== 'string' || !identity.id.trim() || identityIds.has(identity.id.trim())) throw Error(`${identityLabel}.id must be unique and non-empty.`);
-      if (typeof identity.binding !== 'string' || !BINDING.test(identity.binding) || bindings.has(identity.binding)) throw Error(`${identityLabel}.binding must be a unique identifier or property path.`);
-      if (typeof identity.gatesRequest !== 'boolean' || typeof identity.resource !== 'boolean') throw Error(`${identityLabel} must explicitly declare gatesRequest and resource booleans.`);
-      identityIds.add(identity.id.trim());
-      bindings.add(identity.binding);
-      return { id: identity.id.trim(), binding: identity.binding, gatesRequest: identity.gatesRequest, resource: identity.resource };
-    });
-    if (hook.kind === 'mutation' && !identities.some(identity => identity.resource)) throw Error(`${label} mutation must declare at least one resource identity.`);
-    return { id: hook.id.trim(), path: source, export: hook.export, kind: hook.kind,
-      ...(hook.resultBinding === undefined ? {} : { resultBinding: hook.resultBinding }), identities };
-  });
-  return { schema: value.schema, swr: { package: 'swr', major: value.swr.major }, hooks };
-}
-
-function installedSWR(repository) {
-  const require = createRequire(path.join(repository, 'package.json'));
-  let manifest;
-  try { manifest = require.resolve('swr/package.json'); } catch {
-    let entry;
-    try { entry = require.resolve('swr'); } catch { throw Error('Installed swr package is unavailable.'); }
-    let current = path.dirname(entry);
-    while (isInside(repository, current) && current !== repository) {
-      const candidate = path.join(current, 'package.json');
-      if (fs.existsSync(candidate)) { manifest = candidate; break; }
-      current = path.dirname(current);
-    }
-  }
-  if (!manifest) throw Error('Installed swr package.json is unavailable.');
-  const actualManifest = canonical(manifest);
-  const parsed = JSON.parse(fs.readFileSync(actualManifest, 'utf8'));
-  const major = Number.parseInt(String(parsed.version ?? '').split('.')[0], 10);
-  if (parsed.name !== 'swr' || !Number.isInteger(major)) throw Error('Installed swr package identity or version is invalid.');
-  return { name: parsed.name, version: parsed.version, major, root: canonical(path.dirname(actualManifest)) };
-}
-
 function normalizedSymbol(ts, checker, value) {
   let symbol = value ?? null;
   const seen = new Set();
@@ -543,22 +450,29 @@ function nullish(ts, checker, expression) {
   return !symbol || (symbol.getDeclarations?.() ?? []).every(declaration => declaration.getSourceFile().isDeclarationFile);
 }
 
-function trueMeansAvailable(ts, checker, condition, identity) {
+/** True when taking `branch` of `condition` proves the declared identity is available. */
+function branchMeansAvailable(ts, checker, condition, identity, branch) {
   condition = unwrapExpression(ts, condition);
   if (expressionReferences(ts, checker, condition, identity) && (ts.isIdentifier(condition)
-    || ts.isPropertyAccessExpression(condition) || ts.isElementAccessExpression(condition))) return true;
+    || ts.isPropertyAccessExpression(condition) || ts.isElementAccessExpression(condition))) return branch;
   if (ts.isPrefixUnaryExpression(condition) && condition.operator === ts.SyntaxKind.ExclamationToken) {
-    const nested = trueMeansAvailable(ts, checker, condition.operand, identity);
-    return nested === null ? null : !nested;
+    return branchMeansAvailable(ts, checker, condition.operand, identity, !branch);
   }
   if (ts.isBinaryExpression(condition)) {
+    const operator = condition.operatorToken.kind;
+    if (operator === ts.SyntaxKind.AmpersandAmpersandToken || operator === ts.SyntaxKind.BarBarToken) {
+      // `a && b` is true only when both sides are true; `a || b` is false only when both sides are false.
+      const decisive = operator === ts.SyntaxKind.AmpersandAmpersandToken ? branch : !branch;
+      return decisive && [condition.left, condition.right]
+        .some(side => branchMeansAvailable(ts, checker, side, identity, branch));
+    }
     const leftIdentity = expressionReferences(ts, checker, condition.left, identity) && nullish(ts, checker, condition.right);
     const rightIdentity = expressionReferences(ts, checker, condition.right, identity) && nullish(ts, checker, condition.left);
-    if (!leftIdentity && !rightIdentity) return null;
-    if ([ts.SyntaxKind.ExclamationEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken].includes(condition.operatorToken.kind)) return true;
-    if ([ts.SyntaxKind.EqualsEqualsToken, ts.SyntaxKind.EqualsEqualsEqualsToken].includes(condition.operatorToken.kind)) return false;
+    if (!leftIdentity && !rightIdentity) return false;
+    if ([ts.SyntaxKind.ExclamationEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken].includes(operator)) return branch;
+    if ([ts.SyntaxKind.EqualsEqualsToken, ts.SyntaxKind.EqualsEqualsEqualsToken].includes(operator)) return !branch;
   }
-  return null;
+  return false;
 }
 
 function violation(config, call, ruleId, message, extra = {}) {
@@ -687,8 +601,7 @@ function inspectKey(config, context, entry, call, identities, violations, reason
     }
     if (identity.gatesRequest) {
       const gated = active.every(leaf => leaf.decisions.some(decision => {
-        const available = trueMeansAvailable(context.ts, call.checker, decision.condition, identity);
-        return available !== null && decision.branch === available;
+        return branchMeansAvailable(context.ts, call.checker, decision.condition, identity, decision.branch);
       }));
       if (!gated) violations.push(violation(config, call, SWR_KEY_RULE_ID,
         `${entry.id} must produce an explicit null key when ${identity.id} (${identity.binding}) is unavailable.`,

package/runtime/scripts/{checks → hfs}/architecture/required-files.mjs

@@ -5,7 +5,7 @@ import { gitOutput } from '../../api/git/lib.mjs';
 /**
  * HFS check 5: the files and directories the slot manifest requires (knowledge/hfs/slots.yaml `requires`,
  * `requiredInstances`, `minInstances`, required app kinds) must exist in the repository tree. Everything is read through the
- * resolver of scripts/lib/hfs-slots.mjs; nothing here names a path.
+ * resolver of scripts/hfs/slots.mjs; nothing here names a path.
  *
  *   BE_REQUIRED_MODULE_MISSING   a backend app, feature, domain, integrations or platform instance lacks a required file or
  *                                directory, or a required platform instance (config, logging, errors, primitives) is absent

package/runtime/scripts/{checks → hfs}/architecture/surface.mjs

@@ -60,7 +60,7 @@ export const LINT_ENFORCERS = Object.freeze([
   enforcer('component-purity', FE, ['FE_COMPONENT_WORLD_OWNERSHIP', 'FE_WORLD_OWNER_RENDER_BOUNDARY', 'FE_CONNECTED_BLOCK_RENDER_PAIR', 'FE_PURE_REACHES_DATA', 'FE_PURE_WORLD_HOOK', 'FE_PURE_WORLD_IMPORT'], 'A pure component reaches no data or world state; its connected entry owns them.'),
   enforcer('grammar-entry', FE, ['ARCH_GRAMMAR_CONTRACT_INVALID', 'ARCH_GRAMMAR_EXPORT_BYPASS'], 'Vendor grammar is reached only through its owner entry.'),
   enforcer('i18n-keys', FE, ['FE_I18N_KEYS'], 'Translation keys read by source and keys held by catalogs agree both ways.'),
-  // The per-path judgements of the slot manifest (scripts/lib/hfs-path-findings.mjs), on a tracked TypeScript file.
+  // The per-path judgements of the slot manifest (scripts/hfs/path-findings.mjs), on a tracked TypeScript file.
   enforcer('slot-undeclared', BOTH, ['HFS_SLOT_UNDECLARED', 'HFS_SLOT_AMBIGUOUS', 'HFS_SLOT_NOT_ENABLED'], 'A TypeScript file is owned by exactly one slot of the repository.', { origin: 'repo' }),
   enforcer('source-suffix', BE, ['BE_SOURCE_FORM'], 'A source file name is index.ts, main.ts, a migration or <kebab-name>.<suffix>.ts with a suffix of the closed list.', { origin: 'repo' }),
   enforcer('spec-placement', BE, ['BE_SPEC_PLACEMENT'], 'A spec file lives in one of the four test layers and nowhere else.', { origin: 'repo' }),

package/runtime/scripts/{checks → hfs}/architecture/test-world-files.mjs

@@ -1,6 +1,6 @@
 import { treeOf } from './required-files.mjs';
-import { allowsFile } from '../../lib/hfs-allows.mjs';
-import { locateDeclaration } from '../../lib/hfs-slots.mjs';
+import { allowsFile } from '../allows.mjs';
+import { locateDeclaration } from '../slots.mjs';
 import { DEFAULT_ENVIRONMENT, STACKS_DIRECTORY, STATEFUL_KINDS, namesOfService, readStack } from '../../lib/stack-services.mjs';
 
 /**

package/runtime/scripts/{checks → hfs}/architecture/typescript.mjs

@@ -5,7 +5,7 @@ import { canonical, isInside, slash } from './config.mjs';
 import { sameOrUnder } from '../../lib/path-key.mjs';
 import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule, sharedInProgramRun, typeScriptProjectReferencePath } from '../typescript-programs.mjs';
 import { readJsonFile } from '../../lib/json.mjs';
-import { locateDeclaration } from '../../lib/hfs-slots.mjs';
+import { locateDeclaration } from '../slots.mjs';
 
 const CODE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
 const TEST_FILE = /(?:^|[.-])(?:spec|test)\.[cm]?[jt]sx?$/i;

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -0,0 +1,170 @@
+// manifest-shape.mjs - the shape rules of an HFS slot manifest that both manifest kinds share, and the whole shape of a
+// manifest of kind runtime (knowledge/hfs/runtime-slots.yaml): the slot fields, the tier map, ruleParams.runtime and the
+// `pending` allowlist. scripts/hfs/slots.mjs (loadSlotManifest) is the only reader; it adds the app kind's own rules
+// (sides, app kinds) and refuses a manifest whole on any problem (HFS_MANIFEST_INVALID). Pure: every function takes a
+// parsed manifest or slot and returns a list of problems in the words of modules/schemas/hfs-slots.schema.yaml.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+
+export const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+export const NAME = /^[a-z][a-z0-9-]*$/;
+export const ENV_PREFIX = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/;
+export const SLOT_ID = /^(app|repo|be|fe)\.[a-z0-9-]+(\.[a-z0-9-]+)*$/;
+export const RUNTIME_SLOT_ID = /^runtime\.[a-z0-9-]+(\.[a-z0-9-]+)*$/;
+export const PRESENCE = ['required', 'optional', 'opt-in', 'forbidden'];
+export const TRACKED = ['tracked', 'ignored', 'external'];
+/** A runtime manifest adds `generated`: tracked, written only by the slot's generatedBy, judged by drift (RT_GENERATED_DRIFT). */
+export const RUNTIME_TRACKED = [...TRACKED, 'generated'];
+export const TESTS = ['unit-beside', 'e2e', 'none'];
+export const APP_KIND = 'app';
+/** The kind of a manifest and of a declaration that describes the StarCi runtime repository; also its one profile. */
+export const RUNTIME_KIND = 'runtime';
+export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
+/** The kind of a parsed manifest: `kind`, or app when absent (knowledge/hfs/slots.yaml carries none). */
+export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
+export const strList = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0);
+
+const APP_SLOT_KEYS = ['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'];
+/** A runtime slot has no app kind, side composition, layer or managed template; it may name the generator of a generated copy. */
+const RUNTIME_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'minInstances', 'requires', 'allows', 'forbids', 'budget', 'rules', 'goesTo', 'why', 'since', 'retiredIn', 'successor', 'generatedBy'];
+
+/** Shape problems of one slot of a manifest of `kind` (app or runtime). */
+export function slotProblems(slot, index, kind, { appScope = 'app', scopes = [] } = {}) {
+  const bad = [];
+  const runtime = kind === RUNTIME_KIND;
+  const slotKeys = new Set(runtime ? RUNTIME_SLOT_KEYS : APP_SLOT_KEYS);
+  const tracked = runtime ? RUNTIME_TRACKED : TRACKED;
+  const at = isPlainObject(slot) && typeof slot.id === 'string' ? `slot ${slot.id}` : `slots[${index}]`;
+  if (!isPlainObject(slot)) return [`${at} is not a map`];
+  for (const key of Object.keys(slot)) if (!slotKeys.has(key)) bad.push(`${at}: unknown field ${key}`);
+  if (runtime) {
+    if (!RUNTIME_SLOT_ID.test(String(slot.id))) bad.push(`${at}: id must look like runtime.<name>`);
+    if (JSON.stringify(slot.profiles) !== JSON.stringify([RUNTIME_KIND])) bad.push(`${at}: profiles must be [runtime]`);
+    if (slot.tracked === 'generated' && (typeof slot.generatedBy !== 'string' || !slot.generatedBy || slot.generatedBy.startsWith('/') || slot.generatedBy.includes('..'))) bad.push(`${at}: a generated slot names its generator (generatedBy, a repository-relative path)`);
+    if (slot.generatedBy !== undefined && slot.tracked !== 'generated') bad.push(`${at}: generatedBy belongs to a generated slot`);
+  } else {
+    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) => scopes.includes(p)) || new Set(slot.profiles).size !== slot.profiles.length || (slot.profiles.includes(appScope) && slot.profiles.length !== 1)) bad.push(`${at}: profiles must be [app] or a unique non-empty subset of be, fe`);
+    else if ((slot.profiles[0] === appScope) !== String(slot.id).startsWith(`${appScope}.`)) bad.push(`${at}: an app-root slot has profiles [app] and an id app.<name>, and only it`);
+  }
+  if (typeof slot.path !== 'string' || !slot.path) bad.push(`${at}: path is required`);
+  if (!PRESENCE.includes(slot.presence)) bad.push(`${at}: presence must be one of ${PRESENCE.join(', ')}`);
+  if (!tracked.includes(slot.tracked)) bad.push(`${at}: tracked must be one of ${tracked.join(', ')}`);
+  if (!NAME.test(String(slot.tier))) bad.push(`${at}: tier must be a tier name, none or inherit`);
+  if (!TESTS.includes(slot.tests)) bad.push(`${at}: tests must be one of ${TESTS.join(', ')}`);
+  if (slot.owner !== undefined && typeof slot.owner !== 'boolean') bad.push(`${at}: owner must be a boolean`);
+  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 && !(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`);
+  if (slot.retiredIn !== undefined && !(Number.isInteger(slot.retiredIn) && slot.retiredIn >= 2)) bad.push(`${at}: retiredIn must be a major`);
+  if (slot.retiredIn !== undefined && typeof slot.successor !== 'string') bad.push(`${at}: a retired slot names its successor`);
+  if (slot.tracked === 'external' && (typeof slot.goesTo !== 'string' || slot.presence !== 'forbidden')) bad.push(`${at}: an external slot is forbidden and says where it goes (goesTo)`);
+  if (slot.presence === 'forbidden' && slot.tracked !== 'external') bad.push(`${at}: a forbidden slot is external`);
+  return bad;
+}
+
+/** The owners of an external call in a runtime manifest: an api system folder (`api/<system>`, `api/*` any system) or the DB tier. */
+const INFRA_OWNER = /^(?:api\/(?:\*|[a-z][a-z0-9-]*)|engine\/db)$/;
+const RUNTIME_PARAM_KEYS = ['fileLines', 'sourceRoots', 'infraOwners', 'baseWriteMembers', 'baseEnvSeams', 'apiContracts', 'sourceName', 'oneOffNames', 'sharedBasenames', 'generated', 'pinned', 'selfChecks'];
+const PENDING_KEYS = ['path', 'rule', 'lane', 'since', 'reason'];
+/** The chunk of the runtime migration that deletes a pending entry (C1..C8, a split chunk C2a/C2b). */
+const PENDING_LANE = /^C[1-8][ab]?$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const relPath = (v) => typeof v === 'string' && v.length > 0 && !v.startsWith('/') && !v.includes('..') && !v.includes('\\');
+
+/** Shape problems of a parsed manifest of kind runtime (knowledge/hfs/runtime-slots.yaml), in the words of modules/schemas/hfs-slots.schema.yaml. */
+export function runtimeShapeProblems(m) {
+  const bad = [];
+  const allowed = new Set(['schema', 'kind', 'version', 'versioning', 'presenceValues', 'trackedValues', 'testValues', 'profiles', 'tiers', 'ruleParams', 'crossOwner', 'crossSystem', 'slots', 'pending', 'consumers']);
+  for (const key of Object.keys(m)) if (!allowed.has(key)) bad.push(`unknown top-level key ${key}`);
+  if (!/^starci\/runtime-slots@\d+$/.test(String(m.schema))) bad.push('schema must be starci/runtime-slots@<major>');
+  if (!SEMVER.test(String(m.version))) bad.push('version must be MAJOR.MINOR.PATCH');
+  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(RUNTIME_TRACKED)) bad.push(`trackedValues must be ${RUNTIME_TRACKED.join(', ')}`);
+  if (JSON.stringify(m.testValues) !== JSON.stringify(TESTS)) bad.push(`testValues must be ${TESTS.join(', ')}`);
+  if (JSON.stringify(m.profiles) !== JSON.stringify([RUNTIME_KIND])) bad.push('profiles must be [runtime]');
+  for (const key of ['crossOwner', 'crossSystem']) if (m[key] !== undefined && typeof m[key] !== 'string') bad.push(`${key} must be text`);
+  if (!isPlainObject(m.tiers) || Object.keys(m.tiers).join() !== RUNTIME_KIND) bad.push('tiers must be a map with exactly runtime');
+  else bad.push(...tierMapProblems(RUNTIME_KIND, m.tiers.runtime));
+  const rp = m.ruleParams;
+  if (!isPlainObject(rp) || Object.keys(rp).join() !== RUNTIME_KIND || !isPlainObject(rp.runtime)) bad.push('ruleParams must be a map with exactly runtime');
+  else bad.push(...runtimeParamProblems(rp.runtime));
+  if (!Array.isArray(m.slots) || !m.slots.length) bad.push('slots must be a non-empty list');
+  else m.slots.forEach((slot, index) => bad.push(...slotProblems(slot, index, RUNTIME_KIND)));
+  if (m.pending !== undefined) {
+    if (!Array.isArray(m.pending)) bad.push('pending must be a list');
+    else m.pending.forEach((entry, index) => {
+      const at = `pending[${index}]`;
+      if (!isPlainObject(entry)) { bad.push(`${at} is not a map`); return; }
+      for (const key of Object.keys(entry)) if (!PENDING_KEYS.includes(key)) bad.push(`${at}: unknown field ${key}`);
+      if (!relPath(entry.path)) bad.push(`${at}: path must be a repository-relative glob`);
+      if (!/^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/.test(String(entry.rule))) bad.push(`${at}: rule must be a finding code`);
+      if (!PENDING_LANE.test(String(entry.lane))) bad.push(`${at}: lane must be the chunk that removes it (C1..C8, C2a, C2b)`);
+      if (!DATE.test(String(entry.since))) bad.push(`${at}: since must be a date YYYY-MM-DD`);
+      if (typeof entry.reason !== 'string' || !entry.reason.trim()) bad.push(`${at}: reason is required`);
+    });
+  }
+  if (m.consumers !== undefined && !strList(m.consumers)) bad.push('consumers must be a list of paths');
+  return bad;
+}
+
+/** Shape problems of ruleParams.runtime. */
+function runtimeParamProblems(rp) {
+  const bad = [];
+  for (const key of Object.keys(rp)) if (!RUNTIME_PARAM_KEYS.includes(key)) bad.push(`ruleParams.runtime.${key} is not a runtime parameter`);
+  for (const key of RUNTIME_PARAM_KEYS) if (!(key in rp)) bad.push(`ruleParams.runtime.${key} is missing`);
+  const fl = rp.fileLines;
+  if (!(isPlainObject(fl) && Number.isInteger(fl.soft) && fl.soft >= 1 && typeof fl.hardGrowth === 'boolean' && Object.keys(fl).length === 2)) bad.push('ruleParams.runtime.fileLines must be {soft, hardGrowth}');
+  const owners = rp.infraOwners;
+  const ownerMap = (v) => isPlainObject(v) && Object.entries(v).every(([key, list]) => key && Array.isArray(list) && list.every((o) => INFRA_OWNER.test(String(o))) && new Set(list).size === list.length);
+  if (!isPlainObject(owners) || Object.keys(owners).sort().join() !== 'globals,modules,programs' || !['globals', 'modules', 'programs'].every((k) => ownerMap(owners[k]))) bad.push('ruleParams.runtime.infraOwners must be {modules, globals, programs}, each mapping a name to unique owners api/<system>, api/* or engine/db ([] means nowhere)');
+  for (const key of ['sourceRoots', 'baseWriteMembers', 'oneOffNames', 'sharedBasenames']) if (!(strList(rp[key]) && rp[key].length && new Set(rp[key]).size === rp[key].length)) bad.push(`ruleParams.runtime.${key} must be a non-empty list of unique strings`);
+  if (!(Array.isArray(rp.baseEnvSeams) && rp.baseEnvSeams.every(relPath))) bad.push('ruleParams.runtime.baseEnvSeams must be a list of repository-relative paths');
+  if (!(isPlainObject(rp.apiContracts) && Object.entries(rp.apiContracts).every(([system, file]) => NAME.test(system) && relPath(file)))) bad.push('ruleParams.runtime.apiContracts must map an api system to its calls contract path');
+  let sourceNameOk = typeof rp.sourceName === 'string';
+  try { if (sourceNameOk) new RegExp(rp.sourceName); } catch { sourceNameOk = false; }
+  if (!sourceNameOk) bad.push('ruleParams.runtime.sourceName must be a regular expression');
+  if (!(Array.isArray(rp.generated) && rp.generated.length && rp.generated.every((g) => isPlainObject(g) && relPath(g.root) && relPath(g.generatedBy) && Object.keys(g).length === 2))) bad.push('ruleParams.runtime.generated must be a non-empty list of {root, generatedBy}');
+  if (!(Array.isArray(rp.pinned) && rp.pinned.length && rp.pinned.every((p) => isPlainObject(p) && relPath(p.path) && typeof p.why === 'string' && p.why && Object.keys(p).length === 2))) bad.push('ruleParams.runtime.pinned must be a non-empty list of {path, why}');
+  if (!(Array.isArray(rp.selfChecks) && rp.selfChecks.length && rp.selfChecks.every((c) => isPlainObject(c) && NAME.test(String(c.id)) && relPath(c.run) && (c.args === undefined || strList(c.args)) && Object.keys(c).every((k) => ['id', 'run', 'args'].includes(k))))) bad.push('ruleParams.runtime.selfChecks must be a non-empty list of {id, run, args?}');
+  return bad;
+}
+
+/** Shape problems of the tier map of one profile. */
+export function tierMapProblems(profile, tiers) {
+  const bad = [];
+  if (!isPlainObject(tiers) || !Object.keys(tiers).length) return [`tiers.${profile} must be a non-empty map`];
+  for (const [tier, def] of Object.entries(tiers)) {
+    if (!NAME.test(tier)) bad.push(`tiers.${profile}.${tier} is not a tier name`);
+    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`);
+  }
+  return bad;
+}
+
+/** The semantic rules of a runtime manifest beyond the slot rules both kinds share: tier names, the schema major, unique pending entries. */
+export function runtimeSemanticProblems(m) {
+  const bad = [];
+  const tiers = m.tiers.runtime;
+  for (const [tier, def] of Object.entries(tiers)) {
+    for (const target of def.mayImport) if (!(target in tiers)) bad.push(`tiers.runtime.${tier}.mayImport names ${target}, which is not a runtime tier`);
+  }
+  const seen = new Set();
+  for (const entry of m.pending ?? []) {
+    const key = `${entry.path}\0${entry.rule}`;
+    if (seen.has(key)) bad.push(`pending names ${entry.path} for ${entry.rule} twice`);
+    seen.add(key);
+  }
+  const major = Number(m.version.split('.')[0]);
+  if (String(m.schema) !== `starci/runtime-slots@${major}`) bad.push(`schema ${m.schema} does not carry the major of version ${m.version}`);
+  return bad;
+}

package/runtime/scripts/{lib/hfs-path-findings.mjs → hfs/path-findings.mjs}

@@ -1,14 +1,14 @@
 // hfs-path-findings.mjs - the per-path judgements of the slot manifest: what a tracked path is. One function, two surfaces: `hfs check`
 // (checkRepo) runs it over the tracked tree and keeps the findings that have no TypeScript file to sit on; the lint canon's project graph
-// (scripts/lib/project-graph.mjs) runs it over the same tree and serves the findings on a TypeScript file as ESLint reports.
+// (scripts/hfs/project-graph.mjs) runs it over the same tree and serves the findings on a TypeScript file as ESLint reports.
 //   HFS_SLOT_UNDECLARED / HFS_SLOT_AMBIGUOUS / HFS_SLOT_NOT_ENABLED / HFS_FORBIDDEN_PRESENT / HFS_TOOL_CONFIG_LOCAL / HFS_TRACKED_MUST_BE_IGNORED (R01, R16)
 //   BE_SOURCE_FORM (R89, the file name), BE_SPEC_PLACEMENT (R102)
 import path from 'node:path';
-import { allowsFile } from './hfs-allows.mjs';
-import { isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
-import { slotOwnsSecrets } from './hfs-rules/secrets.mjs';
-import { specPlacementFindings } from './hfs-rules/spec-placement.mjs';
-import { APP_SCOPE } from './hfs-slots.mjs';
+import { allowsFile } from './allows.mjs';
+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)\//;

package/runtime/scripts/{lib → hfs}/project-rule.mjs

@@ -1,4 +1,4 @@
-// project-rule.mjs - the factory of the lint rules that read the project graph (scripts/lib/project-graph.mjs).
+// project-rule.mjs - the factory of the lint rules that read the project graph (scripts/hfs/project-graph.mjs).
 //
 // A project rule judges nothing itself: the graph (the architecture machine's module graph and slot manifest, built once per
 // process) holds the findings of its codes, and the rule reports those of the file it is visiting, on the line the machine named.
@@ -6,8 +6,8 @@
 // Both lint canons ship a byte copy of this file in runtime/ and build their rules with it.
 import path from 'node:path';
 import { projectGraph } from './project-graph.mjs';
-import { posixPath } from './path-key.mjs';
-import { belongsTo, codeOf } from '../checks/architecture/surface.mjs';
+import { posixPath } from '../lib/path-key.mjs';
+import { belongsTo, codeOf } from './architecture/surface.mjs';
 
 /**
  * A rule reporting the graph findings of `codes` on the linted file.

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/secrets.mjs

@@ -5,8 +5,8 @@
 //   - a tracked `.enc` that is not a sops envelope (an encrypted-looking file that holds plaintext);
 //   - a line of any other tracked text file that matches a secret pattern.
 // A finding names the file, the line and the pattern, never the value.
-import { FORBIDDEN_FILES, secretHits } from '../secret-patterns.mjs';
-import { isSopsEnvelope } from '../test-secrets.mjs';
+import { FORBIDDEN_FILES, secretHits } from '../../lib/secret-patterns.mjs';
+import { isSopsEnvelope } from '../../lib/test-secrets.mjs';
 import { found, readText } from './read.mjs';
 
 export const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';