@starci/hfs 4.0.7 → 4.0.9

package/runtime/scripts/hfs/architecture/context-coupling.mjs

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { contextModelOf } from './context-map.mjs';
+import { machineKit } from './machine-ast.mjs';
+import { entitiesOf } from './sql-owner.mjs';
+
+/**
+ * R175 `context-coupling` (BE_CONTEXT_COUPLING). Bounded contexts are coupled by events only, never by their schema or their code:
+ *   - an entity relation (`OneToOne`, `OneToMany`, `ManyToOne`, `ManyToMany` imported from typeorm) whose target class is an entity of a capability
+ *     of another context is refused;
+ *   - a migration foreign key (`REFERENCES <table>` in a string of a migration file) onto a table whose entity belongs to another context is refused;
+ *   - a domain or projection file imports no file of a capability of another context (its entities, services or SQL).
+ * A capability's context is the connection its persistence arrays are registered on (context-map.mjs). A file or table with no proven context
+ * (a platform capability, a capability registered nowhere) is never judged, and the table of a foreign key is looked up through the entities the
+ * program declares, never guessed from a name.
+ */
+export const CONTEXT_COUPLING_RULE_IDS = ['BE_CONTEXT_COUPLING'];
+
+const RULE = 'BE_CONTEXT_COUPLING';
+const TYPEORM = 'typeorm';
+const RELATIONS = new Set(['OneToOne', 'OneToMany', 'ManyToOne', 'ManyToMany']);
+// The table identifier after the SQL keyword REFERENCES, optionally schema-qualified and quoted.
+const REFERENCES = /\bREFERENCES\s+(?:"?[A-Za-z0-9_]+"?\s*\.\s*)?"?([A-Za-z0-9_]+)"?/giu;
+
+export function checkContextCoupling(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts, resolver } = kit;
+  const model = contextModelOf(kit, graph);
+  const { tables } = entitiesOf(kit, graph);
+  const violations = [];
+  const seen = new Set();
+  const once = (key, violation) => { if (!seen.has(key)) { seen.add(key); violations.push({ ruleId: RULE, ...violation }); } };
+  const counts = { relations: 0, foreignKeys: 0, imports: 0 };
+  const covered = new Set(); // `${fromRel}|${targetRoot}` pairs a relation already reported, so the import edge is not a second finding
+
+  for (const file of graph.files.values()) {
+    if (file.slot !== 'be.persistence' || !file.owner) continue;
+    const base = path.posix.basename(file.rel);
+    const ownContext = model.contextOfCapability(file.owner.root);
+    if (!ownContext) continue;
+    const checker = kit.checkerOf(file.sourceFile);
+    if (base.endsWith('.entity.ts')) {
+      kit.walk(file.sourceFile, node => {
+        if (!ts.isDecorator(node) || !ts.isCallExpression(node.expression)) return true;
+        const binding = kit.importBinding(checker, node.expression.expression);
+        if (binding?.module !== TYPEORM || !RELATIONS.has(binding.name)) return true;
+        counts.relations += 1;
+        const argument = node.expression.arguments[0];
+        const target = argument && (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument)) && !ts.isBlock(argument.body) ? model.unparen(argument.body) : null;
+        if (!target || !(ts.isIdentifier(target) || ts.isPropertyAccessExpression(target))) return true;
+        const home = kit.declarationsOf(checker, ts.isPropertyAccessExpression(target) ? target.name : target).map(kit.ownerOfDeclaration).find(Boolean);
+        const targetContext = home ? model.contextOfCapability(home.root) : null;
+        if (!home || !targetContext || targetContext === ownContext) return true;
+        covered.add(`${file.rel}|${home.root}`);
+        once(`${file.rel}|${node.getStart()}`, { ...kit.at(file.rel, file.sourceFile, node), message: `A ${binding.name} relation in ${file.owner.root} (context ${ownContext}) targets an entity of ${home.root} (context ${targetContext}); a relation never crosses a context. Keep the other context's id as a plain column and fill a local copy or a projection from its events.`, context: ownContext, targetContext });
+        return true;
+      });
+    }
+    if (file.rel.slice(file.owner.root.length + 1).startsWith('persistence/migrations/')) {
+      kit.walk(file.sourceFile, node => {
+        if (!(ts.isStringLiteralLike(node) || ts.isTemplateExpression(node))) return true;
+        const text = ts.isTemplateExpression(node) ? node.head.text + node.templateSpans.map(span => ` ${span.literal.text}`).join('') : node.text;
+        for (const match of text.matchAll(REFERENCES)) {
+          counts.foreignKeys += 1;
+          const entity = tables.get(match[1].toLowerCase());
+          const targetContext = entity ? model.contextOfCapability(entity.owner) : null;
+          if (!entity || !targetContext || targetContext === ownContext) continue;
+          once(`${file.rel}|${node.getStart()}|${match[1]}`, { ...kit.at(file.rel, file.sourceFile, node), message: `A foreign key in ${file.rel} references table ${entity.table} of ${entity.owner} (context ${targetContext}), but this migration belongs to context ${ownContext}; a foreign key never crosses a context. Keep the id as a plain column and validate it through the other context's API or a local copy fed by its events.`, context: ownContext, targetContext, table: entity.table });
+        }
+        return true;
+      });
+    }
+  }
+
+  for (const edge of graph.edges) {
+    const from = graph.files.get(edge.from);
+    const to = graph.files.get(edge.to);
+    if (!from?.owner || !to?.owner || from.owner.root === to.owner.root) continue;
+    const fromContext = model.contextOfFile(edge.from);
+    const toContext = model.contextOfFile(edge.to);
+    if (!fromContext || !toContext || fromContext === toContext) continue;
+    counts.imports += 1;
+    if (covered.has(`${edge.from}|${to.owner.root}`)) continue;
+    once(`${edge.from}|${edge.to}|${edge.line}`, { path: edge.from, line: edge.line, column: edge.column, message: `${from.owner.root} (context ${fromContext}) imports ${to.owner.root} (context ${toContext}); a context never imports another context's entities, services or SQL. Keep a local copy fed by its events, or read a projection.`, context: fromContext, targetContext: toContext });
+  }
+  void resolver;
+  return { violations, coverage: { status: 'checked', ...counts } };
+}

