@starci/hfs 4.7.31 → 4.7.33

package/templates/be/patterns/idempotency/platform/inbox/inbox.service.spec.ts.tpl

@@ -0,0 +1,388 @@
+import { BATCH_ROWS } from "@modules/platform/database"
+import { IdempotencyErrorCode } from "@modules/platform/idempotency"
+import { Test } from "@nestjs/testing"
+import type { ClientOperation } from "./inbox.port"
+import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { CLAIM_MANAGERS } from "./inbox.decorators"
+import { PostgresInbox } from "./inbox.service"
+import { InboxError, InboxErrorCode } from "./errors/inbox.error"
+import { requestFingerprint } from "./request-fingerprint.policy"
+import { CLAIM_CLIENT, CLAIM_EVENT, RELEASE_EVENT, SAVE_CLIENT_OUTCOME, SWEEP_CLIENTS } from "./persistence/inbox.sql"
+
+const runClient = <T>(
+    inbox: PostgresInbox,
+    request: ClientOperation,
+    manager: ReturnType<typeof mockEntityManager>,
+    effect: () => Promise<T>,
+): Promise<T> => fakeTransaction(manager).em.transaction((tx) => inbox.runClient(request, tx, effect))
+
+const REQUEST = {
+    principalId: "person-1",
+    operation: "checkout.place",
+    idempotencyKey: "key-1",
+    request: { total: 2400 },
+}
+const OUTCOME = { kind: "ok", value: { orderId: "order-1" } }
+
+const build = async (manager: ReturnType<typeof mockEntityManager>) => {
+    const clock = new FakeClock("2026-02-03T04:05:06.000Z")
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            PostgresInbox,
+            { provide: CLAIM_MANAGERS, useValue: [manager] },
+            { provide: CLOCK, useValue: clock },
+        ],
+    }).compile()
+    return moduleRef.get(PostgresInbox)
+}
+
+describe("PostgresInbox claim", () => {
+    it("answers true for the first claim, stamped with the clock", async () => {
+        const manager = mockEntityManager({ query: [CLAIM_EVENT, [{ event_id: "e-1" }]] })
+        const inbox = await build(manager)
+
+        await expect(inbox.claim("payments", "e-1")).resolves.toBe(true)
+        expect(manager.query).toHaveBeenCalledWith(CLAIM_EVENT, [
+            "payments",
+            "e-1",
+            new FakeClock("2026-02-03T04:05:06.000Z").now(),
+        ])
+    })
+
+    it("uses the supplied transaction manager for the claim query without reaching the configured manager", async () => {
+        const configured = mockEntityManager()
+        const tx = fakeTransaction(mockEntityManager({ query: [CLAIM_EVENT, [{ event_id: "e-1" }]] }))
+        const inbox = await build(configured)
+
+        await expect(tx.em.transaction((manager) => inbox.claim("payments", "e-1", manager))).resolves.toBe(true)
+
+        const params = ["payments", "e-1", new FakeClock("2026-02-03T04:05:06.000Z").now()]
+        expect(tx.em.query).toHaveBeenCalledWith(CLAIM_EVENT, params)
+        expect(configured.query).not.toHaveBeenCalled()
+        expect(tx.committedWrites).toEqual([{ method: "query", args: [CLAIM_EVENT, params] }])
+        expect(tx.commits).toBe(1)
+    })
+
+    it("answers false for a duplicate through the supplied manager without falling back to the configured manager", async () => {
+        const configured = mockEntityManager()
+        const supplied = mockEntityManager({ query: [CLAIM_EVENT, []] })
+        const inbox = await build(configured)
+
+        await expect(inbox.claim("payments", "e-1", supplied)).resolves.toBe(false)
+
+        expect(supplied.query).toHaveBeenCalledWith(CLAIM_EVENT, [
+            "payments",
+            "e-1",
+            new FakeClock("2026-02-03T04:05:06.000Z").now(),
+        ])
+        expect(configured.query).not.toHaveBeenCalled()
+    })
+
+    it("propagates the supplied manager query error so its transaction rolls back without root fallback", async () => {
+        const failure = new Error("claim statement failed")
+        const configured = mockEntityManager()
+        const tx = fakeTransaction(mockEntityManager({ query: [CLAIM_EVENT, []] }))
+        tx.em.query.mockRejectedValueOnce(failure)
+        const inbox = await build(configured)
+
+        await expect(tx.em.transaction((manager) => inbox.claim("payments", "e-1", manager))).rejects.toBe(failure)
+
+        expect(configured.query).not.toHaveBeenCalled()
+        expect(tx.rollbacks).toBe(1)
+        expect(tx.commits).toBe(0)
+        expect(tx.committedWrites).toEqual([])
+    })
+
+    it("answers false when the event was claimed before", async () => {
+        const inbox = await build(mockEntityManager({ query: [CLAIM_EVENT, []] }))
+
+        await expect(inbox.claim("payments", "e-1")).resolves.toBe(false)
+    })
+})
+
+describe("PostgresInbox release", () => {
+    it("deletes the claim of the event", async () => {
+        const manager = mockEntityManager({ query: [RELEASE_EVENT, []] })
+        const inbox = await build(manager)
+
+        await expect(inbox.release("payments", "e-1")).resolves.toBeUndefined()
+        expect(manager.query).toHaveBeenCalledWith(RELEASE_EVENT, ["payments", "e-1"])
+    })
+})
+
+describe("PostgresInbox runClient admission", () => {
+    it("refuses a manager outside an active transaction before claiming or applying an effect", async () => {
+        const inbox = await build(mockEntityManager())
+        const manager = mockEntityManager()
+        await expect(inbox.runClient(REQUEST, manager, () => Promise.resolve(OUTCOME))).rejects.toMatchObject({
+            code: InboxErrorCode.TransactionRequired,
+        })
+        expect(manager.query).not.toHaveBeenCalled()
+    })
+
+    it("refuses an existing incomplete claim instead of applying the effect again", async () => {
+        const manager = mockEntityManager({
+            query: [
+                CLAIM_CLIENT,
+                [{ request_fingerprint: requestFingerprint(REQUEST.request), outcome: {}, incomplete: true }],
+            ],
+        })
+        const inbox = await build(mockEntityManager())
+        let calls = 0
+        await expect(
+            runClient(inbox, REQUEST, manager, () => {
+                calls += 1
+                return Promise.resolve(OUTCOME)
+            }),
+        ).rejects.toMatchObject({ code: InboxErrorCode.OutcomeMissing })
+        expect(calls).toBe(0)
+    })
+})
+
+describe("PostgresInbox runClient persistence", () => {
+    it("claims before its callback and returns the persisted outcome through the same transaction", async () => {
+        const configured = mockEntityManager()
+        const manager = mockEntityManager()
+        const fingerprint = requestFingerprint(REQUEST.request)
+        manager.query
+            .mockResolvedValueOnce([{ request_fingerprint: fingerprint, outcome: null }])
+            .mockResolvedValueOnce([{ outcome: { value: OUTCOME } }])
+        const transaction = fakeTransaction(manager)
+        const inbox = await build(configured)
+
+        const outcome = await transaction.em.transaction((tx) =>
+            inbox.runClient(REQUEST, tx, () => {
+                expect(transaction.em.query).toHaveBeenCalledTimes(1)
+                return Promise.resolve(OUTCOME)
+            }),
+        )
+
+        expect(outcome).toEqual(OUTCOME)
+        expect(configured.query).not.toHaveBeenCalled()
+        expect(transaction.em.query).toHaveBeenNthCalledWith(1, CLAIM_CLIENT, [
+            "client:person-1:checkout.place",
+            "key-1",
+            fingerprint,
+            new FakeClock("2026-02-03T04:05:06.000Z").now(),
+        ])
+        expect(transaction.em.query).toHaveBeenNthCalledWith(2, SAVE_CLIENT_OUTCOME, [
+            "client:person-1:checkout.place",
+            "key-1",
+            JSON.stringify({ value: OUTCOME }),
+        ])
+        expect(transaction.commits).toBe(1)
+    })
+})
+
+describe("PostgresInbox runClient replay", () => {
+    it.each([OUTCOME, { kind: "refused", code: "ORDER_EMPTY_CART" }, null])(
+        "replays the stored JSON outcome %p without running the callback",
+        async (outcome) => {
+            const manager = mockEntityManager({
+                query: [
+                    CLAIM_CLIENT,
+                    [
+                        {
+                            request_fingerprint: requestFingerprint(REQUEST.request),
+                            outcome: { value: outcome },
+                        },
+                    ],
+                ],
+            })
+            const inbox = await build(mockEntityManager())
+            let calls = 0
+
+            await expect(
+                runClient(inbox, REQUEST, manager, () => {
+                    calls += 1
+                    return Promise.resolve(outcome)
+                }),
+            ).resolves.toEqual(outcome)
+
+            expect(calls).toBe(0)
+            expect(manager.query).toHaveBeenCalledTimes(1)
+        },
+    )
+})
+
+describe("PostgresInbox runClient key and request validation", () => {
+    it.each(["a-different-fingerprint", null])(
+        "refuses a reused key carrying fingerprint %p before any callback",
+        async (fingerprint) => {
+            const manager = mockEntityManager({
+                query: [CLAIM_CLIENT, [{ request_fingerprint: fingerprint, outcome: { value: OUTCOME } }]],
+            })
+            const inbox = await build(mockEntityManager())
+            let calls = 0
+
+            await expect(
+                runClient(inbox, REQUEST, manager, () => {
+                    calls += 1
+                    return Promise.resolve(OUTCOME)
+                }),
+            ).rejects.toMatchObject({
+                code: IdempotencyErrorCode.KeyReused,
+            })
+
+            expect(calls).toBe(0)
+            expect(manager.query).toHaveBeenCalledTimes(1)
+        },
+    )
+
+    it.each([
+        { ...REQUEST, principalId: " " },
+        { ...REQUEST, principalId: "a:b" },
+        { ...REQUEST, operation: " " },
+        { ...REQUEST, operation: "a:b" },
+        { ...REQUEST, idempotencyKey: " " },
+        { ...REQUEST, idempotencyKey: "a".repeat(65) },
+        { ...REQUEST, request: { unsupported: undefined } },
+    ])("refuses an invalid scope, key or request before querying %p", async (request) => {
+        const manager = mockEntityManager()
+        const inbox = await build(manager)
+
+        await expect(runClient(inbox, request, manager, () => Promise.resolve(OUTCOME))).rejects.toMatchObject({
+            code: IdempotencyErrorCode.RequestInvalid,
+        })
+
+        expect(manager.query).not.toHaveBeenCalled()
+    })
+})
+
+describe("PostgresInbox runClient rollback", () => {
+    it("keeps the exact key and rejects a failed callback by rolling the claim back with the domain transaction", async () => {
+        const manager = mockEntityManager({
+            query: [
+                CLAIM_CLIENT,
+                [
+                    {
+                        request_fingerprint: requestFingerprint(REQUEST.request),
+                        outcome: null,
+                    },
+                ],
+            ],
+        })
+        const transaction = fakeTransaction(manager)
+        const inbox = await build(mockEntityManager())
+        const failure = new InboxError({ code: InboxErrorCode.OutcomeMissing })
+
+        await expect(
+            transaction.em.transaction((tx) =>
+                inbox.runClient({ ...REQUEST, idempotencyKey: " key-1 " }, tx, () => Promise.reject(failure)),
+            ),
+        ).rejects.toBe(failure)
+
+        expect(transaction.em.query).toHaveBeenCalledWith(CLAIM_CLIENT, [
+            "client:person-1:checkout.place",
+            " key-1 ",
+            requestFingerprint(REQUEST.request),
+            new FakeClock("2026-02-03T04:05:06.000Z").now(),
+        ])
+        expect(transaction.rollbacks).toBe(1)
+        expect(transaction.committedWrites).toEqual([])
+    })
+
+    it("propagates a database claim failure without calling the callback", async () => {
+        const manager = mockEntityManager()
+        const failure = new Error("claim failed")
+        manager.query.mockRejectedValueOnce(failure)
+        const inbox = await build(mockEntityManager())
+        let calls = 0
+
+        await expect(
+            runClient(inbox, REQUEST, manager, () => {
+                calls += 1
+                return Promise.resolve(OUTCOME)
+            }),
+        ).rejects.toBe(failure)
+
+        expect(calls).toBe(0)
+    })
+})
+
+describe("PostgresInbox runClient outcome validation", () => {
+    it("refuses a non-JSON callback outcome and rolls back its claim", async () => {
+        const transaction = fakeTransaction(
+            mockEntityManager({
+                query: [
+                    CLAIM_CLIENT,
+                    [
+                        {
+                            request_fingerprint: requestFingerprint(REQUEST.request),
+                            outcome: null,
+                        },
+                    ],
+                ],
+            }),
+        )
+        const inbox = await build(mockEntityManager())
+
+        await expect(
+            transaction.em.transaction((tx) => inbox.runClient(REQUEST, tx, () => Promise.resolve(undefined))),
+        ).rejects.toMatchObject({
+            code: InboxErrorCode.OutcomeInvalid,
+            cause: { code: IdempotencyErrorCode.RequestInvalid },
+        })
+
+        expect(transaction.em.query).toHaveBeenCalledTimes(1)
+        expect(transaction.rollbacks).toBe(1)
+    })
+})
+
+describe("PostgresInbox runClient write failures", () => {
+    it("refuses missing claim and saved rows rather than committing an unrecorded result", async () => {
+        for (const responses of [
+            [[]],
+            [[{ request_fingerprint: requestFingerprint(REQUEST.request), outcome: null }], []],
+        ]) {
+            const manager = mockEntityManager()
+            for (const response of responses) manager.query.mockResolvedValueOnce(response)
+            const transaction = fakeTransaction(manager)
+            const inbox = await build(mockEntityManager())
+
+            await expect(
+                transaction.em.transaction((tx) => inbox.runClient(REQUEST, tx, () => Promise.resolve(OUTCOME))),
+            ).rejects.toMatchObject({
+                code: InboxErrorCode.OutcomeMissing,
+            })
+
+            expect(transaction.rollbacks).toBe(1)
+        }
+    })
+
+    it("rolls back the claim and effect when saving the outcome fails", async () => {
+        const manager = mockEntityManager()
+        const failure = new Error("outcome write failed")
+        manager.query
+            .mockResolvedValueOnce([{ request_fingerprint: requestFingerprint(REQUEST.request), outcome: null }])
+            .mockRejectedValueOnce(failure)
+        const transaction = fakeTransaction(manager)
+        const inbox = await build(mockEntityManager())
+
+        await expect(
+            transaction.em.transaction((tx) => inbox.runClient(REQUEST, tx, () => Promise.resolve(OUTCOME))),
+        ).rejects.toBe(failure)
+
+        expect(transaction.rollbacks).toBe(1)
+        expect(transaction.committedWrites).toEqual([])
+    })
+})
+
+describe("PostgresInbox sweepClients", () => {
+    it.each([
+        { rows: [], expected: 0 },
+        { rows: [{ deleted_count: 0 }], expected: 0 },
+        { rows: [{ deleted_count: 17 }], expected: 17 },
+    ])("returns the bounded deleted row count $expected through the supplied manager", async ({ rows, expected }) => {
+        const configured = mockEntityManager()
+        const manager = mockEntityManager({ query: [SWEEP_CLIENTS, rows] })
+        const inbox = await build(configured)
+        const cutoff = new FakeClock("2026-01-01T00:00:00.000Z").now()
+
+        await expect(inbox.sweepClients(cutoff, manager)).resolves.toBe(expected)
+
+        expect(manager.query).toHaveBeenCalledWith(SWEEP_CLIENTS, [cutoff, BATCH_ROWS])
+        expect(configured.query).not.toHaveBeenCalled()
+    })
+})

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

