@starci/hfs 4.0.8 → 4.0.10

package/templates/be/patterns/event-bus/platform/persistence/event-bus.sql.ts.tpl

@@ -0,0 +1,12 @@
+import { sql } from "@modules/platform/database"
+
+/** Writes one event in the outbox ($1 event id, $2 event name, $3 topic, $4 key, $5 envelope, $6 instant). */
+export const INSERT_OUTBOX_ROW = sql`INSERT INTO event_outbox (event_id, event_name, topic, message_key, envelope, created_at)
+    VALUES ($1, $2, $3, $4, $5, $6)`
+
+/** Locks and reads the oldest rows that wait ($1 batch size); a second relay skips the rows this one holds. */
+export const SELECT_WAITING_ROWS = sql`SELECT id, topic, message_key, envelope FROM event_outbox
+    WHERE sent_at IS NULL ORDER BY id LIMIT $1 FOR UPDATE SKIP LOCKED`
+
+/** Marks the rows as handed to the broker ($1 ids, $2 instant). */
+export const MARK_ROWS_SENT = sql`UPDATE event_outbox SET sent_at = $2 WHERE id = ANY($1::bigint[])`

package/templates/be/patterns/event-bus/platform/persistence/migrations/1789800009000-create-event-outbox.ts.tpl

@@ -0,0 +1,26 @@
+import type { MigrationInterface, QueryRunner } from "typeorm"
+
+/** Creates the outbox table the event bus writes events in and the relay reads them from. */
+export class CreateEventOutbox@@epochMs13@@ implements MigrationInterface {
+    name = "CreateEventOutbox@@epochMs13@@"
+
+    /** Creates the outbox and the partial index of the rows that wait. */
+    async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE TABLE event_outbox (
+    id bigserial PRIMARY KEY,
+    event_id varchar(200) NOT NULL,
+    event_name varchar(200) NOT NULL,
+    topic varchar(200) NOT NULL,
+    message_key varchar(200) NOT NULL,
+    envelope jsonb NOT NULL,
+    created_at timestamptz NOT NULL,
+    sent_at timestamptz
+)`)
+        await queryRunner.query(`CREATE INDEX event_outbox_unsent_idx ON event_outbox (id) WHERE sent_at IS NULL`)
+    }
+
+    /** Drops the outbox. */
+    async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP TABLE event_outbox`)
+    }
+}

package/templates/be/patterns/jobs/job.index.ts.tpl

@@ -0,0 +1 @@
+export { @@Job@@QueueModule } from "./transport/queue/@@job@@-queue.module"

package/templates/be/patterns/jobs/job.module.ts.tpl

@@ -0,0 +1,6 @@
+import { Module } from "@nestjs/common"
+import { @@Step@@Step } from "./steps/@@step@@.step"
+
+@Module({ providers: [@@Step@@Step], exports: [@@Step@@Step] })
+/** The application of the @@job@@ job: its steps; the queue transport module imports it. */
+export class @@Job@@Module {}

package/templates/be/patterns/jobs/job.processor.ts.tpl

@@ -0,0 +1,20 @@
+import { Injectable } from "@nestjs/common"
+import { FencedProcessor } from "@modules/platform/jobs"
+import type { ClaimedJob } from "@modules/platform/jobs"
+import { @@jobUpper@@_QUEUE } from "@modules/queues/@@job@@"
+import { @@Step@@Step } from "../../steps/@@step@@.step"
+
+@Injectable()
+/** The processor of the @@job@@ job: the runner claims and settles, `process` runs the steps in order. */
+export class @@Job@@Processor extends FencedProcessor {
+    readonly queue = @@jobUpper@@_QUEUE
+
+    constructor(private readonly @@stepCamel@@Step: @@Step@@Step) {
+        super()
+    }
+
+    /** Runs the steps of the job; a stale token makes a guarded write throw `JobFencedOut` and nothing else happens. */
+    async process(job: ClaimedJob): Promise<void> {
+        await this.@@stepCamel@@Step.run(job)
+    }
+}

package/templates/be/patterns/jobs/job.queue.module.ts.tpl

