@starci/hfs 4.7.32 → 4.7.34

package/templates/be/patterns/idempotency/platform/inbox/request-fingerprint.policy.spec.ts.tpl

@@ -0,0 +1,76 @@
+import { Test } from "@nestjs/testing"
+import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
+import { requestFingerprint } from "./request-fingerprint.policy"
+
+const FINGERPRINT = Symbol("fingerprint")
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: FINGERPRINT, useValue: requestFingerprint }],
+    }).compile()
+    return moduleRef.get<typeof requestFingerprint>(FINGERPRINT)
+}
+
+describe("requestFingerprint", () => {
+    it("hashes nested objects independently of property insertion order", async () => {
+        const fingerprint = await build()
+
+        expect(fingerprint({ personId: "person-1", body: { quantity: 2, productId: "product-1" } })).toBe(
+            fingerprint({ body: { productId: "product-1", quantity: 2 }, personId: "person-1" }),
+        )
+        expect(fingerprint({ a: 1 })).toMatch(/^[a-f0-9]{64}$/)
+    })
+
+    it("keeps binary UTF-16 key order for non-ASCII and supplementary Unicode keys", async () => {
+        const fingerprint = await build()
+        const body = { "\uE000": 5, "\u{1F600}": 4, "\u00E9": 1, a: 3, Z: 2 }
+
+        expect(fingerprint(body)).toBe(fingerprint({ Z: 2, a: 3, "\u00E9": 1, "\u{1F600}": 4, "\uE000": 5 }))
+        expect(fingerprint(body)).toBe("6eb3469044da5c7df68404ba05b90306384fc773ad605d4de06321a2092ff365")
+    })
+
+    it("preserves array order, JSON types and nested values", async () => {
+        const fingerprint = await build()
+
+        expect(fingerprint([1, 2])).not.toBe(fingerprint([2, 1]))
+        expect(fingerprint({ value: 1 })).not.toBe(fingerprint({ value: "1" }))
+        expect(fingerprint({ body: { quantity: 2 } })).not.toBe(fingerprint({ body: { quantity: 3 } }))
+        expect(new Set([null, true, false, "", 0].map(fingerprint)).size).toBe(5)
+        expect(fingerprint([])).not.toBe(fingerprint({}))
+    })
+
+    it("accepts an object without a prototype and repeated noncyclic references", async () => {
+        const fingerprint = await build()
+        const shared = { quantity: 2 }
+        const withoutPrototype: unknown = Object.assign(Object.create(null), { quantity: 2 })
+
+        expect(fingerprint(withoutPrototype)).toBe(fingerprint(shared))
+        expect(fingerprint([shared, shared])).toBe(fingerprint([{ quantity: 2 }, { quantity: 2 }]))
+    })
+
+    it.each([
+        [undefined],
+        [() => 1],
+        [Symbol("unsupported")],
+        [BigInt(1)],
+        [Number.NaN],
+        [Number.POSITIVE_INFINITY],
+        [Number.NEGATIVE_INFINITY],
+        [{ missing: undefined }],
+        [[undefined]],
+        [Array(1)],
+        [new Date("2026-10-24T00:00:00.000Z")],
+        [new Map([["quantity", 2]])],
+    ])("refuses values that cannot represent a JSON request: %p", async (request: unknown) => {
+        const fingerprint = await build()
+
+        expect(() => fingerprint(request)).toThrow(new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid }))
+    })
+
+    it("refuses cyclic requests before a claim can be written", async () => {
+        const fingerprint = await build()
+        const cyclic: Record<string, unknown> = { quantity: 2 }
+        cyclic.body = cyclic
+
+        expect(() => fingerprint(cyclic)).toThrow(new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid }))
+    })
+})

package/templates/be/patterns/idempotency/platform/inbox/request-fingerprint.policy.ts.tpl

