@starci/eslint-canon-be 3.4.39 → 3.4.41

package/runtime/knowledge/hfs/slots.yaml

@@ -7,7 +7,7 @@
 # catalog READ this file through scripts/hfs/slots.mjs; none of them hardcodes a path.
 # Shape: modules/schemas/hfs-slots.schema.yaml. The repository side is hfs.json: modules/schemas/hfs-repo.schema.yaml.
 schema: starci/hfs-slots@3
-version: 3.6.0
+version: 3.7.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -42,7 +42,9 @@ versioning:
 # 3.5.0 is a minor (alpha.27): it ADDS the opt-in app.browser-config slot, the managed browser/tsconfig.json that type-checks the browser
 # journey (enabled with app.browser by `browser: true`).
 # 3.6.0 is a minor (alpha.30): it ADDS the opt-in be.feature.realtime.sse slot, the server-sent-events door of the realtime kind (owner decision
-# 2026-10-24: lite may serve SSE, and SSE is the default door for one-way push), and lets fe.modules.api hold the SSE stream readers (sse/).
+# 2026-10-24: lite may serve SSE, and SSE is the default door for one-way push), and lets fe.modules.api hold the SSE stream operations (sse/).
+# 3.7.0 is a minor (alpha.31): it ADDS the optional fe.transport.stream slot, the fetch reader of server-sent-events streams (the stream half of the
+# transport client layer), and lets fe.hooks.swr hold the SWR subscription hooks (api/sse/subscriptions/useSubscribe<X>Swr.ts, one useSWRSubscription per stream operation).
 
 # Field meaning, per slot.
 #   id          stable name, never changes meaning inside a major.
@@ -109,15 +111,18 @@ testValues: [unit-beside, e2e, none]
 # The editions a repository declares in hfs.json `edition` (absent means full). ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite IS
 # the full architecture with Supabase backing services - the same monorepo, slots, CQRS shape and patterns (queue,
 # event bus, saga, reactors, projection, realtime, webhooks, fenced job), declared in hfs.json the same way, and the same unit
-# specs (unitRoles, logicRoles, 100 per file, @starci/jest-preset doubles, builders). What differs is ADAPTERS and DELIVERY, all
-# on Supabase except realtime: schema authority in supabase/migrations, queue and event-bus ports on Supabase Queues (pgmq),
-# cache and locks on Postgres, schedules on pg_cron (+ pg_net), storage and auth on Supabase. Realtime uses the socket.io gateway
-# in the api process, one instance and no Redis adapter. Integration and provider sandbox contract specs are optional;
+# specs (unitRoles, logicRoles, 100 per file, @starci/jest-preset doubles, builders). What differs is ADAPTERS and DELIVERY
+# (ruling:R212/case-10): schema authority in supabase/migrations, the queue port on BullMQ over the Redis hfs.json
+# sides.be.backing declares (as in full, fed by the Postgres outbox), event-bus ports on pgmq-backed topics or in-process
+# delivery, cache and locks on Postgres or the declared Redis, schedules on pg_cron (+ pg_net) enqueueing through the queue
+# outbox, storage and auth on Supabase. Realtime uses SSE or the socket.io gateway
+# in the api process, which scales horizontally and stateless (memory hub for one replica or tests; the Redis hub and @socket.io/redis-adapter when Redis is declared, else the Postgres hub and @socket.io/postgres-adapter, for N replicas; websocket only, no sticky sessions). Integration and provider sandbox contract specs are optional;
 # declared patterns owe their integration proofs (R284). Lite has no e2e world. Production uses declared docker-swarm under
-# .starcistacks/production/infra/swarm/ (owner ruling 2026-10-14); no self-hosted database or broker. The front end is full's (R97).
+# .starcistacks/production/infra/swarm/ (owner ruling 2026-10-14); lite runs no self-hosted database, and runs only the backing
+# services sides.be.backing declares. The front end is full's (R97).
 # Lite is this same manifest filtered: a slot whose `editions` lacks lite does not exist for a lite app, `litePresence` replaces
-# presence and a `lite` map replaces the fields it names. Upgrade lite -> full adds only (swap the adapters, add the e2e and
-# self-hosted backing services); downgrade is not supported. Lite contracts are allowed (owner decision 2026-10-14).
+# presence and a `lite` map replaces the fields it names. The edition is chosen once at scaffold; there is no upgrade
+# or downgrade between lite and full. Lite contracts are allowed (owner decision 2026-10-14).
 editions: [full, lite]
 
 # The two sides of an app: the folder of each is its profile name (be/, fe/). `reads` lists the only paths of the OTHER side a side
@@ -189,6 +194,9 @@ ruleParams:
     # R259: btree_gist supplies UUID equality for the booking interval exclusion constraint.
     # R259: unaccent is a first-party Supabase extension used by Vietnamese-content search functions.
     extensions: [pgmq, pg_cron, pgcrypto, pg_trgm, vector, uuid-ossp, pg_net, supabase_vault, unaccent, btree_gist]
+    # R258 DB_CRON_OWNED: THE queue outbox of a Supabase schema (the relay hands its unsent rows to BullMQ, ruling:R212/case-10). A pg_cron
+    # job enqueues only by inserting one row into this table, writing only these columns, one of which is `queue`.
+    queueOutbox: {table: public.queue, columns: [queue, payload, created_at, correlation_id]}
   common:
     # HFS_SIZE_GROWTH: a file above soft may not grow against its parent commit; a new file stays within soft. Slot
     # budgets (component.tsx 300, hooks 200, modules 400) are stricter than this cap where they apply.
@@ -210,12 +218,19 @@ ruleParams:
       "node:https": [platform/http]
       http: [platform/http]
       https: [platform/http]
