@starci/hfs 4.0.7 → 4.0.9

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

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { isInside } from './config.mjs';
-import { isUnshadowedCommonJsRequire, relativePath, sourceLocation, UNPROVEN_FRAMEWORK, unwrapExpression } from './typescript.mjs';
+import { relativePath, UNPROVEN_FRAMEWORK, unwrapExpression } from './typescript.mjs';
+import { commonJsRequireReasons, constructedDecoratorKind, decoratorCallee, moduleExportsOf, mutableDecoratorKind, nodeDecorators, normalizedSymbol, normalizedSymbolValue, programSourcesOf, returnedExpressions, selectedNode, tracedFrameworkKinds, valueSymbol, violation } from './ast-walks.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 
 const SOURCE_LAYOUT_RULE_ID = 'BE_FEATURE_LAYOUT_INVALID';
 const SOURCE_NAME_RULE_ID = 'BE_SOURCE_FORM';
@@ -9,16 +11,16 @@ const FRAMEWORK_EXPORTS = new Map([
   ['typeorm', new Set(['Entity', 'EntitySchema', 'MigrationInterface', 'ViewEntity'])],
 ]);
 const APPLICATION_ROLES = new Set(['command', 'contracts', 'handler', 'query']);
-const TRANSPORT_ROLES = new Set(['args', 'cli', 'consumer', 'controller', 'gateway', 'input', 'job', 'request', 'resolver', 'response', 'type']);
+const TRANSPORT_ROLES = new Set(['args', 'cli', 'consumer', 'controller', 'gateway', 'input', 'processor', 'request', 'resolver', 'response', 'type']);
 const APPLICATION_LAYER_ROLES = new Set([...APPLICATION_ROLES, 'mapper']);
 const TRANSPORT_LAYER_ROLES = new Set([...TRANSPORT_ROLES, 'enum', 'filter', 'guard', 'interceptor', 'mapper']);
 // Class-bearing roles of the CLOSED suffix list of BE-CONVENTION 1.15 (class name = PascalCase of file + role). A role that is
-// not in that list (adapter, exception, processor, provider, repository, strategy, use-case) is never an allowed role here.
+// not in that list (adapter, exception, provider, repository, strategy, use-case) is never an allowed role here.
 const CLASS_ROLE_SUFFIX = new Map([
   ['args', 'Args'], ['cli', 'Cli'], ['client', 'Client'], ['command', 'Command'], ['consumer', 'Consumer'],
   ['controller', 'Controller'], ['entity', 'Entity'], ['error', 'Error'], ['filter', 'Filter'], ['gateway', 'Gateway'],
-  ['guard', 'Guard'], ['handler', 'Handler'], ['input', 'Input'], ['interceptor', 'Interceptor'], ['job', 'Job'],
-  ['mapper', 'Mapper'], ['module', 'Module'], ['module-definition', 'Module'], ['policy', 'Policy'], ['query', 'Query'],
+  ['guard', 'Guard'], ['handler', 'Handler'], ['input', 'Input'], ['interceptor', 'Interceptor'], ['processor', 'Processor'], ['event', 'Event'], ['queue', 'Queue'],
+  ['projection', 'Projection'], ['projection-entity', 'ProjectionEntity'], ['step', 'Step'], ['mapper', 'Mapper'], ['module', 'Module'], ['module-definition', 'Module'], ['policy', 'Policy'], ['query', 'Query'],
   ['request', 'Request'], ['resolver', 'Resolver'], ['response', 'Response'], ['service', 'Service'], ['type', 'Type'],
 ]);
 // Transport object contracts (interfaces and object aliases) named by their file role: <Action>Input in *.input.ts,
@@ -41,162 +43,40 @@ function canonical(file) {
   return path.resolve(file);
 }
 
