@starci/hfs 1.0.1 → 2.0.0

package/runtime/scripts/checks/architecture/test-world-files.mjs

@@ -0,0 +1,163 @@
+import { treeOf } from './required-files.mjs';
+import { allowsFile } from '../../lib/hfs-allows.mjs';
+import { DEFAULT_ENVIRONMENT, STACKS_DIRECTORY, STATEFUL_KINDS, namesOfService, readStack } from '../../lib/stack-services.mjs';
+
+/**
+ * R47 `test-world-files` (BE_TEST_TOPOLOGY). Two judgements over the test world, read through slots, the repository's own
+ * stack definition (`.starcistacks/<env>`, scripts/lib/stack-services.mjs) and the world's declaration
+ * (`test-world.config.ts` of the test-world library), never through a path or a name list:
+ *
+ * 1. Files. `src/tests/world/` is the only test infrastructure location, and it holds only what its slot `allows`
+ *    (knowledge/hfs/slots.yaml be.tests.world: global-setup.ts, global-teardown.ts, use-test-world.ts, and fakes/; kit/ is
+ *    its own slot, be.tests.world.kit) plus files at its root whose role suffix is in ruleParams.be.suffixes
+ *    (`stripe.client.ts`, `checkout.contracts.ts`, `test-world.config.ts`, ...). Every tracked file below the world root is
+ *    matched by the slot's own entries through `allowsFile`.
+ * 2. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world;
+ *    `fakes/<provider>/` holds a network-edge fake of an external SaaS the team does not operate. A `fakes/<provider>/` that
+ *    fakes a stack service (its own name, its image repository or a well-known alias of the image) is refused, except the one
+ *    owner-approved exception: a stack service that is stateless compute needing special hardware or an external model
+ *    (GPU inference, a self-hosted embedding model) and that the config declares in `fakedBy`:
+ *    `fakedBy: { "<stack service>": { fake: "<fakes/ folder>", reason: "<non-empty>" } }`. A stack service of a stateful
+ *    kind (database, cache, identity, storage, mail, queue, search) or with a persistent volume is never accepted, and a
+ *    `fakedBy` entry that names a stack service or a fake folder that does not exist, or has no reason, is refused as stale
+ *    or empty. The config's `stacks` names the stack environments the world runs (default `dev`); the machine reads the
+ *    literal object of the config through the TypeScript AST and nothing else of it.
+ */
+export const TEST_WORLD_FILES_RULE_IDS = ['BE_TEST_TOPOLOGY'];
+
+const RULE = 'BE_TEST_TOPOLOGY';
+const WORLD_SLOT = 'be.tests.world';
+const FAKES_DIRECTORY = 'fakes/';
+const CONFIG_FILE = 'test-world.config.ts';
+const defaultEnvironment = DEFAULT_ENVIRONMENT;
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+const nameOf = (ts, name) => (name && (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) ? name.text : null);
+const unwrap = (ts, node) => {
+  let current = node;
+  while (current && (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression?.(current))) current = current.expression;
+  return current;
+};
+const propertyOf = (ts, literal, key) => literal.properties.find(property => ts.isPropertyAssignment(property) && nameOf(ts, property.name) === key)?.initializer ?? null;
+
+/** The object literal a config file declares: `export default { ... }` or `export default defineTestWorld({ ... })`. */
+function configLiteral(ts, sourceFile) {
+  for (const statement of sourceFile.statements) {
+    if (!ts.isExportAssignment(statement)) continue;
+    const expression = unwrap(ts, statement.expression);
+    if (ts.isObjectLiteralExpression(expression)) return expression;
+    if (ts.isCallExpression(expression)) {
+      const [first] = expression.arguments;
+      const literal = first ? unwrap(ts, first) : null;
+      if (literal && ts.isObjectLiteralExpression(literal)) return literal;
+    }
+  }
+  return null;
+}
+
+/** `stacks` as a list of environment names: an array of strings, or the keys of an object literal. */
+function stacksOf(ts, literal) {
+  const node = literal ? propertyOf(ts, literal, 'stacks') : null;
+  const value = node ? unwrap(ts, node) : null;
+  if (!value) return null;
+  if (ts.isArrayLiteralExpression(value)) return value.elements.filter(element => ts.isStringLiteralLike(element)).map(element => element.text);
+  if (ts.isObjectLiteralExpression(value)) return value.properties.map(property => nameOf(ts, property.name)).filter(Boolean);
+  return null;
+}
+
+/** `fakedBy` entries: [{service, fake, reason, line, column}]; a value the reader cannot read statically has an empty fake and reason. */
+function fakedByOf(ts, sourceFile, literal) {
+  const node = literal ? propertyOf(ts, literal, 'fakedBy') : null;
+  const value = node ? unwrap(ts, node) : null;
+  if (!value || !ts.isObjectLiteralExpression(value)) return [];
+  const entries = [];
+  for (const property of value.properties) {
+    if (!ts.isPropertyAssignment(property)) continue;
+    const service = nameOf(ts, property.name);
+    const body = unwrap(ts, property.initializer);
+    const fake = ts.isObjectLiteralExpression(body) ? propertyOf(ts, body, 'fake') : null;
+    const reason = ts.isObjectLiteralExpression(body) ? propertyOf(ts, body, 'reason') : null;
+    const position = sourceFile.getLineAndCharacterOfPosition(property.getStart(sourceFile));
+    entries.push({
+      service,
+      fake: fake && ts.isStringLiteralLike(fake) ? fake.text : '',
+      reason: reason && ts.isStringLiteralLike(reason) ? reason.text.trim() : '',
+      line: position.line + 1,
+      column: position.character + 1,
+    });
+  }
+  return entries;
+}
+
+export function checkTestWorldFiles(input) {
+  const { config, graph, context } = input;
+  const ts = context.ts;
+  const resolver = graph.resolver;
+  const { suffixes } = resolver.ruleParams();
+  const tree = treeOf(config.root);
+  const violations = [];
+  const fakeProviders = new Map();
+  let worldRoot = null;
+  let files = 0;
+  for (const file of [...tree.files].sort()) {
+    if (!file.endsWith('.ts')) continue;
+    const verdict = allowsFile(resolver, file);
+    if (!verdict || verdict.slot !== WORLD_SLOT) continue;
+    files += 1;
+    worldRoot ??= file.slice(0, file.length - verdict.relative.length);
+    if (verdict.relative.startsWith(FAKES_DIRECTORY)) {
+      const [provider, ...rest] = verdict.relative.slice(FAKES_DIRECTORY.length).split('/');
+      if (rest.length > 0 && !fakeProviders.has(provider)) fakeProviders.set(provider, file);
+    }
+    if (verdict.allowed) continue;
+    const parts = verdict.relative.slice(0, -'.ts'.length).split('.');
+    const roleFileAtRoot = !verdict.relative.includes('/') && parts.length >= 2 && parts.every(part => KEBAB.test(part)) && suffixes.includes(parts.at(-1));
+    if (roleFileAtRoot) continue;
+    violations.push({
+      ruleId: RULE, path: file, line: 1, column: 1,
+      message: `${file} is not allowed in the test world; src/tests/world/ holds only ${verdict.allows.join(', ')} and role-suffixed files (<name>.<role>.ts) at its root. Move it to fakes/ or kit/ (be.tests.world.kit), give it a role suffix, or delete it.`,
+      slot: verdict.slot,
+    });
+  }
+
+  const configPath = worldRoot === null ? null : `${worldRoot}${CONFIG_FILE}`;
+  const configFile = configPath === null ? null : graph.files.get(configPath) ?? null;
+  const literal = configFile ? configLiteral(ts, configFile.sourceFile) : null;
+  const environments = (literal ? stacksOf(ts, literal) : null) ?? [defaultEnvironment];
+  const services = [];
+  for (const environment of environments) {
+    let stack = null;
+    try { stack = readStack({ root: config.root, environment }); } catch { stack = null; }
+    for (const service of stack?.services ?? []) if (service.role !== 'service' && !services.some(known => known.name === service.name)) services.push({ ...service, environment });
+  }
+  const stackHint = `${STACKS_DIRECTORY}/${environments.join(', ')}`;
+  const statefulWhy = service => (STATEFUL_KINDS.has(service.kind) ? `a ${service.kind} holds data the app reads back` : service.persistent ? 'the stack gives it a persistent volume' : null);
+  const declared = configFile ? fakedByOf(ts, configFile.sourceFile, literal) : [];
+
+  for (const entry of declared) {
+    const service = services.find(candidate => candidate.name === entry.service);
+    const problems = [];
+    if (!service) problems.push(`${stackHint} declares no service ${entry.service}`);
+    else if (statefulWhy(service)) problems.push(`${service.name} is stateful (${statefulWhy(service)}) and always runs real`);
+    if (!fakeProviders.has(entry.fake)) problems.push(`there is no fakes/${entry.fake || '<fake>'}/ folder`);
+    if (entry.reason === '') problems.push('the reason is empty');
+    if (problems.length > 0) {
+      violations.push({
+        ruleId: RULE, path: configPath, line: entry.line, column: entry.column, slot: WORLD_SLOT,
+        message: `${configPath} declares ${entry.service} as faked by ${entry.fake || '(no fake)'}, but ${problems.join('; ')}. The exception covers only stateless compute that needs special hardware or an external model, with a reason; everything else in the stack runs real.`,
+      });
+    }
+  }
+
+  for (const [provider, file] of [...fakeProviders].sort(([a], [b]) => a.localeCompare(b))) {
+    const service = services.find(candidate => namesOfService(candidate).includes(provider));
+    if (!service) continue;
+    if (declared.some(entry => entry.service === service.name && entry.fake === provider)) continue; // judged on its config entry above
+    const why = statefulWhy(service);
+    violations.push({
+      ruleId: RULE, path: file, line: 1, column: 1, slot: WORLD_SLOT,
+      message: `fakes/${provider}/ fakes ${service.name} (${service.image}), which ${stackHint} declares: a service of the repository's own stack runs real in the test world. ${why ? `${service.name} is stateful (${why}), so no exception applies. ` : `Only stateless compute that needs special hardware or an external model may be faked, and only when ${configPath ?? `${CONFIG_FILE} in the world`} declares it in fakedBy with a reason. `}Delete the fake and let the world run the real service; fakes/ is otherwise only for external SaaS the team does not operate.`,
+    });
+  }
+  return { violations, coverage: { status: 'checked', files } };
+}

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