+      "@aws-sdk/client-s3": [integrations/object-storage]       # the ObjectStorage port: one S3 adapter for MinIO, S3, Spaces and Supabase Storage
+      "@aws-sdk/s3-request-presigner": [integrations/object-storage]
       cache-manager: [integrations/cache, integrations/redis]
       "@nestjs/cache-manager": [integrations/cache, integrations/redis]     # the CACHE_MANAGER token: caching goes through the cache capability
       redis: [integrations/cache, integrations/redis]
-      ioredis: [integrations/cache, integrations/redis]
+      ioredis: [integrations/cache, integrations/redis, platform/realtime]
+      "@keyv/redis": [integrations/cache, integrations/redis]
+      cache-manager-redis-yet: [integrations/cache, integrations/redis]
+      cache-manager-ioredis-yet: [integrations/cache, integrations/redis]   # the Redis hub and the sharded socket.io adapter of platform/realtime
       bullmq: [platform/queue]               # pattern queue: BullMQ jobs and job schedulers (the relay of the outbox into queues)
       "@nestjs/bullmq": [platform/queue]
+      bull: [platform/queue]
+      "@nestjs/bull": [platform/queue]
       kafkajs: [platform/event-bus]          # pattern event-bus: Kafka is the only event transport
       "@nestjs/schedule": []                 # no @Cron / @Interval / @Timeout anywhere: a schedule is a BullMQ job scheduler of a queue
       eventemitter2: []
@@ -224,6 +239,8 @@ ruleParams:
       "node:timers": [platform/retry, platform/event-bus, platform/queue, platform/http]
       "node:timers/promises": [platform/retry, platform/event-bus, platform/queue, platform/http]
       winston: [platform/logging]
+      "node:async_hooks": [platform/logging]
+      nestjs-cls: []
       dayjs: [platform/clock, platform/primitives]
       moment: [platform/clock, platform/primitives]
       date-fns-tz: [platform/clock, platform/primitives]
@@ -234,6 +251,9 @@ ruleParams:
       socket.io: [platform/realtime]
       graphql-subscriptions: [platform/realtime]
       graphql-ws: [platform/realtime]
+      "@socket.io/postgres-adapter": [platform/realtime]   # the stateless socket.io adapter of a scaled lite back end
+      "@socket.io/redis-adapter": [platform/realtime]      # the sharded socket.io adapter of a scaled full back end
+      pg: [platform/realtime]                              # the LISTEN connection of the Postgres hub; every other query goes through TypeORM
     # R87 BE_CQRS_SHAPE no-event-bus: the in-process event vocabulary the rule refuses. `imports` maps a module
     # specifier to the member names that are an in-process event; `[]` flags the package itself (its emitter packages
     # are the `[]` owners of infraOwners above). `classes` maps a module specifier to the class names that are an
@@ -249,8 +269,13 @@ ruleParams:
     # 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:
+    # Inbox-like names resolve their token declaration first: genuine platform/inbox aliases keep fakeInbox, while a business service
+    # or queue producer containing Inbox keeps its collaborator double. An unresolved origin retains the lexical table choice.
     # 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.
+    # An entry may add `from`, a regex over the path of the file that DECLARES its port's token: the declaration decides, not the import written
+    # in the spec. A token declared in another module that ends alike is a different port (`CORRELATION_IDS` of logging is not `IDS` of ids), and
+    # the owner's token stays that port however it is re-exported or renamed. A token that cannot be resolved is judged by its spelling.
     specDoubles:
       kit: "@starci/jest-preset"
       doubles:
@@ -263,7 +288,7 @@ ruleParams:
         - {token: "(?:^|_)INBOX(?:_|$)", double: fakeInbox, 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]}
+        - {token: "(?:^|_)(?:IDS|ID_GENERATOR|ID_FACTORY)$", from: "/src/modules/platform/ids/", double: fakeIds, forms: [call]}
       fallback: {double: mock, forms: [call, primitive, array]}
     # R85 BE_RAW_INJECT injected-param-name: the names of the ports every class injects the same way (BE-CONVENTION 1.6: the parameter name
     # is the camelCase of the port). An entry matches a constructor parameter that carries an injector and is annotated with a type
@@ -281,7 +306,7 @@ ruleParams:
     # 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, schema, command, query, handler, templates, compensation, saga-state, saga-step, saga, contracts, port, resolver, controller, gateway, webhook, subscription, consumer, cli, event, queue, projection, projection-entity, processor, step, 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]
+    suffixes: [module, module-definition, decorators, options, config, connection, service, schema, command, query, handler, templates, compensation, saga-state, saga-step, saga, contracts, port, resolver, controller, gateway, webhook, subscription, consumer, cli, event, queue, projection, projection-entity, processor, step, input, type, args, request, response, mapper, policy, entity, sql, rows, error, messages, log-events, cache-keys, guard, interceptor, filter, client, adapter, 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}
@@ -300,7 +325,10 @@ ruleParams:
     # options, config, command, query, contracts, port, event, queue, entity, sql, rows, messages, log-events, error, decorators, cache-keys,
     # projection-entity, connection, and every file with no role: index.ts, main.ts, migrations) is declaration or composition and is never measured.
     # A unit spec beside such a file (`<name>.<role>.spec.ts`) is legal but not required: the file owes 100, not a spec of its own.
-    logicRoles: [service, schema, policy, projection, guard, mapper, client, filter, interceptor, processor, step, saga, saga-step, compensation, consumer, webhook]
+    logicRoles: [service, schema, policy, projection, guard, mapper, client, adapter, filter, interceptor, processor, step, saga, saga-step, compensation, consumer, webhook]
+    # R281 BE_SPEC_FORM_ALL_ROLES. THE logic roles whose file declares values Nest never constructs (a zod schema): its spec parses the declared
+    # value directly and builds no testing module; every other logic role is built through `Test.createTestingModule`.
+    valueRoles: [schema]
     # R203 BE_FEATURE_THIN. THE roles a feature-tier file is judged thin by: a file `<name>.<role>.ts` of one of these roles inside a slot of tier
     # feature maps parameters and makes ONE delegating call into modules/ (a service, the command or query bus, the event bus, a queue producer): no
     # branch, loop, ternary, try or throw, no computation; orchestration (step order, compensation, claim, fencing, retry) lives in platform/*.
