@starci/eslint-canon-fe 6.0.1 → 7.0.0

package/runtime/knowledge/hfs/slots.yaml

@@ -84,7 +84,6 @@ tiers:
     foundation:   {mayImport: [foundation, package], acyclic: true}               # modules/{config,i18n,routes,types}
     modules:      {mayImport: [foundation, modules, transport, package], acyclic: true}
     transport:    {mayImport: [foundation, modules, package]}                     # modules/api: the one fetch
-    e2e:          {mayImport: [e2e, package]}                                     # black box: no app source
     package:      {mayImport: [package]}
 crossOwner: every import across owners targets the owner's public entry (index.ts or index.tsx); never export *.
 crossApp: apps never import each other; shared code is a packages/<pkg> slot.
@@ -109,6 +108,7 @@ ruleParams:
       http: [platform/http]
       https: [platform/http]
       cache-manager: [integrations/cache, integrations/redis]
+      "@nestjs/cache-manager": [integrations/cache, integrations/redis]     # the CACHE_MANAGER token: caching goes through the cache capability (retired local rule must-use-cache-service)
       redis: [integrations/cache, integrations/redis]
       ioredis: [integrations/cache, integrations/redis]
       bullmq: [platform/messaging]
@@ -126,11 +126,31 @@ ruleParams:
       "@nestjs/config": []
       dotenv: []
       "@nestjs/event-emitter": []
+    # R48 BE_SPEC_QUALITY spec-infra-double-from-kit: in a `<name>.service.spec.ts` a provider `{ provide: TOKEN, useValue: X }` takes X from
+    # the kit named here (the package root of `kit`). The token name is normalised to UPPER_SNAKE (`EntityManager` -> ENTITY_MANAGER), the
+    # FIRST entry whose `token` regex matches decides, and `fallback` decides for every other token. `forms` say what X may be:
+    # call = `double(...)`, new = `new Double(...)`, curried = `double(...)(...)`, object = a plain object literal (REAL values),
+    # primitive = a string/number/boolean literal, array = an array literal (multi-providers of doubles). A const bound to such a value counts.
+    specDoubles:
+      kit: "@starci/jest-preset"
+      doubles:
+        - {token: "(?:^|_)OPTIONS$", double: builder, forms: [curried, object]}
+        - {token: "(?:^|_)ENTITY_MANAGER$", double: mockEntityManager, forms: [call]}
+        - {token: "(?:^|_)TRANSACTION(?:_RUNNER)?$", double: fakeTransaction, forms: [call]}
+        - {token: "(?:^|_)CLOCK$", double: FakeClock, forms: [new]}
+        - {token: "(?:^|_)OUTBOX(?:_|$)", double: recordingOutbox, forms: [call]}
+        - {token: "(?:^|_)CACHE(?:_|$)", double: fakeCache, forms: [call]}
+        - {token: "(?:^|_)(?:LOCK|LEASE|FENCE|HOLD)(?:_|$)", double: fakeLock, forms: [call]}
+        - {token: "(?:^|_)(?:IDS|ID_GENERATOR|ID_FACTORY)$", double: fakeIds, forms: [call]}
+      fallback: {double: mock, forms: [call, primitive, array]}
     # R89 BE_SOURCE_FORM: the closed role-suffix vocabulary of a source file name (<kebab-name>.<suffix>.ts; BE-CONVENTION 1.15)
     # and the suffixes that are never a role. index.ts, main.ts, app.module.ts and the migrations of be.persistence are the
     # only names outside it.
-    suffixes: [module, module-definition, decorators, options, config, connection, service, command, query, handler, contracts, port, resolver, controller, gateway, consumer, job, cli, input, type, args, request, response, mapper, policy, entity, sql, rows, error, messages, log-events, cache-keys, guard, interceptor, filter, client, spec, integration-spec, e2e-spec, contract-spec, global-setup]
-    bannedSuffixes: [use-case, repository, store, worker, scheduler, cron, listener, dto, util, utils, helper, helpers, rules, types, constants, int-spec, harness-spec, test]
+    suffixes: [module, module-definition, decorators, options, config, connection, service, command, query, handler, contracts, port, resolver, controller, gateway, consumer, job, cli, input, type, args, request, response, mapper, policy, entity, sql, rows, error, messages, log-events, cache-keys, guard, interceptor, filter, client, spec, integration-spec, e2e-spec, contract-spec, global-setup, builder]
+    # R47 BE_CONTRACT_UNGUARDED: the world's shape vocabulary. `helper` names the function a contract spec imports to erase the values of a JSON
+    # payload (`shapeOf`); a contract spec proves a fake's fixtures by asserting helper(real) equals helper(fixture).
+    contractShape: {helper: shapeOf}
+    bannedSuffixes: [use-case, repository, fixture, factory, store, worker, scheduler, cron, listener, dto, util, utils, helper, helpers, rules, types, constants, int-spec, harness-spec, test]
   fe:
     # Slot budgets (component.tsx 300, hooks 200, modules 400) are stricter than this cap where they apply.
     fileLines: {soft: 500, hardGrowth: true}
