@starci/eslint-canon-be 3.0.7 → 3.0.9

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

@@ -1,5 +1,5 @@
 /**
- * The lint surface: which architecture-machine findings an ESLint rule judges instead of `hfs check`.
+ * The lint surface: which architecture-machine findings an ESLint rule judges instead of `starci app check`.
  * Single source of truth. Each enforcer id is the rules.yaml enforcer; `codes` are the exact violation.ruleId strings its
  * check file emits on source files. plugins: 'be' = back-end profile repos, 'fe' = front-end profile, graph checks run for both.
  */
@@ -24,6 +24,7 @@ export const LINT_ENFORCERS = Object.freeze([
   enforcer('tier-direction', BOTH, ['BE_TIER_DIRECTION', 'FE_TIER_DIRECTION'], 'An import goes only to a tier the slot matrix allows.'),
   enforcer('owner-cycle', BOTH, ['ARCH_OWNER_CYCLE'], 'Owners never import each other in a cycle.'),
   enforcer('feature-imports-feature', BE, ['BE_FEATURE_IMPORTS_FEATURE'], 'A feature never imports another feature.'),
+  enforcer('kind-isolation', BE, ['BE_KIND_ISOLATION'], 'A feature of one trigger kind never imports a feature of another kind; the kinds meet through the event bus.'),
   enforcer('app-isolation', FE, ['FE_APP_ISOLATION'], 'An app never imports another app.'),
   enforcer('feature-layout', BE, ['BE_FEATURE_LAYOUT_INVALID'], 'A feature file sits in the folder its role names.'),
   enforcer('application-never-imports-transport', BE, ['BE_APPLICATION_IMPORTS_TRANSPORT', 'BE_APPLICATION_TRANSPORT_FRAMEWORK'], 'Application code never imports transport code, directly or through a chain.'),
@@ -33,6 +34,11 @@ export const LINT_ENFORCERS = Object.freeze([
   enforcer('app-composition-only', BE, ['BE_APP_COMPOSITION_ONLY', 'BE_APP_BUSINESS_ROLE'], 'An app only composes modules and holds no business role.'),
   enforcer('entrypoint-only-in-apps', BE, ['BE_ENTRYPOINT_ONLY_IN_APPS'], 'NestFactory and bootstrap live only in an app main file.'),
   enforcer('schema-owner', BE, ['BE_SCHEMA_OWNER'], 'Each entity array is registered by one owner across all apps.'),
+  enforcer('sql-returning', BE, ['BE_SQL_RETURNING_SHAPE'], 'An UPDATE or DELETE with RETURNING is wrapped in a CTE SELECT, because EntityManager.query returns it as [rows, count].'),
+  enforcer('context-owner', BE, ['BE_CONTEXT_OWNER'], 'An app composes only the contexts (connections) it owns; the migration apps compose all of them.'),
+  enforcer('context-coupling', BE, ['BE_CONTEXT_COUPLING'], 'Contexts are never coupled by a relation, a foreign key or an import; only by events.'),
+  enforcer('context-transaction', BE, ['BE_CONTEXT_TRANSACTION'], 'One transaction touches one context connection.'),
+  enforcer('context-platform-tables', BE, ['BE_CONTEXT_PLATFORM_TABLES'], 'A per-connection platform capability registers its tables on every connection that uses it.'),
   enforcer('error-code-unique', BE, ['BE_ERROR_HOME'], 'An error code is declared once in the repository.'),
   enforcer('error-masked', BE, ['BE_ERROR_MASKED'], 'Every app wires the error filter that masks internal errors.'),
   enforcer('default-deny-app-guard', BE, ['BE_DEFAULT_DENY'], 'Every app registers the default-deny guard before any other guard.'),
@@ -60,7 +66,7 @@ export const LINT_ENFORCERS = Object.freeze([
   enforcer('component-purity', FE, ['FE_COMPONENT_WORLD_OWNERSHIP', 'FE_WORLD_OWNER_RENDER_BOUNDARY', 'FE_CONNECTED_BLOCK_RENDER_PAIR', 'FE_PURE_REACHES_DATA', 'FE_PURE_WORLD_HOOK', 'FE_PURE_WORLD_IMPORT'], 'A pure component reaches no data or world state; its connected entry owns them.'),
   enforcer('grammar-entry', FE, ['ARCH_GRAMMAR_CONTRACT_INVALID', 'ARCH_GRAMMAR_EXPORT_BYPASS'], 'Vendor grammar is reached only through its owner entry.'),
   enforcer('i18n-keys', FE, ['FE_I18N_KEYS'], 'Translation keys read by source and keys held by catalogs agree both ways.'),
-  // The per-path judgements of the slot manifest (scripts/lib/hfs-path-findings.mjs), on a tracked TypeScript file.
+  // The per-path judgements of the slot manifest (scripts/hfs/path-findings.mjs), on a tracked TypeScript file.
   enforcer('slot-undeclared', BOTH, ['HFS_SLOT_UNDECLARED', 'HFS_SLOT_AMBIGUOUS', 'HFS_SLOT_NOT_ENABLED'], 'A TypeScript file is owned by exactly one slot of the repository.', { origin: 'repo' }),
   enforcer('source-suffix', BE, ['BE_SOURCE_FORM'], 'A source file name is index.ts, main.ts, a migration or <kebab-name>.<suffix>.ts with a suffix of the closed list.', { origin: 'repo' }),
   enforcer('spec-placement', BE, ['BE_SPEC_PLACEMENT'], 'A spec file lives in one of the four test layers and nowhere else.', { origin: 'repo' }),
@@ -74,7 +80,7 @@ export const LINT_CODES = new Set(LINT_ENFORCERS.flatMap(e => e.codes));
 export const TS_SOURCE = /\.(?:[cm]?tsx?)$/;
 
 /** True when a finding sits on an existing TypeScript file of the repository: the only findings an editor can show on a line. */
-export function attachesToSource(repositoryRoot, violation) {
+function attachesToSource(repositoryRoot, violation) {
   const file = violation?.path;
   if (typeof file !== 'string' || !TS_SOURCE.test(file)) return false;
   return fs.existsSync(path.join(repositoryRoot, ...file.split('/')));
@@ -87,5 +93,5 @@ export const codeOf = (finding) => finding?.ruleId ?? finding?.code;
 export const belongsTo = (enforcer, finding) => enforcer.codes.includes(codeOf(finding))
   && (finding.origin ?? 'machine') === (enforcer.origin ?? 'machine') && (enforcer.via === undefined || finding.check === enforcer.via);
 
-/** True when some lint rule owns the finding and it sits on an existing TypeScript file: it is an ESLint report, not a `hfs check` finding. */
+/** True when some lint rule owns the finding and it sits on an existing TypeScript file: it is an ESLint report, not a `starci app check` finding. */
 export const onLintSurface = (repositoryRoot, finding) => LINT_ENFORCERS.some(enforcer => belongsTo(enforcer, finding)) && attachesToSource(repositoryRoot, finding);

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

@@ -1,7 +1,9 @@
-import { treeOf } from './required-files.mjs';
-import { allowsFile } from '../../lib/hfs-allows.mjs';
-import { locateDeclaration } from '../../lib/hfs-slots.mjs';
+import { checkerScope } from './required-files.mjs';
+import { allowsFile } from '../allows.mjs';
+import { locateDeclaration } from '../slots.mjs';
 import { DEFAULT_ENVIRONMENT, STACKS_DIRECTORY, STATEFUL_KINDS, namesOfService, readStack } from '../../lib/stack-services.mjs';
+import { unwrapEach } from './ast-walks.mjs';
+import { nameText, sourceLocation } from '../../lib/ts-ast.mjs';
 
 /**
  * R47 `test-world-files` (BE_TEST_TOPOLOGY). Judgements over the test world, read through slots, the repository's own
@@ -40,18 +42,9 @@ const NAMED_FORM = `export const { useTestWorld, useSandbox } = ${DEFINE}({ ...
 const defaultEnvironment = DEFAULT_ENVIRONMENT;
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
-const nameOf = (ts, name) => (name && (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) ? name.text : null);
-const unwrap = (ts, node) => {
-  let current = node;
-  while (current && (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression?.(current))) current = current.expression;
-  return current;
-};
-const propertyOf = (ts, literal, key) => literal.properties.find(property => ts.isPropertyAssignment(property) && nameOf(ts, property.name) === key)?.initializer ?? null;
+const unwrap = (ts, node) => unwrapEach(ts, node, [ts.isParenthesizedExpression, ts.isAsExpression, ts.isSatisfiesExpression]);
+const propertyOf = (ts, literal, key) => literal.properties.find(property => ts.isPropertyAssignment(property) && nameText(ts, property.name) === key)?.initializer ?? null;
 const isExported = (ts, statement) => (statement.modifiers ?? []).some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword);
-const positionOf = (sourceFile, node) => {
-  const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
-  return { line: position.line + 1, column: position.character + 1 };
-};
 
 /** The object literal of `defineTestWorld(<object literal>)`, or null. */
 function defineLiteral(ts, expression) {
@@ -89,7 +82,7 @@ function fakeEntriesOf(ts, sourceFile, literal) {
   const value = node ? unwrap(ts, node) : null;
   if (!value || !ts.isObjectLiteralExpression(value)) return [];
   return value.properties
-    .map(property => ({ name: nameOf(ts, property.name), ...positionOf(sourceFile, property) }))
+    .map(property => ({ name: nameText(ts, property.name), ...sourceLocation(sourceFile, property) }))
     .filter(entry => entry.name);
 }
 
@@ -107,21 +100,18 @@ function fakedByOf(ts, sourceFile, literal) {
     if (!fake) continue;
     const reason = propertyOf(ts, body, 'reason');
     entries.push({
-      service: nameOf(ts, property.name),
+      service: nameText(ts, property.name),
       fake: ts.isStringLiteralLike(fake) ? fake.text : '',
       reason: reason && ts.isStringLiteralLike(reason) ? reason.text.trim() : '',
-      ...positionOf(sourceFile, property),
+      ...sourceLocation(sourceFile, property),
     });
   }
   return entries;
 }
 
 export function checkTestWorldFiles(input) {
-  const { config, graph, context } = input;
-  const ts = context.ts;
-  const resolver = graph.resolver;
+  const { config, graph, ts, resolver, tree } = checkerScope(input);
   const { suffixes } = resolver.ruleParams();
-  const tree = treeOf(config.root);
   const violations = [];
   const fakeProviders = new Map();
   let worldRoot = null;

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

@@ -1,14 +1,18 @@
+import { isServerActionModule } from './server-action.mjs';
+
 /**
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
  *   1. the tier direction matrix: every import, re-export and type-only import between two owners must go from a tier to
  *      a tier its `mayImport` lists (BE_TIER_DIRECTION / FE_TIER_DIRECTION); a backend feature importing another feature
- *      is the one direction with its own code (BE_FEATURE_IMPORTS_FEATURE, R28), never BE_TIER_DIRECTION,
+ *      is the one direction with its own code (BE_FEATURE_IMPORTS_FEATURE, R28), never BE_TIER_DIRECTION, and a feature of one trigger
+ *      kind (slot field `trigger`: api, webhooks, realtime, saga, reactors, jobs, cli) importing a feature of another is
+ *      BE_KIND_ISOLATION, whose fix is the event bus,
  *      an app never imports another app (FE_APP_ISOLATION), and a component layer imports only the layers after it;
  *   2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE),
  *      reported with the cycle path and the import that closes each hop.
  * Importing inside one owner is always allowed; the public-entry rule stays with owners.mjs (ARCH_OWNER_EXPORT_BYPASS).
  */
-export const TIER_RULE_IDS = ['BE_TIER_DIRECTION', 'BE_FEATURE_IMPORTS_FEATURE', 'FE_TIER_DIRECTION', 'FE_APP_ISOLATION', 'ARCH_OWNER_CYCLE'];
+export const TIER_RULE_IDS = ['BE_TIER_DIRECTION', 'BE_FEATURE_IMPORTS_FEATURE', 'BE_KIND_ISOLATION', 'FE_TIER_DIRECTION', 'FE_APP_ISOLATION', 'ARCH_OWNER_CYCLE'];
 
 const REASON_TEXT = {
   tierDirection: ({ fromTier, toTier, mayImport }) => `a ${fromTier} may import only ${mayImport.join(', ') || 'nothing'}; it imports a ${toTier}`,
@@ -70,6 +74,27 @@ function cycleThrough(adjacency, members, origin) {
   return [origin, origin];
 }
 
+/** The trigger kind (slot field `trigger`) of the owner that holds `file`, or null when its owner's slot names none. */
+const triggerOf = (resolver, file) => {
+  const owner = resolver.ownerOf(file);
+  return owner ? (resolver.slot(owner.slot)?.trigger ?? null) : null;
+};
+
+/** The db Server Action an edge targets, or null. */
+const serverActionTarget = (graph, edge) => {
+  if (graph.profile !== 'fe') return null;
+  const to = graph.resolver.classifyPath(edge.to);
+  return to.slot === 'fe.modules.db' && /^write-[^/]+\.ts$/u.test(edge.to.split('/').at(-1))
+    && isServerActionModule(null, graph.files.get(edge.to).sourceFile) ? to : null;
+};
+
+/** A connected block may call a db writer directly when that writer is a file-level Next Server Action. */
+const blockCallsServerAction = (graph, edge) => {
+  if (!serverActionTarget(graph, edge)) return false;
+  const from = graph.resolver.classifyPath(edge.from);
+  return from.slot === 'fe.components' && from.kind === 'blocks' && from.role === 'entry';
+};
+
 export function checkTiers(graph) {
   const { resolver, profile } = graph;
   const violations = [];
@@ -81,15 +106,32 @@ export function checkTiers(graph) {
     const verdict = resolver.importAllowed(edge.from, edge.to);
     if (verdict.reason === 'unowned' || verdict.reason?.startsWith('slot')) { unclassified += 1; continue; }
     edgesChecked += 1;
-    if (verdict.allowed || !REASON_TEXT[verdict.reason]) continue;
+    const actionTarget = serverActionTarget(graph, edge);
+    if ((verdict.allowed || verdict.reason === 'notPublicEntry') && actionTarget && graph.unit(edge.from) !== graph.unit(edge.to) && !blockCallsServerAction(graph, edge)) {
+      counts.tierDirection += 1;
+      violations.push({
+        ruleId: tierRule,
+        path: edge.from, line: edge.line, column: edge.column,
+        specifier: edge.specifier, resolvedPath: edge.to, typeOnly: !edge.runtime,
+        fromTier: resolver.tierOf(edge.from), toTier: resolver.tierOf(edge.to),
+        message: `${edge.from} -> ${edge.to}: a db Server Action is called directly only by a connected block entry; hooks and other tiers use their declared data path${edge.runtime ? '' : ' (type-only imports count)'}.`,
+      });
+      continue;
+    }
+    if (verdict.allowed || (verdict.reason === 'tierDirection' && blockCallsServerAction(graph, edge)) || !REASON_TEXT[verdict.reason]) continue;
     counts[verdict.reason] += 1;
     const featureToFeature = profile === 'be' && verdict.reason === 'tierDirection' && verdict.fromTier === 'feature' && verdict.toTier === 'feature';
+    const fromKind = featureToFeature ? triggerOf(resolver, edge.from) : null;
+    const toKind = featureToFeature ? triggerOf(resolver, edge.to) : null;
+    const crossKind = fromKind !== null && toKind !== null && fromKind !== toKind;
     violations.push({
-      ruleId: verdict.reason === 'crossApp' ? 'FE_APP_ISOLATION' : featureToFeature ? 'BE_FEATURE_IMPORTS_FEATURE' : tierRule,
+      ruleId: verdict.reason === 'crossApp' ? 'FE_APP_ISOLATION' : crossKind ? 'BE_KIND_ISOLATION' : featureToFeature ? 'BE_FEATURE_IMPORTS_FEATURE' : tierRule,
       path: edge.from, line: edge.line, column: edge.column,
       specifier: edge.specifier, resolvedPath: edge.to, typeOnly: !edge.runtime,
       fromTier: verdict.fromTier ?? null, toTier: verdict.toTier ?? null,
-      message: `${edge.from} -> ${edge.to}: ${REASON_TEXT[verdict.reason](verdict)}${edge.runtime ? '' : ' (type-only imports count)'}.`,
+      message: crossKind
+        ? `${edge.from} -> ${edge.to}: a ${fromKind} feature imports a ${toKind} feature; no kind imports another, every cross-kind call is an event published with eventBus.publish(event, tx) from a domain service${edge.runtime ? '' : ' (type-only imports count)'}.`
+        : `${edge.from} -> ${edge.to}: ${REASON_TEXT[verdict.reason](verdict)}${edge.runtime ? '' : ' (type-only imports count)'}.`,
     });
   }
 

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

@@ -6,7 +6,8 @@ import { machineKit } from './machine-ast.mjs';
  * `client-fetch-has-signal`. ESLint judges one file at a time by the spelling of a call; the machine judges the repository by
  * what the checker resolves. A repository has exactly ONE transport client and ONE Outcome union, both named by slot (never
  * by a path spelled here): the api package's (`fe.package.api.client`, `fe.package.api.outcome`) when the repository shares
- * it, or the only app's (`fe.transport.client`, `fe.transport.outcome`) when the repository declares exactly one app.
+ * it, or the only app's (`fe.transport.client`, `fe.transport.outcome`) when the repository declares exactly one app. The
+ * Outcome homes are the slots the manifest marks `outcomeHome` (the lite edition adds `fe.modules.db.outcome`), not a list kept here.
  *
  *   - two or more clients, or two or more Outcome unions, in the repository (two apps each keeping one, or a package one plus
  *     an app one) are findings on every copy;
@@ -30,7 +31,6 @@ const APP_CLIENT_SLOT = 'fe.transport.client';
 const APP_OUTCOME_SLOT = 'fe.transport.outcome';
 const PACKAGE_API_SLOT = 'fe.package.api';
 const CLIENT_SLOTS = new Set([APP_CLIENT_SLOT, 'fe.package.api.client']);
-const OUTCOME_SLOTS = new Set([APP_OUTCOME_SLOT, 'fe.package.api.outcome']);
 const NO_CLIENT = "the repository has no transport client. Create the one client (packages/<family>-api/src/client.ts, or the only app's modules/api/client.ts) and call it.";
 
 export function checkTransportOwner(input) {
@@ -60,7 +60,7 @@ export function checkTransportOwner(input) {
 
   const files = [...graph.files.values()].filter(file => file.slot && file.tier !== 'e2e');
   const clients = files.filter(file => CLIENT_SLOTS.has(file.slot));
-  const outcomes = files.filter(file => OUTCOME_SLOTS.has(file.slot));
+  const outcomes = files.filter(file => resolver.slot(file.slot)?.outcomeHome === true);
   const clientRels = new Set(clients.map(file => file.rel));
   const list = items => items.map(item => item.rel).join(', ');
   const owned = clients.length ? `the repository has one transport (${list(clients)}). Call the client and take its Outcome.` : NO_CLIENT;

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

@@ -2,31 +2,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { canonical, isInside, slash } from './config.mjs';
+import { crossesSide } from './side-boundary.mjs';
 import { sameOrUnder } from '../../lib/path-key.mjs';
 import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule, sharedInProgramRun, typeScriptProjectReferencePath } from '../typescript-programs.mjs';
 import { readJsonFile } from '../../lib/json.mjs';
-import { locateDeclaration } from '../../lib/hfs-slots.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
+import { locateDeclaration } from '../slots.mjs';
 
 const CODE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
 const TEST_FILE = /(?:^|[.-])(?:spec|test)\.[cm]?[jt]sx?$/i;
 const ASSET_EXTENSION = /\.(?:css|scss|sass|less|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|eot|ya?ml|json)$/i;
 // Framework build output a tsconfig may include (Next writes `.next/types/**/*.ts` back into tsconfig.json on
 // every build) is compiled for type resolution but is never source: it is gitignored, regenerated, and no
-// canon or architecture rule applies to it (starci-next inc-2260b3754afa, nivo inc-ffe60c49f502).
-export const GENERATED_SEGMENTS = new Set(['.next', '.turbo', '.vercel', '.output', '.nuxt', '.svelte-kit', '.expo', '.docusaurus', '.swc', '.cache']);
-export function isGeneratedPath(root, fileName) {
+// canon or architecture rule applies to it (inc-ffe60c49f502).
+const GENERATED_SEGMENTS = new Set(['.next', '.turbo', '.vercel', '.output', '.nuxt', '.svelte-kit', '.expo', '.docusaurus', '.swc', '.cache']);
+function isGeneratedPath(root, fileName) {
   return slash(path.relative(root, fileName)).split('/').slice(0, -1).some(segment => GENERATED_SEGMENTS.has(segment));
 }
-// A `<tool>.config.*` or `<tool>.setup.*` module at the root of a project (beside a package manifest or a tsconfig.json:
-// next.config.ts and postcss.config.mjs of an app, which has no package.json of its own) is build tooling a broad `**/*.ts`
-// include pulls in; a `*.config.ts` inside a source tree (src/config/database.config.ts) has neither beside it and stays source.
-// The architecture program still reads tooling modules (a profile may declare one as source); the lint (hfs lint) judges one only
-// through the repository's own eslint.config.
-const TOOLING_MODULE = /^[^/]+\.(?:config|setup)\.[cm]?[jt]sx?$/i;
-export function isToolingModule(fileName) {
-  return TOOLING_MODULE.test(path.basename(fileName)) && ['package.json', 'tsconfig.json'].some((manifest) => fs.existsSync(path.join(path.dirname(fileName), manifest)));
-}
-
 function diagnosticMessage(ts, diagnostic) {
   return ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
 }
@@ -53,7 +45,7 @@ function compilerError(ts, root, diagnostic, project, ruleId = 'ARCH_TSCONFIG_IN
  * Load TypeScript through the target package boundary, never through StarCi's own dependency graph. A side folder of an app has no
  * package.json of its own: the app root's one manifest is the boundary its TypeScript is installed under.
  */
-export function loadTargetTypeScript(repositoryRoot) {
+function loadTargetTypeScript(repositoryRoot) {
   const packageFile = path.join(locateDeclaration(repositoryRoot).appRoot, 'package.json');
   if (!fs.existsSync(packageFile)) throw Error('ARCH_TYPESCRIPT_MISSING: target package.json is required to resolve target-installed TypeScript.');
   const targetRequire = createRequire(packageFile);
@@ -98,7 +90,7 @@ function runtimeImport(ts, node) {
   return true;
 }
 
-function isUnshadowedCommonJsRequire(ts, checker, expression) {
+export function isUnshadowedCommonJsRequire(ts, checker, expression) {
   if (!ts.isIdentifier(expression) || expression.text !== 'require') return false;
   const symbol = checker?.getSymbolAtLocation(expression);
   if (!symbol) return true;
@@ -113,7 +105,7 @@ function isUnshadowedCommonJsRequire(ts, checker, expression) {
  * existing directory and a data-asset extension tail qualify; code never does, since a context of code would
  * be an import graph nobody wrote down. Returns the specifiers, or null when the import stays unproven.
  */
-export function assetContextSpecifiers(ts, sourceFile, argument) {
+function assetContextSpecifiers(ts, sourceFile, argument) {
   if (!argument || !ts.isTemplateExpression(argument)) return null;
   const head = argument.head.text;
   const spans = argument.templateSpans;
@@ -168,11 +160,6 @@ function moduleReferences(ts, sourceFile, checker) {
   return { found, unproven };
 }
 
-function sourceLocation(sourceFile, node) {
-  const point = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
-  return { line: point.line + 1, column: point.character + 1 };
-}
-
 function isProductionSource(root, sourceFile) {
   return isInside(root, sourceFile.fileName)
     && CODE_EXTENSIONS.test(sourceFile.fileName)
@@ -210,7 +197,7 @@ function exportPatternCapture(pattern, request) {
   return request.startsWith(before) && request.endsWith(after) ? request.slice(before.length, request.length - after.length) : null;
 }
 
-function exportTargetStrings(value) {
+export function exportTargetStrings(value) {
   if (typeof value === 'string') return [value];
   if (Array.isArray(value)) return value.flatMap(exportTargetStrings);
   if (value && typeof value === 'object' && !Object.keys(value).some(key => key.startsWith('.'))) return Object.values(value).flatMap(exportTargetStrings);
@@ -497,9 +484,7 @@ function typeScriptContext(config, loaded, paths) {
         || (config.repository && isInside(config.repository, actualTarget) && !slash(actualTarget).includes('/node_modules/'));
       // A side of an app (config.root is be/ or fe/) imports nothing of the app outside itself: the root holds no source, the other
       // side is another program, and a declared read (sides.fe.reads, be/contracts/) is codegen input, never an import.
-      const crossesSide = config.packageRoot !== undefined && config.packageRoot !== config.root
-        && isInside(config.packageRoot, actualTarget) && !isInside(config.root, actualTarget) && !slash(actualTarget).includes('/node_modules/');
-      if (internal && crossesSide) {
+      if (internal && crossesSide(config, actualTarget)) {
         errors.push({
           ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
           project: project.relative,
@@ -581,6 +566,8 @@ export function unwrapExpression(ts, expression) {
   return expression;
 }
 
+/* ---- the AST walks every architecture checker shares ---- */
+
 /** The names of `expected` an import or re-export statement binds (all of them for a namespace or star form). */
 export function referencedExports(ts, statement, expected) {
   if (ts.isImportDeclaration(statement)) {
@@ -595,4 +582,3 @@ export function referencedExports(ts, statement, expected) {
   return [...expected];
 }
 
-export { isUnshadowedCommonJsRequire, sourceLocation };

package/runtime/scripts/hfs/declaration-shape.mjs

@@ -0,0 +1,62 @@
+// declaration-shape.mjs - the dependency-free hfs.json shape validation used by the HFS slot loader. Semantic checks
+// against a loaded manifest remain in slots.mjs; this module mirrors modules/schemas/hfs-repo.schema.yaml only.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { APP_KIND, connectionShapeProblems, NAME, RUNTIME_KIND, SLOT_ID } from './manifest-shape.mjs';
+import { kindShapeProblems, patternShapeProblems } from './declaration-slots.mjs';
+
+/** Shape problems of the optional hfs.json `supabase` block whose auth posture DB_CONFIG_POLICY checks. */
+function supabaseBlockProblems(block) {
+  if (block === undefined) return [];
+  if (!isPlainObject(block)) return ['supabase must be an object'];
+  const bad = [];
+  for (const key of Object.keys(block)) if (!['enableSignup', 'jwtExpiry', 'siteUrl', 'redirectUrls', 'forceRls'].includes(key)) bad.push(`supabase has unknown key ${key}`);
+  if (block.enableSignup !== undefined && typeof block.enableSignup !== 'boolean') bad.push('supabase.enableSignup must be true or false');
+  if (block.jwtExpiry !== undefined && !(Number.isInteger(block.jwtExpiry) && block.jwtExpiry > 0 && block.jwtExpiry <= 3600)) bad.push('supabase.jwtExpiry must be an integer of seconds, 3600 at most');
+  if (block.siteUrl !== undefined && (typeof block.siteUrl !== 'string' || !block.siteUrl.trim())) bad.push('supabase.siteUrl must be a URL string');
+  for (const key of ['redirectUrls', 'forceRls']) if (block[key] !== undefined && !(Array.isArray(block[key]) && block[key].every((value) => typeof value === 'string' && value.trim()))) bad.push(`supabase.${key} must be a list of strings`);
+  return bad;
+}
+
+/** Shape problems of a parsed hfs.json, in the words of modules/schemas/hfs-repo.schema.yaml. */
+export function declarationShapeProblems(declaration, profiles) {
+  const bad = [];
+  if (!isPlainObject(declaration)) return ['hfs.json is not an object'];
+  if (!(Number.isInteger(declaration.hfs) && declaration.hfs >= 1)) bad.push('hfs must be the pinned manifest major (an integer, 1 or more)');
+  if (!NAME.test(String(declaration.project))) bad.push('project must be a project name');
+  if (declaration.kind === RUNTIME_KIND) {
+    for (const key of Object.keys(declaration)) if (!['hfs', 'kind', 'project'].includes(key)) bad.push(`unknown key ${key} (a runtime declaration is {hfs, kind, project})`);
+    return bad;
+  }
+  for (const key of Object.keys(declaration)) if (!['hfs', 'kind', 'project', 'edition', 'supabase', 'sides', 'browser'].includes(key)) bad.push(`unknown key ${key}`);
+  bad.push(...supabaseBlockProblems(declaration.supabase));
+  if (declaration.browser !== undefined && declaration.browser !== true) bad.push('browser is `true` when the app has a browser journey (slot app.browser), and is left out otherwise');
+  if (declaration.kind !== APP_KIND) bad.push(`kind must be ${APP_KIND} (a product is one app repository with a be and an fe side) or ${RUNTIME_KIND} (the StarCi runtime repository)`);
+  if (!isPlainObject(declaration.sides) || Object.keys(declaration.sides).sort().join() !== profiles.join()) { bad.push('sides must declare exactly be and fe'); return bad; }
+  const names = new Map();
+  for (const side of profiles) {
+    const value = declaration.sides[side];
+    const at = `sides.${side}`;
+    if (!isPlainObject(value)) { bad.push(`${at} must be an object`); continue; }
+    for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads'].includes(key)) bad.push(`${at} has unknown key ${key}`);
+    if (!Array.isArray(value.apps) || !value.apps.length) bad.push(`${at}.apps must list every ${side}/apps/<name> with its kind`);
+    else value.apps.forEach((app, index) => {
+      if (!isPlainObject(app) || !NAME.test(String(app.name)) || !NAME.test(String(app.kind)) || Object.keys(app).some((key) => key !== 'name' && key !== 'kind')) bad.push(`${at}.apps[${index}] must be {name, kind}`);
+      else if (names.has(app.name)) bad.push(`app ${app.name} is declared twice (${names.get(app.name)} and ${side})`);
+      else names.set(app.name, side);
+    });
+    if (value.optionalSlots !== undefined && (!Array.isArray(value.optionalSlots) || !value.optionalSlots.every((slot) => SLOT_ID.test(String(slot))) || new Set(value.optionalSlots).size !== value.optionalSlots.length)) bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
+    bad.push(...patternShapeProblems(value, at, NAME), ...kindShapeProblems(value, at, NAME));
+    if (value.reads !== undefined && (!Array.isArray(value.reads) || !value.reads.every((read) => typeof read === 'string' && read.length > 0) || new Set(value.reads).size !== value.reads.length)) bad.push(`${at}.reads must be a unique list of paths`);
+    if (value.connections !== undefined) {
+      if (side !== 'be') { bad.push('connections belong to the be side'); continue; }
+      const list = Array.isArray(value.connections) ? value.connections : null;
+      const shape = connectionShapeProblems(list, value.apps);
+      if (shape.length) bad.push(...shape);
+      else {
+        if (new Set(list.map((connection) => connection.name)).size !== list.length) bad.push('connections names must be unique');
+        for (const a of list) for (const b of list) if (a !== b && `${b.envPrefix}_`.startsWith(`${a.envPrefix}_`)) bad.push(`connections ${a.name} and ${b.name} share env keys (${a.envPrefix}_ covers ${b.envPrefix}_)`);
+      }
+    }
+  }
+  return bad;
+}

package/runtime/scripts/hfs/declaration-slots.mjs

@@ -0,0 +1,75 @@
+// declaration-slots.mjs - how an app declaration (hfs.json) switches on the opt-in slots of a side: by name (`optionalSlots`), by app kind
+// (a slot with `appKind`) and by declared pattern (a slot with `pattern: <name>` is enabled by `sides.<side>.patterns: [<name>]`, one
+// mechanism for every pattern: saga, event-bus, fenced-job, ...). slots.mjs asks this file to judge a side's lists and to say whether a
+// slot is enabled for a repository.
+
+/** The problems of a side's `optionalSlots` and `patterns` against the manifest. */
+export function optionalSlotProblems(manifest, side, s) {
+  const bad = [];
+  for (const id of s.optionalSlots ?? []) {
+    const slot = manifest.slots.find((candidate) => candidate.id === id);
+    if (!slot || !slot.profiles.includes(side)) bad.push(`sides.${side}.optionalSlots names ${id}, which is not a ${side} slot`);
+    else if (slot.presence !== 'opt-in') bad.push(`sides.${side}.optionalSlots names ${id}, which is ${slot.presence}, not opt-in`);
+    else if (slot.appKind !== undefined) bad.push(`sides.${side}.optionalSlots names ${id}; an app of kind ${slot.appKind} enables it`);
+  }
+  for (const name of s.patterns ?? []) {
+    if (!manifest.slots.some((slot) => slot.profiles.includes(side) && slot.pattern === name)) bad.push(`sides.${side}.patterns names ${name}, which no ${side} slot declares as its pattern`);
+  }
+  if (s.kinds !== undefined && side !== 'be') bad.push(`sides.${side}.kinds belongs to the be side`);
+  for (const kind of s.kinds ?? []) {
+    if (!(manifest.triggerKinds ?? []).includes(kind)) bad.push(`sides.${side}.kinds names ${kind}, which is not one of triggerKinds (${(manifest.triggerKinds ?? []).join(', ')})`);
+  }
+  return bad;
+}
+
+/** The problems of the shape of a side's `patterns` list (a unique list of pattern names). */
+export function patternShapeProblems(s, at, namePattern) {
+  const list = s.patterns;
+  if (list === undefined) return [];
+  return Array.isArray(list) && list.every((value) => namePattern.test(String(value))) && new Set(list).size === list.length ? [] : [`${at}.patterns must be a unique list of pattern names`];
+}
+
+/** The problems of the shape of a side's `kinds` list (a unique list of trigger kind names). */
+export function kindShapeProblems(s, at, namePattern) {
+  const list = s.kinds;
+  if (list === undefined) return [];
+  return Array.isArray(list) && list.every((value) => namePattern.test(String(value))) && new Set(list).size === list.length ? [] : [`${at}.kinds must be a unique list of trigger kind names`];
+}
+
+/** The problems of `ruleParams.be.kindPatterns` (trigger kind -> patterns) and `ruleParams.be.addKinds` (starci app add noun -> {topic, variable, patterns, trigger?, needs?, also?, defaults?, wire?}). */
+export function kindParamProblems(be, triggerKinds) {
+  const kebab = /^[a-z][a-z0-9-]*$/;
+  const names = (list) => Array.isArray(list) && list.every((value) => kebab.test(String(value))) && new Set(list).size === list.length;
+  const bad = [];
+  const patterns = be.kindPatterns;
+  if (patterns === null || typeof patterns !== 'object' || Array.isArray(patterns) || !Object.entries(patterns).every(([kind, list]) => (triggerKinds ?? []).includes(kind) && names(list))) bad.push('ruleParams.be.kindPatterns must map a trigger kind to a unique list of pattern names');
+  const nouns = be.addKinds;
+  const nounOk = (spec) => spec !== null && typeof spec === 'object' && kebab.test(String(spec.topic)) && kebab.test(String(spec.variable)) && names(spec.patterns) && (spec.trigger === undefined || kebab.test(String(spec.trigger))) && (spec.needs === undefined || names(spec.needs)) && (spec.also === undefined || names(spec.also)) && (spec.defaults === undefined || (typeof spec.defaults === 'object' && !Array.isArray(spec.defaults))) && (spec.wire === undefined || (spec.wire !== null && typeof spec.wire === 'object' && ['file', 'import', 'symbol'].every((key) => typeof spec.wire[key] === 'string' && spec.wire[key] !== '')));
+  if (nouns === null || typeof nouns !== 'object' || Array.isArray(nouns) || !Object.entries(nouns).every(([noun, spec]) => kebab.test(noun) && nounOk(spec))) bad.push('ruleParams.be.addKinds must map a noun to {topic, variable, patterns, trigger?, needs?, also?, defaults?}');
+  return bad;
+}
+
+/** The problems of `ruleParams.be.patternScenarios`: a pattern name to a non-empty list of unique kebab-case scenario ids. */
+export function scenarioProblem(scenarios) {
+  const kebab = /^[a-z][a-z0-9-]*$/;
+  const ok = scenarios !== null && typeof scenarios === 'object' && !Array.isArray(scenarios) && Object.entries(scenarios).every(([name, list]) => kebab.test(name) && Array.isArray(list) && list.length > 0 && list.every((id) => kebab.test(String(id))) && new Set(list).size === list.length);
+  return ok ? [] : ['ruleParams.be.patternScenarios must map a pattern name to a non-empty list of unique kebab-case scenario ids'];
+}
+
+/** The problems of the `trigger` of a slot against the manifest's `triggerKinds`: a known kind, on a feature-tier slot only. */
+export function triggerProblems(slot, triggerKinds) {
+  if (slot.trigger === undefined) return [];
+  const bad = [];
+  if (!(triggerKinds ?? []).includes(slot.trigger)) bad.push(`slot ${slot.id}: trigger ${slot.trigger} is not one of triggerKinds`);
+  if (slot.tier !== 'feature') bad.push(`slot ${slot.id}: a trigger belongs to a feature-tier slot`);
+  return bad;
+}
+
+/** Whether an opt-in slot is enabled for the repository: by its app kind, by a connection's provider, by name in optionalSlots, or by its declared pattern. */
+export function declaredSlotEnabled(slot, repo) {
+  if (slot.appKind !== undefined) return repo.apps.some((app) => app.kind === slot.appKind);
+  // A provider declared on any connection (be owns them all today) enables the provider slots of every profile: repo.providers
+  // is the app-wide union the declaration resolver computed; a hand-built repo falls back to its own connections.
+  if (slot.provider !== undefined) return (repo.providers ?? (repo.connections ?? []).map((connection) => connection.provider)).includes(slot.provider);
+  return repo.optionalSlots.includes(slot.id) || (slot.pattern !== undefined && (repo.patterns ?? []).includes(slot.pattern));
+}

package/runtime/scripts/hfs/edition-slots.mjs

@@ -0,0 +1,66 @@
+// edition.mjs - the one edition filter shared by the HFS slot resolver, declaration validation, rule catalog and
+// edition-specific rule parameters. Full is the default; lite changes data views, never the checks that consume them.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { EDITIONS } from './manifest-shape.mjs';
+
+/** The presence of `slot` under edition lite for `profile`: `litePresence`, else the slot's own presence. */
+export function litePresenceOf(slot, profile) {
+  const lp = slot.litePresence;
+  if (lp === undefined) return slot.presence;
+  return isPlainObject(lp) ? (lp[profile] ?? slot.presence) : lp;
+}
+
+/** Whether `slot` exists under `edition` of `manifest` (default: the manifest's own editions). */
+export function slotInEdition(manifest, slot, edition) {
+  return (slot.editions ?? manifest.editions ?? EDITIONS).includes(edition);
+}
+
+/** The slot as `edition` sees it: lite overlays its data, presence and tracking while forbidding every test world. */
+export function effectiveSlot(slot, profile, edition) {
+  if (edition !== 'lite') return slot;
+  const { lite, litePresence, ...base } = slot;
+  const presence = litePresenceOf(slot, profile);
+  const tracked = presence === 'forbidden' ? 'external' : (slot.tracked === 'external' ? 'tracked' : slot.tracked);
+  return { ...base, ...(lite ?? {}), presence, tracked, tests: 'none' };
+}
+
+/** The template group starci app sync renders `slot` from under `edition`: `liteManagedBy` (else `managedBy`) in lite, `managedBy` otherwise; undefined when unmanaged. */
+export function managedGroupOf(slot, edition) {
+  return edition === 'lite' ? (slot.liteManagedBy ?? slot.managedBy) : slot.managedBy;
+}
+
+/** The declared edition and the vocabulary against which it is validated. */
+export function declarationEdition(manifest, declaration) {
+  const edition = declaration.edition === undefined ? 'full' : declaration.edition;
+  const known = manifest.editions ?? EDITIONS;
+  return { edition, known, valid: known.includes(edition) };
+}
+
+/** Problems of an optional rule-catalog `editions` list, in the catalog schema's words. */
+export function ruleEditionProblems(rule, label) {
+  if (rule.editions === undefined) return [];
+  const bad = [];
+  if (!Array.isArray(rule.editions) || !rule.editions.length) return [`${label}.editions must be a non-empty list`];
+  for (const value of rule.editions) if (!EDITIONS.includes(value)) bad.push(`${label}.editions has ${JSON.stringify(value)}, not one of ${EDITIONS.join(', ')}`);
+  if (new Set(rule.editions).size !== rule.editions.length) bad.push(`${label}.editions repeats a value`);
+  return bad;
+}
+
+/** Whether a catalogued rule owner judges its finding under `edition`; uncatalogued codes always remain judged. */
+export function judgedInEdition(owner, edition = 'full') {
+  return !owner?.editions || owner.editions.includes(edition);
+}
+
+/** Whether the enforcer `kind:id` of the catalog `rules` runs under `edition`: every rule listing it is judged there, and the enforcer row's own `editions` (a rule with several enforcers where only one is full-only) agrees. A lint rule no rule lists runs everywhere. */
+export function enforcerJudgedInEdition(rules, kind, id, edition = 'full') {
+  const owners = rules.filter((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id));
+  return owners.every((rule) => judgedInEdition(rule, edition) && rule.enforcers.filter((enforcer) => enforcer.kind === kind && enforcer.id === id).every((enforcer) => judgedInEdition(enforcer, edition)));
+}
+
+/** A frozen copy of one profile's parameters, with its lite overrides applied only in the lite edition. */
+export function editionRuleParams(params, edition) {
+  const { lite, ...base } = params;
+  const merged = edition === 'lite' && lite ? { ...base, ...lite } : base;
+  const deepFreeze = (value) => { if (value && typeof value === 'object') Object.values(value).forEach(deepFreeze); return Object.freeze(value); };
+  return deepFreeze(structuredClone(merged));
+}