@@ -308,12 +336,14 @@ ruleParams:
     # BE_PATTERN_SPEC_MISSING: a declared pattern (hfs.json sides.be.patterns) is proven on the test world. Each id below needs a test titled
     # "<pattern>/<id>: ..." in an e2e or integration spec (be/src/tests/e2e, be/src/tests/integration).
     patternScenarios:
+      logging: [correlation-survives-queue]
       event-bus: [atomic-with-transaction, relay-only-after-commit, redelivery-then-dead-letter, duplicate-delivery-is-a-noop]
       queue: [enqueue-atomic-with-transaction, relay-job-id-is-outbox-id, scheduler-fires-once]
       webhooks: [bad-signature-is-refused, replay-is-refused, accepted-delivery-publishes-once]
-      realtime: [subscriber-receives-push, foreign-topic-is-isolated, disconnect-releases-subscription]
+      realtime: [subscriber-receives-push, foreign-topic-is-isolated, disconnect-releases-subscription, push-crosses-replicas, resume-after-reconnect]
       fenced-job: [claim-bumps-token, zombie-fenced-out, redispatch-isolated]
       projection: [recompute-is-idempotent, replay-rebuilds]
+      idempotency: [repeat-returns-same-outcome, reused-key-other-body-is-refused]
     # BE_KIND_DECLARATION: the patterns an app that uses a trigger kind declares in hfs.json sides.be.patterns; the platform capabilities of those
     # patterns (the slots of tier platform that name the pattern) must exist.
     kindPatterns:
@@ -338,23 +368,27 @@ ruleParams:
       api: {topic: api, variable: feature, trigger: api, patterns: [], needs: [service], defaults: {action: "@name"}}
       cli: {topic: cli, variable: group, trigger: cli, patterns: [], needs: [service], wire: {file: src/features/cli/cli.module.ts, import: "./@@group@@/@@group@@.module", symbol: "@@Group@@Module"}}
     bannedSuffixes: [use-case, repository, fixture, factory, store, worker, scheduler, cron, job, listener, dto, util, utils, helper, helpers, rules, types, constants, int-spec, harness-spec, test]
+    # ruling:R212/case-10 (R212 HFS_BACKING_UNDECLARED / HFS_BACKING_UNUSED, R276 STACKS_LITE_SELFHOSTED_DB): THE backing services a back
+    # end may declare in hfs.json sides.be.backing. `clients` are the libraries that consume the service: one of them as a dependency
+    # is its consumer, and under lite none of them may be a dependency while the service is undeclared. `patterns` are the declared
+    # patterns that need the service. `images` are the image repositories (the last path segment) a lite stack runs it from; an
+    # undeclared one is refused there.
+    backing:
+      redis: {clients: [bullmq, "@nestjs/bullmq", bull, "@nestjs/bull", ioredis, redis, "@keyv/redis", cache-manager-redis-yet, cache-manager-ioredis-yet, "@socket.io/redis-adapter"], patterns: [queue, fenced-job], images: [redis, redis-stack, redis-stack-server]}
+      qdrant: {clients: ["@qdrant/js-client-rest", "@qdrant/qdrant-js"], patterns: [], images: [qdrant]}
     # Edition lite (ruleParams(manifest, 'be', 'lite') merges these keys over the base; a map merges one level deep): the schema
     # authority is the Supabase migration tree (supabase/migrations/*.sql, forward-only), so a lite back end holds no TypeORM
     # migration or entity under be/ (R34/R35 read schemaAuthority; be.persistence's lite overlay allows neither). The unit roles,
-    # logic roles and spec doubles are full's (owner ruling 2026-10-12 (owner:lite-production-swarm), with the Work boundary amended by ruling:R212/case-4). infraOwners: the self-hosted libraries are owned nowhere -
-    # platform/queue and platform/event-bus run Supabase Queues (pgmq) through the shared EntityManager, cache and locks are
-    # Postgres (advisory locks or an unlogged table), and realtime is the same socket.io gateway as full, run inside the api
-    # process with no Redis adapter (owner ruling 2026-10-13).
+    # logic roles and spec doubles are full's (owner ruling 2026-10-12 (owner:lite-production-swarm), with the Work boundary amended by ruling:R212/case-4). infraOwners: full's owners,
+    # bullmq in platform/queue and ioredis/redis in integrations/cache and integrations/redis (ruling:R212/case-10: the queue is
+    # Redis in both editions; a backing library is legal only when hfs.json sides.be.backing declares its service, which
+    # HFS_BACKING_UNDECLARED checks), except Kafka, which is owned nowhere (platform/event-bus runs Supabase Queues (pgmq) through
+    # the shared EntityManager); realtime is the same socket.io gateway as full, run inside the api process, scaled horizontally and stateless (hub redis when
+    # Redis is declared, else hub postgres with @socket.io/postgres-adapter; no sticky sessions).
     lite:
       schemaAuthority: supabase
       infraOwners:
-        bullmq: []
-        "@nestjs/bullmq": []
         kafkajs: []
-        redis: []
-        ioredis: []
-        graphql-subscriptions: []
-        graphql-ws: []
 
 slots:
 
@@ -916,7 +950,7 @@ slots:
     tracked: external
     tier: none
     tests: none
