@starci/hfs 4.9.9 → 4.10.0

package/templates/be/inbox/platform/inbox/inbox.service.ts.tpl

@@ -2,14 +2,46 @@ import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
-import { BATCH_ROWS, DatabaseError, DatabaseErrorCode } from "@modules/platform/database"
+import { BATCH_ROWS, DatabaseError, DatabaseErrorCode, callDbFunction } from "@modules/platform/database"
 import type { ClientOperation, ClientOperationEffect, Inbox, InboxEventId } from "./inbox.port"
 import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
 import { InboxError, InboxErrorCode } from "./errors/inbox.error"
 import { clientSource } from "./client-operation.policy"
 import { canonicalJson, requestFingerprint } from "./request-fingerprint.policy"
-import type { ClaimClientRow, InboxEventRow, InboxSweepRow, SavedClientOutcomeRow } from "./persistence/inbox.rows"
-import { CLAIM_CLIENT, CLAIM_EVENT, SAVE_CLIENT_OUTCOME, SWEEP_CLIENTS } from "./persistence/inbox.sql"
+
+/** The JSON envelope makes a completed null value distinct from a pending SQL-null outcome. */
+interface ClientOutcomeRow<T> {
+    /** The operation's complete JSON result, including expected refusals. */
+    readonly value: T
+}
+
+/** The row returned by the atomic client claim. */
+interface ClaimClientRow<T> {
+    /** The digest recorded by the first operation under this scoped key. */
+    readonly request_fingerprint: string | null
+    /** The saved result, or null only for a claim inserted by this transaction. */
+    readonly outcome: ClientOutcomeRow<T> | null
+    /** An existing row had no completed outcome, so it must never run an effect again. */
+    readonly incomplete: boolean
+}
+
+/** The persisted outcome returned to the first caller. */
+interface SavedClientOutcomeRow<T> {
+    /** The normalized JSON result as the database stores it. */
+    readonly outcome: ClientOutcomeRow<T>
+}
+
+/** A claimed or deleted delivery key returned by inbox persistence. */
+interface InboxEventRow {
+    /** The event or client key owned by the row. */
+    readonly event_id: string
+}
+
+/** The bounded retention batch's aggregate result. */
+interface InboxSweepRow {
+    /** Number of completed client claims removed by this transaction. */
+    readonly deleted_count: number
+}
 
 @Injectable()
 /** Claims a delivery with the receipt transaction, so a failure can be retried without losing the delivery. */
@@ -22,7 +54,7 @@ export class PostgresInbox implements Inbox {
         if (!normalizedEventId) {
             throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
         }
-        const rows: Array<InboxEventRow> = await tx.query(CLAIM_EVENT, [source, normalizedEventId])
+        const rows = await callDbFunction<InboxEventRow>(tx, "inbox_claim_event", [source, normalizedEventId])
         return rows.length > 0
     }
 
