@starci/hfs 4.7.30 → 4.7.31

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.7.31 - 2026-10-24
+- Fixed: `HFS_UNUSED_FILE` treats an api app `operations.ts` as a root (the contract emit reads it by path) and the emitted `openapi.json` is a declared JSON format.
+- Fixed: the doc check `HFS_DOC_ENV_UNKNOWN` (R270) no longer reads a documented error code as an environment key: codes the app declares in `errors/`, `*.error.ts` and `*.messages.ts` (`errors.<CODE>` keys) and names in a sentence about error codes pass, while an undeclared environment key still fails.
+- Added: the SSE door templates of the realtime pattern (`channel.sse` module, options and definition); lite may serve SSE beside its socket.io gateway (amended R212).
+- Changed: a new app's starter dependencies (full and lite) carry `zod` at its canon pin, which is `side: both` (the boundary-schema pattern, R304 and R305).
+
 ## 4.7.30 - 2026-10-24
 - Changed: a new app root overrides multer to its canon pin 2.5.0: @nestjs/platform-express depends on exactly multer 2.4.0, which carries GHSA-q7qp-rjg7-q26m (high); the bundled canon pins add `multer` and select @starci/cli 1.7.30, @starci/eslint-canon-be 3.4.38 and @starci/eslint-canon-fe 8.4.37.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.30",
+  "version": "4.7.31",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.38
+    version: 3.4.39
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.37
+    version: 8.4.38
     group: starci
     install: registry
     side: fe
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.30
+    version: 1.7.31
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.30
+    version: 4.7.31
     group: starci
     install: registry
     side: both
@@ -338,8 +338,8 @@ pins:
   'zod':
     version: 4.6.7
     group: framework
-    side: fe
-    why: 'the schema library of front-end forms and boundary parsing (fe-stack forms), also an npm override of every app root; 4.6.7 (the registry latest on 2026-10-24) closes GHSA-mrhx-c7xc-m3w5 (high, fixed in 4.6.6), which npm audit --audit-level=high reported against 4.4.3.'
+    side: both
+    why: 'the schema library of front-end forms (fe-stack forms) and, on the back end, of the boundary parsers (R304 and R305: provider responses, model output and queue payloads, never a transport DTO), also an npm override of every app root; 4.6.7 (the registry latest on 2026-10-24) closes GHSA-mrhx-c7xc-m3w5 (high, fixed in 4.6.6), which npm audit --audit-level=high reported against 4.4.3.'
   '@reduxjs/toolkit':
     version: 2.11.2
     group: framework

package/runtime/knowledge/hfs/fe-stack.yaml

@@ -75,7 +75,7 @@ concerns:
     home: [fe.hooks.socketio]
     pattern: FE-REALTIME
     forbids: [graphql-ws, subscriptions-transport-ws, '@supabase/realtime-js', pusher-js, ably]
-    why: one socket.io-client singleton per namespace and one side-effect component that dispatches to redux and SWR; lite runs the gateway in the be api process.
+    why: one socket.io-client singleton per namespace and one side-effect component that dispatches to redux and SWR; lite runs the gateway in the be api process. A one-way channel served as server-sent events needs no package, only a fetch reader in modules/api/sse and a use<Channel>Stream hook (FE-REALTIME).
   - id: auth
     tier: core
     packages: []

package/runtime/knowledge/hfs/rules.yaml

@@ -1918,7 +1918,7 @@ rules:
       - {path: packages/hfs/src/r94-r96-r97-coverage.spec.mjs, editions: [lite, full], codes: [FE_SLOT_FILE_ROLE]}
   - id: R95
     code: "BE_OPERATION_CONTRACT"
-    law: "A versioned operation is declared once in the app's typed operation table (`OperationContract<Input, Output, RefusalCode>` registered by `defineOperations`): its input and output are closed types (never `any`, `unknown` or `Record<string, unknown>`), its refusal codes a closed union of string literals, and the route that serves the table takes `OperationRequest<Table>` and answers `Promise<OperationReply<Table>>` of that one table."
+    law: "A versioned operation is declared once in the app's typed operation table (`OperationContract<Input, Output, RefusalCode>` registered by `defineOperations`): its input and output are closed types (never `any`, `unknown` or `Record<string, unknown>`), its refusal codes a closed union of string literals, and the route that serves the table takes `OperationRequest<Table>` and answers `Promise<OperationReply<Table>>` of that one table, binding its body to the `OperationValidationService` of `platform/http-security` because the alias leaves no class for the global pipe to validate."
     kinds: [lint]
     failureCodes: ["BE_OPERATION_CONTRACT"]
     enforcers:
@@ -3193,11 +3193,12 @@ rules:
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, editions: [lite, full], codes: [BE_REALTIME_SHAPE]}
     exemplifiedBy:
       - {path: packages/hfs/templates/be/patterns/realtime/channel.gateway.ts.tpl, editions: [lite, full]}
+      - {path: packages/hfs/templates/be/patterns/realtime/channel.controller.ts.tpl, editions: [lite, full]}
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, editions: [lite, full], codes: [BE_REALTIME_SHAPE]}
     witness:
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, edition: lite, codes: [BE_REALTIME_SHAPE]}
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, edition: full, codes: [BE_REALTIME_SHAPE]}
-    law: "A realtime file is the one door its role names: `<channel>.gateway.ts` holds one `@WebSocketGateway` class with `@SubscribeMessage` handlers and `<x>.subscription.ts` holds one `@Resolver` class with `@Subscription` operations, and neither carries a query, a mutation, a field resolver, a REST route or the other protocol. A lite app serves the same socket.io gateway from its api process and no graphql-ws subscription (R212 case-2 (owner:lite-production-swarm), with the Work boundary amended by ruling:R212/case-4)."
+    law: "A realtime file is the one door its role names: `<channel>.gateway.ts` holds one `@WebSocketGateway` class with `@SubscribeMessage` handlers, `<x>.subscription.ts` holds one `@Resolver` class with `@Subscription` operations and `<channel>.controller.ts` of the sse slot holds one `@Controller` class whose one route is `@Sse`, and none carries a query, a mutation, a field resolver, a plain REST route or another protocol. A lite app serves SSE (the default door for one-way push) or the socket.io gateway from its api process and no graphql-ws subscription (R212 case-2 (owner:lite-production-swarm), with the Work boundary amended by ruling:R212/case-4 and the realtime adapter amended by ruling:R212/case-5)."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["BE_REALTIME_SHAPE"]
@@ -3211,11 +3212,12 @@ rules:
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, editions: [lite, full], codes: [BE_REALTIME_WRITES]}
     exemplifiedBy:
       - {path: packages/hfs/templates/be/patterns/realtime/channel.gateway.ts.tpl, editions: [lite, full]}
+      - {path: packages/hfs/templates/be/patterns/realtime/channel.controller.ts.tpl, editions: [lite, full]}
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, editions: [lite, full], codes: [BE_REALTIME_WRITES]}
     witness:
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, edition: lite, codes: [BE_REALTIME_WRITES]}
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, edition: full, codes: [BE_REALTIME_WRITES]}
-    law: "A realtime door reads and pushes only: the one value injected into it is the `RealtimeHub` of `platform/realtime`; no `EntityManager`, bus, queue, event bus or domain service reaches it."
+    law: "A realtime door (gateway, subscription or SSE controller) reads and pushes only: the one value injected into it is the `RealtimeHub` of `platform/realtime`; no `EntityManager`, bus, queue, event bus or domain service reaches it."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["BE_REALTIME_WRITES"]
@@ -3229,11 +3231,12 @@ rules:
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, editions: [lite, full], codes: [BE_REALTIME_TOPIC_SCOPE]}
     exemplifiedBy:
       - {path: packages/hfs/templates/be/patterns/realtime/channel.gateway.ts.tpl, editions: [lite, full]}
+      - {path: packages/hfs/templates/be/patterns/realtime/channel.controller.ts.tpl, editions: [lite, full]}
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, editions: [lite, full], codes: [BE_REALTIME_TOPIC_SCOPE]}
     witness:
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, edition: lite, codes: [BE_REALTIME_TOPIC_SCOPE]}
       - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, edition: full, codes: [BE_REALTIME_TOPIC_SCOPE]}