-    goesTo: "a be feature: webhooks/<provider> for a third-party callback, api for an endpoint, a job of a pgmq-backed queue or a cli command on a schedule (pg_cron / pg_net)"
+    goesTo: "a be feature: webhooks/<provider> for a third-party callback, api for an endpoint, a job of a queue (BullMQ on the declared Redis, its tick enqueued through the queue outbox) or a cli command on a schedule (pg_cron / pg_net)"
     since: 2.1.0
 
   # ----- side root (both sides): what a standalone repository root holds, less the app-root files ----------
@@ -1436,7 +1470,7 @@ slots:
     since: 1.0.0
   - id: be.feature.realtime
     profiles: [be]
-    editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4) and ruling:R212/case-5 (owner decision 2026-10-24): lite serves server-sent events (the default door for one-way push) or runs socket.io in the api process, one instance without Redis; full may scale its gateway."
+    editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4) and ruling:R212/case-5 (owner decision 2026-10-24): both editions serve server-sent events (the default door for one-way push), the socket.io gateway (two-way) and the restricted GraphQL subscription (ruling:R212/case-7) from the api process (owner:lite-graphql-subscription-door), and scale on the hub of their declared infrastructure (BE-REALTIME-7)."
     path: "src/features/realtime/<channel>/"
     presence: opt-in              # a push channel: reads and pushes only (an SSE controller, a socket gateway or a GraphQL subscription), no domain write
     pattern: realtime             # declaring the pattern (hfs.json sides.be.patterns) enables the kind (knowledge/patterns/be/realtime.yaml)
@@ -1449,9 +1483,8 @@ slots:
     tests: none
     lite:
       why: >-
-        a push channel: the server-sent-events door (be.feature.realtime.sse, the default for one-way push, owner decision 2026-10-24)
-        or the same socket.io gateway as full (owner ruling 2026-10-13), both run inside the be api process, one instance and no
-        Redis adapter; the front end listens through a use<Channel>Stream hook over modules/api/sse, or hooks/socketio (knowledge/patterns/be/realtime.yaml, liteAdapter)
+        a push channel with the three doors of both editions: server-sent events (be.feature.realtime.sse, the default for one-way push, owner decision 2026-10-24), the socket.io gateway (two-way, owner ruling 2026-10-13) and the restricted GraphQL subscription (ruling:R212/case-7); all run inside the be api process, which scales horizontally and stateless
+        on the hub of its declared infrastructure; the front end listens through a useSubscribe<Channel>Swr hook over modules/api/sse, or hooks/socketio (knowledge/patterns/be/realtime.yaml, liteAdapter)
     coverage: none
     rules: [BE_KIND_ISOLATION, BE_FEATURE_IMPORTS_FEATURE, BE_FEATURE_NOT_COMPOSED]
     since: 1.0.0
@@ -1459,14 +1492,11 @@ slots:
       - {path: packages/hfs/src/hfs-stacks-swarm.spec.mjs, edition: lite}
   - id: be.feature.realtime.graphql
     profiles: [be]
-    editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite pushes through the SSE door or the in-process socket.io gateway; the GraphQL subscription door remains full-only."
     path: "src/features/realtime/<channel>/transport/graphql/"
-    presence: opt-in              # a GraphQL subscription over graphql-ws
-    litePresence: forbidden       # ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite pushes through the api's SSE door or its in-process socket.io gateway
+    presence: opt-in              # a GraphQL subscription over graphql-ws, served in both editions (ruling:R212/case-7) and restricted: only when the client already uses GraphQL and needs the typed schema payload (knowledge/patterns/be/realtime.yaml)
     pattern: realtime
     tracked: tracked
     tier: feature
-    goesTo: "src/features/realtime/<channel>/transport/sse/ (be.feature.realtime.sse, the default for one-way push) or transport/websocket/ (be.feature.realtime.websocket): lite runs either door in the api process"
     requires: ["<channel>-graphql.module.ts", "<channel>.subscription.ts", "<channel>.subscription.spec.ts"]
     allows: ["<channel>-graphql.module.ts", "<channel>-graphql.module-definition.ts", "<channel>-graphql.options.ts", "<channel>.subscription.ts", "<channel>.subscription.spec.ts", dto/]
     tests: unit-beside            # the door's own spec beside the door (a subscription has no service of its own)
@@ -1476,14 +1506,11 @@ slots:
     since: 1.0.0
   - id: be.feature.realtime.dto
     profiles: [be]
-    editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): GraphQL subscription DTOs exist only with the full subscription door; lite uses SSE or socket.io contracts."
     path: "src/features/realtime/<channel>/transport/graphql/dto/"
     presence: opt-in
-    litePresence: forbidden       # the dto of the graphql door, which lite does not serve
     pattern: realtime
     tracked: tracked
     tier: feature
-    goesTo: "src/features/realtime/<channel>/transport/sse/ (be.feature.realtime.sse, the default for one-way push) or transport/websocket/ (be.feature.realtime.websocket): lite runs either door in the api process"
     allows: ["<name>.{input,type,args}.ts"]
     tests: none
     coverage: none
@@ -1647,13 +1674,28 @@ slots:
     # resolved through the RequestLocale provider (request: stored user preference, else Accept-Language, else
     # vi; non-request: recipient's stored preference, else vi - see knowledge/patterns/be/messages.yaml);
     # database when a connection exists.
-    requiredInstances: {capability: [config, logging, errors, primitives, clock, i18n]}
+    requiredInstances: {capability: [config, errors, primitives, clock, i18n]}
     requires: [index.ts]
     forbids: [common/, utils/, shared/, testing/]   # primitives live in platform/primitives
     tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts, nothing else
     coverage: required
     budget: {indexExports: 60}
     rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE]