-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 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 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 frameworkTargets(config, context, checker, localFiles) {
-  const bySymbol = new Map();
   const reasons = [];
-  const program = context.programs.find(candidate => candidate.getTypeChecker() === checker);
-  if (!program) return { bySymbol, 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 bySymbol = new Map();
+  const files = programSourcesOf(context, checker, localFiles);
+  if (!files) return { bySymbol, reasons: ['a TypeScript program checker could not be associated with its source'] };
+  for (const sourceFile of files) {
     for (const statement of sourceFile.statements) {
-      const specifierNode = (context.ts.isImportDeclaration(statement) || context.ts.isExportDeclaration(statement))
-        && statement.moduleSpecifier && context.ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier : null;
-      const specifier = specifierNode?.text;
-      if (!specifier || !FRAMEWORK_EXPORTS.has(specifier)) continue;
-      const moduleSymbol = checker.getSymbolAtLocation(specifierNode);
-      if (!moduleSymbol) {
-        reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${specifier}`);
-        continue;
-      }
-      const selected = FRAMEWORK_EXPORTS.get(specifier);
-      for (const exported of checker.getExportsOfModule(moduleSymbol)) if (selected.has(exported.getName())) {
-        const target = normalizedSymbolValue(context.ts, checker, exported);
-        if (target) bySymbol.set(target, exported.getName());
-      }
+      const bound = moduleExportsOf(context.ts, checker, statement);
+      if (!bound || !FRAMEWORK_EXPORTS.has(bound.specifier)) continue;
+      if (!bound.symbol) { reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${bound.specifier}`); continue; }
+      const selected = FRAMEWORK_EXPORTS.get(bound.specifier);
+      for (const [name, target] of bound.exports) if (selected.has(name) && target) bySymbol.set(target, name);
     }
-    const visit = node => {
-      if (context.ts.isCallExpression(node) && isUnshadowedCommonJsRequire(context.ts, checker, node.expression)
-        && node.arguments.length === 1 && context.ts.isStringLiteralLike(node.arguments[0]) && FRAMEWORK_EXPORTS.has(node.arguments[0].text)) {
-        reasons.push(`${relativePath(config.root, sourceFile.fileName)} uses a CommonJS ${node.arguments[0].text} binding whose source role cannot be proved`);
-      }
-      context.ts.forEachChild(node, visit);
-    };
-    visit(sourceFile);
+    commonJsRequireReasons(context.ts, checker, sourceFile, (specifier) => FRAMEWORK_EXPORTS.has(specifier),
+      reasons, relativePath(config.root, sourceFile.fileName), 'binding whose source role cannot be proved');
   }
   return { bySymbol, reasons };
 }
 
-function calledExpression(ts, decorator) {
-  return ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
-}
-
 function decoratorKind(ts, checker, decorator, targets) {
-  const selected = selectedNode(ts, calledExpression(ts, decorator));
+  const selected = selectedNode(ts, decoratorCallee(ts, decorator));
   return selected ? targets.get(valueSymbol(ts, checker, selected)) ?? null : null;
 }
 
