@starci/hfs 4.7.32 → 4.7.34

package/runtime/knowledge/patterns/be/event-bus.yaml

@@ -5,7 +5,7 @@ purpose: |-
   Given a fact another context or a background process must react to, how does it travel? Work inside ONE context stays
   synchronous: the handler calls that context's domain service in one transaction and no event exists. An event exists only to
   cross contexts or to trigger asynchronous work (jobs, sagas, reactors, projections). It is a typed event class, published with
-  `eventBus.publish(event, tx)` by a domain service inside its transaction, and travels one durable path: transactional outbox,
+  `eventBus.publish(event, tx, correlationId)` by a domain service inside its transaction, and travels one durable path: transactional outbox,
   relay, Kafka, consumer with retry and dead letter. `platform/event-bus` is the one owner and the only importer of `kafkajs`.
 appliesTo:
   - backend
@@ -15,12 +15,12 @@ family: be
 slots: [be.transport.message, be.feature.reactors, be.events, be.platform.event-bus]
 pattern: event-bus
 provenance:
-  reviewedAt: 2026-10-02
+  reviewedAt: 2026-10-24
   sources:
     - knowledge/hfs/README.md
     - knowledge/hfs/slots.yaml
     - knowledge/hfs/rules.yaml
-    - owner decision 2026-10-02 (Kafka only, transactional outbox, typed event classes, publish(event, tx))
+    - owner decision 2026-10-02 (Kafka only, transactional outbox, typed event classes)
     - https://microservices.io/patterns/data/transactional-outbox.html
   limitations: |-
     Static checks prove who may publish, with which transaction, and that a consumer is a named door that forwards the event
@@ -85,19 +85,24 @@ rules:
     kind: mandatory
     hfsRules: [R152, R90, R87]
     requirement: |-
-      `eventBus.publish(event, tx)` is called only in `modules/domain`, with the manager of the transaction that makes the
-      domain change (`this.entityManager.transaction(async (manager) => { ...; await this.eventBus.publish(event, manager) })`).
+      `eventBus.publish(event, tx, correlationId)` is called only in `modules/domain`, with the manager of the transaction that makes the
+      domain change (`this.entityManager.transaction(async (manager) => { ...; await this.eventBus.publish(event, manager, request.correlationId) })`).
       It writes a row in the outbox table of that transaction's connection; the relay hands committed rows to Kafka (topic
       `events.<service>`, key = aggregate id) and marks them sent. `kafkajs` is imported only by `platform/event-bus`. Nest's
       `EventBus`, `@EventsHandler`, `@OnEvent` and `EventEmitter2` do not exist, and nothing publishes to Kafka directly.
       There is no in-process or local transport: unit specs use a recording fake of the `EventBus` port, allowed in `*.spec.ts`.
+      The explicit id is validated before SQL and stored in the outbox's `correlation_id` column and envelope
+      `metadata.correlationId`, following BE-LOGGING-4. The relay makes the row's `correlation_id` authoritative in outbound metadata.
+      A broker envelope whose metadata is genuinely absent may derive its root from a bounded, safe stable event id only
+      when its event name and payload have the basic envelope shape. That delivery is promoted to explicit metadata before
+      consumer execution, retry or dead-letter publication. Present malformed metadata is rejected.
     rationale: |-
       The outbox row commits with the domain change, so a rolled-back change never emits and a committed one is never lost;
       Kafka then gives ordered, replayable, cross-service delivery.
     cases:
       - id: case-1
         when: A domain service places an order
-        write: 'await this.entityManager.transaction(async (manager) => { await manager.save(...); await this.eventBus.publish(OrderPlacedEvent.create({ ... }), manager) })'
+        write: 'await this.entityManager.transaction(async (manager) => { await manager.save(...); await this.eventBus.publish(OrderPlacedEvent.create({ ... }), manager, request.correlationId) })'
     verification:
       automated:
         - BE_OUTBOX_WRITE_TX
@@ -112,7 +117,7 @@ rules:
     hfsRules: [R153, R80]
     requirement: |-
       A consumer is `transport/message/<event>.consumer.ts` implementing `EventConsumer<E>` with `readonly event = <Event>Event`;
-      `handle(delivery)` dispatches one command and forwards `delivery.eventId`. Delivery is at least once: the domain service the
+      `handle(delivery)` dispatches one command and forwards `delivery.eventId` and `delivery.correlationId`. Delivery is at least once: the domain service the
       command reaches claims the event id in `platform/inbox` as its first awaited expression, inside its own transaction, so a
       redelivery is a no-op. A throw schedules a retry with exponential backoff on the retry topic (`events.<service>.retry`);
       after the event's `attempts` the message goes to the dead-letter topic (`events.<service>.dlq`), which an operator reads
@@ -124,7 +129,7 @@ rules:
     cases:
       - id: case-1
         when: A consumer of order.placed
-        write: 'order-placed.consumer.ts: handle(delivery) { await this.commandBus.execute(new IssueInvoiceCommand({ request: { eventId: delivery.eventId, ... } })) }'
+        write: 'order-placed.consumer.ts: handle(delivery) { await this.commandBus.execute(new IssueInvoiceCommand({ request: { eventId: delivery.eventId, correlationId: delivery.correlationId, ... } })) }'
     verification:
       automated:
         - BE_EVENT_CONSUMER_SHAPE
