@starci/hfs 4.0.7 → 4.0.9

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

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { canonical } from './config.mjs';
-import { isUnshadowedCommonJsRequire, referencedExports, relativePath, sourceLocation, unwrapExpression } from './typescript.mjs';
+import { referencedExports, relativePath, unwrapExpression } from './typescript.mjs';
+import { commonJsRequireReasons, decoratorCallee, moduleExportsOf, mutableDecoratorKind, normalizedSymbol, normalizedSymbolValue, programSourcesOf, selectedNode, valueSymbol } from './ast-walks.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 
 const REGISTRATION_RULE_IDS = ['BE_MODULE_HANDLER_REGISTRATION', 'BE_MODULE_PROVIDER_REREGISTRATION'];
 const FRAMEWORK = new Map([
@@ -9,106 +11,46 @@ const FRAMEWORK = new Map([
   ['QueryHandler', '@nestjs/cqrs'],
 ]);
 
-function normalizedSymbolValue(ts, checker, value) {
-  let symbol = value ?? null;
-  const seen = new Set();
-  while (symbol && (symbol.flags & ts.SymbolFlags.Alias) && !seen.has(symbol)) {
-    seen.add(symbol);
-    const target = checker.getAliasedSymbol(symbol);
-    if (!target || target === symbol) break;
-    symbol = target;
-  }
-  return symbol;
-}
-
-function normalizedSymbol(ts, checker, node) {
-  return normalizedSymbolValue(ts, checker, checker?.getSymbolAtLocation(node) ?? null);
-}
-
-function valueSymbol(ts, checker, node, seen = new Set()) {
-  const selected = selectedNode(ts, node) ?? node;
-  const symbol = normalizedSymbol(ts, checker, selected);
-  if (!symbol || seen.has(symbol)) return symbol;
-  seen.add(symbol);
-  const declarations = symbol.getDeclarations?.() ?? [];
-  if (declarations.length === 1 && ts.isVariableDeclaration(declarations[0]) && declarations[0].initializer
-    && (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) {
-    return valueSymbol(ts, checker, declarations[0].initializer, seen);
-  }
-  return symbol;
-}
-
-function calledExpression(ts, decorator) {
-  const expression = decorator.expression;
-  return ts.isCallExpression(expression) ? expression.expression : expression;
-}
-
-function selectedNode(ts, expression) {
-  expression = unwrapExpression(ts, expression);
-  if (ts.isIdentifier(expression)) return expression;
-  if (ts.isPropertyAccessExpression(expression)) return expression.name;
-  if (ts.isElementAccessExpression(expression) && ts.isStringLiteralLike(expression.argumentExpression)) return expression.argumentExpression;
-  return null;
-}
-
 function frameworkDecorator(ts, checker, decorator, targets) {
-  const selected = selectedNode(ts, calledExpression(ts, decorator));
+  const selected = selectedNode(ts, decoratorCallee(ts, decorator));
   if (!selected) return null;
   const symbol = valueSymbol(ts, checker, selected);
   for (const [name, target] of targets) if (symbol === target) return name;
   return null;
 }
 
-function mutableFrameworkAlias(ts, checker, decorator, targets) {
-  const selected = selectedNode(ts, calledExpression(ts, decorator));
-  const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
-  const declarations = symbol?.getDeclarations?.() ?? [];
-  if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || !declarations[0].initializer
-    || (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) return null;
-  const target = valueSymbol(ts, checker, declarations[0].initializer);
-  for (const [name, expected] of targets) if (target === expected) return name;
-  return null;
-}
+/* This module's framework map keys decorator names, not symbols - invert it (first name wins, as the old
+ * `for...of` scan did) for the shared symbol-keyed lookup. */
+const mutableFrameworkAlias = (ts, checker, decorator, targets) => {
+  const bySymbol = new Map();
+  for (const [name, symbol] of targets) if (!bySymbol.has(symbol)) bySymbol.set(symbol, name);
+  return mutableDecoratorKind(ts, checker, decorator, bySymbol);
+};
 
 function frameworkTargets(config, context, checker, localFiles) {
   const targets = new Map();
   const reasons = [];
-  const program = context.programs.find(candidate => candidate.getTypeChecker() === checker);
-  if (!program) return { targets, reasons: ['a TypeScript program checker could not be associated with its source'] };
-  for (const sourceFile of program.getSourceFiles()) {
-    if (!localFiles.has(canonical(sourceFile.fileName))) continue;
+  const files = programSourcesOf(context, checker, localFiles);
+  if (!files) return { targets, reasons: ['a TypeScript program checker could not be associated with its source'] };
+  for (const sourceFile of files) {
     for (const statement of sourceFile.statements) {
-      const moduleSpecifier = (context.ts.isImportDeclaration(statement) || context.ts.isExportDeclaration(statement))
-        && statement.moduleSpecifier && context.ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier : null;
-      const importEquals = context.ts.isImportEqualsDeclaration(statement) && context.ts.isExternalModuleReference(statement.moduleReference)
-        && statement.moduleReference.expression && context.ts.isStringLiteralLike(statement.moduleReference.expression)
-        ? statement.moduleReference.expression : null;
-      const specifier = (moduleSpecifier ?? importEquals)?.text;
-      if (!specifier || ![...FRAMEWORK.values()].includes(specifier)) continue;
-      const expected = new Set([...FRAMEWORK].filter(([, packageName]) => packageName === specifier).map(([name]) => name));
+      const bound = moduleExportsOf(context.ts, checker, statement);
+      if (!bound || ![...FRAMEWORK.values()].includes(bound.specifier)) continue;
+      const expected = new Set([...FRAMEWORK].filter(([, packageName]) => packageName === bound.specifier).map(([name]) => name));
       const selected = referencedExports(context.ts, statement, expected);
       if (!selected.length) continue;
-      const moduleSymbol = checker.getSymbolAtLocation(moduleSpecifier ?? importEquals);
-      if (!moduleSymbol) {
-        reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${specifier}`);
+      if (!bound.symbol) {
+        reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${bound.specifier}`);
         continue;
       }
-      const exports = new Map(checker.getExportsOfModule(moduleSymbol).map(symbol => [symbol.getName(), normalizedSymbolValue(context.ts, checker, symbol)]));
       for (const name of selected) {
-        const target = exports.get(name);
+        const target = bound.exports.get(name);
         if (target) targets.set(name, target);
-        else reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${name} from ${specifier}`);
+        else reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${name} from ${bound.specifier}`);
       }
     }
-    const visitRequire = node => {
-      if (context.ts.isCallExpression(node) && isUnshadowedCommonJsRequire(context.ts, checker, node.expression)
-        && node.arguments.length === 1 && context.ts.isStringLiteralLike(node.arguments[0])
-        && [...FRAMEWORK.values()].includes(node.arguments[0].text)) {
-        reasons.push(`${relativePath(config.root, sourceFile.fileName)} uses a CommonJS Nest framework binding whose decorator identity cannot be proved`);
-      }
-      context.ts.forEachChild(node, visitRequire);
-    };
-    visitRequire(sourceFile);
+    commonJsRequireReasons(context.ts, checker, sourceFile, (specifier) => [...FRAMEWORK.values()].includes(specifier),
+      reasons, relativePath(config.root, sourceFile.fileName), 'whose decorator identity cannot be proved', 'Nest framework binding');
   }
   return { targets, reasons };
 }

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

@@ -1,35 +1,35 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { gitOutput } from '../../api/git/lib.mjs';
+import { lsFiles } from '../../api/git/ls-files.mjs';
+import { revParseQuery } from '../../api/git/rev-parse-query.mjs';
+import { gitOutputOf } from '../../lib/git.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
  *   FE_ERROR_BOUNDARY_MISSING    a fe.app.next app lacks global-error, error, not-found or loading under src/app
- *   HFS_REQUIRED_FILE_MISSING    any other required file or directory (packages, fe modules, i18n, api ...), and a minimum
- *                                (no api app, no feature, no next app) which is reported once at hfs.json
+ *   HFS_REQUIRED_FILE_MISSING    any other required file or directory of any slot (backend app, feature, domain, integrations and
+ *                                platform instances, a required platform instance such as config or logging, packages, fe modules,
+ *                                i18n, api ...), and a minimum (no api app, no feature, no next app) which is reported once at hfs.json
  *
  * Slots of tier none (README, root config, .starciwork, .starcistacks) belong to the slot check; fe.app.next is the one
  * tier-none slot judged here. The tree is the tracked one (`git ls-files` from the repository root, minus files deleted
  * on disk), else the filesystem without node_modules, .git, dist and .next.
  */
-export const REQUIRED_FILE_RULE_IDS = ['BE_REQUIRED_MODULE_MISSING', 'FE_ERROR_BOUNDARY_MISSING', 'HFS_REQUIRED_FILE_MISSING'];
+export const REQUIRED_FILE_RULE_IDS = ['FE_ERROR_BOUNDARY_MISSING', 'HFS_REQUIRED_FILE_MISSING'];
 
 const SKIPPED_DIRECTORIES = new Set(['node_modules', '.git', 'dist', '.next']);
 const ERROR_BOUNDARY_FILE = /^(?:global-error|error|not-found|loading)\.tsx$/u;
-const BACKEND_MODULE_SLOT = /^be\.(?:app|feature|transport|domain|integrations|platform)(?:\.|$)/u;
 const ALSO_JUDGED_TIER_NONE = new Set(['fe.app.next']);
 
 function gitFiles(root) {
   try {
-    const run = args => gitOutput(args, { cwd: root, maxBuffer: 256 * 1024 * 1024 });
-    run(['rev-parse', '--is-inside-work-tree']);
-    const deleted = new Set(run(['ls-files', '--deleted', '-z', '--', '.']).split('\0').filter(Boolean));
-    return run(['ls-files', '--cached', '-z', '--', '.']).split('\0').filter(file => file && !deleted.has(file));
+    const run = (call, args) => gitOutputOf(call(args, { cwd: root, maxBuffer: 256 * 1024 * 1024 }));
+    run(revParseQuery, ['--is-inside-work-tree']);
+    const deleted = new Set(run(lsFiles, ['--deleted', '-z', '--', '.']).split('\0').filter(Boolean));
+    return run(lsFiles, ['--cached', '-z', '--', '.']).split('\0').filter(file => file && !deleted.has(file));
   } catch {
     return null;
   }
@@ -60,12 +60,20 @@ export function treeOf(root) {
   return { files, directories };
 }
 
+/**
+ * The prelude every tree-walking architecture checker shares: the input's config/graph/context, the compiler,
+ * the slot resolver and the tracked repository tree.
+ */
+export function checkerScope({ config, graph, context }) {
+  return { config, graph, context, ts: context.ts, resolver: graph.resolver, tree: treeOf(config.root) };
+}
+
 const strip = entry => entry.replace(/\/+$/u, '');
 const rootOfTarget = target => (target.endsWith('/') ? strip(target) : (path.posix.dirname(target) === '.' ? '' : path.posix.dirname(target)));
 
 function ruleFor(slotId, target, rootExists) {
   if (slotId === 'fe.app.next' && rootExists && ERROR_BOUNDARY_FILE.test(path.posix.basename(strip(target)))) return 'FE_ERROR_BOUNDARY_MISSING';
-  return BACKEND_MODULE_SLOT.test(slotId) ? 'BE_REQUIRED_MODULE_MISSING' : 'HFS_REQUIRED_FILE_MISSING';
+  return 'HFS_REQUIRED_FILE_MISSING';
 }
 
 export function checkRequiredFiles({ config, graph }) {

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

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { machineKit, pascal } from './machine-ast.mjs';
 import { treeOf } from './required-files.mjs';
 import { DATABASE_DIR } from './connection-map.mjs';
+import { collectRegistrations, isPerConnection, persistenceOfFactory } from './context-map.mjs';
 
 /**
  * R35 `schema-owner` (BE_SCHEMA_OWNER, BE-CONVENTION 1.4.6). Schema lives with the capability that owns the table:
@@ -11,7 +12,7 @@ import { DATABASE_DIR } from './connection-map.mjs';
  *     folder named `entities` or `migrations` outside be.persistence is refused too;
  *   - `persistence/connection.ts` declares `<c>Entities` / `<c>Migrations`, the arrays the apps register; a capability has no
  *     `CONNECTION` alias (C0 lead decision 2026-09-30): its connection is the one those arrays are REGISTERED on, in the
- *     `entities` / `migrations` of a connection literal of `DatabaseModule.register` and of the migrate app. The arrays are
+ *     `entities` / `migrations` of a connection literal of `DatabaseModule.register` and of the cli app. The arrays are
  *     registered under exactly one connection across all apps, that connection is declared in hfs.json, and every
  *     `Inject<Conn>EntityManager()` used inside the capability is that same connection;
  *   - the capability's `index.ts` exports `<c>Entities` when it has entities and `<c>Migrations` when it has migrations
@@ -36,13 +37,7 @@ export function checkSchemaOwner(input) {
   const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
   const plain = (rel, message, extra = {}) => violations.push({ ruleId: RULE, path: rel, line: 1, column: 1, message, ...extra });
 
-  /** {root, capability, folder, below} of a be.persistence file: `folder` is the directory below persistence/ ('' at its root). */
-  const persistenceOf = 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 };
-  };
+  const persistenceOf = persistenceOfFactory(resolver);
 
   let entities = 0;
   let migrations = 0;
@@ -80,7 +75,10 @@ export function checkSchemaOwner(input) {
       const isMigration = heritage(statement).some(expression => kit.isImportOf(checker, expression, 'MigrationInterface', 'typeorm'));
       if (isEntity) {
         entities += 1;
-        if (persistence?.folder !== 'entities') report(file, statement.name, `Entity ${statement.name.text} is declared outside persistence/entities/ of a domain or platform capability; an entity lives with the capability that owns its table, in src/modules/{domain,platform}/<capability>/persistence/entities/<table>.entity.ts.`, { class: statement.name.text });
+        // The table of a projection belongs to the projection that alone writes it: `<name>.projection-entity.ts` of slot be.projections.
+        const ownProjectionTable = resolver.classifyPath(file.rel).slot === 'be.projections' && file.rel.endsWith('.projection-entity.ts');
+        if (ownProjectionTable) note({ root: path.posix.join(path.posix.dirname(file.rel), 'persistence'), capability: path.posix.basename(path.posix.dirname(file.rel)) }, 'entities');
+        else if (persistence?.folder !== 'entities') report(file, statement.name, `Entity ${statement.name.text} is declared outside persistence/entities/ of a domain or platform capability; an entity lives with the capability that owns its table, in src/modules/{domain,platform}/<capability>/persistence/entities/<table>.entity.ts.`, { class: statement.name.text });
         else note(persistence, 'entities');
       }
       if (!isMigration) continue;
@@ -100,124 +98,28 @@ export function checkSchemaOwner(input) {
     }
   }
 
-  // The connection of a capability is where its arrays are registered (no CONNECTION alias in persistence/connection.ts).
-  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 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);
-      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;
-    });
-  }
-  for (const { name, connections: sites } of registered.values()) {
+  const { registered, registrations } = collectRegistrations({ kit, graph, persistenceOf });
+  for (const [key, { name, connections: sites }] of registered) {
     for (const [connection, site] of sites) {
       if (!connections.has(connection)) report(site.file, site.node, `The ${name} capability is registered on connection "${connection}", which hfs.json does not declare (declared: ${[...connections].sort().join(', ') || 'none'}); the tables of a capability live on one declared connection.`, { connection, capability: name });
     }
-    if (sites.size > 1) {
+    if (sites.size > 1 && !isPerConnection(resolver, key, name)) {
       const all = [...sites.keys()].sort().join(' and ');
       for (const [connection, site] of [...sites].slice(1)) report(site.file, site.node, `The ${name} capability's entities and migrations are registered on connections ${all}; a capability's tables live on exactly one connection, so register its arrays under one connection across every app.`, { connection, capability: name });
     }
   }
   for (const [key, kinds] of found) {
-    if (!registered.get(key)?.connections.size) plain(`${key}/persistence/connection.ts`, `The ${kinds.name} capability has entities or migrations but no app registers them; add ${camel(kinds.name)}Entities and ${camel(kinds.name)}Migrations to a connection of DatabaseModule.register and of the migrate app.`, { capability: kinds.name });
+    if (!registered.get(key)?.connections.size) plain(`${key}/persistence/connection.ts`, `The ${kinds.name} capability has entities or migrations but no app registers them; add ${camel(kinds.name)}Entities and ${camel(kinds.name)}Migrations to a connection of DatabaseModule.register and of the cli app.`, { capability: kinds.name });
     const connectionFile = graph.files.get(`${key}/persistence/connection.ts`);
     const declared = new Set((connectionFile?.sourceFile.statements.filter(ts.isVariableStatement).flatMap(statement => statement.declarationList.declarations) ?? []).map(item => item.name.text));
     for (const [kind, has] of [['Entities', kinds.entities], ['Migrations', kinds.migrations]]) {
       if (has && !declared.has(`${camel(kinds.name)}${kind}`)) plain(`${key}/persistence/connection.ts`, `${key}/persistence/connection.ts must export ${camel(kinds.name)}${kind}, the ${kind.toLowerCase()} of the ${kinds.name} capability, the one file that lists them for the apps.`, { capability: kinds.name });
     }
     const only = registered.get(key)?.connections;
-    if (!only || only.size !== 1) continue;
+    if (!only || only.size < 1) continue;
+    // A per-connection platform capability (event-bus, jobs) lives on every connection that uses it; any other on exactly one (reported above).
+    const perConnection = only.size > 1 && isPerConnection(resolver, key, kinds.name);
+    if (only.size > 1 && !perConnection) continue;
     const home = [...only.keys()][0];
     for (const file of graph.files.values()) {
       if (!file.rel.startsWith(`${key}/`)) continue;
@@ -227,7 +129,8 @@ export function checkSchemaOwner(input) {
         const declaration = kit.declarationsOf(checker, node.expression)[0];
         const rel = declaration ? kit.graphPath(declaration) : null;
         const used = rel ? [...connections].find(name => rel === `${DATABASE_DIR}/${name}.decorators.ts`) : null;
-        if (used && used !== home) report(file, node, `${file.rel} injects the entity manager of connection ${used}, but the ${kinds.name} capability's tables are registered on ${home}; a capability reads only its own database, so use Inject${pascal(home)}EntityManager or move the tables.`, { connection: used, expected: home, capability: kinds.name });
+        if (used && perConnection && !only.has(used)) report(file, node, `${file.rel} injects the entity manager of connection ${used}, but the ${kinds.name} capability's tables are registered on ${[...only.keys()].sort().join(' and ')}; register the capability on ${used} too or inject one of its connections.`, { connection: used, expected: [...only.keys()].sort().join(','), capability: kinds.name });
+        else if (used && !perConnection && used !== home) report(file, node, `${file.rel} injects the entity manager of connection ${used}, but the ${kinds.name} capability's tables are registered on ${home}; a capability reads only its own database, so use Inject${pascal(home)}EntityManager or move the tables.`, { connection: used, expected: home, capability: kinds.name });
         return true;
       });
     }

package/runtime/scripts/hfs/architecture/server-action.mjs

@@ -0,0 +1,24 @@
+/** The value of a directive-prologue statement, or null once the prologue has ended. */
+function directiveValue(ts, sourceFile, statement) {
+  const expressionStatement = ts?.isExpressionStatement
+    ? ts.isExpressionStatement(statement)
+    : Boolean(statement?.expression);
+  if (!expressionStatement) return null;
+  const expression = statement.expression;
+  if (ts?.isStringLiteral) return ts.isStringLiteral(expression) ? expression.text : null;
+  const raw = expression?.getText?.(sourceFile);
+  const quote = raw?.[0];
+  return typeof expression?.text === 'string' && (quote === "'" || quote === '"') && raw.at(-1) === quote
+    ? expression.text
+    : null;
+}
+
+/** True when a TypeScript source file declares `"use server"` in its directive prologue. */
+export function isServerActionModule(ts, sourceFile) {
+  for (const statement of sourceFile?.statements ?? []) {
+    const value = directiveValue(ts, sourceFile, statement);
+    if (value === null) return false;
+    if (value === 'use server') return true;
+  }
+  return false;
+}

package/runtime/scripts/hfs/architecture/side-boundary.mjs

@@ -0,0 +1,16 @@
+// side-boundary.mjs - what counts as an import that leaves a side of an app (ARCH_INTERNAL_IMPORT_OUTSIDE).
+// A side (be/ or fe/) imports nothing of the app outside itself: the root holds no source and the other side is another program; a
+// declared read of the OTHER side (be/contracts/) is codegen input, never an import. A declared read of a tree the APP ROOT owns
+// (supabase/types/, sides.<side>.reads of the slot manifest) is the one thing both sides do import: the generated database types.
+import path from 'node:path';
+import { isInside, slash } from './config.mjs';
+
+const OTHER_SIDE = /^(be|fe)\//;
+
+/** True when `target` (an absolute path) lies in a tree of the app root that the side declares it reads (`reads` of the side declaration). */
+const readsAppTree = (config, target) => (config.hfs?.repo?.reads ?? [])
+  .some((read) => !OTHER_SIDE.test(read) && isInside(path.join(config.packageRoot, read), target));
+
+/** Whether an import of `target` leaves the side the machine judges (config.root) for the app (config.packageRoot), declared app-root reads excepted. */
+export const crossesSide = (config, target) => config.packageRoot !== undefined && config.packageRoot !== config.root
+  && isInside(config.packageRoot, target) && !isInside(config.root, target) && !slash(target).includes('/node_modules/') && !readsAppTree(config, target);