-function mutableDecoratorKind(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;
-  return targets.get(valueSymbol(ts, checker, declarations[0].initializer)) ?? null;
-}
-
-function returnedExpressions(ts, declaration) {
-  if ((ts.isArrowFunction(declaration) || ts.isFunctionExpression(declaration)) && !ts.isBlock(declaration.body)) return [declaration.body];
-  const body = ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration)
-    || ts.isArrowFunction(declaration) || ts.isFunctionExpression(declaration) ? declaration.body : null;
-  if (!body || !ts.isBlock(body)) return [];
-  const returned = [];
-  const visit = node => {
-    if (node !== body && (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node))) return;
-    if (ts.isReturnStatement(node) && node.expression) returned.push(node.expression);
-    else ts.forEachChild(node, visit);
-  };
-  visit(body);
-  return returned;
-}
-
-function tracedFrameworkKinds(ts, checker, expression, targets, seen = new Set(), depth = 0) {
-  if (!expression) return new Set();
-  if (depth > 10) return new Set([UNPROVEN_FRAMEWORK]);
-  expression = unwrapExpression(ts, expression);
-  const selected = selectedNode(ts, expression);
-  const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
-  const direct = symbol ? targets.get(symbol) : null;
-  if (direct) return new Set([direct]);
-  if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) {
-    const kinds = new Set();
-    for (const returned of returnedExpressions(ts, expression)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, seen, depth + 1)) kinds.add(kind);
-    }
-    return kinds;
-  }
-  if (ts.isCallExpression(expression)) {
-    const kinds = tracedFrameworkKinds(ts, checker, expression.expression, targets, seen, depth + 1);
-    if (kinds.size) return kinds;
-  }
-  if (ts.isNewExpression(expression)) return tracedFrameworkKinds(ts, checker, expression.expression, targets, seen, depth + 1);
-  if (!symbol || seen.has(symbol)) return new Set();
-  const nextSeen = new Set(seen).add(symbol);
-  const kinds = new Set();
-  for (const declaration of symbol.getDeclarations?.() ?? []) {
-    if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
-      for (const kind of tracedFrameworkKinds(ts, checker, declaration.initializer, targets, nextSeen, depth + 1)) kinds.add(kind);
-    }
-    for (const returned of returnedExpressions(ts, declaration)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, nextSeen, depth + 1)) kinds.add(kind);
-    }
-  }
-  return kinds;
-}
-
-function constructedDecoratorKind(ts, checker, decorator, targets) {
-  const kinds = tracedFrameworkKinds(ts, checker, calledExpression(ts, decorator), targets);
-  if (kinds.has(UNPROVEN_FRAMEWORK)) return 'unproven framework';
-  return kinds.size === 1 ? [...kinds][0] : kinds.size ? 'multiple framework' : null;
-}
-
-function decorators(ts, node) {
-  return ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : node.decorators ?? [];
-}
+/* This module's trace descends `new X()` callees too; the framework map keys symbols directly. */
+const TRACE_NEW = { newExpression: true };
 
 function hasModifier(ts, node, kind) {
   return (ts.canHaveModifiers(node) ? ts.getModifiers(node) ?? [] : node.modifiers ?? []).some(modifier => modifier.kind === kind);
 }
 