@@ -0,0 +1,77 @@
+import { BATCH_ROWS } from "@modules/platform/database"
+import { Injectable } from "@nestjs/common"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import type { EntityManager } from "typeorm"
+import { InjectClaimManagers } from "./inbox.decorators"
+import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
+import { InboxError, InboxErrorCode } from "./errors/inbox.error"
+import { clientSource } from "./client-operation.policy"
+import type { ClientOperation, ClientOperationEffect, Inbox } from "./inbox.port"
+import { canonicalJson, requestFingerprint } from "./request-fingerprint.policy"
+import type { ClaimClientRow, InboxEventRow, InboxSweepRow, SavedClientOutcomeRow } from "./persistence/inbox.rows"
+import { CLAIM_CLIENT, CLAIM_EVENT, RELEASE_EVENT, SAVE_CLIENT_OUTCOME, SWEEP_CLIENTS } from "./persistence/inbox.sql"
+
+@Injectable()
+/** The Inbox adapter over the claims table: the unique (source, event id) pair decides who claims first. */
+export class PostgresInbox implements Inbox {
+    constructor(
+        @InjectClaimManagers() private readonly managers: readonly [EntityManager],
+        @InjectClock() private readonly clock: Clock,
+    ) {}
+
+    /** Claims through the caller transaction when supplied, otherwise through the app's configured manager. */
+    async claim(source: string, eventId: string, tx?: EntityManager): Promise<boolean> {
+        const manager = tx ?? this.managers[0]
+        const rows: Array<InboxEventRow> = await manager.query(CLAIM_EVENT, [source, eventId, this.clock.now()])
+        return rows.length > 0
+    }
+
+    /** Deletes the claim so a redelivery is processed again. */
+    async release(source: string, eventId: string): Promise<void> {
+        const [manager] = this.managers
+        await manager.query(RELEASE_EVENT, [source, eventId])
+    }
+
+    /** Runs once in the domain transaction, returning the persisted JSON outcome on both the first call and every retry. */
+    async runClient<T>(request: ClientOperation, tx: EntityManager, effect: ClientOperationEffect<T>): Promise<T> {
+        if (tx.queryRunner?.isTransactionActive !== true)
+            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, [
+            source,
+            request.idempotencyKey,
+            fingerprint,
+            this.clock.now(),
+        ])
+        const claim = rows[0]
+        if (!claim) throw new InboxError({ code: InboxErrorCode.OutcomeMissing })
+        if (claim.request_fingerprint !== fingerprint)
+            throw new IdempotencyError({ code: IdempotencyErrorCode.KeyReused })
+        if (claim.incomplete) throw new InboxError({ code: InboxErrorCode.OutcomeMissing })
+        if (claim.outcome !== null) return claim.outcome.value
+
+        const value = await effect()
+        let outcome: string
+        try {
+            outcome = canonicalJson({ value })
+        } catch (cause) {
+            throw new InboxError({ code: InboxErrorCode.OutcomeInvalid, cause })
+        }
+        const saved: Array<SavedClientOutcomeRow<T>> = await tx.query(SAVE_CLIENT_OUTCOME, [
+            source,
+            request.idempotencyKey,
+            outcome,
+        ])
+        const recorded = saved[0]
+        if (!recorded) throw new InboxError({ code: InboxErrorCode.OutcomeMissing })
+        return recorded.outcome.value
+    }
+
+    /** 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])
+        return rows[0]?.deleted_count ?? 0
+    }
+}

package/templates/be/patterns/idempotency/platform/inbox/index.ts.tpl

@@ -0,0 +1,10 @@
+export { inboxEntities, inboxMigrations } from "./persistence/connection"
+export { INBOX, InjectInbox } from "./inbox.decorators"
+export { Effectful } from "./effectful.decorators"
+export { InboxModule } from "./inbox.module"
+export type { Inbox } from "./inbox.port"
+export { INBOX_ERROR_KINDS } from "./errors/inbox.error"
+export { INBOX_MESSAGES } from "./messages/inbox.messages"
+export { backfillClientOutcome } from "./client-outcome-backfill.client"
+export { backfillDeliveryClaim } from "./delivery-claim-backfill.client"
+export { releaseDeliveryClaim } from "./delivery-claim-release.client"

package/templates/be/patterns/idempotency/platform/inbox/messages/inbox.messages.ts.tpl

@@ -0,0 +1,15 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the inbox codes. */
+export const INBOX_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.INBOX_OUTCOME_INVALID": "Kết quả thao tác không phải dữ liệu JSON thuần nên không thể lưu.",
+        "errors.INBOX_OUTCOME_MISSING": "Không lưu được kết quả thao tác.",
+        "errors.INBOX_TRANSACTION_REQUIRED": "Thao tác này cần một giao dịch đang hoạt động.",
+    },
+    en: {
+        "errors.INBOX_OUTCOME_INVALID": "The operation outcome is not plain JSON data, so it cannot be stored.",
+        "errors.INBOX_OUTCOME_MISSING": "The operation outcome could not be recorded.",
+        "errors.INBOX_TRANSACTION_REQUIRED": "This operation requires an active transaction.",
+    },
+}