-    law: "The topic a realtime handler passes to `RealtimeHub.subscribe` is built from the handler's `@CurrentPrincipal()` parameter of `domain/identity`, so a client can only listen to channels its principal owns."
+    law: "The topic a realtime handler (including the `@Sse` method of an SSE controller) passes to `RealtimeHub.subscribe` is built from the handler's `@CurrentPrincipal()` parameter of `domain/identity`, so a client can only listen to channels its principal owns; a `Last-Event-ID` header only chooses where the replay inside that topic resumes."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["BE_REALTIME_TOPIC_SCOPE"]
@@ -3568,7 +3571,7 @@ rules:
     docs: [docs/lite-edition.md#edition-validation]
     templateNa: "The hfs.json edition declaration is generated programmatically by packages/hfs/scaffold/app.mjs; no managed declaration template exists. Forbidden paths are rejected rather than scaffolded."
     code: "HFS_EDITION_INVALID"
-    law: "hfs.json names an edition the manifest knows (full, or lite; absent means full). Lite follows the 2026-10-13 ruling: the same monorepo, code structure, slots, patterns and back-end unit specs, with only backing infrastructure swapped for managed Supabase (Postgres, Auth, Storage, Supabase Queues/pgmq for queue and event bus, Postgres locks, pg_cron); the api and sidecars run on docker-swarm on a VPS. The realtime pattern uses the same socket.io gateway inside the be api process (one instance, no Redis adapter), and both editions share knowledge/hfs/fe-stack.yaml. Lite requires application-stacks.yaml and permits environment metadata, runbooks, infra/swarm and encrypted-secret custody, while refusing infra/compose, infra/k8s, infra/terraform and components duplicating Supabase backing services (runtime/{config,env}, seeds and the sealed secrets of its environments are allowed). Contract specs and `test:contract` are allowed (owner 2026-10-14); it has no e2e spec, `test:e2e`, `test:stack` or `test:browser` script, e2e workflow, browser journey, Work catalog, shell, features, resources, UAT or br records, test container, toxiproxy, browser-runner, BullMQ, Kafka, Redis or graphql-ws dependency, or supabase/functions. Its .starciwork is optional and admits only .gitignore, workspace.yaml and brand/**; workspace.yaml is optional and carries project identity and repo roles for the Work tools."
+    law: "hfs.json names an edition the manifest knows (full, or lite; absent means full). Lite follows the 2026-10-13 ruling: the same monorepo, code structure, slots, patterns and back-end unit specs, with only backing infrastructure swapped for managed Supabase (Postgres, Auth, Storage, Supabase Queues/pgmq for queue and event bus, Postgres locks, pg_cron); the api and sidecars run on docker-swarm on a VPS. The realtime pattern serves SSE (the default for one-way push) or the same socket.io gateway inside the be api process (one instance, no Redis adapter; R212 case-5), and both editions share knowledge/hfs/fe-stack.yaml. Lite requires application-stacks.yaml and permits environment metadata, runbooks, infra/swarm and encrypted-secret custody, while refusing infra/compose, infra/k8s, infra/terraform and components duplicating Supabase backing services (runtime/{config,env}, seeds and the sealed secrets of its environments are allowed). Contract specs and `test:contract` are allowed (owner 2026-10-14); it has no e2e spec, `test:e2e`, `test:stack` or `test:browser` script, e2e workflow, browser journey, Work catalog, shell, features, resources, UAT or br records, test container, toxiproxy, browser-runner, BullMQ, Kafka, Redis or graphql-ws dependency, or supabase/functions. Its .starciwork is optional and admits only .gitignore, workspace.yaml and brand/**; workspace.yaml is optional and carries project identity and repo roles for the Work tools."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["HFS_EDITION_INVALID", "HFS_EDITION_FORBIDDEN_PRESENT", "HFS_STARCIWORK_LITE_FORBIDDEN"]
@@ -3598,6 +3601,11 @@ rules:
         source: owner
         quote: "In a lite app, .starciwork keeps only the brand records."
         ruling: "Amended by the owner on 2026-10-14: under lite, .starciwork is optional when the app has no brand records and admits only .gitignore, workspace.yaml and brand/** in the existing brand tooling layout, including drawing records, references and assets. workspace.yaml is optional and keeps the project id and repo roles so Work root detection and render-proof role mapping can tie brand records to the front end. index.yaml, shell/, features/, _resources/, uat and br remain forbidden. Lite readers read workspace.yaml normally and skip the full-edition catalog, shell and feature metadata; lite scaffolding creates .gitignore and workspace.yaml, with brand/ only when present. Full edition is unchanged."
+      - id: case-5
+        date: "2026-10-24"
+        source: owner
+        quote: "Lite may serve SSE, and SSE is the default for one-way push. (alpha.30 BE patterns research, owner decisions 2026-10-24, relayed by the alpha.30 lead)"
+        ruling: "Server-sent events are the third door of the realtime pattern (be.feature.realtime.sse), legal in lite and in full, and the default door for one-way server-to-client push; this amends the lite realtime adapter clause of case-2, which named the socket.io gateway as lite's only push. The socket.io gateway stays for a bidirectional channel, graphql-ws and the GraphQL subscription door stay full-only, and the hub is single-replica (the lite api pins replicas: 1, STACKS_REALTIME_SCALED)."
     proves: [packages/hfs/src/hfs-edition-invalid.spec.mjs, packages/hfs/src/hfs-edition-forbidden-present.spec.mjs, packages/hfs/src/hfs-starciwork-lite-forbidden.spec.mjs]
     exemplifiedBy:
       - {path: packages/hfs/src/hfs-edition-invalid.spec.mjs, editions: [lite, full]}
@@ -4750,8 +4758,8 @@ rules:
       - {path: packages/hfs/src/hfs-secret-custody.spec.mjs, editions: [full], codes: [HFS_SECRET_OUTSIDE_ENC]}
   - id: R278
     code: "BE_REST_DOOR_EVIDENCE"
-    amendedBy: [owner:credential-guarded-rest-door]
-    law: "GraphQL is the default door in lite and full. Each REST route carries its own evidence: a probe, auth handshake, signed webhook, actual byte stream, a public versioned operation served from the app's nonempty defineOperations table, or a credential-guarded route (owner:credential-guarded-rest-door): the route or its controller carries @Credential({ kind: \"<literal>\" }) imported from the domain identity capability, which also declares the CredentialGuard class implementing CanActivate (resolved by TypeScript symbol, never by name); a local decorator of the same name, a @UseGuards of any other guard and a computed kind prove nothing. A class-level reference or an unused StreamableFile import proves no route, and a public REST route absent from the operation table is refused."
+    amendedBy: [owner:credential-guarded-rest-door, owner:lite-sse-door]
+    law: "GraphQL is the default door in lite and full. Each REST route carries its own evidence: a probe, auth handshake, signed webhook, actual byte stream, an event stream (a text/event-stream route: an `@Sse` method of `@nestjs/common` inside the be.feature.realtime.sse slot, owner:lite-sse-door; an `@Sse` anywhere else proves nothing), a public versioned operation served from the app's nonempty defineOperations table, or a credential-guarded route (owner:credential-guarded-rest-door): the route or its controller carries @Credential({ kind: \"<literal>\" }) imported from the domain identity capability, which also declares the CredentialGuard class implementing CanActivate (resolved by TypeScript symbol, never by name); a local decorator of the same name, a @UseGuards of any other guard and a computed kind prove nothing. A class-level reference or an unused StreamableFile import proves no route, and a public REST route absent from the operation table is refused."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["BE_REST_DOOR_EVIDENCE", "BE_REST_ROUTE_UNDECLARED"]
@@ -5279,3 +5287,43 @@ rules:
       - {path: packages/hfs/src/bypass-detector.spec.mjs, editions: [lite, full], codes: [HFS_BYPASS_MARKER]}
     witness:
       - {path: packages/hfs/src/bypass-detector.spec.mjs, editions: [lite, full], codes: [HFS_BYPASS_MARKER]}
+  - id: R304
+    code: "BE_SCHEMA_PLACE"
+    law: "The back end validates by zone. A transport door (GraphQL `@InputType`, REST request class) is validated by `class-validator` (R42); untrusted data that never reaches a DTO (a provider's HTTP response, structured model output, a queue or outbox payload read back, a tool argument) is read through a `zod` schema. `zod` is imported only from a `<name>.schema.ts` file (or its spec) of a `modules/domain`, `modules/platform` or `modules/integrations` owner, never in a feature, a transport door or a `dto/` folder, and a schema file imports neither `class-validator`, `class-transformer` nor `@nestjs/graphql`. The reader that calls the schema maps a failed parse to its owner's error family. No schema is shared between the front end and the back end: the shared contract is the emitted `schema.graphql` and `openapi.json`."
+    kinds: [lint, design]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["BE_SCHEMA_PLACE"]
+    enforcers:
+      - {kind: eslint-be, id: schema-place}
+    editions: [lite, full]
+    docs: [docs/quality-bar.md#r304]
+    proves:
+      - {path: packages/eslint/be/boundary-schema.spec.mjs, editions: [lite, full], codes: [BE_SCHEMA_PLACE]}
+    exemplifiedBy:
+      - {path: examples/full-app/be/src/modules/integrations/sepay/sepay-transactions.schema.ts, edition: full}
+      - {path: examples/lite-app/be/src/modules/domain/calendar-inbox/calendar-delivery.schema.ts, edition: lite}
+      - {path: packages/eslint/be/boundary-schema.spec.mjs, editions: [lite, full], codes: [BE_SCHEMA_PLACE]}
+    witness:
+      - {path: packages/eslint/be/boundary-schema.spec.mjs, edition: lite, codes: [BE_SCHEMA_PLACE]}
+      - {path: packages/eslint/be/boundary-schema.spec.mjs, edition: full, codes: [BE_SCHEMA_PLACE]}
+    templateNa: "A schema is declared per boundary by its owner; the canon scaffolds none, and the two example schemas are the reference."
+  - id: R305
+    code: "BE_SCHEMA_BOUNDED"
+    law: "Every `zod` schema is bounded: each `z.string()` (and the string formats `z.email()`, `z.url()` and kin) has `.max(n)` or `.length(n)`, each `z.array(...)` and `z.set(...)` has `.max(n)`, `.length(n)` or `.size(n)`, each `z.record(...)` and `z.map(...)` bounds its entry count by a `.refine`/`.check`, and `z.any()`, `z.unknown()` and `z.json()` are refused. A bound is a finite positive number: `Infinity`, `0` and `Number.MAX_*` are no bound. An unbounded collection whose elements all fail validation allocates an issue per element (GHSA-mrhx-c7xc-m3w5), and an unbounded string is an unbounded cost on any zod version."
+    kinds: [lint, design]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["BE_SCHEMA_BOUNDED"]
+    enforcers:
+      - {kind: eslint-be, id: schema-bounded}
+    editions: [lite, full]
+    docs: [docs/quality-bar.md#r305]
+    proves:
+      - {path: packages/eslint/be/boundary-schema.spec.mjs, editions: [lite, full], codes: [BE_SCHEMA_BOUNDED]}
+    exemplifiedBy:
+      - {path: examples/full-app/be/src/modules/integrations/sepay/sepay-transactions.schema.ts, edition: full}
+      - {path: examples/lite-app/be/src/modules/domain/calendar-inbox/calendar-delivery.schema.ts, edition: lite}
+      - {path: packages/eslint/be/boundary-schema.spec.mjs, editions: [lite, full], codes: [BE_SCHEMA_BOUNDED]}
+    witness:
+      - {path: packages/eslint/be/boundary-schema.spec.mjs, edition: lite, codes: [BE_SCHEMA_BOUNDED]}
+      - {path: packages/eslint/be/boundary-schema.spec.mjs, edition: full, codes: [BE_SCHEMA_BOUNDED]}
+    templateNa: "A schema is declared per boundary by its owner; the canon scaffolds none, and the two example schemas are the reference."

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.5.0
+version: 3.6.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -41,6 +41,8 @@ versioning:
 # 3.4.0 is a minor (alpha.25): it ADDS the opt-in be.contract.mcp-tools slot, the committed MCP tool-catalog snapshot of an app.
 # 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/).
 
 # Field meaning, per slot.
 #   id          stable name, never changes meaning inside a major.
@@ -217,7 +219,7 @@ ruleParams:
       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: []
-      setInterval: [platform/retry, platform/event-bus, platform/queue, platform/http]
+      setInterval: [platform/retry, platform/event-bus, platform/queue, platform/http, platform/realtime]
       setTimeout: [platform/retry, platform/event-bus, platform/queue, platform/http]
       "node:timers": [platform/retry, platform/event-bus, platform/queue, platform/http]
       "node:timers/promises": [platform/retry, platform/event-bus, platform/queue, platform/http]
@@ -279,7 +281,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, 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, 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}
@@ -298,7 +300,7 @@ 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, policy, projection, guard, mapper, client, filter, interceptor, processor, step, saga, saga-step, compensation, consumer, webhook]
+    logicRoles: [service, schema, policy, projection, guard, mapper, client, filter, interceptor, processor, step, saga, saga-step, compensation, consumer, webhook]
     # 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/*.
@@ -1434,9 +1436,9 @@ 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): lite 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): 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."
     path: "src/features/realtime/<channel>/"
