@starci/eslint-canon-fe 8.2.18 → 8.4.0

package/runtime/knowledge/patterns/fe/folder.yaml

@@ -174,6 +174,9 @@ rules:
       component.tsx. Pure blocks, composites, branches and leaves use index.tsx only and never gain an
       empty twin. classNames.ts is present only when the unit owns class strings. Budgets: component.tsx 300 lines,
       connected index.tsx 200 lines, at most 6 data hooks and 6 useState per connected unit.
+      A composition-only feature may render an existing public pure component owner directly instead of creating a
+      forwarding component.tsx. The route-state overlay host of FE-BOUNDARY-5 renders components/branches/OverlayHost;
+      a connected block still requires its exact private Base twin.
     rationale: |
       Stable basenames make class names and the connected and presentational split discoverable without forwarding
       twins, and budgets keep a unit reviewable.
@@ -303,6 +306,7 @@ rules:
       envelope, the generated wire types (from be/contracts/, through the root codegen) and the axios calls live in
       modules/api; the session lives in modules/auth; mutation feedback in modules/toast; environment reading in
       modules/config; every href builder in modules/routes; locale routing in modules/i18n; colour values in modules/brand.
+      Only hooks/swr imports the API transport operations; feature owners and other hooks consume those SWR hooks.
       A helper name defined twice across hook files is a finding.
     rationale: |
       A rule that says what a hooks folder is also says where everything else goes, so nobody copies a helper sixteen

package/runtime/knowledge/sonar-gate.yaml

@@ -82,7 +82,7 @@ overall:
     rule: typescript:S3776
     via: overall.issues
 # Lite is the same quality policy, coverage included: a lite back end keeps full's unit run and its 100 per file on the measured
-# logic files (owner ruling 2026-10-12, R212 case-1). Readers select this block from hfs.json edition; the gate keeps its own
+# logic files (owner ruling 2026-10-12, R212 case-1 (owner:lite-production-swarm), with the Work boundary amended by ruling:R212/case-4). Readers select this block from hfs.json edition; the gate keeps its own
 # name so a lite project's server gate stays a separate object, and every threshold below equals full's.
 lite:
   gate:

package/runtime/modules/models/runtimes.yaml

@@ -351,7 +351,7 @@ allocation:
   # process keeps the lock regardless of age.
   housekeeping:
     tmpMaxAgeMs: 172800000
-    tmpPrefixes: [policy-, rights-, l4-, starci, starci-w2, evidence, sup-k, work-v3, scoped-lint, si-, w1-, nivo-, orca-spec,
+    tmpPrefixes: [coverage-generated-wire-, work-validate-lite-, example-refs-lite-, example-lite-, coverage-inventory-, policy-, rights-, l4-, starci, starci-w2, evidence, sup-k, work-v3, scoped-lint, si-, w1-, nivo-, orca-spec,
       owner-bias-cli-, admission-runtime-, agent-launch-, starci-provider-budget-, starci-provider-schema-,
       codex-, deps-, direction-part-, draw-layer-, footprint-, grammar-pin-, guard-, literal-argv-, module-yaml-,
       doc-language-, guidance-, hk-, hfs-, install-link-, kernel-check-, kguard-, sup-orca, land-, op-manifest-, path-key-, pathspec-, push-scan-spec-, rename-over-, sbl-, serve-ask-, sup-chat, sup-repo, sup-src, sup-wd,

package/runtime/packages/hfs/templates/app/package-scripts/package.json

@@ -10,6 +10,7 @@
     "test:e2e": "npm run typecheck:tests && cd be && jest --selectProjects e2e",
     "test:contract": "npm run typecheck:tests && cd be && jest --selectProjects contract",
     "test:stack": "starci app stack",
+{{supabaseScripts}}
     "contract:emit": "starci app emit"
   }
 }

package/runtime/scripts/api/git/cat-file.mjs

@@ -0,0 +1,5 @@
+// cat-file.mjs — `git cat-file <args>`: the type, size or content of repository objects (-e, -p, --batch).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git cat-file ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const catFile = (args = [], options = {}) => runGit(['cat-file', ...args], options);

package/runtime/scripts/api/git/diff.mjs

@@ -0,0 +1,5 @@
+// diff.mjs — `git diff <args>`: the changes between commits, the index and the working tree.
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git diff ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const diff = (args = [], options = {}) => runGit(['diff', ...args], options);

