@starci/hfs 4.2.17 → 4.4.0

package/templates/be/inbox/database-client.spec.ts.tpl

@@ -1,47 +1,41 @@
-import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { mockEntityManager } from "@starci/jest-preset"
 import type { EntityManager } from "typeorm"
 import { sql } from "./database.sql"
 import { DatabaseErrorCode } from "./errors/database.error"
-import { acceptWebhookDelivery } from "./webhook-inbox.client"
+import { recordWebhookDelivery } from "./webhook-inbox.client"
 
-// The client runs whatever claim and completion statements its caller owns; opaque function calls stand in for them here.
-const INSERT = sql`SELECT id FROM claim_spec_inbox($1, $2, $3::jsonb)`
-const COMPLETE = sql`SELECT id FROM complete_spec_inbox($1)`
+// The caller owns the conflict-safe pending-row insert; an opaque function call stands in for it here.
+const INSERT = sql`SELECT id FROM record_spec_inbox($1, $2, $3::jsonb)`
 const PAYLOAD = { id: "delivery-1" }
 
-const accept = (entityManager: EntityManager, deliveryId: string | undefined, process: (manager: EntityManager) => Promise<void>) =>
-    acceptWebhookDelivery({ entityManager, insert: INSERT, complete: COMPLETE, provider: "spec", deliveryId, payload: PAYLOAD, process })
+const record = (manager: EntityManager, deliveryId: string | undefined) =>
+    recordWebhookDelivery({ manager, insert: INSERT, provider: "spec", deliveryId, payload: PAYLOAD })
 