@@ -32,7 +64,7 @@ export class PostgresInbox implements Inbox {
             throw new InboxError({ code: InboxErrorCode.TransactionRequired })
         const source = clientSource(request)
         const fingerprint = requestFingerprint(request.request)
-        const rows: Array<ClaimClientRow<T>> = await tx.query(CLAIM_CLIENT, [
+        const rows = await callDbFunction<ClaimClientRow<T>>(tx, "inbox_claim_client", [
             source,
             request.idempotencyKey,
             fingerprint,
@@ -52,7 +84,7 @@ export class PostgresInbox implements Inbox {
         } catch (cause) {
             throw new InboxError({ code: InboxErrorCode.OutcomeInvalid, cause })
         }
-        const saved: Array<SavedClientOutcomeRow<T>> = await tx.query(SAVE_CLIENT_OUTCOME, [
+        const saved = await callDbFunction<SavedClientOutcomeRow<T>>(tx, "inbox_save_client_outcome", [
             source,
             request.idempotencyKey,
             outcome,
@@ -64,7 +96,7 @@ export class PostgresInbox implements Inbox {
 
     /** A row lock and SKIP LOCKED keep retention from competing with a live retry or another sweep worker. */
     async sweepClients(cutoff: Date, tx: EntityManager): Promise<number> {
-        const rows: Array<InboxSweepRow> = await tx.query(SWEEP_CLIENTS, [cutoff, BATCH_ROWS])
+        const rows = await callDbFunction<InboxSweepRow>(tx, "inbox_sweep_clients", [cutoff, BATCH_ROWS])
         return rows[0]?.deleted_count ?? 0
     }
 }

package/templates/be/inbox/platform/migration.sql.tpl

@@ -47,3 +47,25 @@ with check (event_name <> '');
 
 revoke all on table public.event_bus from public, anon, authenticated;
 grant select, insert, update on table public.event_bus to app_be;
+
+-- The claim of one delivery and the typed envelope write, called through callDbFunction of platform/database (R334).
+create function public.inbox_claim_event(p_source text, p_event_id text)
+returns table (event_id text)
+language sql
+as $$
+    insert into public.inbox as i (source, event_id) values (p_source, p_event_id)
+    on conflict (source, event_id) do nothing
+    returning i.event_id
+$$;
+
+create function public.event_bus_write(p_event_id text, p_event_name text, p_payload jsonb, p_correlation_id varchar)
+returns void
+language sql
+as $$
+    insert into public.event_bus (event_id, event_name, payload, correlation_id) values (p_event_id, p_event_name, p_payload, p_correlation_id)
+$$;
+
+revoke all on function public.inbox_claim_event(text, text) from public;
+grant execute on function public.inbox_claim_event(text, text) to app_be;
+revoke all on function public.event_bus_write(text, text, jsonb, varchar) from public;
+grant execute on function public.event_bus_write(text, text, jsonb, varchar) to app_be;

package/templates/be/inbox/service.spec.ts.tpl

@@ -1,13 +1,13 @@
 import { fakeInbox, fakeTransaction, mockEntityManager, recordingEventBus } from "@starci/jest-preset"
 import { Test } from "@nestjs/testing"
-import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { PRIMARY_ENTITY_MANAGER, webhookReceiptInsert } from "@modules/platform/database"
 import { @@Provider@@DeliveryRecordedEvent } from "@modules/events/@@provider@@"
 import { EVENT_BUS } from "@modules/platform/event-bus"
 import { INBOX } from "@modules/platform/inbox"
-import { INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
 import { @@Provider@@InboxService } from "./@@provider@@-inbox.service"
 
 const DELIVERY = { id: "delivery-1" }
+const INSERT_@@providerUpper@@_INBOX = webhookReceiptInsert("@@table@@")
 
 const build = async (fresh: boolean, recorded: ReadonlyArray<{ readonly id: string }> = [{ id: "inbox-1" }]) => {
     const entityManager = mockEntityManager({ query: [INSERT_@@providerUpper@@_INBOX, recorded] })

package/templates/be/inbox/service.ts.tpl

@@ -6,7 +6,6 @@ import { InjectEventBus } from "@modules/platform/event-bus"
 import type { EventBus } from "@modules/platform/event-bus"
 import { InjectInbox } from "@modules/platform/inbox"
 import type { Inbox } from "@modules/platform/inbox"
-import { INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
 
 interface @@Provider@@Delivery {
     readonly id: string
@@ -34,7 +33,7 @@ export class @@Provider@@InboxService {
             if (!(await this.inbox.claim("webhook.@@provider@@", request.eventId, manager))) return
             const receiptId = await recordWebhookDelivery({
                 manager,
-                insert: INSERT_@@providerUpper@@_INBOX,
+                table: "@@table@@",
                 provider: "@@provider@@",
                 deliveryId: request.eventId,
                 payload: request.delivery,

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

@@ -0,0 +1,156 @@
+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"
+
+// The statements callDbFunction of platform/database sends for each job function.
+const CLAIM_JOB = "SELECT * FROM job_claim($1, $2, $3, $4, $5, $6)"
+const ADVANCE_JOB = "SELECT * FROM job_advance($1, $2, $3, $4)"
+const COMPLETE_JOB = "SELECT * FROM job_complete($1, $2, $3)"
+const FAIL_JOB = "SELECT * FROM job_fail($1, $2, $3, $4)"
+
+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 = { correlationId: "request-1", 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",
+                correlationId: "request-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({ correlationId: "request-1", 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({ 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-lite/job-claim.service.ts.tpl

@@ -0,0 +1,114 @@
+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 { callDbFunction } 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"
+
+/** The record job_claim returns (a bigint arrives as text). */
+interface ClaimedRecord {
+    /** The id of the job row. */
+    readonly id: string
+    /** The kind of the job. */
+    readonly kind: string
+    /** The fencing token after the claim. */
+    readonly fencing_token: string
+    /** The last recorded step, or null. */
+    readonly current_step: string | null
+    /** The payload, as the database returns the jsonb value. */
+    readonly payload: object
+}
+
+@Injectable()
+/**
+ * The one owner of the job row, through the job_* functions of its migration (R334). 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 = await callDbFunction<ClaimedRecord>(this.writer(), "job_claim", [
+            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
+        // 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,
+            payload: row.payload,
+        }
+    }
+
+    /** Records a finished step under the token the caller holds. */
+    advance(write: AdvanceWrite): Promise<void> {
+        return this.guarded("job_advance", [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("job_complete", [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("job_fail", [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 guarded function that updates only when the token still matches; no row back means a newer worker owns the job. */
+    private async guarded(
+        fn: "job_advance" | "job_complete" | "job_fail",
+        parameters: Array<unknown>,
+        write: GuardedWrite,
+    ): Promise<void> {
+        const rows = await callDbFunction<object>(this.writer(), fn, parameters)
+        if (rows.length === 0) {
+            throw new JobsError({
+                code: JobsErrorCode.FencedOut,
+                params: { jobId: write.jobId, token: write.expectedFencingToken },
+            })
+        }
+    }
+}

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

@@ -42,3 +42,54 @@ 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;
+
+-- The claim and the guarded writes, called through callDbFunction of platform/database (R334). A claim inserts a new key with
+-- token 1 or claims a failed or expired one again, bumping the token; a done job or a live claim returns no row. Every other
+-- write matches only the token the caller holds, so a worker that lost its claim changes nothing and gets no row back.
+create function public.job_claim(p_kind varchar, p_job_key varchar, p_worker varchar, p_lease_end timestamptz, p_payload jsonb, p_now timestamptz)
+returns table (id uuid, kind varchar, fencing_token bigint, current_step varchar, payload jsonb)
+language sql
+as $$
+    insert into public.jobs as j (kind, job_key, status, fencing_token, claimed_by, lease_expires_at, payload, created_at, updated_at)
+    values (p_kind, p_job_key, 'running', 1, p_worker, p_lease_end, p_payload, p_now, p_now)
+    on conflict (job_key) do update
+       set fencing_token = j.fencing_token + 1, claimed_by = p_worker, lease_expires_at = p_lease_end, status = 'running', error = null, updated_at = p_now
+     where j.status = 'failed' or (j.status = 'running' and j.lease_expires_at < p_now)
+    returning j.id, j.kind, j.fencing_token, j.current_step, j.payload
+$$;
+
+create function public.job_advance(p_id uuid, p_token bigint, p_step varchar, p_now timestamptz)
+returns table (id uuid)
+language sql
+as $$
+    update public.jobs as j set current_step = p_step, updated_at = p_now
+     where j.id = p_id and j.fencing_token = p_token and j.status = 'running'
+    returning j.id
+$$;
+
+create function public.job_complete(p_id uuid, p_token bigint, p_now timestamptz)
+returns table (id uuid)
+language sql
+as $$
+    update public.jobs as j set status = 'done', lease_expires_at = null, updated_at = p_now
+     where j.id = p_id and j.fencing_token = p_token and j.status = 'running'
+    returning j.id
+$$;
+
+create function public.job_fail(p_id uuid, p_token bigint, p_reason text, p_now timestamptz)
+returns table (id uuid)
+language sql
+as $$
+    update public.jobs as j set status = 'failed', error = p_reason, lease_expires_at = null, updated_at = p_now
+     where j.id = p_id and j.fencing_token = p_token and j.status = 'running'
+    returning j.id
+$$;
+
+revoke all on function public.job_claim(varchar, varchar, varchar, timestamptz, jsonb, timestamptz) from public;
+grant execute on function public.job_claim(varchar, varchar, varchar, timestamptz, jsonb, timestamptz) to app_be;
+revoke all on function public.job_advance(uuid, bigint, varchar, timestamptz) from public;
+grant execute on function public.job_advance(uuid, bigint, varchar, timestamptz) to app_be;
+revoke all on function public.job_complete(uuid, bigint, timestamptz) from public;
+grant execute on function public.job_complete(uuid, bigint, timestamptz) to app_be;
+revoke all on function public.job_fail(uuid, bigint, text, timestamptz) from public;
+grant execute on function public.job_fail(uuid, bigint, text, timestamptz) to app_be;

package/templates/be/patterns/queues/platform-lite/queue-outbox.service.spec.ts.tpl

@@ -0,0 +1,62 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { QueueOutboxService } from "./queue-outbox.service"
+
+// The statement callDbFunction of platform/database sends for queue_write.
+const INSERT_QUEUE_ROW = "SELECT * FROM queue_write($1, $2, $3, $4)"
+import { QueueErrorCode } from "./errors/queue.error"
+
+const AT = "2026-02-03T04:05:06.000Z"
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [QueueOutboxService, { provide: CLOCK, useValue: new FakeClock(AT) }],
+    }).compile()
+    return { outbox: moduleRef.get(QueueOutboxService) }
+}
+
+describe("QueueOutboxService", () => {
+    describe("write", () => {
+        it("writes the job as a row of the outbox of the transaction it is given", async () => {
+            const { outbox } = await build()
+            const tx = fakeTransaction(mockEntityManager({ query: [INSERT_QUEUE_ROW, []] }))
+
+            await tx.em.transaction((manager) => outbox.write(manager, "mail", { id: "m-1" }, "request-1"))
+
+            expect(tx.em.query).toHaveBeenCalledWith(INSERT_QUEUE_ROW, [
+                "mail",
+                JSON.stringify({ id: "m-1" }),
+                new Date(AT),
+                "request-1",
+            ])
+            expect(tx.commits).toBe(1)
+        })
+
+        it("leaves no row behind when the transaction rolls back", async () => {
+            const { outbox } = await build()
+            const tx = fakeTransaction(mockEntityManager({ query: [INSERT_QUEUE_ROW, []] }))
+            const failure = new Error("the change failed")
+
+            await expect(
+                tx.em.transaction(async (manager) => {
+                    await outbox.write(manager, "mail", { id: "m-1" }, "request-1")
+                    return Promise.reject(failure)
+                }),
+            ).rejects.toBe(failure)
+
+            expect(tx.rollbacks).toBe(1)
+            expect(tx.committedWrites).toEqual([])
+        })
+
+        it("rejects an unsafe correlation id before writing any SQL", async () => {
+            const { outbox } = await build()
+            const tx = fakeTransaction(mockEntityManager())
+            await expect(
+                tx.em.transaction((manager) => outbox.write(manager, "mail", {}, "bad\nid")),
+            ).rejects.toMatchObject({ code: QueueErrorCode.CorrelationInvalid })
+            expect(tx.em.query).not.toHaveBeenCalled()
+            expect(tx.rollbacks).toBe(1)
+        })
+    })
+})

package/templates/be/patterns/queues/platform-lite/queue-outbox.service.ts.tpl

@@ -0,0 +1,20 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { isCorrelationId } from "@modules/platform/logging"
+import type { QueueOutbox } from "./queue.port"
+import { QueueError, QueueErrorCode } from "./errors/queue.error"
+import { callDbFunction } from "@modules/platform/database"
+
+@Injectable()
+/** The writing side of the queues: a job is a row of the outbox of the caller's transaction, so it exists exactly when the change that needs it commits. */
+export class QueueOutboxService implements QueueOutbox {
+    constructor(@InjectClock() private readonly clock: Clock) {}
+
+    /** Writes the job in the outbox of the transaction `tx`; the relay adds it to BullMQ after the commit. */
+    async write(tx: EntityManager, queue: string, payload: object, correlationId: string): Promise<void> {
+        if (!isCorrelationId(correlationId)) throw new QueueError({ code: QueueErrorCode.CorrelationInvalid })
+        await callDbFunction(tx, "queue_write", [queue, JSON.stringify(payload), this.clock.now(), correlationId])
+    }
+}

package/templates/be/patterns/queues/platform-lite/queue-outbox.sql.tpl

@@ -30,3 +30,38 @@ with check (queue is not null);
 
 revoke all on table public.queue from public, anon, authenticated;
 grant select, insert, update on table public.queue to app_be;
+
+-- The outbox write, the relay's locked read of the waiting rows and its mark, called through callDbFunction of platform/database
+-- (R334). The read locks the rows it returns for the caller's transaction and skips rows another relay holds.
+create function public.queue_write(p_queue varchar, p_payload jsonb, p_created_at timestamptz, p_correlation_id varchar)
+returns void
+language sql
+as $$
+    insert into public.queue (queue, payload, created_at, correlation_id) values (p_queue, p_payload, p_created_at, p_correlation_id)
+$$;
+
+create function public.queue_waiting(p_batch integer)
+returns table (id uuid, queue varchar, payload jsonb, "correlationId" varchar)
+language sql
+as $$
+    select q.id, q.queue, q.payload, coalesce(q.correlation_id, q.id::text)
+      from public.queue as q
+     where q.sent_at is null
+     order by q.created_at, q.id
+     limit p_batch
+       for update skip locked
+$$;
+
+create function public.queue_mark_sent(p_ids uuid[], p_sent_at timestamptz)
+returns void
+language sql
+as $$
+    update public.queue set sent_at = p_sent_at where id = any(p_ids)
+$$;
+
+revoke all on function public.queue_write(varchar, jsonb, timestamptz, varchar) from public;
+grant execute on function public.queue_write(varchar, jsonb, timestamptz, varchar) to app_be;
+revoke all on function public.queue_waiting(integer) from public;
+grant execute on function public.queue_waiting(integer) to app_be;
+revoke all on function public.queue_mark_sent(uuid[], timestamptz) from public;
+grant execute on function public.queue_mark_sent(uuid[], timestamptz) to app_be;

package/templates/be/patterns/queues/platform-lite/queue-relay.service.spec.ts.tpl

@@ -9,7 +9,10 @@ import { OutboxLogEvent } from "@modules/platform/outbox"
 import type { QueueOptions } from "./queue.options"
 import { QueueRelayService } from "./queue-relay.service"
 import type { QueueTransport } from "./queue-transport.port"
-import { MARK_ROWS_SENT, SELECT_WAITING_ROWS } from "./persistence/queue.sql"
+
+// The statements callDbFunction of platform/database sends for the relay's functions.
+const SELECT_WAITING_ROWS = "SELECT * FROM queue_waiting($1)"
+const MARK_ROWS_SENT = "SELECT * FROM queue_mark_sent($1, $2)"
 
 const AT = "2026-02-03T04:05:06.000Z"
 

package/templates/be/patterns/queues/platform-lite/queue-relay.service.ts.tpl

@@ -9,8 +9,19 @@ import { OutboxRelayPolicy } from "@modules/platform/outbox"
 import { InjectQueueOptions, InjectQueueRelayManagers, InjectQueueTransport } from "./queue.decorators"
 import type { QueueOptions } from "./queue.options"
 import type { QueueTransport } from "./queue-transport.port"
-import { MARK_ROWS_SENT, SELECT_WAITING_ROWS } from "./persistence/queue.sql"
-import type { QueueRow } from "./persistence/queue.rows"
+import { callDbFunction } from "@modules/platform/database"
+
+/** One waiting row queue_waiting returns. */
+interface QueueRow {
+    /** The correlation id recorded by the producer's transaction. */
+    readonly correlationId: string
+    /** The row id: it is the BullMQ job id, so a repeated relay pass adds nothing. */
+    readonly id: string
+    /** The queue the job goes to. */
+    readonly queue: string
+    /** The payload, as the database returns the jsonb value. */
+    readonly payload: object
+}
 
 @Injectable()
 /**
@@ -32,8 +43,8 @@ export class QueueRelayService extends OutboxRelayPolicy<QueueRow> {
         super()
     }
 
-    protected select(tx: EntityManager): Promise<Array<QueueRow>> {
-        return tx.query(SELECT_WAITING_ROWS, [this.options.relayBatch])
+    protected async select(tx: EntityManager): Promise<Array<QueueRow>> {
+        return [...(await callDbFunction<QueueRow>(tx, "queue_waiting", [this.options.relayBatch]))]
     }
 
     protected async deliver(rows: ReadonlyArray<QueueRow>): Promise<void> {
@@ -42,7 +53,7 @@ export class QueueRelayService extends OutboxRelayPolicy<QueueRow> {
     }
 
     protected async mark(tx: EntityManager, rows: ReadonlyArray<QueueRow>): Promise<void> {
-        await tx.query(MARK_ROWS_SENT, [rows.map((row) => row.id), this.clock.now()])
+        await callDbFunction(tx, "queue_mark_sent", [rows.map((row) => row.id), this.clock.now()])
     }
 
     protected idle(): Promise<void> {