@starci/hfs 3.0.0 → 4.0.0

package/runtime/modules/kernel/failure-codes.yaml

@@ -444,6 +444,7 @@ BE_RAW_INJECT:
     - "Token là chuỗi thay vì unique symbol"
     - "Tiêm lớp hạ tầng (CacheService, AppLogger) không qua injector"
     - "Dùng ModuleRef.get hoặc forwardRef để né vòng phụ thuộc"
+    - "constructor(private readonly timeoutMs: number) {} hoặc ReadonlyMap<string, X> không có Inject<Thing>() gắn token có tên"
   nextStep_vi: "Khai báo token `export const THING: unique symbol = Symbol(\"<owner>.<thing>\")` và `export const InjectThing = (): TypedParameterDecorator<Thing> => injector<Thing>(THING)` trong <owner>.decorators.ts rồi dùng @InjectThing() ở mọi nơi; vòng phụ thuộc là lỗi kiến trúc cần gỡ, không dùng forwardRef. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra và mục của luật trong BE-CONVENTION; không thêm ngoại lệ, không tắt luật."
   owner: op-retry
   kind: check-finding
@@ -483,8 +484,9 @@ BE_SCHEMA_OWNER:
 BE_SOURCE_FORM:
   title: "Back-end source file breaks the naming or form canon"
   title_vi: "Tệp nguồn BE sai quy ước tên hoặc hình thức"
-  meaning_vi: "Tên tệp phải là kebab-case với hậu tố vai trò trong danh sách đóng của slots.yaml; chỉ export có tên (không export default); mọi export và thành viên công khai có JSDoc tiếng Anh; không emoji, và không có chữ tiếng Việt trong định danh, chuỗi ký tự, chú thích hay tên test ngoài catalog messages/ và slot fixture i18n."
+  meaning_vi: "Tên tệp phải là kebab-case với hậu tố vai trò trong danh sách đóng của slots.yaml; chỉ export có tên (không export default); mọi export và thành viên công khai có JSDoc tiếng Anh; không emoji, và không có chữ tiếng Việt trong định danh, chuỗi ký tự, chú thích hay tên test ngoài catalog messages/ và slot fixture i18n; mã production không khai báo lớp, hàm hay hằng export có từ Mock, Fake hoặc Stub trong tên (đồ giả nằm trong spec hoặc src/tests; driver ngoại tuyến là adapter điều khiển bằng options, đặt tên theo việc nó làm)."
   causes_vi:
+    - "class MockExpertAgentService trong mã production thay vì adapter điều khiển bằng options"
     - "Tệp dùng hậu tố bị cấm (use-case, repository, store, util, helper, types, constants)"
     - "Lớp export không kết thúc bằng hậu tố vai trò của tệp và cũng không kết thúc bằng tên port (interface trong *.port.ts hoặc *.contracts.ts) mà nó implements"
     - "Interface trong tệp *.input.ts, *.request.ts, *.response.ts, *.type.ts, *.args.ts hoặc *.rows.ts không kết thúc bằng Input, Request, Response, Type, Args hoặc Row"
@@ -539,7 +541,7 @@ BE_TEST_TOPOLOGY:
   meaning_vi: "Cấu hình test lệch chuẩn: `<detail>`."
   causes_vi:
     - "Vi phạm luật R47: một `jest.config.js` (preset `@starci/jest-preset`) với bốn project `unit`, `integration`, `e2e`, `contract`; thư mục và hậu tố spec luôn khớp nhau; `diagnostics: false` + `isolatedModules: true`; `test:integration`, `test:e2e`, `test:contract` = `typecheck:tests && jest --selectProjects <tên>`; `src/tests/world/` là nơi duy nhất dựng hạ tầng test và chỉ chứa `global-setup.ts`, `global-teardown.ts`, `use-test-world.ts`, `fakes/` và file gốc có hậu tố vai trò (kể cả `test-world.config.ts`)."