-    presence: opt-in              # a push channel: reads and pushes only (a socket gateway or a GraphQL subscription), no domain write
+    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)
     trigger: realtime
     tracked: tracked
@@ -1447,9 +1449,9 @@ slots:
     tests: none
     lite:
       why: >-
-        a push channel on the same socket.io gateway as full (owner ruling 2026-10-13): lite runs the gateway inside the be api
-        process, one instance and no Redis adapter; the front end listens through hooks/socketio
-        (knowledge/patterns/be/realtime.yaml, liteAdapter)
+        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)
     coverage: none
     rules: [BE_KIND_ISOLATION, BE_FEATURE_IMPORTS_FEATURE, BE_FEATURE_NOT_COMPOSED]
     since: 1.0.0
@@ -1457,14 +1459,14 @@ 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 uses only the in-process socket.io gateway; the GraphQL subscription door remains full-only."
+    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 in-process socket.io gateway
+    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
     pattern: realtime
     tracked: tracked
     tier: feature
-    goesTo: "src/features/realtime/<channel>/transport/websocket/ (be.feature.realtime.websocket): both editions push through the socket.io gateway; lite runs it in the api process"
+    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)
@@ -1474,14 +1476,14 @@ 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 socket.io contracts."
+    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/websocket/ (be.feature.realtime.websocket): both editions push through the socket.io gateway; lite runs it in the api process"
+    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
@@ -1502,6 +1504,22 @@ slots:
     composedBy: [api]
     rules: [BE_REALTIME_SHAPE, BE_REALTIME_WRITES, BE_REALTIME_TOPIC_SCOPE, BE_DEFAULT_DENY]
     since: 1.0.0
+  - id: be.feature.realtime.sse
+    since: 3.6.0
+    profiles: [be]
+    path: "src/features/realtime/<channel>/transport/sse/"
+    presence: opt-in              # a server-sent-events door: one @Sse method, the default door for one-way push (owner decision 2026-10-24), served in both editions
+    pattern: realtime
+    tracked: tracked
+    tier: feature
+    requires: ["<channel>-sse.module.ts", "<channel>.controller.ts", "<channel>.controller.spec.ts"]
+    allows: ["<channel>-sse.module.ts", "<channel>-sse.module-definition.ts", "<channel>-sse.options.ts", "<channel>.controller.ts", "<channel>.controller.spec.ts"]
+    tests: unit-beside            # the door's own spec beside the door (an SSE controller has no service of its own)
+    coverage: none
+    composedBy: [api]
+    rules: [BE_REALTIME_SHAPE, BE_REALTIME_WRITES, BE_REALTIME_TOPIC_SCOPE, BE_DEFAULT_DENY, BE_REST_DOOR_EVIDENCE]
+    exemplifiedBy:
+      - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, editions: [lite, full]}
   - id: be.cli
     since: 3.1.0
     profiles: [be]
@@ -1552,7 +1570,7 @@ slots:
     requires: [index.ts]
     # <name>.templates.ts holds the capability's static templates, copy and presets as TS constants (owner ruling 2026-10-13);
     # user-editable ones are seed rows, large or user media live in object storage.
-    allows: ["<capability>.module.ts", "<capability>.module-definition.ts", "<capability>.config.ts", "<capability>.options.ts", errors/, messages/, persistence/, policies/, "*.service.ts", "*.service.spec.ts", "*.contracts.ts", "*.templates.ts"]
+    allows: ["<capability>.module.ts", "<capability>.module-definition.ts", "<capability>.config.ts", "<capability>.options.ts", errors/, messages/, persistence/, policies/, "*.service.ts", "*.service.spec.ts", "*.contracts.ts", "*.templates.ts", "*.schema.ts", "*.schema.spec.ts"]
     forbids: [testing/, exceptions/, utils/, helpers/, shared/]
     tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts, nothing else
     coverage: required
@@ -2254,15 +2272,17 @@ slots:
     # 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/__generated__) and the axios calls (rest/<area>/*.ts) for uploads, presigned URLs and auth endpoints. A repository has
+    # (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
     # 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"]
+             "graphql/mutations/mutation-*.ts", "graphql/mutations/types/*.ts", "graphql/__generated__/**", "rest/index.ts", "rest/<area>/*.ts",
+             "sse/index.ts", "sse/<area>/*.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"]
+    entries: ["graphql/queries/query-*.ts", "graphql/queries/types/*.ts", "graphql/mutations/mutation-*.ts", "graphql/mutations/types/*.ts", "sse/<area>/*.ts"]
     tests: none
     rules: [FE_TRANSPORT_OWNER, FE_HTTP_STATUS_COLLAPSE, FE_WIRE_GENERATED]
   - id: fe.transport.generated

package/runtime/knowledge/patterns/be/api.yaml

@@ -321,7 +321,9 @@ rules:
     hfsRules: [R95, R88, R23, R278]
     requirement: |-
       A versioned operation `<name>@<version>` (for example `sales.policy@1`) that an app serves over one operation route is
-      declared once, in the app's operation table `be/apps/<app>/src/operations.ts`, which exports `OPERATIONS`. The table is made by
+      declared once, in the app's operation table, which `be/apps/<app>/src/operations.ts` exports as `OPERATIONS`. A feature cannot
+      import an app and a feature's contracts hold no call, so the table is made in a `<name>-operations.contracts.ts` of the
+      domain capability that owns the operations, and the app file re-exports it from the capability's public surface. The table is made by
       `defineOperations` of the platform capability `operations` (`be/src/modules/platform/operations/`, which declares
       `OperationContract<Input, Output, RefusalCode>`, `query`, `mutation`, `defineOperations`, `OperationRequest<Table>` and
       `OperationReply<Table>`). `Input` and `Output` are named, closed types: never `any`, `unknown`, `Record<string, unknown>`,
