@starci/hfs 4.7.31 → 4.7.33

package/templates/be/inbox/platform/inbox/client-operation.policy.ts.tpl

@@ -0,0 +1,17 @@
+import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
+import type { ClientOperation } from "./inbox.port"
+
+/** Builds the authenticated operation scope after checking that its separators and bounded key are unambiguous. */
+export const clientSource = (request: ClientOperation): string => {
+    if (
+        !request.principalId.trim() ||
+        request.principalId.includes(":") ||
+        !request.operation.trim() ||
+        request.operation.includes(":") ||
+        !request.idempotencyKey.trim() ||
+        request.idempotencyKey.length > 64
+    ) {
+        throw new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid })
+    }
+    return `client:${request.principalId}:${request.operation}`
+}

package/templates/be/inbox/platform/inbox/errors/inbox.error.ts.tpl

@@ -0,0 +1,22 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Stable refusals and integrity errors of the shared client inbox. */
+export enum InboxErrorCode {
+    /** The caller supplied a manager outside an active domain transaction. */
+    TransactionRequired = "INBOX_TRANSACTION_REQUIRED",
+    /** The effect returned a value that is not plain JSON data, so no outcome can be stored or replayed. */
+    OutcomeInvalid = "INBOX_OUTCOME_INVALID",
+    /** The atomic claim or outcome write returned no completed row. */
+    OutcomeMissing = "INBOX_OUTCOME_MISSING",
+}
+
+/** The shared transport mapping of inbox errors. */
+export const INBOX_ERROR_KINDS: Record<InboxErrorCode, ErrorKind> = {
+    [InboxErrorCode.OutcomeInvalid]: "internal",
+    [InboxErrorCode.OutcomeMissing]: "internal",
+    [InboxErrorCode.TransactionRequired]: "internal",
+}
+
+/** The error family of the inbox owner. */
+export class InboxError extends DomainError<InboxErrorCode> {}

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

@@ -1,5 +1,22 @@
 import type { EntityManager } from "typeorm"
 
+/** The authenticated scope and complete normalized body of a client operation; the key is never part of the body. */
+export interface ClientOperation {
+    /** The authenticated principal, mapped by the transport rather than supplied by its client. */
+    readonly principalId: string
+    /** A stable operation name; neither it nor the principal may contain a colon. */
+    readonly operation: string
+    /** The client's nonempty key, at most 64 characters. */
+    readonly idempotencyKey: string
+    /** JSON data that identifies every client-controlled input affecting the result. */
+    readonly request: unknown
+}
+
+/** The domain work whose JSON result commits with the client receipt. */
+export interface ClientOperationEffect<T> {
+    (): Promise<T>
+}
+
 /** The signed provider header may omit its delivery identity; the adapter refuses that delivery. */
 export type InboxEventId = string | undefined
 
@@ -7,4 +24,8 @@ export type InboxEventId = string | undefined
 export interface Inbox {
     /** Claims once per source and event id; a rolled-back transaction gives the claim back automatically. */
     claim(source: string, eventId: InboxEventId, tx: EntityManager): Promise<boolean>
+    /** Claims, applies and records one JSON outcome inside the caller transaction; retries replay it. */
+    runClient<T>(request: ClientOperation, tx: EntityManager, effect: ClientOperationEffect<T>): Promise<T>
+    /** Deletes one bounded batch of completed client claims older than the cutoff. */
+    sweepClients(cutoff: Date, tx: EntityManager): Promise<number>
 }

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

@@ -1,20 +1,44 @@
+import { IdempotencyErrorCode } from "@modules/platform/idempotency"
 import { Test } from "@nestjs/testing"
-import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
-import { DatabaseErrorCode } from "@modules/platform/database"
+import type { ClientOperation } from "./inbox.port"
+import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { BATCH_ROWS, DatabaseError, DatabaseErrorCode } from "@modules/platform/database"
+import { CLOCK } from "@modules/platform/clock"
+import { InboxError, InboxErrorCode } from "./errors/inbox.error"
+import { requestFingerprint } from "./request-fingerprint.policy"
 import { PostgresInbox } from "./inbox.service"
-import { CLAIM_EVENT } from "./persistence/inbox.sql"
+import { CLAIM_CLIENT, CLAIM_EVENT, SAVE_CLIENT_OUTCOME, SWEEP_CLIENTS } from "./persistence/inbox.sql"
 