package/runtime/scripts/hfs/architecture/context-map.mjs

@@ -0,0 +1,237 @@
+import path from 'node:path';
+import { pascal } from './machine-ast.mjs';
+import { DATABASE_DIR } from './connection-map.mjs';
+
+const camel = name => { const text = pascal(name); return text[0].toLowerCase() + text.slice(1); };
+
+/**
+ * Where the persistence arrays of every capability are registered: the object literals (`DatabaseModule.register` connections and the
+ * migrate/cli app's) that list `<c>Entities` / `<c>Migrations` of a capability's `persistence/connection.ts` under a connection `name`.
+ * The one walk BE_SCHEMA_OWNER and the bounded-context rules (R174 to R178) share, so a capability's context is decided once, by origin.
+ *
+ * @param {{kit: object, graph: object, persistenceOf: (rel: string) => ({root: string, capability: string, folder: string, below: string[]} | null)}} input
+ * @returns {{registered: Map<string, {name: string, connections: Map<string, {file: object, node: object}>}>, registrations: number, all: Array<{file: object, node: object, connection: string | null}>}}
+ *   `registered`: capability root -> its name and the connections it is registered on (first site each).
+ */
+export function collectRegistrations({ kit, graph, persistenceOf }) {
+  const { ts } = kit;
+  const unparen = node => { let current = node; while (current && (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression?.(current) || ts.isNonNullExpression(current))) current = current.expression; return current; };
+  const returned = declaration => {
+    const fn = ts.isVariableDeclaration(declaration) && declaration.initializer ? unparen(declaration.initializer) : declaration;
+    if (!(ts.isArrowFunction(fn) || ts.isFunctionDeclaration(fn) || ts.isFunctionExpression(fn) || ts.isMethodDeclaration(fn)) || !fn.body) return null;
+    if (!ts.isBlock(fn.body)) return fn.body;
+    const statements = fn.body.statements.filter(ts.isReturnStatement);
+    return statements.length === 1 ? statements[0].expression ?? null : null;
+  };
+  const propertySources = new Map(); // property name -> [{declaration, initializer, checker}] over the program
+  const assignmentsOf = name => {
+    if (propertySources.has(name)) return propertySources.get(name);
+    const list = [];
+    for (const file of graph.files.values()) {
+      if (!file.sourceFile.text.includes(name)) continue;
+      const checker = kit.checkerOf(file.sourceFile);
+      kit.walk(file.sourceFile, node => {
+        if (ts.isPropertyAssignment(node) && kit.propertyNameText(node.name) === name && ts.isObjectLiteralExpression(node.parent)) {
+          // the property of the type the literal is checked against, so a typed const and a typed return meet the same declaration
+          const contextual = checker.getContextualType(node.parent)?.getProperty(name);
+          const symbol = contextual ?? checker.getSymbolAtLocation(node.name);
+          list.push({ declaration: symbol?.declarations?.[0] ?? null, initializer: node.initializer, checker });
+        }
+        return true;
+      });
+    }
+    propertySources.set(name, list);
+    return list;
+  };
+  const nameOfLiteral = (checker, literal, depth) => {
+    const own = kit.propertyOf(literal, 'name');
+    if (own) return kit.stringValue(checker, kit.valueOfProperty(own));
+    for (const property of literal.properties) {
+      if (!ts.isSpreadAssignment(property)) continue;
+      const value = nameOfExpression(checker, property.expression, depth + 1);
+      if (value) return value;
+    }
+    return null;
+  };
+  const nameOfExpression = (checker, expression, depth) => {
+    const node = unparen(expression);
+    if (!node || depth > 5) return null;
+    if (ts.isObjectLiteralExpression(node)) return nameOfLiteral(checker, node, depth);
+    if (ts.isCallExpression(node)) {
+      for (const declaration of kit.declarationsOf(checker, node.expression)) {
+        const body = returned(declaration);
+        const value = body ? nameOfExpression(kit.checkerOf(declaration.getSourceFile()), body, depth + 1) : null;
+        if (value) return value;
+      }
+      return null;
+    }
+    if (ts.isIdentifier(node)) {
+      const declaration = kit.declarationsOf(checker, node)[0];
+      return declaration && ts.isVariableDeclaration(declaration) && declaration.initializer ? nameOfExpression(kit.checkerOf(declaration.getSourceFile()), declaration.initializer, depth + 1) : null;
+    }
+    if (ts.isPropertyAccessExpression(node)) {
+      const target = kit.declarationsOf(checker, node.name)[0];
+      if (!target) return null;
+      const names = new Set(assignmentsOf(node.name.text).filter(item => item.declaration === target).map(item => nameOfExpression(item.checker, item.initializer, depth + 1)).filter(Boolean));
+      return names.size === 1 ? [...names][0] : null;
+    }
+    return null;
+  };
+  /** The capability arrays (`<c>Entities` / `<c>Migrations` of persistence/connection.ts) an expression lists. */
+  const arraysIn = (checker, expression, out, depth) => {
+    const node = unparen(expression);
+    if (!node || depth > 6) return;
+    if (ts.isArrayLiteralExpression(node)) { for (const element of node.elements) arraysIn(checker, ts.isSpreadElement(element) ? element.expression : element, out, depth + 1); return; }
+    if (!ts.isIdentifier(node) && !ts.isPropertyAccessExpression(node)) return;
+    const declaration = kit.declarationsOf(checker, ts.isPropertyAccessExpression(node) ? node.name : node)[0];
+    if (!declaration || !ts.isVariableDeclaration(declaration) || !ts.isIdentifier(declaration.name)) return;
+    const rel = kit.graphPath(declaration);
+    const owner = rel ? persistenceOf(rel) : null;
+    if (owner && owner.below.length === 1 && owner.below[0] === 'connection.ts' && [`${camel(owner.capability)}Entities`, `${camel(owner.capability)}Migrations`].includes(declaration.name.text)) {
+      out.push({ key: path.posix.dirname(owner.root), name: owner.capability });
+    } else if (declaration.initializer) arraysIn(kit.checkerOf(declaration.getSourceFile()), declaration.initializer, out, depth + 1);
+  };
+  const all = []; // every registration literal: {file, node, connection | null when the name cannot be resolved}
+  const registered = new Map(); // capability root -> {name, connections: Map(connection -> first site)}
+  let registrations = 0;
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!ts.isObjectLiteralExpression(node)) return true;
+      const arrays = [];
+      for (const key of ['entities', 'migrations']) {
+        const property = kit.propertyOf(node, key);
+        if (property) arraysIn(checker, kit.valueOfProperty(property), arrays, 0);
+      }
+      if (!arrays.length) return true;
+      registrations += 1;
+      const connection = nameOfLiteral(checker, node, 0);
+      all.push({ file, node, connection });
+      if (connection === null) return true;
+      for (const { key, name } of new Map(arrays.map(item => [item.key, item])).values()) {
+        if (!registered.has(key)) registered.set(key, { name, connections: new Map() });
+        const sites = registered.get(key).connections;
+        if (!sites.has(connection)) sites.set(connection, { file, node });
+      }
+      return true;
+    });
+  }
+  return { registered, registrations, all };
+}
+
+const PERSISTENCE_SLOT = 'be.persistence';
+/** The slot tiers whose capabilities belong to a bounded context: the domain and the projections (a projection is owned by the context whose connection holds its tables). */
+const CONTEXT_TIERS = new Set(['domain', 'projections']);
+
+/** True for a platform capability the manifest lists as `perConnection` (its tables exist on every connection that uses it); `root` is the capability root. */
+export const isPerConnection = (resolver, root, name) => root.split('/').includes('platform') && (resolver.slot(PERSISTENCE_SLOT)?.perConnection ?? []).includes(name);
+
+/**
+ * `persistenceOf(rel)`: {root, capability, folder, below} of a be.persistence file (`folder` the directory below persistence/, '' at its root),
+ * null for any other file. `root` is the persistence root, its dirname the capability root.
+ */
+export const persistenceOfFactory = resolver => rel => {
+  const classified = resolver.classifyPath(rel);
+  if (classified.slot !== PERSISTENCE_SLOT) return null;
+  const below = rel.slice(classified.root.length + 1).split('/');
+  return { root: classified.root, capability: path.posix.basename(path.posix.dirname(classified.root)), folder: below.length > 1 ? below[0] : '', below };
+};
+
+/**
+ * The bounded-context model of a program: which context (declared connection) each capability belongs to, and which connection an expression's
+ * entity manager is. A context is a connection; a capability belongs to the one declared connection its persistence arrays are registered on
+ * (collectRegistrations), a platform capability named by the manifest's `perConnection` list to none (it is infrastructure on every connection).
+ * Everything is decided by declarations and origins: the registration literal, the `Inject<Conn>EntityManager` decorator's home file, the
+ * transaction callback parameter's receiver. Nothing is matched by a variable name.
+ */
+const MODELS = new WeakMap();
+
+export function contextModelOf(kit, graph) {
+  if (MODELS.has(graph)) return MODELS.get(graph);
+  const { ts, resolver } = kit;
+  const persistenceOf = persistenceOfFactory(resolver);
+  const declared = new Map(resolver.repo.connections.map(connection => [connection.name, connection]));
+  const { registered, all } = collectRegistrations({ kit, graph, persistenceOf });
+  const perConnection = new Set();
+  const contextOfRoot = new Map(); // capability root -> declared connection name (single registration only)
+  for (const [root, { name, connections }] of registered) {
+    if (isPerConnection(resolver, root, name)) { perConnection.add(root); continue; }
+    const names = [...connections.keys()].filter(connection => declared.has(connection));
+    if (names.length === 1) contextOfRoot.set(root, names[0]);
+  }
+  /** The declared connection a capability root belongs to, or null (no registration, several, or a per-connection platform capability). */
+  const contextOfCapability = root => contextOfRoot.get(root) ?? null;
+  /** The context of the capability owning `rel` when that capability is of a context tier (domain, projections), else null: only these are bounded contexts. */
+  const contextOfFile = rel => {
+    const file = graph.files.get(rel);
+    if (!file?.owner || !CONTEXT_TIERS.has(file.tier)) return null;
+    return contextOfCapability(file.owner.root);
+  };
+  const unparen = node => { let current = node; while (current && (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current))) current = current.expression; return current; };
+  /** The declared connection named by a decorator whose callee is declared in src/modules/platform/database/<conn>.decorators.ts, else null. */
+  const connectionOfDecorators = (checker, declaration) => {
+    for (const decorator of kit.decorators(declaration)) {
+      const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+      for (const target of kit.declarationsOf(checker, callee)) {
+        const rel = kit.graphPath(target);
+        const name = rel ? [...declared.keys()].find(connection => rel === `${DATABASE_DIR}/${connection}.decorators.ts`) : null;
+        if (name) return name;
+      }
+    }
+    return null;
+  };
+  /**
+   * The declared connection whose entity manager `expression` is: a property or parameter injected with `Inject<Conn>EntityManager`, or the
+   * manager parameter of the callback of a `.transaction(...)` on such a manager. Null when the origin cannot be proven (never guessed).
+   */
+  const connectionOfManager = (checker, expression, depth = 0) => {
+    const node = unparen(expression);
+    if (!node || depth > 4) return null;
+    const target = ts.isPropertyAccessExpression(node) ? node.name : (ts.isIdentifier(node) ? node : null);
+    if (!target) return null;
+    const declaration = kit.declarationsOf(checker, target)[0];
+    if (!declaration) return null;
+    if (ts.isPropertyDeclaration(declaration) || ts.isParameter(declaration)) {
+      const direct = connectionOfDecorators(checker, declaration);
+      if (direct) return direct;
+    }
+    if (ts.isParameter(declaration) && (ts.isArrowFunction(declaration.parent) || ts.isFunctionExpression(declaration.parent)) && declaration.parent.parameters[0] === declaration) {
+      const call = declaration.parent.parent;
+      if (ts.isCallExpression(call) && call.arguments.includes(declaration.parent) && ts.isPropertyAccessExpression(call.expression) && call.expression.name.text === 'transaction') {
+        return connectionOfManager(checker, call.expression.expression, depth + 1);
+      }
+    }
+    return null;
+  };
+  const model = { declared, registered, registrations: all, perConnection, contextOfCapability, contextOfFile, connectionOfManager, unparen };
+  MODELS.set(graph, model);
+  return model;
+}
+
+/** The declared connection names the composition root of `app` passes to the database module registration, as [{connection, node}] in source order. */
+export function connectionsComposedBy(kit, app) {
+  const { ts } = kit;
+  const root = kit.appRoot(app);
+  if (!root) return { root: null, items: [] };
+  const declared = new Set(kit.resolver.repo.connections.map(connection => connection.name));
+  const checker = kit.checkerOf(root.sourceFile);
+  const items = [];
+  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;
+    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 || !declared.has(value)) return true;
+        items.push({ connection: value, node: inner });
+        return false;
+      });
+    }
+    return true;
+  });
+  return { root, items };
+}