@@ -333,6 +335,10 @@ rules:
       table with the type checker, and the full `starci app check` fails when the committed file is stale.
       A public REST operation in either edition belongs to this nonempty table, and its route decorator supplies its own
       versioned-operation evidence; a class-level reference does not justify a route absent from the table.
+      The body of the route is typed by an alias, which leaves no class at run time, so the global pipe validates nothing there.
+      The route therefore binds the body to `OperationValidationService` of `platform/http-security`, given a request class that
+      mirrors the envelope (`@IsIn` on `operation`, a bounded `requestId`, a `@ValidateNested()` input class with the bounds of
+      BE-AUTH-5), and the owning domain service still refuses an input outside its own bounds.
     rationale: |-
       The operation set of an app is a contract the front end (`fe/`, through the root codegen) and other consumers generate a client from. A name-to-string registry with `unknown`
       bodies and results forces every client to hand-type the wire; one typed table gives the client generator, the route and the
@@ -341,14 +347,18 @@ rules:
       - id: case-1
         when: A query with two refusals and a mutation with none
         write: |-
-          // be/apps/core/src/operations.ts
+          // modules/domain/sales/sales-operations.contracts.ts
           export const OPERATIONS = defineOperations({
               "sales.policy@1": query<SalesPolicyAsk, SalesPolicyView, "DENIED" | "INVALID">(),
               "sales.close@1": mutation<SalesCloseAsk, SalesOpportunityView>(),
           })
+          // be/apps/core/src/operations.ts
+          export { OPERATIONS } from "@modules/domain/sales"
           // features/api/sales/transport/http/operations.controller.ts
           @Post("operations")
-          async invoke(@Body() request: OperationRequest<typeof OPERATIONS>): Promise<OperationReply<typeof OPERATIONS>> { ... }
+          async invoke(
+              @Body(new OperationValidationService(SalesPolicyRequest)) request: OperationRequest<typeof OPERATIONS>,
+          ): Promise<OperationReply<typeof OPERATIONS>> { ... }
     verification:
       automated:
         - BE_OPERATION_CONTRACT
@@ -358,7 +368,8 @@ rules:
         - BE_REST_ROUTE_UNDECLARED
       manual:
         - Confirm each refusal code is one the operation's owner can actually answer.
-    relatedExamples: [api]
+        - Confirm that the request class mirrors the envelope and the input bounds of the table.
+    relatedExamples: [operations]
 files:
   - path: src/features/api/<feature>/index.ts
     slot: be.feature

package/runtime/knowledge/patterns/be/realtime.yaml

@@ -3,10 +3,15 @@ id: be.feature.realtime
 title: Realtime channels
 purpose: |-
   Given a state change a connected client must see without asking, how is it pushed? Realtime is a feature KIND:
-  `be/src/features/realtime/<channel>/` holds one door per channel, a socket gateway (`<channel>.gateway.ts`) or a GraphQL
-  subscription (`<x>.subscription.ts`), that READS and PUSHES only. It never writes. The push is fed by a reactor: an event
-  consumer in `features/reactors/` receives the domain event and publishes to a topic of the `RealtimeHub` of `platform/realtime`;
-  the door only subscribes the client to a topic of that hub, scoped to the client's principal.
+  `be/src/features/realtime/<channel>/` holds one door per channel, a server-sent-events controller
+  (`transport/sse/<channel>.controller.ts`), a socket gateway (`<channel>.gateway.ts`) or a GraphQL subscription
+  (`<x>.subscription.ts`), that READS and PUSHES only. It never writes. The push is fed by a reactor: an event consumer in
+  `features/reactors/` receives the domain event and publishes to a topic of the `RealtimeHub` of `platform/realtime` (an app
+  with no event bus lets the domain service that commits the change publish, after its commit); the door only subscribes the
+  client to a topic of that hub, scoped to the client's principal. SSE is the default door for one-way server-to-client push
+  (job progress, a status that changes, streamed tokens), in lite and in full (owner decision 2026-10-24): it is plain HTTP
+  behind the ingress, reconnects by itself and resumes from `Last-Event-ID`. The socket.io gateway stays for a channel that also
+  needs client-to-server messages, and the GraphQL subscription stays full-only.
 appliesTo:
   - backend
 family: be
@@ -19,27 +24,38 @@ provenance:
     - knowledge/patterns/be/transport.yaml
     - knowledge/patterns/be/api-auth.yaml
     - owner decision 2026-10-02 (feature kinds: webhooks, realtime, reactors, saga, jobs, cli; no kind imports another)
+    - owner decision 2026-10-24 (the lite edition may serve SSE, and SSE is the default door for one-way push; ruling:R212/case-5)
   limitations: |-
     Static checks prove the door's role, that the hub is the only thing injected and that a subscribed topic is built from the
     principal. They do not prove the topic naming is collision free across channels, that an initial snapshot is consistent with
     the stream, or the behaviour of the socket under reconnects; the three `realtime/*` scenarios prove delivery, isolation and
-    cleanup on the real stack.
+    cleanup on the real stack. Nothing proves the ingress settings of an SSE channel (no compression, no buffering, HTTP/2, an
+    idle timeout above the heartbeat): they are reviewed against the stack files and a real stream. The hub is single-replica:
+    its subscriptions and its replay buffer live in one process, so a second replica of the api does not see the pushes of the
+    first.
 rules:
   - id: BE-REALTIME-1
     title: A channel is a kind folder with one door, its module and its own spec
     kind: mandatory
-    hfsRules: [R01, R02, R47, R184]
+    hfsRules: [R01, R02, R47, R184, R278]
     requirement: |-
       A push channel lives in `be/src/features/realtime/<channel>/` (slot `be.feature.realtime`), enabled by declaring the pattern
       `realtime` in `hfs.json` `sides.be.patterns`. The folder holds `index.ts` (the module class an app composes), `transport/<protocol>/<channel>-<protocol>.module.ts`, ONE door and its spec: either
+      `transport/sse/<channel>.controller.ts` (one `@Controller` class with ONE `@Sse` method, the default for one-way push) with
+      `<channel>.controller.spec.ts`, or
       `transport/websocket/<channel>.gateway.ts` (one `@WebSocketGateway` class whose handlers are `@SubscribeMessage`) with
       `<channel>.gateway.spec.ts`, or `transport/graphql/<channel>.subscription.ts` (one `@Resolver` class whose operations are `@Subscription`) with
       `<channel>.subscription.spec.ts`, plus optional `dto/` (`<name>.{input,type,args}.ts`). A door carries no query, mutation, field
-      resolver or REST route. The kind imports only `modules/*`, never another kind, and only an api-kind app composes its module.
+      resolver or plain REST route (`@Get`, `@Post` ...; the `@Sse` stream is the event-stream evidence of BE_REST_DOOR_EVIDENCE only in the
+      sse slot). The kind imports only `modules/*`, never another kind, and only an api-kind app composes its module. SSE and the
+      socket.io gateway run in lite and in full; the GraphQL subscription is full only.
     rationale: |-
       One file per door keeps a protocol's machinery in one place, and keeping queries and mutations out guarantees that what a
       client can do through a realtime door is listen.
     cases:
+      - id: case-3
+        when: A one-way push of a status (job progress, a booking that gets confirmed), in either edition
+        write: 'features/realtime/booking-status/index.ts, transport/sse/booking-status-sse.module.ts, transport/sse/booking-status.controller.ts and transport/sse/booking-status.controller.spec.ts.'
       - id: case-1
         when: A GraphQL subscription of order status
         write: 'features/realtime/order-status/index.ts, transport/graphql/order-status-graphql.module.ts, transport/graphql/order-status.subscription.ts and transport/graphql/order-status.subscription.spec.ts.'
@@ -78,6 +94,8 @@ rules:
         - BE_CONTRACT_UNGUARDED
         - BE_UNIT_SPEC_NOT_STAGED
         - BE_REALTIME_SHAPE
+        - BE_REST_DOOR_EVIDENCE
+        - BE_REST_ROUTE_UNDECLARED
       manual:
         - Confirm no query or mutation lives in a subscription door; it lives in an api feature.
     relatedExamples: [realtime]
@@ -87,12 +105,17 @@ rules:
     hfsRules: [R185, R90, R203]
     requirement: |-
       A realtime door is thin (R203 `BE_FEATURE_THIN`): it maps the subscription or the message and makes one delegating call
-      to the hub. The only value it injects is the `RealtimeHub` of `platform/realtime` (`subscribe(topic)` returns an async
-      iterable of frames, `publish(topic, frame)` pushes one; a topic is a typed `RealtimeTopic<T>` built by the owning domain
-      contract, never a string written in a door). No `EntityManager`, `CommandBus`, `QueryBus`, event bus, queue or
+      to the hub. The only value it injects is the `RealtimeHub` of `platform/realtime` (`subscribe(topic, options?)` returns an
+      async iterable of frames, `publish(topic, frame)` pushes one; a topic is a typed `RealtimeTopic<T>` built by the owning domain
+      contract, never a string written in a door). An SSE controller calls `hub.stream(topic, { after })` instead, which returns the
+      `Observable<MessageEvent>` Nest needs (the hub maps its own subscription with `eventStream` of `platform/realtime`): the
+      opening frame, one event per frame with its `id`, and the comment heartbeat. No `EntityManager`, `CommandBus`, `QueryBus`, event bus, queue or
       service of `modules/domain` is injected: a domain service may write, so it is not provably read-only. The data a client