@@ -0,0 +1,20 @@
+import { Module } from "@nestjs/common"
+import type { OnModuleInit } from "@nestjs/common"
+import { InjectJobProcessorRegistry } from "@modules/platform/jobs"
+import type { JobProcessorRegistry } from "@modules/platform/jobs"
+import { @@Job@@Module } from "../../@@job@@.module"
+import { @@Job@@Processor } from "./@@job@@.processor"
+
+@Module({ imports: [@@Job@@Module], providers: [@@Job@@Processor] })
+/** The queue transport of the @@job@@ job: its processor, which a worker or api app composes and which subscribes to its queue when the module starts. */
+export class @@Job@@QueueModule implements OnModuleInit {
+    constructor(
+        @InjectJobProcessorRegistry() private readonly registry: JobProcessorRegistry,
+        private readonly @@jobCamel@@Processor: @@Job@@Processor,
+    ) {}
+
+    /** Hands the processor to the registry. */
+    onModuleInit(): void {
+        this.registry.add(this.@@jobCamel@@Processor)
+    }
+}

package/templates/be/patterns/jobs/job.step.ts.tpl

@@ -0,0 +1,19 @@
+import { Injectable } from "@nestjs/common"
+import { InjectJobClaims } from "@modules/platform/jobs"
+import type { ClaimedJob, JobClaims, JobStep } from "@modules/platform/jobs"
+
+@Injectable()
+/** One external effect of the @@job@@ job. */
+export class @@Step@@Step implements JobStep {
+    constructor(@InjectJobClaims() private readonly claims: JobClaims) {}
+
+    /**
+     * Records the step with the token this worker holds FIRST, so a stale token stops here before any effect; then makes the
+     * one delegating call the step is allowed (R203 `BE_FEATURE_THIN`), handing the module service the payload as delivered
+     * and the run key of this claim. Reading the payload, guarding it and sequencing the effect are the service's.
+     */
+    async run(job: ClaimedJob): Promise<void> {
+        await this.claims.advance({ jobId: job.jobId, expectedFencingToken: job.fencingToken, step: "@@step@@" })
+        // The one delegating call: the module service takes `job.payload` and `this.claims.runKey(job, "@@step@@")` as the idempotency key of the effect.
+    }
+}

package/templates/be/patterns/jobs/platform/fenced.processor.spec.ts.tpl

@@ -0,0 +1,31 @@
+import type { ClaimedJob } from "./jobs.contracts"
+import { FencedProcessor } from "./fenced.processor"
+
+const claimedJob: ClaimedJob = {
+    jobId: "job-1",
+    kind: "mail",
+    fencingToken: 3,
+    currentStep: null,
+    payload: { messageId: "message-1" },
+}
+
+class MailProcessor extends FencedProcessor {
+    readonly queue = "mail"
+    readonly processed: Array<ClaimedJob> = []
+
+    process(job: ClaimedJob): Promise<void> {
+        this.processed.push(job)
+        return Promise.resolve()
+    }
+}
+
+describe("FencedProcessor", () => {
+    it("lets a processor declare its queue and process a claimed job", async () => {
+        const processor = new MailProcessor()
+
+        await processor.process(claimedJob)
+
+        expect(processor.queue).toBe("mail")
+        expect(processor.processed).toEqual([claimedJob])
+    })
+})

package/templates/be/patterns/jobs/platform/fenced.processor.ts.tpl

@@ -0,0 +1,13 @@
+import type { ClaimedJob } from "./jobs.contracts"
+
+/**
+ * The base of every job processor. The runner claims the delivery with a bumped fencing token, calls `process`, and settles the job
+ * through the guarded writes, so a processor holds only what its job does and never touches the job row.
+ */
+export abstract class FencedProcessor {
+    /** The queue this processor consumes: the `<QUEUE>_QUEUE` constant of its `modules/queues/<queue>`. */
+    abstract readonly queue: string
+
+    /** Runs the job; a throw fails this delivery and BullMQ retries it. */
+    abstract process(job: ClaimedJob): Promise<void>
+}

package/templates/be/patterns/jobs/platform/job-claim.service.spec.ts.tpl