@@ -248,12 +268,11 @@ slots:
     profiles: [fe]
     # Managed files (hfs sync renders them, hfs check compares them): the tool configuration of a front end. Each is a
     # reference to a canon package, never a configuration: tsconfig.json extends @starci/tsconfig/next.json and only
-    # excludes the e2e tree (each app's own tsconfig.json, in fe.app.next, carries its aliases and include);
-    # tsconfig.e2e.json extends the e2e preset over e2e/ and playwright.config.ts; eslint.config.mjs is the one-line
-    # starciFeConfig call (it lints apps, packages and e2e/ in one run, so there is no separate e2e lint); stylelint.config.mjs
-    # is the one-line starciStylelintConfig call; vitest.config.ts is the one-line starciVitestWorkspace call;
-    # .prettierrc names @starci/prettier-config; .prettierignore is the template.
-    path: "{tsconfig.json,tsconfig.e2e.json,eslint.config.mjs,stylelint.config.mjs,vitest.config.ts,.prettierrc,.prettierignore}"
+    # names the preset and nothing else (each app's own tsconfig.json, in fe.app.next, carries its aliases and include; there is
+    # no test tsconfig: a front end has no tests, FE_NO_TESTS); eslint.config.mjs is the one-line starciFeConfig call;
+    # stylelint.config.mjs is the one-line starciStylelintConfig call; .prettierrc names @starci/prettier-config;
+    # .prettierignore is the template. A front end has no test configuration at all (FE_NO_TESTS).
+    path: "{tsconfig.json,eslint.config.mjs,stylelint.config.mjs,.prettierrc,.prettierignore}"
     presence: required
     tracked: tracked
     tier: none
@@ -262,18 +281,15 @@ slots:
     rules: [HFS_MANAGED_FILE_DRIFT, HFS_TOOL_CONFIG_LOCAL, HFS_RULE_OFF_WITHOUT_REPLACEMENT, HFS_TS_STRICT]
   - id: fe.tool-config-repo
     profiles: [fe]
-    # The three tool files a preset cannot render because they carry the repository's own facts: vitest.setup.ts (its
-    # setup), playwright.config.ts (its web servers, ports and projects: @starci/playwright-preset returns the shared
-    # defaults and the repository adds what only it knows) and turbo.json (its task graph).
-    path: "{vitest.setup.ts,playwright.config.ts,turbo.json}"
-    roles: {playwright: playwright.config.ts}
+    # The one tool file a preset cannot render because it carries the repository's own facts: turbo.json (its task graph).
+    path: turbo.json
     presence: optional
     tracked: tracked
     tier: none
     tests: none
   - id: fe.tool-config-local
     profiles: [fe]
-    path: "{.eslintrc,.eslintrc.*,.eslintignore,eslint.config.js,eslint.config.cjs,eslint.config.ts,eslint.config.mts,eslint.config.cts,.stylelintrc,.stylelintrc.*,.stylelintignore,stylelint.config.js,stylelint.config.cjs,stylelint.config.ts,stylelint.config.json,prettier.config.*,.prettierrc.*,vitest.config.js,vitest.config.mjs,vitest.config.cjs,vitest.workspace.*,jest.config.*,lint-staged.config.*,.lintstagedrc*}"
+    path: "{.eslintrc,.eslintrc.*,.eslintignore,eslint.config.js,eslint.config.cjs,eslint.config.ts,eslint.config.mts,eslint.config.cts,.stylelintrc,.stylelintrc.*,.stylelintignore,stylelint.config.js,stylelint.config.cjs,stylelint.config.ts,stylelint.config.json,prettier.config.*,.prettierrc.*,lint-staged.config.*,.lintstagedrc*}"
     presence: forbidden
     tracked: external
     tier: none
@@ -282,7 +298,7 @@ slots:
     rules: [HFS_TOOL_CONFIG_LOCAL]
   - id: repo.quality-config
     profiles: [be, fe]
-    path: "{sonar-project.properties,codecov.yml}"
+    path: sonar-project.properties
     presence: required
     tracked: tracked
     tier: none
@@ -308,7 +324,7 @@ slots:
     managedBy: ci-workflows
     rules: [HFS_CI_E2E_AUTOMATIC, HFS_CI_MISSING_CANON, HFS_MANAGED_FILE_DRIFT]
   - id: repo.ci-e2e
-    profiles: [be, fe]
+    profiles: [be]
     path: ".github/workflows/e2e.yml"
     presence: optional     # on: workflow_dispatch only
     tracked: tracked
@@ -325,12 +341,15 @@ slots:
     tests: none
   - id: repo.scripts
     profiles: [be, fe]
-    path: "scripts/<name>.mjs"
+    # The repository's operational scripts only (`*.mjs`, `*.cjs`, `*.ps1`, `*.sh`), or nothing: an empty folder is `scripts/.gitkeep`, which hfs sync --init writes
+    # when the folder is missing. A spec or a test (BE_SPEC_PLACEMENT, FE_NO_TESTS), a check or lint source (`check-*`, `eslint-local-rules*`, a local eslint
+    # plugin: HFS_REPO_LOCAL_CHECK) and anything that re-implements a canon check is not an operational script and has no place here.
+    path: "scripts/{.gitkeep,*.mjs,*.cjs,*.ps1,*.sh}"
     presence: optional
     tracked: tracked
     tier: none
     tests: none