-      needs is pushed by a reactor; the socket library and the pub/sub engine (`socket.io`, `graphql-subscriptions`, `graphql-ws`)
-      are imported only by `platform/realtime`.
+      needs is pushed by a reactor (or by the domain service that commits the change, in an app with no event bus); the socket
+      library and the pub/sub engine (`socket.io`, `graphql-subscriptions`, `graphql-ws`) are imported only by `platform/realtime`,
+      and so is the heartbeat timer (`setInterval` is owned by `platform/realtime`, `infraOwners`). Because the door reads only the
+      hub, a snapshot cannot be sent on connect from the door: the client reads the current state through a query operation first
+      (or again on every open), and the stream carries the changes.
     rationale: |-
       A door that can only touch the hub cannot change business state, so the biggest risk of a long-lived unauthenticated-looking
       connection, a write through it, is removed by type.
@@ -109,11 +132,15 @@ rules:
     kind: mandatory
     hfsRules: [R186, R41]
     requirement: |-
-      Every `@SubscribeMessage` and `@Subscription` handler takes `@CurrentPrincipal()` of `domain/identity` and builds the topic it
+      Every `@SubscribeMessage`, `@Subscription` and `@Sse` handler takes `@CurrentPrincipal()` of `domain/identity` and builds the topic it
       passes to `hub.subscribe` from the principal's id (plus a client-supplied id only inside that prefix) with the topic
       builder of the owning domain contract, so one client cannot
       listen to another's channel. The reactor that pushes uses the same topic builder from the owning domain contract, never a
-      hand-written string. The default-deny guards apply to the door like to any other.
+      hand-written string. The default-deny guards apply to the door like to any other; an SSE stream is never `@Public`. The
+      browser `EventSource` cannot send an `Authorization` header, so the front end reads the stream with `fetch` and the bearer
+      access token (modules/api/sse read by a use<Channel>Stream hook); a token in the URL is refused because it ends up in logs. The `Last-Event-ID` header is client
+      input like any other: it is passed as `{ after }` to `hub.subscribe` and only picks where the replay resumes inside the
+      principal's own topic, it never names a topic.
     rationale: |-
       A topic taken from client input alone is an authorization hole: knowing an order id would be enough to watch it.
     cases:
@@ -136,8 +163,9 @@ rules:
       `subscriber-receives-push` (a connected client receives the frame a reactor pushes after the domain event),
       `foreign-topic-is-isolated` (another principal subscribed to the same channel receives nothing) and
       `disconnect-releases-subscription` (after the client disconnects the hub holds no subscription for it). The client is a real