@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto"
+import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
+
+/** Serializes JSON without depending on object insertion order; array order remains part of the request. */
+const serializeJson = (value: unknown, ancestors: Set<object>): string => {
+    if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value)
+    if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value)
+    if (typeof value !== "object" || ancestors.has(value))
+        throw new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid })
+    ancestors.add(value)
+    let serialized: string
+    if (Array.isArray(value)) {
+        serialized = `[${Array.from(value, (item: unknown) => serializeJson(item, ancestors)).join(",")}]`
+    } else {
+        const prototype: unknown = Object.getPrototypeOf(value)
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid })
+        }
+        serialized = `{${Object.keys(value)
+            .sort((left, right) => Number(left > right) - Number(left < right))
+            .map((key) => {
+                const item: unknown = Reflect.get(value, key)
+                return `${JSON.stringify(key)}:${serializeJson(item, ancestors)}`
+            })
+            .join(",")}}`
+    }
+    ancestors.delete(value)
+    return serialized
+}
+
+/** Returns a stable JSON representation for both the request digest and the stored outcome. */
+export const canonicalJson = (value: unknown): string => serializeJson(value, new Set())
+
+/** Hashes the validated client request, so a reused key cannot silently apply a different body. */
+export const requestFingerprint = (request: unknown): string =>
+    createHash("sha256").update(canonicalJson(request)).digest("hex")

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