@@ -0,0 +1,150 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock, mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { JobsError, JobsErrorCode } from "./errors/jobs.error"
+import type { ClaimedJob } from "./jobs.contracts"
+import { JOBS_MANAGERS } from "./jobs.decorators"
+import { JobClaimService } from "./job-claim.service"
+import { ADVANCE_JOB, CLAIM_JOB, COMPLETE_JOB, FAIL_JOB } from "./persistence/jobs.sql"
+
+const AT = "2026-02-03T04:05:06.000Z"
+
+const build = async (manager: MockEntityManager) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            JobClaimService,
+            { provide: JOBS_MANAGERS, useValue: [manager] },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+        ],
+    }).compile()
+    return { claims: moduleRef.get(JobClaimService) }
+}
+
+const buildWithoutConnection = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            JobClaimService,
+            { provide: JOBS_MANAGERS, useValue: [] },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+        ],
+    }).compile()
+    return { claims: moduleRef.get(JobClaimService) }
+}
+
+const claimed: ClaimedJob = { jobId: "j-1", kind: "mail", fencingToken: 3, currentStep: null, payload: { id: "m-1" } }
+
+describe("JobClaimService", () => {
+    describe("claim", () => {
+        it("claims the delivery in one statement and returns the job with the bumped token", async () => {
+            const manager = mockEntityManager({
+                query: [
+                    CLAIM_JOB,
+                    [{ id: "j-1", kind: "mail", fencing_token: "3", current_step: null, payload: { id: "m-1" } }],
+                ],
+            })
+            const { claims } = await build(manager)
+
+            const job = await claims.claim({
+                kind: "mail",
+                jobKey: "k-1",
+                payload: { id: "m-1" },
+                workerId: "w-1",
+                leaseMs: 60000,
+            })
+
+            expect(job).toEqual(claimed)
+            expect(manager.query).toHaveBeenCalledWith(CLAIM_JOB, [
+                "mail",
+                "k-1",
+                "w-1",
+                new Date("2026-02-03T04:06:06.000Z"),
+                JSON.stringify({ id: "m-1" }),
+                new Date(AT),
+            ])
+        })
+
+        it("answers null when the job is done or another worker holds a live claim", async () => {
+            const manager = mockEntityManager({ query: [CLAIM_JOB, []] })
+            const { claims } = await build(manager)
+
+            await expect(
+                claims.claim({ kind: "mail", jobKey: "k-1", payload: {}, workerId: "w-1", leaseMs: 1000 }),
+            ).resolves.toBeNull()
+        })
+    })
+
+    describe("guarded writes", () => {
+        it("records a step, completes and fails under the token the caller holds", async () => {
+            const manager = mockEntityManager({
+                query: [
+                    [ADVANCE_JOB, [{ id: "j-1" }]],
+                    [COMPLETE_JOB, [{ id: "j-1" }]],
+                    [FAIL_JOB, [{ id: "j-1" }]],
+                ],
+            })
+            const { claims } = await build(manager)
+
+            await claims.advance({ jobId: "j-1", expectedFencingToken: 3, step: "send" })
+            await claims.complete({ jobId: "j-1", expectedFencingToken: 3 })
+            await claims.fail({ jobId: "j-1", expectedFencingToken: 3, reason: "boom" })
+
+            expect(manager.query).toHaveBeenNthCalledWith(1, ADVANCE_JOB, ["j-1", 3, "send", new Date(AT)])
+            expect(manager.query).toHaveBeenNthCalledWith(2, COMPLETE_JOB, ["j-1", 3, new Date(AT)])
+            expect(manager.query).toHaveBeenNthCalledWith(3, FAIL_JOB, ["j-1", 3, "boom", new Date(AT)])
+        })
+
+        it("throws JobFencedOut when a write finds no row at its token: a newer worker owns the job", async () => {
+            const manager = mockEntityManager({
+                query: [
+                    [ADVANCE_JOB, []],
+                    [COMPLETE_JOB, []],
+                    [FAIL_JOB, []],
+                ],
+            })
+            const { claims } = await build(manager)
+
+            const attempts = [
+                claims.advance({ jobId: "j-1", expectedFencingToken: 2, step: "send" }),
+                claims.complete({ jobId: "j-1", expectedFencingToken: 2 }),
+                claims.fail({ jobId: "j-1", expectedFencingToken: 2, reason: "boom" }),
+            ]
+
+            for (const attempt of attempts) {
+                await expect(attempt).rejects.toMatchObject({
+                    code: JobsErrorCode.FencedOut,
+                    params: { jobId: "j-1", token: 2 },
+                })
+                await expect(attempt).rejects.toBeInstanceOf(JobsError)
+            }
+        })
+    })
+
+    describe("runKey", () => {
+        it("includes the job, the step and the fencing token, so a zombie's key differs from the live worker's", async () => {
+            const { claims } = await build(mockEntityManager())
+
+            expect(claims.runKey(claimed, "send")).toBe("j-1:send:3")
+            expect(claims.runKey({ ...claimed, fencingToken: 4 }, "send")).toBe("j-1:send:4")
+        })
+
+        it("refuses a step name that carries the separator, because the key would be ambiguous", async () => {
+            const { claims } = await build(mockEntityManager())
+
+            expect(() => claims.runKey(claimed, "send:twice")).toThrow(JobsError)
+            expect(() => claims.runKey(claimed, "send:twice")).toThrow(JobsErrorCode.RunKeyInvalid)
+        })
+    })
+
+    describe("registration", () => {
+        it("refuses to claim with no connection to hold the job table", async () => {
+            const { claims } = await buildWithoutConnection()
+
+            await expect(
+                claims.claim({ kind: "mail", jobKey: "k-1", payload: {}, workerId: "w-1", leaseMs: 1000 }),
+            ).rejects.toMatchObject({
+                code: JobsErrorCode.ConnectionMissing,
+            })
+        })
+    })
+})