package/templates/be/patterns/idempotency/platform/inbox/persistence/connection.ts.tpl

@@ -0,0 +1,9 @@
+import { InboxClaimEntity } from "./entities/inbox-claim.entity"
+import { CreateInboxClaims1789800005000 } from "./migrations/1789800005000-create-inbox-claims"
+import { ClientOperationOutcomes1792800000000 } from "./migrations/1792800000000-client-operation-outcomes"
+
+/** The entities of the inbox capability, for the connection that holds them. */
+export const inboxEntities = [InboxClaimEntity]
+
+/** The migrations of the inbox capability, in the order they run. */
+export const inboxMigrations = [CreateInboxClaims1789800005000, ClientOperationOutcomes1792800000000]

package/templates/be/patterns/idempotency/platform/inbox/persistence/entities/inbox-claim.entity.ts.tpl

@@ -0,0 +1,25 @@
+import { Column, Entity, PrimaryColumn } from "typeorm"
+
+@Entity("inbox_claims")
+/** One row per event a consumer or webhook has claimed: the pair (source, event id) is unique. */
+export class InboxClaimEntity {
+    /** The consumer queue or webhook the event arrived through. */
+    @PrimaryColumn({ name: "source", type: "varchar", length: 200 })
+    source!: string
+
+    /** The event id the provider or producer supplied. */
+    @PrimaryColumn({ name: "event_id", type: "varchar", length: 200 })
+    eventId!: string
+
+    /** When the event was claimed. */
+    @Column({ name: "claimed_at", type: "timestamptz" })
+    claimedAt!: Date
+
+    /** The canonical JSON request's SHA-256; null for provider and broker deliveries. */
+    @Column({ name: "request_fingerprint", type: "varchar", length: 64, nullable: true })
+    requestFingerprint!: string | null
+
+    /** A completed client operation's JSON envelope, including expected refusals. */
+    @Column({ name: "outcome", type: "jsonb", nullable: true })
+    outcome!: object | null
+}