@@ -283,12 +288,15 @@ files:
     role: "The consumed event's e2e flow; titles event-bus/<scenario>: ... prove the pattern."
     spec: event-bus/atomic-with-transaction, event-bus/relay-only-after-commit, event-bus/redelivery-then-dead-letter, event-bus/duplicate-delivery-is-a-noop
     rules: [BE_PATTERN_SPEC_MISSING]
-# Edition lite (R212, owner ruling 2026-10-14): the same ports and rules, a Supabase adapter behind them.
+# Edition lite (R212): the same ports and rules, a Supabase adapter behind them. ruling:R212/case-10 moved the lite queue to Redis
+# because full's queue is Redis; full's event bus is Kafka, so the lite event-bus adapter below is unchanged by that ruling.
 liteAdapter:
   summary: >-
-    Under lite the event bus keeps typed events, the vendored contract, publish(event, tx) in the domain transaction, the outbox,
+    Under lite the event bus keeps typed events, the vendored contract, publish(event, tx, correlationId) in the domain transaction, the outbox,
     the inbox and thin consumers; Kafka is replaced by pgmq-backed topics, or by in-process delivery after commit for a back end
-    with a single api app.
+    with a single api app. Each consumer group of a topic has its own pgmq queue `<service>__<event>__<group>`, created by a
+    supabase migration, named by a literal `<GROUP>_TOPIC_QUEUE` constant under platform/event-bus (its owner, R258) and
+    granted only to the application role, so each group keeps its own cursor and dead letter.
   ports:
     - {port: EventPublisher (platform/event-bus), adapter: the same outbox row in the domain transaction}
     - {port: relay, adapter: "fans each committed event out with pgmq.send to one queue per consumer group of its topic, marking the row in the same transaction"}
@@ -297,4 +305,3 @@ liteAdapter:
   proof: >-
     Unit specs as full; declaring event-bus requires integration specs titled `event-bus/<scenario>: ...` for every declared
     scenario on `starci supabase start` (R284). Lite has no e2e world.
-  see: [knowledge/patterns/be/supabase-queues.yaml]

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