package/templates/be/patterns/jobs/platform/job-claim.service.ts.tpl

@@ -0,0 +1,100 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { JobsError, JobsErrorCode } from "./errors/jobs.error"
+import type { sql } from "@modules/platform/database"
+import { isRunKey } from "./jobs.contracts"
+import type {
+    AdvanceWrite,
+    ClaimedJob,
+    ClaimParams,
+    ClaimResult,
+    FailWrite,
+    GuardedWrite,
+    RunKey,
+} from "./jobs.contracts"
+import { InjectJobsManagers } from "./jobs.decorators"
+import type { JobClaims } from "./jobs.port"
+import { ADVANCE_JOB, CLAIM_JOB, COMPLETE_JOB, FAIL_JOB } from "./persistence/jobs.sql"
+import type { ClaimedRow } from "./persistence/jobs.rows"
+
+@Injectable()
+/**
+ * The one owner of the job row. A claim is one atomic upsert that bumps the fencing token in the store, so two workers can never
+ * hold the same token; every other write is `WHERE fencing_token = <expected>`, so a worker that lost its claim (a zombie) changes
+ * nothing and learns it from `JobFencedOut`.
+ */
+export class JobClaimService implements JobClaims {
+    constructor(
+        @InjectJobsManagers() private readonly managers: ReadonlyArray<EntityManager>,
+        @InjectClock() private readonly clock: Clock,
+    ) {}
+
+    /** Claims the delivery; null when the job is done or another worker holds a claim that has not expired. */
+    async claim(params: ClaimParams): Promise<ClaimResult> {
+        const now = this.clock.now()
+        const rows: Array<ClaimedRow> = await this.writer().query(CLAIM_JOB, [
+            params.kind,
+            params.jobKey,
+            params.workerId,
+            new Date(now.getTime() + params.leaseMs),
+            JSON.stringify(params.payload),
+            now,
+        ])
+        const row = rows[0]
+        if (row === undefined) return null
+        return {
+            jobId: row.id,
+            kind: row.kind,
+            fencingToken: Number(row.fencing_token),
+            currentStep: row.current_step,
+            payload: row.payload,
+        }
+    }
+
+    /** Records a finished step under the token the caller holds. */
+    advance(write: AdvanceWrite): Promise<void> {
+        return this.guarded(ADVANCE_JOB, [write.jobId, write.expectedFencingToken, write.step, this.clock.now()], write)
+    }
+
+    /** Completes the job under the token the caller holds. */
+    complete(write: GuardedWrite): Promise<void> {
+        return this.guarded(COMPLETE_JOB, [write.jobId, write.expectedFencingToken, this.clock.now()], write)
+    }
+
+    /** Marks the job failed under the token the caller holds, so BullMQ can retry it. */
+    fail(write: FailWrite): Promise<void> {
+        return this.guarded(FAIL_JOB, [write.jobId, write.expectedFencingToken, write.reason, this.clock.now()], write)
+    }
+
+    /** The idempotency key of one step of this claim: it includes the token, so a zombie's repeat is a different key than the live worker's. */
+    runKey(job: ClaimedJob, step: string): RunKey {
+        const key = `${job.jobId}:${step}:${job.fencingToken}`
+        if (!isRunKey(key))
+            throw new JobsError({ code: JobsErrorCode.RunKeyInvalid, params: { jobId: job.jobId, step } })
+        return key
+    }
+
+    /** The entity manager of the connection that holds the job table. */
+    private writer(): EntityManager {
+        const [manager] = this.managers
+        if (manager === undefined) throw new JobsError({ code: JobsErrorCode.ConnectionMissing })
+        return manager
+    }
+
+    /** Runs a statement that updates only when the token still matches; no row updated means a newer worker owns the job. */
+    private async guarded(
+        statement: ReturnType<typeof sql>,
+        parameters: Array<unknown>,
+        write: GuardedWrite,
+    ): Promise<void> {
+        const rows: Array<object> = await this.writer().query(statement, parameters)
+        if (rows.length === 0) {
+            throw new JobsError({
+                code: JobsErrorCode.FencedOut,
+                params: { jobId: write.jobId, token: write.expectedFencingToken },
+            })
+        }
+    }
+}