package/templates/be/patterns/idempotency/platform/inbox/persistence/inbox.rows.ts.tpl

@@ -0,0 +1,33 @@
+/** The JSON envelope makes a completed null value distinct from a pending SQL-null outcome. */
+export interface ClientOutcomeRow<T> {
+    /** The operation's complete JSON result, including expected refusals. */
+    readonly value: T
+}
+
+/** The row returned by the atomic client claim. */
+export 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. */
+export 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. */
+export interface InboxEventRow {
+    /** The event or client key owned by the row. */
+    readonly event_id: string
+}
+
+/** The bounded retention batch's aggregate result. */
+export interface InboxSweepRow {
+    /** Number of completed client claims removed by this transaction. */
+    readonly deleted_count: number
+}

package/templates/be/patterns/idempotency/platform/inbox/persistence/inbox.sql.ts.tpl

@@ -0,0 +1,39 @@
+import { sql } from "@modules/platform/database"
+
+/** Claims the event ($1 source, $2 event id, $3 instant); answers one row when this call won and none when it was claimed before. */
+export const CLAIM_EVENT = sql`INSERT INTO inbox_claims (source, event_id, claimed_at) VALUES ($1, $2, $3)
+    ON CONFLICT (source, event_id) DO NOTHING RETURNING event_id`
+
+/** Gives a delivery claim back; client outcomes can expire only through the retention API. */
+export const RELEASE_EVENT = sql`DELETE FROM inbox_claims WHERE source = $1 AND event_id = $2 AND request_fingerprint IS NULL`
+
+/** A conflicting insert locks the existing row and returns its committed fingerprint and outcome after the winner commits. */
+export const CLAIM_CLIENT = sql`INSERT INTO inbox_claims (source, event_id, request_fingerprint, claimed_at)
+VALUES ($1, $2, $3, $4)
+ON CONFLICT (source, event_id) DO UPDATE SET outcome = COALESCE(inbox_claims.outcome, '{}'::jsonb)
+RETURNING request_fingerprint, outcome, (outcome IS NOT NULL AND (jsonb_typeof(outcome) <> 'object' OR NOT (outcome ? 'value'))) AS incomplete`
+
+/** The JSON envelope distinguishes a completed null result from an uncompleted claim in this transaction. */
+export const SAVE_CLIENT_OUTCOME = sql`WITH saved AS (
+    UPDATE inbox_claims SET outcome = $3::jsonb
+    WHERE source = $1 AND event_id = $2
+    RETURNING outcome
+)
+SELECT outcome FROM saved LIMIT 1`
+
+/** Retention never deletes delivery rows or an incomplete claim; its bounded batch skips rows held by active retries. */
+export const SWEEP_CLIENTS = sql`WITH expired AS (
+    SELECT source, event_id FROM inbox_claims
+    WHERE source LIKE 'client:%' AND request_fingerprint IS NOT NULL AND outcome IS NOT NULL AND jsonb_typeof(outcome) = 'object' AND outcome ? 'value' AND claimed_at < $1
+    ORDER BY claimed_at, source, event_id LIMIT $2 FOR UPDATE SKIP LOCKED
+), deleted AS (
+DELETE FROM inbox_claims AS claims USING expired
+WHERE claims.source = expired.source AND claims.event_id = expired.event_id
+RETURNING claims.event_id
+)
+SELECT count(*)::int AS deleted_count FROM deleted`
+
+/** Imports an already completed legacy operation without replacing a key another migration has already transferred. */
+export const BACKFILL_CLIENT_OUTCOME = sql`INSERT INTO inbox_claims (source, event_id, request_fingerprint, claimed_at, outcome)
+VALUES ($1, $2, $3, $4, $5::jsonb)
+ON CONFLICT (source, event_id) DO NOTHING`