-      socket or GraphQL-over-websocket client of the test world. The unit spec of the door covers its wiring with the Nest testing
-      module and a recording hub double.
+      socket, GraphQL-over-websocket or HTTP event-stream client of the test world (an SSE channel is read with a real `fetch` of
+      `text/event-stream` against the running api, with the principal's bearer token). The unit spec of the door covers its wiring
+      with the Nest testing module and a recording hub double.
     rationale: |-
       The door has no logic, so the risk is delivery, isolation and leaks on a real connection, which only a client against the
       real app shows.
@@ -151,6 +179,42 @@ rules:
       manual:
         - Confirm the e2e client waits with the world's waitFor and never sleeps.
     relatedExamples: [realtime]
+  - id: BE-REALTIME-5
+    title: An SSE stream stays open, resumes and is bounded
+    kind: mandatory
+    hfsRules: [R184, R278, R90]
+    requirement: |-
+      An SSE channel returns `hub.stream(topic, { after: lastEventId })` of `platform/realtime` and nothing else:
+      the stream writes an opening frame with the reconnect delay (`retry`), one event per frame whose `id` is the domain event id
+      of the frame (unique within the topic, for example `<booking>:<status>`), and a comment heartbeat (`: heartbeat`) every 15 to 25
+      seconds while the channel is idle, below the idle timeout of the ingress. The heartbeat timer belongs to `platform/realtime`
+      alone (`infraOwners` `setInterval`). The hub retains the last frames of a topic that carry a string `id` in a bounded
+      buffer (a fixed number of frames per topic and of topics, the oldest dropped first), so a client that reconnects with
+      `Last-Event-ID` receives what it missed; an id the buffer no longer holds replays the whole buffer, and the client refetches
+      its snapshot through the query operation on every open. The hub is single-replica: the api that composes an SSE channel
+      runs one replica (STACKS_REALTIME_SCALED in lite); a shared hub across replicas is a later decision. At the ingress, the
+      stream route is never compressed or buffered (Nest sends `X-Accel-Buffering: no` and `Cache-Control: no-cache, no-transform`;
+      Traefik's compress middleware excludes `text/event-stream`, a Caddy route sets no `encode` and `flush_interval -1`), the edge
+      speaks HTTP/2 to the browser so the six-connection limit of HTTP/1.1 per origin does not starve tabs, and an Express
+      `compression()` is never put in front of the app.
+    rationale: |-
+      A quiet stream is cut by every proxy that sees no bytes, a buffered one delivers nothing until it fills, and a stream with no
+      ids loses every push made while the client reconnects. Bounding the buffer keeps one process from growing with its history.
+    cases:
+      - id: case-1
+        when: A client on a flaky network reconnects after missing two pushes
+        write: 'The browser reconnects with Last-Event-ID: b-1:confirmed, hub.stream(topic, { after: "b-1:confirmed" }) replays the retained frames after it, then goes live; the front end also refetches the status once on open.'
+    verification:
+      automated:
+        - BE_REALTIME_SHAPE
+        - BE_REST_DOOR_EVIDENCE
+        - BE_REST_ROUTE_UNDECLARED
+        - BE_INFRA_OWNER
+      manual:
+        - Confirm the ingress route of the api sets no compression and no response buffering for text/event-stream, and that its idle timeout is above the heartbeat.
+        - Confirm the lite stack pins the api to one replica (STACKS_REALTIME_SCALED refuses a scaled api that composes realtime).
+        - Confirm the replay bounds fit the channel (frames per topic, number of topics).
+    relatedExamples: [realtime]
 files:
   - path: src/features/realtime/<channel>/index.ts
     slot: be.feature.realtime
@@ -214,11 +278,43 @@ files:
     template: realtime/channel.input.ts.tpl
     role: The typed, bounded arguments of the door.
     rules: [BE_INPUT_BOUNDED]
+  - path: src/features/realtime/<channel>/transport/sse/<channel>-sse.options.ts
+    slot: be.feature.realtime.sse
+    template: realtime/channel.sse.options.ts.tpl
+    role: The options of the SSE door's module; empty, the app's default-deny guards authenticate the stream.
+    optional: true
+  - path: src/features/realtime/<channel>/transport/sse/<channel>-sse.module-definition.ts
+    slot: be.feature.realtime.sse
+    template: realtime/channel.sse.module-definition.ts.tpl
+    role: The configurable-module base of the SSE door's module, registered as register.
+    optional: true
+  - path: src/features/realtime/<channel>/transport/sse/<channel>-sse.module.ts
+    slot: be.feature.realtime.sse
+    template: realtime/channel.sse.module.ts.tpl
+    role: Nest module of the SSE door, composed only by an api-kind app.
+    optional: true
+  - path: src/features/realtime/<channel>/transport/sse/<channel>.controller.ts
+    slot: be.feature.realtime.sse
+    template: realtime/channel.controller.ts.tpl
+    role: A server-sent-events door (one Controller class with one Sse method); the default door for one-way push.
+    rules: [BE_REALTIME_SHAPE, BE_REALTIME_WRITES, BE_REALTIME_TOPIC_SCOPE, BE_REST_DOOR_EVIDENCE]
+    spec: src/features/realtime/<channel>/transport/sse/<channel>.controller.spec.ts
+    optional: true
+  - path: src/features/realtime/<channel>/transport/sse/<channel>.controller.spec.ts
+    slot: be.feature.realtime.sse
+    template: realtime/channel.controller.spec.ts.tpl
+    role: Unit spec of the SSE controller beside it.
+    optional: true
   - path: src/modules/platform/realtime/realtime.hub.ts
     slot: be.platform
-    role: RealtimeHub, the one owner of the socket and subscription engine (publish and subscribe).
+    role: RealtimeHub, the one owner of the socket and subscription engine (publish and subscribe, with the bounded replay buffer an SSE reconnect resumes from).
     spec: src/modules/platform/realtime/realtime.service.spec.ts
     optional: true
+  - path: src/modules/platform/realtime/event-stream.mapper.ts
+    slot: be.platform
+    role: eventStream, the one place that turns hub frames into server-sent events (opening frame, ids, comment heartbeat) and owns the heartbeat timer.
+    spec: src/modules/platform/realtime/event-stream.mapper.spec.ts
+    optional: true
   - path: src/features/reactors/<name>/transport/message/<event>.consumer.ts
     slot: be.transport.message
     role: The reactor consumer that receives the domain event and pushes the frame through the hub.
@@ -229,21 +325,24 @@ files:
     spec: realtime/subscriber-receives-push, realtime/foreign-topic-is-isolated, realtime/disconnect-releases-subscription
     rules: [BE_PATTERN_SPEC_MISSING]
     optional: true
-# Edition lite (R212, owner ruling 2026-10-14): the same ports, door and rules; one instance behind them.
+# Edition lite (R212, owner ruling 2026-10-14; the SSE door by owner decision 2026-10-24, ruling:R212/case-5): the same ports, door and rules; one instance behind them.
 liteAdapter:
   summary: >-
-    Under lite the realtime pattern is the full one: the socket.io gateway of be.feature.realtime.websocket
-    (transport/websocket/<channel>.gateway.ts) runs inside the be api process, one instance with the default in-memory adapter
-    and no Redis adapter. A reactor publishes to the RealtimeHub of platform/realtime, which emits to the principal-scoped room
-    of the namespace; the front end listens through hooks/socketio (knowledge/patterns/fe/realtime.yaml). graphql-ws
-    subscriptions are not used in lite.
+    Under lite the realtime pattern is the full one with its lite doors: the SSE controller of be.feature.realtime.sse
+    (transport/sse/<channel>.controller.ts, the default for one-way push) or the socket.io gateway of be.feature.realtime.websocket
+    (transport/websocket/<channel>.gateway.ts) runs inside the be api process, one instance (the memory hub, its bounded replay
+    buffer and the socket.io default in-memory adapter, no Redis adapter). A publisher (a reactor, or the domain service that
+    commits the change in an app with no event bus) publishes to the RealtimeHub of platform/realtime; the SSE door streams the
+    principal-scoped topic as text/event-stream and the gateway emits to the principal-scoped room of the namespace. The front end
+    listens through a use<Channel>Stream hook over modules/api/sse (a fetch reader with the bearer token) or hooks/socketio (knowledge/patterns/fe/realtime.yaml).
+    graphql-ws subscriptions are not used in lite.
   ports:
-    - {port: RealtimeHub.publish (platform/realtime), adapter: "the socket.io server of the api process emits to the namespace room of the topic (no Redis adapter: one instance)"}
-    - {port: RealtimeHub.subscribe, adapter: "the gateway's @SubscribeMessage handler joins the room built from the principal, as full"}
-    - {port: topic scope, adapter: "the room name built from @CurrentPrincipal (BE_REALTIME_TOPIC_SCOPE), as full"}
+    - {port: RealtimeHub.publish (platform/realtime), adapter: "the memory hub of the api process retains the frame (bounded) and hands it to the open SSE streams; the socket.io server emits to the namespace room of the topic (no Redis adapter: one instance)"}
+    - {port: RealtimeHub.subscribe, adapter: "the SSE controller streams hub.stream(topic, { after }) (the subscription through eventStream); the gateway's stream joins the room built from the principal, as full"}
+    - {port: topic scope, adapter: "the topic and the room name built from @CurrentPrincipal (BE_REALTIME_TOPIC_SCOPE), as full"}
   forbids: [redis, ioredis, "@socket.io/redis-adapter", graphql-ws, graphql-subscriptions]
   proof: >-
-    The gateway's own unit spec (<channel>.gateway.spec.ts) and the hub adapter's spec, as full; declaring realtime requires
-    integration specs titled `realtime/<scenario>: ...` for every declared scenario on `starci supabase start` (R284), using a
-    real socket.io client. Lite has no e2e world.
+    The door's own unit spec (<channel>.controller.spec.ts or <channel>.gateway.spec.ts) and the hub adapter's spec, as full;
+    declaring realtime requires integration specs titled `realtime/<scenario>: ...` for every declared scenario on
+    `starci supabase start` (R284), using a real client (an HTTP event-stream read or a socket.io client). Lite has no e2e world.
   see: [knowledge/patterns/be/supabase-queues.yaml, knowledge/patterns/fe/realtime.yaml]

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

@@ -1027,12 +1027,13 @@ BE_MODULE_SHAPE:
 BE_OPERATION_CONTRACT:
   title: "A versioned operation has no typed contract"
   title_vi: "Thao tác có phiên bản không có hợp đồng kiểu"
-  meaning_vi: "Mỗi thao tác `<tên>@<phiên bản>` của một app được khai báo đúng một lần trong bảng thao tác có kiểu `apps/<app>/src/operations.ts` (`OperationContract<Input, Output, RefusalCode>` đăng ký bằng `defineOperations`). Bộ kiểm tra thấy đầu vào hoặc đầu ra là `any`, `unknown`, `Record<string, unknown>`, kiểu generic chưa gán, hàm hoặc `Date`; mã từ chối không phải hợp các chuỗi literal đóng; hoặc route phục vụ bảng không nhận `OperationRequest<Table>` và trả `Promise<OperationReply<Table>>` của cùng một bảng."
+  meaning_vi: "Mỗi thao tác `<tên>@<phiên bản>` của một app được khai báo đúng một lần trong bảng thao tác có kiểu `apps/<app>/src/operations.ts` (`OperationContract<Input, Output, RefusalCode>` đăng ký bằng `defineOperations`). Bộ kiểm tra thấy đầu vào hoặc đầu ra là `any`, `unknown`, `Record<string, unknown>`, kiểu generic chưa gán, hàm hoặc `Date`; mã từ chối không phải hợp các chuỗi literal đóng; hoặc route phục vụ bảng không nhận `OperationRequest<Table>` và trả `Promise<OperationReply<Table>>` của cùng một bảng, hoặc body của route chưa gắn `OperationValidationService` nên pipe toàn cục không có lớp nào để kiểm."
   causes_vi:
     - "Đầu vào hoặc kết quả của thao tác khai báo là `unknown` nên client phải tự gõ kiểu tay"
     - "Mã từ chối khai báo là `string` thay vì hợp các literal như `\"DENIED\" | \"INVALID\"`"
     - "Route nhận `@Body() body: unknown` hoặc chỉ dùng một nửa `OperationRequest` / `OperationReply`"
-  nextStep_vi: "Khai báo kiểu có tên, đóng cho đầu vào và đầu ra của từng thao tác, liệt kê mã từ chối bằng hợp literal, và cho route nhận `OperationRequest<typeof OPERATIONS>` và trả `Promise<OperationReply<typeof OPERATIONS>>`; chạy `starci app emit` để sinh `contracts/<app>/openapi.json`. 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 BE-OPERATIONS-1; không thêm ngoại lệ, không tắt luật."
+    - "Body của route chỉ gõ bằng `OperationRequest<Table>` mà không có `@Body(new OperationValidationService(RequestClass))`, nên không ai kiểm giá trị lúc chạy"
+  nextStep_vi: "Khai báo kiểu có tên, đóng cho đầu vào và đầu ra của từng thao tác, liệt kê mã từ chối bằng hợp literal, và cho route nhận `@Body(new OperationValidationService(RequestClass)) request: OperationRequest<typeof OPERATIONS>` và trả `Promise<OperationReply<typeof OPERATIONS>>`; chạy `starci app emit` để sinh `contracts/<app>/openapi.json`. 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 BE-OPERATIONS-1; không thêm ngoại lệ, không tắt luật."
   owner: op-retry
   kind: check-finding
 
@@ -1318,6 +1319,17 @@ BE_SCHEMA_AUTHORITY:
   owner: op-retry
   kind: check-finding
 
+BE_SCHEMA_BOUNDED:
+  title: "A zod schema has an unbounded string, collection or open value"
+  title_vi: "Schema zod có chuỗi, tập hợp hoặc giá trị mở không giới hạn"
+  meaning_vi: "Schema ở `<file>` có `z.string()` (hoặc `z.email()`, `z.url()`) không có `.max(n)`/`.length(n)`, `z.array()`/`z.set()` không có `.max(n)`/`.length(n)`/`.size(n)`, `z.record()`/`z.map()` không giới hạn số phần tử bằng `.refine`/`.check`, hoặc dùng `z.any()`, `z.unknown()`, `z.json()`; hoặc giới hạn vô nghĩa như `Infinity`, `0`, `Number.MAX_*`."
+  causes_vi:
+    - "Vi phạm luật R305: mảng không giới hạn mà mọi phần tử đều lỗi sẽ cấp phát một issue cho từng phần tử (GHSA-mrhx-c7xc-m3w5), còn chuỗi không giới hạn là chi phí không giới hạn ở mọi phiên bản zod"
+    - "Schema mô tả dữ liệu ngoài bằng `z.any()` hoặc `z.unknown()` nên thực chất không kiểm gì"
+  nextStep_vi: "Thêm giới hạn hữu hạn dương cho từng chuỗi và tập hợp (`z.string().max(200)`, `z.array(item).max(100)`), giới hạn số phần tử của record bằng `.refine`, và mô tả hình dạng thật thay cho `z.any()`. 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."
+  owner: op-retry
+  kind: check-finding
+
 BE_SCHEMA_OWNER:
   title: "Entities and migrations live in the owning capability's `persistence/`"
   title_vi: "Entity hoặc migration sai chủ"
@@ -1328,6 +1340,17 @@ BE_SCHEMA_OWNER:
   owner: op-retry
   kind: check-finding
 
+BE_SCHEMA_PLACE:
+  title: "A zod schema is outside its zone"
+  title_vi: "Schema zod đặt sai vùng"
+  meaning_vi: "Tệp `<file>` import `zod` ngoài tệp `<name>.schema.ts` của một chủ sở hữu domain, platform hoặc integrations; hoặc import `zod` trong feature, cửa transport hay thư mục `dto/`; hoặc tệp schema còn import `class-validator`, `class-transformer` hay `@nestjs/graphql`."
+  causes_vi:
+    - "Vi phạm luật R304: đầu vào của cửa transport được class-validator kiểm (R42), còn dữ liệu không đi qua DTO (phản hồi của nhà cung cấp, đầu ra có cấu trúc của mô hình, payload hàng đợi hoặc outbox đọc lại) mới đi qua schema zod của chủ sở hữu"
+    - "Schema zod viết thẳng trong service, mapper hay lớp DTO thay vì tệp `<name>.schema.ts`"
+  nextStep_vi: "Chuyển schema sang `<name>.schema.ts` cạnh bộ đọc trong chủ sở hữu domain, platform hoặc integrations, để bộ đọc import schema (và kiểu suy ra) từ đó và ánh xạ lỗi parse sang họ lỗi của chủ sở hữu; đầu vào của cửa transport dùng class-validator. 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."
+  owner: op-retry
+  kind: check-finding
+
 BE_SECRET_DEFAULT:
   title: "Literal default for a secret or URL"
   title_vi: "Giá trị mặc định cố định cho bí mật hoặc URL"

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

@@ -3,6 +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),
  *                      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.
@@ -24,7 +25,7 @@
  * Specs and tests are not in the graph, so an export used only by a spec is dead, on purpose, with these exceptions (unit test
  * standard): the unit spec of every unit role (ruleParams.be.unitRoles: `<name>.service.spec.ts`, `<name>.cli.spec.ts`) and of every logic role
  * (ruleParams.be.logicRoles: `<name>.policy.spec.ts`, `<name>.client.spec.ts`, ...), a
- * unit spec of a webhook, gateway or subscription door (`.webhook.spec.ts`, `.gateway.spec.ts`, `.subscription.spec.ts`: a door has no service of its own), a
+ * unit spec of a webhook, gateway, subscription or SSE controller door (`.webhook.spec.ts`, `.gateway.spec.ts`, `.subscription.spec.ts`, `.controller.spec.ts`: a door has no service of its own), a
  * `*.builder.ts` under src/tests/fixtures/builders, and a file of the test world (slots be.tests.world and be.tests.world.kit, which
  * open and migrate the real databases of the e2e run) read from disk or staged in the git index count as consumers, because a spec can only provide an
  * Inject*() token or a param type the entry exports, and the world wires the same capabilities the apps do. An integration
@@ -47,6 +48,8 @@ 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'];
@@ -144,7 +147,7 @@ function rootFiles(graph, config) {
     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)) roots.add(rel);