@@ -0,0 +1,265 @@
+schema: starci/knowledge-source@1
+id: be.idempotency
+title: Inbox dedupe and client operation receipts
+purpose: |-
+  Given a door a delivery can repeat through - a signed webhook, a queue message, a relayed outbox row - how does the receiver
+  make a repeat a no-op instead of a second charge, a second email or a second state transition? One inbox table keyed by
+  (source, event id) sits in front of every such door, reached through `InjectInbox()`. Effectful client commands use the
+  same owner to bind a key to the request fingerprint and replay the committed outcome.
+appliesTo:
+  - backend
+family: be
+# The slot ids this topic teaches (knowledge/hfs/slots.yaml); scripts/gates/read-digest.mjs inverts these
+# into the READ-step slot -> pattern-topic map (knowledge/op-gate.yaml kinds), each slot's topics in index.yaml order.
+slots: [be.transport.message, be.feature.reactors, be.integrations, be.feature.application, be.transport.graphql, be.transport.http, be.platform]
+pattern: idempotency
+provenance:
+  reviewedAt: 2026-10-24
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - knowledge/hfs/rules.yaml
+    - owner-locked BE convention 2026-09-30
+    - knowledge/patterns/be/persistence.yaml
+    - owner decision 2026-10-24 (effectful client commands require marker and lint)
+    - https://www.postgresql.org/docs/16/sql-insert.html (read 2026-10-24)
+    - https://www.postgresql.org/docs/16/transaction-iso.html (read 2026-10-24)
+    - https://raw.githubusercontent.com/typeorm/typeorm/0.3.31/src/driver/postgres/PostgresQueryRunner.ts (read 2026-10-24)
+  limitations: |-
+    Static checks judge the delivery entry of the service a thin door calls: the genuine Inbox receiver, the first await,
+    and the return on false. For a sole returned or awaited EntityManager transaction, they also inspect its actual inline
+    callback, require the claim in its first statement, and bind the claim's manager to that callback's parameter.
+    They do not prove getter effects, called helpers, database rollback or broker delivery; service specs and the real test world
+    prove failure and redelivery behaviour. Non-inline callbacks and dynamic isolation expressions are not static proof here.
+    The client rule checks the marked command contract, transport key validation and the handler's resolved domain delegation
+    into a transaction-owned runClient call. Whether an operation has effects, its fingerprint covers all request meaning,
+    and its remote effects are separately protected remain design review and behavioral proof obligations.
+rules:
+  - id: BE-IDEMPOTENCY-1
+    title: The delivery service claims the event before it acts
+    kind: mandatory
+    hfsRules: [R80, R85]
+    requirement: |-
+      A consumer (`transport/message/<event>.consumer.ts`) is a thin door that forwards the delivery's `eventId` through one
+      command to the domain service. A signed webhook verifies first and calls one domain method that durably records the
+      inbox receipt and outbox event; only a reactor or job dispatches its processing command after commit (webhooks.yaml).
+      A public delivery method
+      of that service (its first parameter carries `eventId`) takes `@InjectInbox() private readonly inbox: Inbox`, claims
+      `(source, eventId)` first and returns when the claim answers `false`. When the service owns an EntityManager transaction,
+      the first awaited work in the transaction callback is `this.inbox.claim(source, eventId, manager)`, with that callback's
+      own manager. The claim, domain writes and outbox rows commit or roll back together; never move the claim to the shared
+      manager outside the transaction to satisfy a static check. A duplicate return ends the callback and no outer delivery
+      work follows it. `source` names the provider or publisher; `eventId` comes from the delivery and is never generated by
+      the receiver. The rule identifies the Inbox and EntityManager by their declared type origins, not variable names.
+      An outbox relay that only produces is not a delivery service and is not asked for a claim.
+    rationale: |-
+      A sender that gets no timely reply resends: a payment provider retries a webhook, a queue redelivers a message it never
+      saw acknowledged. Identifying the receiver by type removes the keyword match a renamed variable could satisfy.
+    cases:
+      - id: case-1
+        when: A signed webhook controller
+        write: 'the webhook door (webhooks.yaml) verifies the signature and calls one domain recording intake; that method claims (PAYOS_SOURCE, eventId) first in its transaction, returns when the claim answers false, and saves the durable receipt with its outbox event. A reactor or job consumes the committed receipt and dispatches the processing command; the webhook door, HTTP module and called intake never dispatch on a command bus.'
+      - id: case-2
+        when: A consumer
+        write: 'be/src/features/api/billing/transport/message/payment-captured.consumer.ts forwards delivery.eventId in one command; its domain service claims first inside its own transaction with the callback manager, then writes and publishes through that manager.'
+    verification:
+      automated:
+        - BE_INBOX_DEDUPE_MISSING
+        - BE_RAW_INJECT
+      manual:
+        - Trace that the claim executes on every path before the side effect, including an early return added later.
+    relatedExamples: []
+  - id: BE-IDEMPOTENCY-2
+    title: The inbox is one table, owned by platform, shared by every door
+    kind: mandatory
+    hfsRules: [R80, R35, R34]
+    requirement: |-
+      `platform/inbox` owns one table, `inbox_claims(source varchar(200), event_id varchar(200),
+      claimed_at timestamptz not null, request_fingerprint varchar(64) null, outcome jsonb null)`, with a composite primary key on `(source, event_id)`, created by a migration under
+      `platform/inbox/persistence/migrations/`. `Inbox.claim(source, eventId, tx?)` inserts atomically on the supplied
+      transaction manager, or on the configured manager when no caller transaction is supplied. A conflict-safe insert
+      (`ON CONFLICT (source, event_id) DO NOTHING RETURNING event_id`) returns `true` for a new row and `false` for a
+      duplicate without aborting the caller's transaction. It never reads first and writes after, which races two concurrent
+      deliveries of the same event. Lite uses its existing `public.inbox` table with the same client receipt columns,
+      owned by a forward-only Supabase migration. A client receipt extends this table; no capability creates another
+      dedupe table or unique request-key constraint to compete with it.
+    rationale: |-
+      One shared table with one owner keeps the guarantee "this (source, event id) claims at most once" in one place, and
+      the atomic conflict-safe insert makes the claim safe under concurrent delivery and keeps a duplicate transaction usable.
+    cases:
+      - id: case-1
+        when: The migration
+        write: 'The platform inbox migration creates inbox_claims with PRIMARY KEY (source, event_id); its client-operation migration adds request_fingerprint and outcome to that same table.'
+      - id: case-2
+        when: The adapter
+        write: 'async claim(source, eventId, tx?) { const manager = tx ?? this.managers[0]; const rows = await manager.query(CLAIM_EVENT, [source, eventId, this.clock.now()]); return rows.length > 0 } // CLAIM_EVENT is the conflict-safe insert in the inbox owner persistence file.'
+    verification:
+      automated:
+        - BE_INBOX_DEDUPE_MISSING
+        - BE_SCHEMA_OWNER
+        - BE_SCHEMA_AUTHORITY
+      manual:
+        - Confirm no capability declares a second inbox-shaped table instead of using this one.
+    relatedExamples: [idempotency]
+  - id: BE-IDEMPOTENCY-3
+    title: Effectful client commands require a key and replay their committed outcome
+    kind: mandatory
+    hfsRules: [R310, R155, R83, R87]
+    requirement: |-
+      Mark every command that initiates an effectful client operation with the `Effectful()` decorator exported by
+      `platform/inbox` (deciding that a command is effectful is a design-review judgment: R310 judges the commands that carry
+      the marker, it cannot find one that lacks it, and an app that never marks a command declares no idempotency
+      pattern). Its request carries a required string `idempotencyKey`. GraphQL accepts a required input field;
+      REST maps `Idempotency-Key` through a validated input. Validate the key with `IsUUID()` or with `IsString()`,
+      `MinLength(1)` and `MaxLength(64)`. The client retains one key across retries of one intended operation and uses a new
+      key for a new intent. Internal delivery commands retain the delivery identity of BE-IDEMPOTENCY-1.
+      The thin handler forwards the key to one domain service. That service returns its EntityManager transaction,
+      whose callback returns `inbox.runClient({ principalId, operation, idempotencyKey, request }, manager, effect)`.
+      The principal comes from verified authentication; the operation is a stable operation name. `request` contains every
+      business input that changes the meaning of the operation, excluding the key. Inbox canonicalizes the JSON object
+      keys and hashes the request, then atomically claims `(source = client:<principalId>:<operation>, event_id = key)`
+      through that callback manager. A matching repeat returns the stored complete outcome, including a domain refusal,
+      without invoking `effect`; a different fingerprint throws `IDEMPOTENCY_KEY_REUSED`, mapped to a conflict.
+      The claim, effect's local writes and outbox rows, and JSON outcome commit together. An exception rolls them all back.
+      The outcome is JSON data; undefined, non-finite numbers and non-JSON objects are refused. A concurrent claimant waits
+      for the first transaction and replays its committed outcome or claims after its rollback. External calls use an
+      outbox or their provider's supported idempotency contract; the local receipt does not prove remote deduplication.
+      The domain owns the transaction (BE-PERSISTENCE-10); no interceptor owns a claim or transaction.
+      A scheduled fenced job sweeps completed client receipts in bounded batches after the configured retention window
+      measured from their first claim.
+      Delivery claims are preserved. A key may identify a new intent after its receipt is swept, so clients must keep
+      retries within the advertised retention window. Declare `idempotency` in `hfs.json` `sides.be.patterns` and prove
+      `idempotency/repeat-returns-same-outcome` and `idempotency/reused-key-other-body-is-refused` on real Postgres through
+      the full test world or lite's local integration lane.
+    rationale: |-
+      A timeout leaves a client unsure whether a mutation committed. The receipt binds the caller's intent to its durable
+      result while a request fingerprint prevents the same key from silently authorizing different work.
+    cases:
+      - id: case-1
+        when: Checkout adds a cart item
+        write: 'Mark AddCartItemCommand with Effectful(); forward its validated key and fingerprint { productId, quantity } to runClient inside the checkout transaction, and return the stored Outcome on retry.'
+      - id: case-2
+        when: A transaction fails before commit
+        write: 'Let the exception escape the transaction; the receipt and mutation roll back together so the same key can retry.'
+      - id: case-3
+        when: Retention expires
+        write: 'A FencedProcessor delegates to the inbox retention domain service; the inbox owner deletes only completed client receipts older than the configured window in a bounded batch.'
+    verification:
+      automated:
+        - BE_MUTATION_IDEMPOTENT
+        - BE_PATTERN_SPEC_MISSING
+        - BE_UNNAMED_DATA_ACCESS
+        - BE_CQRS_SHAPE
+        - BE_READONLY_BOUNDARY
+      manual:
+        - Review the effectful designation, authenticated principal, operation identity, complete request meaning and JSON outcome.
+        - Exercise simultaneous identical requests, rollback and a changed body under the same key on the real database.
+        - Confirm retention and provider recovery behavior match the advertised client contract.
+    relatedExamples: [idempotency]
+files:
+  - path: src/modules/platform/idempotency/index.ts
+    slot: be.platform
+    template: idempotency/platform/idempotency/index.ts.tpl
+  - path: src/modules/platform/idempotency/errors/idempotency.error.ts
+    slot: be.platform
+    template: idempotency/platform/idempotency/errors/idempotency.error.ts.tpl
+  - path: src/modules/platform/idempotency/messages/idempotency.messages.ts
+    slot: be.domain.messages
+    template: idempotency/platform/idempotency/messages/idempotency.messages.ts.tpl
+  - path: src/modules/platform/inbox/index.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/index.ts.tpl
+  - path: src/modules/platform/inbox/inbox.port.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/inbox.port.ts.tpl
+  - path: src/modules/platform/inbox/inbox.decorators.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/inbox.decorators.ts.tpl
+  - path: src/modules/platform/inbox/effectful.decorators.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/effectful.decorators.ts.tpl
+  - path: src/modules/platform/inbox/inbox.options.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/inbox.options.ts.tpl
+  - path: src/modules/platform/inbox/inbox.module-definition.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/inbox.module-definition.ts.tpl
+  - path: src/modules/platform/inbox/inbox.module.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/inbox.module.ts.tpl
+  - path: src/modules/platform/inbox/inbox.service.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/inbox.service.ts.tpl
+  - path: src/modules/platform/inbox/inbox.service.spec.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/inbox.service.spec.ts.tpl
+  - path: src/modules/platform/inbox/request-fingerprint.policy.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/request-fingerprint.policy.ts.tpl
+  - path: src/modules/platform/inbox/request-fingerprint.policy.spec.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/request-fingerprint.policy.spec.ts.tpl
+  - path: src/modules/platform/inbox/client-operation.policy.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/client-operation.policy.ts.tpl
+  - path: src/modules/platform/inbox/client-operation.policy.spec.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/client-operation.policy.spec.ts.tpl
+  - path: src/modules/platform/inbox/errors/inbox.error.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/errors/inbox.error.ts.tpl
+  - path: src/modules/platform/inbox/messages/inbox.messages.ts
+    slot: be.domain.messages
+    template: idempotency/platform/inbox/messages/inbox.messages.ts.tpl
+  - path: src/modules/platform/inbox/persistence/connection.ts
+    slot: be.persistence
+    template: idempotency/platform/inbox/persistence/connection.ts.tpl
+  - path: src/modules/platform/inbox/persistence/inbox.sql.ts
+    slot: be.persistence
+    template: idempotency/platform/inbox/persistence/inbox.sql.ts.tpl
+  - path: src/modules/platform/inbox/persistence/inbox.rows.ts
+    slot: be.persistence
+    template: idempotency/platform/inbox/persistence/inbox.rows.ts.tpl
+  - path: src/modules/platform/inbox/client-outcome-backfill.client.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/client-outcome-backfill.client.ts.tpl
+  - path: src/modules/platform/inbox/client-outcome-backfill.client.spec.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/client-outcome-backfill.client.spec.ts.tpl
+  - path: src/modules/platform/inbox/delivery-claim-backfill.client.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/delivery-claim-backfill.client.ts.tpl
+  - path: src/modules/platform/inbox/delivery-claim-backfill.client.spec.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/delivery-claim-backfill.client.spec.ts.tpl
+  - path: src/modules/platform/inbox/delivery-claim-release.client.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/delivery-claim-release.client.ts.tpl
+  - path: src/modules/platform/inbox/delivery-claim-release.client.spec.ts
+    slot: be.platform
+    template: idempotency/platform/inbox/delivery-claim-release.client.spec.ts.tpl
+  - path: src/modules/platform/inbox/persistence/entities/inbox-claim.entity.ts
+    slot: be.persistence
+    template: idempotency/platform/inbox/persistence/entities/inbox-claim.entity.ts.tpl
+  - path: src/modules/platform/inbox/persistence/migrations/1789800005000-create-inbox-claims.ts
+    slot: be.persistence
+    template: idempotency/platform/inbox/persistence/migrations/1789800005000-create-inbox-claims.ts.tpl
+  - path: src/modules/platform/inbox/persistence/migrations/1792800000000-client-operation-outcomes.ts
+    slot: be.persistence
+    template: idempotency/platform/inbox/persistence/migrations/1792800000000-client-operation-outcomes.ts.tpl
+liteAdapter:
+  summary: >-
+    Lite keeps the Inbox port and transaction-owned client receipt API. Its existing public.inbox
+    table uses Supabase migration authority; the be/inbox platform templates carry the lite adapter and the
+    platform/client-operation-outcomes.sql.tpl forward migration. The files tree above describes the full TypeORM adapter.
+    Delivery-only webhook scaffolds do not install a client marker. When adopting this client pattern, add the shared
+    idempotency/platform/inbox/effectful.decorators.ts.tpl as src/modules/platform/inbox/effectful.decorators.ts and
+    export Effectful from the inbox barrel. Every effectful client command then uses that marker and declares the
+    idempotency pattern with its required proof scenarios.
+  ports:
+    - {port: Inbox, adapter: PostgresInbox through the caller's active EntityManager transaction}
+    - {port: receipt retention, adapter: a fenced job delivered by the BullMQ queue on the declared Redis and scheduled by a pg_cron tick that enqueues through the queue outbox}
+  proof: >-
+    The same inbox and fingerprint unit specs apply; declaring idempotency requires both client receipt scenarios in
+    lite's local Supabase integration lane.
+  see: [knowledge/patterns/be/queues.yaml]

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

@@ -14,7 +14,7 @@ family: be
 slots: [be.feature.jobs, be.feature.jobs.steps, be.platform.jobs]
 pattern: fenced-job
 provenance:
-  reviewedAt: 2026-10-02
+  reviewedAt: 2026-10-24
   sources:
     - knowledge/hfs/README.md
     - knowledge/hfs/slots.yaml
@@ -40,13 +40,15 @@ rules:
       delivery (the job key is the BullMQ job id), then `process`, then the guarded `complete`. Nothing else writes the row: no
       `manager.update`, `increment`, `save`, `insert`, `delete` or query-builder write on the job entity outside `platform/jobs`. The table
       exists on every connection that runs jobs.
+      `ClaimParams.correlationId` comes from the queue delivery and is carried into `ClaimedJob.correlationId` for the processor
+      and steps. It keeps the delivery identity across claims, independently of the fencing token and provider run key.
     rationale: |-
       A read-modify-write claim races, and a second writer defeats the fence. One owner and one atomic statement keep the token
       monotonic.
     cases:
       - id: case-1
         when: A worker picks up a job
-        write: 'const job = await this.claims.claim({ kind: "send-receipt", jobKey: delivery.id, payload, workerId, leaseMs })  // token = previous + 1'
+        write: 'const job = await this.claims.claim({ kind: "send-receipt", jobKey: delivery.id, correlationId: delivery.correlationId, payload: delivery.payload, workerId, leaseMs })  // token = previous + 1'
     verification:
       automated:
         - BE_JOB_WRITE_OUTSIDE_OWNER
@@ -81,7 +83,7 @@ rules:
     hfsRules: [R159]
     requirement: |-
       `JobClaims.runKey(job, step)` returns a `RunKey` (`<jobId>:<step>:<fencingToken>`); it is the only way to make one. The step's
-      one delegating call hands the payload as delivered and the run key to the module service that owns the effect, and every
+      one delegating call hands the payload as delivered, the run key and `job.correlationId` to the module service that owns the effect, and every
       call that reaches an integration passes the key as the provider's idempotency key, so a repeated effect of a stale
       worker is dropped by the provider. A read from an integration belongs in the application layer, not in a step. When the
       provider cannot enforce idempotency, constrain overlap and reconcile before a retry.
@@ -89,8 +91,8 @@ rules:
       Fencing the local row does not fence the remote effect. The key ties the effect to one claim.
     cases:
       - id: case-1
-        when: A step sends a mail
-        write: 'await this.mail.send(message, this.claims.runKey(job, "send"))'
+        when: A step archives a receipt
+        write: 'await this.receipts.archiveReceipt(job.payload, this.claims.runKey(job, "store"), job.correlationId)'
     verification:
       automated:
         - BE_JOB_RUN_KEY
@@ -106,7 +108,7 @@ rules:
       settles through the guarded writes); `steps/<step>.step.ts` declares a class implementing `JobStep`; `application/` holds
       plain CQRS. The processor and every step are thin feature files (R203 `BE_FEATURE_THIN`): they map the claimed job and
       delegate into `modules/`; the claim, the fence, the settle and the retry live in `platform/jobs`. A domain service starts
