@starci/hfs 4.0.8 → 4.0.10

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

@@ -0,0 +1,113 @@
+schema: starci/knowledge-source@1
+id: be.domain
+title: Domain capabilities (module family domain)
+purpose: |-
+  Given a business capability (orders, payments, catalog), where does its decision live? In `modules/domain/<capability>/`: services that
+  own the rules, the entities and migrations of its tables on one connection, its errors and its messages. The capability belongs to
+  one bounded context, so everything inside it is synchronous and runs in one transaction; the context talks to other contexts only
+  through events. Features reach it through its public `index.ts`.
+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/services.yaml
+    - knowledge/patterns/be/persistence.yaml
+    - knowledge/patterns/be/event-bus.yaml
+    - owner decision 2026-10-02 (bounded contexts)
+  limitations: |-
+    Static checks prove the folder shape, the one connection per context, the coupling between contexts and the one-transaction rule. They do
+    not prove that a rule is the right business rule; the service specs and the e2e run do.
+rules:
+  - id: BE-DOMAIN-1
+    title: A capability owns its rules, its tables and its transaction
+    kind: mandatory
+    hfsRules: [R175, R176, R174, R30]
+    requirement: |-
+      A capability folder holds `index.ts`, `<capability>.module.ts`, `<capability>.service.ts` with its `<capability>.service.spec.ts` beside it,
+      `<capability>.contracts.ts`, `errors/`, `messages/` and `persistence/` (its entities, migrations, SQL and rows on the connection of its
+      context). A service opens one transaction on that connection and publishes its events inside it (`eventBus.publish(event, tx)`, event-bus.yaml).
+      No relation, foreign key or import reaches a capability of another context; contexts are coupled by events only.
+    rationale: |-
+      A capability that owns its rules and its tables can change them without asking another team, and a transaction that touches one connection
+      stays atomic.
+    cases:
+      - id: case-1
+        when: Order and payment must agree
+        write: 'The payment service commits its row and publishes PaymentSettledEvent in one transaction; an order reactor consumes it and the order service updates its own copy.'
+    verification:
+      automated:
+        - BE_CONTEXT_COUPLING
+        - BE_CONTEXT_TRANSACTION
+        - BE_CONTEXT_OWNER
+        - BE_PUBLIC_SURFACE
+        - ARCH_OWNER_EXPORT_BYPASS
+        - ARCH_OWNER_EXPORT_STAR
+        - HFS_ALIAS_REEXPORT
+        - ARCH_PACKAGE_EXPORT_BYPASS
+      manual:
+        - Confirm the capability is named after the business capability, not after a technical layer.
+    relatedExamples: [domain]
+  - id: BE-DOMAIN-2
+    title: Work inside one context is synchronous; an event crosses contexts or starts async work
+    kind: mandatory
+    hfsRules: [R152, R175]
+    requirement: |-
+      A handler that needs another capability of the same context calls its service in the same transaction and no event exists for it. An event is
+      published only when another context must react or when the work it starts is asynchronous by nature (a job, a saga step, a reactor, a projection
+      recompute), and only from a domain service inside its transaction.
+    rationale: |-
+      An event inside one context adds a delivery that can fail between two writes the transaction would have made atomic.
+    cases:
+      - id: case-1
+        when: Checkout reserves stock in the same context
+        write: 'The order service calls the catalog service in its transaction; PlacementCompletedEvent is published only for the billing context.'
+    verification:
+      automated:
+        - BE_OUTBOX_WRITE_TX
+        - BE_CONTEXT_COUPLING
+      manual:
+        - Confirm no published event is consumed by the context that published it only to tell itself something.
+    relatedExamples: [domain]
+files:
+  - path: src/modules/domain/<capability>/index.ts
+    slot: be.domain
+    role: The public surface (services, contracts, errors and the entity and migration arrays), never an entity class used elsewhere.
+    rules: [BE_PUBLIC_SURFACE]
+  - path: src/modules/domain/<capability>/<capability>.module.ts
+    slot: be.domain
+    role: Registers the services of the capability.
+  - path: src/modules/domain/<capability>/<capability>.service.ts
+    slot: be.domain
+    role: The rules, in one transaction on the connection of the context.
+    rules: [BE_CONTEXT_TRANSACTION, BE_OUTBOX_WRITE_TX]
+  - path: src/modules/domain/<capability>/<capability>.service.spec.ts
+    slot: be.domain
+    role: The unit spec beside the service, with a few mocks.
+  - path: src/modules/domain/<capability>/<capability>.contracts.ts
+    slot: be.domain
+    role: The plain types the service takes and returns.
+  - path: src/modules/domain/<capability>/errors/<capability>.error.ts
+    slot: be.errors
+    role: The error family of the capability.
+  - path: src/modules/domain/<capability>/messages/<capability>.messages.ts
+    slot: be.domain.messages
+    role: The keyed vi and en text of the capability.
+  - path: src/modules/domain/<capability>/persistence/connection.ts
+    slot: be.persistence
+    role: The entity and migration arrays the apps register on the connection of the context.
+  - path: src/modules/domain/<capability>/persistence/entities/<table>.entity.ts
+    slot: be.persistence
+    role: One table of the capability; no relation to another context.
+    rules: [BE_CONTEXT_COUPLING]
+  - path: src/modules/domain/<capability>/persistence/migrations/<epochMs13>-<name>.ts
+    slot: be.persistence
+    role: One migration; no foreign key onto another context.
+    rules: [BE_CONTEXT_COUPLING]
+  - path: src/modules/domain/<capability>/persistence/<name>.sql.ts
+    slot: be.persistence
+    role: The statements of the capability, one owner per table.

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

@@ -0,0 +1,285 @@
+schema: starci/knowledge-source@1
+id: be.event-bus
+title: Event bus
+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,
+  relay, Kafka, consumer with retry and dead letter. `platform/event-bus` is the one owner and the only importer of `kafkajs`.
+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.events, be.platform.event-bus]
+pattern: event-bus
+provenance:
+  reviewedAt: 2026-10-02
+  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))
+    - 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
+    id. They do not prove broker configuration, partition keys, schema evolution or the operational handling of a dead letter;
+    the test-world scenarios (`event-bus/*`) prove the delivery behaviour against a real broker.
+rules:
+  - id: BE-EVENT-BUS-1
+    title: Inside one context nothing is an event
+    kind: mandatory
+    hfsRules: [R152, R26]
+    requirement: |-
+      Work that stays inside one context (one connection, one set of tables) is synchronous: the handler dispatches to that
+      context's domain service, which does the whole change in one transaction. No event, no queue and no bus is involved, and a
+      caller that needs the result reads it from the return value. A fact is published as an event only when (a) another context
+      must react to it, or (b) the work it triggers is asynchronous by nature (a job, a saga step, a reactor, a projection
+      refresh). One transaction touches one context's connection only.
+    rationale: |-
+      An event inside one context buys eventual consistency, a failure mode and a broker round trip for work the transaction
+      already makes atomic. Events are the price of crossing a boundary, not a style.
+    cases:
+      - id: case-1
+        when: 'A buyer adds an item to the cart (same context, the answer is needed now)'
+        write: 'add-cart-item.handler.ts dispatches to CartService.addItem, which updates the cart rows in one transaction and returns the cart. No event. (passing)'
+      - id: case-2
+        when: 'Order needs to know whether a payment settled (payment is another context)'
+        write: 'Order never reads the payment tables or imports the payment service. PaymentService publishes PaymentSettledEvent in its transaction; an order reactor keeps a local copy of the status, or a projection serves the read. (a direct read is the violation)'
+    verification:
+      automated:
+        - BE_OUTBOX_WRITE_TX
+        - BE_TIER_DIRECTION
+        - FE_TIER_DIRECTION
+        - ARCH_PACKAGE_IMPORTS_APP
+      manual:
+        - Confirm each published event crosses a context or starts asynchronous work, and no handler publishes to tell itself something.
+    relatedExamples: [event-bus]
+  - id: BE-EVENT-BUS-2
+    title: An event is a typed class that equals its vendored contract
+    kind: mandatory
+    hfsRules: [R151]
+    requirement: |-
+      Events are classes in `be/src/modules/events/<service>/<event>.event.ts`, one per file, named after the event
+      (`order.placed` is `order-placed.event.ts`): a class extending the platform `BaseEvent` with literal
+      `static readonly eventName` and `static readonly version`, a payload typed in the class, a `create()` that builds it
+      and a `parse()` that reads a delivered payload back. Each class is an entry of the vendored contract
+      `be/contracts/<service>/events.json` at the same name and version and every contract entry has its class. Schemas
+      evolve only additively; a breaking change is a new event name (`<event>.v2`).
+    rationale: |-
+      The class is what the publisher and the consumer compile against; the contract is what another service pins. Two
+      sources of truth drift, so a check holds them equal.
+    cases:
+      - id: case-1
+        when: A new event
+        write: 'modules/events/order/order-placed.event.ts with eventName "order.placed" and version 1, then `starci app emit` so be/contracts/order/events.json lists it.'
+    verification:
+      automated:
+        - BE_EVENT_CLASS_CONTRACT
+      manual:
+        - Confirm a payload change is additive.
+    relatedExamples: [event-bus]
+  - id: BE-EVENT-BUS-3
+    title: Publish through the bus, in the domain transaction, to Kafka only
+    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) })`).
+      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`.
+    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) })'
+    verification:
+      automated:
+        - BE_OUTBOX_WRITE_TX
+        - BE_INFRA_OWNER
+        - BE_CQRS_SHAPE
+        - BE_READONLY_BOUNDARY
+      manual: []
+    relatedExamples: [event-bus]
+  - id: BE-EVENT-BUS-4
+    title: A consumer is a thin door; delivery is at least once with retry and a dead letter
+    kind: mandatory
+    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
+      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
+      and requeues through `eventBus.deadLetters(event)` and `eventBus.requeue(id)` (a cli command). `eventBus.pendingRetries(event)`
+      lets a failure-injection spec wait for a retry.
+    rationale: |-
+      A claim persisted before the handler finishes would lose the event on a crash; claiming in the effect's transaction makes
+      the effect and the claim one atomic fact.
+    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, ... } })) }'
+    verification:
+      automated:
+        - BE_EVENT_CONSUMER_SHAPE
+        - BE_INBOX_DEDUPE_MISSING
+      manual:
+        - Confirm the retry budget and backoff fit the consumer's side effects.
+    relatedExamples: [event-bus]
+  - id: BE-EVENT-BUS-5
+    title: A declared event bus is proven on the test world
+    kind: mandatory
+    hfsRules: [R155]
+    requirement: |-
+      An app that declares the pattern (`hfs.json` `sides.be.patterns: ["event-bus"]`) has e2e or integration tests, titled
+      `event-bus/<scenario>: ...`, for each scenario of `ruleParams.be.patternScenarios.event-bus`, run against a real Kafka:
+      `atomic-with-transaction` (the outbox row exists exactly when the domain change commits), `relay-only-after-commit` (nothing is
+      published for a rolled-back transaction), `redelivery-then-dead-letter` (a failing consumer is retried, then buried) and
+      `duplicate-delivery-is-a-noop` (a redelivered event changes nothing twice).
+    rationale: |-
+      Delivery behaviour is not visible to a linter; a real broker run is the only proof.
+    cases:
+      - id: case-1
+        when: The order e2e suite
+        write: "it('event-bus/atomic-with-transaction: the row commits with the order', ...)"
+    verification:
+      automated:
+        - BE_PATTERN_SPEC_MISSING
+      manual: []
+    relatedExamples: [event-bus]
+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/event-bus/errors/event-bus.error.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/errors/event-bus.error.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.config.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-bus.config.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.contracts.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-bus.contracts.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.decorators.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-bus.decorators.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.log-events.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-bus.log-events.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.module-definition.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-bus.module-definition.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.module.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-bus.module.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.options.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-bus.options.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.port.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-bus.port.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.service.spec.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-bus.service.spec.ts.tpl
+  - path: src/modules/platform/event-bus/event-bus.service.ts
+    slot: be.platform.event-bus
+    role: "publish (outbox write through tx), dead letters, requeue, pending retries."
+    template: event-bus/platform/event-bus.service.ts.tpl
+  - path: src/modules/platform/event-bus/event-envelope.policy.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-envelope.policy.ts.tpl
+  - path: src/modules/platform/event-bus/event-envelope.policy.spec.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-envelope.policy.spec.ts.tpl
+  - path: src/modules/platform/event-bus/event-relay.service.spec.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-relay.service.spec.ts.tpl
+  - path: src/modules/platform/event-bus/event-relay.service.ts
+    slot: be.platform.event-bus
+    role: "Relay of committed outbox rows to Kafka, per registered connection."
+    template: event-bus/platform/event-relay.service.ts.tpl
+  - path: src/modules/platform/event-bus/event-runner.service.spec.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-runner.service.spec.ts.tpl
+  - path: src/modules/platform/event-bus/event-runner.service.ts
+    slot: be.platform.event-bus
+    role: "Consumer registry and Kafka read loop with retry and dead letter."
+    template: event-bus/platform/event-runner.service.ts.tpl
+  - path: src/modules/platform/event-bus/event-transport.port.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event-transport.port.ts.tpl
+  - path: src/modules/platform/event-bus/event.policy.ts
+    slot: be.platform.event-bus
+    role: "Topics, attempts and backoff."
+    template: event-bus/platform/event.policy.ts.tpl
+  - path: src/modules/platform/event-bus/event.policy.spec.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/event.policy.spec.ts.tpl
+  - path: src/modules/platform/event-bus/index.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/index.ts.tpl
+  - path: src/modules/platform/event-bus/kafka-event-transport.client.ts
+    slot: be.platform.event-bus
+    role: "The one kafkajs importer."
+    template: event-bus/platform/kafka-event-transport.client.ts.tpl
+  - path: src/modules/platform/event-bus/kafka-event-transport.client.spec.ts
+    slot: be.platform.event-bus
+    template: event-bus/platform/kafka-event-transport.client.spec.ts.tpl
+  - path: src/modules/platform/event-bus/messages/event-bus.messages.ts
+    slot: be.domain.messages
+    template: event-bus/platform/messages/event-bus.messages.ts.tpl
+  - path: src/modules/platform/event-bus/persistence/connection.ts
+    slot: be.persistence
+    template: event-bus/platform/persistence/connection.ts.tpl
+  - path: src/modules/platform/event-bus/persistence/entities/event-outbox.entity.ts
+    slot: be.persistence
+    template: event-bus/platform/persistence/entities/event-outbox.entity.ts.tpl
+  - path: src/modules/platform/event-bus/persistence/event-bus.rows.ts
+    slot: be.persistence
+    template: event-bus/platform/persistence/event-bus.rows.ts.tpl
+  - path: src/modules/platform/event-bus/persistence/event-bus.sql.ts
+    slot: be.persistence
+    template: event-bus/platform/persistence/event-bus.sql.ts.tpl
+  - path: src/modules/platform/event-bus/persistence/migrations/<epochMs13>-create-event-outbox.ts
+    slot: be.persistence
+    template: event-bus/platform/persistence/migrations/1789800009000-create-event-outbox.ts.tpl
+  - path: src/modules/events/<service>/index.ts
+    slot: be.events
+  - path: src/modules/events/<service>/<event>.event.ts
+    slot: be.events
+    role: One typed event class.
+    rules: [BE_EVENT_CLASS_CONTRACT]
+  - path: contracts/<service>/events.json
+    slot: be.contract.events
+    role: The emitted catalog of the service events (name, version, payload shape); the event classes equal it, so a consumer in another service reads one contract.
+    rules: [BE_EVENT_CLASS_CONTRACT]
+  - path: src/features/<kind>/<feature>/transport/message/<event>.consumer.ts
+    slot: be.transport.message
+    role: The consumer door of one event.
+    rules: [BE_EVENT_CONSUMER_SHAPE]
+  - path: src/features/<kind>/<feature>/transport/message/<feature>-message.module.ts
+    slot: be.transport.message
+    role: Registers the consumers with the registry.
+  - path: src/tests/e2e/<area>/<event>.e2e-spec.ts
+    slot: be.tests.e2e
+    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]

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

@@ -0,0 +1,261 @@
+schema: starci/knowledge-source@1
+id: be.jobs
+title: Fenced background jobs
+purpose: |-
+  Given work that runs in the background and must survive a worker that stalls, restarts or is replaced, how is it claimed and
+  settled? A job is a row whose `fencingToken` the claim bumps. Every write on a claimed job carries the token the writer holds and
+  is refused when it is stale, so a zombie worker (one that lost its claim but kept running) changes nothing, and every external
+  effect carries a run key that includes the token, so the provider drops a repeat. `platform/jobs` is the one owner of the row.
+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.feature.jobs.steps, be.platform.jobs]
+pattern: fenced-job
+provenance:
+  reviewedAt: 2026-10-02
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - knowledge/hfs/rules.yaml
+    - owner decision 2026-10-02 (fenced jobs with a required fencing token)
+    - https://martin.kleppmann.com/2016/02/08/how-to-do-distributed-locking.html
+  limitations: |-
+    Static checks prove who writes the job row, that the token is required in the type and not cast around, that effects carry a
+    run key and that a processor has the fenced base. They do not prove that the provider honours the idempotency key or that a
+    step is safe to repeat; the test-world scenarios (`fenced-job/*`) prove the zombie and re-dispatch behaviour against real
+    Postgres and a double of the provider.
+rules:
+  - id: BE-JOBS-1
+    title: The job row has one owner and one atomic claim
+    kind: mandatory
+    hfsRules: [R157, R86]
+    requirement: |-
+      `modules/platform/jobs` holds the job entity (`id`, `kind`, `status`, `currentStep`, `fencingToken`, `claimedBy`,
+      `leaseExpiresAt`, `payload`, a unique `jobKey`), `job-claim.service.ts` and the persistence of the table. `claim()` is one
+      atomic upsert keyed by the delivery (`INSERT ... ON CONFLICT (job_key) DO UPDATE SET fencing_token = jobs.fencing_token + 1 ... WHERE
+      status = 'failed' OR the lease expired ... RETURNING`, a `SqlText` constant): the job row is created by its first claim, the token is
+      bumped by the store and returned, and a done job or a live claim matches nothing. `JobRunnerService` calls it for every BullMQ
+      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.
+    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'
+    verification:
+      automated:
+        - BE_JOB_WRITE_OUTSIDE_OWNER
+        - BE_SQL_TABLE_OWNER
+      manual:
+        - Confirm the claim SQL is a single statement and the lease length fits the longest step.
+    relatedExamples: [fenced-job]
+  - id: BE-JOBS-2
+    title: Every write to a claimed job carries expectedFencingToken, required in the type
+    kind: mandatory
+    hfsRules: [R158]
+    requirement: |-
+      `JobClaims.advance`, `complete` and `fail` take `GuardedWrite & {...}` where `GuardedWrite = { jobId: string; expectedFencingToken: number }`:
+      the token is required, never optional or nullable, and a call never passes it through `as`, `!` or `any`. Each write is
+      `UPDATE ... WHERE id = $1 AND fencing_token = $2`; zero rows updated throws `JobFencedOut` and the worker stops with no
+      further effect. A step or processor never catches around a guarded write: the `FencedProcessor` base owns the failure path.
+    rationale: |-
+      An optional guard is a guard some caller forgets. The token is checked atomically by the store that accepts the write, which
+      is the only place a stale worker can be refused.
+    cases:
+      - id: case-1
+        when: A step finishes
+        write: 'await this.claims.advance({ jobId: job.jobId, expectedFencingToken: job.fencingToken, step: "send" })'
+    verification:
+      automated:
+        - BE_JOB_FENCE_REQUIRED
+      manual: []
+    relatedExamples: [fenced-job]
+  - id: BE-JOBS-3
+    title: An external effect carries a run key that includes the token
+    kind: mandatory
+    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
+      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.
+    rationale: |-
+      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"))'
+    verification:
+      automated:
+        - BE_JOB_RUN_KEY
+      manual:
+        - Confirm the provider documents idempotent handling of its key.
+    relatedExamples: [fenced-job]
+  - id: BE-JOBS-4
+    title: A job is a processor plus steps, started by a producer and run by a worker or api app
+    kind: mandatory
+    hfsRules: [R160, R156, R46, R203]
+    requirement: |-
+      `features/jobs/<job>/transport/queue/<job>.processor.ts` declares a class extending `FencedProcessor` (it claims, calls `process(job)` and
+      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
+      (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: |-
+      One place and one base class mean a job cannot skip the fence, and the kind boundary keeps a long job from running inside a
+      request.
+    cases:
+      - id: case-1
+        when: A new background job send-receipt
+        write: 'features/jobs/send-receipt/{transport/queue/send-receipt.processor.ts, transport/queue/send-receipt-queue.module.ts, send-receipt.module.ts, steps/mail.step.ts, application/send-receipt.command.ts}'
+    verification:
+      automated:
+        - BE_JOB_SHAPE
+        - BE_KIND_ISOLATION
+        - BE_BACKGROUND_UNOWNED
+        - BE_FEATURE_THIN
+      manual:
+        - Confirm each step is one external effect that is safe to repeat under the same run key.
+    relatedExamples: [fenced-job]
+  - id: BE-JOBS-5
+    title: A declared fenced-job is proven on the test world
+    kind: mandatory
+    hfsRules: [R155]
+    requirement: |-
+      An app that declares `fenced-job` has tests titled `fenced-job/<scenario>: ...` for `claim-bumps-token`,
+      `zombie-fenced-out` (a worker with a stale token gets `JobFencedOut` and the external double sees zero calls) and
+      `redispatch-isolated` (a re-dispatch claims a higher token, the old worker's write is refused and the new run's effects carry
+      their own run key), run on the test world with real Postgres.
+    rationale: |-
+      The fence is a runtime property; only a paused old worker resuming after reassignment shows it holds.
+    cases:
+      - id: case-1
+        when: The send-receipt e2e suite
+        write: "it('fenced-job/zombie-fenced-out: the stale worker changes nothing', ...)"
+    verification:
+      automated:
+        - BE_PATTERN_SPEC_MISSING
+      manual: []
+    relatedExamples: [fenced-job]
+files:
+  - path: src/modules/platform/jobs/index.ts
+    slot: be.platform.jobs
+    role: "Public surface of the capability."
+    template: jobs/platform/jobs.index.ts.tpl
+  - path: src/modules/platform/jobs/jobs.module.ts
+    slot: be.platform.jobs
+    role: "Dynamic module registered once per app that runs jobs, over the connection that holds the job table."
+    template: jobs/platform/jobs.module.ts.tpl
+  - path: src/modules/platform/jobs/jobs.module-definition.ts
+    slot: be.platform.jobs
+    template: jobs/platform/jobs.module-definition.ts.tpl
+  - path: src/modules/platform/jobs/jobs.options.ts
+    slot: be.platform.jobs
+    template: jobs/platform/jobs.options.ts.tpl
+  - path: src/modules/platform/jobs/jobs.config.ts
+    slot: be.platform.jobs
+    template: jobs/platform/jobs.config.ts.tpl
+  - path: src/modules/platform/jobs/jobs.decorators.ts
+    slot: be.platform.jobs
+    role: "InjectJobClaims, InjectJobProcessorRegistry and their tokens."
+    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."
+    template: jobs/platform/jobs.contracts.ts.tpl
+  - path: src/modules/platform/jobs/jobs.port.ts
+    slot: be.platform.jobs
+    role: "JobClaims, JobStep and JobProcessorRegistry ports."
+    rules: [BE_JOB_FENCE_REQUIRED]
+    template: jobs/platform/jobs.port.ts.tpl
+  - path: src/modules/platform/jobs/job-claim.service.ts
+    slot: be.platform.jobs
+    role: "The claim and the guarded writes; the only writer of the job row."
+    rules: [BE_JOB_WRITE_OUTSIDE_OWNER]
+    template: jobs/platform/job-claim.service.ts.tpl
+  - path: src/modules/platform/jobs/job-claim.service.spec.ts
+    slot: be.platform.jobs
+    template: jobs/platform/job-claim.service.spec.ts.tpl
+  - path: src/modules/platform/jobs/job-runner.service.ts
+    slot: be.platform.jobs
+    role: "Subscribes processors to their queues; claim, process, complete or fail, fenced out means stop."
+    template: jobs/platform/job-runner.service.ts.tpl
+  - path: src/modules/platform/jobs/job-runner.service.spec.ts
+    slot: be.platform.jobs
+    template: jobs/platform/job-runner.service.spec.ts.tpl
+  - path: src/modules/platform/jobs/fenced.processor.ts
+    slot: be.platform.jobs
+    role: "The base class every processor extends."
+    template: jobs/platform/fenced.processor.ts.tpl
+  - path: src/modules/platform/jobs/fenced.processor.spec.ts
+    slot: be.platform.jobs
+    template: jobs/platform/fenced.processor.spec.ts.tpl
+  - path: src/modules/platform/jobs/jobs.log-events.ts
+    slot: be.platform.jobs
+    template: jobs/platform/jobs.log-events.ts.tpl
+  - path: src/modules/platform/jobs/errors/jobs.error.ts
+    slot: be.platform.jobs
+    role: "JobFencedOut."
+    template: jobs/platform/jobs.error.ts.tpl
+  - path: src/modules/platform/jobs/messages/jobs.messages.ts
+    slot: be.domain.messages
+    template: jobs/platform/jobs.messages.ts.tpl
+  - path: src/modules/platform/jobs/persistence/connection.ts
+    slot: be.persistence
+    role: "The job entity array registered on every connection that runs jobs."
+    template: jobs/platform/persistence.connection.ts.tpl
+  - path: src/modules/platform/jobs/persistence/entities/job.entity.ts
+    slot: be.persistence
+    template: jobs/platform/persistence.job.entity.ts.tpl
+  - path: src/modules/platform/jobs/persistence/jobs.sql.ts
+    slot: be.persistence
+    role: "The claim and guarded-write statements as SqlText constants."
+    template: jobs/platform/persistence.jobs.sql.ts.tpl
+  - path: src/modules/platform/jobs/persistence/jobs.rows.ts
+    slot: be.persistence
+    template: jobs/platform/persistence.jobs.rows.ts.tpl
+  - path: src/modules/platform/jobs/persistence/migrations/<epochMs13>-create-jobs.ts
+    slot: be.persistence
+    template: jobs/platform/persistence.migration.ts.tpl
+  - path: src/features/jobs/<job>/index.ts
+    slot: be.feature.jobs
+    template: jobs/job.index.ts.tpl
+  - path: src/features/jobs/<job>/<job>.module.ts
+    slot: be.feature.jobs
+    template: jobs/job.module.ts.tpl
+  - path: src/features/jobs/<job>/transport/queue/<job>-queue.module.ts
+    slot: be.feature.jobs.queue
+    template: jobs/job.queue.module.ts.tpl
+    role: The queue transport module of the job; composed by an api or worker app, registers the processor.
+  - path: src/features/jobs/<job>/transport/queue/<job>.processor.ts
+    slot: be.feature.jobs.queue
+    template: jobs/job.processor.ts.tpl
+    role: 'The processor of one job; extends FencedProcessor — thin (R203 `BE_FEATURE_THIN`): `process` maps the claimed job and delegates into modules/.'
+    rules: [BE_JOB_SHAPE]
+  - 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.'
+    rules: [BE_JOB_SHAPE, BE_JOB_RUN_KEY]
+  - path: src/features/jobs/<job>/application/<action>.command.ts
+    slot: be.feature.application
+    optional: true
+  - path: src/features/jobs/<job>/application/<action>.handler.ts
+    slot: be.feature.application
+    optional: true
+  - path: src/features/jobs/<job>/application/<action>.contracts.ts
+    slot: be.feature.application
+    optional: true
+  - path: src/tests/e2e/<area>/<job>.e2e-spec.ts
+    slot: be.tests.e2e
+    role: "Titles fenced-job/<scenario>: ... prove the pattern."
+    spec: fenced-job/claim-bumps-token, fenced-job/zombie-fenced-out, fenced-job/redispatch-isolated
+    rules: [BE_PATTERN_SPEC_MISSING]