@starci/hfs 4.7.32 → 4.7.34

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

@@ -164,4 +164,4 @@ liteAdapter:
   proof: >-
     `starci app check --wiring` proves the composing lite app's module graph with doubles (R272); declaring event-bus requires
     its scenario-titled integration specs on `starci supabase start` (R284), including redelivery through the reactor.
-  see: [knowledge/patterns/be/supabase-queues.yaml]
+  see: [knowledge/patterns/be/event-bus.yaml]

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

@@ -11,7 +11,8 @@ purpose: |-
   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.
+  needs client-to-server messages, and the GraphQL subscription is the restricted door for a typed schema payload on a client that already uses
+  GraphQL (BE-REALTIME-6); all three run in both editions.
 appliesTo:
   - backend
 family: be
@@ -24,15 +25,27 @@ 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)
+    - 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, amended by owner:lite-graphql-subscription-door and ruling:R212/case-7 for the GraphQL subscription door)
   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. 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.
+    idle timeout above the heartbeat): they are reviewed against the stack files and a real stream. The memory hub is
+    single-process: its subscriptions and its replay buffer live in one process, so it serves tests and one replica only
+    (STACKS_REALTIME_SCALED refuses it with more); a shared hub (BE-REALTIME-7) carries pushes and replay across replicas, and
+    its socket.io adapters have no connection state recovery, so a socket client resyncs by query. A replay returns at most 64 frames
+    per topic; Postgres sweeps frames older than 15 minutes, Redis expires a topic stream after 15 minutes without a retained publish,
+    and memory keeps its bounded buffer without a TTL. A client whose
+    `Last-Event-ID` is older or unknown receives the newest retained frames with no signal
+    of the gap, so a screen refetches its snapshot after any reconnect. A frame with no string `id` is live-only in the memory
+    and Redis hubs; Postgres retains it and reloads it after a LISTEN loss by its sequence position, but no client can name it as
+    `Last-Event-ID`. Only the Postgres hub publishes inside the publisher's transaction, the other hubs push at once. Each open
+    subscription on a shared hub keeps its own last position, initially where its topic stood at join. After a lost LISTEN or subscriber connection
+    the hub reloads each topic after the minimum last position of its open subscriptions; each subscription drops positions it has
+    already taken, so a new subscription cannot skip frames owed to an older one and replay, reload and held notifications do not
+    duplicate a retained frame. A failed reload keeps live delivery paused and retries until the current loss generation reloads.
+    graphql-ws has no replay: a screen on a GraphQL subscription refetches its snapshot on reconnect.
 rules:
   - id: BE-REALTIME-1
     title: A channel is a kind folder with one door, its module and its own spec