-      the job with a typed queue producer `enqueueX(payload, tx)` inside its transaction
+      the job with a typed queue producer `enqueueX(payload, tx, correlationId)` inside its transaction
       (queues.yaml). The jobs kind imports only `modules/*`: it never imports an api, saga or reactor feature, and it talks to
       them through events. An app of kind `worker` or `api` composes the job queue module.
     rationale: |-
@@ -169,7 +171,7 @@ files:
     template: jobs/platform/jobs.decorators.ts.tpl
   - path: src/modules/platform/jobs/jobs.contracts.ts
     slot: be.platform.jobs
-    role: "ClaimedJob, GuardedWrite (the token is required), RunKey."
+    role: "ClaimedJob with the delivery correlationId, GuardedWrite (the token is required), RunKey."
     template: jobs/platform/jobs.contracts.ts.tpl
   - path: src/modules/platform/jobs/jobs.port.ts
     slot: be.platform.jobs
@@ -259,7 +261,7 @@ files:
   - path: src/features/jobs/<job>/steps/<step>.step.ts
     slot: be.feature.jobs.steps
     template: jobs/job.step.ts.tpl
-    role: 'One external effect; implements JobStep — thin (R203 `BE_FEATURE_THIN`): the fence call first, then one delegating call that hands the payload and the run key to a service of the modules; the payload guards live there.'
+    role: 'One external effect; implements JobStep — thin (R203 `BE_FEATURE_THIN`): the fence call first, then one delegating call that hands the payload, the run key and correlationId to a service of the modules; the payload guards live there.'
     rules: [BE_JOB_SHAPE, BE_JOB_RUN_KEY]
   - path: src/features/jobs/<job>/application/<action>.command.ts
     slot: be.feature.application
