@starci/hfs 1.0.1 → 2.0.0

package/runtime/scripts/checks/architecture/connection-map.mjs

@@ -0,0 +1,208 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { machineKit, pascal, upperSnake } from './machine-ast.mjs';
+
+/**
+ * R84 `connection-map` (BE_CONNECTION_DUPLICATE), folding RED01 and RED02. One physical database is one connection, one
+ * `Inject<Conn>EntityManager()` injector, one config; the `hfs.json` connections, the connection files, the injectors, the
+ * database module registration of every app and the env of every stack correspond one to one.
+ *
+ *   - per declared connection `<name>`: `src/modules/platform/database/<name>.connection.ts` exports
+ *     `<NAME>_CONNECTION = "<name>"`, `<name>.decorators.ts` exports `Inject<Pascal>EntityManager`, `<name>.config.ts`
+ *     exists and reads only `<ENVPREFIX>_*` keys;
+ *   - a connection file for a name hfs.json does not declare is refused;
+ *   - `getEntityManagerToken(` and `InjectEntityManager(` (from @nestjs/typeorm) resolve their argument through the
+ *     checker to a connection name and may be called only in that connection's decorators file, once; the DataSource
+ *     forms only in platform/database, the migrate app and the test fixtures; an exported `Inject*EntityManager`
+ *     anywhere else (a capability-specific injector, a duplicate) is refused;
+ *   - inside one app every connection is passed to the platform/database module registration once;
+ *   - in every `.starcistacks/<env>/runtime/env` two connections whose `<PREFIX>_HOST`, `<PREFIX>_PORT` and
+ *     `<PREFIX>_NAME` (or `_DATABASE`, whichever the config reads) resolve to one triple are the same database.
+ */
+export const CONNECTION_RULE_IDS = ['BE_CONNECTION_DUPLICATE'];
+
+const RULE = 'BE_CONNECTION_DUPLICATE';
+export const DATABASE_DIR = 'src/modules/platform/database';
+const TYPEORM = '@nestjs/typeorm';
+const MANAGER_CALLS = new Set(['getEntityManagerToken', 'InjectEntityManager']);
+const SOURCE_CALLS = new Set(['getDataSourceToken', 'InjectDataSource']);
+const ENV_KEY = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/u;
+const INJECTOR_NAME = /^Inject[A-Za-z0-9]*EntityManager$/u;
+
+function readEnvFiles(target) {
+  const merged = new Map();
+  const readFile = file => {
+    let text;
+    try { text = fs.readFileSync(file, 'utf8'); } catch { return; }
+    for (const raw of text.split(/\r?\n/u)) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/u.exec(line);
+      if (!match) continue;
+      let value = match[2].trim();
+      if (/^(['"]).*\1$/u.test(value)) value = value.slice(1, -1);
+      merged.set(match[1], value.trim());
+    }
+  };
+  let stat;
+  try { stat = fs.statSync(target); } catch { return null; }
+  if (stat.isFile()) readFile(target);
+  else for (const entry of fs.readdirSync(target, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.isFile() && !entry.name.toLowerCase().endsWith('.md')) readFile(path.join(target, entry.name));
+  }
+  return merged;
+}
+
+export function checkConnectionMap(input) {
+  const { config, graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const declared = config.hfs.repo.connections ?? [];
+  const byName = new Map(declared.map(connection => [connection.name, connection]));
+  const violations = [];
+  const report = (rel, message, extra = {}) => violations.push({ ruleId: RULE, path: rel, message, ...extra });
+  const decoratorsFile = name => `${DATABASE_DIR}/${name}.decorators.ts`;
+  const databaseFiles = [...graph.files.values()].filter(file => file.rel.startsWith(`${DATABASE_DIR}/`));
+
+  // 1. The three files of each declared connection, and no file of an undeclared one.
+  for (const connection of declared) {
+    const connectionRel = `${DATABASE_DIR}/${connection.name}.connection.ts`;
+    const constant = `${upperSnake(connection.name)}_CONNECTION`;
+    const connectionFile = kit.graphFile(connectionRel);
+    if (!connectionFile) report(connectionRel, `hfs.json declares connection ${connection.name} but ${connectionRel} does not exist; declare \`export const ${constant} = "${connection.name}"\` there.`, { connection: connection.name });
+    else {
+      const checker = kit.checkerOf(connectionFile.sourceFile);
+      const statement = connectionFile.sourceFile.statements.find(item => ts.isVariableStatement(item) && kit.isExported(item)
+        && item.declarationList.declarations.some(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === constant));
+      const initializer = statement?.declarationList.declarations.find(declaration => declaration.name.text === constant)?.initializer;
+      if (!statement || kit.stringValue(checker, initializer) !== connection.name) {
+        report(connectionRel, `${connectionRel} must export \`${constant} = "${connection.name}"\` (the connection name declared in hfs.json).`, { connection: connection.name });
+      }
+    }
+    const decorators = kit.graphFile(decoratorsFile(connection.name));
+    const injector = `Inject${pascal(connection.name)}EntityManager`;
+    const exported = decorators?.sourceFile.statements.some(item => (ts.isVariableStatement(item) && kit.isExported(item)
+      && item.declarationList.declarations.some(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === injector))
+      || (ts.isFunctionDeclaration(item) && kit.isExported(item) && item.name?.text === injector));
+    if (!exported) report(decoratorsFile(connection.name), `Connection ${connection.name} needs ${decoratorsFile(connection.name)} exporting ${injector}, the one injector of its shared EntityManager.`, { connection: connection.name });
+    const configRel = `${DATABASE_DIR}/${connection.name}.config.ts`;
+    const configFile = kit.graphFile(configRel);
+    if (!configFile) {
+      report(configRel, `Connection ${connection.name} needs ${configRel}, the one place its ${connection.envPrefix}_* keys are read.`, { connection: connection.name });
+      continue;
+    }
+    kit.walk(configFile.sourceFile, node => {
+      let key = null;
+      if (ts.isStringLiteralLike(node) && ENV_KEY.test(node.text)) key = node.text;
+      else if (ts.isPropertyAccessExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'env'
+        && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === 'process' && ENV_KEY.test(node.name.text)) key = node.name.text;
+      if (key === null) return true;
+      const own = key.startsWith(`${connection.envPrefix}_`);
+      const foreign = declared.find(other => other !== connection && key.startsWith(`${other.envPrefix}_`));
+      if (!own || foreign) {
+        report(configRel, `${configRel} reads ${key}; the config of connection ${connection.name} reads only ${connection.envPrefix}_* keys.`, { ...kit.at(configRel, configFile.sourceFile, node), connection: connection.name });
+      }
+      return false;
+    });
+  }
+  for (const file of databaseFiles) {
+    const match = /^(.+)\.(connection|decorators|config)\.ts$/u.exec(path.posix.basename(file.rel));
+    if (match && path.posix.dirname(file.rel) === DATABASE_DIR && !byName.has(match[1])) {
+      report(file.rel, `${file.rel} belongs to connection ${match[1]}, which hfs.json does not declare; declare the database in hfs.json connections or delete the file.`, { connection: match[1] });
+    }
+  }
+
+  // 2. Every entity manager token and injector in the program: one home per connection.
+  const perDecorators = new Map();
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    const slotIs = id => file.slot === id;
+    kit.walk(file.sourceFile, node => {
+      if (ts.isCallExpression(node)) {
+        const binding = kit.importBinding(checker, node.expression);
+        if (binding?.module === TYPEORM && MANAGER_CALLS.has(binding.name)) {
+          const value = kit.stringValue(checker, node.arguments[0]);
+          const home = value === null ? null : decoratorsFile(value);
+          if (value === null || !byName.has(value)) {
+            report(file.rel, `${binding.name}() names ${value === null ? 'a connection that cannot be resolved to a constant' : `connection ${value}, which hfs.json does not declare`}; only the declared connections have an entity manager token.`, kit.at(file.rel, file.sourceFile, node));
+          } else if (file.rel !== home) {
+            report(file.rel, `${binding.name}(${value}) belongs in ${home} only; inject the shared manager with Inject${pascal(value)}EntityManager() instead of a second path to connection ${value}.`, { ...kit.at(file.rel, file.sourceFile, node), connection: value });
+          } else {
+            perDecorators.set(value, (perDecorators.get(value) ?? 0) + 1);
+            if (perDecorators.get(value) > 1) report(file.rel, `${home} resolves connection ${value} more than once; one connection has one injector.`, { ...kit.at(file.rel, file.sourceFile, node), connection: value });
+          }
+        } else if (binding?.module === TYPEORM && SOURCE_CALLS.has(binding.name)) {
+          const allowed = file.rel.startsWith(`${DATABASE_DIR}/`) || slotIs('be.app.migrate') || slotIs('be.tests.fixtures');
+          if (!allowed) report(file.rel, `${binding.name}() reaches the DataSource outside platform/database and the migrate app; inject the shared EntityManager of the connection instead.`, kit.at(file.rel, file.sourceFile, node));
+        }
+      }
+      const exportedName = (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && ts.isVariableStatement(node.parent?.parent) && kit.isExported(node.parent.parent)) ? node.name.text
+        : (ts.isFunctionDeclaration(node) && kit.isExported(node) && node.name ? node.name.text : null);
+      if (exportedName && INJECTOR_NAME.test(exportedName)) {
+        const home = [...byName.keys()].find(name => `Inject${pascal(name)}EntityManager` === exportedName);
+        if (!home || file.rel !== decoratorsFile(home)) {
+          report(file.rel, `${exportedName} is exported here, but the only injector of an entity manager is Inject<Conn>EntityManager in src/modules/platform/database/<conn>.decorators.ts, one per declared connection.`, kit.at(file.rel, file.sourceFile, node));
+        }
+      }
+      return true;
+    });
+  }
+
+  // 3. Each connection is passed to the database module registration once per app.
+  let registrations = 0;
+  for (const app of config.apps) {
+    const root = kit.appRoot(app.name);
+    if (!root) continue;
+    const checker = kit.checkerOf(root.sourceFile);
+    const passed = new Map();
+    kit.walk(root.sourceFile, node => {
+      if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register')) return true;
+      const owner = kit.declarationsOf(checker, node.expression.expression).map(kit.ownerOfDeclaration).find(Boolean);
+      if (!owner || owner.tier !== 'platform' || owner.name !== 'database') return true;
+      registrations += 1;
+      for (const argument of node.arguments) {
+        kit.walk(argument, inner => {
+          if (ts.isPropertyAssignment(inner.parent ?? {}) && inner.parent.name === inner) return true;
+          if (ts.isPropertyAccessExpression(inner.parent ?? {}) && inner.parent.name === inner) return true;
+          if (!(ts.isIdentifier(inner) || ts.isStringLiteralLike(inner) || ts.isPropertyAccessExpression(inner))) return true;
+          const value = kit.stringValue(checker, inner);
+          if (value === null || !byName.has(value)) return true;
+          passed.set(value, (passed.get(value) ?? 0) + 1);
+          if (passed.get(value) > 1) report(root.rel, `App ${app.name} passes connection ${value} to the database module registration more than once; one connection is registered once per app.`, { ...kit.at(root.rel, root.sourceFile, inner), connection: value, app: app.name });
+          return false;
+        });
+      }
+      return true;
+    });
+  }
+
+  // 4. Stacks: two connections that resolve to one host, port and database are one database.
+  let stacksChecked = 0;
+  let stacksSkipped = 0;
+  const stacksRoot = path.join(config.root, '.starcistacks');
+  let envs = [];
+  try { envs = fs.readdirSync(stacksRoot, { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name).sort(); } catch { envs = []; }
+  for (const env of envs) {
+    const rel = `.starcistacks/${env}/runtime/env`;
+    const values = readEnvFiles(path.join(stacksRoot, env, 'runtime', 'env'));
+    if (!values || values.size === 0) { stacksSkipped += 1; continue; }
+    const seen = new Map();
+    let resolved = 0;
+    for (const connection of declared) {
+      const configFile = kit.graphFile(`${DATABASE_DIR}/${connection.name}.config.ts`);
+      const nameKey = configFile?.sourceFile.text.includes(`${connection.envPrefix}_DATABASE`) ? `${connection.envPrefix}_DATABASE` : `${connection.envPrefix}_NAME`;
+      const host = values.get(`${connection.envPrefix}_HOST`);
+      const port = values.get(`${connection.envPrefix}_PORT`);
+      const database = values.get(nameKey);
+      if (!host || !port || !database) continue;
+      resolved += 1;
+      const triple = `${host.toLowerCase()}|${port}|${database}`;
+      if (seen.has(triple)) {
+        report(rel, `Connections ${seen.get(triple)} and ${connection.name} resolve to the same database (${host}:${port}/${database}) in stack ${env}; one physical database is one connection.`, { connection: connection.name, env });
+      } else seen.set(triple, connection.name);
+    }
+    if (resolved) stacksChecked += 1; else stacksSkipped += 1;
+  }
+
+  return { violations, coverage: { status: 'checked', connections: declared.length, registrations, stacksChecked, stacksSkipped } };
+}

package/runtime/scripts/checks/architecture/constructor-deps.mjs

@@ -0,0 +1,100 @@
+import path from 'node:path';
+
+/**
+ * The constructor dependencies of a service, read the way the injection law (R85) writes them, shared by the unit-spec
+ * provider check (R48 `unit-spec-providers`) and the token export check (R85 `injection-token-exported`).
+ *
+ * A constructor parameter is one of
+ *   - `token`: decorated with a custom `Inject<Thing>()` decorator. The decorator is declared in a `<cap>.decorators.ts`
+ *     as `injector<T>(TOKEN)`; the dependency is the TOKEN it names, identified by the name the token is exported under
+ *     (the declaration's own name), never by the decorator's or the parameter's name. A raw `@Inject(TOKEN)` is read the same way.
+ *   - `class`: no injection decorator and a class type; the dependency is that class.
+ *   - `unresolved`: anything else (a token expression that is not a plain identifier, a decorator the reader cannot follow,
+ *     a type that is not a class).
+ */
+const INJECT_NAME = /^Inject(?:[A-Z][A-Za-z0-9]*)?$/u;
+
+/** The identifier a decorator names: `@InjectFoo()` -> InjectFoo, `@Inject(TOKEN)` -> Inject; null for a non-identifier decorator. */
+function decoratorCallee(ts, decorator) {
+  const expression = decorator.expression;
+  const callee = ts.isCallExpression(expression) ? expression.expression : expression;
+  return ts.isIdentifier(callee) ? { callee, call: ts.isCallExpression(expression) ? expression : null } : null;
+}
+
+/** The token a `injector(<arg>)` call names, judged where the argument is declared. */
+function tokenOfArgument(kit, checker, argument) {
+  const { ts } = kit;
+  if (!argument || !ts.isIdentifier(argument)) return { kind: 'unresolved', reason: 'its token is not a plain identifier of an exported const', node: argument ?? null };
+  const declaration = kit.declarationsOf(checker, argument).find(item => ts.isVariableDeclaration(item) || ts.isBindingElement(item));
+  if (declaration) {
+    const name = ts.isIdentifier(declaration.name) ? declaration.name.text : argument.text;
+    return { kind: 'token', name, declaration, argument, external: false };
+  }
+  const binding = kit.importBinding(checker, argument);
+  if (binding && !binding.module.startsWith('.')) return { kind: 'token', name: binding.name, declaration: null, argument, external: true };
+  return { kind: 'unresolved', reason: `the token ${argument.text} does not resolve to a declaration`, node: argument };
+}
+
+/** The injector token of a custom `Inject<Thing>()` decorator, or an unresolved reason. */
+function tokenOfInjectDecorator(kit, checker, parameter, decorator) {
+  const { ts } = kit;
+  const head = decoratorCallee(ts, decorator);
+  if (!head || !INJECT_NAME.test(head.callee.text)) return null;
+  if (head.callee.text === 'Inject' && head.call?.arguments.length) return { ...tokenOfArgument(kit, checker, head.call.arguments[0]), decorator: head.callee.text, decoratorDeclaration: null, decoratorFile: null };
+  const declaration = kit.declarationsOf(checker, head.callee).find(item => ts.isVariableDeclaration(item) || ts.isFunctionDeclaration(item));
+  if (!declaration) return { kind: 'unresolved', reason: `${head.callee.text}() does not resolve to a declaration`, node: parameter, decorator: head.callee.text };
+  let injectorCall = null;
+  kit.walk(declaration, node => {
+    if (injectorCall) return false;
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      const declarationChecker = kit.checkerOf(declaration.getSourceFile());
+      const binding = kit.importBinding(declarationChecker, node.expression);
+      if ((binding?.name ?? node.expression.text) === 'injector') injectorCall = node;
+    }
+    return true;
+  });
+  if (!injectorCall) return { kind: 'unresolved', reason: `${head.callee.text}() is not built with injector<T>(TOKEN)`, node: parameter, decorator: head.callee.text };
+  const declarationChecker = kit.checkerOf(declaration.getSourceFile());
+  return { ...tokenOfArgument(kit, declarationChecker, injectorCall.arguments[0]), decorator: head.callee.text, decoratorDeclaration: declaration, injectorCall };
+}
+
+/** The class a parameter type names, judged where the type is declared; null when it is not a class type. */
+function classOfType(kit, checker, type) {
+  const { ts } = kit;
+  if (!type || !ts.isTypeReferenceNode(type) || !ts.isIdentifier(type.typeName)) return null;
+  const declarations = kit.declarationsOf(checker, type.typeName);
+  const declared = declarations.find(item => ts.isClassDeclaration(item) && item.name);
+  if (declared) return declared.name.text;
+  if (declarations.length) return null;
+  const binding = kit.importBinding(checker, type.typeName);
+  return binding && binding.name !== 'default' && binding.name !== '*' ? binding.name : null;
+}
+
+/** The dependencies of one class, in constructor order: [{kind, name?, node, parameter, ...}]. */
+export function constructorDependencies(kit, file, classDeclaration) {
+  const { ts } = kit;
+  const checker = kit.checkerOf(file.sourceFile);
+  const constructor = classDeclaration.members.find(member => ts.isConstructorDeclaration(member) && member.body !== undefined)
+    ?? classDeclaration.members.find(member => ts.isConstructorDeclaration(member));
+  if (!constructor) return [];
+  return constructor.parameters.map(parameter => {
+    for (const decorator of kit.decorators(parameter)) {
+      const token = tokenOfInjectDecorator(kit, checker, parameter, decorator);
+      if (token) return { ...token, parameter, node: token.node ?? parameter };
+    }
+    const name = classOfType(kit, checker, parameter.type);
+    if (name) return { kind: 'class', name, parameter, node: parameter };
+    return { kind: 'unresolved', reason: 'it has no Inject<Thing>() decorator and its type is not a class', parameter, node: parameter };
+  });
+}
+
+/** Every service class of the program: [{file, declaration}] for each class of a `*.service.ts` file. */
+export function serviceClasses(kit, graph) {
+  const { ts } = kit;
+  const found = [];
+  for (const file of graph.files.values()) {
+    if (!path.posix.basename(file.rel).endsWith('.service.ts')) continue;
+    for (const statement of file.sourceFile.statements) if (ts.isClassDeclaration(statement) && statement.name) found.push({ file, declaration: statement });
+  }
+  return found;
+}

package/runtime/scripts/checks/architecture/contract-fixture-guard.mjs

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { treeOf } from './required-files.mjs';
+import { allowsFile } from '../../lib/hfs-allows.mjs';
+
+/**
+ * R47 `contract-fixture-guard` (BE_CONTRACT_UNGUARDED). A fake at the network edge serves payload fixtures; a fixture drifts
+ * from the real provider silently unless a sandbox contract spec compares them. So every `fakes/<provider>/` of the test
+ * world that holds payload fixtures (`payloads/*.json`) needs at least one `src/tests/contract/<provider>/*.contract-spec.ts`
+ * (slot be.tests.contract) that, in its AST,
+ *   1. references that provider's fixtures: a call whose argument is the provider's name as a string literal (the world's
+ *      fixture accessor, `renderPayload("<provider>", ...)`), an import from `fakes/<provider>/`, or a string that names
+ *      `fakes/<provider>/`; and
+ *   2. compares shapes: an `expect(<... shapeOf(real) ...>).toEqual(<... shapeOf(fixture) ...>)` (or `toStrictEqual`), where
+ *      `shapeOf` is the helper the world vocabulary names (knowledge/hfs/slots.yaml ruleParams.be.contractShape.helper) and
+ *      is imported, never declared in the spec.
+ * A fake with fixtures and no such spec is a finding at its first fixture. The tree is the tracked one over the world's own
+ * slot; nothing names a path. Fakes the test-world library provides (declared in `test-world.config.ts`, held in the library
+ * package) have no tracked fixtures here and are guarded by the library's own contract specs, so only the repository's own
+ * `fakes/<provider>/` folders are judged.
+ */
+export const CONTRACT_FIXTURE_GUARD_RULE_IDS = ['BE_CONTRACT_UNGUARDED'];
+
+const RULE = 'BE_CONTRACT_UNGUARDED';
+const WORLD_SLOT = 'be.tests.world';
+const CONTRACT_SLOT = 'be.tests.contract';
+const FAKES_DIRECTORY = 'fakes/';
+const PAYLOADS = /^([^/]+)\/payloads\/[^/]+\.json$/u;
+const SHAPE_MATCHERS = new Set(['toEqual', 'toStrictEqual']);
+
+const unwrap = (ts, node) => {
+  let current = node;
+  while (current && (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current) || ts.isAwaitExpression(current))) current = current.expression;
+  return current;
+};
+
+/** Every node under `root`, itself included. */
+function walk(ts, root, visit) {
+  const step = node => { visit(node); ts.forEachChild(node, step); };
+  step(root);
+}
+
+/** Facts one contract spec establishes: the providers whose fixtures it references and whether it compares shapes. */
+function readSpec(ts, sourceFile, helper, providers) {
+  const shapeNames = new Set();
+  const referenced = new Set();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    const from = statement.moduleSpecifier.text;
+    for (const provider of providers) if (from.includes(`${FAKES_DIRECTORY}${provider}/`) || from.endsWith(`${FAKES_DIRECTORY}${provider}`)) referenced.add(provider);
+    const named = statement.importClause?.namedBindings;
+    if (!named || !ts.isNamedImports(named)) continue;
+    for (const element of named.elements) if ((element.propertyName ?? element.name).text === helper) shapeNames.add(element.name.text);
+  }
+  const callsShape = node => {
+    let found = false;
+    walk(ts, node, inner => { if (ts.isCallExpression(inner) && ts.isIdentifier(inner.expression) && shapeNames.has(inner.expression.text)) found = true; });
+    return found;
+  };
+  let compares = false;
+  walk(ts, sourceFile, node => {
+    if (ts.isStringLiteralLike(node)) for (const provider of providers) if (node.text.includes(`${FAKES_DIRECTORY}${provider}/`)) referenced.add(provider);
+    if (!ts.isCallExpression(node)) return;
+    const named = ts.isIdentifier(node.expression) ? node.expression.text : null;
+    for (const argument of node.arguments) {
+      const value = unwrap(ts, argument);
+      if (value && ts.isStringLiteralLike(value) && providers.has(value.text) && named !== 'describe' && named !== 'it' && named !== 'test') referenced.add(value.text);
+    }
+    const callee = node.expression;
+    if (!ts.isPropertyAccessExpression(callee) || !SHAPE_MATCHERS.has(callee.name.text)) return;
+    let receiver = unwrap(ts, callee.expression);
+    while (receiver && ts.isPropertyAccessExpression(receiver)) receiver = unwrap(ts, receiver.expression); // .not / .resolves
+    if (!receiver || !ts.isCallExpression(receiver) || !ts.isIdentifier(receiver.expression) || receiver.expression.text !== 'expect') return;
+    const [actual] = receiver.arguments;
+    const [expected] = node.arguments;
+    if (actual && expected && callsShape(actual) && callsShape(expected)) compares = true;
+  });
+  return { referenced, compares };
+}
+
+export function checkContractFixtureGuard(input) {
+  const { config, graph, context } = input;
+  const ts = context.ts;
+  const resolver = graph.resolver;
+  const { contractShape } = resolver.ruleParams();
+  const tree = treeOf(config.root);
+  const violations = [];
+  const fixtures = new Map(); // provider -> first payload fixture file
+  const specs = new Map(); // provider -> [contract spec file]
+  for (const file of [...tree.files].sort()) {
+    const classified = resolver.classifyPath(file);
+    if (classified.status !== 'owned') continue;
+    if (classified.slot === CONTRACT_SLOT) {
+      const provider = classified.bindings?.provider;
+      if (provider && file.endsWith('.contract-spec.ts')) specs.set(provider, [...(specs.get(provider) ?? []), file]);
+      continue;
+    }
+    const verdict = classified.slot === WORLD_SLOT ? allowsFile(resolver, file) : null;
+    if (verdict?.slot === WORLD_SLOT) {
+      if (!verdict.relative.startsWith(FAKES_DIRECTORY)) continue;
+      const match = PAYLOADS.exec(verdict.relative.slice(FAKES_DIRECTORY.length));
+      if (match && !fixtures.has(match[1])) fixtures.set(match[1], file);
+    }
+  }
+  const providers = new Set(fixtures.keys());
+  const guarded = new Set();
+  for (const [provider, files] of specs) {
+    for (const file of files) {
+      const absolute = path.join(config.root, ...file.split('/'));
+      if (!fs.existsSync(absolute)) continue;
+      const sourceFile = ts.createSourceFile(absolute, fs.readFileSync(absolute, 'utf8'), ts.ScriptTarget.Latest, true); // the contract tree is outside the root program
+      const facts = readSpec(ts, sourceFile, contractShape.helper, providers);
+      if (facts.compares && facts.referenced.has(provider)) guarded.add(provider);
+    }
+  }
+  for (const [provider, file] of [...fixtures].sort(([a], [b]) => a.localeCompare(b))) {
+    if (guarded.has(provider)) continue;
+    const has = specs.get(provider)?.length ?? 0;
+    const why = has === 0
+      ? `there is no src/tests/contract/${provider}/*.contract-spec.ts`
+      : `none of the ${has} contract spec(s) under src/tests/contract/${provider}/ both references the ${provider} fixtures and asserts expect(${contractShape.helper}(real)).toEqual(${contractShape.helper}(fixture))`;
+    violations.push({
+      ruleId: RULE, path: file, line: 1, column: 1, slot: WORLD_SLOT,
+      message: `fakes/${provider}/ serves payload fixtures but no contract spec guards them: ${why}. A fixture that is not compared with the real provider drifts silently; add the sandbox contract spec (the contract helper of the world skips it when the sandbox config is absent).`,
+    });
+  }
+  return { violations, coverage: { status: 'checked', fixtureFakes: fixtures.size, contractSpecs: [...specs.values()].flat().length } };
+}