-function violation(config, sourceFile, node, ruleId, message, extra = {}) {
-  return { ruleId, path: relativePath(config.root, sourceFile.fileName), ...sourceLocation(sourceFile, node), message, ...extra };
-}
+
 
 function sourceRole(ts, sourceFile) {
   const file = path.basename(sourceFile.fileName).replace(SOURCE_EXTENSION, '');
@@ -304,7 +184,7 @@ function companionInterfaceAllowed(ts, sourceFile, name) {
   if (!/^I[A-Z]/.test(name)) return false;
   const companion = name.slice(1);
   return sourceFile.statements.some(statement => ts.isClassDeclaration(statement) && statement.name?.text === companion
-    && decorators(ts, statement).length > 0);
+    && nodeDecorators(ts, statement).length > 0);
 }
 
 function camelCase(value) {
@@ -485,7 +365,7 @@ export function checkBackendSourceShape(config, context) {
 
     const classDeclarations = sourceFile.statements.filter(statement => ts.isClassDeclaration(statement));
     for (const declaration of classDeclarations) {
-      const declarationDecorators = decorators(ts, declaration);
+      const declarationDecorators = nodeDecorators(ts, declaration);
       const kinds = declarationDecorators.map(decorator => decoratorKind(ts, checker, decorator, framework.bySymbol)).filter(Boolean);
       const graphQlDto = kinds.some(kind => kind === 'ArgsType' || kind === 'InputType' || kind === 'ObjectType');
       if (graphQlDto && (!featureRoot || !inTransport || directories[transportIndex + 1] !== 'graphql')) {
@@ -551,11 +431,11 @@ export function checkBackendSourceShape(config, context) {
     }
 
     const visit = node => {
-      for (const decorator of decorators(ts, node)) {
+      for (const decorator of nodeDecorators(ts, node)) {
         const kind = decoratorKind(ts, checker, decorator, framework.bySymbol);
         if (!kind) {
           const dynamic = mutableDecoratorKind(ts, checker, decorator, framework.bySymbol)
-            ?? constructedDecoratorKind(ts, checker, decorator, framework.bySymbol);
+            ?? constructedDecoratorKind(ts, checker, decorator, framework.bySymbol, TRACE_NEW);
           if (dynamic) {
             const detail = `${relative} uses a mutable or constructed ${dynamic} decorator identity`;
             if (['Entity', 'ViewEntity', 'ArgsType', 'InputType', 'ObjectType', 'multiple framework', 'unproven framework'].includes(dynamic)) layoutReasons.push(detail);
@@ -574,7 +454,7 @@ export function checkBackendSourceShape(config, context) {
       }
       const exportedFactoryCall = ts.isCallExpression(node) && ts.isVariableDeclaration(node.parent) && publicDeclarations.has(node.parent);
       if ((ts.isNewExpression(node) || exportedFactoryCall) && featureRoot) {
-        const constructed = tracedFrameworkKinds(ts, checker, node, framework.bySymbol);
+        const constructed = tracedFrameworkKinds(ts, checker, node, framework.bySymbol, TRACE_NEW);
         if (constructed.has('EntitySchema')) violations.push(violation(config, sourceFile, node.expression, SOURCE_LAYOUT_RULE_ID,
           'TypeORM EntitySchema cannot be owned by a feature; place schema under its declared persistence module.'));
         if (constructed.has(UNPROVEN_FRAMEWORK)) layoutReasons.push(`${relative} has a constructed provider identity beyond the bounded static trace`);

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

@@ -1,16 +1,19 @@
 import path from 'node:path';
 import { analyzeSql, HOLE } from './sql-tokens.mjs';
 import { machineKit } from './machine-ast.mjs';
+import { contextModelOf } from './context-map.mjs';
+import { supabaseTablesOf } from './supabase-tables.mjs';
 
 /**
  * R86 `sql-owner` (BE_SQL_TABLE_OWNER). Every `sql` tagged template (the tag declared in platform/database) of a
  * `<name>.sql.ts` file in a capability's `persistence/` is read with the tokenizer of sql-tokens.mjs and judged against the
- * entities of the whole program:
- *   - it writes (INSERT INTO, UPDATE, DELETE FROM, MERGE INTO, TRUNCATE) only tables the file's own capability declares
- *     with `@Entity("<table>")` in its persistence;
- *   - it reads (FROM, JOIN, USING) only tables of capabilities its owner may import (the tier matrix, through
- *     `resolver.importAllowed` to the table owner's public entry) or its own;
- *   - every table it names is declared by some entity;
+ * schema authority of the whole program:
+ *   - it writes (INSERT INTO, UPDATE, DELETE FROM, MERGE INTO, TRUNCATE) only tables the file's own capability declares;
+ *   - it reads (FROM, JOIN, USING) only tables of its own CONTEXT (the connection its capability's arrays are registered on): its own
+ *     capability's, or those of a same-context capability its owner may import (the tier matrix, through `resolver.importAllowed`
+ *     to the table owner's public entry); a table of another context is refused (cross-context data comes only by events);
+ *   - every table it names is declared by some entity under TypeORM authority, or by the generated
+ *     `Database['public']['Tables']` contract under Supabase authority;
  *   - a SELECT carries LIMIT, or constrains the primary key or a unique key of its first table with `=`, or selects only
  *     aggregates without GROUP BY.
  * Table positions that hold a `${...}` substitution (SqlIdent) are dynamic; they are counted in the coverage and judged by
@@ -28,7 +31,7 @@ const literalStrings = (ts, node) => {
   return null;
 };
 
-function entitiesOf(kit, graph) {
+export function entitiesOf(kit, graph) {
   const { ts } = kit;
   const tables = new Map();
   let unreadable = 0;
@@ -90,11 +93,29 @@ function entitiesOf(kit, graph) {
   return { tables, unreadable };
 }
 
+const capabilityTable = root => path.posix.basename(root).replaceAll('-', '_').toLowerCase();
+
+/** Supabase declarations, with an owner when the generated table name matches a capability's persistence folder. */
+function supabaseDeclarations(graph, appRoot, ts) {
+  const generated = supabaseTablesOf(appRoot, ts);
+  const tables = new Map([...generated].map(table => [table, { table, owner: null, rel: null, uniqueSets: [] }]));
+  for (const file of graph.files.values()) {
+    if (file.slot !== 'be.persistence' || !file.owner) continue;
+    const key = capabilityTable(file.owner.root);
+    const declaration = tables.get(key);
+    if (declaration && declaration.owner === null) tables.set(key, { ...declaration, owner: file.owner.root, rel: file.rel });
+  }
+  return tables;
+}
+
 export function checkSqlOwner(input) {
-  const { graph } = input;
+  const { config, graph } = input;
   const kit = machineKit(input);
   const { ts, resolver } = kit;
-  const { tables, unreadable } = entitiesOf(kit, graph);
+  const supabase = resolver.ruleParams().schemaAuthority === 'supabase';
+  const entityDeclarations = supabase ? { tables: new Map(), unreadable: 0 } : entitiesOf(kit, graph);
+  const tables = supabase ? supabaseDeclarations(graph, config.packageRoot, ts) : entityDeclarations.tables;
+  const model = contextModelOf(kit, graph);
   const violations = [];
   let templates = 0;
   let dynamic = 0;
@@ -119,17 +140,36 @@ export function checkSqlOwner(input) {
       };
       const result = analyzeSql(text, { uniqueSetsOf: table => tables.get(table.toLowerCase())?.uniqueSets ?? null });
       dynamic += result.dynamic;
+      const ownTable = capabilityTable(file.owner.root);
       for (const write of result.writes) {
-        const entity = tables.get(write.table.toLowerCase());
-        if (!entity) report(`SQL writes table ${write.table}, which no @Entity declares; declare the entity in the owning capability's persistence/entities.`, { table: write.table });
-        else if (entity.owner !== file.owner.root) report(`SQL in ${file.owner.root} writes table ${write.table}, owned by ${entity.owner}; a capability writes only the tables of its own entities, call the owner's public API instead.`, { table: write.table, tableOwner: entity.owner });
+        const declaration = tables.get(write.table.toLowerCase());
+        if (!declaration) {
+          report(supabase
+            ? `SQL writes table ${write.table}, which Database['public']['Tables'] does not declare; regenerate supabase/types/database.types.ts from the migrations.`
+            : `SQL writes table ${write.table}, which no @Entity declares; declare the entity in the owning capability's persistence/entities.`, { table: write.table });
+        } else if (supabase && write.table.toLowerCase() !== ownTable) {
+          report(`SQL in ${file.owner.root} writes table ${write.table}${declaration.owner ? `, owned by ${declaration.owner}` : ''}; under Supabase schema authority a capability writes only its own table (${ownTable}), named for that capability.`, { table: write.table, ...(declaration.owner ? { tableOwner: declaration.owner } : {}) });
+        } else if (!supabase && declaration.owner !== file.owner.root) {
+          report(`SQL in ${file.owner.root} writes table ${write.table}, owned by ${declaration.owner}; a capability writes only the tables of its own entities, call the owner's public API instead.`, { table: write.table, tableOwner: declaration.owner });
+        }
       }
       for (const read of result.reads) {
-        const entity = tables.get(read.table.toLowerCase());
-        if (!entity) { report(`SQL reads table ${read.table}, which no @Entity declares; declare the entity in the owning capability's persistence/entities.`, { table: read.table }); continue; }
-        if (entity.owner === file.owner.root) continue;
-        const verdict = resolver.importAllowed(file.rel, `${entity.owner}/index.ts`);
-        if (!verdict.allowed) report(`SQL in ${file.owner.root} reads table ${read.table}, owned by ${entity.owner}, which ${file.owner.root} may not import (${verdict.reason}); read it through the owner's public API.`, { table: read.table, tableOwner: entity.owner, reason: verdict.reason });
+        const declaration = tables.get(read.table.toLowerCase());
+        if (!declaration) {
+          report(supabase
+            ? `SQL reads table ${read.table}, which Database['public']['Tables'] does not declare; regenerate supabase/types/database.types.ts from the migrations.`
+            : `SQL reads table ${read.table}, which no @Entity declares; declare the entity in the owning capability's persistence/entities.`, { table: read.table });
+          continue;
+        }
+        if (!declaration.owner || declaration.owner === file.owner.root) continue;
+        const ownContext = model.contextOfCapability(file.owner.root);
+        const tableContext = model.contextOfCapability(declaration.owner);
+        if (ownContext && tableContext && ownContext !== tableContext) {
+          report(`SQL in ${file.owner.root} (context ${ownContext}) reads table ${read.table}, owned by ${declaration.owner} (context ${tableContext}); a context reads and writes only its own context's tables, so a cross-context JOIN or subquery is refused. Keep a local copy fed by the other context's events (a reactor), or read a projection.`, { table: read.table, tableOwner: declaration.owner, context: ownContext, tableContext });
+          continue;
+        }
+        const verdict = resolver.importAllowed(file.rel, `${declaration.owner}/index.ts`);
+        if (!verdict.allowed) report(`SQL in ${file.owner.root} reads table ${read.table}, owned by ${declaration.owner}, which ${file.owner.root} may not import (${verdict.reason}); read it through the owner's public API.`, { table: read.table, tableOwner: declaration.owner, reason: verdict.reason });
       }
       for (const select of result.selects) {
         if (select.bounded || (select.table && !tables.has(select.table.toLowerCase()))) continue;
@@ -138,5 +178,6 @@ export function checkSqlOwner(input) {
       return true;
     });
   }
-  return { violations, coverage: { status: 'checked', entities: tables.size, unreadableEntities: unreadable, templates, dynamicIdentifiers: dynamic, foreignTags } };
+  return { violations, coverage: { status: 'checked', entities: entityDeclarations.tables.size, unreadableEntities: entityDeclarations.unreadable,
+    ...(supabase ? { supabaseTables: tables.size } : {}), templates, dynamicIdentifiers: dynamic, foreignTags } };
 }

package/runtime/scripts/hfs/architecture/sql-returning.mjs

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { HOLE, tokenizeSql } from './sql-tokens.mjs';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R181 `sql-returning` (BE_SQL_RETURNING_SHAPE). TypeORM's `EntityManager.query` returns an UPDATE or DELETE with RETURNING as
+ * `[rows, affectedCount]`, not as rows (an INSERT ... RETURNING returns rows), so a caller that reads the result as rows silently reads
+ * the wrong thing and no unit spec that stubs the SQL can see it. Every `sql` tagged template (the tag declared in platform/database) of a
+ * `<name>.sql.ts` file in a capability's `persistence/` is read with the tokenizer of sql-tokens.mjs, split into statements at top-level
+ * semicolons, and a statement that STARTS with UPDATE or DELETE and carries RETURNING at the top level is refused: write it as
+ * `WITH changed AS (UPDATE ... RETURNING ...) SELECT ... FROM changed`, which returns rows. A RETURNING inside a parenthesised CTE is the
+ * wrapped form and passes; so does INSERT ... RETURNING and any statement without RETURNING.
+ */
+export const SQL_RETURNING_RULE_IDS = ['BE_SQL_RETURNING_SHAPE'];
+
+const RULE = 'BE_SQL_RETURNING_SHAPE';
+
+/** The leading verbs of the top-level statements of `text` that RETURN from an UPDATE or DELETE without a wrapping SELECT. */
+function unwrappedReturning(text) {
+  const found = [];
+  let depth = 0;
+  let verb = null;
+  let returning = false;
+  const close = () => { if (verb && returning) found.push(verb); verb = null; returning = false; };
+  for (const token of tokenizeSql(text)) {
+    if (token.t === 'punct') {
+      if (token.v === '(') depth += 1;
+      else if (token.v === ')') depth = Math.max(0, depth - 1);
+      else if (token.v === ';' && depth === 0) close();
+      continue;
+    }
+    if (depth !== 0 || token.t !== 'word') continue;
+    if (verb === null) verb = token.up;
+    else if (token.up === 'RETURNING') returning = true;
+  }
+  close();
+  return found.filter(verb => verb === 'UPDATE' || verb === 'DELETE');
+}
+
+export function checkSqlReturning(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  let templates = 0;
+  for (const file of graph.files.values()) {
+    if (file.slot !== 'be.persistence' || !path.posix.basename(file.rel).endsWith('.sql.ts') || !file.owner) continue;
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!ts.isTaggedTemplateExpression(node)) return true;
+      const home = kit.declarationsOf(checker, node.tag).map(kit.ownerOfDeclaration).find(Boolean);
+      if (!home || home.tier !== 'platform' || home.name !== 'database') return true;
+      templates += 1;
+      const template = node.template;
+      const text = ts.isNoSubstitutionTemplateLiteral(template) ? template.text
+        : template.head.text + template.templateSpans.map(span => HOLE + span.literal.text).join('');
+      for (const verb of unwrappedReturning(text)) {
+        violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message: `${verb} ... RETURNING in ${file.rel} is returned by EntityManager.query as [rows, affectedCount], not as rows, so a caller reading rows reads the wrong value. Wrap it: WITH changed AS (${verb} ... RETURNING ...) SELECT ... FROM changed.`, verb });
+      }
+      return true;
+    });
+  }
+  return { violations, coverage: { status: 'checked', templates } };
+}

package/runtime/scripts/hfs/architecture/supabase-ast.mjs

@@ -0,0 +1,111 @@
+// supabase-ast.mjs - shared TypeScript-symbol and expression helpers for the front-end and back-end Supabase
+// architecture checks. Recognition follows imported declarations and inferred types, never local spelling alone.
+export const SUPABASE_MODULES = new Set(['@supabase/ssr', '@supabase/supabase-js']);
+
+export const moduleNameOf = (ts, node) => {
+  if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) return node.moduleSpecifier.text;
+  if (!ts.isCallExpression(node)) return null;
+  const dynamic = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+  const required = ts.isIdentifier(node.expression) && node.expression.text === 'require';
+  return (dynamic || required) && node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0]) ? node.arguments[0].text : null;
+};
+
+export const importedFrom = (kit, checker, node, modules, names = null) => {
+  const binding = kit.importBinding(checker, node);
+  return Boolean(binding && modules.has(binding.module) && (names === null || names.has(binding.name)));
+};
+
+const declarationFromSupabase = (declaration) => /(?:^|\/)node_modules\/@supabase\/(?:ssr|supabase-js|auth-js|postgrest-js|storage-js)(?:\/|$)/u
+  .test(String(declaration?.getSourceFile?.().fileName ?? '').replace(/\\/gu, '/'));
+
+const typeFromSupabase = (checker, node) => {
+  let type;
+  try { type = checker.getTypeAtLocation(node); } catch { return false; }
+  const queue = [type];
+  const seen = new Set();
+  while (queue.length) {
+    const item = queue.shift();
+    if (!item || seen.has(item)) continue;
+    seen.add(item);
+    if ([item.symbol, item.aliasSymbol].some((symbol) => symbol?.declarations?.some(declarationFromSupabase))) return true;
+    if (item.types) queue.push(...item.types);
+    if (item.target && item.target !== item) queue.push(item.target);
+  }
+  return false;
+};
+
+export const signatureFromSupabase = (checker, call) => {
+  try { return declarationFromSupabase(checker.getResolvedSignature(call)?.declaration); } catch { return false; }
+};
+
+export const unwrap = (ts, node) => {
+  let current = node;
+  while (current && (ts.isParenthesizedExpression(current) || ts.isAwaitExpression(current) || ts.isAsExpression(current)
+    || ts.isTypeAssertionExpression(current) || ts.isNonNullExpression(current))) current = current.expression;
+  return current;
+};
+
+export const isSupabaseValue = (kit, checker, node) => {
+  const current = unwrap(kit.ts, node);
+  if (!current) return false;
+  if (importedFrom(kit, checker, current, SUPABASE_MODULES)) return true;
+  if (kit.ts.isCallExpression(current) && signatureFromSupabase(checker, current)) return true;
+  return typeFromSupabase(checker, current);
+};
+
+export const callName = (ts, call) => ts.isCallExpression(call) && ts.isPropertyAccessExpression(call.expression) ? call.expression.name.text : null;
+
+export const chainParts = (ts, expression) => {
+  const names = [];
+  let current = unwrap(ts, expression);
+  while (current) {
+    if (ts.isCallExpression(current)) {
+      if (ts.isPropertyAccessExpression(current.expression)) {
+        names.unshift(current.expression.name.text);
+        current = unwrap(ts, current.expression.expression);
+        continue;
+      }
+      current = unwrap(ts, current.expression);
+      continue;
+    }
+    if (ts.isPropertyAccessExpression(current)) {
+      names.unshift(current.name.text);
+      current = unwrap(ts, current.expression);
+      continue;
+    }
+    break;
+  }
+  return names;
+};
+
+export const isSupabaseCall = (kit, checker, node) => kit.ts.isCallExpression(node)
+  && (signatureFromSupabase(checker, node) || isSupabaseValue(kit, checker, kit.ts.isPropertyAccessExpression(node.expression) ? node.expression.expression : node.expression));
+
+export const isDatabaseType = (ts, node) => {
+  if (!node) return false;
+  if (ts.isTypeReferenceNode(node)) {
+    const name = ts.isIdentifier(node.typeName) ? node.typeName.text : node.typeName.right.text;
+    return name === 'Database';
+  }
+  return false;
+};
+
+export const supabaseClientType = (kit, checker, node) => {
+  if (!node || !kit.ts.isTypeReferenceNode(node)) return false;
+  const name = kit.ts.isIdentifier(node.typeName) ? node.typeName : null;
+  return Boolean(name && importedFrom(kit, checker, name, SUPABASE_MODULES, new Set(['SupabaseClient'])));
+};
+
+export const contextTypesClient = (kit, checker, call) => {
+  let parent = call.parent;
+  while (parent && (kit.ts.isParenthesizedExpression(parent) || kit.ts.isAsExpression(parent))) {
+    if (kit.ts.isAsExpression(parent) && supabaseClientType(kit, checker, parent.type) && isDatabaseType(kit.ts, parent.type.typeArguments?.[0])) return true;
+    parent = parent.parent;
+  }
+  return kit.ts.isVariableDeclaration(parent) && supabaseClientType(kit, checker, parent.type)
+    && isDatabaseType(kit.ts, parent.type.typeArguments?.[0]);
+};
+
+export const reportAt = (violations, kit, ruleId, file, node, message, extra = {}) => {
+  violations.push({ ruleId, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
+};