package/runtime/scripts/hfs/architecture/context-owner.mjs

@@ -0,0 +1,82 @@
+import { contextModelOf, connectionsComposedBy } from './context-map.mjs';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R174 `context-owner` (BE_CONTEXT_OWNER). A connection of hfs.json IS a bounded context, and its `owner` is the one service app that composes it:
+ *   - an api or worker app passes to the database module registration (or lists in its options) only the connections it owns (a monolith's one
+ *     app owns them all);
+ *   - an api or worker app imports no domain or projection capability of a context it does not own: it composes only its own contexts;
+ *   - the cli app is the migration runner and composes every declared connection
+ *     that holds registered tables (migrations run only through it, once per connection).
+ * Which connection an app composes is read from two typed origins in its own files: the connection passed to the database module registration
+ * and the connection literal that lists a capability's `<c>Entities` / `<c>Migrations`. Which context a capability belongs to is the connection
+ * its arrays are registered on (context-map.mjs); an import is judged by the owner graph edge and the target's slot tier, never by a path or
+ * name pattern. A runner app with a registration whose connection name cannot be resolved is not judged for missing connections.
+ */
+export const CONTEXT_OWNER_RULE_IDS = ['BE_CONTEXT_OWNER'];
+
+const RULE = 'BE_CONTEXT_OWNER';
+const SERVICE_KINDS = new Set(['api', 'worker']);
+const RUNNER_KINDS = new Set(['migrate', 'cli']);
+
+export function checkContextOwner(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { resolver } = kit;
+  const model = contextModelOf(kit, graph);
+  const violations = [];
+  const owners = new Map(resolver.repo.connections.map(connection => [connection.name, connection.owner]));
+  let compositions = 0;
+  let imports = 0;
+  const seen = new Set();
+  const once = (key, violation) => { if (!seen.has(key)) { seen.add(key); violations.push({ ruleId: RULE, ...violation }); } };
+  const appOf = rel => { const classified = resolver.classifyPath(rel); return classified.slot?.startsWith('be.app.') ? classified.bindings?.app ?? null : null; };
+
+  // What each app composes: [{connection, file, node}] from the database module registration and from the registration literals under its files.
+  const composed = new Map(resolver.repo.apps.map(app => [app.name, { items: [], unresolved: false }]));
+  for (const app of resolver.repo.apps) {
+    const { root, items } = connectionsComposedBy(kit, app.name);
+    for (const item of items) composed.get(app.name).items.push({ ...item, file: root });
+  }
+  for (const site of model.registrations) {
+    const app = appOf(site.file.rel);
+    if (!app || !composed.has(app)) continue;
+    if (site.connection === null) composed.get(app).unresolved = true;
+    else composed.get(app).items.push({ connection: site.connection, file: site.file, node: site.node });
+  }
+
+  for (const app of resolver.repo.apps) {
+    const { items, unresolved } = composed.get(app.name);
+    compositions += items.length;
+    if (SERVICE_KINDS.has(app.kind)) {
+      for (const { connection, file, node } of items) {
+        const owner = owners.get(connection);
+        if (owner && owner !== app.name) {
+          once(`${app.name}|${connection}`, { ...kit.at(file.rel, file.sourceFile, node), message: `App ${app.name} composes connection ${connection}, the context owned by app ${owner}; an app composes only the contexts it owns. Reach that context through the API or the events of ${owner}.`, connection, app: app.name, owner });
+        }
+      }
+    } else if (RUNNER_KINDS.has(app.kind) && !unresolved) {
+      const root = kit.appRoot(app.name);
+      const present = new Set(items.map(item => item.connection));
+      const held = new Set([...model.registered.values()].flatMap(entry => [...entry.connections.keys()]));
+      for (const connection of owners.keys()) {
+        if (!root || present.has(connection) || !held.has(connection) || !items.length) continue;
+        once(`${app.name}|missing|${connection}`, { ...kit.at(root.rel, root.sourceFile, root.sourceFile), message: `The ${app.kind} app ${app.name} does not compose connection ${connection}; migrations run only through it, once per connection, so it registers every declared connection that holds tables.`, connection, app: app.name });
+      }
+    }
+  }
+
+  const kinds = new Map(resolver.repo.apps.map(app => [app.name, app.kind]));
+  for (const edge of graph.edges) {
+    const app = appOf(edge.from);
+    if (!app || !SERVICE_KINDS.has(kinds.get(app))) continue;
+    const context = model.contextOfFile(edge.to);
+    if (!context) continue;
+    imports += 1;
+    const owner = owners.get(context);
+    if (owner && owner !== app) {
+      once(`${edge.from}|${edge.to}`, { path: edge.from, line: edge.line, column: edge.column, message: `App ${app} imports ${graph.files.get(edge.to).owner.root}, a capability of context ${context} owned by app ${owner}; an app composes only the contexts it owns, so use the API or the events of ${owner} instead.`, connection: context, app, owner });
+    }
+  }
+  return { violations, coverage: { status: 'checked', apps: resolver.repo.apps.length, compositions, contextImports: imports } };
+}