-    rules: [HFS_SCRIPT_ONE_OFF]     # one-off codemods and fix-* scripts are agent output, not tooling
+    rules: [HFS_SCRIPT_ONE_OFF, BE_SPEC_PLACEMENT, HFS_REPO_LOCAL_CHECK]     # one-off codemods and fix-* scripts are agent output, not tooling
   - id: repo.docs
     profiles: [be, fe]
     path: "docs/{adr,runbooks,guides}/**/*.md"
@@ -375,7 +394,7 @@ slots:
   # ----- never tracked: build output the tools need in place ---------------------------------------------
   - id: repo.build-output
     profiles: [be, fe]
-    path: "{**/node_modules/,dist/,apps/*/dist/,packages/*/dist/,.next/,apps/*/.next/,coverage/,reports/,test-results/,playwright-report/,**/next-env.d.ts,**/*.tsbuildinfo}"
+    path: "{**/node_modules/,dist/,apps/*/dist/,packages/*/dist/,.next/,apps/*/.next/,coverage/,reports/,test-results/,**/next-env.d.ts,**/*.tsbuildinfo}"
     presence: optional
     tracked: ignored
     tier: none
@@ -450,6 +469,7 @@ slots:
     tracked: tracked
     tier: none
     tests: none
+    why: emitted by `npm run contract:emit` (`hfs emit-contracts`, never written by hand) from the app's typed operation table `apps/<app>/src/operations.ts` (canon BE-OPERATIONS-1); CI fails when the emitted file differs
     rules: [HFS_CONTRACT_SNAPSHOT_DRIFT]
   - id: fe.contract.copy
     profiles: [fe]
@@ -471,9 +491,9 @@ slots:
     tier: app
     owner: true
     minInstances: 1
-    requires: [main.ts, app.module.ts, "<app>.composition.spec.ts"]
-    allows: [main.ts, app.module.ts, "<app>.composition.spec.ts", "<app>.options.ts"]
-    tests: unit-beside            # the composition spec boots the REAL AppModule with stubbed options
+    requires: [main.ts, app.module.ts]
+    allows: [main.ts, app.module.ts, "<app>.options.ts", operations.ts]
+    tests: none                   # an app is proven by the e2e world (useTestWorld({ apps })), never by a unit spec
     budget: {app.module.ts: 250, main.ts: 80}
     rules: [BE_APP_COMPOSITION_ONLY, BE_APP_BUSINESS_ROLE, BE_DEFAULT_DENY, BE_ERROR_MASKED, BE_FEATURE_NOT_COMPOSED]
   - id: be.app.worker
@@ -484,8 +504,9 @@ slots:
     tracked: tracked
     tier: app
     owner: true
-    requires: [main.ts, app.module.ts, "<app>.composition.spec.ts"]
-    tests: unit-beside
+    requires: [main.ts, app.module.ts]
+    allows: [main.ts, app.module.ts, "<app>.options.ts"]
+    tests: none                   # an app is proven by the e2e world (useTestWorld({ apps })), never by a unit spec
     rules: [BE_APP_COMPOSITION_ONLY, BE_BACKGROUND_UNOWNED]
   - id: be.app.migrate
     profiles: [be]
@@ -496,8 +517,9 @@ slots:
     tracked: tracked
     tier: app
     owner: true
-    requires: [main.ts, "<app>.composition.spec.ts"]
-    tests: unit-beside
+    requires: [main.ts]
+    allows: [main.ts, "<app>.options.ts"]
+    tests: none                   # an app is proven by the e2e world (useTestWorld({ apps })), never by a unit spec
     rules: [BE_SCHEMA_AUTHORITY, BE_ENTRYPOINT_ONLY_IN_APPS]
   - id: be.app.cli
     profiles: [be]
@@ -507,8 +529,9 @@ slots:
     tracked: tracked
     tier: app
     owner: true
-    requires: [main.ts, app.module.ts, "<app>.composition.spec.ts"]
-    tests: unit-beside
+    requires: [main.ts, app.module.ts]
+    allows: [main.ts, app.module.ts, "<app>.options.ts"]
+    tests: none                   # an app is proven by the e2e world (useTestWorld({ apps })), never by a unit spec
 
   # ----- BE: features ------------------------------------------------------------------------------------
   - id: be.feature
@@ -521,7 +544,7 @@ slots:
     minInstances: 1
     requires: [index.ts, "<feature>.module.ts", application/]
     allows: [index.ts, "<feature>.module.ts", application/, transport/, messages/]   # nothing else at feature root
-    tests: unit-beside
+    tests: none
     budget: {files: 250, indexExports: 60}   # a feature above 250 source files must be split by product capability
     rules: [BE_FEATURE_SHAPE, BE_FEATURE_IMPORTS_FEATURE, BE_PUBLIC_SURFACE, BE_FEATURE_NOT_COMPOSED]
   - id: be.feature.application
@@ -530,9 +553,9 @@ slots:
     presence: required
     tracked: tracked
     tier: feature