@@ -0,0 +1,130 @@
+/**
+ * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
+ *   1. the tier direction matrix: every import, re-export and type-only import between two owners must go from a tier to
+ *      a tier its `mayImport` lists (BE_TIER_DIRECTION / FE_TIER_DIRECTION); a backend feature importing another feature
+ *      is the one direction with its own code (BE_FEATURE_IMPORTS_FEATURE, R28), never BE_TIER_DIRECTION,
+ *      an app never imports another app (FE_APP_ISOLATION), and a component layer imports only the layers after it;
+ *   2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE),
+ *      reported with the cycle path and the import that closes each hop.
+ * Importing inside one owner is always allowed; the public-entry rule stays with owners.mjs (ARCH_OWNER_EXPORT_BYPASS).
+ */
+export const TIER_RULE_IDS = ['BE_TIER_DIRECTION', 'BE_FEATURE_IMPORTS_FEATURE', 'FE_TIER_DIRECTION', 'FE_APP_ISOLATION', 'ARCH_OWNER_CYCLE'];
+
+const REASON_TEXT = {
+  tierDirection: ({ fromTier, toTier, mayImport }) => `a ${fromTier} may import only ${mayImport.join(', ') || 'nothing'}; it imports a ${toTier}`,
+  layerOrder: ({ fromLayer, toLayer }) => `a ${fromLayer} component may import only the layers after it; it imports a ${toLayer}`,
+  crossApp: ({ from, to }) => `app ${from} imports app ${to}; apps never import each other, shared code is a packages/<pkg> slot`,
+};
+
+/** Strongly connected components (Tarjan, iterative) of `adjacency` (Map<node, Set<node>>); components of one node are dropped. */
+export function stronglyConnected(adjacency) {
+  let counter = 0;
+  const index = new Map();
+  const low = new Map();
+  const onStack = new Set();
+  const stack = [];
+  const result = [];
+  for (const start of adjacency.keys()) {
+    if (index.has(start)) continue;
+    const work = [{ node: start, iterator: adjacency.get(start)[Symbol.iterator]() }];
+    index.set(start, counter); low.set(start, counter); counter += 1; stack.push(start); onStack.add(start);
+    while (work.length) {
+      const frame = work.at(-1);
+      const next = frame.iterator.next();
+      if (!next.done) {
+        const target = next.value;
+        if (!adjacency.has(target)) continue;
+        if (!index.has(target)) {
+          index.set(target, counter); low.set(target, counter); counter += 1; stack.push(target); onStack.add(target);
+          work.push({ node: target, iterator: adjacency.get(target)[Symbol.iterator]() });
+        } else if (onStack.has(target)) low.set(frame.node, Math.min(low.get(frame.node), index.get(target)));
+        continue;
+      }
+      work.pop();
+      if (work.length) { const parent = work.at(-1).node; low.set(parent, Math.min(low.get(parent), low.get(frame.node))); }
+      if (low.get(frame.node) === index.get(frame.node)) {
+        const component = [];
+        let member;
+        do { member = stack.pop(); onStack.delete(member); component.push(member); } while (member !== frame.node);
+        if (component.length > 1) result.push(component);
+      }
+    }
+  }
+  return result;
+}
+
+/** A shortest cycle through `origin` inside `members`, as a node path that starts and ends at origin. */
+function cycleThrough(adjacency, members, origin) {
+  const queue = [[origin]];
+  const seen = new Set();
+  while (queue.length) {
+    const trail = queue.shift();
+    for (const next of adjacency.get(trail.at(-1)) ?? []) {
+      if (!members.has(next)) continue;
+      if (next === origin) return [...trail, origin];
+      if (seen.has(next)) continue;
+      seen.add(next);
+      queue.push([...trail, next]);
+    }
+  }
+  return [origin, origin];
+}
+
+export function checkTiers(graph) {
+  const { resolver, profile } = graph;
+  const violations = [];
+  const tierRule = profile === 'be' ? 'BE_TIER_DIRECTION' : 'FE_TIER_DIRECTION';
+  let edgesChecked = 0;
+  let unclassified = 0;
+  const counts = { tierDirection: 0, layerOrder: 0, crossApp: 0 };
+  for (const edge of graph.edges) {
+    const verdict = resolver.importAllowed(edge.from, edge.to);
+    if (verdict.reason === 'unowned' || verdict.reason?.startsWith('slot')) { unclassified += 1; continue; }
+    edgesChecked += 1;
+    if (verdict.allowed || !REASON_TEXT[verdict.reason]) continue;
+    counts[verdict.reason] += 1;
+    const featureToFeature = profile === 'be' && verdict.reason === 'tierDirection' && verdict.fromTier === 'feature' && verdict.toTier === 'feature';
+    violations.push({
+      ruleId: verdict.reason === 'crossApp' ? 'FE_APP_ISOLATION' : featureToFeature ? 'BE_FEATURE_IMPORTS_FEATURE' : tierRule,
+      path: edge.from, line: edge.line, column: edge.column,
+      specifier: edge.specifier, resolvedPath: edge.to, typeOnly: !edge.runtime,
+      fromTier: verdict.fromTier ?? null, toTier: verdict.toTier ?? null,
+      message: `${edge.from} -> ${edge.to}: ${REASON_TEXT[verdict.reason](verdict)}${edge.runtime ? '' : ' (type-only imports count)'}.`,
+    });
+  }
+
+  // Owner cycles: nodes are owner units, edges the imports between two distinct units.
+  const adjacency = new Map();
+  const witness = new Map();
+  for (const edge of graph.edges) {
+    const a = graph.unit(edge.from);
+    const b = graph.unit(edge.to);
+    if (!a || !b || a === b) continue;
+    if (resolver.tierOf(edge.from) === 'none' || resolver.tierOf(edge.to) === 'none') continue;
+    if (!adjacency.has(a)) adjacency.set(a, new Set());
+    if (!adjacency.has(b)) adjacency.set(b, new Set());
+    adjacency.get(a).add(b);
+    if (!witness.has(`${a}\0${b}`)) witness.set(`${a}\0${b}`, edge);
+  }
+  const components = stronglyConnected(adjacency);
+  for (const component of components) {
+    const members = new Set(component);
+    const origin = [...component].sort()[0];
+    const cycle = cycleThrough(adjacency, members, origin);
+    const hops = cycle.slice(0, -1).map((unit, i) => witness.get(`${unit}\0${cycle[i + 1]}`));
+    const label = unit => unit.slice(unit.indexOf(':') + 1) || unit;
+    const first = hops[0];
+    violations.push({
+      ruleId: 'ARCH_OWNER_CYCLE',
+      path: first.from, line: first.line, column: first.column,
+      cycle: cycle.map(label),
+      cycleImports: hops.map(hop => ({ path: hop.from, line: hop.line, specifier: hop.specifier, typeOnly: !hop.runtime })),
+      componentSize: component.length,
+      message: `Owner cycle: ${cycle.map(label).join(' -> ')}${component.length > cycle.length - 1 ? ` (strongly connected with ${component.length} owners)` : ''}; type-only imports count.`,
+    });
+  }
+  return {
+    violations,
+    coverage: { status: 'checked', edgesChecked, unclassifiedEdges: unclassified, ownerUnits: adjacency.size, cycles: components.length, ...counts },
+  };
+}