-    - "Vi phạm luật R47 về stack thật: mọi dịch vụ khai trong `.starcistacks/<env>` (Postgres, Redis, Keycloak, mail host, k3s...) chạy THẬT trong world qua toxiproxy, world đọc dịch vụ và phiên bản image từ stack lúc chạy; `fakes/<provider>/` chỉ giả SaaS bên ngoài mà đội không vận hành. Ngoại lệ duy nhất: dịch vụ stateless cần phần cứng đặc biệt hoặc model bên ngoài (GPU inference, embedding tự host) được giả khi `test-world.config.ts` khai trong `fakedBy` với `reason` không rỗng; dịch vụ có trạng thái (database, cache, identity, storage, mail, queue, search hoặc có volume bền) không bao giờ được giả, và mục `fakedBy` trỏ tới dịch vụ hoặc thư mục fake không tồn tại bị coi là cũ."
+    - "Vi phạm luật R47 về stack thật: mọi dịch vụ khai trong `.starcistacks/<env>` (Postgres, Redis, Keycloak, mail host, k3s...) chạy THẬT trong world qua toxiproxy, world đọc dịch vụ và phiên bản image từ stack lúc chạy; `fakes/<provider>/` chỉ giả SaaS bên ngoài mà đội không vận hành. Ngoại lệ duy nhất: dịch vụ stateless cần phần cứng đặc biệt hoặc model bên ngoài (GPU inference, embedding tự host) được giả khi mục `stacks` của dịch vụ đó trong `test-world.config.ts` khai `{ fakedBy, reason }` với `reason` không rỗng; dịch vụ có trạng thái (database, cache, identity, storage, mail, queue, search hoặc có volume bền) không bao giờ được giả, và mục `fakedBy` trỏ tới dịch vụ hoặc fake (mục `fakes` hay thư mục `fakes/`) không tồn tại bị coi là cũ. `test-world.config.ts` khai world theo đúng một dạng export có tên `export const { useTestWorld, useSandbox } = defineTestWorld({...})` (`stack`, `stacks` theo từng dịch vụ, `fakes`); export default không được đọc và bị báo lỗi."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -905,11 +907,11 @@ FE_TRANSPORT_OWNER:
   kind: check-finding
 
 FE_WIRE_GENERATED:
-  title: "Wire types generated from the contract copy"
+  title: "Wire types generated from the be contract snapshots the fe side reads"
   title_vi: "Kiểu wire gõ tay"
-  meaning_vi: "`<file>` tự gõ kiểu wire/ép kiểu phản hồi. Dùng kiểu sinh từ `contract/`."
+  meaning_vi: "`<file>` tự gõ kiểu wire/ép kiểu phản hồi, hoặc kiểu sinh ra cũ hơn ảnh chụp hợp đồng. Dùng kiểu sinh từ `be/contracts/`."
   causes_vi:
-    - "Vi phạm luật R52: Kiểu wire sinh từ bản hợp đồng (`codegen`); tài liệu GraphQL trong `.graphql`; cấm `as GraphqlResult<T>`; enum wire không phải `string`."
+    - "Vi phạm luật R52: Kiểu wire sinh từ ảnh chụp hợp đồng của be (`be/contracts/`, chạy `npm run codegen` ở gốc app); tài liệu GraphQL trong `.graphql`; cấm `as GraphqlResult<T>`; enum wire không phải `string`."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra và mục của luật trong tiêu chuẩn HFS; nợ cũ cần quyết định thiết kế nên op không thêm ngoại lệ, chỉ tách hoặc chuyển về đúng chủ."
   owner: op-retry
   kind: check-finding
@@ -991,11 +993,11 @@ HFS_CI_MISSING_CANON:
   kind: check-finding
 
 HFS_CONTRACT_SNAPSHOT_DRIFT:
-  title: "Contract snapshot equals the emit, the FE copy equals the BE"
+  title: "The be side commits its contract snapshot and it equals the emit"
   title_vi: "Bản hợp đồng lệch bản thật"
-  meaning_vi: "Hợp đồng `<file>` lệch bản thật (`<sha>` ≠ `<sha>`). Chạy `npm run contract:emit` (BE) / `contract:pull` (FE) rồi commit kết quả. Nếu emit không chạy được thì finding nêu nguyên văn lỗi của emit; không bao giờ bỏ qua âm thầm."
+  meaning_vi: "Hợp đồng `<file>` lệch bản thật (`<sha>` ≠ `<sha>`). Chạy `npm run contract:emit` ở gốc app rồi commit kết quả. Nếu emit không chạy được thì finding nêu nguyên văn lỗi của emit; không bao giờ bỏ qua âm thầm."
   causes_vi:
-    - "Vi phạm luật R23: BE: `contracts/<app>/schema.graphql` và `contracts/<app>/openapi.json` (sinh từ bảng thao tác có kiểu `apps/<app>/src/operations.ts`) phải bằng bản `hfs emit-contracts` phát ra ngay lúc kiểm tra (đồ thị module đọc từ mã nguồn, không cần env, DB hay mạng); chỉ chạy ở lượt kiểm tra đầy đủ, `--fast` bỏ qua và nói rõ trong phần coverage. FE: `modules/api/contract/*` bằng bản BE (so hash)."
+    - "Vi phạm luật R23: phía be: `be/contracts/<app>/schema.graphql` và `be/contracts/<app>/openapi.json` (sinh từ bảng thao tác có kiểu `apps/<app>/src/operations.ts`) phải bằng bản `hfs emit-contracts` phát ra ngay lúc kiểm tra (đồ thị module đọc từ mã nguồn, không cần env, DB hay mạng); chỉ chạy ở lượt kiểm tra đầy đủ, `--fast` bỏ qua và nói rõ trong phần coverage. Phía fe đọc thẳng `be/contracts/` (đường đọc chéo duy nhất khai trong hfs.json `sides.fe.reads`), không giữ bản sao."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -1141,27 +1143,6 @@ HFS_HOOKS_PATH_REDIRECTED:
   owner: op-retry
   kind: check-finding
 
-HFS_INIT_EXISTS:
-  title: "hfs.json already exists"
-  title_vi: "hfs.json đã có sẵn"
-  meaning_vi: "Lệnh hfs init không ghi đè bản khai báo đã có vì bản đó là quyết định của kho."
-  causes_vi:
-    - "Chạy hfs init trong kho đã có hfs.json"
-  nextStep_vi: "Sửa hfs.json trực tiếp, hoặc dùng hfs init --stdout để xem bản dò tự động rồi so sánh."
-  owner: op-retry
-  kind: verb-refusal
-
-HFS_INIT_UNDETECTED:
-  title: "Repository profile or apps not detected"
-  title_vi: "Không dò được loại kho hoặc ứng dụng"
-  meaning_vi: "Lệnh hfs init không xác định chắc chắn kho là backend hay frontend, hoặc không thấy ứng dụng nào dưới apps/ để khai báo, nên không đoán mò."
-  causes_vi:
-    - "Không có next hay @nestjs/core trong phụ thuộc, hoặc có cả hai"
-    - "Kho chưa có thư mục apps/<tên>/ (Nest cần thêm src/, Next cần next.config)"
-  nextStep_vi: "Tạo bố cục apps/<tên>/ theo chuẩn hoặc viết hfs.json bằng tay theo modules/schemas/hfs-repo.schema.yaml."
-  owner: op-retry
-  kind: verb-refusal
-
 HFS_LINT_SUPPRESSION_FILE:
   title: "A repository keeps no lint-suppression file, script or option"
   title_vi: "Kho có tệp hoặc script ghi nhận bỏ qua lỗi lint"
@@ -1238,6 +1219,16 @@ HFS_PACKAGE_MANAGER_MIXED:
   owner: other-op:backend.scaffold
   kind: check-finding
 
+HFS_PEER_INTEGRATION_MISSING:
+  title: "An app declares the runtime peer its driver integration needs"
+  title_vi: "Thiếu gói peer mà tích hợp driver cần khi chạy"
+  meaning_vi: "`package.json` ở gốc app phụ thuộc vào các gói của một cặp trong `knowledge/hfs/peer-integrations.yaml` (ví dụ `@nestjs/apollo` trên `@nestjs/platform-express` 11, tức Express 5) nhưng không khai báo gói `<requires>` trong dependencies, nên api không khởi động được."
+  causes_vi:
+    - "Vi phạm luật R111: npm không tự cài gói peer này, type-check và unit spec không nạp nó, nên lỗi chỉ lộ ra khi api khởi động (hai backend cũ thiếu `@as-integrations/express5` và api GraphQL không chạy được trên Express 5)."
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: thêm gói `<requires>` vào dependencies của `package.json` ở gốc app; không thêm ngoại lệ."
+  owner: op-retry
+  kind: check-finding
+
 HFS_PLAINTEXT_SECRET:
   title: "Secrets exist only as `.starcistacks/<env>/secrets/<slug>.enc`"
   title_vi: "Bí mật dạng rõ trong kho"
