@starci/hfs 4.0.8 → 4.0.9

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

@@ -0,0 +1,222 @@
+schema: starci/knowledge-source@1
+id: be.feature.realtime
+title: Realtime channels
+purpose: |-
+  Given a state change a connected client must see without asking, how is it pushed? Realtime is a feature KIND:
+  `be/src/features/realtime/<channel>/` holds one door per channel, a socket gateway (`<channel>.gateway.ts`) or a GraphQL
+  subscription (`<x>.subscription.ts`), that READS and PUSHES only. It never writes. The push is fed by a reactor: an event
+  consumer in `features/reactors/` receives the domain event and publishes to a topic of the `RealtimeHub` of `platform/realtime`;
+  the door only subscribes the client to a topic of that hub, scoped to the client's principal.
+appliesTo:
+  - backend
+family: be
+provenance:
+  reviewedAt: 2026-10-02
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - knowledge/hfs/rules.yaml
+    - 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)
+  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.
+rules:
+  - id: BE-REALTIME-1
+    title: A channel is a kind folder with one door, its module and its own spec
+    kind: mandatory
+    hfsRules: [R01, R02, R47, R184]
+    requirement: |-
+      A push channel lives in `be/src/features/realtime/<channel>/` (slot `be.feature.realtime`), enabled by declaring the pattern
+      `realtime` in `hfs.json` `sides.be.patterns`. The folder holds `index.ts` (the module class an app composes), `transport/<protocol>/<channel>-<protocol>.module.ts`, ONE door and its spec: either
+      `transport/websocket/<channel>.gateway.ts` (one `@WebSocketGateway` class whose handlers are `@SubscribeMessage`) with
+      `<channel>.gateway.spec.ts`, or `transport/graphql/<channel>.subscription.ts` (one `@Resolver` class whose operations are `@Subscription`) with
+      `<channel>.subscription.spec.ts`, plus optional `dto/` (`<name>.{input,type,args}.ts`). A door carries no query, mutation, field
+      resolver or REST route. The kind imports only `modules/*`, never another kind, and only an api-kind app composes its module.
+    rationale: |-
+      One file per door keeps a protocol's machinery in one place, and keeping queries and mutations out guarantees that what a
+      client can do through a realtime door is listen.
+    cases:
+      - id: case-1
+        when: A GraphQL subscription of order status
+        write: 'features/realtime/order-status/index.ts, transport/graphql/order-status-graphql.module.ts, transport/graphql/order-status.subscription.ts and transport/graphql/order-status.subscription.spec.ts.'
+      - id: case-2
+        when: A socket gateway
+        write: 'features/realtime/chat/transport/websocket/chat-websocket.module.ts, transport/websocket/chat.gateway.ts and transport/websocket/chat.gateway.spec.ts.'
+    verification:
+      automated:
+        - HFS_SLOT_UNDECLARED
+        - HFS_SLOT_AMBIGUOUS
+        - HFS_SLOT_NOT_ENABLED
+        - HFS_FORBIDDEN_PRESENT
+        - HFS_TRACKED_MUST_BE_IGNORED
+        - HFS_ROOT_ENTRY_FORBIDDEN
+        - HFS_ROOT_MARKDOWN_FORBIDDEN
+        - HFS_ROOT_SRC_FORBIDDEN_FE
+        - HFS_SRC_LAYOUT_INVALID
+        - HFS_MODULE_TIER_INVALID
+        - HFS_WORK_IN_FE
+        - HFS_STACKS_IN_SIDE
+        - HFS_SLOT_REQUIRED_MISSING
+        - HFS_MIN_INSTANCES
+        - HFS_REQUIRED_FILE_MISSING
+        - HFS_ROOT_ENTRY_MISSING
+        - HFS_APPS_REQUIRED
+        - HFS_APP_LAYOUT_INVALID
+        - HFS_README_TITLE_INVALID
+        - HFS_README_DESCRIPTION_INVALID
+        - HFS_README_SECTION_MISSING
+        - HFS_README_SECTION_ORDER
+        - HFS_README_DEVELOPMENT_INCOMPLETE
+        - HFS_README_WORK_POINTER_MISSING
+        - HFS_README_PRIVATE_URL
+        - HFS_README_BADGE_NOT_LIVE
+        - BE_TEST_TOPOLOGY
+        - BE_CONTRACT_UNGUARDED
+        - BE_REALTIME_SHAPE
+      manual:
+        - Confirm a query or mutation an old subscription door carried now lives in an api feature.
+    relatedExamples: [realtime]
+  - id: BE-REALTIME-2
+    title: A realtime door reads and pushes, it never writes
+    kind: mandatory
+    hfsRules: [R185, R90, R203]
+    requirement: |-
+      A realtime door is thin (R203 `BE_FEATURE_THIN`): it maps the subscription or the message and makes one delegating call
+      to the hub. The only value it injects is the `RealtimeHub` of `platform/realtime` (`subscribe(topic)` returns an async
+      iterable of frames, `publish(topic, frame)` pushes one; a topic is a typed `RealtimeTopic<T>` built by the owning domain
+      contract, never a string written in a door). No `EntityManager`, `CommandBus`, `QueryBus`, event bus, queue or
+      service of `modules/domain` is injected: a domain service may write, so it is not provably read-only. The data a client
+      needs is pushed by a reactor; the socket library and the pub/sub engine (`socket.io`, `graphql-subscriptions`, `graphql-ws`)
+      are imported only by `platform/realtime`.
+    rationale: |-
+      A door that can only touch the hub cannot change business state, so the biggest risk of a long-lived unauthenticated-looking
+      connection, a write through it, is removed by type.
+    cases:
+      - id: case-1
+        when: A subscription that pushes order status changes
+        write: |-
+          @Resolver()
+          export class OrderStatusSubscription {
+              constructor(private readonly hub: RealtimeHub) {}
+
+              @Subscription(() => OrderStatusChangedType)
+              orderStatusChanged(@CurrentPrincipal() principal: Principal, @Args("orderId") orderId: string): AsyncIterable<OrderStatusChangedType> {
+                  return this.hub.subscribe(orderStatusTopic(principal.id, orderId))
+              }
+          }
+    verification:
+      automated:
+        - BE_REALTIME_WRITES
+        - BE_INFRA_OWNER
+        - BE_FEATURE_THIN
+      manual:
+        - Confirm the frame type carries only what the principal may see.
+    relatedExamples: [realtime]
+  - id: BE-REALTIME-3
+    title: The topic is built from the principal
+    kind: mandatory
+    hfsRules: [R186, R41]
+    requirement: |-
+      Every `@SubscribeMessage` and `@Subscription` handler takes `@CurrentPrincipal()` of `domain/identity` and builds the topic it
+      passes to `hub.subscribe` from the principal's id (plus a client-supplied id only inside that prefix) with the topic
+      builder of the owning domain contract, so one client cannot
+      listen to another's channel. The reactor that pushes uses the same topic builder from the owning domain contract, never a
+      hand-written string. The default-deny guards apply to the door like to any other.
+    rationale: |-
+      A topic taken from client input alone is an authorization hole: knowing an order id would be enough to watch it.
+    cases:
+      - id: case-1
+        when: Subscribing to one order's status
+        write: 'hub.subscribe(orderStatusTopic(principal.id, orderId)); the reactor publishes to orderStatusTopic(buyerId, orderId) of the order owner, so a different principal receives nothing.'
+    verification:
+      automated:
+        - BE_REALTIME_TOPIC_SCOPE
+        - BE_DEFAULT_DENY
+      manual:
+        - Review that the topic builder shared with the reactor lives in the domain contract and is used by both sides.
+    relatedExamples: [realtime]
+  - id: BE-REALTIME-4
+    title: Three behaviours are proven on the test world
+    kind: mandatory
+    hfsRules: [R155]
+    requirement: |-
+      Declaring the pattern `realtime` requires e2e or integration tests titled `realtime/<scenario>: ...` for each scenario
+      `subscriber-receives-push` (a connected client receives the frame a reactor pushes after the domain event),
+      `foreign-topic-is-isolated` (another principal subscribed to the same channel receives nothing) and
+      `disconnect-releases-subscription` (after the client disconnects the hub holds no subscription for it). The client is a real
+      socket or GraphQL-over-websocket client of the test world. The unit spec of the door covers its wiring with the Nest testing
+      module and a recording hub double.
+    rationale: |-
+      The door has no logic, so the risk is delivery, isolation and leaks on a real connection, which only a client against the
+      real app shows.
+    cases:
+      - id: case-1
+        when: The e2e of the order status channel
+        write: 'e2e/order/order-status-push.e2e-spec.ts has `it("realtime/subscriber-receives-push: ...")`, `it("realtime/foreign-topic-is-isolated: ...")` and `it("realtime/disconnect-releases-subscription: ...")`.'
+    verification:
+      automated:
+        - BE_PATTERN_SPEC_MISSING
+      manual:
+        - Confirm the e2e client waits with the world's waitFor and never sleeps.
+    relatedExamples: [realtime]
+files:
+  - path: src/features/realtime/<channel>/index.ts
+    slot: be.feature.realtime
+    template: realtime/channel.index.ts.tpl
+    role: The public surface of the kind folder, the module class an api-kind app composes.
+  - path: src/features/realtime/<channel>/transport/graphql/<channel>-graphql.module.ts
+    slot: be.feature.realtime.graphql
+    template: realtime/channel.graphql.module.ts.tpl
+    role: Nest module of the subscription door, composed only by an api-kind app.
+  - path: src/features/realtime/<channel>/transport/websocket/<channel>-websocket.module.ts
+    slot: be.feature.realtime.websocket
+    role: Nest module of the gateway door, composed only by an api-kind app.
+    optional: true
+  - path: src/features/realtime/<channel>/transport/websocket/<channel>.gateway.ts
+    slot: be.feature.realtime.websocket
+    role: A socket door (one WebSocketGateway class); exactly one of gateway or subscription per channel file name.
+    rules: [BE_REALTIME_SHAPE, BE_REALTIME_WRITES, BE_REALTIME_TOPIC_SCOPE]
+    spec: src/features/realtime/<channel>/transport/websocket/<channel>.gateway.spec.ts
+    optional: true
+  - path: src/features/realtime/<channel>/transport/websocket/<channel>.gateway.spec.ts
+    slot: be.feature.realtime.websocket
+    role: Unit spec of the gateway beside it.
+    optional: true
+  - path: src/features/realtime/<channel>/transport/graphql/<channel>.subscription.ts
+    slot: be.feature.realtime.graphql
+    template: realtime/channel.subscription.ts.tpl
+    role: A GraphQL subscription door (one Resolver class).
+    rules: [BE_REALTIME_SHAPE, BE_REALTIME_WRITES, BE_REALTIME_TOPIC_SCOPE]
+    spec: src/features/realtime/<channel>/transport/graphql/<channel>.subscription.spec.ts
+  - path: src/features/realtime/<channel>/transport/graphql/<channel>.subscription.spec.ts
+    slot: be.feature.realtime.graphql
+    template: realtime/channel.subscription.spec.ts.tpl
+    role: Unit spec of the subscription beside it.
+  - path: src/features/realtime/<channel>/transport/graphql/dto/<channel>-changed.type.ts
+    slot: be.feature.realtime.dto
+    template: realtime/channel.type.ts.tpl
+    role: "The typed frame of the door, what the subscriber may see of a change."
+  - path: src/features/realtime/<channel>/transport/graphql/dto/<channel>.input.ts
+    slot: be.feature.realtime.dto
+    template: realtime/channel.input.ts.tpl
+    role: The typed, bounded arguments of the door.
+    rules: [BE_INPUT_BOUNDED]
+  - path: src/modules/platform/realtime/realtime.hub.ts
+    slot: be.platform
+    role: RealtimeHub, the one owner of the socket and subscription engine (publish and subscribe).
+    spec: src/modules/platform/realtime/realtime.service.spec.ts
+    optional: true
+  - path: src/features/reactors/<name>/transport/message/<event>.consumer.ts
+    slot: be.transport.message
+    role: The reactor consumer that receives the domain event and pushes the frame through the hub.
+    optional: true
+  - path: src/tests/e2e/<area>/<channel>-push.e2e-spec.ts
+    slot: be.tests.e2e
+    role: "Titles realtime/<scenario>: ... prove the pattern against a real client."
+    spec: realtime/subscriber-receives-push, realtime/foreign-topic-is-isolated, realtime/disconnect-releases-subscription
+    rules: [BE_PATTERN_SPEC_MISSING]
+    optional: true

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