-describe("acceptWebhookDelivery", () => {
-    it("claims a new delivery, processes it and marks it complete in one committed transaction", async () => {
-        const transaction = fakeTransaction(mockEntityManager({ query: [[INSERT, [{ id: "inbox-1" }]], [COMPLETE, [{ id: "inbox-1" }]]] }))
-        const process = jest.fn<Promise<void>, [EntityManager]>().mockResolvedValue(undefined)
+describe("recordWebhookDelivery", () => {
+    it("records a new delivery through the caller's transaction manager", async () => {
+        const manager = mockEntityManager({ query: [INSERT, [{ id: "inbox-1" }]] })
 
-        await accept(transaction.em, "  delivery-1  ", process)
+        const receiptId = await record(manager, "  delivery-1  ")
 
-        expect(process).toHaveBeenCalledTimes(1)
-        expect(transaction.em.query).toHaveBeenCalledWith(INSERT, ["spec", "delivery-1", JSON.stringify(PAYLOAD)])
-        expect(transaction.em.query).toHaveBeenCalledWith(COMPLETE, ["inbox-1"])
-        expect(transaction.commits).toBe(1)
+        expect(manager.query).toHaveBeenCalledTimes(1)
+        expect(manager.query).toHaveBeenCalledWith(INSERT, ["spec", "delivery-1", JSON.stringify(PAYLOAD)])
+        expect(receiptId).toBe("inbox-1")
     })
 
-    it("acknowledges a duplicate without processing it again", async () => {
-        const transaction = fakeTransaction(mockEntityManager({ query: [INSERT, []] }))
-        const process = jest.fn<Promise<void>, [EntityManager]>()
+    it("acknowledges a duplicate without any completion or business write", async () => {
+        const manager = mockEntityManager({ query: [INSERT, []] })
 
-        await accept(transaction.em, "delivery-1", process)
+        const receiptId = await record(manager, "delivery-1")
 
-        expect(process).not.toHaveBeenCalled()
-        expect(transaction.em.query).toHaveBeenCalledTimes(1)
+        expect(manager.query).toHaveBeenCalledTimes(1)
+        expect(receiptId).toBeUndefined()
     })
 
-    it.each([["no", undefined], ["a blank", "   "]])("refuses %s delivery id before opening a transaction", async (_label, deliveryId) => {
-        const transaction = fakeTransaction(mockEntityManager())
-        const process = jest.fn<Promise<void>, [EntityManager]>()
+    it.each([["no", undefined], ["a blank", "   "]])("refuses %s delivery id before writing a receipt", async (_label, deliveryId) => {
+        const manager = mockEntityManager()
 
-        await expect(accept(transaction.em, deliveryId, process)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+        await expect(record(manager, deliveryId)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
 
-        expect(transaction.outcomes).toEqual([])
-        expect(process).not.toHaveBeenCalled()
+        expect(manager.query).not.toHaveBeenCalled()
     })
 })

package/templates/be/inbox/database-client.ts.tpl

@@ -2,49 +2,35 @@ import type { EntityManager } from "typeorm"
 import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
 import type { SqlText } from "./database.sql"
 
-interface WebhookInboxStatements {
+interface RecordWebhookDelivery {
+    readonly manager: EntityManager
     readonly insert: SqlText
-    readonly complete: SqlText
-}
-
-interface AcceptWebhookDelivery extends WebhookInboxStatements {
-    readonly entityManager: EntityManager
     readonly provider: string
     readonly deliveryId: string | undefined
     readonly payload: object
-    readonly process: (manager: EntityManager) => Promise<void>
 }
 
-interface InboxIdentity {
-    readonly id: string
-}
+type WebhookReceiptId = string | undefined
 
 /**
- * Claims and processes one delivery in one EntityManager transaction. A conflict returns without calling `process`, so
- * a redelivery receives the original empty acknowledgement and cannot repeat the domain mutation.
+ * Records one pending delivery using the intake's transaction manager and returns its durable receipt identity.
+ * Business processing and the completion marker belong to the reactor or job that consumes the committed row.
  */
-export const acceptWebhookDelivery = async ({
-    entityManager,
+export const recordWebhookDelivery = async ({
+    manager,
     insert,
-    complete,
     provider,
     deliveryId,
     payload,
-    process,
-}: AcceptWebhookDelivery): Promise<void> => {
+}: RecordWebhookDelivery): Promise<WebhookReceiptId> => {
     const normalizedDeliveryId = deliveryId?.trim()
     if (!normalizedDeliveryId) {
         throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
     }
-    await entityManager.transaction(async (manager) => {
-        const claimed = await manager.query<Array<InboxIdentity>>(insert, [
-            provider,
-            normalizedDeliveryId,
-            JSON.stringify(payload),
-        ])
-        const identity = claimed[0]
-        if (identity === undefined) return
-        await process(manager)
-        await manager.query(complete, [identity.id])
-    })
+    const rows: Array<{ readonly id: string }> = await manager.query(insert, [
+        provider,
+        normalizedDeliveryId,
+        JSON.stringify(payload),
+    ])
+    return rows[0]?.id
 }

package/templates/be/inbox/delivery-recorded.event.ts.tpl

@@ -0,0 +1,36 @@
+import { BaseEvent } from "@modules/platform/event-bus"
+import type { ParsedEvent } from "@modules/platform/event-bus"
+
+/** A durable receipt reference; processing reads the provider payload after the intake commits. */
+export interface @@Provider@@DeliveryRecordedPayload {
+    readonly receiptId: string
+}
+
+/** Version 1 of `@@provider@@.delivery-recorded`, published once by the provider inbox intake. */
+export class @@Provider@@DeliveryRecordedEvent extends BaseEvent {
+    static readonly eventName = "@@provider@@.delivery-recorded"
+    static readonly version = 1
+
+    readonly eventName = @@Provider@@DeliveryRecordedEvent.eventName
+
+    private constructor(
+        readonly eventId: string,
+        readonly payload: @@Provider@@DeliveryRecordedPayload,
+    ) {
+        super()
+    }
+
+    /** The receipt identity is stable across relay retries and distinct from a consumer's inbox source. */
+    static create(payload: @@Provider@@DeliveryRecordedPayload): @@Provider@@DeliveryRecordedEvent {
+        return new @@Provider@@DeliveryRecordedEvent(payload.receiptId, payload)
+    }
+
+    /** Reads an outbox envelope; malformed deliveries never reach a processing consumer. */
+    static parse(envelope: unknown): ParsedEvent<@@Provider@@DeliveryRecordedEvent> {
+        if (typeof envelope !== "object" || envelope === null || !("eventId" in envelope) || !("payload" in envelope)) return null
+        const { eventId, payload } = envelope
+        if (typeof eventId !== "string" || !eventId.trim() || typeof payload !== "object" || payload === null || !("receiptId" in payload)) return null
+        if (typeof payload.receiptId !== "string" || !payload.receiptId.trim()) return null
+        return new @@Provider@@DeliveryRecordedEvent(eventId, { receiptId: payload.receiptId })
+    }
+}

package/templates/be/inbox/event-index.ts.tpl

@@ -0,0 +1 @@
+export { @@Provider@@DeliveryRecordedEvent } from "./@@provider@@-delivery-recorded.event"

package/templates/be/inbox/events.json.tpl

@@ -0,0 +1,10 @@
+{
+  "events": {
+    "@@provider@@.delivery-recorded": {
+      "payload": { "receiptId": "string" },
+      "version": 1
+    }
+  },
+  "schema": "starci/event-contract@1",
+  "service": "@@provider@@"
+}

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

@@ -9,6 +9,7 @@ create table public.@@table@@ (
 );
 
 alter table public.@@table@@ enable row level security;
+alter table public.@@table@@ force row level security;
 
 -- The dedicated app_be PostgreSQL role is the only application path. With no anon or authenticated policy,
 -- RLS denies those PostgREST roles by default; the service-role JWT is deliberately not granted here.

package/templates/be/inbox/platform/event-bus/event-bus.contracts.ts.tpl

@@ -0,0 +1,42 @@
+/** The base of each typed event in modules/events: its stable identity, name and payload. */
+export abstract class BaseEvent {
+    /** A receiver uses this stable identity to deduplicate redelivery. */
+    abstract readonly eventId: string
+    /** The event name listed by the service's vendored event contract. */
+    abstract readonly eventName: string
+    /** The fact that a reactor or job processes after commit. */
+    abstract readonly payload: object
+}
+
+/** Parsing either returns the event or refuses a mismatched envelope. */
+export type ParsedEvent<Event extends BaseEvent> = Event | null
+
+/** The class side of a typed event, shared by publishers and later consumers. */
+export interface EventClass<Event extends BaseEvent> {
+    /** The contract's event name. */
+    readonly eventName: string
+    /** The contract's payload version. */
+    readonly version: number
+    /** Reads the event from its durable envelope. */
+    parse(envelope: unknown): ParsedEvent<Event>
+}
+
+/** One committed delivery received by a reactor. */
+export interface EventDelivery<Event extends BaseEvent> {
+    /** The consumer's idempotency key. */
+    readonly eventId: string
+    /** The typed event. */
+    readonly event: Event
+    /** The number of attempts, including this one. */
+    readonly attempt: number
+}
+
+/** The typed event's durable envelope, read only after the intake transaction commits. */
+export interface EventEnvelope {
+    /** The stable event id. */
+    readonly eventId: string
+    /** The contract's event name. */
+    readonly eventName: string
+    /** The data of the fact. */
+    readonly payload: object
+}

package/templates/be/inbox/platform/event-bus/event-bus.decorators.ts.tpl

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { EventBus } from "./event-bus.port"
+
+/** Token of the transactional EventBus publisher. */
+export const EVENT_BUS: unique symbol = Symbol("platform.event-bus")
+
+/** Injects the EventBus port. Parameter type: EventBus. */
+export const InjectEventBus = (): TypedParameterDecorator<EventBus> => injector<EventBus>(EVENT_BUS)

package/templates/be/inbox/platform/event-bus/event-bus.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { EventBusOptions } from "./event-bus.options"
+
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<EventBusOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/inbox/platform/event-bus/event-bus.module.ts.tpl

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { EVENT_BUS } from "./event-bus.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./event-bus.module-definition"
+import { EventBusService } from "./event-bus.service"
+
+@Module({})
+/** Provides the transactional lite EventBus publisher, shared by domain intake services. */
+export class EventBusModule extends ConfigurableModuleClass {
+    /** Registers the publishing capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), { provide: EVENT_BUS, useClass: EventBusService }],
+            exports: [EVENT_BUS],
+        }
+    }
+}

package/templates/be/inbox/platform/event-bus/event-bus.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The lite publisher uses the caller's transaction and has no runtime options. */
+export interface EventBusOptions {}

package/templates/be/inbox/platform/event-bus/event-bus.port.ts.tpl

@@ -0,0 +1,16 @@
+import type { EntityManager } from "typeorm"
+import type { BaseEvent, EventClass, EventDelivery } from "./event-bus.contracts"
+
+/** The publishing side of the lite event bus; the reactor or job owns delivery of committed outbox rows. */
+export interface EventBus {
+    /** Writes the typed event in the caller's transaction; a rollback writes no durable event. */
+    publish(event: BaseEvent, tx: EntityManager): Promise<void>
+}
+
+/** A later message transport receives one typed event and forwards its delivery id. */
+export interface EventConsumer<Event extends BaseEvent> {
+    /** The event class the consumer reads. */
+    readonly event: EventClass<Event>
+    /** Applies one delivery after commit; a throw leaves the delivery available for retry. */
+    handle(delivery: EventDelivery<Event>): Promise<void>
+}

package/templates/be/inbox/platform/event-bus/event-bus.service.spec.ts.tpl

@@ -0,0 +1,45 @@
+import { Test } from "@nestjs/testing"
+import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { BaseEvent } from "./event-bus.contracts"
+import { EventBusService } from "./event-bus.service"
+import { INSERT_OUTBOX_EVENT } from "./persistence/event-bus.sql"
+
+class ReceiptRecordedEvent extends BaseEvent {
+    readonly eventId = "receipt-1"
+    readonly eventName = "spec.delivery-recorded"
+    readonly payload = { receiptId: "receipt-1" }
+}
+
+describe("EventBusService", () => {
+    const build = async () => {
+        const module = await Test.createTestingModule({ providers: [EventBusService] }).compile()
+        return module.get(EventBusService)
+    }
+
+    it("writes the typed envelope through the receipt transaction", async () => {
+        const subject = await build()
+        const transaction = fakeTransaction(mockEntityManager({ query: [INSERT_OUTBOX_EVENT, []] }))
+        const event = new ReceiptRecordedEvent()
+
+        await transaction.em.transaction((manager) => subject.publish(event, manager))
+
+        expect(transaction.em.query).toHaveBeenCalledWith(INSERT_OUTBOX_EVENT, [
+            "receipt-1",
+            "spec.delivery-recorded",
+            JSON.stringify({ eventId: event.eventId, eventName: event.eventName, payload: event.payload }),
+        ])
+        expect(transaction.commits).toBe(1)
+    })
+
+    it("propagates an outbox failure so the receipt transaction rolls back", async () => {
+        const subject = await build()
+        const manager = mockEntityManager({ query: [INSERT_OUTBOX_EVENT, []] })
+        jest.spyOn(manager, "query").mockRejectedValue(new Error("outbox unavailable"))
+        const transaction = fakeTransaction(manager)
+
+        await expect(transaction.em.transaction((tx) => subject.publish(new ReceiptRecordedEvent(), tx))).rejects.toThrow("outbox unavailable")
+
+        expect(transaction.commits).toBe(0)
+        expect(transaction.rollbacks).toBe(1)
+    })
+})

package/templates/be/inbox/platform/event-bus/event-bus.service.ts.tpl

@@ -0,0 +1,15 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import type { BaseEvent, EventEnvelope } from "./event-bus.contracts"
+import type { EventBus } from "./event-bus.port"
+import { INSERT_OUTBOX_EVENT } from "./persistence/event-bus.sql"
+
+@Injectable()
+/** Writes a receipt event into the same transaction as its inbox receipt, without running any consumer. */
+export class EventBusService implements EventBus {
+    /** The outbox commits or rolls back with the receipt; only a later reactor or job processes it. */
+    async publish(event: BaseEvent, tx: EntityManager): Promise<void> {
+        const envelope: EventEnvelope = { eventId: event.eventId, eventName: event.eventName, payload: event.payload }
+        await tx.query(INSERT_OUTBOX_EVENT, [event.eventId, event.eventName, JSON.stringify(envelope)])
+    }
+}

package/templates/be/inbox/platform/event-bus/index.ts.tpl

@@ -0,0 +1,5 @@
+export { BaseEvent } from "./event-bus.contracts"
+export type { EventClass, EventDelivery, EventEnvelope, ParsedEvent } from "./event-bus.contracts"
+export { EVENT_BUS, InjectEventBus } from "./event-bus.decorators"
+export { EventBusModule } from "./event-bus.module"
+export type { EventBus, EventConsumer } from "./event-bus.port"

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

@@ -0,0 +1,5 @@
+import { sql } from "@modules/platform/database"
+
+/** Writes only the typed envelope; a reactor or job reads the committed row afterward. */
+export const INSERT_OUTBOX_EVENT = sql`INSERT INTO public.event_bus (event_id, event_name, payload)
+VALUES ($1, $2, $3::jsonb)`

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

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { Inbox } from "./inbox.port"
+
+/** Token of the shared, transaction-owned inbox claims. */
+export const INBOX: unique symbol = Symbol("platform.inbox")
+
+/** Injects the Inbox port. Parameter type: Inbox. */
+export const InjectInbox = (): TypedParameterDecorator<Inbox> => injector<Inbox>(INBOX)

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

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { InboxOptions } from "./inbox.options"
+
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<InboxOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

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

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { INBOX } from "./inbox.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./inbox.module-definition"
+import { PostgresInbox } from "./inbox.service"
+
+@Module({})
+/** Provides the lite Inbox port; all claims use the domain service's own transaction. */
+export class InboxModule extends ConfigurableModuleClass {
+    /** Registers the shared inbox once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), { provide: INBOX, useClass: PostgresInbox }],
+            exports: [INBOX],
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+/** The lite inbox uses the caller's transaction and has no runtime options. */
+export interface InboxOptions {}

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

@@ -0,0 +1,10 @@
+import type { EntityManager } from "typeorm"
+
+/** The signed provider header may omit its delivery identity; the adapter refuses that delivery. */
+export type InboxEventId = string | undefined
+
+/** Deduplicates a delivery inside the transaction that records its receipt or applies its effect. */
+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>
+}

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

@@ -0,0 +1,41 @@
+import { Test } from "@nestjs/testing"
+import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { DatabaseErrorCode } from "@modules/platform/database"
+import { PostgresInbox } from "./inbox.service"
+import { CLAIM_EVENT } from "./persistence/inbox.sql"
+
+describe("PostgresInbox", () => {
+    const build = async () => {
+        const module = await Test.createTestingModule({ providers: [PostgresInbox] }).compile()
+        return module.get(PostgresInbox)
+    }
+
+    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))
+
+        expect(fresh).toBe(true)
+        expect(transaction.em.query).toHaveBeenCalledWith(CLAIM_EVENT, ["webhook:spec", "delivery-1"])
+        expect(transaction.commits).toBe(1)
+    })
+
+    it("returns false when the source and event id have already been claimed", async () => {
+        const subject = await build()
+        const manager = mockEntityManager({ query: [CLAIM_EVENT, []] })
+
+        await expect(subject.claim("webhook:spec", "delivery-1", manager)).resolves.toBe(false)
+
+        expect(manager.query).toHaveBeenCalledTimes(1)
+    })
+
+    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 })
+
+        expect(manager.query).not.toHaveBeenCalled()
+    })
+})

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

@@ -0,0 +1,19 @@
+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"
+
+@Injectable()
+/** Claims a delivery with the receipt transaction, so a failure can be retried without losing the delivery. */
+export class PostgresInbox implements Inbox {
+    /** 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])
+        return rows.length > 0
+    }
+}

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

@@ -0,0 +1,3 @@
+export { INBOX, InjectInbox } from "./inbox.decorators"
+export { InboxModule } from "./inbox.module"
+export type { Inbox, InboxEventId } from "./inbox.port"

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

@@ -0,0 +1,7 @@
+import { sql } from "@modules/platform/database"
+
+/** The unique source and delivery id let only one transaction record or process each delivery. */
+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`

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

@@ -0,0 +1,48 @@
+-- Both the claim and receipt event use the intake transaction; after-commit processing reads the outbox separately.
+create table public.inbox (
+    source text not null check (source <> ''),
+    event_id text not null check (event_id <> ''),
+    claimed_at timestamptz not null default now(),
+    primary key (source, event_id)
+);
+
+alter table public.inbox enable row level security;
+alter table public.inbox force row level security;
+
+create policy "inbox_app_be_select"
+on public.inbox for select to app_be
+using (source <> '');
+
+create policy "inbox_app_be_insert"
+on public.inbox for insert to app_be
+with check (source <> '');
+
+revoke all on table public.inbox from public, anon, authenticated;
+grant select, insert on table public.inbox to app_be;
+
+create table public.event_bus (
+    event_id text primary key check (event_id <> ''),
+    event_name text not null check (event_name <> ''),
+    payload jsonb not null,
+    recorded_at timestamptz not null default now(),
+    delivered_at timestamptz
+);
+
+alter table public.event_bus enable row level security;
+alter table public.event_bus force row level security;
+
+create policy "event_bus_app_be_select"
+on public.event_bus for select to app_be
+using (event_name <> '');
+
+create policy "event_bus_app_be_insert"
+on public.event_bus for insert to app_be
+with check (event_name <> '');
+
+create policy "event_bus_app_be_update"
+on public.event_bus for update to app_be
+using (event_name <> '')
+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;