@starci/hfs 1.0.1 → 2.0.1

package/runtime/scripts/checks/architecture/clones.mjs

@@ -0,0 +1,200 @@
+/**
+ * HFS check 7, R21 duplicate code (knowledge/hfs/slots.yaml ruleParams.<profile>.duplicateBlock = {lines: N, tokens: T},
+ * the one definition of the threshold): a token-normalised block of at least N source lines and T tokens that appears
+ * twice in the production program - in two owners, in two files of one owner, or twice in one file - is code copied
+ * instead of shared.
+ *
+ * Normalisation: every production file is flattened into its syntax-node sequence (the compiler's parsed tree, walked in
+ * source order; comments and whitespace do not exist in it), identifiers become one ID kind, string, template, numeric,
+ * bigint and regex literals become one LIT kind, keywords and operators keep their own kind. Leading import and
+ * export-from statements are dropped (imports repeat legitimately). A window is the run of tokens on N consecutive
+ * physical lines starting at a line start whose last token reaches line N; windows are hashed with a rolling polynomial
+ * hash (O(total tokens)), equal windows of two different owners are verified token by token, and overlapping hits on the
+ * same file pair and offset merge into one maximal block. A block whose lines are mostly type declarations
+ * (fewer than N/2 lines outside interface and type alias declarations) or of fewer than N/3 distinct line shapes
+ * (a decorated DTO field list repeating one shape) is ignored.
+ *
+ * Two kinds of file are uniform by design and are not compared, both found through the slot resolver: the entry main.ts of
+ * an app (slot appKind + its required main.ts) and the transport doors of a feature (a *.controller.ts, *.resolver.ts,
+ * *.gateway.ts, *.consumer.ts, *.job.ts or *.cli.ts of a slot that a protocol app composes). This is not a loophole: logic
+ * cannot live in either. A door body is dispatch only (eslint transport-is-thin, R88), and main.ts cannot share a
+ * helper because NestFactory is allowed only in main.ts (BE_ENTRYPOINT_ONLY_IN_APPS), so what repeats there is the
+ * canonical shape of section 5 of BE-CONVENTION. A door or main.ts that grows logic is refused by those enforcers, not
+ * excused here; every other file of the same slots (mappers, dto, app.module.ts) stays compared.
+ */
+export const CLONE_RULE_IDS = ['HFS_DUPLICATE_CODE'];
+
+const MAX_VIOLATIONS = 200;
+const DOOR_ROLES = new Set(['controller', 'resolver', 'gateway', 'consumer', 'job', 'cli']);
+const APP_ENTRY = 'main.ts';
+const ID = -1;
+const LIT = -2;
+
+function tokenize(ts, sourceFile) {
+  const { SyntaxKind } = ts;
+  const literalKinds = new Set([SyntaxKind.StringLiteral, SyntaxKind.NumericLiteral, SyntaxKind.BigIntLiteral, SyntaxKind.RegularExpressionLiteral,
+    SyntaxKind.NoSubstitutionTemplateLiteral, SyntaxKind.TemplateHead, SyntaxKind.TemplateMiddle, SyntaxKind.TemplateTail, SyntaxKind.JsxText]);
+  const kinds = [];
+  const lines = [];
+  const types = [];
+  const lineStarts = sourceFile.getLineStarts();
+  const lineOf = (position) => {
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low < high) {
+      const mid = (low + high + 1) >> 1;
+      if (lineStarts[mid] <= position) low = mid; else high = mid - 1;
+    }
+    return low + 1;
+  };
+  const visit = (node, inType) => {
+    const kind = node.kind;
+    if (kind >= SyntaxKind.FirstJSDocNode && kind <= SyntaxKind.LastJSDocNode) return;
+    if (kind === SyntaxKind.JsxText && node.containsOnlyTriviaWhiteSpaces) return;
+    const typeScope = inType || kind === SyntaxKind.InterfaceDeclaration || kind === SyntaxKind.TypeAliasDeclaration;
+    kinds.push(kind === SyntaxKind.Identifier || kind === SyntaxKind.PrivateIdentifier ? ID : literalKinds.has(kind) ? LIT : kind);
+    lines.push(lineOf(node.getStart(sourceFile)));
+    types.push(typeScope ? 1 : 0);
+    ts.forEachChild(node, (child) => { visit(child, typeScope); });
+  };
+  for (const statement of sourceFile.statements) {
+    if (statement.kind === SyntaxKind.ImportDeclaration || statement.kind === SyntaxKind.ImportEqualsDeclaration
+      || (statement.kind === SyntaxKind.ExportDeclaration && statement.moduleSpecifier)) continue;
+    visit(statement, false);
+  }
+  return { kinds: Int32Array.from(kinds), lines: Int32Array.from(lines), types: Uint8Array.from(types) };
+}
+
+/** The app a file belongs to, by the slot binding of the manifest; null for a file of no app. */
+const appOfFile = (resolver, rel) => resolver.classifyPath(rel).bindings?.app ?? null;
+
+/** True for the app entry and the transport doors: their shape is fixed by the convention and their body cannot hold logic. */
+function uniformByDesign(resolver, rel) {
+  const classified = resolver.classifyPath(rel);
+  if (classified.status !== 'owned' || !classified.slot) return false;
+  const slot = resolver.slot(classified.slot);
+  const base = rel.slice(rel.lastIndexOf('/') + 1);
+  if (slot.appKind !== undefined) return base === APP_ENTRY && (slot.requires ?? []).includes(APP_ENTRY);
+  const role = base.split('.').at(-2);
+  return (slot.composedBy?.length ?? 0) > 0 && DOOR_ROLES.has(role) && base.endsWith('.ts');
+}
+
+function homeText(profile, sameOwner, crossApp) {
+  if (crossApp) return 'move it to a package (packages/<pkg>, the shared-code slot of the repository) and import it from both apps';
+  if (sameOwner) return 'extract it once inside the owner and call it from both places';
+  if (profile === 'fe') return 'extract it once inside the app (apps/<app>/src/modules/<capability>/ when pure, apps/<app>/src/hooks/<domain>/ for a React hook) and import it from both';
+  return "move the shared helper to src/modules/platform/primitives/ or into the owning capability's src/modules/domain/<capability>/ and import it from both";
+}
+
+export function checkClones({ config, context, graph } = {}) {
+  const { lines: N, tokens: T } = graph.resolver.ruleParams().duplicateBlock;
+  const ts = context.ts ?? context.loaded.ts;
+  const entries = [];
+  for (const rel of [...graph.files.keys()].sort()) {
+    if (/\.d\.[cm]?tsx?$/.test(rel) || uniformByDesign(graph.resolver, rel)) continue;
+    const unit = graph.unit(rel);
+    if (!unit) continue;
+    entries.push({ rel, unit, ...tokenize(ts, graph.files.get(rel).sourceFile) });
+  }
+  // Rolling hash: two independent 32-bit polynomial prefix hashes, verified by token comparison on every match.
+  const B1 = 1000003;
+  const B2 = 92821;
+  let maxTokens = 0;
+  for (const file of entries) maxTokens = Math.max(maxTokens, file.kinds.length);
+  const pow1 = new Int32Array(maxTokens + 1);
+  const pow2 = new Int32Array(maxTokens + 1);
+  pow1[0] = 1; pow2[0] = 1;
+  for (let i = 1; i <= maxTokens; i += 1) { pow1[i] = Math.imul(pow1[i - 1], B1); pow2[i] = Math.imul(pow2[i - 1], B2); }
+  const buckets = new Map();
+  entries.forEach((file, fileIndex) => {
+    const { kinds, lines } = file;
+    const count = kinds.length;
+    const pre1 = new Int32Array(count + 1);
+    const pre2 = new Int32Array(count + 1);
+    for (let i = 0; i < count; i += 1) {
+      pre1[i + 1] = (Math.imul(pre1[i], B1) + kinds[i] + 3) | 0;
+      pre2[i + 1] = (Math.imul(pre2[i], B2) + kinds[i] + 7) | 0;
+    }
+    let end = 0;
+    for (let start = 0; start < count; start += 1) {
+      if (start > 0 && lines[start] === lines[start - 1]) continue;
+      const limit = lines[start] + N;
+      if (end < start) end = start;
+      while (end < count && lines[end] < limit) end += 1;
+      if (end === start || lines[end - 1] - lines[start] + 1 < N) continue;
+      const length = end - start;
+      if (length < T) continue;
+      const key = `${(pre1[end] - Math.imul(pre1[start], pow1[length])) | 0}:${(pre2[end] - Math.imul(pre2[start], pow2[length])) | 0}:${length}`;
+      const list = buckets.get(key);
+      const item = [fileIndex, start, end];
+      if (list) list.push(item); else buckets.set(key, [item]);
+    }
+  });
+  const same = (a, b) => {
+    const ka = entries[a[0]].kinds;
+    const kb = entries[b[0]].kinds;
+    for (let i = 0; i < a[2] - a[1]; i += 1) if (ka[a[1] + i] !== kb[b[1] + i]) return false;
+    return true;
+  };
+  // Hits per (file a, file b, offset): merged into maximal blocks below.
+  const hits = new Map();
+  for (const list of buckets.values()) {
+    if (list.length < 2) continue;
+    for (const item of list) {
+      // The first other occurrence is the partner; overlapping windows of one file are one occurrence, not a copy.
+      const partner = list.find((other) => other !== item && (other[0] !== item[0] || other[1] >= item[2] || item[1] >= other[2]));
+      if (!partner || !same(item, partner)) continue;
+      const order = entries[item[0]].rel === entries[partner[0]].rel ? item[1] < partner[1] : entries[item[0]].rel < entries[partner[0]].rel;
+      const [a, b] = order ? [item, partner] : [partner, item];
+      const key = `${a[0]}|${b[0]}|${b[1] - a[1]}`;
+      const group = hits.get(key);
+      if (group) group.push([a[1], a[2]]); else hits.set(key, [[a[1], a[2]]]);
+    }
+  }
+  const blocks = [];
+  // Shape of a block: the lines outside type declarations and the number of distinct line shapes (a field list of
+  // one decorated DTO shape repeated N times is boilerplate, not a copied helper).
+  const blockShape = (file, start, end) => {
+    const nonType = new Set();
+    const shapes = new Map();
+    for (let i = start; i < end; i += 1) {
+      if (!file.types[i]) nonType.add(file.lines[i]);
+      shapes.set(file.lines[i], ((shapes.get(file.lines[i]) ?? 7) * 31 + file.kinds[i] + 5) | 0);
+    }
+    return { nonType: nonType.size, distinct: new Set(shapes.values()).size };
+  };
+  for (const [key, group] of hits) {
+    const [ai, bi, diagText] = key.split('|');
+    const fileA = entries[Number(ai)];
+    const fileB = entries[Number(bi)];
+    const diag = Number(diagText);
+    group.sort((x, y) => x[0] - y[0]);
+    let [start, end] = group[0];
+    const flush = () => {
+      const shape = blockShape(fileA, start, end);
+      if (shape.nonType < Math.ceil(N / 2) || shape.distinct < Math.ceil(N / 3)) return;
+      const lineA = fileA.lines[start];
+      const endA = fileA.lines[end - 1];
+      blocks.push({ a: fileA, b: fileB, line: lineA, endLine: endA, lines: endA - lineA + 1,
+        twin: { path: fileB.rel, line: fileB.lines[start + diag], endLine: fileB.lines[end - 1 + diag] } });
+    };
+    for (const [nextStart, nextEnd] of group.slice(1)) {
+      if (nextStart <= end) { end = Math.max(end, nextEnd); continue; }
+      flush();
+      start = nextStart; end = nextEnd;
+    }
+    flush();
+  }
+  blocks.sort((x, y) => x.a.rel.localeCompare(y.a.rel) || x.line - y.line || x.b.rel.localeCompare(y.b.rel));
+  const profile = graph.profile;
+  const differentApps = (a, b) => { const left = appOfFile(graph.resolver, a); const right = appOfFile(graph.resolver, b); return left !== null && right !== null && left !== right; };
+  const violations = blocks.slice(0, MAX_VIOLATIONS).map((block) => ({
+    ruleId: 'HFS_DUPLICATE_CODE', path: block.a.rel, line: block.line, endLine: block.endLine, twin: block.twin, lines: block.lines,
+    message: `${block.a.rel}:${block.line}-${block.endLine} duplicates ${block.twin.path}:${block.twin.line}-${block.twin.endLine} (${block.lines} lines, threshold ${N} lines / ${T} tokens, identifiers and literals ignored); ${homeText(profile, block.a.unit === block.b.unit, differentApps(block.a.rel, block.b.rel))}.`,
+  }));
+  const owners = new Set();
+  let duplicatedLines = 0;
+  for (const block of blocks) { owners.add(block.a.unit); owners.add(block.b.unit); duplicatedLines += block.lines; }
+  return { violations, coverage: { status: 'checked', minLines: N, minTokens: T, files: entries.length, cloneBlocks: blocks.length, ownersInvolved: owners.size, duplicatedLines,
+    ...(blocks.length > MAX_VIOLATIONS ? { truncated: true } : {}) } };
+}