-    allows: ["<action>.{command,query,handler,contracts}.ts", "*.spec.ts"]
+    allows: ["<action>.{command,query,handler,contracts}.ts"]
     forbids: [graphql/, http/, message/, schedule/, transport/]   # no protocol names under application/
-    tests: unit-beside
+    tests: none
     rules: [BE_APPLICATION_IMPORTS_TRANSPORT, BE_APPLICATION_TRANSPORT_FRAMEWORK, BE_ENTITY_IN_CONTRACT, BE_CQRS_SHAPE]
   - id: be.feature.application.support
     profiles: [be]
@@ -540,9 +563,9 @@ slots:
     presence: optional            # helpers and types local to ONE feature; same tier as application, never a shared home
     tracked: tracked
     tier: feature                 # feature tier: another feature cannot import it (features never import features)
-    allows: ["<name>.<role>.ts", "*.spec.ts"]     # <role> from ruleParams.be.suffixes; no <name>.types.ts
+    allows: ["<name>.<role>.ts"]     # <role> from ruleParams.be.suffixes; no <name>.types.ts
     forbids: [graphql/, http/, message/, schedule/, transport/]
-    tests: unit-beside            # a <name>.spec.ts beside every <name>.ts
+    tests: none
     rules: [BE_APPLICATION_IMPORTS_TRANSPORT, BE_APPLICATION_TRANSPORT_FRAMEWORK, BE_FEATURE_IMPORTS_FEATURE]
     since: 1.0.0
   - id: be.transport.http
@@ -552,8 +575,8 @@ slots:
     tracked: tracked
     tier: feature
     requires: ["<feature>-http.module.ts"]
-    allows: ["<action>.controller.ts", "dto/<action>.{request,response}.ts", "<action>.mapper.ts", "*.spec.ts"]
-    tests: unit-beside
+    allows: ["<action>.controller.ts", "dto/<action>.{request,response}.ts", "<action>.mapper.ts"]
+    tests: none
     composedBy: [api]
     rules: [BE_DEFAULT_DENY, BE_INPUT_BOUNDED, BE_TRANSPORT_SHAPE]
   - id: be.transport.graphql
@@ -563,8 +586,8 @@ slots:
     tracked: tracked
     tier: feature
     requires: ["<feature>-graphql.module.ts"]
-    allows: ["<action>.resolver.ts", "dto/<action>.{input,type,args}.ts", "<action>.mapper.ts", "*.spec.ts"]
-    tests: unit-beside
+    allows: ["<action>.resolver.ts", "dto/<action>.{input,type,args}.ts", "<action>.mapper.ts"]
+    tests: none
     composedBy: [api]
     rules: [BE_DEFAULT_DENY, BE_INPUT_BOUNDED, BE_TRANSPORT_SHAPE]
   - id: be.transport.message
@@ -574,8 +597,8 @@ slots:
     tracked: tracked
     tier: feature
     requires: ["<feature>-message.module.ts"]
-    allows: ["<event>.consumer.ts", "<event>.message.ts", "*.spec.ts"]
-    tests: unit-beside
+    allows: ["<event>.consumer.ts"]     # BE-CONVENTION 1.6: transport/message holds only consumers; a .message.ts is outside the closed suffix list
+    tests: none
     composedBy: [worker]
     rules: [BE_BACKGROUND_UNOWNED]
   - id: be.transport.schedule
@@ -585,8 +608,8 @@ slots:
     tracked: tracked
     tier: feature
     requires: ["<feature>-schedule.module.ts"]
-    allows: ["<job>.job.ts", "*.spec.ts"]
-    tests: unit-beside
+    allows: ["<job>.job.ts"]
+    tests: none
     composedBy: [worker]
     rules: [BE_BACKGROUND_UNOWNED]
   - id: be.transport.websocket
@@ -596,8 +619,8 @@ slots:
     tracked: tracked
     tier: feature
     requires: ["<feature>-websocket.module.ts"]
-    allows: ["<channel>.gateway.ts", "dto/*.ts", "*.spec.ts"]
-    tests: unit-beside
+    allows: ["<channel>.gateway.ts", "dto/*.ts"]
+    tests: none
     composedBy: [api]
     since: 1.0.0
   - id: be.feature.transport.cli
@@ -607,8 +630,8 @@ slots:
     tracked: tracked
     tier: feature
     requires: ["<feature>-cli.module.ts"]
-    allows: ["<name>.cli.ts", "dto/*.ts", "*.spec.ts"]     # .cli.ts: .command.ts is a CQRS message (HFS delta 3)
-    tests: unit-beside
+    allows: ["<name>.cli.ts", "dto/*.ts"]     # .cli.ts: .command.ts is a CQRS message (HFS delta 3)
+    tests: none
     composedBy: [cli]
     rules: [BE_APPLICATION_IMPORTS_TRANSPORT, BE_FEATURE_NOT_COMPOSED, BE_ENTRYPOINT_ONLY_IN_APPS]
     since: 1.0.0
@@ -622,9 +645,9 @@ slots:
     tier: domain
     owner: true
     requires: [index.ts]