+  - id: be.platform.logging
+    since: 3.5.0
+    profiles: [be]
+    path: "src/modules/platform/logging/"
+    presence: required
+    pattern: logging
+    tracked: tracked
+    tier: platform
+    owner: true
+    requires: [index.ts]
+    forbids: [common/, utils/, shared/, testing/]
+    tests: unit-beside
+    coverage: required
+    budget: {indexExports: 60}
+    rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE]
   # ----- BE: pattern slots (opt-in; enabled by hfs.json sides.be.patterns). A path under one is HFS_SLOT_NOT_ENABLED unless its pattern is declared.
   - id: be.platform.event-bus
     since: 3.1.0
@@ -1670,7 +1712,7 @@ slots:
         the same EventPublisher and EventConsumer ports on Supabase Queues (pgmq): the outbox relay sends each committed row to the
         pgmq queue of every consumer group of its topic through the shared EntityManager, a consumer reads with a visibility
         timeout, retries by letting it lapse and archives the message on dead letter (read_ct over the budget); a single api may
-        deliver in process. No Kafka (knowledge/patterns/be/supabase-queues.yaml)
+        deliver in process. No Kafka (knowledge/patterns/be/event-bus.yaml liteAdapter)
     requires: [index.ts, event-bus.module.ts, event-bus.port.ts, event-bus.contracts.ts, event-bus.service.ts, event-bus.service.spec.ts]
     tests: unit-beside
     coverage: required
@@ -1681,7 +1723,7 @@ slots:
   - id: be.platform.queue
     since: 3.1.0
     profiles: [be]
-    editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite implements queue ports with pgmq and pg_cron; full uses BullMQ and Redis."
+    editionWhy: "ruling:R212/case-10: both editions implement the queue ports with BullMQ on Redis; lite declares its Redis in hfs.json sides.be.backing and keeps the outbox table in a supabase migration."
     path: "src/modules/platform/queue/"
     presence: opt-in
     pattern: queue                # the ONE BullMQ owner: the outbox relay into queues (jobId = outbox id) and job schedulers (knowledge/patterns/be/queues.yaml)
@@ -1690,10 +1732,10 @@ slots:
     owner: true
     lite:
       why: >-
-        the same QueueOutbox and QueueWorkerRegistry ports on Supabase Queues (pgmq): the relay sends each committed outbox row with
-        pgmq.send (the outbox id travels in the message, so a second send is a no-op at the processor's inbox), processors read
-        with a visibility timeout, back off by extending it, and pgmq.archive a message whose read_ct exceeds the budget (the dead
-        letter); a schedule is a pg_cron job that enqueues. No BullMQ or Redis (knowledge/patterns/be/supabase-queues.yaml)
+        the same QueueOutbox and QueueWorkerRegistry ports and full's BullMQ adapter on the declared Redis (backing: [redis]): the
+        relay adds each committed outbox row with the outbox id as the job id, workers retry with exponential backoff and keep a
+        job that exhausts its attempts as failed (the dead letter); the outbox table comes from a supabase migration, and a
+        schedule is a BullMQ job scheduler or a pg_cron tick that inserts one outbox row (knowledge/patterns/be/queues.yaml liteAdapter)
     requires: [index.ts, queue.module.ts, queue.port.ts, queue.contracts.ts, queue-outbox.service.ts, queue-outbox.service.spec.ts]
     tests: unit-beside
     coverage: required
@@ -1786,7 +1828,7 @@ slots:
   - id: be.platform.jobs
     since: 3.1.0
     profiles: [be]
-    editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite persists fenced claims in Supabase migrations and dispatches through pgmq; full uses TypeORM schema authority and its queue adapter."
+    editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite persists fenced claims in Supabase migrations and dispatches through the BullMQ queue on its declared Redis (ruling:R212/case-10); full uses TypeORM schema authority and the same queue adapter."
     path: "src/modules/platform/jobs/"
     presence: opt-in
     pattern: fenced-job           # the ONE fencing primitive: the job entity, the claim that bumps the token, guarded writes (knowledge/patterns/be/jobs.yaml)
@@ -2138,8 +2180,8 @@ slots:
     rules: [FE_HOOKS_ARE_HOOKS, FE_DATA_FRESHNESS]
   - id: fe.hooks.swr
     profiles: [fe]
-    # The data hooks (fe-stack data, FE-DATA-SWR): one useSWR / useSWRMutation wrapper per modules/api operation, keyed
-    # QUERY_<X>_SWR_KEY / MUTATE_<X>_SWR_KEY plus the identity of the request; SwrSideEffects.tsx runs the app-wide hooks once.
+    # The data hooks (fe-stack data, FE-DATA-SWR): one useSWR / useSWRMutation / useSWRSubscription wrapper per modules/api operation, keyed
+    # QUERY_<X>_SWR_KEY / MUTATE_<X>_SWR_KEY / SUBSCRIBE_<X>_SWR_KEY plus the identity of the request; SwrSideEffects.tsx runs the app-wide hooks once.
     path: "apps/<app>/src/hooks/swr/"
     presence: optional
     tracked: tracked
@@ -2148,7 +2190,9 @@ slots:
     requires: [index.ts]
     allows: [index.ts, SwrSideEffects.tsx, api/index.ts, "api/{graphql,rest}/index.ts", "api/{graphql,rest}/{queries,mutations}/index.ts",
              "api/graphql/queries/useQuery*Swr.ts", "api/graphql/mutations/useMutate*Swr.ts",
-             "api/rest/queries/useGet*Swr.ts", "api/rest/mutations/use{Post,Put,Patch,Delete}*Swr.ts"]
+             "api/rest/queries/useGet*Swr.ts", "api/rest/mutations/use{Post,Put,Patch,Delete}*Swr.ts",
+             "api/graphql/subscriptions/index.ts", "api/graphql/subscriptions/useSubscribe*Swr.ts",
+             "api/sse/index.ts", "api/sse/subscriptions/index.ts", "api/sse/subscriptions/useSubscribe*Swr.ts"]
     roles: {entry: index.ts, effects: SwrSideEffects.tsx}
     tests: none
     budget: {file: 200, barrel: 400}