package/runtime/scripts/checks/architecture/config-unread.mjs

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import { treeOf } from './required-files.mjs';
+
+/**
+ * R24 `arch-config-unread` (HFS_ARCH_CONFIG_UNREAD). The machine reads `hfs.json` and nothing else; a config file it
+ * no longer reads is dead text that says a rule is tuned when it is not, and a declaration that yields no analysed file
+ * is a machine that judged nothing. Both are red:
+ *
+ *   - a tracked `architecture.json` (the retired per-repository config; the declaration is hfs.json, the rest is derived
+ *     from the slot manifest);
+ *   - a repository whose declaration and tsconfig load but whose program holds no production source file.
+ */
+export const CONFIG_UNREAD_RULE_IDS = ['HFS_ARCH_CONFIG_UNREAD'];
+
+const RULE = 'HFS_ARCH_CONFIG_UNREAD';
+/** Config file names an earlier machine read and this one never does. */
+const RETIRED_CONFIG_NAMES = ['architecture.json'];
+
+export function checkConfigUnread({ config, context }) {
+  const violations = [];
+  const tree = treeOf(config.root);
+  let retired = 0;
+  for (const file of [...tree.files].sort()) {
+    if (!RETIRED_CONFIG_NAMES.includes(path.posix.basename(file))) continue;
+    retired += 1;
+    violations.push({ ruleId: RULE, path: file, line: 1, column: 1,
+      message: `${file} is a config the architecture machine no longer reads. hfs.json declares the repository; owners, roots, tiers and budgets come from the slot manifest. Delete ${file}.` });
+  }
+  const analysed = context.files.length;
+  if (analysed === 0) {
+    violations.push({ ruleId: RULE, path: 'hfs.json', line: 1, column: 1,
+      message: 'hfs.json and the TypeScript projects load but the machine analysed no production source file, so it judged nothing. Declare the apps that hold source in hfs.json, or fix the tsconfig include so the source is in the program.' });
+  }
+  return { violations, coverage: { status: 'checked', retired, analysed } };
+}