-    allows: ["<capability>.module.ts", "<capability>.config.ts", "<capability>.options.ts", errors/, messages/, persistence/, policies/, "*.service.ts", "*.contracts.ts", "*.spec.ts"]
+    allows: ["<capability>.module.ts", "<capability>.config.ts", "<capability>.options.ts", errors/, messages/, persistence/, policies/, "*.service.ts", "*.service.spec.ts", "*.contracts.ts"]
     forbids: [testing/, exceptions/, utils/, helpers/, shared/]
-    tests: unit-beside
+    tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts, nothing else
     budget: {indexExports: 60}
     rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_PUBLIC_SURFACE, BE_ERROR_HOME, BE_CONFIG_OWNER]
   - id: be.errors
@@ -633,17 +656,17 @@ slots:
     presence: optional
     tracked: tracked
     tier: inherit
-    allows: ["<capability>.error.ts", "<name>.error.ts", "*.spec.ts"]   # one family per capability, extends platform/errors DomainError
-    tests: unit-beside
+    allows: ["<capability>.error.ts", "<name>.error.ts"]   # one family per capability, extends platform/errors DomainError
+    tests: none
     rules: [BE_ERROR_HOME]
   - id: be.domain.messages
     profiles: [be]
-    path: "src/modules/{domain,integrations}/<capability>/messages/"
-    presence: optional            # a capability that raises no user-facing text carries none
+    path: "src/modules/{domain,platform,integrations}/<capability>/messages/"
+    presence: optional            # a capability (any tier) that raises no user-facing text carries none
     tracked: tracked
     tier: inherit
-    allows: ["<capability>.messages.ts", "*.spec.ts"]   # one keyed catalog per capability, vi and en, read through the platform/i18n MessageCatalog port
-    tests: unit-beside
+    allows: ["<capability>.messages.ts"]   # one keyed catalog per capability, vi and en, read through the platform/i18n MessageCatalog port
+    tests: none
     rules: [BE_USER_COPY_LITERAL]
     since: 1.0.0
   - id: be.feature.messages
@@ -652,8 +675,8 @@ slots:
     presence: optional
     tracked: tracked
     tier: feature
-    allows: ["<feature>.messages.ts", "*.spec.ts"]   # one keyed catalog per feature, vi and en, read through the platform/i18n MessageCatalog port
-    tests: unit-beside
+    allows: ["<feature>.messages.ts"]   # one keyed catalog per feature, vi and en, read through the platform/i18n MessageCatalog port
+    tests: none
     rules: [BE_USER_COPY_LITERAL]
     since: 1.0.0
   - id: be.persistence
@@ -662,10 +685,10 @@ slots:
     presence: optional
     tracked: tracked
     tier: inherit
-    requires: [connection.ts]     # CONNECTION = <CONN>_CONNECTION of an hfs.json connection, and the capability's <c>Entities / <c>Migrations arrays (the owner index re-exports the two arrays by name)
-    allows: ["entities/<table>.entity.ts", "migrations/<epochMs13>-<kebab-name>.ts", "<name>.sql.ts", "<name>.rows.ts", connection.ts, "*.spec.ts"]
+    requires: [connection.ts]     # the capability's <c>Entities / <c>Migrations arrays (the owner index re-exports the two arrays by name); no CONNECTION alias: the connection is the one the apps register the arrays on
+    allows: ["entities/<table>.entity.ts", "migrations/<epochMs13>-<kebab-name>.ts", "<name>.sql.ts", "<name>.rows.ts", connection.ts]
     forbids: [index.ts, "<name>.repository.ts"]
-    tests: unit-beside
+    tests: none
     rules: [BE_SCHEMA_OWNER, BE_SCHEMA_AUTHORITY, BE_SQL_OUTSIDE_PERSISTENCE]
   - id: be.platform
     profiles: [be]
@@ -684,7 +707,7 @@ slots:
     requiredInstances: {capability: [config, logging, errors, primitives, clock, i18n]}
     requires: [index.ts]
     forbids: [common/, utils/, shared/, testing/]   # primitives live in platform/primitives
-    tests: unit-beside
+    tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts, nothing else
     budget: {indexExports: 60}
     rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE]
   - id: be.integrations
@@ -695,7 +718,7 @@ slots:
     tier: integrations
     owner: true
     requires: [index.ts, "<provider>.config.ts"]
-    tests: unit-beside
+    tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts, nothing else
     budget: {indexExports: 60}
     rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT]
   - id: be.integrations.model
@@ -704,10 +727,10 @@ slots:
     presence: opt-in
     tracked: tracked
     tier: integrations
-    tests: unit-beside
+    tests: none
     why: an ML or LLM model client is an integration; weights and datasets are never in git
 
-  # ----- BE: tests (owner test layout 2026-09-30). Unit specs sit beside their subject (<name>.spec.ts); everything else
+  # ----- BE: tests (owner test layout 2026-09-30). Unit specs are <name>.service.spec.ts beside their service and nothing else; everything else
   # lives under src/tests/, one folder per kind, and the folder and the file suffix always agree (a file whose suffix does
   # not match its folder matches no slot: HFS_SLOT_UNDECLARED).
   - id: be.tests.world
@@ -716,25 +739,57 @@ slots:
     presence: optional
     tracked: tracked
     tier: e2e