@@ -1413,7 +1404,7 @@ HFS_ROOT_MARKDOWN_FORBIDDEN:
   kind: check-finding
 
 HFS_ROOT_SRC_FORBIDDEN_FE:
-  title: "Root src folder in frontend repo"
+  title: "Root src folder in the front end (fe/)"
   title_vi: "Repo giao diện có thư mục src ở gốc"
   meaning_vi: "Repo giao diện có thư mục src ngay ở gốc, trong khi mã nguồn chỉ được đặt trong apps/<tên app>/src."
   causes_vi:
@@ -1513,7 +1504,7 @@ HFS_SRC_LAYOUT_INVALID:
   kind: check-finding
 
 HFS_STACKS_IN_FE:
-  title: "Stack declarations in frontend repo"
+  title: "Stack declarations in the front end (fe/)"
   title_vi: "Khai báo stack nằm trong repo giao diện"
   meaning_vi: "Repo giao diện đang chứa thư mục .starcistacks, trong khi khai báo stack chỉ được đặt ở repo backend."
   causes_vi:
@@ -1610,7 +1601,7 @@ HFS_UNUSED_FILE:
   kind: check-finding
 
 HFS_WORK_IN_FE:
-  title: "Work tree inside frontend repo"
+  title: "Work tree inside the front end (fe/)"
   title_vi: "Hồ sơ Work nằm trong repo giao diện"
   meaning_vi: "Repo giao diện chứa thư mục .starciwork, trong khi hồ sơ Work chỉ được lưu ở repo backend."
   causes_vi:

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