package/templates/be/patterns/jobs/platform/job-runner.service.spec.ts.tpl

@@ -0,0 +1,138 @@
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { LOGGER } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { QUEUE_WORKER_REGISTRY } from "@modules/platform/queue"
+import type { QueueDelivery, QueueWorkerRegistry } from "@modules/platform/queue"
+import { JobsError, JobsErrorCode } from "./errors/jobs.error"
+import type { FencedProcessor } from "./fenced.processor"
+import type { ClaimedJob } from "./jobs.contracts"
+import { JOB_CLAIMS, JOBS_OPTIONS } from "./jobs.decorators"
+import { JobsLogEvent } from "./jobs.log-events"
+import type { JobsOptions } from "./jobs.options"
+import type { JobClaims } from "./jobs.port"
+import { JobRunnerService } from "./job-runner.service"
+
+const options: JobsOptions = { connection: "primary", workerId: "w-1", leaseMs: 60000 }
+const delivery: QueueDelivery = { id: "k-1", queue: "mail", payload: { id: "m-1" }, attempt: 1 }
+const job: ClaimedJob = { jobId: "j-1", kind: "mail", fencingToken: 2, currentStep: null, payload: { id: "m-1" } }
+const fenced = (): JobsError => new JobsError({ code: JobsErrorCode.FencedOut, params: { jobId: "j-1", token: 2 } })
+
+const build = async () => {
+    const claims = mock<JobClaims>()
+    claims.fail.mockResolvedValue(undefined)
+    const queues = mock<QueueWorkerRegistry>()
+    const logger = mock<Logger>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            JobRunnerService,
+            { provide: JOBS_OPTIONS, useValue: options },
+            { provide: JOB_CLAIMS, useValue: claims },
+            { provide: QUEUE_WORKER_REGISTRY, useValue: queues },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return {
+        runner: moduleRef.get(JobRunnerService),
+        claims,
+        queues,
+        logger,
+        processor: mock<FencedProcessor>({ queue: "mail" }),
+    }
+}
+
+describe("JobRunnerService", () => {
+    describe("add", () => {
+        it("subscribes the processor to its queue, and the handler runs a delivery through the fence", async () => {
+            const { runner, claims, queues, processor } = await build()
+            claims.claim.mockResolvedValue(job)
+            runner.add(processor)
+            const handler = queues.add.mock.calls[0]?.[0]
+
+            await handler?.handle(delivery)
+
+            expect(handler?.queue).toBe("mail")
+            expect(processor.process).toHaveBeenCalledWith(job)
+        })
+    })
+
+    describe("run", () => {
+        it("claims the delivery with the job key and the lease, processes it and completes it under the claimed token", async () => {
+            const { runner, claims, processor } = await build()
+            claims.claim.mockResolvedValue(job)
+
+            await runner.run(processor, delivery)
+
+            expect(claims.claim).toHaveBeenCalledWith({
+                kind: "mail",
+                jobKey: "k-1",
+                payload: { id: "m-1" },
+                workerId: "w-1",
+                leaseMs: 60000,
+            })
+            expect(processor.process).toHaveBeenCalledWith(job)
+            expect(claims.complete).toHaveBeenCalledWith({ jobId: "j-1", expectedFencingToken: 2 })
+            expect(claims.fail).not.toHaveBeenCalled()
+        })
+
+        it("does nothing when the job is done or another worker holds a live claim", async () => {
+            const { runner, claims, processor } = await build()
+            claims.claim.mockResolvedValue(null)
+
+            await runner.run(processor, delivery)
+
+            expect(processor.process).not.toHaveBeenCalled()
+            expect(claims.complete).not.toHaveBeenCalled()
+        })
+
+        it("stops quietly when a write is fenced out: a newer worker owns the job and this one causes no further effect", async () => {
+            const { runner, claims, logger, processor } = await build()
+            claims.claim.mockResolvedValue(job)
+            claims.complete.mockRejectedValue(fenced())
+
+            await expect(runner.run(processor, delivery)).resolves.toBeUndefined()
+
+            expect(logger.warn).toHaveBeenCalledWith(JobsLogEvent.FencedOut, { jobId: "j-1" })
+            expect(claims.fail).not.toHaveBeenCalled()
+        })
+
+        it("marks the job failed under its token and rethrows when the processor throws, so BullMQ retries", async () => {
+            const { runner, claims, logger, processor } = await build()
+            claims.claim.mockResolvedValue(job)
+            const failure = new Error("provider down")
+            processor.process.mockRejectedValue(failure)
+
+            await expect(runner.run(processor, delivery)).rejects.toBe(failure)
+
+            expect(claims.fail).toHaveBeenCalledWith({ jobId: "j-1", expectedFencingToken: 2, reason: "provider down" })
+            expect(logger.error).toHaveBeenCalledWith(JobsLogEvent.DeliveryFailed, failure, { jobId: "j-1" })
+        })
+
+        it("records a thrown value that is not an Error by its text", async () => {
+            const { runner, claims, processor } = await build()
+            claims.claim.mockResolvedValue(job)
+            processor.process.mockRejectedValue("plain text")
+
+            await expect(runner.run(processor, delivery)).rejects.toBe("plain text")
+
+            expect(claims.fail).toHaveBeenCalledWith({ jobId: "j-1", expectedFencingToken: 2, reason: "plain text" })
+        })
+
+        it("still rethrows the original failure when recording it is fenced out, and logs when recording it fails otherwise", async () => {
+            const { runner, claims, logger, processor } = await build()
+            claims.claim.mockResolvedValue(job)
+            const failure = new Error("provider down")
+            processor.process.mockRejectedValue(failure)
+            claims.fail.mockRejectedValueOnce(fenced())
+
+            await expect(runner.run(processor, delivery)).rejects.toBe(failure)
+            expect(logger.warn).toHaveBeenCalledWith(JobsLogEvent.FencedOut, { jobId: "j-1" })
+
+            const storeDown = new Error("store down")
+            claims.fail.mockRejectedValueOnce(storeDown)
+
+            await expect(runner.run(processor, delivery)).rejects.toBe(failure)
+            expect(logger.error).toHaveBeenCalledWith(JobsLogEvent.FailureNotRecorded, storeDown, { jobId: "j-1" })
+        })
+    })
+})