@@ -47,8 +60,8 @@ rules:
       `<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 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.
+      sse slot). The kind imports only `modules/*`, never another kind, and only an api-kind app composes its module. All three doors
+      run in lite and in full; BE-REALTIME-6 chooses between them.
     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.
@@ -106,13 +119,13 @@ rules:
     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, options?)` returns an
-      async iterable of frames, `publish(topic, frame)` pushes one; a topic is a typed `RealtimeTopic<T>` built by the owning domain
+      async iterable of frames, `publish(topic, frame)` pushes one and settles once the hub accepted it; 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 (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`,
+      library and the pub/sub engine (`socket.io`, `@socket.io/postgres-adapter`, `@socket.io/redis-adapter`, `graphql-subscriptions`, `graphql-ws`, `pg` for LISTEN and `ioredis`) 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.
@@ -138,7 +151,7 @@ rules:
       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; 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
+      access token (an operation of modules/api/sse read by a useSubscribe<Channel>Swr 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: |-
@@ -160,6 +173,7 @@ rules:
     hfsRules: [R155]
     requirement: |-
       Declaring the pattern `realtime` requires e2e or integration tests titled `realtime/<scenario>: ...` for each scenario
+      `push-crosses-replicas` and `resume-after-reconnect` (two api replicas, BE-REALTIME-7),
       `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
@@ -191,8 +205,8 @@ rules:
       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
+      its snapshot through the query operation on every open. The memory hub keeps that buffer in one process; a shared hub keeps it in
+      the `realtime_events` table or a Redis Stream, so a reconnect that lands on any replica resumes (BE-REALTIME-7). 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
@@ -212,9 +226,230 @@ rules:
         - 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 an api that runs more than one replica selects a shared hub (STACKS_REALTIME_SCALED refuses the memory hub there).
         - Confirm the replay bounds fit the channel (frames per topic, number of topics).
     relatedExamples: [realtime]
+  - id: BE-REALTIME-6
+    title: The door follows what is pushed and which way, not the API default
+    kind: mandatory
+    hfsRules: [R184, R212, R90, R185, R186]
+    requirement: |-
+      The API's default door is GraphQL (BE-TRANSPORT), but realtime is a separate decision: what is pushed and in which direction
+      picks the door, in both editions.
+
+      Choosing the door (both editions):
+      - One-way server-to-client push (a status that changes, job progress, streamed AI tokens): SSE, the default. It is plain HTTP that
+        passes every proxy, ingress and HTTP/2, the browser reconnects by itself and resumes from `Last-Event-ID` (the hub replays),
+        and it is the cheapest per connection.
+      - A push of a schema type the screen already reads through GraphQL, when the typed payload matters (the whole `Order` with its
+        generated type): the GraphQL subscription, restricted. It shares the schema, the codegen and the guards of the queries. Its
+        limits: graphql-ws has no replay, so on every reconnect the screen refetches its snapshot with a query; it costs more per
+        connection; it needs the WebSocket upgrade at the ingress. Use it only when the client already uses GraphQL AND needs the typed
+        payload; otherwise SSE.
+      - Two-way messages (chat, presence, collaborative input): the WebSocket door (socket.io gateway), the only door where the client
+        sends messages. It needs the WebSocket upgrade, plus sticky sessions when the long-polling fallback is on.
+
+      Every door, in both editions: it reads and pushes only (no write, query, mutation or REST route); its topic is built from
+      `@CurrentPrincipal()` and it is never `@Public`; a token never travels in the URL; only `platform/realtime` imports the engine
+      (`graphql-ws`, `graphql-subscriptions`, `socket.io`); three `realtime/*` scenarios prove delivery, isolation and cleanup. On the
+      front end the reader of a stream, a subscription or a socket is owned by the transport client layer, exposed as an operation and
+      consumed only through an SWR subscription hook that revalidates its snapshot query when the stream opens, with no fetch in an effect
+      (knowledge/patterns/fe/realtime.yaml).
+
+      Hub (both editions): the hub default is Redis when Redis is declared (lite or full), Postgres LISTEN/NOTIFY when lite declares no
+      Redis, and memory for tests or a single replica only; the memory hub is non-scale. Scale is the hub adapter behind the one
+      `RealtimeHub` port, never a different door. The Redis and Postgres hubs, the refusal of a stack with more than one api replica on
+      the memory hub (STACKS_REALTIME_SCALED) and the two-replica scenarios are the realtime scale rule BE-REALTIME-7.
+
+      Lite (ruling:R212/case-10, owner:lite-vector-is-pgvector):
+      ONE instance type, one api deployable, scales horizontally and stateless, with no sticky sessions, on Postgres/Supabase plus
+      Redis when a declared capability needs it. Vector search uses Supabase pgvector. The three doors above are served from that api (the GraphQL subscription door is new
+      in lite, ruling:R212/case-7). A lite api with more than one replica uses the Redis hub when Redis is
+      declared, else the Postgres hub. The example is the SSE `booking-status` channel.
+
+      Full: the complete infrastructure, several services with Redis (ioredis, BullMQ), and the api may run several replicas on the Redis hub (BE-REALTIME-7). The three doors and the choice above are the same as lite; no door is full-only. The example is the
+      GraphQL subscription `order-status` channel, where the typed `Order` payload matters; a screen that reads it refetches the order on
+      reconnect.
+    rationale: |-
+      A reader who knows the API is GraphQL assumes a GraphQL subscription everywhere; the push is cheaper, easier to proxy and
+      resumable over SSE, so the heavier door is chosen only for what only it gives.
+    cases:
+      - id: case-1
+        when: A booking that gets confirmed after a job, shown on a screen that already reads it through a query
+        write: 'SSE: transport/sse/booking-status.controller.ts; the front end reads the stream through a useSubscribe<Channel>Swr hook and the query operation carries the snapshot.'
+      - id: case-2
+        when: An order whose whole typed payload the screen renders, on a client that already uses GraphQL
+        write: 'GraphQL subscription: transport/graphql/order-status.subscription.ts; on every reconnect the screen refetches the order with its query because graphql-ws has no replay.'
+    verification:
+      automated:
+        - BE_REALTIME_SHAPE
+        - HFS_EDITION_INVALID
+        - HFS_EDITION_FORBIDDEN_PRESENT
+        - HFS_STARCIWORK_LITE_FORBIDDEN
+        - HFS_BACKING_UNDECLARED
+        - HFS_BACKING_UNUSED
+        - BE_INFRA_OWNER
+        - BE_REALTIME_WRITES
+        - BE_REALTIME_TOPIC_SCOPE
+      manual:
+        - Confirm a GraphQL subscription channel serves a client that already uses GraphQL and needs the typed payload, and that its screen refetches the snapshot on reconnect.
+        - "Confirm that a stack with more than one api replica uses a shared hub (BE-REALTIME-7)."
+    relatedExamples: [realtime]
+  - id: BE-REALTIME-7
+    title: A realtime channel scales horizontally on one hub port with a shared hub
+    kind: mandatory
+    hfsRules: [R90, R266, R155]
+    requirement: |-
+      Both editions run N api replicas. `platform/realtime` keeps ONE port, `RealtimeHub` (`publish(topic, frame, within?): Promise<void>`
+      called by a reactor, or by the domain service that owns the state change and passes its own transaction as `within`,
+      `subscribe(topic, { after })` for GraphQL and socket doors, `stream(topic, { after })` for the SSE door), so a door never
+      changes between a single replica and N replicas: only the hub binding does. Three adapters implement the port:
+      `MemoryRealtimeHub` (non-scale: one process, tests and a single-replica dev run, replay from an in-process ring buffer),
+      `PostgresRealtimeHub` (stateless: `publish` takes a per-topic advisory lock, writes a `realtime_events` row and NOTIFYs, in the
+      publisher's transaction when it passes one, so the push goes out at commit and a rolled-back change pushes nothing; every
+      replica LISTENs and fans out to its local subscribers; replay reads the table after the `Last-Event-ID`; when the LISTEN
+      connection is lost the hub holds notifications and reloads each followed topic after the minimum last position of its open
+      subscriptions. Each subscription starts at the topic's join position and advances as it takes entries, dropping any position
+      already taken, so an older subscription receives its outage frames once even when a new subscription joins the same topic.
+      A failed live row load takes the same loss path; a failed reload keeps the pause and retries through the injected Timer after
+      RECONNECT_DELAY_MS. Only a successful reload of the current loss generation releases and drains held notifications; a second
+      loss during a reload leaves the pause to the newer reload. The table is bounded by a fenced TTL sweep job that runs batch after batch) and
+      `RedisRealtimeHub` (`publish` runs one atomic script: XADD to a Redis Stream per topic with `MAXLEN ~`, PEXPIRE and PUBLISH;
+      replay reads the stream with XRANGE and resumes after the newest entry carrying the id; when the subscriber connection comes
+      back the hub reloads each followed topic after the minimum last stream id of its open subscriptions, with the same per-subscription
+      duplicate suppression and paused retry policy as Postgres; ioredis, every key and channel carries the
+      app prefix `REALTIME_REDIS_PREFIX`). The app selects the hub with `REALTIME_HUB=memory|postgres|redis`, parsed once by
+      `parseRealtimeConfig` and validated at boot; unset, the parser defaults to `redis` when `REALTIME_REDIS_URL` is declared (lite
+      and full), `postgres` when lite declares no Redis, and never `memory`, so a scaled deploy cannot fall back to the in-process
+      hub unseen. All three
+      adapters are legal in both editions; select `redis` when Redis is declared (lite with Redis, and full), `postgres` when it is
+      not, and `memory` only for tests or one replica. A Postgres hub LISTENs on `REALTIME_DB_URL` when declared, else on the
+      primary URL, and proves the connection at boot by hearing a probe the hub sends from another session, so a transaction pooler
+      fails the boot instead of delivering nothing. The Redis hub reads its address from the secret `REALTIME_REDIS_URL`
+      (password, ACL user and `rediss://` included). The stack check `STACKS_REALTIME_SCALED` refuses an api that composes
+      a realtime feature, runs more than one replica and does not select `postgres` or `redis`. The socket.io adapters live in
+      `platform/realtime` too and `main.ts` installs the one the hub selects through `realtimeIoAdapter(app)`: the default
+      `IoAdapter` on the memory hub, `PostgresIoAdapter` (`@socket.io/postgres-adapter`, payloads of 8 KB or more through the
+      `socket_io_attachments` table) or `RedisIoAdapter` (`createShardedAdapter`, Redis 7 or later). Both force
+      `transports: ['websocket']`, so on either shared adapter a socket is one connection to one replica, long-polling is off and
+      no sticky session exists. The memory hub's default IoAdapter also accepts polling; the canonical client uses websocket only in every mode.
+      Neither adapter has connection state recovery, and graphql-ws has no replay, so a socket or GraphQL client refetches its
+      snapshot with a query on every reconnect. The engines (`socket.io`, `@socket.io/postgres-adapter`, `@socket.io/redis-adapter`,
+      `graphql-ws`, `graphql-subscriptions`, `pg` for LISTEN and `ioredis`) are imported only by `platform/realtime`
+      (`BE_INFRA_OWNER`). The tables are migrations of the app (`realtime_events` and, for the Postgres socket adapter,
+      `socket_io_attachments`: a Supabase migration in lite, a TypeORM migration of `platform/realtime` in full). Declaring realtime
+      adds two scenarios, proven with two api replicas: `realtime/push-crosses-replicas` (published through replica A, received on
+      replica B) and `realtime/resume-after-reconnect` (`Last-Event-ID` sent to the other replica receives the missed frames).
+    rationale: |-
+      A hub in the process memory loses every push that was published on another replica and every replay buffer a reconnect lands
+      away from. Shared state in Postgres or Redis, a websocket-only transport and a client that resyncs by query make any replica
+      able to serve any request or reconnect, with no sticky session and no state a replica needs from another.
+    cases:
+      - id: case-1
+        when: SSE, non-scale (tests, one replica)
+        write: |-
+          The door is the same in every mode. Only the hub binding differs.
+          // features/realtime/booking-status/transport/sse/booking-status.controller.ts
+          @Controller('booking-status')
+          export class BookingStatusController {
+            constructor(@InjectRealtimeHub() private readonly hub: RealtimeHub) {}
+            @Sse('stream')
+            stream(@CurrentPrincipal() principal: Principal, @Headers('last-event-id') lastEventId?: string): Observable<MessageEvent> {
+              return this.hub.stream(bookingStatusTopic(principal.id), { after: lastEventId })
+            }
+          }
+          // app root: REALTIME_HUB=memory -> RealtimeModule.register({ isGlobal: true, hub: 'memory' }); replay comes from the
+          // in-process buffer and a reconnect must land on the same process.
+      - id: case-2
+        when: SSE, scale on Postgres (lite without Redis; full may too)
+        write: |-
+          The same controller. The app root binds the Postgres hub and the stack runs N replicas with no sticky routing:
+          // be/apps/api/src/compose/platform.ts
+          RealtimeModule.register({ isGlobal: true, ...withConnection(options.realtime, PRIMARY_ENTITY_MANAGER, options.database.url) })
+          // stack.yaml: environment REALTIME_HUB: postgres, deploy.replicas: 2
+          publish writes the realtime_events row and NOTIFYs; every replica LISTENs and writes the frame to its local streams; a
+          reconnect to ANY replica sends Last-Event-ID and the hub reads the missed rows from the table. A domain service that owns the
+          change publishes inside its own transaction (`hub.publish(topic, frame, tx)`), so the confirmation and its push commit together. At the ingress the stream is
+          not buffered or compressed and the idle timeout is above the heartbeat. Migration: supabase/migrations/<ts>_realtime-events.sql
+          (lite) or platform/realtime/persistence/migrations/<epochMs>-create-realtime-events.ts (full).
+      - id: case-3
+        when: SSE, scale on Redis (Redis declared, lite or full)
+        write: |-
+          The same controller. REALTIME_HUB=redis binds RedisRealtimeHub: publish runs one atomic script that XADDs `<prefix>:<topic>`
+          with MAXLEN ~ 64, expires the key and PUBLISHes the frame on the `<prefix>` channel; replay is XRANGE of the stream, resuming after the newest entry whose id equals the Last-Event-ID; no table and no sweep work (its
+          retention tick is a no-op).
+          RealtimeModule.register({ isGlobal: true, ...withConnection(options.realtime, ORDER_ENTITY_MANAGER, options.database.url) })
+          // REALTIME_HUB=redis, the secret REALTIME_REDIS_URL, REALTIME_REDIS_DB (and REALTIME_REDIS_PREFIX when the server is shared);
+          // Redis 7 or later for the sharded socket.io adapter.
+      - id: case-4
+        when: GraphQL subscription, non-scale
+        write: |-
+          // features/realtime/order-status/transport/graphql/order-status.subscription.ts (same in every mode)
+          @Subscription(() => OrderStatusChangedType, { name: 'orderStatusChanged', resolve: (frame: OrderStatusFrame) => frame })
+          @Roles('member')
+          orderStatusChanged(@CurrentPrincipal() principal: Principal, @Args('input') input: OrderStatusInput) {
+            return this.hub.subscribe(orderStatusTopic(principal.id, input.orderId))
+          }
+          // REALTIME_HUB=memory replaces the graphql-subscriptions PubSub, which is not for production.
+      - id: case-5
+        when: GraphQL subscription, scale (Redis or Postgres hub)
+        write: |-
+          The same resolver. graphql-ws rides ONE WebSocket, so no stickiness is needed; the hub fans the frame out through Redis
+          (the full-app order-status example, REALTIME_HUB=redis) or Postgres LISTEN/NOTIFY. graphql-ws has no replay: the screen
+          refetches its snapshot query on every reconnect, in every mode.
+      - id: case-6
+        when: WebSocket (socket.io), non-scale
+        write: |-
+          The gateway is identical in every mode. `main.ts` calls `app.useWebSocketAdapter(realtimeIoAdapter(app))`; on the memory hub
+          that is the default Nest IoAdapter, in process.
+      - id: case-7
+        when: WebSocket, scale on Postgres
+        write: |-
+          // platform/realtime/postgres-io.adapter.ts (installed by realtimeIoAdapter on REALTIME_HUB=postgres)
+          export class PostgresIoAdapter extends IoAdapter {
+            constructor(app: INestApplicationContext, private readonly pool: Pool, private readonly build: typeof createAdapter, logger: Logger) {
+              super(app)
+              pool.on('error', (cause) => logger.warn(RealtimeLogEvent.PoolFailed, { cause: cause.message })) // an idle client lost in a failover must not crash the replica
+            }
+            override createIOServer(port: number, options?: Partial<ServerOptions>): Server {
+              const server: Server = super.createIOServer(port, { ...options, transports: ['websocket'] }) // no polling, so no sticky session
+              server.adapter(this.build(this.pool, { tableName: SOCKET_IO_ATTACHMENTS_TABLE, errorHandler: this.report }))
+              return server
+            }
+          }
+          The pool is built by RealtimeModule from the session-mode database URL (LISTEN does not work through a transaction pooler).
+      - id: case-8
+        when: WebSocket, scale on Redis
+        write: |-
+          // platform/realtime/redis-io.adapter.ts (installed on REALTIME_HUB=redis)
+          export class RedisIoAdapter extends IoAdapter {
+            constructor(app: INestApplicationContext, private readonly publisher: Redis, private readonly subscriber: Redis, private readonly build: typeof createShardedAdapter, logger: Logger, private readonly channelPrefix: string) { super(app) }
+            override createIOServer(port: number, options?: Partial<ServerOptions>): Server {
+              const server: Server = super.createIOServer(port, { ...options, transports: ['websocket'] })
+              server.adapter(this.build(this.publisher, this.subscriber, { channelPrefix: this.channelPrefix })) // two connections, errors logged, channels prefixed
+              return server
+            }
+          }
+    verification:
+      automated:
+        - BE_INFRA_OWNER
+        - STACKS_SECRET_NOT_EXTERNAL
+        - STACKS_SECRET_UNVERSIONED
+        - STACKS_SECRET_ENV_LITERAL
+        - STACKS_PORT_PUBLISHED
+        - STACKS_SECOND_INGRESS
+        - STACKS_DNS_UNDECLARED
+        - STACKS_HOST_UNROUTED
+        - STACKS_TLS_UNDECLARED
+        - STACKS_PLACEMENT_MISSING
+        - STACKS_HEALTHCHECK_MISSING
+        - STACKS_UPDATE_POLICY_MISSING
+        - STACKS_REALTIME_SCALED
+        - BE_PATTERN_SPEC_MISSING
+      manual:
+        - Confirm the ingress holds no sticky-session declaration for the api, and that polling is off in the socket.io client configuration.
+        - Confirm a Postgres hub connects through a session-mode URL and that the realtime tables are migrations of the app.
+    relatedExamples: [realtime]
 files:
   - path: src/features/realtime/<channel>/index.ts
     slot: be.feature.realtime
@@ -305,16 +540,78 @@ files:
     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
+  - path: src/modules/platform/realtime/realtime.port.ts
+    slot: be.platform
+    role: RealtimeHub, the one port of the realtime kind (publish, subscribe, stream) and the typed topic; its three adapters are the files below.
+    optional: true
+  - path: src/modules/platform/realtime/memory-realtime-hub.service.ts
+    slot: be.platform
+    role: "MemoryRealtimeHub, the non-scale adapter: one process, tests and a single-replica dev run, replay from an in-process ring buffer."
+    spec: src/modules/platform/realtime/memory-realtime-hub.service.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/postgres-realtime-hub.service.ts
+    slot: be.platform
+    role: "PostgresRealtimeHub: publish locks the topic, writes a realtime_events row and NOTIFYs (in the publisher's transaction when given), every replica LISTENs and fans out, replay reads the table, and a lost LISTEN connection is reloaded per topic (both editions)."
+    spec: src/modules/platform/realtime/postgres-realtime-hub.service.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/redis-realtime-hub.service.ts
+    slot: be.platform
+    role: "RedisRealtimeHub: a Redis Stream per topic for replay and Pub/Sub for the live push, published by one atomic script over ioredis, reloaded per topic after a subscriber reconnect (when Redis is declared)."
+    spec: src/modules/platform/realtime/redis-realtime-hub.service.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/realtime-subscriptions.policy.ts
+    slot: be.platform
+    role: "The subscriptions of one replica, shared by the shared hubs: join, replay then live without a duplicate, release on stop."
+    spec: src/modules/platform/realtime/realtime-subscriptions.policy.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/postgres-listener.client.ts
+    slot: be.platform
+    role: "The LISTEN connection of the Postgres hub: proves itself with a probe at boot, reconnects, closes the dead client and tells the hub it was lost and when it resumed."
+    spec: src/modules/platform/realtime/postgres-listener.client.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/realtime-retention.service.ts
     slot: be.platform
-    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
+    role: The bounded, batched delete of the replay table that the fenced sweep job runs, asking the fence before every batch.
+    spec: src/modules/platform/realtime/realtime-retention.service.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/no-realtime-retention.service.ts
+    slot: be.platform
+    role: "The retention of a hub with no replay table (memory, Redis): a scheduled sweep tick is acknowledged and deletes nothing."
+    spec: src/modules/platform/realtime/no-realtime-retention.service.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/redis-stream-id.policy.ts
+    slot: be.platform
+    role: Orders two Redis stream ids, so the Redis hub reloads only what a topic has not delivered.
+    spec: src/modules/platform/realtime/redis-stream-id.policy.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/postgres-io.adapter.ts
+    slot: be.platform
+    role: "PostgresIoAdapter: socket.io over @socket.io/postgres-adapter, websocket only, so no sticky session."
+    spec: src/modules/platform/realtime/postgres-io.adapter.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/redis-io.adapter.ts
+    slot: be.platform
+    role: "RedisIoAdapter: socket.io over the sharded @socket.io/redis-adapter (ioredis), websocket only."
+    spec: src/modules/platform/realtime/redis-io.adapter.spec.ts
+    optional: true
+  - path: src/modules/platform/realtime/realtime-io.adapter.ts
+    slot: be.platform
+    role: "realtimeIoAdapter(app), the one call main.ts makes to install the socket.io adapter the selected hub provides."
+    spec: src/modules/platform/realtime/realtime-io.adapter.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/modules/platform/realtime/persistence/migrations/<epochMs13>-create-realtime-events.ts
+    slot: be.persistence
+    role: Full edition migration of the realtime_events replay table and the socket_io_attachments table of the Postgres adapter.
+    optional: true
+  - path: supabase/migrations/<timestamp>_realtime-events.sql
+    slot: repo.side-root-forbidden
+    role: Lite edition migration (created with supabase migration new) of the same two tables, forced row level security for app_be, and the pg_cron tick of the retention queue.
+    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.
@@ -325,24 +622,26 @@ 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 SSE door by owner decision 2026-10-24, ruling:R212/case-5): 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 GraphQL subscription door, ruling:R212/case-7 and owner:lite-graphql-subscription-door): the same ports, doors and rules; it scales horizontally and stateless.
 liteAdapter:
   summary: >-
-    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
+    Under lite the realtime pattern is the full one with its three doors: the SSE controller of be.feature.realtime.sse
+    (transport/sse/<channel>.controller.ts, the default for one-way push), the socket.io gateway of be.feature.realtime.websocket
+    (transport/websocket/<channel>.gateway.ts) or the GraphQL subscription of be.feature.realtime.graphql (restricted, BE-REALTIME-6) runs inside the be api process. One replica or a test runs the memory hub (its bounded replay buffer and the socket.io
+    default adapter); replicas > 1 run the Redis hub and the sharded @socket.io/redis-adapter when Redis is declared, else the Postgres hub
+    (LISTEN/NOTIFY and the bounded realtime_events table) and @socket.io/postgres-adapter, websocket only, with no sticky sessions (BE-REALTIME-7). 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.
+    principal-scoped topic as text/event-stream, the gateway emits to the principal-scoped room of the namespace and the subscription resolver
+    returns the hub stream of the principal-scoped topic. The front end listens through a useSubscribe<Channel>Swr hook over modules/api/sse
+    (a reader of the transport client layer with the bearer token) or hooks/socketio (knowledge/patterns/fe/realtime.yaml). graphql-ws
+    has no replay, so a screen on the subscription refetches its snapshot on reconnect. The memory hub serves tests and one replica; with more than one api replica the hub is the Redis hub when Redis is declared, else the Postgres hub (stateless, no sticky sessions; BE-REALTIME-7).
   ports:
-    - {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.publish (platform/realtime), adapter: "the memory hub (one replica, tests) retains the frame (bounded) in the api process; the Postgres hub (replicas > 1) writes the realtime_events row and NOTIFYs, every replica hands it to its open SSE streams; the socket.io server emits to the namespace room of the topic, across replicas through @socket.io/postgres-adapter (websocket only)"}
     - {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]
+  forbids: []
   proof: >-
     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]
+  see: [knowledge/patterns/fe/realtime.yaml]

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

@@ -147,7 +147,7 @@ files:
     optional: true
   - path: src/modules/platform/saga/
     slot: be.platform
-    role: 'The shared store: `saga_states` (status and version fence) and the event claims, with the state machine in `saga.service.ts` — a measured file of a `coverage: required` slot, held at 100 per file with its spec beside it.'
+    role: 'The fenced `saga_states` store and the state machine in `saga.service.ts`, which claims deliveries through the shared `platform/inbox` port (BE-IDEMPOTENCY-2). The service is a measured file of a `coverage: required` slot, held at 100 per file with its spec beside it.'
     rules: [R170, R80]
     optional: true
   - path: src/tests/e2e/<area>/<name>.e2e-spec.ts
@@ -275,4 +275,4 @@ liteAdapter:
     The orchestrator's unit spec (<saga>.saga.service.spec.ts) as full; declaring saga requires integration specs titled
     `saga/<scenario>: ...` for every declared scenario on `starci supabase start` (R284), including each compensation path with
     failure injection and the final state read back. The e2e world of R173 remains full-only.
-  see: [knowledge/patterns/be/supabase-queues.yaml]
+  see: [knowledge/patterns/be/event-bus.yaml]

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.