@@ -227,7 +227,7 @@ function externalTransportReexport(ts, sourceFile, selected) {
   for (const statement of sourceFile.statements) {
     if (!ts.isExportDeclaration(statement)) continue;
     const clause = statement.exportClause;
-    const specifier = ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
+    const specifier = statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
     if (specifier && (specifier === '@nestjs/common' || TRANSPORT_PACKAGES.test(specifier))) {
       if (!clause) {
         if (specifier !== '@nestjs/common' || selected === null || [...selected].some(name => NEST_COMMON_TRANSPORT.has(name))) {

package/runtime/scripts/checks/architecture/config.mjs

@@ -61,7 +61,12 @@ function existingRegularFile(root, relative) {
   }
 }
 
-function workspaceDirectories(root) {
+/**
+ * The npm workspaces below `root`. The one package.json of an app is at `packageRoot` (the app root; `root` is its side folder):
+ * its workspace patterns under `<side>/` are this side's, read relative to the side folder, and every other pattern is the other
+ * side's.
+ */
+function workspaceDirectories(root, { packageRoot: appPackageRoot = root, side = null } = {}) {
   const directories = new Set();
   const queue = [root];
   const visited = new Set();
@@ -89,11 +94,14 @@ function workspaceDirectories(root) {
     const packageRoot = queue.shift();
     if (visited.has(packageRoot)) continue;
     visited.add(packageRoot);
-    const pkg = readJson(path.join(packageRoot, 'package.json'));
+    const sideRoot = side !== null && packageRoot === root;
+    const pkg = readJson(path.join(sideRoot ? appPackageRoot : packageRoot, 'package.json'));
     const patterns = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
     for (const pattern of Array.isArray(patterns) ? patterns : []) {
       if (typeof pattern !== 'string' || !pattern.trim()) throw Error('package.json workspace entries must be non-empty paths.');
-      const normalized = slash(pattern.trim()).replace(/^\.\//, '');
+      const written = slash(pattern.trim()).replace(/^\.\//, '');
+      if (sideRoot && !written.startsWith(`${side}/`)) continue;
+      const normalized = sideRoot ? written.slice(side.length + 1) : written;
       const segments = normalized.split('/');
       if (path.isAbsolute(normalized) || segments.some(segment => segment === '..' || (segment.includes('*') && segment !== '*'))) {
         throw Error(`Unsupported local workspace pattern: ${normalized}.`);
@@ -121,7 +129,10 @@ function workspaceDirectories(root) {
     for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
       for (const [name, value] of Object.entries(pkg?.[section] ?? {})) {
         if (typeof value !== 'string' || !value.startsWith('file:')) continue;
-        const absolute = path.resolve(packageRoot, value.slice('file:'.length));
+        const absolute = path.resolve(sideRoot ? appPackageRoot : packageRoot, value.slice('file:'.length));
+        // The app's one package.json also lists the other side's file dependencies (inside the app, outside this side): not this
+        // side's. A path that leaves the app is judged like any other: a package of the same repository, or refused.
+        if (sideRoot && !isInside(root, absolute) && isInside(appPackageRoot, absolute)) continue;
         const label = `${section}.${name} file dependency`;
         if (isInside(root, absolute)) { admit(absolute, label, true); continue; }
         // A sibling package of the same repository: this project consumes it, so the path is real and
@@ -248,15 +259,19 @@ const GRAMMAR_PACKAGE = '@starci/grammar';
  * source, every app and every workspace package that depends on the Grammar package is a consumer. null when no app has
  * a globals.css to judge (the contract is then reported unavailable, never passed).
  */
-function derivedGrammar(root, apps, workspaces) {
+function derivedGrammar(root, packageRoot, workspaces, apps = []) {
   const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
   if (!styleSources.length) return null;
-  const consumerManifests = apps.map(app => `apps/${app.name}/package.json`).filter(relative => existingRegularFile(root, relative));
+  // The apps have no package.json of their own: the app root's one manifest declares their dependencies, and it is a consumer
+  // when it declares the Grammar package; so is every workspace package that does.
+  const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE)));
+  const appManifest = slash(path.relative(root, path.join(packageRoot, 'package.json')));
+  const consumerManifests = declaresGrammar(readJson(path.join(packageRoot, 'package.json'))) ? [appManifest] : [];
   for (const workspace of workspaces) {
     if (!workspace.startsWith('packages/')) continue;
     const manifest = `${workspace}/package.json`;
     const pkg = readJson(path.join(root, ...manifest.split('/')));
-    if (pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE))) consumerManifests.push(manifest);
+    if (declaresGrammar(pkg)) consumerManifests.push(manifest);
   }
   if (!consumerManifests.length) return null;
   return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react'] };
@@ -272,10 +287,14 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
   if (!fs.lstatSync(root).isDirectory()) throw Error('Repository root must be a directory.');
   const opened = hfs ?? openHfs({ repoRoot: root });
   const { profile, apps } = opened.repo;
-  const workspaces = workspaceDirectories(root);
-  const inferred = inferredLayout(root, [...new Set([...workspaces, ...apps.map(app => `apps/${app.name}`)])].sort());
+  // A side of an app (the side folder is the root the machine judges) keeps its dependencies in the app root's one package.json.
+  const side = opened.repo.side ?? null;
+  const packageRoot = side === null ? root : path.dirname(root);
+  const workspaces = workspaceDirectories(root, { packageRoot, side });
+  const appDirs = apps.map(app => `apps/${app.name}`);
+  const inferred = inferredLayout(root, [...new Set([...workspaces, ...appDirs])].sort());
   const kinds = [profile === 'be' ? 'backend' : 'frontend'];
-  const projects = discoveredProjects(root, workspaces);
+  const projects = discoveredProjects(root, [...new Set([...workspaces, ...appDirs])].sort());
   if (!projects.length) throw Error('The repository has no tsconfig.json to derive a TypeScript project from.');
   const backend = {
     modules: ['src/modules'],
@@ -290,11 +309,12 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
     hooks: inferred.hooks,
     modules: inferred.modules,
     transport: inferred.transport,
-    grammar: profile === 'fe' ? derivedGrammar(root, apps, workspaces) : null,
+    grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps) : null,
   };
   if (profile === 'fe') assertFrontendRolesDisjoint(root, frontend);
   return {
     root,
+    packageRoot,
     repository: enclosingRepository(root),
     kinds,
     projects,

package/runtime/scripts/checks/architecture/contracts.mjs

@@ -276,7 +276,7 @@ function contractTypeStatusFromType(ts, checker, type, seen = new Set(), depth =
   }
   for (const anonymous of ['Record', 'Partial', 'Pick', 'Omit', 'Required']) if (builtinSymbol(ts, named, anonymous)) return 'inline';
   if (type.aliasSymbol) return 'named';
-  if (type.symbol?.getDeclarations?.().some(declaration => ts.isEnumDeclaration(declaration))) return 'named';
+  if ((type.symbol?.getDeclarations?.() ?? []).some(declaration => ts.isEnumDeclaration(declaration))) return 'named';
   if (type.flags & ts.TypeFlags.TypeParameter) return 'named';
   if (type.flags & ts.TypeFlags.Boolean) return 'scalar';
   if (type.flags & (ts.TypeFlags.Union | ts.TypeFlags.Intersection)) return 'inline';
@@ -590,7 +590,7 @@ function checkMessageReadonly(config, context, checker, declaration, localFiles,
     }
     const type = classInstanceType(ts, checker, selected);
     for (const base of type && checker.getBaseTypes ? checker.getBaseTypes(type) : []) {
-      const declarations = base.symbol?.getDeclarations?.().filter(item => ts.isClassDeclaration(item)) ?? [];
+      const declarations = (base.symbol?.getDeclarations?.() ?? []).filter(item => ts.isClassDeclaration(item)) ?? [];
       if (declarations.length !== 1) {
         reasons.push(`${relativePath(config.root, sourceFile.fileName)} inherits message fields from a class outside the checked production program`);
       } else if (localFiles.has(canonical(declarations[0].getSourceFile().fileName))) visitClass(declarations[0]);
@@ -654,7 +654,7 @@ function checkInjectedClass(config, context, checker, declaration, classKind, ta
   if (classKind) {
     const type = classInstanceType(ts, checker, declaration);
     for (const base of type && checker.getBaseTypes ? checker.getBaseTypes(type) : []) {
-      const declarations = base.symbol?.getDeclarations?.().filter(item => ts.isClassDeclaration(item)) ?? [];
+      const declarations = (base.symbol?.getDeclarations?.() ?? []).filter(item => ts.isClassDeclaration(item)) ?? [];
       if (declarations.length !== 1) {
         reasons.push(`${relativePath(config.root, sourceFile.fileName)} inherits an injected constructor from a class outside the checked production program`);
       } else if (localFiles.has(canonical(declarations[0].getSourceFile().fileName))) {
@@ -709,7 +709,7 @@ export function checkBackendContracts(config, context) {
       publicReasons.push(`${owner.entry} uses export =, so named capability API discovery is unavailable`);
     }
     for (const symbol of exportedSymbols(ts, checker, entry)) {
-      const declarations = symbol.getDeclarations?.().filter(declaration => localFiles.has(canonical(declaration.getSourceFile().fileName))) ?? [];
+      const declarations = (symbol.getDeclarations?.() ?? []).filter(declaration => localFiles.has(canonical(declaration.getSourceFile().fileName))) ?? [];
       if (!declarations.length) continue;
       const representative = declarations[0];
       if (isFrameworkHelper(representative.getSourceFile(), representative, framework)) continue;

package/runtime/scripts/checks/architecture/fe-slot-allows.mjs

@@ -1,14 +1,17 @@
 import { treeOf } from './required-files.mjs';
 import { allowsFile } from '../../lib/hfs-allows.mjs';
+import { isFeTestPath } from '../../lib/hfs-rules/fe-no-tests.mjs';
 
 /**
  * R94 `fe-slot-allows` (FE_SLOT_FILE_ROLE). A front-end slot that owns a whole directory (`fe.route`, `fe.feature`,
  * `fe.components`, `fe.hooks`, `fe.modules.api`) also says what its instances hold (`allows` in knowledge/hfs/slots.yaml).
  * Every tracked file of such a slot is matched against the `requires` and `allows` entries of its slot; a file no entry names is a
- * finding - `page.tsx` in a hooks domain, a `[lang]` segment under `app/`, a `.test.tsx` beside a component, a stray file at
- * a feature root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
+ * finding - `page.tsx` in a hooks domain, a `[lang]` segment under `app/`, a stray file beside a component or at a feature
+ * root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
  * Files no slot owns are HFS_PATH_NO_SLOT's (`hfs check`), so together every front-end file is placed by exactly one slot and
- * named by it.
+ * named by it. A test path (a `.spec.tsx` or `.test.tsx` beside a component, a test directory or test tooling) is FE_NO_TESTS's
+ * (R97, contract-change fe-no-tests): that rule is the one finding of such a file, so this check leaves it alone, as
+ * HFS_PATH_NO_SLOT does (scripts/lib/hfs-path-findings.mjs).
  */
 export const FE_SLOT_ALLOWS_RULE_IDS = ['FE_SLOT_FILE_ROLE'];
 
@@ -21,6 +24,7 @@ export function checkFeSlotAllows({ config, graph }) {
   let files = 0;
   const report = (file, message, extra = {}) => violations.push({ ruleId: RULE, path: file, line: 1, column: 1, message, ...extra });
   for (const file of [...tree.files].sort()) {
+    if (isFeTestPath(file)) continue;   // FE_NO_TESTS's, the one finding of that file
     const classified = resolver.classifyPath(file);
     if (classified.status !== 'owned') continue;
     const slot = resolver.slot(classified.slot);

package/runtime/scripts/checks/architecture/framework-pinned.mjs

@@ -1,14 +1,11 @@
 // framework-pinned.mjs - the Next.js files that only load from a source root (the directory holding
-// app/), and the export names the framework mandates in them. Authored once in
-// knowledge/patterns/fe/folder.yaml FE-FOLDER-1 (frameworkPinnedRootFiles, frameworkPinnedRootExports),
-// never hard-coded here (supervisor rulings, nivo wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4 and
-// inc-846867b9a34e). Read by the architecture check (FE_SOURCE_LAYOUT_INVALID) and the Next name-shape
-// check (FE_SOURCE_NAME_SHAPE).
+// app/). Authored once in knowledge/patterns/fe/folder.yaml FE-FOLDER-1 (frameworkPinnedRootFiles), never
+// hard-coded here (supervisor ruling, nivo wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4). Read by the architecture
+// check (FE_SOURCE_LAYOUT_INVALID).
 //
-// An unreadable or malformed list is a broken install, not "no pinned files": both readers throw
+// An unreadable or malformed list is a broken install, not "no pinned files": the reader throws
 // ARCH_KNOWLEDGE_UNAVAILABLE so the caller reports an error instead of judging with a different contract.
 import fs from 'node:fs';
-import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml } from '../../../engine/yaml.mjs';
 
@@ -21,11 +18,6 @@ function unavailable(file, detail) {
   return Error(`ARCH_KNOWLEDGE_UNAVAILABLE: ${file} ${detail}`);
 }
 
-/** The file stem Next.js keys a pinned file by: `middleware.ts` -> `middleware`, `next-env.d.ts` -> `next-env`. */
-export function pinnedStem(fileName) {
-  return path.basename(fileName).replace(/(?:\.d)?\.[cm]?[jt]sx?$/i, '');
-}
-
 function load(file) {
   if (cache.has(file)) return cache.get(file);
   let rule;
@@ -38,21 +30,7 @@ function load(file) {
   if (!Array.isArray(list) || !list.length || list.some(name => typeof name !== 'string' || !EXACT_NAME.test(name))) {
     throw unavailable(file, 'FE-FOLDER-1 frameworkPinnedRootFiles must be a nonempty list of exact file names.');
   }
-  const files = new Set(list);
-  const stems = new Set(list.map(pinnedStem));
-  const declared = rule.frameworkPinnedRootExports;
-  if (!declared || typeof declared !== 'object' || Array.isArray(declared)) {
-    throw unavailable(file, 'FE-FOLDER-1 frameworkPinnedRootExports must map a pinned file stem to its framework-mandated export names.');
-  }
-  const exports = new Map();
-  for (const [stem, names] of Object.entries(declared)) {
-    if (!stems.has(stem)) throw unavailable(file, `FE-FOLDER-1 frameworkPinnedRootExports names ${stem}, which no frameworkPinnedRootFiles entry pins.`);
-    if (!Array.isArray(names) || !names.length || names.some(name => typeof name !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(name))) {
-      throw unavailable(file, `FE-FOLDER-1 frameworkPinnedRootExports.${stem} must be a nonempty list of export identifiers.`);
-    }
-    exports.set(stem, new Set(names));
-  }
-  const loaded = { files, exports };
+  const loaded = { files: new Set(list) };
   if (file === FRAMEWORK_PINNED_KNOWLEDGE) cache.set(file, loaded);
   return loaded;
 }
@@ -61,23 +39,3 @@ function load(file) {
 export function frameworkPinnedRootFiles(file = FRAMEWORK_PINNED_KNOWLEDGE) {
   return load(file).files;
 }
-
-/** Map of pinned file stem to the export names the framework mandates there. */
-export function frameworkPinnedRootExports(file = FRAMEWORK_PINNED_KNOWLEDGE) {
-  return load(file).exports;
-}
-
-/**
- * The framework-mandated export names for an absolute source file when it is a pinned file sitting
- * directly in a Next source root (its directory holds an app/ directory), else null.
- */
-export function frameworkMandatedExports(absoluteFile, file = FRAMEWORK_PINNED_KNOWLEDGE) {
-  const { files, exports } = load(file);
-  if (!files.has(path.basename(absoluteFile))) return null;
-  try {
-    if (!fs.statSync(path.join(path.dirname(absoluteFile), 'app')).isDirectory()) return null;
-  } catch {
-    return null;
-  }
-  return exports.get(pinnedStem(absoluteFile)) ?? new Set();
-}

package/runtime/scripts/checks/architecture/frontend.mjs

@@ -108,13 +108,15 @@ function checkGrammar(config, context) {
   // Node resolution per consumer: in an npm-workspaces monorepo a consumer whose range differs from the
   // hoisted copy gets its own apps/<app>/node_modules/<package> (nivo-fe: apps/app on 0.5.0 beside a hoisted
   // 0.4.11). Every consumer is judged against the copy it actually resolves, never the hoisted one alone.
+  // An app installs once, at its root (config.packageRoot): a side folder has no node_modules of its own.
+  const installRoot = config.packageRoot ?? config.root;
   const installedFrom = (from) => {
-    for (let dir = from; isInside(config.root, dir); dir = path.dirname(dir)) {
+    for (let dir = from; isInside(installRoot, dir); dir = path.dirname(dir)) {
       const candidate = path.join(dir, 'node_modules', ...grammar.package.split('/'));
       if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate;
-      if (dir === config.root || path.dirname(dir) === dir) break;
+      if (dir === installRoot || path.dirname(dir) === dir) break;
     }
-    return path.join(config.root, 'node_modules', ...grammar.package.split('/'));
+    return path.join(installRoot, 'node_modules', ...grammar.package.split('/'));
   };
   const consumers = grammar.consumerManifests.map(relative => {
     const root = path.dirname(path.join(config.root, ...relative.split('/')));
@@ -123,7 +125,7 @@ function checkGrammar(config, context) {
       manifest: readJson(path.join(config.root, ...relative.split('/'))) ?? {} };
   });
   const installs = [...new Map(consumers.map(consumer => [consumer.packageRoot, consumer])).values()];
-  const packageRoot = installs[0]?.packageRoot ?? local?.root ?? path.join(config.root, 'node_modules', ...grammar.package.split('/'));
+  const packageRoot = installs[0]?.packageRoot ?? local?.root ?? path.join(installRoot, 'node_modules', ...grammar.package.split('/'));
   const manifestFile = path.join(packageRoot, 'package.json');
   const manifest = readJson(manifestFile);
   const ownerOf = (fileName) => consumers.filter(consumer => isInside(consumer.root, fileName))