+    if ((slot?.requires ?? []).includes(inside) || inside === OPERATION_TABLE_FILE) roots.add(rel);
   }
   for (const [key, owner] of graph.ownerRoots) {
     if (owner.tier !== 'package') continue;
@@ -177,8 +180,8 @@ function deadFiles(graph, config) {
   return { violations, judged: judgedFiles.length, roots: roots.size };
 }
 
-/** The unit spec of a webhook, gateway or subscription door: a door has no service of its own, so its spec is the only unit spec of its kind. */
-const DOOR_SPEC = /^src\/features\/(?:webhooks|realtime)\/.+\.(?:webhook|gateway|subscription)\.spec\.ts$/u;
+/** The unit spec of a webhook, gateway, subscription or SSE controller door: a door has no service of its own, so its spec is the only unit spec of its kind. */
+const DOOR_SPEC = /^src\/features\/(?:webhooks|realtime)\/.+\.(?:webhook|gateway|subscription|controller)\.spec\.ts$/u;
 const BUILDER_CONSUMER = /^src\/tests\/fixtures\/builders\/.+\.builder\.ts$/u;
 /** The test world slots (knowledge/hfs/slots.yaml): their files wire the real capabilities of the e2e run. */
 const WORLD_SLOTS = new Set(['be.tests.world', 'be.tests.world.kit']);

package/runtime/scripts/hfs/rules/doc-fresh.mjs

@@ -18,6 +18,9 @@ const DOCUMENT = /(?:^|\/)README\.md$|(?:^|\/)docs\/.+\.mdx?$/i;
 const KEY = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/;
 const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
 const PLACEHOLDER = /[<>{}*$]/;
+const ERROR_CODE_FILE = /(?:^|\/)errors\/[^/]+\.[cm]?[jt]s$|\.error\.[cm]?[jt]s$|\.messages\.[cm]?[jt]s$/;
+const ERROR_CODE_PROSE = /\b(?:error|failure|exception)s?\s+codes?\b/i;
+const ENV_PROSE = /\benv(?:ironment)?\b|\bvariable\b/i;
 const PATH_TOKEN = /^(?:\.\.?\/)?[\w@.-]+(?:\/[\w@.()[\]-]+)*\/?$/;
 let runtimeCatalogs;
 
@@ -225,8 +228,18 @@ function symbolCall(ts, node) {
   return ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === 'Symbol' && callee.name.text === 'for';
 }
 
-function declaredTokens(ts, source, tokens) {
+/** A code the app declares: a string literal of an error file (enum member, kind map) or an `errors.<CODE>` message key. */
+function declaredErrorCode(ts, node) {
+  if (!ts.isStringLiteralLike(node)) return undefined;
+  const key = /^(?:errors\.)?([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)$/.exec(node.text);
+  return key?.[1];
+}
+
+function declaredTokens(ts, source, tokens, file = '') {
+  const errorFile = ERROR_CODE_FILE.test(file);
   const visit = (node) => {
+    const code = errorFile ? declaredErrorCode(ts, node) : undefined;
+    if (code) tokens.add(code);
     if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && KEY.test(node.name.text) && symbolCall(ts, node.initializer)) tokens.add(node.name.text);
     ts.forEachChild(node, visit);
   };
@@ -240,14 +253,15 @@ function injectionTokens(repoRoot, tracked) {
   for (const file of tracked) {
     if (!/\.[cm]?[jt]sx?$/.test(file) || /(?:(?:^|\/)(?:tests?|__tests__)\/)|(?:(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$)/.test(file)) continue;
     const text = readText(repoRoot, file) ?? '';
-    declaredTokens(ts, ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true), tokens);
+    declaredTokens(ts, ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true), tokens, file);
   }
   return tokens;
 }
 
 function unknownEnvironmentName(name, line, keys, codes, tokens, explicit) {
   if (!KEY.test(name) || /^R\d+$/.test(name) || codes.has(name)) return false;
-  if (!explicit && tokens.has(name) && !/\benv(?:ironment)?\b|\bvariable\b/i.test(line)) return false;
+  if (!explicit && tokens.has(name) && !ENV_PROSE.test(line)) return false;
+  if (!explicit && ERROR_CODE_PROSE.test(line) && !ENV_PROSE.test(line)) return false;
   if (!name.includes('_') && !keys.has(name) && !/\benv(?:ironment)?\b|\b(?:key|variable)s?\b/i.test(line)) return false;
   return !keys.has(name) && !(name.endsWith('_FILE') && keys.has(name.slice(0, -5)));
 }

package/runtime/scripts/hfs/rules/stacks-swarm.mjs

@@ -388,7 +388,7 @@ function realtimeIssues(input, add) {
     const component = mapping(input.doc.components)[id], app = component?.app ?? id;
     if (!apis.has(app) || service.deploy?.replicas === 1) continue;
     if (appComposesRealtime(input.repoRoot, app, list(input.files)))
-      add('STACKS_REALTIME_SCALED', `services.${id}.deploy.replicas`, 'A lite API composing realtime must pin deploy.replicas: 1 because its gateway runs in one API process');
+      add('STACKS_REALTIME_SCALED', `services.${id}.deploy.replicas`, 'A lite API composing realtime must pin deploy.replicas: 1 because its realtime hub and gateway live in one API process');
   }
 }
 

package/runtime/scripts/lib/json-formats.mjs

@@ -25,6 +25,7 @@ export const JSON_FORMATS = Object.freeze([
   { id: 'keycloak-realm-import', tool: 'Keycloak realm import', match: (rel) => /(^|\/)\.starcistacks\/[^/]+\/infra\/compose\/realm-[^/]+\.json$/.test(rel) },
   { id: 'package-scripts-fragment', tool: 'npm (scripts rendered into package.json)', match: (rel) => /^packages\/hfs\/templates\/app\/package-scripts[^/]*\/[^/]+\.json$/.test(rel) },
   { id: 'async-event-contract', tool: 'starci app emit', match: (rel) => /(^|\/)be\/contracts\/[^/]+\/events(\.pin)?\.json$/.test(rel) },
+  { id: 'operation-contract', tool: 'starci app emit', match: (rel) => /(^|\/)be\/contracts\/[^/]+\/openapi\.json$/.test(rel) },
   { id: 'model-scorecard-snapshot', tool: 'scripts/agent/benchmark-snapshot.mjs', match: (rel) => /^benchmark\/snapshots\/[^/]+\.json$/.test(rel) },
 ]);
 

package/scaffold/app.mjs

@@ -157,7 +157,7 @@ const STARTER_DEPENDENCIES = Object.freeze({
   dependencies: {
     '@apollo/server': null, '@nestjs/apollo': null, '@nestjs/common': null, '@nestjs/core': null, '@nestjs/cqrs': null, '@nestjs/graphql': null,
     '@nestjs/platform-express': null, '@nestjs/typeorm': null, 'nest-commander': null, pg: null, graphql: null,
-    'class-transformer': null, 'class-validator': null, 'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null,
+    'class-transformer': null, 'class-validator': null, 'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, zod: null,
   },
   devDependencies: {
     turbo: null, '@nestjs/testing': null, '@starci/cli': null, '@starci/eslint-canon-be': null, '@starci/eslint-canon-fe': null, '@starci/jest-preset': null,
@@ -178,7 +178,7 @@ const LITE_STARTER_DEPENDENCIES = Object.freeze({
     '@apollo/server': null, '@nestjs/apollo': null, '@nestjs/common': null, '@nestjs/core': null, '@nestjs/cqrs': null, '@nestjs/graphql': null,
     '@nestjs/platform-express': null, '@nestjs/typeorm': null, '@supabase/supabase-js': null,
     'class-transformer': null, 'class-validator': null, graphql: null, jose: null, pg: null,
-    'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null,
+    'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, zod: null,
   },
   devDependencies: {
     turbo: null, '@nestjs/testing': null, '@starci/eslint-canon-be': null, '@starci/eslint-canon-fe': null, '@starci/cli': null,

package/templates/app/skeleton-lite/.starcistacks/production/infra/swarm/Caddyfile

@@ -7,5 +7,8 @@
 }
 
 api.{{project}}.example.invalid {
-    reverse_proxy api:3001
+    reverse_proxy api:3001 {
+        # server-sent events: flush every write at once; never add `encode` to this route (no compression of text/event-stream)
+        flush_interval -1
+    }
 }

package/templates/be/patterns/realtime/channel.controller.spec.ts.tpl

@@ -0,0 +1,103 @@
+import { METHOD_METADATA, PATH_METADATA, SSE_METADATA } from "@nestjs/common/constants"
+import type { MessageEvent } from "@nestjs/common"
+import { RequestMethod } from "@nestjs/common"
+import { Test } from "@nestjs/testing"
+import { Observable } from "rxjs"
+import { @@service@@ } from "@@serviceModule@@"
+import type { Principal } from "@modules/platform/cqrs"
+import { REALTIME_HUB } from "@modules/platform/realtime"
+import type { RealtimeHub, RealtimeSubscribeOptions, RealtimeTopic } from "@modules/platform/realtime"
+import { @@Channel@@Controller } from "./@@channel@@.controller"
+
+const principal: Principal = { id: "p-1", role: "authenticated" }
+/** One event of the channel: replace the data with the real frame; its `id` is the domain event id. */
+const EVENT: MessageEvent = { id: "x-1", data: { id: "x-1" } }
+
+/** A recording hub whose event stream yields one event and records the topic, the resume point and the release. */
+const hubAnswering = () => {
+    const streamed: Array<{ readonly topic: string; readonly after: string | undefined }> = []
+    const released: Array<string> = []
+    const hub: RealtimeHub = {
+        publish: () => undefined,
+        subscribe: () => ({ [Symbol.asyncIterator]: () => ({ next: () => Promise.resolve({ done: true, value: undefined }) }) }),
+        subscriberCount: () => 0,
+        stream: <T extends { readonly id: string }>(topic: RealtimeTopic<T>, options?: RealtimeSubscribeOptions) => {
+            streamed.push({ topic: topic.name, after: options?.after })
+            return new Observable<MessageEvent>((subscriber) => {
+                subscriber.next(EVENT)
+                return () => {
+                    released.push(topic.name)
+                }
+            })
+        },
+    }
+    return { hub, streamed, released }
+}
+
+const build = async (hub: RealtimeHub) => {
+    const moduleRef = await Test.createTestingModule({
+        controllers: [@@Channel@@Controller],
+        providers: [{ provide: REALTIME_HUB, useValue: hub }],
+    }).compile()
+    return moduleRef.get(@@Channel@@Controller)
+}
+
+describe("@@Channel@@Controller", () => {
+    it("streams the topic built only from the authenticated principal", async () => {
+        const { hub, streamed } = hubAnswering()
+        const door = await build(hub)
+
+        door.stream(principal, undefined).subscribe().unsubscribe()
+
+        expect(streamed).toEqual([{ topic: @@service@@(principal.id).name, after: undefined }])
+    })
+
+    it("isolates another authenticated principal's topic", async () => {
+        const { hub, streamed } = hubAnswering()
+        const door = await build(hub)
+
+        door.stream({ id: "p-2", role: "authenticated" }, undefined).subscribe().unsubscribe()
+
+        expect(streamed.map((entry) => entry.topic)).toEqual([@@service@@("p-2").name])
+        expect(streamed.map((entry) => entry.topic)).not.toContain(@@service@@(principal.id).name)
+    })
+
+    it("resumes after the Last-Event-ID inside the caller's own topic", async () => {
+        const { hub, streamed } = hubAnswering()
+        const door = await build(hub)
+
+        door.stream(principal, "x-0").subscribe().unsubscribe()
+
+        expect(streamed).toEqual([{ topic: @@service@@(principal.id).name, after: "x-0" }])
+    })
+
+    it("hands the events of the hub to the response as they are", async () => {
+        const { hub } = hubAnswering()
+        const door = await build(hub)
+        const received: Array<MessageEvent> = []
+
+        door.stream(principal, undefined).subscribe((event) => received.push(event)).unsubscribe()
+
+        expect(received).toEqual([EVENT])
+    })
+
+    it("releases the hub stream when the client disconnects", async () => {
+        const { hub, released } = hubAnswering()
+        const door = await build(hub)
+
+        door.stream(principal, undefined).subscribe().unsubscribe()
+
+        expect(released).toEqual([@@service@@(principal.id).name])
+    })
+
+    it("is one GET event stream with no other handler", async () => {
+        const { hub } = hubAnswering()
+        const door = await build(hub)
+
+        expect(Reflect.getMetadata(SSE_METADATA, door.stream)).toBe(true)
+        expect(Reflect.getMetadata(METHOD_METADATA, door.stream)).toBe(RequestMethod.GET)
+        expect(Reflect.getMetadata(PATH_METADATA, door.stream)).toBe("stream")
+        expect(Reflect.getMetadata(PATH_METADATA, @@Channel@@Controller)).toBe("@@channel@@")
+        expect(Object.getOwnPropertyNames(@@Channel@@Controller.prototype)).toEqual(["constructor", "stream"])
+    })
+})

package/templates/be/patterns/realtime/channel.controller.ts.tpl

@@ -0,0 +1,23 @@
+import { Controller, Headers, Sse } from "@nestjs/common"
+import type { MessageEvent } from "@nestjs/common"
+import type { Observable } from "rxjs"
+import { @@service@@ } from "@@serviceModule@@"
+import { CurrentPrincipal } from "@modules/domain/identity"
+import type { Principal } from "@modules/platform/cqrs"
+import { InjectRealtimeHub } from "@modules/platform/realtime"
+import type { RealtimeHub } from "@modules/platform/realtime"
+
+@Controller("@@channel@@")
+/** The push-only @@channel@@ door: the default guards authenticate the stream, and it writes nothing. */
+export class @@Channel@@Controller {
+    constructor(@InjectRealtimeHub() private readonly hub: RealtimeHub) {}
+
+    /**
+     * The changes of the caller's @@channel@@, as server-sent events. The domain contract builds the principal-wide topic and the
+     * reactor publishes through the same builder; a `Last-Event-ID` header only resumes after that frame inside the caller's own topic.
+     */
+    @Sse("stream")
+    stream(@CurrentPrincipal() principal: Principal, @Headers("last-event-id") lastEventId?: string): Observable<MessageEvent> {
+        return this.hub.stream(@@service@@(principal.id), { after: lastEventId })
+    }
+}

package/templates/be/patterns/realtime/channel.sse.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Channel@@SseOptions } from "./@@channel@@-sse.options"
+
+/** The configurable-module base of the @@channel@@-sse module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Channel@@SseOptions>().setClassMethodName("register").build()

package/templates/be/patterns/realtime/channel.sse.module.ts.tpl

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./@@channel@@-sse.module-definition"
+import { @@Channel@@Controller } from "./@@channel@@.controller"
+
+@Module({ controllers: [@@Channel@@Controller] })
+/** The server-sent-events transport of the @@channel@@ channel: one authenticated stream per principal. */
+export class @@Channel@@SseModule extends ConfigurableModuleClass {}

package/templates/be/patterns/realtime/channel.sse.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@channel@@ SSE door takes no options: the app's default-deny guards authenticate the stream and the hub is global. */
+export type @@Channel@@SseOptions = Record<string, never>