@@ -279,11 +281,14 @@ files:
 liteAdapter:
   summary: >-
     Under lite a fenced job is unchanged: the job row with its fencing token, the atomic claim, guarded writes and run keys. The
-    row's table is a supabase migration, and the processor is fed by the lite queue (pgmq).
+    row's table is a supabase migration, and the processor is fed by full's BullMQ queue on the declared Redis, so a lite app
+    that declares fenced-job declares `backing: [redis]`. Without a declared Redis a lite app has no fenced job; a long task is
+    a declared replicated-job running a cli command.
   ports:
     - {port: job claim (platform/jobs), adapter: "the same claim SQL through the shared EntityManager; the table comes from supabase/migrations"}
-    - {port: processor delivery, adapter: "the lite queue worker (pgmq.read, visibility timeout, archive on dead letter)"}
+    - {port: processor delivery, adapter: "full's BullMQ worker (attempts and exponential backoff from the queue policy, failed jobs kept as the dead letter)"}
   proof: >-
     Unit specs as full (job-claim.service.spec.ts); declaring fenced-job requires integration specs titled
-    `fenced-job/<scenario>: ...` for every declared scenario on `starci supabase start` (R284).
-  see: [knowledge/patterns/be/supabase-queues.yaml]
+    `fenced-job/<scenario>: ...` for every declared scenario on the local Supabase stack (R284, which runs no container of its
+    own): the claim, the fencing token and the guarded writes are Postgres facts, driven there by the real runner without BullMQ.
+  see: [knowledge/patterns/be/queues.yaml]

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

@@ -181,10 +181,10 @@ liteAdapter:
   summary: >-
     Under lite a projection is unchanged in behaviour (only it writes its table, recompute is idempotent and replayable, readers
     use get*); its table is a supabase migration with a rows type, so the slot carries no projection entity (be.projections lite
-    overlay), and it is kept current by a reactor or a job on the lite transport.
+    overlay), and it is kept current by a reactor on the lite event bus or by a job on the queue (BullMQ on the declared Redis).
   ports:
     - {port: read model table, adapter: "a supabase migration plus <name>.sql.ts and <name>.rows.ts under persistence/"}
   proof: >-
     Unit specs as full (the projection is a logic role at 100 per file); declaring projection requires integration specs titled
     `projection/<scenario>: ...` for every declared scenario on `starci supabase start` (R284).
-  see: [knowledge/patterns/be/supabase-queues.yaml]
+  see: [knowledge/patterns/be/event-bus.yaml, knowledge/patterns/be/queues.yaml]

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

@@ -3,7 +3,7 @@ id: be.queues
 title: Queues and schedulers
 purpose: |-
   Given work that must run later, in the background or on a schedule, how is it started? It is a job of a typed queue:
-  `modules/queues/<queue>/<queue>.queue.ts` is the producer (`enqueueX(payload, tx)` writes the outbox in the caller's
+  `modules/queues/<queue>/<queue>.queue.ts` is the producer (`enqueueX(payload, tx, correlationId)` writes the outbox in the caller's
   transaction), `platform/queue` relays committed rows to BullMQ (the job id is the outbox id, so a relay retry never duplicates
   a job), and a `features/jobs/<job>/<job>.processor.ts` runs it. A schedule is a BullMQ job scheduler declared beside the
   producer; `@Cron`, `@Interval` and `@Timeout` do not exist.
@@ -15,12 +15,13 @@ family: be
 slots: [be.feature.jobs, be.queues, be.platform.queue]
 pattern: queue
 provenance:
-  reviewedAt: 2026-10-02
+  reviewedAt: 2026-10-24
   sources:
     - knowledge/hfs/README.md
     - knowledge/hfs/slots.yaml
     - knowledge/hfs/rules.yaml
     - owner decision 2026-10-02 (BullMQ queues with a transactional outbox, schedulers replace cron)
+    - ruling:R212/case-10 (2026-10-24; the queue is Redis in both editions, lite declares its Redis)
     - https://docs.bullmq.io/guide/job-schedulers
   limitations: |-
     Static checks prove who enqueues, with which transaction, and that nothing imports BullMQ or Nest scheduling outside the
@@ -33,17 +34,18 @@ rules:
     hfsRules: [R152, R154]
     requirement: |-
       Each queue is a folder `be/src/modules/queues/<queue>/` with `<queue>.queue.ts` (a class whose methods are the typed
-      producers `enqueueX(payload, tx: EntityManager)`), optional `<queue>.contracts.ts` (payload types and the queue name) and
-      `index.ts`. A producer writes the `QueueOutbox` port of `platform/queue` with its own `tx` as the first argument. A producer
+      producers `enqueueX(payload, tx: EntityManager, correlationId: string)`), optional `<queue>.contracts.ts` (payload types and the queue name) and
+      `index.ts`. A producer calls `QueueOutbox.write(tx, queue, payload, correlationId)` in `platform/queue`. A producer
       is called only by a domain service, inside its transaction (the same rule as `eventBus.publish`). Work inside one context
       that must happen now is a direct call, not a job.
+      Current outbox writes validate the explicit correlation id before issuing SQL.
     rationale: |-
       The job row commits with the change that caused it, so a rolled-back change never starts work and a committed one is never
       lost.
     cases:
       - id: case-1
         when: A domain service must send a receipt after payment
-        write: 'await this.entityManager.transaction(async (manager) => { await manager.save(...); await this.receiptQueue.enqueueSendReceipt({ orderId }, manager) })'
+        write: 'await this.entityManager.transaction(async (manager) => { await manager.save(...); await this.receiptQueue.enqueueSendReceipt({ orderId }, manager, request.correlationId) })'
     verification:
       automated:
         - BE_OUTBOX_WRITE_TX
@@ -60,34 +62,47 @@ rules:
       registered connection and adds each job with `jobId = <outbox id>`; BullMQ ignores a second add of the same id, so a relay
       that crashes after adding and before marking the row sent re-adds harmlessly. Nothing else constructs a `Queue`, `Worker`
       or `FlowProducer`.
+      The row's explicit `correlationId` travels in the job envelope and `QueueDelivery`, following BE-LOGGING-4.
+      BullMQ envelopes carry the owned `schema: "starci/queue@1"` marker; enqueued jobs wrap the payload and explicit id.
+      Only the owned marker family is interpreted as transport data. Unmarked legacy objects remain whole business payloads,
+      including their `kind`, `schema` and `correlationId` fields.
     rationale: |-
       The relay is at least once; a deterministic job id turns it into effectively once.
     cases:
       - id: case-1
         when: The relay re-reads a row it already added
-        write: 'queue.add(name, payload, { jobId: row.id }) is a no-op for an id BullMQ already holds.'
+        write: 'transport.add(row.queue, row.id, row.payload, row.correlationId) preserves the outbox id and correlation id; the BullMQ adapter adds the envelope with jobId = row.id.'
     verification:
       automated:
         - BE_INFRA_OWNER
       manual: []
     relatedExamples: [queue]
   - id: BE-QUEUES-3
-    title: A schedule is a BullMQ job scheduler declared with its queue
+    title: A schedule is a BullMQ job scheduler declared with its queue, or a pg_cron tick that writes the outbox
     kind: mandatory
-    hfsRules: [R90]
+    hfsRules: [R90, R258]
     requirement: |-
       A recurring task is a job scheduler (`upsertJobScheduler`) that the queue module declares in its `schedulers` list and
-      `platform/queue` registers at boot; its job is processed by the same `features/jobs/<job>/<job>.processor.ts` as any
-      enqueued job. `@nestjs/schedule`, `@Cron`, `@Interval`, `@Timeout` and `setInterval` for work are not used anywhere.
+      `platform/queue` registers at boot, or, in an app on Supabase, a uniquely named pg_cron job of a migration whose command
+      (directly or through one `*_tick` function) only inserts one row of a queue constant into the queue outbox table of
+      `ruleParams.db.queueOutbox` (`public.queue`), which the relay hands to BullMQ; a tick has exactly one of the two owners. Its job is processed by the same
+      `features/jobs/<job>/<job>.processor.ts` as any enqueued job. `@nestjs/schedule`, `@Cron`, `@Interval`, `@Timeout` and
+      `setInterval` for work are not used anywhere.
     rationale: |-
-      One scheduler in Redis fires once for the whole deployment, where cron in a replicated process fires once per replica.
+      One scheduler in Redis, or one pg_cron job in the database, fires once for the whole deployment, where cron in a replicated
+      process fires once per replica.
     cases:
       - id: case-1
         when: Expire unpaid orders every five minutes
         write: 'order-expiry.queue.ts declares scheduler { every: 5 minutes } for the expire-orders job; the processor dispatches ExpireOrdersCommand.'
+      - id: case-2
+        when: A lite app on Supabase sends booking reminders every fifteen minutes
+        write: "A migration declares private.booking_reminder_tick() as one insert into public.queue (queue, payload, created_at) values ('booking_reminder', jsonb_build_object('tick', true), now()) and schedules it with cron.schedule('booking_reminder_tick', '*/15 * * * *', ...); the send-reminder processor is the queue's."
     verification:
       automated:
         - BE_INFRA_OWNER
+        - DB_PGMQ_DECLARED
+        - DB_CRON_OWNED
       manual:
         - Confirm the cadence and the job's idempotence.
     relatedExamples: [queue]
@@ -169,6 +184,13 @@ files:
   - path: src/modules/platform/queue/queue.log-events.ts
     slot: be.platform.queue
     template: queues/platform/queue.log-events.ts.tpl