package/runtime/scripts/api/git/lib.mjs

@@ -75,3 +75,6 @@ export const gitExecutable = (options = null) => {
   if (!options) cachedGit = found;
   return found;
 };
+
+/** The output ceiling of the whole-diff and `cat-file --batch` calls `test affected` batches (a release diff is tens of megabytes). */
+export const BATCH_MAX_BUFFER = 1024 * 1024 * 1024;

package/runtime/scripts/api/git/merge-base.mjs

@@ -0,0 +1,9 @@
+// merge-base.mjs — `git merge-base <a> <b>`: the best common ancestor of two commits. Whether one commit is in another
+// is is-ancestor.mjs.
+import { gitRunner } from './lib.mjs';
+
+/** The best common ancestor of commits `a` and `b` (a sha), or null when they share none or a ref does not resolve. */
+export const mergeBase = (cwd, a, b, { git = null } = {}) => {
+  const r = gitRunner(git)(['merge-base', a, b], { cwd });
+  return r.ok && r.stdout ? r.stdout : null;
+};

package/runtime/scripts/api/git/recorded-lines.mjs

@@ -1,19 +1,65 @@
 // recorded-lines.mjs - the line count a file had at a git revision (git show <ref>:<file>): the recorded size a
 // size-growth rule compares the working file with.
 import path from 'node:path';
+import { existsSync } from 'node:fs';
 import { runGit } from './lib.mjs';
+import { mergeBase } from './merge-base.mjs';
+import { withoutGitLocalEnv } from '../../lib/git.mjs';
 import { lineCount } from '../../lib/line-count.mjs';
+import { readEnv } from '../../lib/env.mjs';
+import { folded } from '../../lib/event-contract.mjs';
+
+const ok = (result) => !result.error && result.status === 0;
+const pathKey = (value) => process.platform === 'win32' ? value.toLowerCase() : value;
+
+/** A commit hook exports an index; HEAD applies only to a staged file whose lint text is that index's text. */
+function lintingIndex(dir, name, source) {
+  const indexFile = readEnv('GIT_INDEX_FILE');
+  if (!indexFile || typeof source !== 'string') return false;
+  const options = { dir, env: withoutGitLocalEnv(process.env), maxBuffer: 64 * 1024 * 1024 };
+  const index = runGit(['rev-parse', '--path-format=absolute', '--git-path', 'index'], options);
+  const root = runGit(['rev-parse', '--show-toplevel'], options);
+  if (!ok(index) || !ok(root)) return false;
+  // The hook's relative index path is relative to the repository root even after xargs changes to be/ or fe/.
+  const hookIndex = path.resolve(root.stdout.trim(), indexFile);
+  if (pathKey(path.dirname(hookIndex)) !== pathKey(path.dirname(path.resolve(index.stdout.trim())))) return false;
+  const stagedOptions = { ...options, env: { ...options.env, GIT_INDEX_FILE: hookIndex } };
+  const changed = runGit(['diff', '--cached', '--relative', '--name-only', '-z', '--', `./${name}`], stagedOptions);
+  if (!ok(changed) || !changed.stdout.split('\0').includes(name)) return false;
+  const staged = runGit(['show', `:./${name}`], stagedOptions);
+  return ok(staged) && folded(staged.stdout) === folded(source);
+}
+
+function recordedRef(dir, name, source) {
+  if (lintingIndex(dir, name, source)) return 'HEAD';
+  const base = readEnv('STARCI_BASE_REF');
+  for (const ref of base ? [base] : ['origin/main', 'main']) {
+    const sha = mergeBase(dir, 'HEAD', ref);
+    if (sha) return sha;
+  }
+  return null;
+}
 
 /**
- * The line count of a file at a git revision, or null when the file did not exist there or git is absent.
+ * The line count at the branch's merge base, null for a confirmed new file, or `unavailable` for unreadable history.
+ * Only lint text matching a changed file in a commit hook's index is compared with HEAD. Explicit revision strings
+ * remain supported for callers that request a particular revision rather than the lint baseline.
  *
  * @param {string} filename - Absolute path of the file.
- * @param {string} ref - The revision, `HEAD` by default (the parent of the commit being made).
- * @returns {number | null} The recorded line count.
+ * @param {object | string} options - `{ source }` from ESLint, or an explicit revision.
+ * @returns {number | null | 'unavailable'} The recorded line count or the reason it cannot be compared.
  */