-describe("PostgresInbox", () => {
-    const build = async () => {
-        const module = await Test.createTestingModule({ providers: [PostgresInbox] }).compile()
-        return module.get(PostgresInbox)
-    }
+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 () => {
+    const module = await Test.createTestingModule({
+        providers: [PostgresInbox, { provide: CLOCK, useValue: new FakeClock("2026-02-03T04:05:06.000Z") }],
+    }).compile()
+    return module.get(PostgresInbox)
+}
+
+describe("PostgresInbox delivery claims", () => {
     it("claims a normalized delivery id through the caller's transaction", async () => {
         const subject = await build()
         const transaction = fakeTransaction(mockEntityManager({ query: [CLAIM_EVENT, [{ event_id: "delivery-1" }]] }))
 
-        const fresh = await transaction.em.transaction((manager) => subject.claim("webhook:spec", "  delivery-1  ", manager))
+        const fresh = await transaction.em.transaction((manager) =>
+            subject.claim("webhook:spec", "  delivery-1  ", manager),
+        )
 
         expect(fresh).toBe(true)
         expect(transaction.em.query).toHaveBeenCalledWith(CLAIM_EVENT, ["webhook:spec", "delivery-1"])
@@ -29,13 +53,312 @@ describe("PostgresInbox", () => {
 
         expect(manager.query).toHaveBeenCalledTimes(1)
     })
+})
+
+describe("PostgresInbox delivery rollback and validation", () => {
+    it("rolls the claim back when later work in the receipt transaction fails", async () => {
+        const subject = await build()
+        const transaction = fakeTransaction(mockEntityManager({ query: [CLAIM_EVENT, [{ event_id: "delivery-1" }]] }))
+        const failure = new DatabaseError({ code: DatabaseErrorCode.IdentifierRejected })
+
+        await expect(
+            transaction.em.transaction(async (manager) => {
+                expect(await subject.claim("webhook:spec", "delivery-1", manager)).toBe(true)
+                throw failure
+            }),
+        ).rejects.toBe(failure)
+
+        expect(transaction.commits).toBe(0)
+        expect(transaction.rollbacks).toBe(1)
+        expect(transaction.committedWrites).toEqual([])
+        expect(transaction.rolledBackWrites).toHaveLength(1)
+    })
 
-    it.each([["no", undefined], ["a blank", "   "]])("refuses %s delivery id before writing a claim", async (_label, eventId) => {
+    it.each([
+        ["no", undefined],
+        ["a blank", "   "],
+    ])("refuses %s delivery id before writing a claim", async (_label, eventId) => {
         const subject = await build()
         const manager = mockEntityManager()
 
-        await expect(subject.claim("webhook:spec", eventId, manager)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+        await expect(subject.claim("webhook:spec", eventId, manager)).rejects.toMatchObject({
+            code: DatabaseErrorCode.WebhookDeliveryIdRequired,
+        })
+
+        expect(manager.query).not.toHaveBeenCalled()
+    })
+})
+
+describe("PostgresInbox client transaction admission", () => {
+    it("refuses a manager outside an active transaction before claiming or applying an effect", async () => {
+        const inbox = await build()
+        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()
+        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 client outcome persistence", () => {
+    it("claims before its callback and returns the persisted outcome through the same transaction", async () => {
+        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()
+
+        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(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 client replay and fingerprint identity", () => {
+    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()
+            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)
+        },
+    )
+
+    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()
+            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)
+        },
+    )
+})
+
+describe("PostgresInbox client request validation", () => {
+    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()
+
+        await expect(runClient(inbox, request, manager, () => Promise.resolve(OUTCOME))).rejects.toMatchObject({
+            code: IdempotencyErrorCode.RequestInvalid,
+        })
 
         expect(manager.query).not.toHaveBeenCalled()
     })
 })
+
+describe("PostgresInbox client effect 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()
+        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([])
+    })
+})
+
+describe("PostgresInbox client claim and serialization failures", () => {
+    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()
+        let calls = 0
+
+        await expect(
+            runClient(inbox, REQUEST, manager, () => {
+                calls += 1
+                return Promise.resolve(OUTCOME)
+            }),
+        ).rejects.toBe(failure)
+
+        expect(calls).toBe(0)
+    })
+
+    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()
+
+        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 client incomplete database responses", () => {
+    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()
+
+            await expect(
+                transaction.em.transaction((tx) => inbox.runClient(REQUEST, tx, () => Promise.resolve(OUTCOME))),
+            ).rejects.toMatchObject({
+                code: InboxErrorCode.OutcomeMissing,
+            })
+
+            expect(transaction.rollbacks).toBe(1)
+        }
+    })
+})
+
+describe("PostgresInbox client outcome write rollback", () => {
+    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()
+
+        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 client retention", () => {
+    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 manager = mockEntityManager({ query: [SWEEP_CLIENTS, rows] })
+        const inbox = await build()
+        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])
+    })
+})

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

@@ -1,19 +1,70 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
-import { DatabaseError, DatabaseErrorCode } from "@modules/platform/database"
-import type { Inbox, InboxEventId } from "./inbox.port"
-import { CLAIM_EVENT } from "./persistence/inbox.sql"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { BATCH_ROWS, DatabaseError, DatabaseErrorCode } 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"
 
 @Injectable()
 /** Claims a delivery with the receipt transaction, so a failure can be retried without losing the delivery. */
 export class PostgresInbox implements Inbox {
+    constructor(@InjectClock() private readonly clock: Clock) {}
+
     /** The first claim wins; the same source and delivery id becomes a no-op on redelivery. */
     async claim(source: string, eventId: InboxEventId, tx: EntityManager): Promise<boolean> {
         const normalizedEventId = eventId?.trim()
         if (!normalizedEventId) {
             throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
         }
-        const rows: Array<object> = await tx.query(CLAIM_EVENT, [source, normalizedEventId])
+        const rows: Array<InboxEventRow> = await tx.query(CLAIM_EVENT, [source, normalizedEventId])
         return rows.length > 0
     }
+
+    /** 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/inbox/platform/inbox/index.ts.tpl

@@ -1,3 +1,5 @@
 export { INBOX, InjectInbox } from "./inbox.decorators"
 export { InboxModule } from "./inbox.module"
 export type { Inbox, InboxEventId } from "./inbox.port"
+export { INBOX_ERROR_KINDS } from "./errors/inbox.error"
+export { INBOX_MESSAGES } from "./messages/inbox.messages"

package/templates/be/inbox/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/inbox/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/inbox/platform/inbox/persistence/inbox.sql.ts.tpl

@@ -5,3 +5,29 @@ export const CLAIM_EVENT = sql`INSERT INTO public.inbox (source, event_id)
 VALUES ($1, $2)
 ON CONFLICT (source, event_id) DO NOTHING
 RETURNING event_id`
+
+/** 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 public.inbox (source, event_id, request_fingerprint, claimed_at)
+VALUES ($1, $2, $3, $4)
+ON CONFLICT (source, event_id) DO UPDATE SET outcome = COALESCE(inbox.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 public.inbox 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 public.inbox
+    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 public.inbox 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`