package/templates/be/patterns/idempotency/platform/inbox/persistence/migrations/1789800005000-create-inbox-claims.ts.tpl

@@ -0,0 +1,21 @@
+import type { MigrationInterface, QueryRunner } from "typeorm"
+
+/** Creates the table the inbox claims events in. */
+export class CreateInboxClaims1789800005000 implements MigrationInterface {
+    name = "CreateInboxClaims1789800005000"
+
+    /** Creates the claims table. */
+    async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE TABLE inbox_claims (
+    source varchar(200) NOT NULL,
+    event_id varchar(200) NOT NULL,
+    claimed_at timestamptz NOT NULL,
+    PRIMARY KEY (source, event_id)
+)`)
+    }
+
+    /** Drops the claims table. */
+    async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP TABLE inbox_claims`)
+    }
+}

package/templates/be/patterns/idempotency/platform/inbox/persistence/migrations/1792800000000-client-operation-outcomes.ts.tpl

@@ -0,0 +1,21 @@
+import type { MigrationInterface, QueryRunner } from "typeorm"
+
+/** Extends the one shared inbox to retain a client operation's request identity and outcome. */
+export class ClientOperationOutcomes1792800000000 implements MigrationInterface {
+    name = "ClientOperationOutcomes1792800000000"
+
+    /** Adds nullable columns so existing delivery claims retain their meaning. */
+    async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`ALTER TABLE inbox_claims
+ADD COLUMN request_fingerprint varchar(64),
+ADD COLUMN outcome jsonb`)
+        await queryRunner.query(`CREATE INDEX inbox_claims_client_retention_idx ON inbox_claims (claimed_at, source, event_id)
+WHERE source LIKE 'client:%' AND request_fingerprint IS NOT NULL AND outcome IS NOT NULL`)
+    }
+
+    /** Removes the client outcome extension. */
+    async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX inbox_claims_client_retention_idx`)
+        await queryRunner.query(`ALTER TABLE inbox_claims DROP COLUMN outcome, DROP COLUMN request_fingerprint`)
+    }
+}