package/runtime/scripts/checks/architecture/config.mjs

@@ -0,0 +1,310 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { slash } from '../../lib/path-key.mjs';
+import { readJsonFile as readJson } from '../../lib/json.mjs';
+import { isInside } from '../common.mjs';
+import { openHfs } from '../../lib/hfs-slots.mjs';
+
+
+/** A file's identity: its resolved real path, or the resolved path when it does not exist. */
+function canonical(file) {
+  const absolute = path.resolve(file);
+  try { return path.resolve(fs.realpathSync(absolute)); } catch { return absolute; }
+}
+
+function exactKeys(value, allowed, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw Error(`${label} must be an object.`);
+  const unknown = Object.keys(value).filter(key => !allowed.has(key));
+  if (unknown.length) throw Error(`${label} has unsupported fields: ${unknown.sort().join(', ')}.`);
+}
+
+/**
+ * The git repository `root` sits in, found by walking up for a `.git` entry (a directory in a clone, a
+ * file in a worktree), or null when there is none. It is the outer boundary a `file:` dependency may
+ * resolve into: a checked project is routinely one package of a repository that also ships the packages
+ * it consumes, and `--root` is the project, not the repository.
+ */
+function enclosingRepository(root) {
+  let cursor = path.resolve(root);
+  for (;;) {
+    if (fs.existsSync(path.join(cursor, '.git'))) return cursor;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) return null;
+    cursor = parent;
+  }
+}
+
+function existingPackageDirectory(absolute) {
+  try {
+    if (!fs.lstatSync(absolute).isDirectory()) return false;
+    const manifest = fs.lstatSync(path.join(absolute, 'package.json'));
+    return manifest.isFile() && !manifest.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function existingDirectory(root, relative) {
+  try {
+    return fs.lstatSync(path.join(root, relative)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function existingRegularFile(root, relative) {
+  try {
+    const stat = fs.lstatSync(path.join(root, ...relative.split('/')));
+    return stat.isFile() && !stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function workspaceDirectories(root) {
+  const directories = new Set();
+  const queue = [root];
+  const visited = new Set();
+  const repository = enclosingRepository(root);
+  const admit = (candidate, label = 'local package', strict = false) => {
+    const absolute = path.resolve(candidate);
+    if (!isInside(root, absolute) || absolute === root || !existingDirectory(root, slash(path.relative(root, absolute)))) {
+      if (strict) throw Error(`${label} must resolve to a package directory inside the repository.`);
+      return;
+    }
+    const manifest = path.join(absolute, 'package.json');
+    try {
+      if (!fs.lstatSync(manifest).isFile() || fs.lstatSync(manifest).isSymbolicLink()) {
+        if (strict) throw Error(`${label} must resolve to a regular package.json inside the repository.`);
+        return;
+      }
+    } catch (error) {
+      if (strict) throw Error(error.message.startsWith(label) ? error.message : `${label} must resolve to a regular package.json inside the repository.`);
+      return;
+    }
+    const relative = slash(path.relative(root, absolute));
+    if (!directories.has(relative)) { directories.add(relative); queue.push(absolute); }
+  };
+  while (queue.length) {
+    const packageRoot = queue.shift();
+    if (visited.has(packageRoot)) continue;
+    visited.add(packageRoot);
+    const pkg = readJson(path.join(packageRoot, 'package.json'));
+    const patterns = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
+    for (const pattern of Array.isArray(patterns) ? patterns : []) {
+      if (typeof pattern !== 'string' || !pattern.trim()) throw Error('package.json workspace entries must be non-empty paths.');
+      const normalized = slash(pattern.trim()).replace(/^\.\//, '');
+      const segments = normalized.split('/');
+      if (path.isAbsolute(normalized) || segments.some(segment => segment === '..' || (segment.includes('*') && segment !== '*'))) {
+        throw Error(`Unsupported local workspace pattern: ${normalized}.`);
+      }
+      let candidates = [packageRoot];
+      for (const segment of segments) {
+        const next = [];
+        for (const base of candidates) {
+          if (segment === '*') {
+            if (!fs.existsSync(base) || !fs.lstatSync(base).isDirectory()) continue;
+            next.push(...fs.readdirSync(base, { withFileTypes: true })
+              .filter(item => item.isDirectory())
+              .sort((a, b) => a.name.localeCompare(b.name))
+              .map(item => path.join(base, item.name)));
+          } else next.push(path.join(base, segment));
+        }
+        candidates = next;
+      }
+      if (!candidates.length) throw Error(`Workspace pattern matched no package directories: ${normalized}.`);
+      // npm expands a `*` segment to the directories that hold a package.json and skips the rest (an empty or untracked folder is
+      // HFS_EMPTY_DIR / HFS_SLOT_UNDECLARED, never a reason to analyse nothing); a literal workspace path must resolve.
+      const wildcard = segments.includes('*');
+      for (const candidate of candidates) admit(candidate, `workspace ${normalized}`, !wildcard);
+    }
+    for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+      for (const [name, value] of Object.entries(pkg?.[section] ?? {})) {
+        if (typeof value !== 'string' || !value.startsWith('file:')) continue;
+        const absolute = path.resolve(packageRoot, value.slice('file:'.length));
+        const label = `${section}.${name} file dependency`;
+        if (isInside(root, absolute)) { admit(absolute, label, true); continue; }
+        // A sibling package of the same repository: this project consumes it, so the path is real and
+        // resolvable, but it is not part of this project's own source layout and must not become one of
+        // its workspaces - collecting it would pull another package's src into these roots. Refusing it
+        // instead would fail the whole check closed over an ordinary monorepo shape.
+        if (!repository || !isInside(repository, absolute) || !existingPackageDirectory(absolute)) {
+          throw Error(`${label} must resolve to a package directory inside the repository.`);
+        }
+      }
+    }
+  }
+  return [...directories].sort();
+}
+
+function discoveredProjects(root, workspaces) {
+  const projects = [];
+  if (fs.existsSync(path.join(root, 'tsconfig.json'))) projects.push('tsconfig.json');
+  for (const workspace of workspaces) {
+    for (const name of ['tsconfig.json', 'tsconfig.app.json', 'tsconfig.build.json']) {
+      const candidate = `${workspace}/${name}`;
+      if (fs.existsSync(path.join(root, ...candidate.split('/')))) {
+        projects.push(candidate);
+        break;
+      }
+    }
+  }
+  return [...new Set(projects)];
+}
+
+function inferredLayout(root, workspaces) {
+  // HFS: frontend source roots live only under workspace packages (apps/<app>/, packages/<pkg>/);
+  // the repository root itself is never a frontend source root.
+  // The route, feature, component, hook and module roles are app slots (fe.route, fe.feature, fe.components, fe.hooks, fe.modules:
+  // apps/<app>/src/...); a workspace package is tier `package` and holds none of them - its own src/hooks is package source, and a
+  // grammar package's tier folders make it a component root below.
+  const appWorkspaces = workspaces.filter(prefix => prefix.startsWith('apps/'));
+  const collect = suffix => appWorkspaces.map(prefix => `${prefix}/${suffix}`).filter(relative => existingDirectory(root, relative));
+  // A design-system workspace whose src carries tier dirs (leaves/branches/…) IS a component root;
+  // collecting its src/components too would nest two roots in one role and fail the disjoint check.
+  const tierSources = new Set(workspaces.map(prefix => `${prefix}/src`)
+    .filter(source => ['leaves', 'branches', 'blocks', 'overlays', 'composites', 'layouts', 'product-shells', 'pages']
+      .some(tier => existingDirectory(root, `${source}/${tier}`))));
+  const components = collect('src/components')
+    .filter(relative => !tierSources.has(path.posix.dirname(relative)));
+  components.push(...tierSources);
+  return {
+    routes: collect('src/app'),
+    features: collect('src/features'),
+    components: [...new Set(components)],
+    hooks: collect('src/hooks'),
+    modules: collect('src/modules'),
+    transport: collect('src/modules/api'),
+  };
+}
+
+function assertFrontendRolesDisjoint(root, frontend) {
+  const roles = ['routes', 'features', 'components', 'hooks', 'modules'];
+  const entries = roles.flatMap(role => frontend[role].map(relative => ({
+    role,
+    relative,
+    absolute: path.join(root, ...relative.split('/')),
+  })));
+  for (let index = 0; index < entries.length; index += 1) for (let other = index + 1; other < entries.length; other += 1) {
+    const left = entries[index];
+    const right = entries[other];
+    if (isInside(left.absolute, right.absolute) || isInside(right.absolute, left.absolute)) {
+      throw Error(`Architecture frontend role roots must be disjoint; ${left.role} ${left.relative} overlaps ${right.role} ${right.relative}.`);
+    }
+  }
+}
+
+const SKIPPED_DIRECTORIES = new Set(['node_modules', '.git', 'dist', '.next', '.turbo', 'coverage', 'test-results', '.starciwork', '.starcistacks']);
+
+function directoriesUnder(root, relative, depth) {
+  const out = [];
+  const visit = (dir, left) => {
+    let entries;
+    try { entries = fs.readdirSync(path.join(root, ...dir.split('/').filter(Boolean)), { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIPPED_DIRECTORIES.has(entry.name)) continue;
+      const child = dir ? `${dir}/${entry.name}` : entry.name;
+      out.push(child);
+      if (left > 1) visit(child, left - 1);
+    }
+  };
+  visit(relative, depth);
+  return out;
+}
+
+/** The owner entry a slot instance exposes: index.ts/index.tsx, a package's src/index.ts, an app's app.module.ts. */
+function ownerEntry(root, ownerRoot, tier) {
+  const candidates = tier === 'package' ? ['src/index.ts', 'src/index.tsx', 'index.ts', 'index.tsx']
+    : tier === 'app' ? ['app.module.ts'] : ['index.ts', 'index.tsx'];
+  for (const candidate of candidates) {
+    const relative = `${ownerRoot}/${candidate}`;
+    if (existingRegularFile(root, relative)) return relative;
+  }
+  return null;
+}
+
+/**
+ * Owners are derived from the slot manifest: every directory that an `owner: true` slot matches, with its entry file.
+ * An instance with no entry file is not listed: the required-files check reports the missing entry.
+ */
+function derivedOwners(root, resolver) {
+  const seen = new Map();
+  for (const directory of directoriesUnder(root, '', 6)) {
+    const owner = resolver.ownerOf(directory);
+    if (!owner || owner.root !== directory || seen.has(owner.root)) continue;
+    const slot = resolver.slot(owner.slot);
+    const entry = ownerEntry(root, owner.root, slot.tier);
+    if (entry) seen.set(owner.root, { id: `${owner.slot}:${owner.root}`, root: owner.root, entry, slot: owner.slot, tier: slot.tier });
+  }
+  return [...seen.values()].sort((a, b) => a.root.localeCompare(b.root));
+}
+
+const DECLARED_HANDLER_DECORATORS = ['CommandHandler', 'QueryHandler'];
+
+const GRAMMAR_PACKAGE = '@starci/grammar';
+
+/**
+ * The Grammar contract of a frontend repository, derived rather than declared: every app's globals.css is a style
+ * source, every app and every workspace package that depends on the Grammar package is a consumer. null when no app has
+ * a globals.css to judge (the contract is then reported unavailable, never passed).
+ */
+function derivedGrammar(root, apps, workspaces) {
+  const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
+  if (!styleSources.length) return null;
+  const consumerManifests = apps.map(app => `apps/${app.name}/package.json`).filter(relative => existingRegularFile(root, relative));
+  for (const workspace of workspaces) {
+    if (!workspace.startsWith('packages/')) continue;
+    const manifest = `${workspace}/package.json`;
+    const pkg = readJson(path.join(root, ...manifest.split('/')));
+    if (pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE))) consumerManifests.push(manifest);
+  }
+  if (!consumerManifests.length) return null;
+  return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react'] };
+}
+
+/**
+ * Resolve the layout contract from hfs.json and the slot manifest (knowledge/hfs/slots.yaml). architecture.json is
+ * retired: a repository carries only hfs.json. Owners, roots and the tier of every path come from slots; the contract
+ * has no ignore, waiver or baseline field.
+ */
+export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
+  const root = fs.realpathSync(path.resolve(repositoryRoot));
+  if (!fs.lstatSync(root).isDirectory()) throw Error('Repository root must be a directory.');
+  const opened = hfs ?? openHfs({ repoRoot: root });
+  const { profile, apps } = opened.repo;
+  const workspaces = workspaceDirectories(root);
+  const inferred = inferredLayout(root, [...new Set([...workspaces, ...apps.map(app => `apps/${app.name}`)])].sort());
+  const kinds = [profile === 'be' ? 'backend' : 'frontend'];
+  const projects = discoveredProjects(root, workspaces);
+  if (!projects.length) throw Error('The repository has no tsconfig.json to derive a TypeScript project from.');
+  const backend = {
+    modules: ['src/modules'],
+    features: ['src/features'],
+    apps: ['apps'],
+    moduleRegistration: { providerIdentity: 'exported-class-token', handlerDecorators: [...DECLARED_HANDLER_DECORATORS] },
+  };
+  const frontend = {
+    routes: inferred.routes,
+    features: inferred.features,
+    components: inferred.components,
+    hooks: inferred.hooks,
+    modules: inferred.modules,
+    transport: inferred.transport,
+    grammar: profile === 'fe' ? derivedGrammar(root, apps, workspaces) : null,
+  };
+  if (profile === 'fe') assertFrontendRolesDisjoint(root, frontend);
+  return {
+    root,
+    repository: enclosingRepository(root),
+    kinds,
+    projects,
+    workspaces,
+    apps: apps.map(app => ({ name: app.name, kind: app.kind })),
+    hfs: opened,
+    owners: derivedOwners(root, opened),
+    backend,
+    frontend,
+  };
+}
+
+export { canonical, enclosingRepository, exactKeys, isInside, slash };