package/runtime/scripts/hfs/architecture/context-platform-tables.mjs

@@ -0,0 +1,47 @@
+import { contextModelOf } from './context-map.mjs';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R178 `context-platform-tables` (BE_CONTEXT_PLATFORM_TABLES). A platform capability the manifest lists as `perConnection` (the event-bus outbox,
+ * the job table) keeps its tables on EVERY connection that uses it: when a call into the capability passes the entity manager of connection C
+ * (an `Inject<C>EntityManager` property, or the manager of a transaction on one), the capability's `<c>Entities` and `<c>Migrations` must be
+ * registered on C, or the row the call writes has no table in C's database. The caller's connection is proven by the manager's origin; a call
+ * whose manager origin cannot be proven is not judged.
+ */
+export const CONTEXT_PLATFORM_TABLES_RULE_IDS = ['BE_CONTEXT_PLATFORM_TABLES'];
+
+const RULE = 'BE_CONTEXT_PLATFORM_TABLES';
+
+export function checkContextPlatformTables(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const model = contextModelOf(kit, graph);
+  const violations = [];
+  let calls = 0;
+  let unproven = 0;
+  if (!model.perConnection.size) return { violations, coverage: { status: 'checked', perConnectionCapabilities: 0, calls, unproven } };
+  const seen = new Set();
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!ts.isCallExpression(node)) return true;
+      const callee = ts.isPropertyAccessExpression(node.expression) ? node.expression.name : node.expression;
+      const home = kit.declarationsOf(checker, callee).map(kit.ownerOfDeclaration).find(Boolean);
+      if (!home || !model.perConnection.has(home.root) || file.owner?.root === home.root) return true;
+      calls += 1;
+      const connections = new Set(node.arguments.map(argument => model.connectionOfManager(checker, argument)).filter(Boolean));
+      if (!connections.size) { unproven += 1; return true; }
+      const registeredOn = model.registered.get(home.root)?.connections ?? new Map();
+      for (const connection of connections) {
+        if (registeredOn.has(connection)) continue;
+        const key = `${file.rel}|${node.getStart()}|${connection}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        violations.push({ ruleId: RULE, ...kit.at(file.rel, file.sourceFile, node), message: `${file.rel} passes the entity manager of connection ${connection} to ${home.name}, but the tables of ${home.name} are not registered on ${connection} (registered: ${[...registeredOn.keys()].sort().join(', ') || 'none'}); register its entities and migrations on ${connection} too, so the table exists in the database of that context.`, connection, capability: home.name });
+      }
+      return true;
+    });
+  }
+  return { violations, coverage: { status: 'checked', perConnectionCapabilities: model.perConnection.size, calls, unproven } };
+}

package/runtime/scripts/hfs/architecture/context-transaction.mjs

@@ -0,0 +1,60 @@
+import { contextModelOf } from './context-map.mjs';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R176 `context-transaction` (BE_CONTEXT_TRANSACTION). One transaction touches one context's connection. In the callback of
+ * `<manager>.transaction(async (manager) => ...)`, where `<manager>` is proven to be the entity manager of connection C (an
+ * `Inject<C>EntityManager` property or parameter), the code never:
+ *   - uses the entity manager of another declared connection (proven by its injector's home file); or
+ *   - calls a method of a domain or projection capability of another context (that capability writes through its own connection).
+ * Work that spans contexts is a saga of one transaction per context, linked by events. A receiver whose connection cannot be proven is not judged.
+ */
+export const CONTEXT_TRANSACTION_RULE_IDS = ['BE_CONTEXT_TRANSACTION'];
+
+const RULE = 'BE_CONTEXT_TRANSACTION';
+
+export function checkContextTransaction(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const model = contextModelOf(kit, graph);
+  const violations = [];
+  let transactions = 0;
+  let unproven = 0;
+  const seen = new Set();
+  const report = (file, node, message, extra) => {
+    const key = `${file.rel}|${node.getStart()}|${message}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    violations.push({ ruleId: RULE, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
+  };
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'transaction')) return true;
+      const callback = node.arguments.find(argument => ts.isArrowFunction(argument) || ts.isFunctionExpression(argument));
+      if (!callback) return true;
+      const connection = model.connectionOfManager(checker, node.expression.expression);
+      if (!connection) { unproven += 1; return true; }
+      transactions += 1;
+      kit.walk(callback.body, inner => {
+        if (ts.isPropertyAccessExpression(inner)) {
+          const other = model.connectionOfManager(checker, inner);
+          if (other && other !== connection) report(file, inner, `A transaction on connection ${connection} uses the entity manager of connection ${other}; one transaction touches one context's connection. Span contexts with a saga: one transaction per context, linked by events.`, { connection, other });
+        }
+        if (ts.isCallExpression(inner)) {
+          const callee = ts.isPropertyAccessExpression(inner.expression) ? inner.expression.name : inner.expression;
+          const declaration = kit.declarationsOf(checker, callee)[0];
+          const rel = declaration ? kit.graphPath(declaration) : null;
+          const context = rel ? model.contextOfFile(rel) : null;
+          if (context && context !== connection) {
+            report(file, inner, `A transaction on connection ${connection} calls ${graph.files.get(rel).owner.root} of context ${context}; one transaction touches one context's connection. Span contexts with a saga: one transaction per context, linked by events.`, { connection, other: context });
+          }
+        }
+        return true;
+      });
+      return true;
+    });
+  }
+  return { violations, coverage: { status: 'checked', transactions, unproven } };
+}

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

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { treeOf } from './required-files.mjs';
-import { allowsFile } from '../../lib/hfs-allows.mjs';
+import { checkerScope } from './required-files.mjs';
+import { allowsFile } from '../allows.mjs';
+import { unwrapEach } from './ast-walks.mjs';
 
 /**
  * R47 `contract-fixture-guard` (BE_CONTRACT_UNGUARDED). A fake at the network edge serves payload fixtures; a fixture drifts
@@ -28,11 +29,7 @@ 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;
-};
+const unwrap = (ts, node) => unwrapEach(ts, node, [ts.isParenthesizedExpression, ts.isAsExpression, ts.isNonNullExpression, ts.isAwaitExpression]);
 
 /** Every node under `root`, itself included. */
 function walk(ts, root, visit) {
@@ -79,11 +76,8 @@ function readSpec(ts, sourceFile, helper, providers) {
 }
 
 export function checkContractFixtureGuard(input) {
-  const { config, graph, context } = input;
-  const ts = context.ts;
-  const resolver = graph.resolver;
+  const { config, graph, ts, resolver, tree } = checkerScope(input);
   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]