@starci/eslint-canon-be 3.2.18 → 3.3.0

package/runtime/scripts/hfs/architecture/i18n-keys.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { byCodeUnit } from '../../lib/list.mjs';
+import { escapeRegExp } from '../../lib/regex.mjs';
 
 /**
  * R106 `i18n-keys` (FE_I18N_KEYS). The catalogs of an app (`apps/<app>/src/modules/i18n/messages/<locale>.json`, slot fe.modules.i18n) and
@@ -12,7 +13,7 @@ import { byCodeUnit } from '../../lib/list.mjs';
  *     own source (both branches of a conditional key are read). A key no locale's catalog holds is FE_I18N_KEYS, once per call. A computed
  *     key (a template with an interpolation, a variable) is not judged here; it counts as a read.
  *   - a key nobody reads is dead: a leaf of the app's catalogs that no string in the app's or the shared packages' source can be reading.
- *     A leaf counts as read when a string literal or a template pattern (each interpolation a wildcard segment) of that source equals a
+ *     A leaf counts as read when a string literal or a template pattern (each interpolation a wildcard within its dotted segment) equals a
  *     tail of its dotted path (`"title"`, `"card.title"`, `"orders.card.title"` all read `orders.card.title`); the test is deliberately loose
  *     so a key handed through props or a table of keys is never reported, and only a key that appears nowhere is.
  *
@@ -39,7 +40,10 @@ const held = (leaves, full) => leaves.has(full) || [...leaves].some(leaf => leaf
 
 // A pattern that is only wildcards (`${a}`, `${a}.${b}`) names nothing: it would read every key, so it reads none.
 const tailMatches = (pattern, leafSegments) => pattern.some(segment => segment !== '*' && segment !== '') && pattern.length <= leafSegments.length
-  && pattern.every((segment, index) => segment === '*' || segment === leafSegments[leafSegments.length - pattern.length + index]);
+  && pattern.every((segment, index) => {
+    const leaf = leafSegments[leafSegments.length - pattern.length + index];
+    return segment instanceof RegExp ? segment.test(leaf) : segment === '*' || segment === leaf;
+  });
 
 function catalogsPerApp(config, graph) {
   const catalogs = new Map();
@@ -56,12 +60,21 @@ function catalogsPerApp(config, graph) {
   return catalogs;
 }
 
+/** Each interpolation can fill part or all of a segment; the template's static fragments keep their literal spelling. */
+function templatePatternOf(node) {
+  return [node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').split('.').map(segment => {
+    if (!segment.includes('\u0000')) return segment;
+    const parts = segment.split('\u0000');
+    return parts.every(part => part === '') ? '*' : new RegExp(`^${parts.map(escapeRegExp).join('.*')}$`, 'su');
+  });
+}
+
 function patternsOf(ts, files) {
   const patterns = [];
   for (const file of files) {
     const visit = node => {
       if (ts.isStringLiteralLike(node)) patterns.push(node.text.split('.'));
-      else if (ts.isTemplateExpression(node)) patterns.push([node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').replaceAll('\u0000', '*').split('.'));
+      else if (ts.isTemplateExpression(node)) patterns.push(templatePatternOf(node));
       ts.forEachChild(node, visit);
     };
     visit(file.sourceFile);

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

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { canonical } from './config.mjs';
 import { hasAnyFlag, sourceLocation } from '../../lib/ts-ast.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const HELPER_DEPTH = 4;
 
@@ -110,6 +111,21 @@ const at = (env, rel, sourceFile, node, extra = {}) => ({ path: rel, ...sourceLo
 /** The app root file of an app (apps/<name>/src/app.module.ts), or null when the program does not hold it. */
 const appRoot = (env, name) => graphFile(env, `apps/${name}/src/app.module.ts`);
 
+/**
+ * Whether a repository-relative file is a composition group of an app: `apps/<app>/src/compose/<area>.ts`, the module list of
+ * one area that the app root spreads into its imports (slot allows `compose/<area>.ts` of every be.app.* slot).
+ */
+export const isComposeGroup = rel => /^apps\/[^/]+\/src\/compose\/[^/]+\.ts$/.test(rel) && !/\.(?:spec|d)\.ts$/.test(rel);
+
+/** The app root and the composition groups of an app, in path order (the root first); [] when the program holds no root. */
+const appCompositionFiles = (env, name) => {
+  const root = appRoot(env, name);
+  if (!root) return [];
+  const prefix = `apps/${name}/src/compose/`;
+  const groups = [...env.graph.files.values()].filter(file => file.rel.startsWith(prefix) && isComposeGroup(file.rel));
+  return [root, ...groups.sort((a, b) => byCodeUnit(a.rel, b.rel))];
+};
+
 /** The body a call or a spread identifier resolves to when it is a function or a const declared in a file of the program (not a package), else null. */
 function helperBodyOf(env, checker, node) {
   const { ts } = env;
@@ -200,6 +216,7 @@ export function machineKit({ context, graph }) {
     valueOfProperty: bound(valueOfProperty),
     at: bound(at),
     appRoot: bound(appRoot),
+    appCompositionFiles: bound(appCompositionFiles),
   };
 }
 

package/runtime/scripts/hfs/architecture/module-per-transport.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { machineKit } from './machine-ast.mjs';
+import { isComposeGroup, machineKit } from './machine-ast.mjs';
 import { treeOf } from './required-files.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { trimTrailingSlashes } from '../trailing-slashes.mjs';
@@ -13,8 +13,9 @@ import { trimTrailingSlashes } from '../trailing-slashes.mjs';
  *     anywhere in a feature, and an `@Module` class (or a `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a
  *     feature file that is neither the application module nor the transport module of its own folder are refused;
  *   - apps import only transport modules, of the kinds their app kind allows: the `composedBy` list of each transport slot
- *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root that
- *     lists a feature's application module, or the transport module of another kind, is refused;
+ *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root (app.module.ts
+ *     or a composition group of its compose/ folder) that lists a feature's application module, or the transport module
+ *     of another kind, is refused;
  *   - a composed root (an owner slot with `composedBy`, be.cli) holds one static module per folder, named after the folder
  *     (cli.module.ts, <group>/<group>.module.ts); an app of a composing kind lists the root module only, and an app of any
  *     other kind lists none of its modules.
@@ -22,7 +23,6 @@ import { trimTrailingSlashes } from '../trailing-slashes.mjs';
 export const MODULE_PER_TRANSPORT_RULE_IDS = ['BE_MODULE_SHAPE'];
 
 const RULE = 'BE_MODULE_SHAPE';
-const APP_ROOT_FILE = 'app.module.ts';
 
 function featureOwnerOf(resolver, rel) {
   const owner = resolver.ownerOf(rel);
@@ -152,28 +152,37 @@ function inspectModuleDeclarations(checker, target, node, root, app, scan, seen)
   return references;
 }
 
-function inspectAppRoot(app, scan) {
-  const { graph, kit, ts } = scan;
-  const root = graph.files.get(`apps/${app.name}/src/${APP_ROOT_FILE}`);
-  if (!root) return 0;
-  const checker = kit.checkerOf(root.sourceFile);
-  const seen = new Set();
+/** The module references of one composition file: the root's `imports` lists, or every array of a composition group (its module list). */
+function inspectCompositionFile(file, app, scan, seen) {
+  const { kit, ts } = scan;
+  const checker = kit.checkerOf(file.sourceFile);
+  const group = isComposeGroup(file.rel);
   let references = 0;
   const judge = node => {
     const call = ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register';
     if (ts.isCallExpression(node) && !call) return;
     const target = call ? node.expression.expression : node;
-    references += inspectModuleDeclarations(checker, target, node, root, app, scan, seen);
+    references += inspectModuleDeclarations(checker, target, node, file, app, scan, seen);
   };
-  kit.walk(root.sourceFile, node => {
+  kit.walk(file.sourceFile, node => {
     if (ts.isPropertyAssignment(node) && kit.propertyNameText(node.name) === 'imports' && ts.isArrayLiteralExpression(node.initializer)) {
       for (const element of node.initializer.elements) judge(element);
+    } else if (group && ts.isArrayLiteralExpression(node)) {
+      for (const element of node.elements) judge(element);
     } else if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register') judge(node);
     return true;
   });
   return references;
 }
 
+/** The module references of an app: its root `apps/<app>/src/app.module.ts` and the composition groups of `compose/` it spreads. */
+function inspectAppRoot(app, scan) {
+  const seen = new Set();
+  let references = 0;
+  for (const file of scan.kit.appCompositionFiles(app.name)) references += inspectCompositionFile(file, app, scan, seen);
+  return references;
+}
+
 function appModuleReferences(apps, scan) {
   let references = 0;
   for (const app of apps) references += inspectAppRoot(app, scan);

package/runtime/scripts/hfs/architecture/register-once.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { machineKit } from './machine-ast.mjs';
+import { isComposeGroup, machineKit } from './machine-ast.mjs';
 import { callName } from './supabase-ast.mjs';
 import { isTestWorldSlot } from '../test-world-slot.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
@@ -7,7 +7,8 @@ import { byCodeUnit } from '../../lib/list.mjs';
 /**
  * R45 `register-once` (BE_MODULE_SHAPE), the module graph read from the app roots (owner rule of 2026-09-30, the
  * reference's `CodingModule imports DeviceModule` shape). Each capability has one representative module: the only module
- * of the capability an app registers, once, in `apps/<app>/src/app.module.ts` as `X.register({ isGlobal: true, ... })`.
+ * of the capability an app registers, once, in `apps/<app>/src/app.module.ts` as `X.register({ isGlobal: true, ... })`, or in a
+ * composition group `apps/<app>/src/compose/<area>.ts` the root spreads (an app root here means the root and its groups).
  * It may split itself into sub-modules imported as plain `imports: [Sub]`; a sub-module is never in an app and has one
  * importer, its parent. Over every `@Module` class of the program:
  *
@@ -57,6 +58,7 @@ function enclosingModule(ts, modules, node) {
 /** Records the reference an element of an imports list, or a register call, makes to a module. */
 function noteReference(scan, element, viaImports) {
   const { ts, kit, modules, checker, file, seen, references, isAppRoot } = scan;
+  if (seen.has(element)) return;
   const call = callName(ts, element) === 'register';
   if (ts.isCallExpression(element) && !call) return;
   const target = targetOf(kit, modules, checker, call ? element.expression.expression : element);
@@ -72,14 +74,19 @@ const isImportsList = (scan, node) => scan.ts.isPropertyAssignment(node) && scan
 const isStrayGlobal = (scan, node) => scan.ts.isPropertyAssignment(node) && scan.kit.propertyNameText(node.name) === 'isGlobal'
   && node.initializer.kind === scan.ts.SyntaxKind.TrueKeyword && !scan.isAppRoot(scan.file) && !scan.isWorld(scan.file);
 
+// A composition group's module list is any array of the group: the root spreads it into its imports.
+const isGroupList = (scan, node) => scan.ts.isArrayLiteralExpression(node) && isComposeGroup(scan.file.rel);
+
 function visitReferenceNode(scan, node) {
   if (isImportsList(scan, node)) {
     for (const element of node.initializer.elements) noteReference(scan, element, true);
+  } else if (isGroupList(scan, node)) {
+    for (const element of node.elements) noteReference(scan, element, true);
   } else if (callName(scan.ts, node) === 'register' && !scan.seen.has(node)) {
     noteReference(scan, node, false);
   }
   if (isStrayGlobal(scan, node)) {
-    scan.report(scan.file, node, '`isGlobal: true` appears only in the app root (apps/<app>/src/app.module.ts), where the representative module of a capability is registered; a module never decides its own globality.');
+    scan.report(scan.file, node, '`isGlobal: true` appears only in the app root (apps/<app>/src/app.module.ts or a group of apps/<app>/src/compose/), where the representative module of a capability is registered; a module never decides its own globality.');
   }
   return true;
 }
@@ -170,11 +177,12 @@ export function checkRegisterOnce(input) {
   const { ts } = 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 });
-  const isAppRoot = file => Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'app.module.ts';
+  const isAppRoot = file => Boolean(file.slot?.startsWith('be.app.')) && (path.posix.basename(file.rel) === 'app.module.ts' || isComposeGroup(file.rel));
   // The test world (slot be.tests.world) is the test composition root: useTestWorld registers capability modules with
   // `isGlobal: true` the way an app root does. A spec (integration, contract, e2e) is not a composition root.
   const isWorld = file => isTestWorldSlot(file.slot);
-  const appOf = file => config.apps.find(app => file.rel === `apps/${app.name}/src/app.module.ts`)?.name ?? null;
+  const appOf = file => config.apps.find(app => file.rel === `apps/${app.name}/src/app.module.ts`
+    || (isComposeGroup(file.rel) && file.rel.startsWith(`apps/${app.name}/src/compose/`)))?.name ?? null;
   const modules = moduleDeclarations(graph, kit, ts);
   const references = moduleReferences(graph, kit, ts, modules, isWorld, isAppRoot, report);
   const rootReferences = references.filter(item => item.root);

package/runtime/scripts/hfs/architecture/required-files.mjs

@@ -4,6 +4,7 @@ import { lsFiles } from '../../api/git/ls-files.mjs';
 import { revParseQuery } from '../../api/git/rev-parse-query.mjs';
 import { gitOutputOf } from '../../lib/git.mjs';
 import { trimTrailingSlashes } from '../trailing-slashes.mjs';
+import { requiredFileApplies } from '../slot-required.mjs';
 
 /**
  * HFS check 5: the files and directories the slot manifest requires (knowledge/hfs/slots.yaml `requires`,
@@ -173,7 +174,7 @@ function requirementExists(tree, target) {
 }
 
 function reportMissingRequirement(requirement, tree, report) {
-  if (requirementExists(tree, requirement.target)) return;
+  if (requirementExists(tree, requirement.target) || !requiredFileApplies(requirement.slot, requirement.target, tree.files)) return;
   const rootExists = !requirement.root || tree.directories.has(requirement.root);
   if (!rootExists) {
     report(ruleFor(requirement.slot, requirement.target, false), requirement.root, requirement.slot, requirement.root, { kind: 'directory' },

package/runtime/scripts/hfs/architecture/staged-consumers.mjs

@@ -0,0 +1,37 @@
+import { catFile } from '../../api/git/cat-file.mjs';
+import { diff } from '../../api/git/diff.mjs';
+import { gitOutputOf } from '../../lib/git.mjs';
+
+/** Eligible additions, copies, edits and rename destinations in the index, read in one blob batch. */
+export function stagedConsumerSources(root, accept) {
+  try {
+    const options = { cwd: root, maxBuffer: 256 * 1024 * 1024 };
+    const files = gitOutputOf(diff(['--cached', '--relative', '--name-only', '--diff-filter=ACMR', '-z', '--', '.'], options))
+      .split('\0').filter(file => file && accept(file));
+    if (!files.length) return [];
+    // :./ keeps paths relative to this side's root even when git's top level is the parent app folder.
+    // -z terminates requests with NUL; output headers and blob trailers still use LF.
+    const bytes = gitOutputOf(catFile(['--batch', '-z'], {
+      ...options, encoding: null, input: files.map(file => `:./${file}\0`).join(''),
+    }));
+    if (!Buffer.isBuffer(bytes)) return [];
+    const sources = [];
+    let cursor = 0;
+    for (const file of files) {
+      const end = bytes.indexOf(10, cursor);
+      if (end < 0) return [];
+      const header = /^[0-9a-f]+ blob (\d+)$/u.exec(bytes.subarray(cursor, end).toString('utf8'));
+      if (!header) return []; // An index changed during the read: discard this supplement, keep disk consumers.
+      const size = Number(header[1]);
+      const start = end + 1;
+      const next = start + size;
+      if (!Number.isSafeInteger(size) || next >= bytes.length || bytes[next] !== 10) return [];
+      sources.push({ file, text: bytes.subarray(start, next).toString('utf8') });
+      cursor = next + 1;
+    }
+    return sources;
+  } catch {
+    // A non-git fixture (or an unavailable index) still uses the existing filesystem consumers.
+    return [];
+  }
+}

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

@@ -1,5 +1,7 @@
 // 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.
+import { unwrapExpression } from '../../lib/ts-analysis.mjs';
+
 export const SUPABASE_MODULES = new Set(['@supabase/ssr', '@supabase/supabase-js']);
 
 export const moduleNameOf = (ts, node) => {
@@ -38,12 +40,7 @@ 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 unwrap = (ts, node) => unwrapExpression(ts, node, { awaitExpressions: true, satisfiesExpressions: false });
 
 const isSupabaseValue = (kit, checker, node) => {
   const current = unwrap(kit.ts, node);

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

@@ -3,6 +3,7 @@
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
 import { importedFrom, reportAt, unwrap } from './supabase-ast.mjs';
+import { accessName } from './backend-app-files.mjs';
 
 const BE_SUPABASE_SLOT = 'be.integrations.supabase';
 const BE_JWT_VERIFIED = 'BE_SUPABASE_JWT_VERIFIED';
@@ -47,12 +48,6 @@ const importedCall = (kit, checker, call) => {
   return owner?.name === 'default' ? { module: owner.module, name: call.expression.name.text } : null;
 };
 
-const accessName = (ts, node) => {
-  if (ts.isPropertyAccessExpression(node)) return node.name.text;
-  if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) return node.argumentExpression.text;
-  return null;
-};
-
 const requestLike = (ts, node) => {
   const current = unwrap(ts, node);
   if (ts.isIdentifier(current)) return /^(?:req|request)$/iu.test(current.text);

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

@@ -14,8 +14,15 @@ import { byCodeUnit } from '../../lib/list.mjs';
  */
 export const TIER_RULE_IDS = ['BE_TIER_DIRECTION', 'BE_FEATURE_IMPORTS_FEATURE', 'BE_KIND_ISOLATION', 'FE_TIER_DIRECTION', 'FE_APP_ISOLATION', 'ARCH_OWNER_CYCLE'];
 
+function tierDirectionText({ fromTier, toTier, mayImport, kindRestriction, fromKind, toKind }) {
+  if (!kindRestriction) return `a ${fromTier} may import only ${mayImport.join(', ') || 'nothing'}; it imports a ${toTier}`;
+  const source = fromKind ?? 'no folder kind';
+  const target = toKind ?? 'no folder kind';
+  return `a ${fromTier} may import ${toTier} owners only from kinds ${kindRestriction.from.join(', ')} to kinds ${kindRestriction.to.join(', ')}; it imports ${source} -> ${target}`;
+}
+
 const REASON_TEXT = {
-  tierDirection: ({ fromTier, toTier, mayImport }) => `a ${fromTier} may import only ${mayImport.join(', ') || 'nothing'}; it imports a ${toTier}`,
+  tierDirection: tierDirectionText,
   layerOrder: ({ fromLayer, toLayer }) => `a ${fromLayer} component may import only the layers after it; it imports a ${toLayer}`,
   crossApp: ({ from, to }) => `app ${from} imports app ${to}; apps never import each other, shared code is a packages/<pkg> slot`,
 };

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

@@ -9,6 +9,7 @@ import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule
 import { readJsonFile } from '../../lib/json.mjs';
 import { sourceLocation } from '../../lib/ts-ast.mjs';
 import { locateDeclaration } from '../slots.mjs';
+export { unwrapExpression } from '../../lib/ts-analysis.mjs';
 
 const CODE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
 const SCRIPT_TAIL = '[cm]?[jt]sx?';
@@ -399,14 +400,6 @@ export function reachableViolation(edges, firstEdge, forbidden, { follow = () =>
 /** A framework identity the checkers cannot prove statically. */
 export const UNPROVEN_FRAMEWORK = '(unproven framework identity)';
 
-/** The expression under parentheses, type assertions, non-null and satisfies wrappers. */
-export function unwrapExpression(ts, expression) {
-  while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
-    || ts.isTypeAssertionExpression(expression) || ts.isNonNullExpression(expression)
-    || (ts.isSatisfiesExpression?.(expression) ?? false))) expression = expression.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). */

package/runtime/scripts/hfs/architecture/unit-spec-providers.mjs

@@ -4,6 +4,7 @@ import { machineKit } from './machine-ast.mjs';
 import { constructorDependencies } from './constructor-deps.mjs';
 import { treeOf } from './required-files.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
+import { importsOf } from '../../lib/ts-analysis.mjs';
 
 /**
  * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
@@ -25,17 +26,6 @@ export const UNIT_SPEC_PROVIDERS_RULE_IDS = ['BE_SPEC_QUALITY'];
 const RULE = 'BE_SPEC_QUALITY';
 const SPEC_ROOT = /^(?:src|apps)\//u;
 
-/** local name -> {name, module} for every named import of a source file. */
-function importsOf(ts, sourceFile) {
-  const imports = new Map();
-  for (const statement of sourceFile.statements) {
-    const bindings = ts.isImportDeclaration(statement) ? statement.importClause?.namedBindings : null;
-    if (!bindings || !ts.isNamedImports(bindings)) continue;
-    for (const element of bindings.elements) imports.set(element.name.text, { name: (element.propertyName ?? element.name).text, module: statement.moduleSpecifier.text });
-  }
-  return imports;
-}
-
 /** The `Test.createTestingModule(...)` calls of a spec. */
 function testingModules(ts, sourceFile) {
   const calls = [];

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

@@ -323,6 +323,12 @@ function runtimeParamProblems(rp) {
   ];
 }
 
+const folderKindsValid = list => strList(list) && list.length > 0 && new Set(list).size === list.length && list.every(kind => NAME.test(kind));
+const kindPairValid = pair => isPlainObject(pair) && Object.keys(pair).sort(byCodeUnit).join() === 'from,to'
+  && ['from', 'to'].every(side => folderKindsValid(pair[side]));
+const kindRestrictionValid = kinds => isPlainObject(kinds) && Object.keys(kinds).length > 0
+  && Object.entries(kinds).every(([target, pair]) => NAME.test(target) && kindPairValid(pair));
+
 /** Shape problems of the tier map of one profile. */
 export function tierMapProblems(profile, tiers) {
   const bad = [];
@@ -330,14 +336,33 @@ export function tierMapProblems(profile, tiers) {
   for (const [tier, def] of Object.entries(tiers)) {
     if (!NAME.test(tier)) bad.push(`tiers.${profile}.${tier} is not a tier name`);
     if (!isPlainObject(def) || !Array.isArray(def.mayImport) || !def.mayImport.every((t) => NAME.test(String(t)))) bad.push(`tiers.${profile}.${tier}.mayImport must be a list of tier names`);
-    for (const key of Object.keys(def ?? {})) if (!['mayImport', 'acyclic', 'lowerLayerOnly'].includes(key)) bad.push(`tiers.${profile}.${tier}.${key} is not a tier field`);
+    if (def?.mayImportKinds !== undefined && !kindRestrictionValid(def.mayImportKinds)) bad.push(`tiers.${profile}.${tier}.mayImportKinds must map tier names to {from, to} non-empty lists of unique folder kinds`);
+    for (const key of Object.keys(def ?? {})) if (!['mayImport', 'mayImportKinds', 'acyclic', 'lowerLayerOnly'].includes(key)) bad.push(`tiers.${profile}.${tier}.${key} is not a tier field`);
+  }
+  return bad;
+}
+
+function tierFolderKindProblems(manifest, profile, tier, kinds, at) {
+  const known = new Set(manifest.slots.filter((slot) => slot.profiles.includes(profile) && slot.tier === tier).flatMap((slot) => [...(slot.kinds ?? []), ...(slot.layers ?? [])]));
+  return kinds.filter(kind => !known.has(kind)).map(kind => `${at} names ${kind}, which is not a folder kind of the ${tier} tier`);
+}
+
+/** Kind restrictions narrow an allowed tier edge and name kinds that its source and target slots actually declare. */
+export function tierKindProblems(manifest, profile) {
+  const bad = [];
+  for (const [tier, def] of Object.entries(manifest.tiers[profile])) {
+    for (const [target, kinds] of Object.entries(def.mayImportKinds ?? {})) {
+      const at = `tiers.${profile}.${tier}.mayImportKinds.${target}`;
+      if (!def.mayImport.includes(target)) bad.push(`${at} restricts a tier that mayImport does not allow`);
+      bad.push(...tierFolderKindProblems(manifest, profile, tier, kinds.from, `${at}.from`), ...tierFolderKindProblems(manifest, profile, target, kinds.to, `${at}.to`));
+    }
   }
   return bad;
 }
 
 /** The semantic rules of a runtime manifest beyond the slot rules both kinds share: tier names and the schema major. */
 export function runtimeSemanticProblems(m) {
-  const bad = [];
+  const bad = tierKindProblems(m, RUNTIME_KIND);
   const tiers = m.tiers.runtime;
   for (const [tier, def] of Object.entries(tiers)) {
     for (const target of def.mayImport) if (!(target in tiers)) bad.push(`tiers.runtime.${tier}.mayImport names ${target}, which is not a runtime tier`);

package/runtime/scripts/hfs/path-findings.mjs

@@ -3,6 +3,7 @@
 // (scripts/hfs/project-graph.mjs) runs it over the same tree and serves the findings on a TypeScript file as ESLint reports.
 //   HFS_SLOT_UNDECLARED / HFS_SLOT_AMBIGUOUS / HFS_SLOT_NOT_ENABLED / HFS_FORBIDDEN_PRESENT / HFS_TOOL_CONFIG_LOCAL / HFS_TRACKED_MUST_BE_IGNORED (R01, R16)
 //   BE_SOURCE_FORM (R89, the file name), BE_SPEC_PLACEMENT (R102)
+import fs from 'node:fs';
 import path from 'node:path';
 import { allowsFile } from './allows.mjs';
 import { isFeTestPath } from './rules/fe-no-tests.mjs';
@@ -30,8 +31,11 @@ function sourceFormContext(file, resolver, suffixes, bannedSuffixes) {
   const slot = resolver.slot(c.slot);
   if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].includes(base)) return null;
   const admitted = allowsFile(resolver, file);
+  // Environment parsing is an app slot role, not a source suffix admitted outside that matching app file.
+  if (c.slot.startsWith('be.app.') && admitted?.allowed && admitted.entry === '<app>.env.ts') return null;
   if (admitted?.allowed && admitted.entry?.includes('/') && path.posix.basename(admitted.entry) === base) return null;
-  if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) return null;
+  // A plain entry names its file by a variable only (`<x>.ts`, or `compose/<area>.ts` of an app slot): a kebab name is its form.
+  if (admitted?.allowed && PLAIN_ENTRY.test(path.posix.basename(admitted.entry ?? '')) && KEBAB.test(base.slice(0, -'.ts'.length))) return null;
   if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') return null;
   return { c, base, suffixes, bannedSuffixes };
 }
@@ -54,7 +58,7 @@ function sourceFormFinding(file, { c, base, suffixes, bannedSuffixes }, boundSuf
 
 /**
  * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
- * be.persistence, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
+ * be.persistence, the matching <app>.env.ts explicitly admitted by its app slot, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
  * as order.service.spec.ts keeps its inner words kebab-case). A suffix of ruleParams.be.bannedSuffixes anywhere in the
  * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
  */
@@ -86,6 +90,8 @@ function forbiddenPathFinding(file, c, resolver) {
 }
 
 function pathStatusFinding(file, resolver) {
+  const liteWork = liteStarciworkFinding(file, resolver);
+  if (liteWork) return liteWork;
   const c = resolver.classifyPath(file);
   if (c.status === 'no-slot') {
     const nearestNote = c.nearest ? `; nearest slot ${c.nearest.slot} (${c.nearest.pattern}), matched ${c.nearest.matchedPrefix || '.'} then expected ${c.nearest.expectedNext ?? 'nothing'}` : '';
@@ -98,6 +104,30 @@ function pathStatusFinding(file, resolver) {
   return null;
 }
 
+/** The lite Work boundary, read from app.starciwork's edition-specific admission list, including paths a narrower slot owns. */
+export function liteStarciworkFinding(file, resolver, { dir = false } = {}) {
+  if (resolver.repo?.edition !== 'lite' || !resolver.slot('app.starciwork')) return null;
+  const p = resolver.classifyPath(file).path;
+  if (!p.startsWith('.starciwork/')) return null;
+  const admitted = allowsFile(resolver, dir ? `${p}/.probe` : p);
+  if (admitted?.slot === 'app.starciwork' && admitted.allowed) return null;
+  return { code: 'HFS_STARCIWORK_LITE_FORBIDDEN', level: 'error', path: p, slot: 'app.starciwork', message: `${p}: lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore); remove this path or use the full edition` };
+}
+
+/** Local lite Work leftovers, including metadata ignored by an old full-edition .gitignore. */
+export function liteStarciworkTreeFindings(repoRoot, resolver, tracked) {
+  if (resolver.repo?.edition !== 'lite' || !resolver.slot('app.starciwork')) return [];
+  let entries = [];
+  try { entries = fs.readdirSync(path.join(repoRoot, '.starciwork'), { withFileTypes: true }); } catch { /* Work is optional. */ }
+  const trackedSet = new Set(tracked);
+  return entries.flatMap(entry => {
+    const file = `.starciwork/${entry.name}`;
+    if (trackedSet.has(file)) return [];
+    const finding = liteStarciworkFinding(file, resolver, { dir: entry.isDirectory() });
+    return finding ? [finding] : [];
+  });
+}
+
 /** The findings of the slot manifest over `files` (repository-relative tracked paths) of a repository of `profile`. */
 export function pathFindings({ files, resolver, profile }) {
   const findings = [];

package/runtime/scripts/hfs/rules/secrets.mjs

@@ -5,6 +5,8 @@
 //   - a tracked `.enc` that is not a sops envelope (an encrypted-looking file that holds plaintext);
 //   - a line of any other tracked text file that matches a secret pattern.
 // A finding names the file, the line and the pattern, never the value.
+import fs from 'node:fs';
+import path from 'node:path';
 import { FORBIDDEN_FILES, secretHits } from '../../lib/secret-patterns.mjs';
 import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
@@ -16,6 +18,17 @@ const NOT_SCANNED = /(^|\/)package-lock\.json$/;
 /** True when the slot `id` of the manifest reports HFS_PLAINTEXT_SECRET for the paths it forbids. */
 export const slotOwnsSecrets = (slot) => slot?.rules?.includes(PLAINTEXT_SECRET) === true;
 
+/** A legacy lite root secrets.env is reported even when ignored; its presence is enough, so no value is read. */
+export function untrackedSecretFindings({ repoRoot, files, repo }) {
+  if (repo.profile !== 'app' || repo.edition !== 'lite' || files.includes('secrets.env')) return [];
+  try {
+    if (!fs.statSync(path.join(repoRoot, 'secrets.env')).isFile()) return [];
+  } catch {
+    return [];
+  }
+  return [found(PLAINTEXT_SECRET, 'secrets.env', 'secrets.env is an untracked plaintext secret at the lite app root; seal it with starci app secret set into .starcistacks/<env>/secrets/<slug>.enc and remove the plaintext file; read materialized values by *_FILE', { level: 'warning', pattern: 'untracked-secrets-env' })];
+}
+
 /**
  * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too

package/runtime/scripts/hfs/slot-imports.mjs

@@ -65,8 +65,10 @@ export function importAllowedIn(scope, fromPath, toPath) {
   const fromOwner = ownerIn(scope, from.path);
   const toOwner = ownerIn(scope, to.path);
   if (sameOwnerUnit(from, fromOwner) === sameOwnerUnit(to, toOwner)) return { allowed: true, reason: 'sameOwner' };
-  const { mayImport } = scope.manifest.tiers[scope.profile][fromTier] ?? {};
+  const { mayImport, mayImportKinds } = scope.manifest.tiers[scope.profile][fromTier] ?? {};
   if (!mayImport?.includes(toTier)) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport: mayImport ?? [] };
+  const kindRestriction = mayImportKinds?.[toTier];
+  if (kindRestriction && (!kindRestriction.from.includes(from.kind) || !kindRestriction.to.includes(to.kind))) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport, kindRestriction, fromKind: from.kind ?? null, toKind: to.kind ?? null };
   const layerProblem = lowerLayerProblem(scope, from, to, fromTier, toTier, fromOwner, toOwner);
   if (layerProblem) return layerProblem;
   // A runtime owner is imported file by file (crossOwner of knowledge/hfs/runtime-slots.yaml): no public entry.

package/runtime/scripts/hfs/slot-required.mjs

@@ -5,6 +5,19 @@ import { braceVariants } from '../lib/glob.mjs';
 import { classifyIn, slotEnabled } from './slot-classify.mjs';
 import { fillVars, varsOf } from './slot-match.mjs';
 
+/** A populated fe.modules instance needs its index.ts only when it contains TypeScript, including nested files. */
+export function requiredFileApplies(slotId, target, files) {
+  if (!/^fe\.modules(?:\.|$)/u.test(slotId) || path.posix.basename(target) !== 'index.ts') return true;
+  const prefix = `${path.posix.dirname(target)}/`;
+  let populated = false;
+  for (const file of files) {
+    if (!file.startsWith(prefix)) continue;
+    populated = true;
+    if (/\.tsx?$/u.test(file)) return true;
+  }
+  return !populated;
+}
+
 /** One `requires` entry of a slot placed under `root`: a leading / makes it repository-relative, the variables are filled from `bindings`. */
 function requiredEntry(entry, bindings, root) {
   const rooted = entry.startsWith('/');

package/runtime/scripts/hfs/slot-semantic-problems.mjs

@@ -2,7 +2,7 @@
 import { isPlainObject } from '../../engine/plain-object.mjs';
 import { triggerProblems } from './declaration-slots.mjs';
 import { litePresenceOf, slotInEdition } from './edition-slots.mjs';
-import { manifestKind, RUNTIME_KIND, runtimeSemanticProblems } from './manifest-shape.mjs';
+import { manifestKind, RUNTIME_KIND, runtimeSemanticProblems, tierKindProblems } from './manifest-shape.mjs';
 import { APP_SCOPE, PROFILES } from './slot-manifest-shape.mjs';
 
 function checkAppRootSlot(slot, bad) {
@@ -113,6 +113,7 @@ function checkSideReads(manifest, bad, braceVariants) {
 }
 
 function checkProfileTierTargets(manifest, profile, bad) {
+  bad.push(...tierKindProblems(manifest, profile));
   for (const [tier, def] of Object.entries(manifest.tiers[profile])) {
     for (const target of def.mayImport) {
       if (!(target in manifest.tiers[profile])) bad.push(`tiers.${profile}.${tier}.mayImport names ${target}, which is not a ${profile} tier`);

package/runtime/scripts/lib/ts-analysis.mjs

@@ -0,0 +1,20 @@
+/** The expression under the wrappers selected by an AST check's contract. */
+export function unwrapExpression(ts, expression, { awaitExpressions = false, typeAssertions = true, satisfiesExpressions = true } = {}) {
+  while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
+    || (typeAssertions && ts.isTypeAssertionExpression(expression)) || ts.isNonNullExpression(expression)
+    || (satisfiesExpressions && (ts.isSatisfiesExpression?.(expression) ?? false))
+    || (awaitExpressions && ts.isAwaitExpression(expression)))) expression = expression.expression;
+  return expression;
+}
+
+/** Local name -> imported name and module; callers select their existing module key and literal policy. */
+export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiteralsOnly = false } = {}) {
+  const imports = new Map();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || (stringLiteralsOnly && !ts.isStringLiteralLike(statement.moduleSpecifier))) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const binding of bindings.elements) imports.set(binding.name.text, { name: (binding.propertyName ?? binding.name).text, [moduleKey]: statement.moduleSpecifier.text });
+  }
+  return imports;
+}