-    allows: [global-setup.ts, global-teardown.ts, use-test-world.ts, fakes/, kit/]   # jest globalSetup/globalTeardown default-export (Jest API); plus root files with a role suffix (test-world-files, R47)
+    allows: [global-setup.ts, global-teardown.ts, use-test-world.ts, fakes/]   # jest globalSetup/globalTeardown default-export (Jest API); plus root files with a role suffix (test-world-files, R47)
     tests: none
     why: >-
       the ONLY test infrastructure location, shared by integration and e2e: global-setup.ts starts the shared
       infrastructure (containers) and runs apps/migrate's exported bootstrap once; use-test-world.ts exports
       useTestWorld({ apps: { <name>: { module, listen? } } } | { modules: [...] }) -> world.apps.<name>.api,
-      world.db.<connection> (the shared EntityManager), world.fake.<provider> (a network-edge fake started by the world, with
+      world.db.<connection> (the shared EntityManager), world.infra.<service> (latency/cut/restore on a REAL service of the repository's
+      own stack, `.starcistacks/<env>`, each behind toxiproxy), world.fake.<provider> (a network-edge fake of an external SaaS started by the world, with
       failNext/replayWebhook/delay), world.waitFor; fakes/<provider>/ holds the fake servers and payload fixtures, kit/ the inlined test helpers, and the world root may hold role-suffixed helpers (<name>.client.ts, <name>.contracts.ts, ...). Nothing is
       overridden in the DI container. It is the only test location that may import typeorm's DataSource or testcontainers,
       call migrate/runMigrations/synchronize, or write process.env.
+  - id: be.tests.world.kit
+    profiles: [be]
+    path: "src/tests/world/kit/"
+    presence: optional
+    tracked: tracked
+    tier: e2e
+    allows: ["<name>.ts"]    # plain kebab names, like platform/primitives (BE-CONVENTION 1.11 names primitives/time.ts): the world's inlined test helpers (poll, free-ports)
+    tests: none
+    why: the helpers the test world needs (polling, free ports, transports), inlined so the world imports no other repository; a bare <name>.ts entry in allows is what admits a plain name in BE_SOURCE_FORM
   - id: be.tests.fixtures
     profiles: [be]
     path: "src/tests/fixtures/"
     presence: optional
     tracked: tracked
     tier: fixtures
-    allows: [database.ts]         # mockEntityManager() and fakeTransaction() (BE-CONVENTION 1.16); other fixtures use role suffixes
-    tests: unit-beside
-    why: typed doubles and data builders; importable by unit specs, integration and e2e; never imports a feature
+    allows: [i18n/]   # i18n/ is the one folder that may carry localized text
+    tests: none
+    why: payload fixtures with a role suffix (the doubles come from @starci/jest-preset, not from here); the test data builders live in its builders/ slot; importable by unit specs, integration and e2e; never imports a feature
+  - id: be.tests.fixtures.builders
+    profiles: [be]
+    path: "src/tests/fixtures/builders/*.builder.ts"
+    presence: optional
+    tracked: tracked
+    tier: fixtures
+    tests: none
+    why: >-
+      the ONLY home of test data builders, one <area>.builder.ts per area, shared by every spec of that area: pure object builders
+      (commissionRow(overrides), accrueInput(overrides)) for unit specs and persisting builders (orderBuilder(world.db.primary).pending().build(overrides))
+      for integration and e2e; arrange only, constraints on, deterministic defaults. A .builder.ts anywhere else, and a *.repository.ts,
+      *.fixture.ts or *.factory.ts anywhere, is a BE_SOURCE_FORM finding
+    rules: [BE_SOURCE_FORM]
+  - id: be.tests.fixtures.i18n
+    profiles: [be]
+    path: "src/tests/fixtures/i18n/"
+    presence: optional
+    tracked: tracked
+    tier: fixtures
+    allows: ["<name>.<role>.ts"]   # data files that deliberately carry localized text (a real Vietnamese string a parser or formatter must accept); no specs here
+    tests: none
+    why: the ONLY test-fixture location where Vietnamese or another language may appear in source (LANG_NOT_ENGLISH); placement is the marker, there is no comment pragma
   - id: be.tests.integration
     profiles: [be]
     path: "src/tests/integration/<capability>/*.integration-spec.ts"
@@ -794,7 +849,7 @@ slots:
     tier: none
     tests: none
     requires: [application-stacks.yaml]
-    allows: [application-stacks.yaml, "<env>/README.md", "<env>/environment.json", "<env>/infra/{compose,k8s,terraform}/**",
+    allows: [application-stacks.yaml, "<env>/README.md", "<env>/environment.json", "<env>/infra/{compose,k8s,terraform}/**", "<env>/infra/metadata.json",
              "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.enc", "<env>/seeds/**"]
     forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
     rules: [HFS_STACKS_SHAPE, HFS_PLAINTEXT_SECRET, HFS_IDENTITY_CUSTODY]
@@ -821,11 +876,10 @@ slots:
     rules: [FE_APP_ISOLATION, FE_ERROR_BOUNDARY_MISSING, FE_NEXT_CONVENTIONS]
   - id: fe.app-optional
     profiles: [fe]
-    path: "apps/<app>/{vitest.config.ts,playwright.config.ts,public/}"
+    path: "apps/<app>/public/"
     presence: optional
     tracked: tracked
     tier: none
-    roles: {playwright: playwright.config.ts}
     tests: none
   - id: fe.route
     profiles: [fe]
@@ -837,8 +891,9 @@ slots:
              global-error.tsx, page.tsx,   # the root page.tsx only redirects (FE_ROUTE_FILES_THIN)
              not-found.tsx, layout.tsx,    # next-intl: a request outside every locale renders the root not-found inside a root layout
              "health/{live,ready}/route.ts", "api/**/route.ts", "_*/**", providers.tsx, globals.css,
-             "{icon,favicon,apple-icon,opengraph-image,twitter-image}.*", robots.ts, sitemap.ts, manifest.ts, "**/*.spec.ts", "**/*.spec.tsx"]
-    roles: {page: page.tsx, layout: layout.tsx, template: template.tsx, loading: loading.tsx, error: error.tsx, not-found: not-found.tsx, default: default.tsx, route: route.ts, global-error: global-error.tsx}
+             "{icon,favicon,apple-icon,opengraph-image,twitter-image}.*", robots.ts, sitemap.ts, manifest.ts]
+    # providers.tsx (root or [locale]) is the client wrapper the server layout renders around its children to host context providers.
+    roles: {page: page.tsx, layout: layout.tsx, template: template.tsx, loading: loading.tsx, error: error.tsx, not-found: not-found.tsx, default: default.tsx, route: route.ts, global-error: global-error.tsx, providers: providers.tsx}
     tests: none
     rules: [FE_ROUTE_FILES_THIN, FE_CLIENT_BOUNDARY, FE_OWNER_REACHABLE]
   - id: fe.source-root-pinned
