@starci/hfs 4.0.6 → 4.0.8

package/runtime/scripts/api/sops/decrypt.mjs

@@ -0,0 +1,16 @@
+// decrypt.mjs — one `sops` decryption: the custody reads (scripts/api/sops/exec-env.mjs execEnv) and the test
+// secrets (scripts/lib/test-secrets.mjs testSecret). The plaintext stays in this process's memory (stdout over a pipe).
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Run `<bin> <args>` with SOPS_AGE_KEY_FILE defaulted to ~/.starci/master.identity. {status, stdout, stderr, error}.
+ */
+export function sopsDecrypt(bin, args, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024 } = {}) {
+  const r = spawnSync(bin, args, {
+    cwd, encoding: 'utf8', windowsHide: true, maxBuffer,
+    env: { ...env, SOPS_AGE_KEY_FILE: env.SOPS_AGE_KEY_FILE || path.join(os.homedir(), '.starci', 'master.identity') },
+  });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
+}

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

@@ -1,10 +1,10 @@
 import path from 'node:path';
-import { braceVariants, globExpression } from './glob.mjs';
+import { braceVariants, globExpression } from '../lib/glob.mjs';
 
 /**
  * What a slot's `requires`, `allows` and `forbids` entries (knowledge/hfs/slots.yaml) say about a file, read through the
- * resolver of scripts/lib/hfs-slots.mjs. The machine checks that judge "this folder holds only what its slot allows"
- * (feature-shape, fe-slot-allows) and the front-end lint rules (through `hfs.allows(file)` of scripts/lib/hfs-view.mjs) read it here so no check keeps a path list.
+ * resolver of scripts/hfs/slots.mjs. The machine checks that judge "this folder holds only what its slot allows"
+ * (feature-shape, fe-slot-allows) and the front-end lint rules (through `hfs.allows(file)` of scripts/hfs/view.mjs) read it here so no check keeps a path list.
  *
  * An entry is a name relative to the slot instance root: `<var>` is the instance's bound variable when the slot binds it
  * (`<feature>`, `<capability>`) and one path segment of any text otherwise (`<action>`), `*` and `?` stay inside a segment,

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

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { isInside } from './config.mjs';
-import { slotAdmitsFile } from '../../lib/hfs-allows.mjs';
+import { slotAdmitsFile } from '../allows.mjs';
 import { reachableViolation, relativePath, sourceLocation } from './typescript.mjs';
 
 const FORBIDDEN_APP_ROLE = /(?:^|\.)(?:service|provider|providers|resolver|controller|handler|repository|entity|use-case|command|query|listener|consumer|processor)\.[cm]?[jt]sx?$/i;

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

@@ -2,8 +2,8 @@ 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';
+import { isInside } from '../../lib/walk.mjs';
+import { openHfs } from '../slots.mjs';
 
 
 /** A file's identity: its resolved real path, or the resolved path when it does not exist. */

package/runtime/scripts/{checks → hfs}/architecture/connection-map.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { machineKit, pascal, upperSnake } from './machine-ast.mjs';
-import { locateDeclaration } from '../../lib/hfs-slots.mjs';
+import { locateDeclaration } from '../slots.mjs';
 
 /**
  * R84 `connection-map` (BE_CONNECTION_DUPLICATE), folding RED01 and RED02. One physical database is one connection, one

package/runtime/scripts/{checks → hfs}/architecture/contract-fixture-guard.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { treeOf } from './required-files.mjs';
-import { allowsFile } from '../../lib/hfs-allows.mjs';
+import { allowsFile } from '../allows.mjs';
 
 /**
  * R47 `contract-fixture-guard` (BE_CONTRACT_UNGUARDED). A fake at the network edge serves payload fixtures; a fixture drifts

package/runtime/scripts/{checks → hfs}/architecture/fe-slot-allows.mjs

@@ -1,6 +1,6 @@
 import { treeOf } from './required-files.mjs';
-import { allowsFile } from '../../lib/hfs-allows.mjs';
-import { isFeTestPath } from '../../lib/hfs-rules/fe-no-tests.mjs';
+import { allowsFile } from '../allows.mjs';
+import { isFeTestPath } from '../rules/fe-no-tests.mjs';
 
 /**
  * R94 `fe-slot-allows` (FE_SLOT_FILE_ROLE). A front-end slot that owns a whole directory (`fe.route`, `fe.feature`,
@@ -11,7 +11,7 @@ import { isFeTestPath } from '../../lib/hfs-rules/fe-no-tests.mjs';
  * Files no slot owns are HFS_PATH_NO_SLOT's (`hfs check`), so together every front-end file is placed by exactly one slot and
  * named by it. A test path (a `.spec.tsx` or `.test.tsx` beside a component, a test directory or test tooling) is FE_NO_TESTS's
  * (R97, contract-change fe-no-tests): that rule is the one finding of such a file, so this check leaves it alone, as
- * HFS_PATH_NO_SLOT does (scripts/lib/hfs-path-findings.mjs).
+ * HFS_PATH_NO_SLOT does (scripts/hfs/path-findings.mjs).
  */
 export const FE_SLOT_ALLOWS_RULE_IDS = ['FE_SLOT_FILE_ROLE'];
 