@@ -2271,18 +2315,19 @@ slots:
     tier: transport
     # The browser's calls to the back end (owner ruling 2026-10-13, fe-stack graphql/rest/codegen, FE-API-GRAPHQL): the auth and
     # no-auth Apollo clients with their link chain (graphql/clients), one file per operation (graphql/queries/query-<x>.ts,
-    # graphql/mutations/mutation-<x>.ts with its gql document map and typed request/response in types/), the generated wire types
+    # graphql/mutations/mutation-<x>.ts and graphql/subscriptions/subscription-<x>.ts, each with its gql document map and typed request/response in types/), the generated wire types
     # (graphql/__generated__), the axios calls (rest/<area>/*.ts) for uploads, presigned URLs and auth endpoints and the fetch readers of
-    # server-sent-events streams (sse/<area>/*.ts, one file per stream, the bearer token from modules/auth). A repository has
+    # server-sent-events streams (sse/<area>/stream-<channel>.ts, one operation per stream, run on the stream reader of sse/clients). A repository has
     # exactly ONE client folder and ONE GraphQLResponse union: the app's (fe.transport.client/outcome) when one app calls the back end,
     # or the api package's (fe.package.api.client/outcome) when several do (FE_TRANSPORT_OWNER, machine).
     requires: [index.ts]
     allows: [index.ts, graphql/index.ts, graphql/types.ts, "graphql/clients/**", "graphql/queries/query-*.ts", "graphql/queries/types/*.ts",
-             "graphql/mutations/mutation-*.ts", "graphql/mutations/types/*.ts", "graphql/__generated__/**", "rest/index.ts", "rest/<area>/*.ts",
-             "sse/index.ts", "sse/<area>/*.ts"]
+             "graphql/mutations/mutation-*.ts", "graphql/mutations/types/*.ts", "graphql/subscriptions/subscription-*.ts", "graphql/subscriptions/types/*.ts",
+             "graphql/__generated__/**", "rest/index.ts", "rest/<area>/*.ts",
+             "sse/clients/**", "sse/*/stream-*.ts"]
     roles: {entry: index.ts, query: "query-*.ts", mutation: "mutation-*.ts"}
     # A hook imports its one operation file directly (one file per operation, FE-API-GRAPHQL), never through a barrel of every operation.
-    entries: ["graphql/queries/query-*.ts", "graphql/queries/types/*.ts", "graphql/mutations/mutation-*.ts", "graphql/mutations/types/*.ts", "sse/<area>/*.ts"]
+    entries: ["graphql/queries/query-*.ts", "graphql/queries/types/*.ts", "graphql/mutations/mutation-*.ts", "graphql/mutations/types/*.ts", "graphql/subscriptions/subscription-*.ts", "graphql/subscriptions/types/*.ts", "sse/*/stream-*.ts"]
     tests: none
     rules: [FE_TRANSPORT_OWNER, FE_HTTP_STATUS_COLLAPSE, FE_WIRE_GENERATED]
   - id: fe.transport.generated
@@ -2307,6 +2352,19 @@ slots:
     tests: none
     why: the auth and no-auth Apollo clients and their link chain (retry, error, timeout, token refresh, attach access token, http) of the one app that calls the back end; when several apps do, the shared client is fe.package.api.client
     rules: [FE_TRANSPORT_OWNER]
+  - id: fe.transport.stream
+    since: 3.7.0
+    profiles: [fe]
+    path: "apps/<app>/src/modules/api/sse/clients/"
+    presence: optional
+    tracked: tracked
+    tier: transport
+    allows: ["*.ts"]
+    tests: none
+    why: "the fetch reader of server-sent-events streams of the one app that calls the back end, the stream half of the transport client layer (FE-REALTIME): it opens the stream with the bearer access token, parses the events and reopens it with Last-Event-ID after a capped, doubling wait; a stream operation (sse/<area>/stream-<channel>.ts) runs on it and a useSubscribe hook of hooks/swr reads that operation; a fetch here asks for text/event-stream and only a stream operation imports the reader (FE_TRANSPORT_OWNER); a repository where several apps stream keeps one reader in each of them"
+    rules: [FE_TRANSPORT_OWNER]
+    exemplifiedBy:
+      - {path: packages/eslint/fe/r50-transport-owner-coverage.spec.mjs, editions: [lite, full]}
   - id: fe.transport.outcome
     since: 3.1.0
     profiles: [fe]

package/runtime/knowledge/sonar-gate.yaml

@@ -129,7 +129,7 @@ enforces:
   - {rule: R21, code: HFS_DUPLICATE_CODE, enforcer: duplicated-lines-density, condition: duplication}
   - {rule: R21, code: HFS_DUPLICATE_SYMBOL, enforcer: duplicated-lines-density, condition: duplication}
 # Ops that write product code: each runs sonar-local on its own change and cannot settle done while the gate is red.
-enforcedOps: [backend.implement, interface.implement, code.refactor]
+enforcedOps: [backend.implement, interface.implement, code.refactor, code.fix]
 reasoning: |
   Chosen against the four projects the local server holds on 2026-09-29 (whole-project duplicated lines
   1.6 / 2.1 / 1.7 / 0.0 percent), so new code that meets them is at or below what main already carries.

package/runtime/modules/kernel/removed-vocabulary.yaml

@@ -8,6 +8,27 @@
 # a word to scan for).
 kinds: [config-key, bias-field, verb, flag, code, vocabulary, file]
 removed:
+  - id: cut-seam-command
+    kind: flag
+    name: cut-seam --command
+    match: 'cut-seam[^\n]*--command\b'
+    use: 'cut-seam --reconcile reads the commands and selection from --checks-file'
+    since: 1.0.0-alpha.31
+  - id: cut-set-closing-check
+    kind: vocabulary
+    name: closingCheck
+    use: 'modules/kernel/check-policy.yaml#regression owns integration checks after job merges; closingOrdinal identifies only the final open ordinal'
+    since: 1.0.0-alpha.31
+  - id: verb-guard-input
+    kind: verb
+    name: starci guard input
+    use: 'the reference-transaction hook reads prepared ref updates directly in its shell loop'
+    since: 1.0.0-alpha.31
+  - id: hook-input-timeout-ms
+    kind: config-key
+    name: hook-input.timeoutMs
+    use: 'modules/kernel/hook-input.yaml declares the input window as minInputWindowMs'
+    since: 1.0.0-alpha.31
   - id: bias-require
     kind: bias-field
     name: require
@@ -339,3 +360,44 @@ removed:
     use: 'the runtime has no specs of its own (owner ruling no-runtime-specs); specs.unit and specs.e2e switch the product workflow tests'
     since: 1.0.0-alpha.19
     match: '\bspecs\.harness\b'
+  - id: file-supabase-queues-topic
+    kind: file
+    name: supabase-queues.yaml
+    use: 'the queue is BullMQ on Redis in both editions (ruling:R212/case-10): knowledge/patterns/be/queues.yaml owns the adapter, and each pattern topic''s liteAdapter says what lite uses with and without its declared backing service'
+    since: 1.0.0-alpha.31
+    match: '(?<![\w-])supabase-queues(?:\.yaml)?\b'
+  - id: code-rt-gate-loosening
+    kind: code
+    name: RT_GATE_LOOSENING
+    use: 'the tree is judged as it stands, never by its history: RT_LOOSENING_STATE (the loosening-state self-check) with the design-truths manifest knowledge/hfs/design-truths.yaml'
+    since: 1.0.0-alpha.31
+  - id: vocabulary-gate-loosening
+    kind: vocabulary
+    name: gate-loosening
+    use: 'the diff-based detector and its table are gone: the loosening-state self-check (scripts/checks/check-loosening-state.mjs) reads the tree as it stands against knowledge/hfs/design-truths.yaml'
+    since: 1.0.0-alpha.31
+    match: 'gate-loosening|gateLoosening|loosensReleased|looseningsOf|check-code-loosening'
+  - id: verb-runtime-benchmark-snapshot
+    kind: verb
+    name: starci runtime benchmark-snapshot
+    use: 'routing evidence is read live from the ledgers: `starci machine op-metrics --by op` and the ledger view v_model_scorecard (modules/models/registry.yaml costPolicy)'
+    since: 1.0.0-alpha.31
+    match: '(?<![\w-])benchmark-snapshot(?![\w-])'
+  - id: vocab-benchmark-scorecard
+    kind: vocabulary
+    name: the benchmark/ model-pool scorecard
+    use: 'routing evidence is read live from the ledgers: `starci machine op-metrics --by op` and the ledger view v_model_scorecard (modules/models/registry.yaml costPolicy)'
+    since: 1.0.0-alpha.31
+    match: '(?<![\w./-])benchmark/(?:README\.md|expectations\.yaml|snapshots\b|findings\b)|benchmark-expectations@1'
+  - id: slot-runtime-benchmark
+    kind: vocabulary
+    name: runtime.benchmark
+    use: 'the runtime tree has no benchmark slot; routing evidence is read live from the ledgers (modules/models/registry.yaml costPolicy)'
+    since: 1.0.0-alpha.31
+    match: '\bruntime\.benchmark\b'
+  - id: config-release-tagmatchesversion
+    kind: config-key
+    name: release.tagMatchesVersion
+    use: 'the release tag is always <release.tagPrefix><package.json version>; delete the key'
+    since: 1.0.0-alpha.31
+    match: '\btagMatchesVersion\b'

package/runtime/modules/models/registry.yaml

@@ -192,7 +192,9 @@ costPolicy: |-
   imagegen call tier (tiers.yaml calls, tierUse) and holds one provider slot while it runs. Every automatic launch contains only worker-start candidates and advances only
   after a verified no-effect failure. Agents have explicit turn, wall-time and tool-call ceilings; a ceiling stop is a
   failed attempt and never proof of completion. Never infer price or quality superiority from a subscription label;
-  benchmark bounded representative operations before proposing another tier change. A native worker is released
+  a tier change is proposed only on live ledger evidence: `starci machine op-metrics --by op` (success rate, retry
+  chains and repeated failures per op) and the ledger view `v_model_scorecard` (pass rate and tokens per op, agent
+  and model). A native worker is released
   after its exact worker_done result is accepted; the workflow child remains until integration is complete.
 assetFallback: When image generation is unavailable, reuse verified assets first; Claude may leave
   decorative image slots blank with a concrete deferred brief. Never mark missing artwork generated

package/runtime/modules/models/runtimes.yaml

@@ -442,6 +442,7 @@ allocation:
       interface.audit: {mb: 3000, class: heavy}
       brand.decide: {mb: 3000, class: heavy}
       code.refactor: {mb: 2000, class: heavy}
+      code.fix: {mb: 2000, class: heavy}
       test.author: {mb: 2500, class: heavy}
       task.execute: {mb: 2000, class: heavy}
       backend.scaffold: {mb: 2000, class: heavy}
@@ -513,6 +514,7 @@ roleOfKind:
   package.scaffold: {role: implement, work: hands-on, floor: easy}
   scope.define: {role: decide, work: think, floor: hard}
   code.refactor: {role: implement, work: hands-on, floor: easy}
