@starci/hfs 4.7.32 → 4.7.33

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

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

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

@@ -9,6 +9,7 @@ export class CreateEventOutbox@@epochMs13@@ implements MigrationInterface {
         await queryRunner.query(`CREATE TABLE event_outbox (
     id bigserial PRIMARY KEY,
     event_id varchar(200) NOT NULL,
+    correlation_id varchar(128) NOT NULL DEFAULT pg_catalog.gen_random_uuid()::text,
     event_name varchar(200) NOT NULL,
     topic varchar(200) NOT NULL,
     message_key varchar(200) NOT NULL,

package/templates/be/patterns/idempotency/platform/idempotency/errors/idempotency.error.ts.tpl

@@ -0,0 +1,19 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Stable client-operation refusals shared by transports and durable inbox adapters. */
+export enum IdempotencyErrorCode {
+    /** This principal's operation key was already used for a different request. */
+    KeyReused = "IDEMPOTENCY_KEY_REUSED",
+    /** The key, authenticated scope or JSON data cannot identify a valid operation. */
+    RequestInvalid = "IDEMPOTENCY_REQUEST_INVALID",
+}
+
+/** Transport kinds of the public idempotency refusals. */
+export const IDEMPOTENCY_ERROR_KINDS: Record<IdempotencyErrorCode, ErrorKind> = {
+    [IdempotencyErrorCode.KeyReused]: "conflict",
+    [IdempotencyErrorCode.RequestInvalid]: "invalid",
+}
+
+/** The public idempotency error family. */
+export class IdempotencyError extends DomainError<IdempotencyErrorCode> {}

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

@@ -0,0 +1,2 @@
+export { IdempotencyError, IdempotencyErrorCode, IDEMPOTENCY_ERROR_KINDS } from "./errors/idempotency.error"
+export { IDEMPOTENCY_MESSAGES } from "./messages/idempotency.messages"

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

@@ -0,0 +1,13 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the public client-operation refusals. */
+export const IDEMPOTENCY_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.IDEMPOTENCY_KEY_REUSED": "Khóa thao tác đã được dùng cho nội dung khác.",
+        "errors.IDEMPOTENCY_REQUEST_INVALID": "Khóa, phạm vi hoặc dữ liệu thao tác không hợp lệ.",
+    },
+    en: {
+        "errors.IDEMPOTENCY_KEY_REUSED": "This operation key was already used with a different request.",
+        "errors.IDEMPOTENCY_REQUEST_INVALID": "The operation key, scope or JSON data is invalid.",
+    },
+}

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

@@ -0,0 +1,32 @@
+import { Test } from "@nestjs/testing"
+import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
+import { clientSource } from "./client-operation.policy"
+
+const CLIENT_SOURCE = Symbol("client-source")
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: CLIENT_SOURCE, useValue: clientSource }],
+    }).compile()
+    return moduleRef.get<typeof clientSource>(CLIENT_SOURCE)
+}
+
+const REQUEST = { principalId: "person-1", operation: "checkout.place", idempotencyKey: "key-1", request: {} }
+
+describe("clientSource", () => {
+    it("binds the exact authenticated principal and operation and accepts a 64-character key", async () => {
+        const sourceOf = await build()
+        expect(sourceOf({ ...REQUEST, idempotencyKey: "a".repeat(64) })).toBe("client:person-1:checkout.place")
+    })
+
+    it.each([
+        { ...REQUEST, principalId: " " },
+        { ...REQUEST, principalId: "a:b" },
+        { ...REQUEST, operation: " " },
+        { ...REQUEST, operation: "a:b" },
+        { ...REQUEST, idempotencyKey: " " },
+        { ...REQUEST, idempotencyKey: "a".repeat(65) },
+    ])("refuses ambiguous scopes and unbounded or empty keys %p", async (request) => {
+        const sourceOf = await build()
+        expect(() => sourceOf(request)).toThrow(new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid }))
+    })
+})

package/templates/be/patterns/idempotency/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/patterns/idempotency/platform/inbox/client-outcome-backfill.client.spec.ts.tpl

@@ -0,0 +1,66 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { InboxErrorCode } from "./errors/inbox.error"
+import { requestFingerprint } from "./request-fingerprint.policy"
+import { backfillClientOutcome } from "./client-outcome-backfill.client"
+import { BACKFILL_CLIENT_OUTCOME } from "./persistence/inbox.sql"
+
+const BACKFILL = Symbol("client-outcome-backfill")
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: BACKFILL, useValue: backfillClientOutcome }],
+    }).compile()
+    return moduleRef.get<typeof backfillClientOutcome>(BACKFILL)
+}
+
+const OPERATION = {
+    principalId: "person-1",
+    operation: "checkout.place-order",
+    idempotencyKey: "legacy-key",
+    request: {},
+}
+const OUTCOME = { kind: "ok", value: { orderId: "old-order", status: "pending" } }
+
+describe("backfillClientOutcome", () => {
+    it("records the legacy scoped key, original instant, fingerprint and original JSON outcome through the migration transaction", async () => {
+        const backfill = await build()
+        const manager = mockEntityManager({ query: [BACKFILL_CLIENT_OUTCOME, []] })
+        const transaction = fakeTransaction(manager)
+        const instant = new FakeClock("2026-01-01T00:00:00.000Z").now()
+
+        await transaction.em.transaction((tx) => backfill(tx, OPERATION, OUTCOME, instant))
+
+        expect(transaction.em.query).toHaveBeenCalledWith(BACKFILL_CLIENT_OUTCOME, [
+            "client:person-1:checkout.place-order",
+            "legacy-key",
+            requestFingerprint({}),
+            instant,
+            '{"value":{"kind":"ok","value":{"orderId":"old-order","status":"pending"}}}',
+        ])
+        expect(transaction.commits).toBe(1)
+    })
+
+    it("refuses a migration outside its active transaction before recording anything", async () => {
+        const backfill = await build()
+        const manager = mockEntityManager()
+
+        await expect(backfill(manager, OPERATION, OUTCOME, new FakeClock().now())).rejects.toMatchObject({
+            code: InboxErrorCode.TransactionRequired,
+        })
+
+        expect(manager.query).not.toHaveBeenCalled()
+    })
+
+    it("propagates a failed insert so the domain migration rolls back", async () => {
+        const backfill = await build()
+        const manager = mockEntityManager()
+        const failure = new Error("backfill insert failed")
+        manager.query.mockRejectedValueOnce(failure)
+        const transaction = fakeTransaction(manager)
+
+        await expect(
+            transaction.em.transaction((tx) => backfill(tx, OPERATION, OUTCOME, new FakeClock().now())),
+        ).rejects.toBe(failure)
+        expect(transaction.rollbacks).toBe(1)
+    })
+})

package/templates/be/patterns/idempotency/platform/inbox/client-outcome-backfill.client.ts.tpl

@@ -0,0 +1,24 @@
+import type { EntityManager } from "typeorm"
+import { clientSource } from "./client-operation.policy"
+import { InboxError, InboxErrorCode } from "./errors/inbox.error"
+import type { ClientOperation } from "./inbox.port"
+import { canonicalJson, requestFingerprint } from "./request-fingerprint.policy"
+import { BACKFILL_CLIENT_OUTCOME } from "./persistence/inbox.sql"
+
+/** Transfers a capability's legacy completed operation into the shared inbox during its data migration. */
+export const backfillClientOutcome = async (
+    manager: EntityManager,
+    operation: ClientOperation,
+    outcome: unknown,
+    claimedAt: Date,
+): Promise<void> => {
+    if (manager.queryRunner?.isTransactionActive !== true)
+        throw new InboxError({ code: InboxErrorCode.TransactionRequired })
+    await manager.query(BACKFILL_CLIENT_OUTCOME, [
+        clientSource(operation),
+        operation.idempotencyKey,
+        requestFingerprint(operation.request),
+        claimedAt,
+        canonicalJson({ value: outcome }),
+    ])
+}

package/templates/be/patterns/idempotency/platform/inbox/delivery-claim-backfill.client.spec.ts.tpl

@@ -0,0 +1,60 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { InboxErrorCode } from "./errors/inbox.error"
+import { backfillDeliveryClaim } from "./delivery-claim-backfill.client"
+import { CLAIM_EVENT } from "./persistence/inbox.sql"
+
+const BACKFILL_DELIVERY = Symbol("delivery-claim-backfill")
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: BACKFILL_DELIVERY, useValue: backfillDeliveryClaim }],
+    }).compile()
+    return moduleRef.get<typeof backfillDeliveryClaim>(BACKFILL_DELIVERY)
+}
+
+const CLAIM = {
+    source: "saga:place-order",
+    eventId: "event-1",
+    claimedAt: new FakeClock("2026-01-01T00:00:00.000Z").now(),
+}
+
+describe("backfillDeliveryClaim", () => {
+    it.each([{ rows: [{ event_id: "event-1" }] }, { rows: [] }])(
+        "preserves the legacy scope and instant without replacing an existing receipt: %p",
+        async ({ rows }) => {
+            const backfill = await build()
+            const transaction = fakeTransaction(mockEntityManager({ query: [CLAIM_EVENT, rows] }))
+
+            await expect(transaction.em.transaction((manager) => backfill(manager, CLAIM))).resolves.toBeUndefined()
+
+            expect(transaction.em.query).toHaveBeenCalledWith(CLAIM_EVENT, [
+                CLAIM.source,
+                CLAIM.eventId,
+                CLAIM.claimedAt,
+            ])
+            expect(transaction.commits).toBe(1)
+        },
+    )
+
+    it("refuses a manager outside an active migration transaction before transferring a claim", async () => {
+        const backfill = await build()
+        const manager = mockEntityManager()
+
+        await expect(backfill(manager, CLAIM)).rejects.toMatchObject({ code: InboxErrorCode.TransactionRequired })
+
+        expect(manager.query).not.toHaveBeenCalled()
+    })
+
+    it("propagates a failed claim statement so the capability migration rolls back", async () => {
+        const backfill = await build()
+        const manager = mockEntityManager()
+        const failure = new Error("delivery claim transfer failed")
+        manager.query.mockRejectedValueOnce(failure)
+        const transaction = fakeTransaction(manager)
+
+        await expect(transaction.em.transaction((tx) => backfill(tx, CLAIM))).rejects.toBe(failure)
+
+        expect(transaction.rollbacks).toBe(1)
+        expect(transaction.committedWrites).toEqual([])
+    })
+})

package/templates/be/patterns/idempotency/platform/inbox/delivery-claim-backfill.client.ts.tpl

@@ -0,0 +1,12 @@
+import type { EntityManager } from "typeorm"
+import { InboxError, InboxErrorCode } from "./errors/inbox.error"
+import type { DeliveryClaimBackfill } from "./inbox.port"
+import { CLAIM_EVENT } from "./persistence/inbox.sql"
+
+/** Transfers a legacy delivery claim inside its owning capability's migration transaction. */
+export const backfillDeliveryClaim = async (manager: EntityManager, claim: DeliveryClaimBackfill): Promise<void> => {
+    if (manager.queryRunner?.isTransactionActive !== true) {
+        throw new InboxError({ code: InboxErrorCode.TransactionRequired })
+    }
+    await manager.query(CLAIM_EVENT, [claim.source, claim.eventId, claim.claimedAt])
+}

package/templates/be/patterns/idempotency/platform/inbox/delivery-claim-release.client.spec.ts.tpl

@@ -0,0 +1,49 @@
+import { Test } from "@nestjs/testing"
+import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { InboxErrorCode } from "./errors/inbox.error"
+import { releaseDeliveryClaim } from "./delivery-claim-release.client"
+import { RELEASE_EVENT } from "./persistence/inbox.sql"
+
+const RELEASE_DELIVERY = Symbol("delivery-claim-release")
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: RELEASE_DELIVERY, useValue: releaseDeliveryClaim }],
+    }).compile()
+    return moduleRef.get<typeof releaseDeliveryClaim>(RELEASE_DELIVERY)
+}
+
+const CLAIM = { source: "saga:place-order", eventId: "event-1" }
+
+describe("releaseDeliveryClaim", () => {
+    it("uses the protected delivery delete through the migration's transaction", async () => {
+        const release = await build()
+        const transaction = fakeTransaction(mockEntityManager({ query: [RELEASE_EVENT, []] }))
+
+        await transaction.em.transaction((manager) => release(manager, CLAIM))
+
+        expect(transaction.em.query).toHaveBeenCalledWith(RELEASE_EVENT, [CLAIM.source, CLAIM.eventId])
+        expect(transaction.commits).toBe(1)
+    })
+
+    it("refuses to release a receipt outside an active migration transaction", async () => {
+        const release = await build()
+        const manager = mockEntityManager()
+
+        await expect(release(manager, CLAIM)).rejects.toMatchObject({ code: InboxErrorCode.TransactionRequired })
+
+        expect(manager.query).not.toHaveBeenCalled()
+    })
+
+    it("propagates a failed delete so restoring and releasing the receipt roll back together", async () => {
+        const release = await build()
+        const manager = mockEntityManager()
+        const failure = new Error("delivery claim release failed")
+        manager.query.mockRejectedValueOnce(failure)
+        const transaction = fakeTransaction(manager)
+
+        await expect(transaction.em.transaction((tx) => release(tx, CLAIM))).rejects.toBe(failure)
+
+        expect(transaction.rollbacks).toBe(1)
+        expect(transaction.committedWrites).toEqual([])
+    })
+})

package/templates/be/patterns/idempotency/platform/inbox/delivery-claim-release.client.ts.tpl

@@ -0,0 +1,12 @@
+import type { EntityManager } from "typeorm"
+import { InboxError, InboxErrorCode } from "./errors/inbox.error"
+import type { DeliveryClaim } from "./inbox.port"
+import { RELEASE_EVENT } from "./persistence/inbox.sql"
+
+/** Transfers a delivery receipt's authority back after its legacy owner restored the receipt in the same transaction. */
+export const releaseDeliveryClaim = async (manager: EntityManager, claim: DeliveryClaim): Promise<void> => {
+    if (manager.queryRunner?.isTransactionActive !== true) {
+        throw new InboxError({ code: InboxErrorCode.TransactionRequired })
+    }
+    await manager.query(RELEASE_EVENT, [claim.source, claim.eventId])
+}

package/templates/be/patterns/idempotency/platform/inbox/effectful.decorators.ts.tpl

@@ -0,0 +1,7 @@
+import { SetMetadata } from "@nestjs/common"
+
+/** Metadata of a client command whose effects require a durable operation key. */
+const EFFECTFUL: unique symbol = Symbol("platform.inbox.effectful")
+
+/** Marks an effectful client command for BE_MUTATION_IDEMPOTENT; transaction ownership remains in its domain service. */
+export const Effectful = (): ClassDecorator => SetMetadata(EFFECTFUL, true)

package/templates/be/patterns/idempotency/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/patterns/idempotency/platform/inbox/inbox.decorators.ts.tpl

@@ -0,0 +1,17 @@
+import type { EntityManager } from "typeorm"
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { Inbox } from "./inbox.port"
+
+/** Token of the Inbox port. */
+export const INBOX: unique symbol = Symbol("platform.inbox")
+
+/** Token of the entity managers of the connections that hold the claims table, in the order the options name them. */
+export const CLAIM_MANAGERS: unique symbol = Symbol("platform.inbox.claim-managers")
+
+/** Injects the Inbox port. Parameter type: Inbox. */
+export const InjectInbox = (): TypedParameterDecorator<Inbox> => injector<Inbox>(INBOX)
+
+/** Injects the entity managers of the connections that hold the claims table. Parameter type: a one-manager tuple (`readonly [EntityManager]`). */
+export const InjectClaimManagers = (): TypedParameterDecorator<readonly [EntityManager]> =>
+    injector<readonly [EntityManager]>(CLAIM_MANAGERS)

package/templates/be/patterns/idempotency/platform/inbox/inbox.module-definition.ts.tpl

@@ -0,0 +1,7 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { InboxOptions } from "./inbox.options"
+
+/** The configurable-module base of the inbox capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<InboxOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

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

@@ -0,0 +1,28 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { INBOX, CLAIM_MANAGERS } from "./inbox.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./inbox.module-definition"
+import { PostgresInbox } from "./inbox.service"
+
+@Module({})
+/** Provides the Inbox port over the claims table of the connection the app names. */
+export class InboxModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [
+                ...(base.providers ?? []),
+                {
+                    provide: CLAIM_MANAGERS,
+                    useFactory: (manager: EntityManager) => [manager],
+                    inject: [options.connection],
+                },
+                { provide: INBOX, useClass: PostgresInbox },
+            ],
+            exports: [INBOX],
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { InjectionToken } from "@nestjs/common"
+
+/** What the inbox of one app needs: the connection whose claims table it uses, so every service claims on its own database. */
+export interface InboxOptions {
+    /** The token of the shared entity manager of the connection that holds the claims table of the app. */
+    readonly connection: InjectionToken
+}

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

@@ -0,0 +1,44 @@
+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 original identity of a delivery receipt. */
+export interface DeliveryClaim {
+    /** The original publisher or consumer namespace, preserved exactly. */
+    readonly source: string
+    /** The original delivered event identity. */
+    readonly eventId: string
+}
+
+/** A delivery receipt transferred from a capability's legacy dedupe store by its data migration. */
+export interface DeliveryClaimBackfill extends DeliveryClaim {
+    /** The instant the original receiver claimed the event. */
+    readonly claimedAt: Date
+}
+
+/** The domain work whose JSON result commits with the client receipt. */
+export interface ClientOperationEffect<T> {
+    (): Promise<T>
+}
+
+/** Deduplicates deliveries by the source and event id of their consumer. */
+export interface Inbox {
+    /** True for the first claim; with `tx`, the claim commits or rolls back with the caller's effect. */
+    claim(source: string, eventId: string, tx?: EntityManager): Promise<boolean>
+    /** Gives a separately committed claim back after a failed attempt; a transaction-owned claim rolls back with its effect. */
+    release(source: string, eventId: string): Promise<void>
+    /** Claims, applies and records one JSON outcome inside the caller's transaction; repeats replay it without running the effect. */
+    runClient<T>(request: ClientOperation, tx: EntityManager, effect: ClientOperationEffect<T>): Promise<T>
+    /** Deletes at most one bounded batch of completed client claims before the cutoff, keeping delivery claims intact. */
+    sweepClients(cutoff: Date, tx: EntityManager): Promise<number>
+}