@@ -4,6 +4,7 @@ import { FencedProcessor } from "./fenced.processor"
 
 const claimedJob: ClaimedJob = {
     jobId: "job-1",
+    correlationId: "request-1",
     kind: "mail",
     fencingToken: 3,
     currentStep: null,

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

@@ -32,7 +32,7 @@ const buildWithoutConnection = async () => {
     return { claims: moduleRef.get(JobClaimService) }
 }
 
-const claimed: ClaimedJob = { jobId: "j-1", kind: "mail", fencingToken: 3, currentStep: null, payload: { id: "m-1" } }
+const claimed: ClaimedJob = { correlationId: "request-1", jobId: "j-1", kind: "mail", fencingToken: 3, currentStep: null, payload: { id: "m-1" } }
 
 describe("JobClaimService", () => {
     describe("claim", () => {
@@ -48,6 +48,7 @@ describe("JobClaimService", () => {
             const job = await claims.claim({
                 kind: "mail",
                 jobKey: "k-1",
+                correlationId: "request-1",
                 payload: { id: "m-1" },
                 workerId: "w-1",
                 leaseMs: 60000,
@@ -69,7 +70,7 @@ describe("JobClaimService", () => {
             const { claims } = await build(manager)
 
             await expect(
-                claims.claim({ kind: "mail", jobKey: "k-1", payload: {}, workerId: "w-1", leaseMs: 1000 }),
+                claims.claim({ correlationId: "request-1", kind: "mail", jobKey: "k-1", payload: {}, workerId: "w-1", leaseMs: 1000 }),
             ).resolves.toBeNull()
         })
     })
@@ -141,7 +142,7 @@ describe("JobClaimService", () => {
             const { claims } = await buildWithoutConnection()
 
             await expect(
-                claims.claim({ kind: "mail", jobKey: "k-1", payload: {}, workerId: "w-1", leaseMs: 1000 }),
+                claims.claim({ correlationId: "request-1", 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

@@ -44,8 +44,10 @@ export class JobClaimService implements JobClaims {
         ])
         const row = rows[0]
         if (row === undefined) return null
+        // The durable delivery supplies the same request id on every retry; the job fence identifies a claim separately.
         return {
             jobId: row.id,
+            correlationId: params.correlationId,
             kind: row.kind,
             fencingToken: Number(row.fencing_token),
             currentStep: row.current_step,

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

@@ -14,8 +14,8 @@ 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 delivery: QueueDelivery = { correlationId: "request-1", id: "k-1", queue: "mail", payload: { id: "m-1" }, attempt: 1 }
+const job: ClaimedJob = { correlationId: "request-1", 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 () => {
@@ -66,6 +66,7 @@ describe("JobRunnerService", () => {
             expect(claims.claim).toHaveBeenCalledWith({
                 kind: "mail",
                 jobKey: "k-1",
+                correlationId: "request-1",
                 payload: { id: "m-1" },
                 workerId: "w-1",
                 leaseMs: 60000,
@@ -75,6 +76,23 @@ describe("JobRunnerService", () => {
             expect(claims.fail).not.toHaveBeenCalled()
         })
 
+        it("retains the original request correlation when a retry claims a newer fence", async () => {
+            const { runner, claims, processor } = await build()
+            const failure = new Error("provider unavailable")
+            claims.claim.mockResolvedValueOnce(job).mockResolvedValueOnce({ ...job, fencingToken: 3 })
+            processor.process.mockRejectedValueOnce(failure).mockResolvedValueOnce(undefined)
+
+            await expect(runner.run(processor, delivery)).rejects.toBe(failure)
+            await runner.run(processor, { ...delivery, attempt: 2 })
+
+            expect(processor.process.mock.calls.map(([claimed]) => claimed.correlationId)).toEqual([
+                "request-1",
+                "request-1",
+            ])
+            expect(processor.process.mock.calls.map(([claimed]) => claimed.fencingToken)).toEqual([2, 3])
+            expect(claims.complete).toHaveBeenCalledWith({ jobId: "j-1", expectedFencingToken: 3 })
+        })
+
         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)

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

@@ -38,6 +38,7 @@ export class JobRunnerService implements JobProcessorRegistry {
         const job = await this.claims.claim({
             kind: processor.queue,
             jobKey: delivery.id,
+            correlationId: delivery.correlationId,
             payload: delivery.payload,
             workerId: this.options.workerId,
             leaseMs: this.options.leaseMs,

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

@@ -1,5 +1,7 @@
 /** A job a worker claimed: the token it must pass to every write. */
 export interface ClaimedJob {
+    /** The originating request id carried explicitly by the durable queue delivery. */
+    readonly correlationId: string
     /** The id of the job row. */
     readonly jobId: string
     /** The kind of the job: the queue its processor consumes. */
@@ -14,6 +16,8 @@ export interface ClaimedJob {
 
 /** What a worker asks for when it claims a delivery. */
 export interface ClaimParams {
+    /** The originating request id retained across delivery retries. */
+    readonly correlationId: string
     /** The kind of the job. */
     readonly kind: string
     /** The key of the delivery: the BullMQ job id. A second claim of the same key bumps the token of the same row. */

package/templates/be/patterns/jobs/platform-lite/jobs.index.ts.tpl

@@ -0,0 +1,10 @@
+export { JOBS_ERROR_KINDS } from "./errors/jobs.error"
+export { parseJobsConfig } from "./jobs.config"
+export type { JobsConfig } from "./jobs.config"
+export { isRunKey } from "./jobs.contracts"
+export type { ClaimedJob, RunKey } from "./jobs.contracts"
+export { InjectJobClaims, InjectJobProcessorRegistry } from "./jobs.decorators"
+export { JobsModule } from "./jobs.module"
+export type { JobClaims, JobProcessorRegistry, JobStep } from "./jobs.port"
+export { FencedProcessor } from "./fenced.processor"
+export { JOBS_MESSAGES } from "./messages/jobs.messages"

package/templates/be/patterns/jobs/platform-lite/jobs.sql.tpl

@@ -0,0 +1,44 @@
+-- The fenced jobs: one row per delivery key. A claim bumps the fencing token and every
+-- other write of a worker carries the token it holds, so a worker that lost its claim
+-- changes nothing. Only the app_be connection reaches it.
+create table public.jobs (
+    id uuid primary key default gen_random_uuid(),
+    kind varchar(200) not null,
+    job_key varchar(200) not null,
+    status varchar(16) not null,
+    current_step varchar(200),
+    fencing_token bigint not null,
+    claimed_by varchar(200),
+    lease_expires_at timestamptz,
+    payload jsonb not null,
+    error text,
+    created_at timestamptz not null,
+    updated_at timestamptz not null,
+    constraint jobs_job_key_key unique (job_key),
+    constraint jobs_status_check check (status in ('running', 'failed', 'done')),
+    constraint jobs_fencing_token_check check (fencing_token >= 1)
+);
+
+alter table public.jobs enable row level security;
+alter table public.jobs force row level security;
+
+create trigger jobs_set_updated_at
+before update on public.jobs
+for each row
+execute function private.set_updated_at();
+
+create policy jobs_app_be_select
+on public.jobs for select to app_be
+using (kind is not null);
+
+create policy jobs_app_be_insert
+on public.jobs for insert to app_be
+with check (kind is not null);
+
+create policy jobs_app_be_update
+on public.jobs for update to app_be
+using (kind is not null)
+with check (kind is not null);
+
+revoke all on table public.jobs from public, anon, authenticated;
+grant select, insert, update on table public.jobs to app_be;

package/templates/be/patterns/jobs/platform-lite/persistence.jobs.sql.ts.tpl

@@ -0,0 +1,33 @@
+import { sql } from "@modules/platform/database"
+
+/**
+ * Claims a delivery in one statement ($1 kind, $2 job key, $3 worker, $4 lease end, $5 payload, $6 instant). A new key inserts the row
+ * with token 1; an existing key is claimed again only when the job failed or its lease expired, and then the token is bumped by the
+ * store. A done job and a live claim match nothing, so no row comes back.
+ */
+export const CLAIM_JOB = sql`INSERT INTO public.jobs (kind, job_key, status, fencing_token, claimed_by, lease_expires_at, payload, created_at, updated_at)
+    VALUES ($1, $2, 'running', 1, $3, $4, $5::jsonb, $6, $6)
+    ON CONFLICT (job_key) DO UPDATE
+       SET fencing_token = jobs.fencing_token + 1, claimed_by = $3, lease_expires_at = $4, status = 'running', error = NULL, updated_at = $6
+     WHERE jobs.status = 'failed' OR (jobs.status = 'running' AND jobs.lease_expires_at < $6)
+    RETURNING id, kind, fencing_token, current_step, payload`
+
+/** The guarded writes wrap their UPDATE in a CTE: TypeORM returns a bare `UPDATE ... RETURNING` as `[rows, count]`, a SELECT as rows. */
+
+/** Records a step ($1 job id, $2 expected token, $3 step, $4 instant); no row comes back when the token is stale. */
+export const ADVANCE_JOB = sql`WITH changed AS (UPDATE public.jobs SET current_step = $3, updated_at = $4
+    WHERE id = $1 AND fencing_token = $2 AND status = 'running'
+       RETURNING id)
+    SELECT id FROM changed`
+
+/** Completes the job ($1 job id, $2 expected token, $3 instant). */
+export const COMPLETE_JOB = sql`WITH changed AS (UPDATE public.jobs SET status = 'done', lease_expires_at = NULL, updated_at = $3
+    WHERE id = $1 AND fencing_token = $2 AND status = 'running'
+       RETURNING id)
+    SELECT id FROM changed`
+
+/** Fails the job ($1 job id, $2 expected token, $3 reason, $4 instant). */
+export const FAIL_JOB = sql`WITH changed AS (UPDATE public.jobs SET status = 'failed', error = $3, lease_expires_at = NULL, updated_at = $4
+    WHERE id = $1 AND fencing_token = $2 AND status = 'running'
+       RETURNING id)
+    SELECT id FROM changed`

package/templates/be/patterns/queues/platform/bullmq-queue-transport.client.spec.ts.tpl

@@ -1,14 +1,19 @@
 import { Test } from "@nestjs/testing"
-import { mock } from "@starci/jest-preset"
+import { fakeIds, mock } from "@starci/jest-preset"
+import { LOGGER } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { IDS } from "@modules/platform/ids"
+import { QueueErrorCode } from "./errors/queue.error"
 import { BullmqQueueTransportClient } from "./bullmq-queue-transport.client"
+import { BULLMQ_JOB_SCHEMA } from "./queue.contracts"
 import type { QueueHandler } from "./queue.contracts"
 import { QUEUE_FACTORY, QUEUE_OPTIONS } from "./queue.decorators"
+import { QueueLogEvent } from "./queue.log-events"
 import type { QueueOptions } from "./queue.options"
 import { ATTEMPTS, BACKOFF_MS, KEEP_COMPLETED_SECONDS } from "./queue.policy"
 import type { BullmqJob, BullmqQueue, BullmqWorker, QueueFactory } from "./queue-transport.port"
 
-/** Asymmetric matchers read as `unknown`: jest types them `any`, which may not flow into a property or a typed argument. */
-const anyOf = (type: unknown): unknown => expect.any(type)
+const MINTED_ID = "00000000-0000-4000-8000-000000000001"
 
 const options: QueueOptions = {
     redisHost: "redis.test",
@@ -26,6 +31,8 @@ const build = async () => {
     const queue = mock<BullmqQueue>()
     const worker = mock<BullmqWorker>()
     const factory = mock<QueueFactory>()
+    const ids = fakeIds()
+    const logger = mock<Logger>()
     factory.queue.mockReturnValue(queue)
     factory.worker.mockReturnValue(worker)
     const moduleRef = await Test.createTestingModule({
@@ -33,30 +40,46 @@ const build = async () => {
             BullmqQueueTransportClient,
             { provide: QUEUE_OPTIONS, useValue: options },
             { provide: QUEUE_FACTORY, useValue: factory },
+            { provide: IDS, useValue: ids },
+            { provide: LOGGER, useValue: logger },
         ],
     }).compile()
-    return { client: moduleRef.get(BullmqQueueTransportClient), queue, worker, factory }
+    return { client: moduleRef.get(BullmqQueueTransportClient), queue, worker, factory, logger, ids }
 }
 
-describe("BullmqQueueTransportClient", () => {
+describe("BullmqQueueTransportClient jobs and schedulers", () => {
     it("adds idempotent jobs with the queue retry and retention policy", async () => {
         const { client, queue, factory } = await build()
         const payload = { orderId: "order-1" }
 
-        await client.add("orders", "outbox-1", payload)
-        await client.add("orders", "outbox-2", payload)
+        await client.add("orders", "outbox-1", payload, "request-1")
+        await client.add("orders", "outbox-2", payload, "request-2")
 
         expect(factory.queue).toHaveBeenCalledTimes(1)
         expect(factory.queue).toHaveBeenCalledWith("orders", {
             prefix: "spec.",
             connection: { host: "redis.test", port: 6380, db: 7, maxRetriesPerRequest: null },
         })
-        expect(queue.add).toHaveBeenNthCalledWith(1, "orders", payload, {
-            jobId: "outbox-1",
-            attempts: ATTEMPTS,
-            backoff: { type: "exponential", delay: BACKOFF_MS },
-            removeOnComplete: { age: KEEP_COMPLETED_SECONDS },
+        expect(queue.add).toHaveBeenNthCalledWith(
+            1,
+            "orders",
+            { schema: BULLMQ_JOB_SCHEMA, kind: "enqueued", payload, correlationId: "request-1" },
+            {
+                jobId: "outbox-1",
+                attempts: ATTEMPTS,
+                backoff: { type: "exponential", delay: BACKOFF_MS },
+                removeOnComplete: { age: KEEP_COMPLETED_SECONDS },
+            },
+        )
+    })
+
+    it("rejects unsafe correlation before writing a new job", async () => {
+        const { client, factory } = await build()
+
+        await expect(client.add("orders", "outbox-1", {}, "unsafe\nrequest")).rejects.toMatchObject({
+            code: QueueErrorCode.CorrelationInvalid,
         })
+        expect(factory.queue).not.toHaveBeenCalled()
     })
 
     it("upserts schedulers with their payload or an empty payload", async () => {
@@ -69,16 +92,26 @@ describe("BullmqQueueTransportClient", () => {
             1,
             "settlement",
             { every: 60_000 },
-            { name: "billing", data: { shard: 2 }, opts: { attempts: ATTEMPTS } },
+            {
+                name: "billing",
+                data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: { shard: 2 } },
+                opts: { attempts: ATTEMPTS },
+            },
         )
         expect(queue.upsertJobScheduler).toHaveBeenNthCalledWith(
             2,
             "cleanup",
             { every: 120_000 },
-            { name: "billing", data: {}, opts: { attempts: ATTEMPTS } },
+            {
+                name: "billing",
+                data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: {} },
+                opts: { attempts: ATTEMPTS },
+            },
         )
     })
+})
 
+describe("BullmqQueueTransportClient worker deliveries", () => {
     it("starts a worker that translates BullMQ jobs into queue deliveries", async () => {
         const { client, factory } = await build()
         const handler = mock<QueueHandler>({ queue: "orders" })
@@ -86,29 +119,181 @@ describe("BullmqQueueTransportClient", () => {
 
         await client.work(handler, 3)
 
-        expect(factory.worker).toHaveBeenCalledWith("orders", anyOf(Function), {
+        expect(factory.worker).toHaveBeenCalledWith("orders", expect.any(Function), {
             prefix: "spec.",
             connection: { host: "redis.test", port: 6380, db: 7, maxRetriesPerRequest: null },
             concurrency: 3,
         })
         const processor = factory.worker.mock.calls[0]?.[1]
-        await processor?.(mock<BullmqJob>({ id: "job-1", data: { orderId: "order-1" }, attemptsMade: 2 }))
-        await processor?.({ data: { orderId: "order-2" }, attemptsMade: 0 } satisfies BullmqJob)
+        await processor?.(
+            mock<BullmqJob>({
+                id: "job-1",
+                data: {
+                    schema: BULLMQ_JOB_SCHEMA,
+                    kind: "enqueued",
+                    payload: { orderId: "order-1" },
+                    correlationId: "request-1",
+                },
+                attemptsMade: 2,
+            }),
+        )
+        await processor?.({
+            data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: { orderId: "order-2" } },
+            attemptsMade: 0,
+        } satisfies BullmqJob)
+        await processor?.({
+            id: "tick-3",
+            data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: {} },
+            attemptsMade: 1,
+        } satisfies BullmqJob)
 
         expect(handler.handle).toHaveBeenNthCalledWith(1, {
             id: "job-1",
+            correlationId: "request-1",
             queue: "orders",
             payload: { orderId: "order-1" },
             attempt: 3,
         })
         expect(handler.handle).toHaveBeenNthCalledWith(2, {
             id: "",
+            correlationId: MINTED_ID,
             queue: "orders",
             payload: { orderId: "order-2" },
             attempt: 1,
         })
+        expect(handler.handle).toHaveBeenNthCalledWith(3, {
+            id: "tick-3",
+            correlationId: "tick-3",
+            queue: "orders",
+            payload: {},
+            attempt: 2,
+        })
+    })
+})
+
+describe("BullmqQueueTransportClient stored job upgrades", () => {
+    it("preserves raw payloads and the same job correlation through legacy retries", async () => {
+        const { client, factory, ids } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        await client.work(handler, 3)
+        const processor = factory.worker.mock.calls[0]?.[1]
+        const payload = { orderId: "before-upgrade", kind: "expire-order", payload: { reason: "unpaid" } }
+
+        await processor?.({ id: "legacy-job", data: payload, attemptsMade: 0 })
+        await processor?.({ id: "legacy-job", data: payload, attemptsMade: 1 })
+
+        expect(handler.handle).toHaveBeenNthCalledWith(1, {
+            id: "legacy-job",
+            queue: "orders",
+            payload,
+            correlationId: "legacy-job",
+            attempt: 1,
+        })
+        expect(handler.handle).toHaveBeenNthCalledWith(2, {
+            id: "legacy-job",
+            queue: "orders",
+            payload,
+            correlationId: "legacy-job",
+            attempt: 2,
+        })
+        expect(ids.issued).toEqual([])
+    })
+
+    it.each(["enqueued", "scheduled"])("keeps legacy business fields even when kind is %s", async (kind) => {
+        const { client, factory, ids } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        await client.work(handler, 3)
+        const processor = factory.worker.mock.calls[0]?.[1]
+        const payload = {
+            schema: "order/business@1",
+            kind,
+            correlationId: "business\nkey",
+            payload: { orderId: "legacy-order" },
+        }
+
+        await processor?.({ id: "legacy-collision", data: payload, attemptsMade: 0 })
+
+        expect(handler.handle).toHaveBeenCalledWith({
+            id: "legacy-collision",
+            queue: "orders",
+            payload,
+            correlationId: "legacy-collision",
+            attempt: 1,
+        })
+        expect(ids.issued).toEqual([])
+    })
+})
+
+describe("BullmqQueueTransportClient correlation roots and marked envelopes", () => {
+    it("mints only when legacy data has no job id and accepts explicit scheduled correlation", async () => {
+        const { client, factory, ids } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        await client.work(handler, 3)
+        const processor = factory.worker.mock.calls[0]?.[1]
+
+        await processor?.({ data: { orderId: "legacy-no-id" }, attemptsMade: 0 })
+        await processor?.({
+            data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: {}, correlationId: "upstream-tick" },
+            attemptsMade: 0,
+        })
+
+        expect(handler.handle.mock.calls.map(([delivery]) => delivery.correlationId)).toEqual([
+            MINTED_ID,
+            "upstream-tick",
+        ])
+        expect(ids.issued).toEqual([MINTED_ID])
+    })
+
+    it.each<unknown>([
+        null,
+        { schema: "starci/queue@2", kind: "enqueued", payload: {}, correlationId: "request-1" },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "unknown", payload: {} },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "enqueued", payload: {}, correlationId: undefined },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "enqueued", payload: null, correlationId: "request-1" },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "enqueued", payload: {}, correlationId: "bad\nidentity" },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: {}, correlationId: undefined },
+    ])("rejects malformed current data before business delivery (%j)", async (data) => {
+        const { client, factory } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        await client.work(handler, 3)
+        const processor = factory.worker.mock.calls[0]?.[1]
+
+        await expect(processor?.({ id: "stored-job", data, attemptsMade: 0 })).rejects.toMatchObject({
+            code: QueueErrorCode.MalformedMessage,
+        })
+        expect(handler.handle).not.toHaveBeenCalled()
+    })
+})
+
+describe("BullmqQueueTransportClient driver errors", () => {
+    it("routes queue driver errors through the logger once per queue", async () => {
+        const { client, queue, logger } = await build()
+        await client.add("orders", "outbox-1", {}, "request-1")
+        await client.add("orders", "outbox-2", {}, "request-2")
+        const cause = new Error("redis connection lost")
+
+        const listener = queue.on.mock.calls[0]?.[1]
+        listener?.(cause)
+
+        expect(queue.on).toHaveBeenCalledTimes(1)
+        expect(queue.on).toHaveBeenCalledWith("error", expect.any(Function))
+        expect(logger.error).toHaveBeenCalledWith(QueueLogEvent.QueueFailed, cause, { queue: "orders" })
+    })
+
+    it("routes worker driver errors through the logger", async () => {
+        const { client, worker, logger } = await build()
+        await client.work(mock<QueueHandler>({ queue: "orders" }), 3)
+        const cause = new Error("blocking redis connection lost")
+
+        const listener = worker.on.mock.calls[0]?.[1]
+        listener?.(cause)
+
+        expect(worker.on).toHaveBeenCalledWith("error", expect.any(Function))
+        expect(logger.error).toHaveBeenCalledWith(QueueLogEvent.WorkerFailed, cause, { queue: "orders" })
     })
+})
 
+describe("BullmqQueueTransportClient wait and shutdown", () => {
     it("waits for the requested delay", async () => {
         jest.useFakeTimers()
         try {
@@ -132,7 +317,7 @@ describe("BullmqQueueTransportClient", () => {
                 finishWorkerClose = resolve
             }),
         )
-        await client.add("orders", "outbox-1", {})
+        await client.add("orders", "outbox-1", {}, "request-1")
         await client.work(handler, 3)
 
         const closing = client.close()