@@ -868,9 +923,9 @@ slots:
     owner: true
     kinds: [pages, layouts, overlays]
     requires: [index.tsx]
-    allows: [index.tsx, component.tsx, classNames.ts, "*.spec.tsx", "*.spec.ts"]
+    allows: [index.tsx, component.tsx, classNames.ts]
     roles: {entry: index.tsx, drawing: component.tsx, styles: classNames.ts}   # the connected entry, the pure drawing half and the styling declarations of a component owner
-    tests: unit-beside
+    tests: none
     budget: {component.tsx: 300, index.tsx: 200, dataHooks: 6, useState: 6}
     rules: [FE_SIZE_BUDGET, FE_OWNER_REACHABLE, FE_I18N_LITERAL]
   - id: fe.components
@@ -882,9 +937,9 @@ slots:
     owner: true
     layers: [blocks, composites, branches, leaves]   # a layer imports only the layers after it
     requires: [index.tsx]
-    allows: [index.tsx, component.tsx, classNames.ts, "*.spec.tsx", "*.spec.ts"]
+    allows: [index.tsx, component.tsx, classNames.ts]
     roles: {entry: index.tsx, drawing: component.tsx, styles: classNames.ts}   # the connected entry, the pure drawing half and the styling declarations of a component owner
-    tests: unit-beside
+    tests: none
     budget: {component.tsx: 300, index.tsx: 200, dataHooks: 6, useState: 6}
     rules: [FE_CONNECTED_BLOCK_RENDER_PAIR, FE_I18N_LITERAL, FE_NATIVE_FORM_CONTROL, FE_CLIENT_BOUNDARY]
   - id: fe.hooks
@@ -895,9 +950,9 @@ slots:
     tier: hooks
     owner: true                   # a domain is an owner: other domains import it through index.ts only
     requires: [index.ts]
-    allows: [index.ts, "use<name>.ts", "<domain>.shared.ts", "*.spec.ts"]   # React hooks only; <domain>.shared.ts = sanctioned non-hook helpers
+    allows: [index.ts, "use<name>.ts", "<domain>.shared.ts"]   # React hooks only; <domain>.shared.ts = sanctioned non-hook helpers
     roles: {entry: index.ts, shared: "<domain>.shared.ts"}
-    tests: unit-beside
+    tests: none
     budget: {file: 200, dataHooks: 6, useState: 6}
     rules: [FE_HOOKS_ARE_HOOKS, FE_DATA_FRESHNESS]
   - id: fe.modules
@@ -909,7 +964,7 @@ slots:
     owner: true
     requiredInstances: {capability: [config, i18n, routes]}
     requires: [index.ts]
-    tests: unit-beside
+    tests: none
     budget: {file: 400}
     rules: [FE_ENV_OWNER, FE_TRANSPORT_OWNER]
   - id: fe.modules.api
@@ -922,9 +977,9 @@ slots:
     # client.ts/outcome.ts (fe.transport.client/outcome) in a one-app repository, or the api package's
     # (fe.package.api.client/outcome) when the repository shares it (FE_TRANSPORT_OWNER, machine).
     requires: [index.ts]
-    allows: [index.ts, client.ts, outcome.ts, "<domain>/read-*.ts", "<domain>/*.graphql", "<domain>/<domain>.mapper.ts", contract/, __generated__/, "*.spec.ts"]
+    allows: [index.ts, client.ts, outcome.ts, "<domain>/read-*.ts", "<domain>/*.graphql", "<domain>/<domain>.mapper.ts", contract/, __generated__/]
     roles: {entry: index.ts, reader: "read-*.ts"}   # a reader is a server module (FE_CLIENT_REACHES_SERVER)