package/runtime/scripts/{checks → hfs}/architecture/feature-shape.mjs

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { treeOf } from './required-files.mjs';
-import { allowsFile } from '../../lib/hfs-allows.mjs';
+import { allowsFile } from '../allows.mjs';
 
 /**
  * R29 `feature-shape` (BE_FEATURE_SHAPE). A feature root holds `index.ts`, `<feature>.module.ts`, `application/`,

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

@@ -3,7 +3,7 @@ import { relativePath } from './typescript.mjs';
 
 /**
  * The file and owner graph the HFS architecture checks share. Every production source file the TypeScript context
- * loaded becomes a node classified by the slot manifest (config.hfs is the resolver of scripts/lib/hfs-slots.mjs);
+ * loaded becomes a node classified by the slot manifest (config.hfs is the resolver of scripts/hfs/slots.mjs);
  * every import, re-export and type-only import between two of them becomes an edge. Nothing here judges: the checks
  * in tiers.mjs, reachability.mjs, dead-exports.mjs, required-files.mjs and clones.mjs read it.
  *

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

@@ -2,10 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { isIP } from 'node:net';
 import { gitOutput } from '../../api/git/lib.mjs';
-import { repositoryName } from '../../lib/repo-identity.mjs';
+import { repositoryName } from '../repo-identity.mjs';
 import { braceVariants } from '../../lib/glob.mjs';
-import { createSlotResolver, loadSlotManifest, openHfs } from '../../lib/hfs-slots.mjs';
-import { isFeTestPath } from '../../lib/hfs-rules/fe-no-tests.mjs';
+import { createSlotResolver, loadSlotManifest, openHfs } from '../slots.mjs';
+import { isFeTestPath } from '../rules/fe-no-tests.mjs';
 
 /**
  * HFS repository-tree check (knowledge/hfs/README.md): every StarCi repository is an

package/runtime/scripts/hfs/architecture/next-data-contract.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { canonical, exactKeys, isInside, slash } from './config.mjs';
+
+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']);
+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;
+}
+
+export 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 };
+}
+
+export 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)) };
+}

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/{checks → hfs}/architecture.mjs

@@ -1,13 +1,13 @@
 // architecture.mjs — the architecture check (docs/architecture-check.md).
 //
-//   node scripts/checks/architecture.mjs <repo-root> [--base <commit>]
+//   node scripts/hfs/architecture.mjs <repo-root> [--base <commit>]
 //
 // Prints one starci/architecture-check@1 record. Exit 0: ok. Exit 1: violations or errors (a check that
 // cannot run is an error, never a pass). Exit 2: bad arguments.
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {checkArchitecture} from './architecture/index.mjs';
-import { isMain } from './common.mjs';
+import { isMain } from '../lib/is-main.mjs';
 
 export {checkArchitecture};
 

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

@@ -1,6 +1,6 @@
 // hfs-check.mjs - the HFS app check, behind `hfs check | explain` (packages/hfs) and reusable by any
 // runtime check. It reads three things and nothing else: the app's hfs.json, the slot manifest
-// (knowledge/hfs/slots.yaml through scripts/lib/hfs-slots.mjs) and the pins (knowledge/hfs/canon-pins.yaml). It never
+// (knowledge/hfs/slots.yaml through scripts/hfs/slots.mjs) and the pins (knowledge/hfs/canon-pins.yaml). It never
 // writes to the repository it inspects.
 //
 // checkRepo() answers, for the tracked paths of one app (git ls-files), per scope (the app root and each side folder):
@@ -28,6 +28,7 @@
 //   HFS_PROOF_COMMAND_FILE_MISSING (R105, hfs-rules/proof-commands.mjs) a .starciwork proof command that runs a file the repository does not hold
 //   HFS_PEER_INTEGRATION_MISSING  (R111, hfs-rules/peer-integrations.mjs) the app root package.json lacks the runtime peer a driver integration needs
 //   BE_INTEGRATION_SPEC_MISSING   (R112, hfs-rules/integration-specs.mjs) an integration with no integration spec that registers its module, maps its refusals and drives an outage
+//   FE_GRAPHQL_CONTRACT           (R113, hfs-rules/fe-contract-documents.mjs) a front-end GraphQL document the back end's contract snapshot does not serve
 //   FE_WIRE_GENERATED, FE_I18N_PLACEMENT, FE_I18N_CATALOG   (R52, R59, R60, hfs-rules/frontend.mjs) the front-end tree of each app
 //   HFS_GITIGNORE_BLOCK_DRIFT, HFS_SONAR_CONFIG   (R04, R11) produced by packages/hfs/sync/managed.mjs, which renders the templates
 //   HFS_FORMAT                    (R19) produced by packages/hfs/sync/format.mjs, which runs the repository's own prettier
@@ -38,37 +39,41 @@
 //   HFS_EMPTY_DIR                 a directory with no file below it (git never tracks one), outside .git, node_modules and ignored slots
 //   HFS_GHOST_TREE                an empty directory beside a sibling within two edits of its name (business / bussiness)
 //   HFS_UNTRACKED_ROOT_ENTRY      an entry git neither tracks nor ignores, outside an `ignored` slot (R03)
-// checkRepository() is the whole `hfs check`: checkRepo() plus the architecture machine (scripts/checks/architecture.mjs, one
+// A runtime repository (hfs.json kind runtime, judged with knowledge/hfs/runtime-slots.yaml) gets the per-path slot findings,
+// the required files and minimum instances and the tree findings only; scripts/hfs/runtime-check.mjs adds the runtime rules.
+// checkRepository() is the whole `hfs check`: checkRepo() plus the architecture machine (scripts/hfs/architecture.mjs, one
 // implementation; the published bundle carries a byte copy), its violations and errors reported as findings under their own
 // codes; `fast` limits both to the owners changed since the merge-base. Every finding carries its code and the Vietnamese why text of modules/kernel/failure-codes.yaml. Only `error`
 // findings fail the check.
 import fs from 'node:fs';
 import path from 'node:path';
 import { skillRoot } from '../../engine/runtime-root.mjs';
-import { ARCHITECTURE_RULE_IDS, checkArchitecture } from '../checks/architecture/index.mjs';
+import { ARCHITECTURE_RULE_IDS, checkArchitecture } from './architecture/index.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './hfs-slots.mjs';
-import { allowsFile } from './hfs-allows.mjs';
+import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './slots.mjs';
+import { allowsFile } from './allows.mjs';
+import { RUNTIME_KIND } from './manifest-shape.mjs';
 import { gitOutput } from '../api/git/lib.mjs';
-import { posixPath } from './path-key.mjs';
-import { readTree, treeFacts, untrackedEntries } from './hfs-tree.mjs';
-import { contractFindings } from './hfs-rules/contract.mjs';
-import { depFindings } from './hfs-rules/deps.mjs';
-import { appFrontendFindings, frontendFindings } from './hfs-rules/frontend.mjs';
-import { integrationSpecFindings } from './hfs-rules/integration-specs.mjs';
-import { lintSuppressionFindings } from './hfs-rules/lint-suppression.mjs';
-import { peerIntegrationFindings } from './hfs-rules/peer-integrations.mjs';
-import { pipelineFindings } from './hfs-rules/pipeline.mjs';
-import { proofCommandFindings } from './hfs-rules/proof-commands.mjs';
-import { repoLocalCheckFindings } from './hfs-rules/repo-local-checks.mjs';
-import { readJson } from './hfs-rules/read.mjs';
-import { secretFindings } from './hfs-rules/secrets.mjs';
-import { pathFindings } from './hfs-path-findings.mjs';
-import { onLintSurface } from '../checks/architecture/surface.mjs';
-import { checkAppRoot, trackedTreeView } from '../checks/architecture/hfs.mjs';
-import { stacksFindings } from './hfs-rules/stacks.mjs';
-import { testTopologyFindings } from './hfs-rules/test-topology.mjs';
-import { feNoTestsFindings, isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
+import { posixPath } from '../lib/path-key.mjs';
+import { readTree, treeFacts, untrackedEntries } from './tree.mjs';
+import { contractFindings } from './rules/contract.mjs';
+import { depFindings } from './rules/deps.mjs';
+import { appFrontendFindings, frontendFindings } from './rules/frontend-tree.mjs';
+import { feContractFindings } from './rules/fe-contract-documents.mjs';
+import { integrationSpecFindings } from './rules/integration-specs.mjs';
+import { lintSuppressionFindings } from './rules/lint-suppression.mjs';
+import { peerIntegrationFindings } from './rules/peer-integrations.mjs';
+import { pipelineFindings } from './rules/pipeline.mjs';
+import { proofCommandFindings } from './rules/proof-commands.mjs';
+import { repoLocalCheckFindings } from './rules/repo-local-checks.mjs';
+import { readJson } from './rules/read.mjs';
+import { secretFindings } from './rules/secrets.mjs';
+import { pathFindings } from './path-findings.mjs';
+import { onLintSurface } from './architecture/surface.mjs';
+import { checkAppRoot, trackedTreeView } from './architecture/hfs.mjs';
+import { stacksFindings } from './rules/stacks.mjs';
+import { testTopologyFindings } from './rules/test-topology.mjs';
+import { feNoTestsFindings, isFeTestPath } from './rules/fe-no-tests.mjs';
 
 export const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 export const FAILURE_CODES_FILE = 'modules/kernel/failure-codes.yaml';
@@ -86,7 +91,7 @@ export const CHECK_CODES = Object.freeze([
   'HFS_SLOT_REQUIRED_MISSING', 'HFS_MIN_INSTANCES', 'HFS_CANON_PIN_DRIFT', 'HFS_SIZE_SOFT_BACKLOG', 'BE_SOURCE_FORM',
   'HFS_MANAGED_FILE_DRIFT', 'HFS_TOOL_CONFIG_LOCAL', 'HFS_RULE_OFF_WITHOUT_REPLACEMENT', 'HFS_TS_STRICT',
   'HFS_PLAINTEXT_SECRET', 'HFS_STACKS_SHAPE', 'HFS_CI_MISSING_CANON', 'HFS_DEP_VERSION_SKEW', 'HFS_CONTRACT_SNAPSHOT_DRIFT',
-  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'BE_INTEGRATION_SPEC_MISSING', 'FE_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
+  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'BE_INTEGRATION_SPEC_MISSING', 'FE_GRAPHQL_CONTRACT', 'FE_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
   'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_FORMAT',
   'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
   ...REFUSAL_CODES,
@@ -253,6 +258,8 @@ function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, sco
     const count = instances.filter((i) => i.slot === slot).length;
     if (count < min) findings.push({ code: 'HFS_MIN_INSTANCES', level: 'error', path: resolver.slot(slot).path, slot, min, count, message: `${slot} needs at least ${min} instance${min === 1 ? '' : 's'} (${resolver.slot(slot).path}), found ${count}` });
   }
+  // The runtime repository (kind runtime) is judged here by its tree law only; its own rules run in scripts/hfs/runtime-check.mjs.
+  if (repo.kind === RUNTIME_KIND) return findings;
 
   const pins = readPins(root);
   findings.push(...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }));
@@ -268,6 +275,7 @@ function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, sco
       ...depFindings({ repoRoot, files: all }),
       ...peerIntegrationFindings({ repoRoot, files: all }),
       ...integrationSpecFindings({ repoRoot, files: all }),
+      ...feContractFindings({ repoRoot, files: all }),
       ...pipelineFindings({ repoRoot, files, pins }),
       ...testTopologyFindings({ repoRoot, files }),
       ...proofCommandFindings({ repoRoot, files: all, resolver, sides: Object.keys(repo.sides ?? {}) }),