@@ -0,0 +1,248 @@
+schema: starci/knowledge-source@1
+id: be.saga
+title: Sagas
+purpose: |-
+  Given a flow that spans services and must be undone when a later step fails, how is it written so that hfs can check it?
+  A saga is a feature of the saga kind (`be/src/features/saga/<saga>/`): an orchestrator that lists the steps and, for each, the compensation that undoes it; the
+  persisted state of a run with a version fence; consumers that advance it through the inbox; and the events it relies on,
+  declared in the vendored contracts. The saga pattern is declared (`patterns: ["saga"]` in hfs.json sides.be); an
+  undeclared saga folder is refused.
+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.saga]
+provenance:
+  reviewedAt: 2026-10-02
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - knowledge/hfs/rules.yaml
+    - knowledge/patterns/be/services.yaml
+    - examples/ecommerce-app
+  limitations: |-
+    The checks read the folder tree, the step and compensation event names, the contracts, the consumers' use of the delivery id
+    and the e2e specs. They cannot see that a compensation really undoes its step, that a step is idempotent, or that the
+    failure injected by an e2e spec is the right one; the state machine and its fence are proven by the unit spec of
+    platform/saga, the flow by the e2e specs, and the semantics by review.
+files:
+  - path: src/features/saga/<saga>/index.ts
+    slot: be.feature.saga
+    template: saga/saga.index.ts.tpl
+    role: "The public surface of the kind folder: the message module an app composes."
+  - path: src/features/saga/<saga>/<saga>.module.ts
+    slot: be.feature.saga
+    template: saga/saga.module.ts.tpl
+    role: "The application module: handlers, orchestrator, step and compensation."
+  - path: src/features/saga/<saga>/<saga>.saga.service.ts
+    slot: be.feature.saga
+    template: saga/saga.service.ts.tpl
+    role: "The orchestrator. A `*.service.ts` because a handler injects only services; thin (R203 `BE_FEATURE_THIN`) like every feature file — it maps and delegates, and the run's orchestration lives in `platform/saga` — and it owes its `<saga>.saga.service.spec.ts` beside it (a `service` of `ruleParams.be.unitRoles`), which asserts the delegation. It hands `platform/saga` each run with the compensation OBJECT of the step (`compensation`, never a callback): the platform logs `Compensating`, orders the steps and moves the run through the version fence; its slot is `coverage: none`, so it is never a coverage target."
+    suffix: saga.service
+    rules: [R169, R170, R203]
+  - path: src/features/saga/<saga>/<saga>.saga.service.spec.ts
+    slot: be.feature.saga
+    template: saga/saga.service.spec.ts.tpl
+    role: "Unit spec of the orchestrator beside it."
+  - path: src/features/saga/<saga>/<saga>.saga-state.ts
+    slot: be.feature.saga
+    template: saga/saga.state.ts.tpl
+    role: "The typed state of a run, with `status` and `version: number`, the fence."
+    suffix: saga-state
+    rules: [R170]
+  - path: src/features/saga/<saga>/steps/<step>.saga-step.ts
+    slot: be.feature.saga.steps
+    template: saga/saga.step.ts.tpl
+    role: "One step. Names its event (`readonly event = \"<name>\"`); the domain does the work and announces the event in its transaction."
+    suffix: step
+    rules: [R169, R171]
+  - path: src/features/saga/<saga>/compensations/<step>.compensation.ts
+    slot: be.feature.saga.compensations
+    template: saga/saga.compensation.ts.tpl
+    role: "The compensation of the step of the same name; REQUIRED for every step. Names the step it undoes and the failure event, and dispatches one command; the orchestrator passes it to `platform/saga` as the compensation object."
+    suffix: compensation
+    rules: [R169, R171, R173]
+  - path: src/features/saga/<saga>/application/undo-<saga>.command.ts
+    slot: be.feature.application
+    template: saga/saga.undo.command.ts.tpl
+    role: "The undo command of the saga (command): undoes what the saga did; plain CQRS (BE-CQRS-1), thin handlers calling one service."
+    rules: [R87]
+  - path: src/features/saga/<saga>/application/undo-<saga>.contracts.ts
+    slot: be.feature.application
+    template: saga/saga.undo.contracts.ts.tpl
+    role: "The undo command of the saga (contracts): undoes what the saga did; plain CQRS (BE-CQRS-1), thin handlers calling one service."
+    rules: [R87]
+  - path: src/features/saga/<saga>/application/undo-<saga>.handler.ts
+    slot: be.feature.application
+    template: saga/saga.undo.handler.ts.tpl
+    role: "The undo command of the saga (handler): undoes what the saga did; plain CQRS (BE-CQRS-1), thin handlers calling one service."
+    rules: [R87]
+  - path: src/features/saga/<saga>/application/compensate-<saga>.command.ts
+    slot: be.feature.application
+    template: saga/saga.compensate.command.ts.tpl
+    role: "The compensate command of the saga (command): compensates a failed run; plain CQRS (BE-CQRS-1), thin handlers calling one service."
+    rules: [R87]
+  - path: src/features/saga/<saga>/application/compensate-<saga>.contracts.ts
+    slot: be.feature.application
+    template: saga/saga.compensate.contracts.ts.tpl
+    role: "The compensate command of the saga (contracts): compensates a failed run; plain CQRS (BE-CQRS-1), thin handlers calling one service."
+    rules: [R87]
+  - path: src/features/saga/<saga>/application/compensate-<saga>.handler.ts
+    slot: be.feature.application
+    template: saga/saga.compensate.handler.ts.tpl
+    role: "The compensate command of the saga (handler): compensates a failed run; plain CQRS (BE-CQRS-1), thin handlers calling one service."
+    rules: [R87]
+  - path: src/features/saga/<saga>/application/complete-<saga>.command.ts
+    slot: be.feature.application
+    template: saga/saga.complete.command.ts.tpl
+    role: "The complete command of the saga (command): completes a finished run; plain CQRS (BE-CQRS-1), thin handlers calling one service."
+    rules: [R87]
+  - path: src/features/saga/<saga>/application/complete-<saga>.contracts.ts
+    slot: be.feature.application
+    template: saga/saga.complete.contracts.ts.tpl
+    role: "The complete command of the saga (contracts): completes a finished run; plain CQRS (BE-CQRS-1), thin handlers calling one service."
+    rules: [R87]
+  - path: src/features/saga/<saga>/application/complete-<saga>.handler.ts
+    slot: be.feature.application
+    template: saga/saga.complete.handler.ts.tpl
+    role: "The complete command of the saga (handler): completes a finished run; plain CQRS (BE-CQRS-1), thin handlers calling one service."
+    rules: [R87]
+  - path: src/features/saga/<saga>/transport/message/<failed>.consumer.ts
+    slot: be.transport.message
+    template: saga/saga.failed.consumer.ts.tpl
+    role: "A thin door that hands the failure delivery, with its `eventId`, to the compensate command; the saga takes it through the inbox."
+    suffix: consumer
+    rules: [R80, R88, R172]
+  - path: src/features/saga/<saga>/transport/message/<done>.consumer.ts
+    slot: be.transport.message
+    template: saga/saga.done.consumer.ts.tpl
+    role: "A thin door that hands the delivery of the last event, with its `eventId`, to the complete command; the saga takes it through the inbox."
+    suffix: consumer
+    rules: [R80, R88, R172]
+  - path: src/features/saga/<saga>/transport/message/<saga>-message.module.ts
+    slot: be.transport.message
+    template: saga/saga.message.module.ts.tpl
+    role: "The message transport module: registers the consumers with the event bus; composed only by an app."
+  - path: contracts/<service>/events.json
+    slot: be.contract.events
+    role: 'Every event of the saga, emitted from the publisher''s events.ts; a compensating event declares `compensates`.'
+    rules: [R166, R171]
+    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.'
+    rules: [R170, R80]
+    optional: true
+  - path: src/tests/e2e/<area>/<name>.e2e-spec.ts
+    slot: be.tests.e2e
+    suffix: e2e-spec
+    role: One spec per compensation path that names the compensation event and injects a failure through the world (an infra or app outage, a fake's failNext), then reads the compensated state back; plus one spec from the api call to the final state.
+    rules: [R173, R167]
+    optional: true
+rules:
+  - id: BE-SAGA-1
+    title: Every step has a compensation, and the orchestrator lists them all
+    kind: mandatory
+    hfsRules: [R169, R01]
+    requirement: |-
+      A saga is `be/src/features/saga/<saga>/` with `<saga>.saga.service.ts`, `steps/<step>.saga-step.ts` and
+      `compensations/<step>.compensation.ts`: every step has a compensation of the same name and every compensation a step,
+      and the orchestrator passes every compensation of its folder to `platform/saga` (the compensation names the step it
+      undoes). The folders are slots enabled by the declared pattern; a saga folder in a product that does not declare
+      `patterns: ["saga"]` is `HFS_SLOT_NOT_ENABLED`.
+    rationale: |-
+      A forward step with no way back leaves a half-done flow when a later step fails. Naming the pair by file makes the
+      missing half a finding, and listing both in the orchestrator keeps a step nobody runs from hiding.
+    cases:
+      - id: case-1
+        when: A new step
+        write: 'features/saga/place-order/steps/reserve-order.saga-step.ts and features/saga/place-order/compensations/reserve-order.compensation.ts; the orchestrator passes the compensation object to `platform/saga`.'
+    verification:
+      automated:
+        - BE_SAGA_STEP_COMPENSATION
+        - HFS_SLOT_UNDECLARED
+        - HFS_SLOT_AMBIGUOUS
+        - HFS_SLOT_NOT_ENABLED
+        - HFS_FORBIDDEN_PRESENT
+        - HFS_TRACKED_MUST_BE_IGNORED
+        - HFS_ROOT_ENTRY_FORBIDDEN
+        - HFS_ROOT_MARKDOWN_FORBIDDEN
+        - HFS_ROOT_SRC_FORBIDDEN_FE
+        - HFS_SRC_LAYOUT_INVALID
+        - HFS_MODULE_TIER_INVALID
+        - HFS_WORK_IN_FE
+        - HFS_STACKS_IN_SIDE
+      manual:
+        - Check the compensation undoes every effect of the step, including the ones another service made.
+    relatedExamples: [saga]
+  - id: BE-SAGA-2
+    title: The state of a run is typed, versioned and moved only through the fenced store
+    kind: mandatory
+    hfsRules: [R170, R80, R172, R203]
+    requirement: |-
+      `<saga>.saga-state.ts` exports the state type with `status` and `version: number`. The orchestrator is a thin feature
+      file (R203 `BE_FEATURE_THIN`) and the run's orchestration lives in `platform/saga`: the orchestrator moves a run only
+      through it, a transition names the version it read and moves it by one, and takes its event through the
+      inbox first. A consumer of a saga passes the id of the delivery (`message.eventId`) to its command.
+    rationale: |-
+      Deliveries repeat and arrive late. The version fence stops a zombie delivery from moving a run twice, and the inbox makes
+      a redelivery a no-op.
+    cases:
+      - id: case-1
+        when: A failure event arrives twice
+        write: 'compensate({ saga, correlationId, eventId, compensation }) claims the event, moves running to compensating at version 1, logs Compensating and runs compensation.run(correlationId), settles compensated; the second delivery answers duplicate.'
+    verification:
+      automated:
+        - BE_SAGA_STATE_VERSIONED
+        - BE_INBOX_DEDUPE_MISSING
+        - BE_SAGA_CONSUMER_DEDUPE
+        - BE_FEATURE_THIN
+      manual:
+        - Check a failing compensation gives the event back so the redelivery resumes the run.
+    relatedExamples: [saga]
+  - id: BE-SAGA-3
+    title: Every event of a step or compensation is in a vendored contract
+    kind: mandatory
+    hfsRules: [R171, R166]
+    requirement: |-
+      A step and a compensation each declare `readonly event = "<name>"`; both events are declared in a vendored contract
+      (`be/contracts/<service>/events.json`), and the contract of the compensation's event declares `compensates: "<event of
+      the step>"`. A consumer lists what it reads in `consumes.ts`.
+    rationale: |-
+      The failure event is the only thing that tells the saga to undo a step; declaring which step it undoes in the contract
+      makes the pairing reviewable in the provider and judged in the consumer.
+    cases:
+      - id: case-1
+        when: Billing rejects an invoice
+        write: 'billing/src/events.ts: "billing.invoice-rejected": { version: 1, compensates: "order.placed", payload: { ... } }.'
+    verification:
+      automated:
+        - BE_SAGA_EVENT_CONTRACT
+        - HFS_EVENT_CONTRACT
+      manual:
+        - Review the payload of a new failure event for what the compensation needs.
+    relatedExamples: [saga]
+  - id: BE-SAGA-4
+    title: Every compensation path has an e2e spec that injects a failure
+    kind: mandatory
+    hfsRules: [R173, R167]
+    requirement: |-
+      For each compensation, `be/src/tests/e2e/<area>/*.e2e-spec.ts` boots the real apps through `useTestWorld`, names the
+      compensation's event, injects a failure through the world (`during`, `cut` or `latency` of an infra service or an app, a
+      fake's `failNext`, `interruptDatabase`) and reads the compensated state back. One more spec runs the saga from the api
+      call to its final state.
+    rationale: |-
+      The compensation exists for the failures; a spec that only runs the happy flow proves nothing about it. A fault injected
+      at the moment the failure event is delivered proves the retry and the resume.
+    cases:
+      - id: case-1
+        when: The order compensation
+        write: 'e2e/order/invoice-rejected.e2e-spec.ts cuts the order database while billing.invoice-rejected is delivered, restores it and asserts the order cancelled, the stock back and the saga run compensated at version 3.'
+    verification:
+      automated:
+        - BE_SAGA_E2E_MISSING
+        - BE_ASYNC_SPEC_MISSING
+      manual:
+        - Check the injected fault hits the compensation, not only the step before it.
+    relatedExamples: [saga]