-    tests: unit-beside
+    tests: none
     rules: [FE_TRANSPORT_OWNER, FE_HTTP_STATUS_COLLAPSE, FE_WIRE_GENERATED]
   - id: fe.transport.client
     profiles: [fe]
@@ -932,7 +987,7 @@ slots:
     presence: optional
     tracked: tracked
     tier: transport
-    tests: unit-beside
+    tests: none
     why: the one fetch of a one-app repository (timeout, abort, 401/403 -> refused); a shared client is fe.package.api.client
     rules: [FE_TRANSPORT_OWNER]
   - id: fe.transport.outcome
@@ -941,7 +996,7 @@ slots:
     presence: optional
     tracked: tracked
     tier: transport
-    tests: unit-beside
+    tests: none
     why: the one Outcome union of a one-app repository; a shared union is fe.package.api.outcome
     rules: [FE_HTTP_STATUS_COLLAPSE]
   - id: fe.modules.config
@@ -950,7 +1005,7 @@ slots:
     presence: required
     tracked: tracked
     tier: foundation
-    tests: unit-beside
+    tests: none
     why: the only reader of process.env and NEXT_PUBLIC_*; fails fast, no localhost fallback
   - id: fe.modules.i18n
     profiles: [fe]
@@ -962,7 +1017,7 @@ slots:
     # navigation, request config) is written once per repository: in the i18n package (fe.package.i18n, `createAppI18n`)
     # when the repository has one, else in the only app's module.
     requires: [index.ts]
-    tests: unit-beside
+    tests: none
     rules: [FE_I18N_PLACEMENT, FE_I18N_CATALOG]
   - id: fe.modules.brand
     profiles: [fe]
@@ -979,7 +1034,7 @@ slots:
     presence: required
     tracked: tracked
     tier: foundation
-    tests: unit-beside
+    tests: none
     why: every href builder; FE_HREF_RESOLVES checks each against app/
   - id: fe.modules.types
     profiles: [fe]
@@ -987,7 +1042,7 @@ slots:
     presence: optional
     tracked: tracked
     tier: foundation
-    tests: unit-beside
+    tests: none
     why: shared types with no runtime behaviour; a component may import them
   - id: fe.package.ui
     profiles: [fe]
@@ -999,7 +1054,7 @@ slots:
     kinds: [composites, branches, leaves]   # the layer folders under src/ (a package owns no blocks)
     roles: {entry: index.tsx, drawing: component.tsx, styles: classNames.ts}
     requires: [package.json, src/index.ts, tsconfig.json]
-    tests: unit-beside
+    tests: none
     budget: {component.tsx: 300, index.tsx: 200, dataHooks: 6, useState: 6}
     why: built to dist with explicit named exports; only composites, branches and leaves; no unused export; no colour literal
     rules: [FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT, FE_STYLE_TOKEN_ONLY]
@@ -1011,7 +1066,7 @@ slots:
     tier: package
     owner: true
     requires: [package.json, src/index.ts, src/client.ts, src/outcome.ts, tsconfig.json]
-    tests: unit-beside
+    tests: none
     why: the one transport client and the one Outcome union shared by every app of the repository; no app keeps its own
     rules: [FE_TRANSPORT_OWNER, FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT]
   - id: fe.package.api.client
@@ -1020,7 +1075,7 @@ slots:
     presence: optional     # enabled with its package (fe.package.api is the opt-in)
     tracked: tracked
     tier: package
-    tests: unit-beside
+    tests: none
     why: the repository's one fetch (timeout, abort, 401/403 -> refused)
     rules: [FE_TRANSPORT_OWNER]
   - id: fe.package.api.outcome
@@ -1029,7 +1084,7 @@ slots:
     presence: optional     # enabled with its package (fe.package.api is the opt-in)
     tracked: tracked
     tier: package
-    tests: unit-beside
+    tests: none
     why: the repository's one Outcome union
     rules: [FE_HTTP_STATUS_COLLAPSE]
   - id: fe.package.i18n
@@ -1040,25 +1095,9 @@ slots:
     tier: package
     owner: true
     requires: [package.json, src/index.ts, tsconfig.json]
-    tests: unit-beside
+    tests: none
     why: the next-intl stack (routing, navigation, request config) written once, exported as the createAppI18n factory every app calls
     rules: [FE_I18N_PLACEMENT, FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT]
-  - id: fe.e2e
-    profiles: [fe]
-    path: "e2e/<area>/*.e2e-spec.ts"
-    presence: optional
-    tracked: tracked
-    tier: e2e
-    tests: e2e
-    requires: [/playwright.config.ts, /tsconfig.e2e.json]
-    rules: [FE_E2E_SHAPE, HFS_CI_E2E_AUTOMATIC]
-  - id: fe.e2e-support
-    profiles: [fe]
-    path: "e2e/{support,fixtures}/"
-    presence: optional
-    tracked: tracked
-    tier: e2e
-    tests: none
 
 # Checks that read this manifest (all ship from .claude; none keeps its own path list)
 consumers: