@starci/hfs 4.0.7 → 4.0.9

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

@@ -0,0 +1,178 @@
+schema: starci/knowledge-source@1
+id: be.projections
+title: Projections (read models)
+purpose: |-
+  Given a read that needs data of another context (a join of order and payment, a count over many aggregates), where does it come
+  from? Never from a cross-context join: a projection keeps a read model, a table of its own under the owning context's
+  connection, that a reactor or a job recomputes from the source events. `modules/projections/<name>/` holds the projection class
+  (`recompute*` writes, `get*` reads) and its entity; only the projection writes its table, and the api reads only through `get*`.
+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.projections]
+pattern: projection
+provenance:
+  reviewedAt: 2026-10-02
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - knowledge/hfs/rules.yaml
+    - owner decision 2026-10-02 (projections replace cross-context joins)
+  limitations: |-
+    Static checks prove who writes the table, the method vocabulary, that the entity stays inside and that the api never recomputes.
+    They do not prove that a recompute is idempotent or that a replay rebuilds the same rows; the test-world scenarios
+    (`projection/*`) prove both.
+rules:
+  - id: BE-PROJECTIONS-1
+    title: Only the projection writes its table
+    kind: mandatory
+    hfsRules: [R161, R86]
+    requirement: |-
+      The entity of a projection (`<name>.projection-entity.ts`) is written only by `<name>.projection.ts` of the same folder:
+      no domain service, handler, reactor, job or other projection writes it. Its table, migrations and connection registration
+      sit in `modules/projections/<name>/persistence/`, on the connection of the context that owns the read model.
+    rationale: |-
+      A read model with one writer can always be rebuilt from its sources; a second writer makes the table a source of truth that
+      replay would destroy.
+    cases:
+      - id: case-1
+        when: A payment settles and the order summary must show it
+        write: 'The payment event reaches an order reactor, which dispatches RecomputeOrderSummaryCommand; its handler calls OrderSummaryProjection.recomputeOrderSummary(orderId).'
+    verification:
+      automated:
+        - BE_PROJECTION_WRITE_OWNER
+        - BE_SQL_TABLE_OWNER
+      manual:
+        - Confirm the projection sits on the connection of the context that serves the read.
+    relatedExamples: [projection]
+  - id: BE-PROJECTIONS-2
+    title: A projection speaks recompute and get, and hides its entity
+    kind: mandatory
+    hfsRules: [R162]
+    requirement: |-
+      Every public method of the projection class is `recompute*` (an idempotent write from the source facts that can replay from
+      scratch) or `get*` (a read). The `index.ts` of the projection exports the class and its contracts, never the entity. A feature
+      of kind api calls only `get*`; a reactor, a job or a cli command calls `recompute*`.
+    rationale: |-
+      A closed vocabulary keeps writes replayable and reads shape-independent, and the kind rule keeps the request path off the
+      write side.
+    cases:
+      - id: case-1
+        when: The api serves an order summary
+        write: 'show-order-summary.handler.ts calls this.orderSummary.getOrderSummary(orderId) and never recomputeOrderSummary.'
+    verification:
+      automated:
+        - BE_PROJECTION_SHAPE
+      manual:
+        - Confirm each recompute reads only source facts and upserts by a natural key.
+    relatedExamples: [projection]
+  - id: BE-PROJECTIONS-3
+    title: A projection publishes nothing and is kept current by a reactor or a job
+    kind: mandatory
+    hfsRules: [R152, R156]
+    requirement: |-
+      A projection never publishes an event or enqueues a job (`eventBus.publish` and queue producers are refused outside
+      `modules/domain`). A reactor under `features/reactors/<name>-projection/` consumes the source event and dispatches a command
+      whose handler calls `recompute*`; a rebuild is a job or a cli command that calls `recompute*` for every key. A projection
+      reads the facts of its own context through that context's domain services, never another context's tables.
+    rationale: |-
+      The read model is derived data: an event from it would let derived data drive the system of record.
+    cases:
+      - id: case-1
+        when: Rebuild every summary
+        write: 'features/jobs/rebuild-order-summary: a processor that pages order ids and calls recomputeOrderSummary for each.'
+    verification:
+      automated:
+        - BE_OUTBOX_WRITE_TX
+        - BE_KIND_ISOLATION
+      manual:
+        - Confirm no projection class holds an event bus or a queue producer.
+    relatedExamples: [projection]
+  - id: BE-PROJECTIONS-4
+    title: A declared projection is proven on the test world
+    kind: mandatory
+    hfsRules: [R155]
+    requirement: |-
+      An app that declares `projection` has tests titled `projection/<scenario>: ...` for `recompute-is-idempotent` (the same recompute
+      twice leaves one identical row) and `replay-rebuilds` (dropping the table and replaying the events rebuilds the same rows).
+    rationale: |-
+      Idempotence and replayability are the two properties that make a read model safe to operate.
+    cases:
+      - id: case-1
+        when: The order-summary e2e suite
+        write: "it('projection/replay-rebuilds: truncate then replay gives the same summaries', ...)"
+    verification:
+      automated:
+        - BE_PATTERN_SPEC_MISSING
+      manual: []
+    relatedExamples: [projection]
+  - id: BE-PROJECTIONS-5
+    title: A projection stays inside the context that serves the read
+    kind: mandatory
+    hfsRules: [R175]
+    requirement: |-
+      A projection sits on the connection of one context. Its entity declares no relation and its migration no foreign key onto a table
+      of another context, and no file of the projection imports a file of a capability of another context (its entities, services or SQL).
+      The facts it summarises from another context arrive as events through a reactor, never through a join or an import.
+    rationale: |-
+      A read model that reaches into another context's schema rebuilds the coupling the contexts were split to avoid.
+    cases:
+      - id: case-1
+        when: An order summary that shows the payment status
+        write: 'The payment event reaches an order reactor, which dispatches a command that stores the status locally and calls recomputeOrderSummary; the projection never joins the payment tables.'
+    verification:
+      automated:
+        - BE_CONTEXT_COUPLING
+      manual:
+        - Confirm the projection sits on the connection of the context that serves the read.
+    relatedExamples: [projection]
+files:
+  - path: src/modules/projections/<name>/index.ts
+    slot: be.projections
+    template: projections/projection.index.ts.tpl
+    role: Exports the projection class and its contracts, never the entity.
+    rules: [BE_PROJECTION_SHAPE]
+  - path: src/modules/projections/<name>/<name>.options.ts
+    slot: be.projections
+    template: projections/projection.options.ts.tpl
+    role: The empty options of the projection (the configurable module base needs a type).
+  - path: src/modules/projections/<name>/<name>.module-definition.ts
+    slot: be.projections
+    template: projections/projection.module-definition.ts.tpl
+    role: The configurable-module base; isGlobal is the app root's decision.
+  - path: src/modules/projections/<name>/<name>.module.ts
+    slot: be.projections
+    template: projections/projection.module.ts.tpl
+  - path: src/modules/projections/<name>/<name>.projection.ts
+    slot: be.projections
+    template: projections/projection.projection.ts.tpl
+    role: recompute* and get* only.
+    rules: [BE_PROJECTION_SHAPE, BE_PROJECTION_WRITE_OWNER]
+  - path: src/modules/projections/<name>/<name>.projection.spec.ts
+    slot: be.projections
+    template: projections/projection.projection.spec.ts.tpl
+  - path: src/modules/projections/<name>/<name>.projection-entity.ts
+    slot: be.projections
+    template: projections/projection.entity.ts.tpl
+    role: The read-model table; written only by the projection.
+    rules: [BE_PROJECTION_WRITE_OWNER]
+  - path: src/modules/projections/<name>/<name>.contracts.ts
+    slot: be.projections
+    optional: true
+  - path: src/modules/projections/<name>/persistence/connection.ts
+    slot: be.persistence
+    template: projections/persistence.connection.ts.tpl
+  - path: src/modules/projections/<name>/persistence/migrations/<epochMs13>-create-<name>.ts
+    slot: be.persistence
+    template: projections/migration.ts.tpl
+  - path: src/features/reactors/<name>-projection/transport/message/<event>.consumer.ts
+    slot: be.transport.message
+    role: The reactor door that triggers a recompute.
+    rules: [BE_EVENT_CONSUMER_SHAPE]
+  - path: src/tests/e2e/<area>/<name>.e2e-spec.ts
+    slot: be.tests.e2e
+    role: "Titles projection/<scenario>: ... prove the pattern."
+    spec: projection/recompute-is-idempotent, projection/replay-rebuilds
+    rules: [BE_PATTERN_SPEC_MISSING]

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

@@ -0,0 +1,236 @@
+schema: starci/knowledge-source@1
+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
+  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.
+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.feature.jobs, be.queues, be.platform.queue]
+pattern: queue
+provenance:
+  reviewedAt: 2026-10-02
+  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)
+    - 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
+    owner. They do not prove retry budgets, concurrency, or that a scheduler's cadence suits the business; the test-world
+    scenarios (`queue/*`) prove delivery against a real Redis.
+rules:
+  - id: BE-QUEUES-1
+    title: A queue is a typed producer that writes the outbox in the caller's transaction
+    kind: mandatory
+    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
+      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.
+    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) })'
+    verification:
+      automated:
+        - BE_OUTBOX_WRITE_TX
+        - BE_QUEUE_PRODUCER_SHAPE
+      manual:
+        - Confirm the payload carries ids, not entities, and the queue name is the contract between producer and processor.
+    relatedExamples: [queue]
+  - id: BE-QUEUES-2
+    title: platform/queue is the only BullMQ owner and the relay keeps jobId equal to the outbox id
+    kind: mandatory
+    hfsRules: [R90]
+    requirement: |-
+      `bullmq` and `@nestjs/bullmq` are imported only by `platform/queue`. Its relay claims committed queue-outbox rows per
+      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`.
+    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.'
+    verification:
+      automated:
+        - BE_INFRA_OWNER
+      manual: []
+    relatedExamples: [queue]
+  - id: BE-QUEUES-3
+    title: A schedule is a BullMQ job scheduler declared with its queue
+    kind: mandatory
+    hfsRules: [R90]
+    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.
+    rationale: |-
+      One scheduler in Redis 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.'
+    verification:
+      automated:
+        - BE_INFRA_OWNER
+      manual:
+        - Confirm the cadence and the job's idempotence.
+    relatedExamples: [queue]
+  - id: BE-QUEUES-4
+    title: A declared queue pattern is proven on the test world
+    kind: mandatory
+    hfsRules: [R155]
+    requirement: |-
+      An app that declares `queue` has tests titled `queue/<scenario>: ...` for `enqueue-atomic-with-transaction`,
+      `relay-job-id-is-outbox-id` and `scheduler-fires-once`, run against a real Redis.
+    rationale: |-
+      Atomicity and once-only firing are runtime facts.
+    cases:
+      - id: case-1
+        when: The order-expiry e2e suite
+        write: "it('queue/scheduler-fires-once: two relays, one job', ...)"
+    verification:
+      automated:
+        - BE_PATTERN_SPEC_MISSING
+      manual: []
+    relatedExamples: [queue]
+files:
+  - path: src/modules/platform/outbox/index.ts
+    slot: be.platform
+    role: "The public surface of the shared outbox relay."
+    template: outbox/platform/index.ts.tpl
+  - path: src/modules/platform/outbox/outbox.log-events.ts
+    slot: be.platform
+    role: "The log event of a failed relay pass."
+    template: outbox/platform/outbox.log-events.ts.tpl
+  - path: src/modules/platform/outbox/outbox-relay.policy.ts
+    slot: be.platform
+    role: "The one relay loop the event bus and the queues share: read, deliver and mark in one transaction."
+    template: outbox/platform/outbox-relay.policy.ts.tpl
+  - path: src/modules/platform/outbox/outbox-relay.policy.spec.ts
+    slot: be.platform
+    template: outbox/platform/outbox-relay.policy.spec.ts.tpl
+  - path: src/modules/platform/queue/index.ts
+    slot: be.platform.queue
+    role: "Public surface of the capability (ports, config, module, entity arrays)."
+    template: queues/platform/queue.index.ts.tpl
+  - path: src/modules/platform/queue/queue.module.ts
+    slot: be.platform.queue
+    role: "Dynamic module registered once per app with the connections that enqueue and the schedulers."
+    template: queues/platform/queue.module.ts.tpl
+  - path: src/modules/platform/queue/queue.module-definition.ts
+    slot: be.platform.queue
+    template: queues/platform/queue.module-definition.ts.tpl
+  - path: src/modules/platform/queue/queue.options.ts
+    slot: be.platform.queue
+    template: queues/platform/queue.options.ts.tpl
+  - path: src/modules/platform/queue/queue.config.ts
+    slot: be.platform.queue
+    role: "Typed reader of the Redis and relay settings."
+    template: queues/platform/queue.config.ts.tpl
+  - path: src/modules/platform/queue/queue.decorators.ts
+    slot: be.platform.queue
+    role: "InjectQueueOutbox, InjectQueueWorkerRegistry and their tokens."
+    template: queues/platform/queue.decorators.ts.tpl
+  - path: src/modules/platform/queue/queue.contracts.ts
+    slot: be.platform.queue
+    role: "QueueSchedulerDefinition, QueueDelivery, QueueHandler."
+    template: queues/platform/queue.contracts.ts.tpl
+  - path: src/modules/platform/queue/queue.port.ts
+    slot: be.platform.queue
+    role: "QueueOutbox (write(tx, queue, payload)) and QueueWorkerRegistry ports."
+    template: queues/platform/queue.port.ts.tpl
+  - path: src/modules/platform/queue/queue-transport.port.ts
+    slot: be.platform.queue
+    role: "The BullMQ port."
+    template: queues/platform/queue-transport.port.ts.tpl
+  - path: src/modules/platform/queue/queue.policy.ts
+    slot: be.platform.queue
+    role: "Attempts, backoff and retention of BullMQ jobs."
+    template: queues/platform/queue.policy.ts.tpl
+  - path: src/modules/platform/queue/queue.policy.spec.ts
+    slot: be.platform.queue
+    template: queues/platform/queue.policy.spec.ts.tpl
+  - 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/bullmq-queue-transport.client.ts
+    slot: be.platform.queue
+    role: "The one bullmq importer."
+    template: queues/platform/bullmq-queue-transport.client.ts.tpl
+  - path: src/modules/platform/queue/bullmq-queue-transport.client.spec.ts
+    slot: be.platform.queue
+    template: queues/platform/bullmq-queue-transport.client.spec.ts.tpl
+  - path: src/modules/platform/queue/queue-outbox.service.ts
+    slot: be.platform.queue
+    role: "Writes a job row through the caller's tx."
+    template: queues/platform/queue-outbox.service.ts.tpl
+  - path: src/modules/platform/queue/queue-outbox.service.spec.ts
+    slot: be.platform.queue
+    template: queues/platform/queue-outbox.service.spec.ts.tpl
+  - path: src/modules/platform/queue/queue-relay.service.ts
+    slot: be.platform.queue
+    role: "Relay of committed rows into BullMQ with jobId = the row id, per registered connection."
+    template: queues/platform/queue-relay.service.ts.tpl
+  - path: src/modules/platform/queue/queue-relay.service.spec.ts
+    slot: be.platform.queue
+    template: queues/platform/queue-relay.service.spec.ts.tpl
+  - path: src/modules/platform/queue/queue-worker.service.ts
+    slot: be.platform.queue
+    role: "The handler registry, the workers and the scheduler registration."
+    template: queues/platform/queue-worker.service.ts.tpl
+  - path: src/modules/platform/queue/queue-worker.service.spec.ts
+    slot: be.platform.queue
+    template: queues/platform/queue-worker.service.spec.ts.tpl
+  - path: src/modules/platform/queue/persistence/connection.ts
+    slot: be.persistence
+    role: "The outbox entity array registered on every connection that enqueues."
+    template: queues/platform/persistence.connection.ts.tpl
+  - path: src/modules/platform/queue/persistence/entities/queue-outbox.entity.ts
+    slot: be.persistence
+    template: queues/platform/persistence.queue-outbox.entity.ts.tpl
+  - path: src/modules/platform/queue/persistence/queue.sql.ts
+    slot: be.persistence
+    template: queues/platform/persistence.queue.sql.ts.tpl
+  - path: src/modules/platform/queue/persistence/queue.rows.ts
+    slot: be.persistence
+    template: queues/platform/persistence.queue.rows.ts.tpl
+  - path: src/modules/platform/queue/persistence/migrations/<epochMs13>-create-queue-outbox.ts
+    slot: be.persistence
+    template: queues/platform/persistence.migration.ts.tpl
+  - path: src/modules/queues/<queue>/index.ts
+    slot: be.queues
+    template: queues/queue.index.ts.tpl
+  - path: src/modules/queues/<queue>/<queue>.module.ts
+    slot: be.queues
+    role: The Nest module that provides the typed producer.
+    template: queues/queue.module.ts.tpl
+  - path: src/modules/queues/<queue>/<queue>.queue.ts
+    slot: be.queues
+    template: queues/queue.queue.ts.tpl
+    role: The typed producers and the schedulers of one queue.
+    rules: [BE_QUEUE_PRODUCER_SHAPE, BE_OUTBOX_WRITE_TX]
+  - path: src/modules/queues/<queue>/<queue>.contracts.ts
+    slot: be.queues
+    role: Payload types and the queue name.
+    optional: true
+  - path: src/tests/e2e/<area>/<queue>.e2e-spec.ts
+    slot: be.tests.e2e
+    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]

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

@@ -0,0 +1,140 @@
+schema: starci/knowledge-source@1
+id: be.reactors
+title: Reactors
+purpose: |-
+  Given a fact another context announced that this context must remember or act on, who listens? A reactor: a feature of kind
+  `reactors` under `features/reactors/<reactor>/` that consumes events of another context and either keeps a local copy of what
+  this context needs (the payment status inside order) or triggers a projection recompute. It is a thin door (R203 `BE_FEATURE_THIN`):
+  it maps the delivery and dispatches one command, and the domain service of its own context does the work in one transaction.
+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.feature.reactors]
+provenance:
+  reviewedAt: 2026-10-02
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - knowledge/hfs/rules.yaml
+    - owner decision 2026-10-02 (reactors keep local copies and trigger projections)
+  limitations: |-
+    Static checks prove the consumer shape, the kind boundary and composition. They do not prove that the local copy is replayable or
+    that the event carries what the copy needs; the context rules and the test-world scenarios prove that.
+rules:
+  - id: BE-REACTORS-1
+    title: A reactor consumes events and dispatches commands
+    kind: mandatory
+    hfsRules: [R153, R80, R203]
+    requirement: |-
+      A reactor holds `transport/message/<event>.consumer.ts` (implementing `EventConsumer<E>` with `readonly event = <Event>Event`),
+      `<reactor>-message.module.ts` and an `application/` of plain CQRS. The consumer is thin (R203 `BE_FEATURE_THIN`):
+      `handle(delivery)` maps the delivery and dispatches one command, forwarding
+      `delivery.eventId`; the domain service the command reaches claims the event id in `platform/inbox` inside its own transaction,
+      so a redelivery is a no-op.
+    rationale: |-
+      Delivery is at least once; the reactor stays a door and the decision stays in the domain.
+    cases:
+      - id: case-1
+        when: order learns that a payment settled
+        write: 'features/reactors/payment-status/transport/message/payment-settled.consumer.ts dispatches RecordPaymentStatusCommand with delivery.eventId.'
+    verification:
+      automated:
+        - BE_EVENT_CONSUMER_SHAPE
+        - BE_INBOX_DEDUPE_MISSING
+        - BE_FEATURE_THIN
+      manual: []
+    relatedExamples: [event-bus]
+  - id: BE-REACTORS-2
+    title: A reactor never imports another kind and never reads another context
+    kind: mandatory
+    hfsRules: [R156, R26]
+    requirement: |-
+      A reactor imports only `modules/*`; it meets the api, saga and jobs kinds through events. It never reads another context's
+      tables or imports its entities, services or SQL: what it needs from that context arrives in the event, or is read from a
+      projection. An order service that needs the payment status either keeps a local copy fed by a reactor (passing) or reads a
+      projection; joining or importing the payment tables is the violation.
+    rationale: |-
+      Contexts stay separately deployable only when cross-context data travels as events.
+    cases:
+      - id: case-1
+        when: order shows the payment status
+        write: 'passing: an order-owned payment_status copy written by the reactor command; violating: order SQL joining the payment table or importing PaymentService.'
+    verification:
+      automated:
+        - BE_KIND_ISOLATION
+        - BE_TIER_DIRECTION
+        - FE_TIER_DIRECTION
+        - ARCH_PACKAGE_IMPORTS_APP
+      manual:
+        - Confirm the event carries every field the copy needs.
+    relatedExamples: [event-bus]
+  - id: BE-REACTORS-3
+    title: The local copy lives in the reactor's own context and is replayable
+    kind: mandatory
+    hfsRules: [R152, R80]
+    requirement: |-
+      The copy is a table of the context that owns the reactor, on that context's connection, written by a domain service of that
+      context (one transaction touches one context's connection). The write is an idempotent upsert keyed by the aggregate id and
+      guarded by the event version or id, so replaying the event stream rebuilds the same rows.
+    rationale: |-
+      A copy that cannot be rebuilt is a second source of truth.
+    cases:
+      - id: case-1
+        when: The same payment.settled event is delivered twice
+        write: 'The second delivery claims nothing in the inbox and the row is unchanged.'
+    verification:
+      automated:
+        - BE_OUTBOX_WRITE_TX
+        - BE_INBOX_DEDUPE_MISSING
+      manual:
+        - Confirm a replay from the start of the topic gives the same rows.
+    relatedExamples: [event-bus]
+  - id: BE-REACTORS-4
+    title: A reactor is composed by a worker or api app
+    kind: mandatory
+    hfsRules: [R46, R31]
+    requirement: |-
+      The message module of a reactor is imported by the root module of an app of kind `worker` or `api`, and an e2e run boots that
+      app's real AppModule and drives the event through the bus.
+    rationale: |-
+      A consumer that no app composes never runs.
+    cases:
+      - id: case-1
+        when: A new reactor
+        write: 'Import PaymentStatusMessageModule in the order app module in the same change and cover it in the order e2e.'
+    verification:
+      automated:
+        - BE_BACKGROUND_UNOWNED
+        - BE_FEATURE_NOT_COMPOSED
+      manual: []
+    relatedExamples: [event-bus]
+files:
+  - path: src/features/reactors/<reactor>/index.ts
+    slot: be.feature.reactors
+    template: reactors/reactor.index.ts.tpl
+  - path: src/features/reactors/<reactor>/<reactor>.module.ts
+    slot: be.feature.reactors
+    template: reactors/reactor.module.ts.tpl
+  - path: src/features/reactors/<reactor>/application/<action>.command.ts
+    slot: be.feature.application
+    template: reactors/application.command.ts.tpl
+  - path: src/features/reactors/<reactor>/application/<action>.handler.ts
+    slot: be.feature.application
+    template: reactors/application.handler.ts.tpl
+  - path: src/features/reactors/<reactor>/application/<action>.contracts.ts
+    slot: be.feature.application
+    template: reactors/application.contracts.ts.tpl
+  - path: src/features/reactors/<reactor>/transport/message/<event>.consumer.ts
+    slot: be.transport.message
+    template: reactors/consumer.ts.tpl
+    role: The consumer door of one event.
+    rules: [BE_EVENT_CONSUMER_SHAPE]
+  - path: src/features/reactors/<reactor>/transport/message/<reactor>-message.module.ts
+    slot: be.transport.message
+    template: reactors/message.module.ts.tpl
+    role: Registers the consumers with the registry.
+  - path: src/tests/e2e/<area>/<event>.e2e-spec.ts
+    slot: be.tests.e2e
+    role: The reactor's event flow through the bus, redelivery included.