+  - path: src/modules/platform/queue/errors/queue.error.ts
+    slot: be.platform.queue
+    role: "Malformed stored queue envelope failures."
+    template: queues/platform/errors/queue.error.ts.tpl
+  - path: src/modules/platform/queue/messages/queue.messages.ts
+    slot: be.domain.messages
+    template: queues/platform/messages/queue.messages.ts.tpl
   - path: src/modules/platform/queue/bullmq-queue-transport.client.ts
     slot: be.platform.queue
     role: "The one bullmq importer."
@@ -242,18 +264,31 @@ files:
     role: "Titles queue/<scenario>: ... prove the pattern."
     spec: queue/enqueue-atomic-with-transaction, queue/relay-job-id-is-outbox-id, queue/scheduler-fires-once
     rules: [BE_PATTERN_SPEC_MISSING]
-# Edition lite (R212, owner ruling 2026-10-14): the same ports and rules, a Supabase adapter behind them.
+# Edition lite (ruling:R212/case-10): the queue is BullMQ on Redis in both editions; only the outbox table's schema authority differs.
 liteAdapter:
   summary: >-
-    Under lite the queue pattern is unchanged above the port (producers, the outbox written in the caller's transaction, processors,
-    schedulers declared with their queue) and its transport is Supabase Queues (pgmq) instead of BullMQ and Redis.
+    Under lite the queue pattern is full's, adapter included: producers write the outbox in the caller's transaction, the relay
+    adds each committed row to BullMQ with the outbox id as the job id, BullMQ workers run the processors with the queue policy's
+    attempts and exponential backoff, and a job that exhausts its attempts stays in BullMQ's failed set (the dead letter). The
+    queue needs Redis: a lite app that declares queue or fenced-job declares `backing: [redis]` in hfs.json sides.be, and its
+    stack runs one Redis with AOF persistence (appendonly yes, appendfsync everysec) on a named volume. One difference from
+    full's adapter: the relay marks an outbox row sent only after the transport's persist step confirms Redis wrote the job to
+    its append-only file (WAITAOF) and still holds it, so a job Redis loses inside the at most one second fsync window leaves
+    its row waiting and is added again; that is why a lite queue does not lose a job. Without a declared Redis there is no queue
+    pattern: the work is a direct call inside the request, or a declared replicated-job running a cli command. Supabase Queues
+    (pgmq) is not a queue transport. `starci app add queue|job` writes this adapter in a lite app, with the outbox and job
+    tables as one supabase migration, the Redis declaration and the persisted Redis of every docker-swarm environment.
   ports:
-    - {port: QueueOutbox (platform/queue), adapter: the same outbox row written through the caller's tx; nothing changes}
-    - {port: queue transport (queue-transport.port.ts), adapter: "pgmq-queue-transport.client.ts: pgmq.send through the shared EntityManager, the outbox id inside the message"}
-    - {port: QueueWorkerRegistry (platform/queue), adapter: "a poll loop per queue: pgmq.read with the policy's visibility timeout, pgmq.delete on success, pgmq.set_vt for backoff, pgmq.archive when read_ct exceeds the attempts"}
-    - {port: schedulers, adapter: "a pg_cron job declared in a supabase migration that calls pgmq.send; no BullMQ job scheduler"}
-  forbids: [bullmq, "@nestjs/bullmq", redis, ioredis, "@nestjs/schedule"]
+    - {port: QueueOutbox (platform/queue), adapter: "full's outbox row written through the caller's tx; the table comes from a supabase migration (no TypeORM entity under lite)"}
+    - {port: queue transport (queue-transport.port.ts), adapter: "full's bullmq-queue-transport.client.ts over the declared Redis (host, port, db and the password read from its sealed secret file), plus persist(jobs): WAITAOF 1 0 on each queue's connection, then each job's state, refusing with QUEUE_NOT_PERSISTED or QUEUE_JOB_LOST (errors/queue.error.ts)"}
+    - {port: outbox relay (queue-relay.service.ts), adapter: "full's relay, which calls persist after the adds and before it marks the rows sent, so a refusal rolls the mark back and the next pass adds the rows again"}
+    - {port: QueueWorkerRegistry (platform/queue), adapter: "full's BullMQ worker per queue: attempts and exponential backoff from queue.policy.ts, failed jobs kept as the dead letter"}
+    - {port: schedulers, adapter: "a BullMQ job scheduler declared with its queue, as full, or a pg_cron job in a supabase migration whose tick inserts one row of the queue constant into the queue outbox"}
+  forbids: [kafkajs, "@nestjs/schedule"]
   proof: >-
-    Unit specs as full (queue-outbox, relay and worker services, the pgmq client against mockEntityManager); declaring queue
-    requires integration specs titled `queue/<scenario>: ...` for every declared scenario on `starci supabase start` (R284).
-  see: [knowledge/patterns/be/supabase-queues.yaml]
+    Unit specs as full (queue-outbox, relay and worker services, the BullMQ client against a mocked factory); declaring queue
+    requires integration specs titled `queue/<scenario>: ...` for every declared scenario on the local Supabase stack (R284,
+    which runs no container of its own): the outbox, its commit boundary, the relay identity and the pg_cron tick are Postgres
+    facts proved there with the real outbox writer and relay, and the queue transport records what the relay hands to BullMQ
+    (the job id is the outbox id). BullMQ itself is covered by the unit spec of the BullMQ client, which also proves the
+    persist refusals; the relay's unit spec proves a refused persist leaves the rows waiting.