package/templates/be/patterns/jobs/platform/job-runner.service.ts.tpl

@@ -0,0 +1,69 @@
+import { Injectable } from "@nestjs/common"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { InjectQueueWorkerRegistry } from "@modules/platform/queue"
+import type { QueueDelivery, QueueWorkerRegistry } from "@modules/platform/queue"
+import { JobsError, JobsErrorCode } from "./errors/jobs.error"
+import type { ClaimedJob } from "./jobs.contracts"
+import { InjectJobClaims, InjectJobsOptions } from "./jobs.decorators"
+import { JobsLogEvent } from "./jobs.log-events"
+import type { JobsOptions } from "./jobs.options"
+import type { JobClaims, JobProcessorRegistry } from "./jobs.port"
+import type { FencedProcessor } from "./fenced.processor"
+
+const isFencedOut = (cause: unknown): boolean => cause instanceof JobsError && cause.code === JobsErrorCode.FencedOut
+
+@Injectable()
+/**
+ * The runner of fenced jobs: it subscribes each registered processor to its queue and, for every delivery, claims the job (bumping the
+ * fencing token), calls the processor and settles the job through the guarded writes. A `JobFencedOut` means a newer worker owns the
+ * job: this worker stops with no further effect and the delivery is acknowledged. Any other failure marks the job failed and is
+ * rethrown, so BullMQ retries the delivery and the next claim bumps the token again.
+ */
+export class JobRunnerService implements JobProcessorRegistry {
+    constructor(
+        @InjectJobsOptions() private readonly options: JobsOptions,
+        @InjectJobClaims() private readonly claims: JobClaims,
+        @InjectQueueWorkerRegistry() private readonly queues: QueueWorkerRegistry,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    /** Subscribes the processor to its queue. */
+    add(processor: FencedProcessor): void {
+        this.queues.add({ queue: processor.queue, handle: (delivery) => this.run(processor, delivery) })
+    }
+
+    /** Runs one delivery of the processor's queue. */
+    async run(processor: FencedProcessor, delivery: QueueDelivery): Promise<void> {
+        const job = await this.claims.claim({
+            kind: processor.queue,
+            jobKey: delivery.id,
+            payload: delivery.payload,
+            workerId: this.options.workerId,
+            leaseMs: this.options.leaseMs,
+        })
+        if (job === null) return
+        try {
+            await processor.process(job)
+            await this.claims.complete({ jobId: job.jobId, expectedFencingToken: job.fencingToken })
+        } catch (cause) {
+            if (isFencedOut(cause)) {
+                this.logger.warn(JobsLogEvent.FencedOut, { jobId: job.jobId })
+                return
+            }
+            await this.recordFailure(job, cause)
+            throw cause
+        }
+    }
+
+    private async recordFailure(job: ClaimedJob, cause: unknown): Promise<void> {
+        const reason = cause instanceof Error ? cause.message : String(cause)
+        this.logger.error(JobsLogEvent.DeliveryFailed, cause, { jobId: job.jobId })
+        await this.claims
+            .fail({ jobId: job.jobId, expectedFencingToken: job.fencingToken, reason })
+            .catch((error_: unknown) => {
+                if (isFencedOut(error_)) this.logger.warn(JobsLogEvent.FencedOut, { jobId: job.jobId })
+                else this.logger.error(JobsLogEvent.FailureNotRecorded, error_, { jobId: job.jobId })
+            })
+    }
+}

package/templates/be/patterns/jobs/platform/jobs.config.ts.tpl

@@ -0,0 +1,11 @@
+import type { EnvSource } from "@modules/platform/config"
+import type { JobsOptions } from "./jobs.options"
+
+/** What the app's `main.ts` reads for the jobs; the connection token is the app root's choice. */
+export type JobsConfig = Omit<JobsOptions, "connection">
+
+/** Reads the jobs options: both are tunables with literal defaults. */
+export const parseJobsConfig = (env: EnvSource): JobsConfig => ({
+    workerId: env.optional("JOBS_WORKER_ID") ?? "worker",
+    leaseMs: env.duration("JOBS_LEASE", 60000),
+})