-export const recordedLines = (filename, ref = 'HEAD') => {
-  const r = runGit(['show', `${ref}:./${path.basename(filename)}`], { dir: path.dirname(filename), maxBuffer: 64 * 1024 * 1024 });
-  // no repository, no such revision, or a new file: all mean there is no recorded size to compare with
-  if (r.error || r.status !== 0) return null;
-  return lineCount(r.stdout);
+export const recordedLines = (filename, options = {}) => {
+  const absolute = path.resolve(filename);
+  let dir = path.dirname(absolute);
+  while (!existsSync(dir) && path.dirname(dir) !== dir) dir = path.dirname(dir);
+  const name = path.relative(dir, absolute).split(path.sep).join('/');
+  const ref = typeof options === 'string' ? options : recordedRef(dir, name, options.source);
+  if (!ref) return 'unavailable';
+  const gitOptions = { dir, maxBuffer: 64 * 1024 * 1024 };
+  const files = runGit(['ls-tree', '--name-only', '-z', ref, '--', `./${name}`], gitOptions);
+  if (!ok(files)) return 'unavailable';
+  if (!files.stdout.split('\0').includes(name)) return null;
+  const recorded = runGit(['show', `${ref}:./${name}`], gitOptions);
+  return ok(recorded) ? lineCount(recorded.stdout) : 'unavailable';
 };

package/runtime/scripts/hfs/architecture/backend-app-files.mjs

@@ -0,0 +1,103 @@
+import path from 'node:path';
+import { allowsFile } from '../allows.mjs';
+import { relativePath, unwrapExpression } from './typescript.mjs';
+import { accessName, sourceLocation } from '../../lib/ts-ast.mjs';
+
+const PROCESS_MODULES = new Set(['process', 'node:process']);
+const PROCESS_GLOBAL = new Set(['process']);
+const GLOBAL_HOLDERS = new Set(['globalThis', 'global']);
+const REFLECT_GLOBAL = new Set(['Reflect']);
+
+function bindingName(ts, element) {
+  const name = element.propertyName ?? element.name;
+  if (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) return name.text;
+  return ts.isComputedPropertyName(name) && ts.isStringLiteralLike(name.expression) ? name.expression.text : null;
+}
+
+/** A global name is not a same-named local variable or parameter. */
+function isGlobalName(ts, checker, node, names) {
+  if (!ts.isIdentifier(node) || !names.has(node.text)) return false;
+  const declarations = checker?.getSymbolAtLocation(node)?.getDeclarations() ?? [];
+  return declarations.every(declaration => declaration.getSourceFile().isDeclarationFile);
+}
+
+function recordProcessBindings(ts, clause, add, report) {
+  if (clause?.name) add(clause.name);
+  const bindings = clause?.namedBindings;
+  if (bindings && ts.isNamespaceImport(bindings)) add(bindings.name);
+  if (!bindings || !ts.isNamedImports(bindings)) return;
+  for (const element of bindings.elements) {
+    const name = (element.propertyName ?? element.name).text;
+    if (name === 'env') report(element);
+    else if (name === 'default') add(element.name);
+  }
+}
+
+function processImportSymbols(ts, checker, sourceFile, report) {
+  const imports = new Set();
+  const add = name => {
+    const symbol = checker.getSymbolAtLocation(name);
+    if (symbol) imports.add(symbol);
+  };
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier)
+      || !PROCESS_MODULES.has(statement.moduleSpecifier.text)) continue;
+    recordProcessBindings(ts, statement.importClause, add, report);
+  }
+  return imports;
+}
+
+/** Process bindings are resolved by symbol, so a nested parameter cannot masquerade as an imported process. */
+function processAccess(ts, checker, sourceFile, report) {
+  const imports = processImportSymbols(ts, checker, sourceFile, report);
+  const isProcess = expression => {
+    const node = unwrapExpression(ts, expression);
+    if (!node) return false;
+    if (ts.isIdentifier(node)) return imports.has(checker.getSymbolAtLocation(node))
+      || isGlobalName(ts, checker, node, PROCESS_GLOBAL);
+    return accessName(ts, node) === 'process'
+      && isGlobalName(ts, checker, node.expression, GLOBAL_HOLDERS);
+  };
+  return node => {
+    if (accessName(ts, node) === 'env' && isProcess(node.expression)) report(node);
+    if (ts.isVariableDeclaration(node) && node.initializer && isProcess(node.initializer) && ts.isObjectBindingPattern(node.name)
+      && node.name.elements.some(element => bindingName(ts, element) === 'env')) report(node);
+    if (ts.isCallExpression(node) && accessName(ts, node.expression) === 'get'
+      && isGlobalName(ts, checker, node.expression.expression, REFLECT_GLOBAL)
+      && isProcess(node.arguments[0]) && node.arguments[1] && ts.isStringLiteralLike(node.arguments[1]) && node.arguments[1].text === 'env') report(node);
+  };
+}
+
+/** The declaration, rather than the caller's name, identifies EnvSource readers and configuration helpers. */
+function appEnvironmentCall(config, ts, checker, call) {
+  const declaration = checker.getResolvedSignature(call)?.declaration;
+  if (!declaration) return false;
+  const relative = relativePath(config.root, declaration.getSourceFile().fileName);
+  if (ts.isMethodDeclaration(declaration) && ts.isClassDeclaration(declaration.parent) && declaration.parent.name?.text === 'EnvSource') {
+    return config.hfs.tierOf(relative) === 'platform' && path.posix.basename(config.hfs.ownerOf(relative)?.root ?? '') === 'config';
+  }
+  if (!ts.isFunctionDeclaration(declaration) && !ts.isArrowFunction(declaration) && !ts.isFunctionExpression(declaration)) return false;
+  return allowsFile(config.hfs, relative)?.entry === '<app>.env.ts'
+    || (path.posix.basename(relative).endsWith('.config.ts') && config.hfs.slotOf(relative) !== null);
+}
+
+/** Composition groups and options consume parsed options; only the app's matching env role and main read them. */
+export function checkApplicationEnvironment(config, context, sourceFile, fileName, violations) {
+  const role = allowsFile(config.hfs, relativePath(config.root, fileName));
+  if (role?.allowed && (role.entry === 'main.ts' || role.entry === '<app>.env.ts')) return;
+  const { ts } = context;
+  const checker = context.checkerFor(fileName);
+  const report = node => violations.push({
+    ruleId: 'BE_APP_COMPOSITION_ONLY',
+    path: relativePath(config.root, fileName),
+    ...sourceLocation(sourceFile, node),
+    message: "Application environment reads live in main.ts or the matching <app>.env.ts. Options files and compose/<area>.ts receive the typed result of read<App>Env(env: EnvSource).",
+  });
+  const checkProcess = processAccess(ts, checker, sourceFile, report);
+  const visit = node => {
+    checkProcess(node);
+    if (ts.isCallExpression(node) && appEnvironmentCall(config, ts, checker, node)) report(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+}

package/runtime/scripts/hfs/architecture/backend.mjs

@@ -1,8 +1,9 @@
 import path from 'node:path';
 import { isInside } from './config.mjs';
-import { slotAdmitsFile } from '../allows.mjs';
+import { allowsFile, slotAdmitsFile } from '../allows.mjs';
 import { reachableViolation, relativePath } from './typescript.mjs';
-import { sourceLocation } from '../../lib/ts-ast.mjs';
+import { checkApplicationEnvironment } from './backend-app-files.mjs';
+import { accessName, sourceLocation } from '../../lib/ts-ast.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 
 const FORBIDDEN_APP_ROLE = /(?:^|\.)(?:service|provider|providers|resolver|controller|handler|repository|entity|use-case|command|query|listener|consumer|processor)\.[cm]?[jt]sx?$/i;
@@ -176,15 +177,10 @@ function requiredSpecifier(ts, call) {
     : null;
 }
 
-const requiredMemberSelection = (ts, node) => {
-  if (ts.isPropertyAccessExpression(node)) return node.name.text;
-  return ts.isStringLiteralLike(node.argumentExpression) ? node.argumentExpression.text : null;
-};
-
 function requiredMemberEvidence(ts, node, found) {
   if (!(ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) || !ts.isCallExpression(node.expression)) return;
   const specifier = requiredSpecifier(ts, node.expression);
-  const selected = requiredMemberSelection(ts, node);
+  const selected = accessName(ts, node);
   const member = ts.isPropertyAccessExpression(node) ? node.name : node.argumentExpression;
   if (specifier && TRANSPORT_PACKAGES.test(specifier)) {
     found.push({ node: member, specifier, detail: `${selected ?? 'computed member'} from ${specifier}` });
@@ -376,11 +372,23 @@ function checkApplicationComposition(config, ts, sourceFile, fileName, app, viol
       path: relativePath(config.root, fileName),
       line: 1,
       column: 1,
-      message: `Application source ${app.relative} is not a file its app slot requires or allows (main.ts, app.module.ts, <app>.options.ts).`,
+      message: `Application source ${app.relative} is not a file its app slot requires or allows (main.ts, app.module.ts, <app>.env.ts, <app>.options.ts, compose/<area>.ts).`,
     });
   }
 }
 
+/** The app's environment parser never depends on features, even through a type import or an internal barrel. */
+function checkApplicationEnvEdges(config, context, fileName, violations) {
+  const role = allowsFile(config.hfs, relativePath(config.root, fileName));
+  if (!role?.allowed || role.entry !== '<app>.env.ts') return;
+  const isFeature = target => config.hfs.tierOf(relativePath(config.root, target)) === 'feature';
+  for (const edge of context.edges.get(fileName) ?? []) {
+    const featureChain = reachableViolation(context.edges, edge, isFeature);
+    if (featureChain) violations.push(finding(config, edge, 'BE_APP_COMPOSITION_ONLY',
+      'The app environment file holds typed, fail-fast environment parsing only; it cannot depend on features, including through a type import or an internal barrel.', featureChain));
+  }
+}
+
 function checkApplicationTransport(config, context, sourceFile, fileName, violations) {
   for (const evidence of transportFrameworkEvidence(context.ts, sourceFile, context.checkerFor(fileName))) {
     violations.push({
@@ -409,7 +417,11 @@ function checkBackendSource(config, context, sourceFiles, roots, sourceFile, vio
   const fromFeatures = insideAny(featureRoots, fileName);
   const fromApplication = fromFeatures && insideFeatureLayer(featureRoots, fileName, 'application');
   const app = !fromModules && !fromFeatures ? appSource(config, fileName, nonAppRoots) : null;
-  if (app) checkApplicationComposition(config, context.ts, sourceFile, fileName, app, violations);
+  if (app) {
+    checkApplicationComposition(config, context.ts, sourceFile, fileName, app, violations);
+    checkApplicationEnvEdges(config, context, fileName, violations);
+    checkApplicationEnvironment(config, context, sourceFile, fileName, violations);
+  }
   if (!fromModules && !fromFeatures) return;
   if (fromApplication) checkApplicationTransport(config, context, sourceFile, fileName, violations);
   if (fromApplication) checkFeatureTransportEdges(config, context, sourceFiles, featureRoots, fileName, violations);

package/runtime/scripts/hfs/architecture/background-unowned.mjs

@@ -5,30 +5,45 @@ import { machineKit } from './machine-ast.mjs';
  * R46 `background-unowned` (BE_BACKGROUND_UNOWNED, BE-CONVENTION 1.6 and 1.13). Background work is a transport that only
  * a worker or api app runs (an api app composes the message transport of its own service; a separate worker is opt-in):
  *
- *   - every job processor (`*.processor.ts`, the jobs kind) and consumer (`*.consumer.ts`) is composed by an app of kind `worker` or
- *     `api`: the file is reachable, through runtime imports, from the root module of some such app declared in hfs.json; one no app
- *     reaches never runs. A schedule is a BullMQ job scheduler of a queue, so no scheduler decorator or timer is judged here: `@nestjs/schedule`
- *     and the timers are owned by platform capabilities (R90 BE_INFRA_OWNER);
- *   - a method whose name is one of the words the law names (`sweep`, `deliver`, `reconcile`, `retry`, alone or as the
- *     first word of a camelCase name) in a domain, integrations or feature class is reachable from a composed processor or
- *     consumer: from the processor or consumer files and everything they import, and from the files of the feature that holds them
- *     (its handlers are registered with the command bus, not imported by the processor). Mechanisms of platform are exempt.
+ *   - a processor, consumer, scheduler, saga or event handler is composed by an app of kind `worker` or `api`: its file is
+ *     reachable, through runtime imports, from an app root declared in hfs.json. Context comes from its file role or framework
+ *     decorators, never a method name. Infrastructure restrictions on scheduler libraries remain R90 BE_INFRA_OWNER's concern;
+ *   - methods in those contexts, and methods they call transitively, are reachable from a composed background entry point:
+ *     its imports and the files of its own feature (command handlers are registered with the bus). Platform mechanisms are
+ *     exempt. Resolvers and controllers are user entry points and never background, even when called by a background method.
  *
- * Reachability is static (imports, re-exports and the feature of the processor); it proves a processor or consumer could call the method,
- * not that it does.
+ * Classification follows statically resolved calls; ownership follows runtime imports, re-exports and the entry point's feature.
  */
 export const BACKGROUND_UNOWNED_RULE_IDS = ['BE_BACKGROUND_UNOWNED'];
 
 const RULE = 'BE_BACKGROUND_UNOWNED';
-const BACKGROUND_ROLES = new Set(['processor', 'consumer']);
-/** The words the law names for background methods (knowledge/hfs/README.md 5.7). */
-const BACKGROUND_WORDS = ['sweep', 'deliver', 'reconcile', 'retry'];
+const BACKGROUND_ROLES = new Set(['processor', 'consumer', 'scheduler', 'saga', 'event-handler']);
+const USER_ROLES = new Set(['resolver', 'controller']);
+const CLASS_DECORATORS = new Map([
+  ['@nestjs/bull:Processor', 'processor'], ['@nestjs/bullmq:Processor', 'processor'],
+  ['@nestjs/cqrs:EventsHandler', 'event-handler'],
+]);
+const METHOD_DECORATORS = new Map([
+  ['@nestjs/cqrs:Saga', 'saga'], ['@nestjs/event-emitter:OnEvent', 'event-handler'],
+  ...['Cron', 'Interval', 'Timeout'].map(name => [`@nestjs/schedule:${name}`, 'scheduler']),
+]);
+const USER_DECORATORS = new Map([['@nestjs/graphql:Resolver', 'resolver'], ['@nestjs/common:Controller', 'controller']]);
 
 const roleOf = rel => {
   const parts = path.posix.basename(rel).split('.');
-  return parts.length >= 3 && parts.at(-1) === 'ts' && BACKGROUND_ROLES.has(parts.at(-2)) ? parts.at(-2) : null;
+  return parts.length >= 3 && parts.at(-1) === 'ts' ? parts.at(-2) : null;
+};
+
+const decoratedRole = (kit, checker, node, roles) => {
+  for (const decorator of kit.decorators(node)) {
+    const expression = decorator.expression;
+    const callee = kit.ts.isCallExpression(expression) ? expression.expression : expression;
+    const binding = kit.importBinding(checker, callee);
+    const role = binding ? roles.get(`${binding.module}:${binding.name}`) : null;
+    if (role) return role;
+  }
+  return null;
 };
-const isBackgroundName = name => BACKGROUND_WORDS.some(word => name === word || (name.startsWith(word) && /[A-Z]/u.test(name[word.length] ?? '')));
 
 const adjacencyOf = edges => {
   const adjacency = new Map();
@@ -60,19 +75,16 @@ const appRootsOf = (apps, graph) => {
   return { workers, composed: [...workers, ...services] };
 };
 
-const backgroundFilesOf = graph => [...graph.files.values()].filter(file => roleOf(file.rel) && file.tier === 'feature');
-
 const reportUncomposedFiles = (background, composed, workerRoots, report) => {
-  for (const file of background) {
-    if (composed.has(file.rel)) continue;
-    const role = roleOf(file.rel);
-    report(file, file.sourceFile, `${file.rel} is a ${role} that no service app composes${workerRoots.length ? '' : ' (hfs.json declares no worker app)'}; a ${role} runs only when the ${role === 'processor' ? 'job' : 'message'} module of its feature is imported by the root module of an app of kind worker or api.`, { role });
+  for (const { file, role } of background) {
+    if (file.tier === 'platform' || composed.has(file.rel)) continue;
+    report(file, file.sourceFile, `${file.rel} is a ${role} that no service app composes${workerRoots.length ? '' : ' (hfs.json declares no worker app)'}; its module must be imported by the root module of an app of kind worker or api.`, { role });
   }
 };
 
 const rootsOfRunningFeatures = (running, files) => {
   const roots = new Set();
-  for (const file of running) {
+  for (const { file } of running) {
     roots.add(file.rel);
     const owner = file.owner?.root;
     if (owner) for (const other of files.values()) if (other.owner?.root === owner) roots.add(other.rel);
@@ -80,22 +92,125 @@ const rootsOfRunningFeatures = (running, files) => {
   return roots;
 };
 
-const backgroundMethodsOf = (node, kit, ts) => node.members.flatMap(member => {
-  if (!ts.isMethodDeclaration(member) || !member.name) return [];
-  const name = kit.propertyNameText(member.name);
-  return name && isBackgroundName(name) ? [{ name, node: member.name }] : [];
-});
+const callableKey = (kit, node) => `${kit.graphPath(node)}:${node.getStart()}`;
+const callableBody = (ts, declaration) => {
+  const node = declaration.initializer ?? declaration;
+  return ts.isFunctionLike(node) && node.body ? node : null;
+};
+const methodMember = (ts, node) => {
+  if (ts.isMethodDeclaration(node)) return node;
+  return ts.isPropertyDeclaration(node.parent) && node.parent.initializer === node ? node.parent : null;
+};
 
-const checkBackgroundMethods = ({ graph, kit, ts, reachable, report }) => {
-  let methods = 0;
-  const reportMethod = (file, method) => {
-    methods += 1;
-    if (!reachable.has(file.rel)) report(file, method.node, `${method.name} is background work (a ${BACKGROUND_WORDS.join(', ')} method) that no processor or consumer composed by a worker or api app can reach. Add a processor in features/jobs/<job> or a consumer in transport/message of a feature that runs it, and compose its module in a worker or api app.`, { method: method.name });
-  };
+const isUserClass = (kit, checker, node) => USER_ROLES.has(roleOf(kit.graphPath(node) ?? ''))
+  || Boolean(decoratedRole(kit, checker, node, USER_DECORATORS));
+
+const seedClass = (scope, file, checker, node, role) => {
+  scope.background.set(file.rel, { file, role });
+  scope.contextFiles.add(file.rel);
+  for (const symbol of checker.getTypeAtLocation(node).getProperties()) {
+    for (const declaration of symbol.declarations ?? []) {
+      const body = callableBody(scope.kit.ts, declaration);
+      if (body) scope.inherited.push(body);
+    }
+  }
+};
+
+const classContext = (scope, file, checker, node, state) => {
+  const user = state.user || isUserClass(scope.kit, checker, node);
+  if (!state.nested && user) scope.userFiles.add(file.rel);
+  let classRole = null;
+  if (!state.nested && !user) {
+    const fileRole = BACKGROUND_ROLES.has(state.fileRole) ? state.fileRole : null;
+    classRole = decoratedRole(scope.kit, checker, node, CLASS_DECORATORS) ?? fileRole;
+  }
+  if (classRole) seedClass(scope, file, checker, node, classRole);
+  return { ...state, user, classRole };
+};
+
+const recordCallable = (scope, file, checker, node, state) => {
+  const { kit } = scope;
+  const member = methodMember(kit.ts, node);
+  const canSeed = member && !state.user && !state.nested;
+  const role = canSeed ? decoratedRole(kit, checker, member, METHOD_DECORATORS) ?? state.classRole : null;
+  const entry = { file, node, checker, user: state.user, member, name: member ? kit.propertyNameText(member.name) : null };
+  scope.callables.set(callableKey(kit, node), entry);
+  if (role) {
+    scope.background.set(file.rel, { file, role });
+    scope.contextFiles.add(file.rel);
+    scope.seeds.push(entry);
+  }
+};
+
+const indexCallables = (scope, file, checker, node, state) => {
+  const { ts } = scope.kit;
+  if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) state = classContext(scope, file, checker, node, state);
+  const callable = ts.isFunctionLike(node);
+  if (callable && node.body) recordCallable(scope, file, checker, node, state);
+  const childState = { ...state, nested: state.nested || callable };
+  ts.forEachChild(node, child => indexCallables(scope, file, checker, child, childState));
+};
+
+/** Index callable bodies once; a resolver/controller is a barrier to background propagation. */
+const backgroundContextOf = (graph, kit) => {
+  const callables = new Map();
+  const background = new Map();
+  const seeds = [];
+  const inherited = [];
+  const scope = { kit, callables, background, seeds, inherited, userFiles: new Set(), contextFiles: new Set() };
   for (const file of graph.files.values()) {
-    if (file.tier === 'platform') continue;
-    kit.walk(file.sourceFile, node => {
-      if (ts.isClassDeclaration(node)) for (const method of backgroundMethodsOf(node, kit, ts)) reportMethod(file, method);
+    const checker = kit.checkerOf(file.sourceFile);
+    const fileRole = roleOf(file.rel);
+    if (BACKGROUND_ROLES.has(fileRole)) background.set(file.rel, { file, role: fileRole });
+    indexCallables(scope, file, checker, file.sourceFile, { fileRole, classRole: null, user: USER_ROLES.has(fileRole), nested: false });
+  }
+  // Request context overrides a file suffix; mixed files can still hold a separate background class.
+  for (const rel of scope.userFiles) if (!scope.contextFiles.has(rel)) background.delete(rel);
+  for (const body of inherited) {
+    const entry = callables.get(callableKey(kit, body));
+    if (entry) seeds.push(entry);
+  }
+  return { callables, background: [...background.values()], seeds };
+};
+
+const calledBodies = (kit, checker, call) => {
+  const { ts } = kit;
+  const expression = call.expression;
+  if (ts.isPropertyAccessExpression(expression) || ts.isElementAccessExpression(expression)) {
+    const receiver = checker.getNonNullableType(checker.getTypeAtLocation(expression.expression));
+    if (receiver.getSymbol()?.declarations?.some(declaration => isUserClass(kit, checker, declaration))) return [];
+  }
+  const target = ts.isPropertyAccessExpression(expression) ? expression.name : expression;
+  const declarations = [...kit.declarationsOf(checker, target)];
+  const signature = checker.getResolvedSignature(call)?.declaration;
+  if (signature) declarations.push(signature);
+  return declarations.map(declaration => callableBody(ts, declaration)).filter(Boolean);
+};
+
+const checkBackgroundMethods = ({ kit, context, reachable, report }) => {
+  const { callables, seeds } = context;
+  const seen = new Set();
+  const queue = [...seeds];
+  let methods = 0;
+  while (queue.length) {
+    const entry = queue.pop();
+    const { file, node, checker, user, member, name } = entry;
+    const key = callableKey(kit, node);
+    if (user || seen.has(key)) continue;
+    seen.add(key);
+    if (name && file.tier !== 'platform') {
+      methods += 1;
+      if (!reachable.has(file.rel)) report(file, member.name, `${name} is background work that no background entry point composed by a worker or api app can reach. Compose the processor, consumer, scheduler, saga or event handler that runs it in a worker or api app.`, { method: name });
+    }
+    kit.walk(node.body, inner => {
+      // Nested bodies run only through a resolved call or when passed as a callback.
+      if (kit.ts.isFunctionLike(inner) || kit.ts.isClassDeclaration(inner) || kit.ts.isClassExpression(inner)) return false;
+      if (!kit.ts.isCallExpression(inner)) return;
+      const callbacks = inner.arguments.filter(argument => kit.ts.isArrowFunction(argument) || kit.ts.isFunctionExpression(argument));
+      for (const body of [...calledBodies(kit, checker, inner), ...callbacks]) {
+        const called = callables.get(callableKey(kit, body));
+        if (called) queue.push(called);
+      }
     });
   }
   return methods;
@@ -104,7 +219,7 @@ const checkBackgroundMethods = ({ graph, kit, ts, reachable, report }) => {
 export function checkBackgroundUnowned(input) {
   const { graph } = input;
   const kit = machineKit(input);
-  const { ts, resolver } = kit;
+  const { resolver } = kit;
   const violations = [];
   const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
 
@@ -112,13 +227,14 @@ export function checkBackgroundUnowned(input) {
   const closure = starts => closureOf(adjacency, starts);
   const { workers: workerRoots, composed: appRoots } = appRootsOf(resolver.repo.apps, graph);
   const composed = closure(appRoots);
-  const background = backgroundFilesOf(graph);
-  const running = background.filter(file => composed.has(file.rel));
+  const context = backgroundContextOf(graph, kit);
+  const { background } = context;
+  const running = background.filter(({ file }) => composed.has(file.rel));
   reportUncomposedFiles(background, composed, workerRoots, report);
 
-  // Everything a composed processor or consumer can reach: its imports, and the files of its own feature (command handlers).
+  // Everything a composed background entry point can reach: its imports and its own feature's command handlers.
   const roots = rootsOfRunningFeatures(running, graph.files);
   const reachable = closure([...roots]);
-  const methods = checkBackgroundMethods({ graph, kit, ts, reachable, report });
+  const methods = checkBackgroundMethods({ kit, context, reachable, report });
   return { violations, coverage: { status: 'checked', workers: workerRoots.length, jobsAndConsumers: background.length, composed: running.length, backgroundMethods: methods } };
 }