+  code.fix: {role: implement, work: hands-on, floor: medium}
   test.author: {role: implement, work: hands-on, floor: easy}
   grammar.update: {role: implement, work: hands-on, floor: hard}
   architecture.revise: {role: decide, work: think, floor: hard}

package/runtime/scripts/api/git/ls-tree.mjs

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

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

@@ -0,0 +1,6 @@
+// show.mjs — `git show <args>`: an object of a repository - a file at a revision (`<rev>:<path>`), or a commit's
+// header and message (-s --format=...).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git show ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const show = (args = [], options = {}) => runGit(['show', ...args], options);

package/runtime/scripts/hfs/architecture/dead-exports.mjs

@@ -3,7 +3,7 @@
  *   HFS_UNUSED_EXPORT  an export of an owner's public entry that no production file outside the owner imports is dead.
  *   HFS_UNUSED_FILE    a production source file that no root reaches is dead. Roots: the files an app slot requires
  *                      (main.ts, app.module.ts), every route file (slot tier `route`), the public entry of every package,
- *                      and an api app operation table `operations.ts` (the contract emit reads it by path),
+ *                      the declared API app's registered operation contract consumed by app emit,
  *                      and a source file a framework config of the app names by a relative string literal
  *                      (next.config.ts pointing next-intl at its request config). Specs and tests are not in the graph,
  *                      so a file only a spec imports is dead, on purpose. Type-only imports reach a file.
@@ -42,14 +42,13 @@ import { treeOf } from './required-files.mjs';
 import { globExpression } from '../../lib/glob.mjs';
 import { stagedConsumerSources } from './staged-consumers.mjs';
 import { bindingsOf } from './dead-exports-bindings.mjs';
+import { operationContractRoots } from './operation-contract-roots.mjs';
 
 export const DEAD_EXPORT_RULE_IDS = ['HFS_UNUSED_EXPORT', 'HFS_UNUSED_FILE'];
 
 const PACKAGE_ENTRIES = ['src/index.ts', 'src/index.tsx', 'index.ts', 'index.tsx'];
 const OWNER_ENTRIES = ['index.ts', 'index.tsx'];
 const CHAIN_DEPTH = 6;
-/** The file of an api app that the contract emit reads by path for the typed operation table (BE-OPERATIONS-1): no import reaches it, the emit does. */
-const OPERATION_TABLE_FILE = "operations.ts";
 /** Tiers whose files are not production source that an app serves: judged by no dead-file rule. */
 const UNJUDGED_TIERS = new Set(['none', 'e2e', 'fixtures']);
 const CONFIG_EXTENSIONS = ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '/index.ts', '/index.tsx', '/index.js'];
@@ -139,15 +138,15 @@ const addFrameworkConfigRoots = (graph, config, roots) => {
   for (const app of config.apps ?? []) addAppConfigRoots(graph, config, app, roots);
 };
 
-/** The files the graph serves from: what an app slot requires, every route file, every package entry, every config-named file. */
-function rootFiles(graph, config) {
+/** Roots are required app files, registered operation contracts, routes, package entries and config-named files. */
+function rootFiles(graph, config, context) {
   const roots = new Set();
   for (const [rel, node] of graph.files) {
     if (node.tier === 'route') { roots.add(rel); continue; }
     if (!node.owner || node.tier !== 'app') continue;
     const slot = graph.resolver.slot(node.owner.slot);
     const inside = rel.slice(withoutSlash(node.owner.root).length + 1);
-    if ((slot?.requires ?? []).includes(inside) || inside === OPERATION_TABLE_FILE) roots.add(rel);
+    if ((slot?.requires ?? []).includes(inside)) roots.add(rel);
   }
   for (const [key, owner] of graph.ownerRoots) {
     if (owner.tier !== 'package') continue;
@@ -156,6 +155,7 @@ function rootFiles(graph, config) {
   }
   // A framework config of an app (slot fe.app.next) names sources by string, never by import.
   addFrameworkConfigRoots(graph, config, roots);
+  for (const entry of operationContractRoots(context, graph, config)) roots.add(entry);
   return roots;
 }
 
@@ -163,12 +163,12 @@ const unusedFileViolation = (rel, node) => ({
   ruleId: 'HFS_UNUSED_FILE',
   path: rel, line: 1, column: 1,
   slot: node.slot, owner: node.owner?.root ?? null,
-  message: `${rel} is not reached from any root (an app main.ts or app.module.ts, a route file, a package entry): nothing imports it, so no process runs it. Delete the file, or import it where it is used (a spec alone does not count).`,
+  message: `${rel} is not reached from any root (an app main.ts or app.module.ts, a registered operation contract, a route file, a package entry): nothing consumes it. Delete the file, or import it where it is used (a spec alone does not count).`,
 });
 
 /** HFS_UNUSED_FILE: production files no root reaches through runtime or type-only imports and re-exports. */
-function deadFiles(graph, config) {
-  const roots = rootFiles(graph, config);
+function deadFiles(graph, config, context) {
+  const roots = rootFiles(graph, config, context);
   const forward = Map.groupBy(graph.edges, edge => edge.from);
   const reached = new Set(roots);
   const queue = [...roots];
@@ -355,7 +355,7 @@ export function checkDeadExports({ context, graph, config }) {
   const edgesTo = edgeIndex([...graph.edges, ...testConsumerEdges({ context, graph, config })]);
   const analysis = { ...context, graph, edgesTo, namespaceCheckers: new WeakMap(), namespaceUses: new WeakMap() };
   const exports = ownerExportFindings(analysis, config);
-  const files = deadFiles(graph, config);
+  const files = deadFiles(graph, config, context);
   const dead = exports.violations.length;
   exports.violations.push(...files.violations);
   return { violations: exports.violations, coverage: { status: 'checked', owners: exports.owners, exports: exports.exports, dead, files: files.judged, roots: files.roots, unusedFiles: files.violations.length } };