package/runtime/scripts/checks/architecture/transport-owner.mjs

@@ -0,0 +1,112 @@
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R50 `transport-owner` (FE_TRANSPORT_OWNER), the machine half of the eslint rules `fetch-only-in-api-client` and
+ * `client-fetch-has-signal`. ESLint judges one file at a time by the spelling of a call; the machine judges the repository by
+ * what the checker resolves. A repository has exactly ONE transport client and ONE Outcome union, both named by slot (never
+ * by a path spelled here): the api package's (`fe.package.api.client`, `fe.package.api.outcome`) when the repository shares
+ * it, or the only app's (`fe.transport.client`, `fe.transport.outcome`) when the repository declares exactly one app.
+ *
+ *   - two or more clients, or two or more Outcome unions, in the repository (two apps each keeping one, or a package one plus
+ *     an app one) are findings on every copy;
+ *   - an app client or app Outcome union in a repository that declares more than one app is a finding (it belongs to the package);
+ *   - the client calls the global `fetch` (a client that never calls it has its transport somewhere else);
+ *   - no other file references the global `fetch`: a call, `globalThis.fetch`, `window.fetch`, or a reference passed as a value
+ *     (`useSWR(key, fetch)`, `const send = fetch`), all of which a spelling-based rule misses; with no client at all every such
+ *     reference is a finding that says the repository has no client;
+ *   - no file imports an HTTP library, by static import, `import()` or `require()`;
+ *   - every server reader (`modules/api/<domain>/read-*.ts`) imports the client (or the api package that holds it), so a reader
+ *     is a caller of the one transport and not a second one.
+ */
+export const TRANSPORT_OWNER_RULE_IDS = ['FE_TRANSPORT_OWNER'];
+
+const RULE = 'FE_TRANSPORT_OWNER';
+/** Packages that send HTTP requests: a second transport when a file imports one. */
+const HTTP_LIBRARIES = new Set(['axios', 'ky', 'ky-universal', 'got', 'node-fetch', 'undici', 'cross-fetch', 'isomorphic-fetch', 'superagent', 'ofetch', 'whatwg-fetch']);
+const GLOBAL_OBJECTS = new Set(['globalThis', 'window', 'self', 'global']);
+const API_SLOT = 'fe.modules.api';
+const APP_CLIENT_SLOT = 'fe.transport.client';
+const APP_OUTCOME_SLOT = 'fe.transport.outcome';
+const PACKAGE_API_SLOT = 'fe.package.api';
+const CLIENT_SLOTS = new Set([APP_CLIENT_SLOT, 'fe.package.api.client']);
+const OUTCOME_SLOTS = new Set([APP_OUTCOME_SLOT, 'fe.package.api.outcome']);
+const NO_CLIENT = "the repository has no transport client. Create the one client (packages/<family>-api/src/client.ts, or the only app's modules/api/client.ts) and call it.";
+
+export function checkTransportOwner(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts, resolver } = kit;
+  const violations = [];
+  const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
+  const nextApps = resolver.repo.apps.filter(item => item.kind === 'next');
+  let readers = 0;
+
+  /** True when `node` names the global fetch: no import, and no declaration outside a lib declaration file. */
+  const isGlobalFetch = (checker, node) => {
+    if (ts.isIdentifier(node)) {
+      if (node.text !== 'fetch' || kit.importBinding(checker, node)) return false;
+      const parent = node.parent;
+      if (ts.isPropertyAccessExpression(parent) && parent.name === node) return false;
+      // A type position (`typeof fetch`, `typeof globalThis.fetch`) names the type of fetch and sends nothing.
+      if (ts.isTypeQueryNode(parent) || ts.isQualifiedName(parent)) return false;
+      if ((ts.isPropertyAssignment(parent) || ts.isPropertyDeclaration(parent) || ts.isMethodDeclaration(parent) || ts.isBindingElement(parent) || ts.isParameter(parent) || ts.isVariableDeclaration(parent)) && parent.name === node) return false;
+      if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent) || ts.isPropertySignature(parent)) return false;
+      const declarations = kit.declarationsOf(checker, node);
+      return declarations.every(declaration => declaration.getSourceFile().isDeclarationFile);
+    }
+    return ts.isPropertyAccessExpression(node) && node.name.text === 'fetch' && ts.isIdentifier(node.expression) && GLOBAL_OBJECTS.has(node.expression.text);
+  };
+
+  const files = [...graph.files.values()].filter(file => file.slot && file.tier !== 'e2e');
+  const clients = files.filter(file => CLIENT_SLOTS.has(file.slot));
+  const outcomes = files.filter(file => OUTCOME_SLOTS.has(file.slot));
+  const clientRels = new Set(clients.map(file => file.rel));
+  const list = items => items.map(item => item.rel).join(', ');
+  const owned = clients.length ? `the repository has one transport (${list(clients)}). Call the client and take its Outcome.` : NO_CLIENT;
+
+  // Exactly one client and one Outcome union per repository.
+  for (const [items, noun] of [[clients, 'transport client'], [outcomes, 'Outcome union']]) {
+    for (const file of items) {
+      if (items.length > 1) report(file, file.sourceFile, `The repository has ${items.length} ${noun}s (${list(items)}); it has exactly one: the api package's (packages/<family>-api/src/) when the apps share it, or the only app's. Keep one and delete the others.`);
+      else if ((file.slot === APP_CLIENT_SLOT || file.slot === APP_OUTCOME_SLOT) && nextApps.length > 1) {
+        report(file, file.sourceFile, `${file.rel} is an app's ${noun} in a repository of ${nextApps.length} apps; a repository with several apps keeps its one ${noun} in the api package (packages/<family>-api/src/).`);
+      }
+    }
+  }
+
+  const appsWithFiles = new Set();
+  for (const file of files) {
+    const bindings = resolver.classifyPath(file.rel).bindings;
+    if (bindings?.app) appsWithFiles.add(bindings.app);
+    const checker = kit.checkerOf(file.sourceFile);
+    const isClient = clientRels.has(file.rel);
+    let clientCalls = 0;
+    kit.walk(file.sourceFile, node => {
+      if (ts.isPropertyAccessExpression(node) && isGlobalFetch(checker, node)) {
+        if (isClient) clientCalls += 1;
+        else report(file, node, `${node.getText(file.sourceFile)} reaches the global fetch outside the transport client; ${owned}`);
+        return false;
+      }
+      if (ts.isIdentifier(node) && isGlobalFetch(checker, node)) {
+        if (isClient) clientCalls += 1;
+        else report(file, node, `fetch is used outside the transport client (called, aliased or passed as a value); ${owned}`);
+        return false;
+      }
+      const specifier = ts.isImportDeclaration(node) || ts.isExportDeclaration(node) ? node.moduleSpecifier
+        : ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === 'require')) ? node.arguments[0] : null;
+      if (specifier && ts.isStringLiteralLike(specifier) && HTTP_LIBRARIES.has(specifier.text.split('/')[0])) {
+        report(file, node, `${specifier.text} is a second HTTP transport; the repository's one transport is built on fetch (${clients.length ? list(clients) : 'no client exists yet'}). Use the client.`, { library: specifier.text });
+      }
+      return true;
+    });
+    if (isClient && clientCalls === 0) report(file, file.sourceFile, `${file.rel} never calls the global fetch; the client is the one module that owns fetch, with its timeout and abort signal.`);
+    if (file.slot === API_SLOT && bindings?.app && path.posix.basename(file.rel).startsWith('read-')) {
+      readers += 1;
+      const reachesClient = graph.edges.some(edge => edge.from === file.rel && edge.runtime
+        && (clientRels.has(edge.to) || graph.files.get(edge.to)?.slot === PACKAGE_API_SLOT));
+      if (!reachesClient) report(file, file.sourceFile, `${file.rel} is a server reader that does not import the transport client; a reader fetches through the repository's one client, never through its own transport.`);
+    }
+  }
+  return { violations, coverage: { status: 'checked', apps: appsWithFiles.size, readers, clients: clients.length, outcomes: outcomes.length } };
+}