@starci/hfs 4.11.12 → 4.11.15

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

@@ -1,9 +1,17 @@
 import { Injectable } from "@nestjs/common"
-import type { EntityManager } from "typeorm"
+import type { EntityManager, ObjectLiteral } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
-import { BATCH_ROWS, DatabaseError, DatabaseErrorCode, callDbFunction } from "@modules/platform/database"
-import type { ClientOperation, ClientOperationEffect, Inbox, InboxEventId } from "./inbox.port"
+import { BATCH_ROWS, DatabaseError, DatabaseErrorCode, callDbFunction, returnedRows, rowShape } from "@modules/platform/database"
+import type {
+    ClientOperation,
+    ClientOperationEffect,
+    EntityInbox,
+    Inbox,
+    InboxEntityReceipt,
+    InboxEventId,
+    InboxReceiptId,
+} from "./inbox.port"
 import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
 import { InboxError, InboxErrorCode } from "./errors/inbox.error"
 import { clientSource } from "./client-operation.policy"
@@ -43,19 +51,43 @@ interface InboxSweepRow {
     readonly deleted_count: number
 }
 
+/** The row a receipt insert returns to the transaction that won it. */
+const isReceiptRow = rowShape({ id: "string" })
+
+/** The provider's delivery id, trimmed; a missing or blank one is refused before anything is claimed or written. */
+const deliveryIdOf = (eventId: InboxEventId): string => {
+    const deliveryId = eventId?.trim()
+    if (!deliveryId) throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+    return deliveryId
+}
+
 @Injectable()
 /** Claims a delivery with the receipt transaction, so a failure can be retried without losing the delivery. */
-export class PostgresInbox implements Inbox {
+export class PostgresInbox implements Inbox, EntityInbox {
     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 = await callDbFunction<InboxEventRow>(tx, "public.inbox_claim_event", [source, normalizedEventId])
-        return rows.length > 0
+        return this.claimDelivery(source, deliveryIdOf(eventId), tx)
+    }
+
+    /** The claim first; only its winner inserts the receipt row, and a row that already exists is left as it is. */
+    async claimRow<Row extends ObjectLiteral>(
+        source: string,
+        eventId: InboxEventId,
+        tx: EntityManager,
+        receipt: InboxEntityReceipt<Row>,
+    ): Promise<InboxReceiptId> {
+        const deliveryId = deliveryIdOf(eventId)
+        if (!(await this.claimDelivery(source, deliveryId, tx))) return undefined
+        const inserted = await tx
+            .createQueryBuilder(receipt.entity, "receipt")
+            .insert()
+            .values(receipt.row(deliveryId))
+            .orIgnore()
+            .returning("id")
+            .execute()
+        return returnedRows(inserted.raw, isReceiptRow)[0]?.id
     }
 
     /** Runs once in the domain transaction, returning the persisted JSON outcome on both the first call and every retry. */
@@ -99,4 +131,10 @@ export class PostgresInbox implements Inbox {
         const rows = await callDbFunction<InboxSweepRow>(tx, "public.inbox_sweep_clients", [cutoff, BATCH_ROWS])
         return rows[0]?.deleted_count ?? 0
     }
+
+    /** Claims a normalized delivery id; an answered row means this transaction holds the first claim. */
+    private async claimDelivery(source: string, deliveryId: string, tx: EntityManager): Promise<boolean> {
+        const rows = await callDbFunction<InboxEventRow>(tx, "public.inbox_claim_event", [source, deliveryId])
+        return rows.length > 0
+    }
 }

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

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

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

@@ -1,19 +1,19 @@
 import { fakeInbox, fakeTransaction, mockEntityManager, recordingEventBus } from "@starci/jest-preset"
 import { Test } from "@nestjs/testing"
-import { PRIMARY_ENTITY_MANAGER, webhookReceiptInsert } from "@modules/platform/database"
+import { DatabaseErrorCode, PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
 import { @@Provider@@DeliveryRecordedEvent } from "@modules/events/@@provider@@"
 import { EVENT_BUS } from "@modules/platform/event-bus"
 import { INBOX } from "@modules/platform/inbox"
+import { @@Provider@@InboxEntity } from "./persistence/entities/@@provider@@-inbox.entity"
 import { @@Provider@@InboxService } from "./@@provider@@-inbox.service"
 
 const DELIVERY = { id: "delivery-1" }
-const INSERT_@@providerUpper@@_INBOX = webhookReceiptInsert("@@table@@")
+const SOURCE = "webhook.@@provider@@"
 
-const build = async (fresh: boolean, recorded: ReadonlyArray<{ readonly id: string }> = [{ id: "inbox-1" }]) => {
-    const entityManager = mockEntityManager({ query: [INSERT_@@providerUpper@@_INBOX, recorded] })
+const build = async () => {
+    const entityManager = mockEntityManager()
     const transaction = fakeTransaction(entityManager)
     const claims = fakeInbox()
-    if (!fresh) claims.seen("webhook.@@provider@@", "delivery-1")
     const events = recordingEventBus<@@Provider@@DeliveryRecordedEvent>()
     const moduleRef = await Test.createTestingModule({
         providers: [
@@ -28,41 +28,65 @@ const build = async (fresh: boolean, recorded: ReadonlyArray<{ readonly id: stri
 
 describe("@@Provider@@InboxService", () => {
     describe("record@@Provider@@Delivery", () => {
-        it("claims, records and publishes a typed event in the same transaction", async () => {
-            const { inbox, claims, events, entityManager, transaction } = await build(true)
+        it("claims, records the receipt row and publishes a typed event in the same transaction", async () => {
+            const { inbox, claims, events, entityManager, transaction } = await build()
 
             await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })
 
-            expect(entityManager.query).toHaveBeenCalledTimes(1)
-            expect(entityManager.query).toHaveBeenCalledWith(INSERT_@@providerUpper@@_INBOX, ["@@provider@@", "delivery-1", JSON.stringify(DELIVERY)])
-            expect(claims.claims).toEqual([{ source: "webhook.@@provider@@", eventId: "delivery-1" }])
-            expect(events.events).toEqual([@@Provider@@DeliveryRecordedEvent.create({ receiptId: "inbox-1" })])
+            expect(claims.claims).toEqual([{ source: SOURCE, eventId: "delivery-1" }])
+            expect(claims.receipts).toEqual([
+                {
+                    id: "receipt-1",
+                    source: SOURCE,
+                    eventId: "delivery-1",
+                    entity: @@Provider@@InboxEntity,
+                    row: { provider: "@@provider@@", deliveryId: "delivery-1", payload: DELIVERY },
+                    tx: events.entries[0]?.tx,
+                    inTransaction: true,
+                },
+            ])
+            expect(events.events).toEqual([@@Provider@@DeliveryRecordedEvent.create({ receiptId: "receipt-1" })])
             expect(events.allInTransaction).toBe(true)
             expect(events.entries[0]?.tx).not.toBe(entityManager)
             expect(transaction.commits).toBe(1)
         })
 
         it("acknowledges a duplicate @@provider@@ delivery without further work", async () => {
-            const { inbox, events, entityManager, transaction } = await build(false)
+            const { inbox, claims, events, transaction } = await build()
+            claims.seen(SOURCE, "delivery-1")
 
             await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })
 
-            expect(entityManager.query).not.toHaveBeenCalled()
+            expect(claims.receipts).toEqual([])
             expect(events.events).toEqual([])
             expect(transaction.commits).toBe(1)
         })
 
         it("does not publish for an already recorded receipt", async () => {
-            const { inbox, events, transaction } = await build(true, [])
+            const { inbox, claims, events, transaction } = await build()
+            claims.receiptExists(SOURCE, "delivery-1")
 
             await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })
 
+            expect(claims.receipts).toEqual([])
             expect(events.events).toEqual([])
             expect(transaction.commits).toBe(1)
         })
 
+        it("refuses a delivery without an id before recording anything", async () => {
+            const { inbox, claims, events, transaction } = await build()
+
+            await expect(inbox.record@@Provider@@Delivery({ eventId: undefined, delivery: DELIVERY, correlationId: "request-1" })).rejects.toMatchObject({
+                code: DatabaseErrorCode.WebhookDeliveryIdRequired,
+            })
+
+            expect(claims.receipts).toEqual([])
+            expect(events.events).toEqual([])
+            expect(transaction.rollbacks).toBe(1)
+        })
+
         it("rolls back the receipt when publishing fails", async () => {
-            const { inbox, events, transaction } = await build(true)
+            const { inbox, events, transaction } = await build()
             const failure = new Error("event bus unavailable")
             events.failNext("publish", failure)
 

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

@@ -1,11 +1,12 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
-import { InjectPrimaryEntityManager, recordWebhookDelivery } from "@modules/platform/database"
+import { InjectPrimaryEntityManager } from "@modules/platform/database"
 import { @@Provider@@DeliveryRecordedEvent } from "@modules/events/@@provider@@"
 import { InjectEventBus } from "@modules/platform/event-bus"
 import type { EventBus } from "@modules/platform/event-bus"
-import { InjectInbox } from "@modules/platform/inbox"
-import type { Inbox } from "@modules/platform/inbox"
+import { InjectEntityInbox } from "@modules/platform/inbox"
+import type { EntityInbox, InboxEntityReceipt } from "@modules/platform/inbox"
+import { @@Provider@@InboxEntity } from "./persistence/entities/@@provider@@-inbox.entity"
 
 interface @@Provider@@Delivery {
     readonly id: string
@@ -23,21 +24,20 @@ interface @@Provider@@DeliveryRequest {
 export class @@Provider@@InboxService {
     constructor(
         @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
-        @InjectInbox() private readonly inbox: Inbox,
+        @InjectEntityInbox() private readonly inbox: EntityInbox,
         @InjectEventBus() private readonly eventBus: EventBus,
     ) {}
 
-    /** A duplicate is acknowledged without creating another pending row; this intake never dispatches a command. */
+    /**
+     * The claim and the pending receipt row commit together: the winning claim inserts the row keyed by the delivery id the
+     * claim normalized; a duplicate is acknowledged without another pending row, and this intake never dispatches a command.
+     */
     record@@Provider@@Delivery(request: @@Provider@@DeliveryRequest): Promise<void> {
         return this.entityManager.transaction(async (manager) => {
-            if (!(await this.inbox.claim("webhook.@@provider@@", request.eventId, manager))) return
-            const receiptId = await recordWebhookDelivery({
-                manager,
-                table: "@@table@@",
-                provider: "@@provider@@",
-                deliveryId: request.eventId,
-                payload: request.delivery,
-            })
+            const receiptId = await this.inbox.claimRow("webhook.@@provider@@", request.eventId, manager, {
+                entity: @@Provider@@InboxEntity,
+                row: (deliveryId) => ({ provider: "@@provider@@", deliveryId, payload: request.delivery }),
+            } satisfies InboxEntityReceipt<@@Provider@@InboxEntity>)
             if (receiptId === undefined) return
             await this.eventBus.publish(@@Provider@@DeliveryRecordedEvent.create({ receiptId }), manager, request.correlationId)
         })

package/templates/be/inbox/webhook-door.spec.ts.tpl

@@ -5,7 +5,7 @@ import { Test } from "@nestjs/testing"
 import type { Request } from "express"
 import { @@Provider@@InboxService } from "@modules/domain/@@provider@@-inbox"
 import { Secret } from "@modules/platform/config"
-import { HttpSecurityModule, WebhookSignatureService } from "@modules/platform/http-security"
+import { HttpSecurityModule, ReadinessService, WebhookSignatureService } from "@modules/platform/http-security"
 import type { HttpSecurityOptions } from "@modules/platform/http-security"
 import type { CorrelationRequest } from "@modules/platform/logging"
 import { @@Event@@Request } from "./dto/@@event@@.request"
@@ -46,6 +46,9 @@ const build = async (deliveries: @@Provider@@InboxService) => {
     })
         .overrideProvider(WebhookSignatureService)
         .useValue(new WebhookSignatureService(OPTIONS, new FakeClock(AT)))
+        // The module also provides the readiness probe, which needs the database and retry timer this door never reaches.
+        .overrideProvider(ReadinessService)
+        .useValue(mock<ReadinessService>())
         .compile()
     return moduleRef.get(@@Provider@@Webhook)
 }

package/templates/be/skeleton/src/modules/domain/note/note.service.ts

@@ -2,12 +2,11 @@ import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
-import { InjectPrimaryEntityManager, LIST_ROWS_MAX } from "@modules/platform/database"
+import { InjectPrimaryEntityManager, LIST_ROWS_MAX, returnedRows } from "@modules/platform/database"
 import type { CreateNoteParams, Note } from "./note.contracts"
 import { NoteError, NoteErrorCode } from "./errors/note.error"
 import { NoteEntity } from "./persistence/entities/note.entity"
-import { toNote } from "./persistence/note.rows"
-import type { NoteRow } from "./persistence/note.rows"
+import { isNoteRow, toNote } from "./persistence/note.rows"
 import { INSERT_NOTE } from "./persistence/note.sql"
 
 @Injectable()
@@ -29,7 +28,7 @@ export class NoteService {
 
     /** Writes one note in the caller transaction, stamped by the clock, and answers it as stored. */
     async create(params: CreateNoteParams): Promise<Note> {
-        const rows: Array<NoteRow> = await params.manager.query(INSERT_NOTE, [params.body, this.clock.now()])
+        const rows = returnedRows(await params.manager.query(INSERT_NOTE, [params.body, this.clock.now()]), isNoteRow)
         const note = toNote(rows)
         if (note === null) throw new NoteError({ code: NoteErrorCode.NoteMissing })
         return note

package/templates/be/skeleton/src/modules/domain/note/persistence/note.rows.ts

@@ -1,3 +1,4 @@
+import { rowShape } from "@modules/platform/database"
 import type { Note } from "../note.contracts"
 
 /** The row INSERT_NOTE answers. */
@@ -10,6 +11,9 @@ export interface NoteRow {
     created_at: Date
 }
 
+/** Proves one row INSERT_NOTE answered is a NoteRow. */
+export const isNoteRow: (value: unknown) => value is NoteRow = rowShape({ id: "string", body: "string", created_at: "date" })
+
 /** The note of the row an insert answers, or null when it answered none. */
 export const toNote = (rows: ReadonlyArray<NoteRow>): Note | null => {
     const row = rows[0]

package/templates/be/skeleton/src/modules/platform/database/errors/database.error.ts

@@ -5,11 +5,14 @@ import type { ErrorKind } from "@modules/platform/errors"
 export enum DatabaseErrorCode {
     /** A dynamic SQL identifier was not on the list of names its caller allows. */
     IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",
+    /** A RETURNING statement answered something other than rows of the shape its caller expects. */
+    ReturningRowRejected = "DATABASE_RETURNING_ROW_REJECTED",
 }
 
 /** How each database code travels. */
 export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {
     [DatabaseErrorCode.IdentifierRejected]: "internal",
+    [DatabaseErrorCode.ReturningRowRejected]: "internal",
 }
 
 /** The one error class of the database capability. */

package/templates/be/skeleton/src/modules/platform/database/index.ts

@@ -7,5 +7,6 @@ export { SeedRunnerService } from "./seed-runner.service"
 export type { DatabaseConnectionConfig, DatabaseConnectionOptions } from "./database.options"
 export { LIST_ROWS_MAX, sql } from "./database.sql"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
+export { returnedRows, rowShape } from "./returned-rows.policy"
 export { parsePrimaryDatabaseConfig } from "./primary.config"
 export { InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"

package/templates/be/skeleton/src/modules/platform/database/returned-rows.policy.spec.ts

@@ -0,0 +1,84 @@
+import { Test } from "@nestjs/testing"
+import { DatabaseErrorCode } from "./errors/database.error"
+import { returnedRows, rowShape } from "./returned-rows.policy"
+
+const RETURNED_ROWS_POLICY: unique symbol = Symbol("database.returned-rows")
+
+/** The policy under test, resolved through a testing module as the unit spec standard asks. */
+interface ReturnedRowsPolicy {
+    readonly returnedRows: typeof returnedRows
+    readonly rowShape: typeof rowShape
+}
+
+const AT = new Date("2026-02-03T04:05:06.000Z")
+
+describe("returned rows", () => {
+    let subject: ReturnedRowsPolicy
+
+    beforeEach(async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [{ provide: RETURNED_ROWS_POLICY, useFactory: (): ReturnedRowsPolicy => ({ returnedRows, rowShape }) }],
+        }).compile()
+        subject = moduleRef.get<ReturnedRowsPolicy>(RETURNED_ROWS_POLICY)
+    })
+
+    describe("rowShape", () => {
+        it("admits a row holding every named column with a value of its kind", () => {
+            const isRow = subject.rowShape({ id: "string", hits: "number", open: "boolean", created_at: "date", payload: "json" })
+
+            expect(isRow({ id: "row-1", hits: 2, open: true, created_at: AT, payload: { a: 1 }, extra: "kept" })).toBe(true)
+        })
+
+        it("admits null only for a kind that ends in ?", () => {
+            const isRow = subject.rowShape({ note: "string?", hits: "number?", open: "boolean?", seen_at: "date?" })
+
+            expect(isRow({ note: null, hits: null, open: null, seen_at: null })).toBe(true)
+            expect(isRow({ note: "n", hits: 1, open: false, seen_at: AT })).toBe(true)
+            expect(subject.rowShape({ note: "string" })({ note: null })).toBe(false)
+            expect(subject.rowShape({ payload: "json" })({ payload: null })).toBe(true)
+        })
+
+        it.each([
+            ["a column the statement did not return", { hits: 1 }],
+            ["a value of another kind", { id: 7, hits: 1 }],
+            ["a number returned as text", { id: "row-1", hits: "1" }],
+            ["a value that is not a row", "row-1"],
+            ["null", null],
+        ])("refuses %s", (_case, value) => {
+            expect(subject.rowShape({ id: "string", hits: "number" })(value)).toBe(false)
+        })
+
+        it("refuses a json column the statement did not return", () => {
+            expect(subject.rowShape({ payload: "json" })({})).toBe(false)
+        })
+    })
+
+    describe("returnedRows", () => {
+        it("answers every row, typed by its guard, in the order the statement returned them", () => {
+            const rows = subject.returnedRows([{ id: "a" }, { id: "b" }], subject.rowShape({ id: "string" }))
+
+            expect(rows.map((row) => row.id)).toEqual(["a", "b"])
+        })
+
+        it("answers no rows for a statement that returned none", () => {
+            expect(subject.returnedRows([], subject.rowShape({ id: "string" }))).toEqual([])
+        })
+
+        it("refuses a row of another shape instead of reading it", () => {
+            expect(() => subject.returnedRows([{ id: "a" }, { id: 2 }], subject.rowShape({ id: "string" }))).toThrow(
+                expect.objectContaining({ code: DatabaseErrorCode.ReturningRowRejected }),
+            )
+        })
+
+        it("refuses a result that is not a list of rows, such as the [rows, count] of a bare UPDATE", () => {
+            const isRow = subject.rowShape({ id: "string" })
+
+            expect(() => subject.returnedRows({ id: "a" }, isRow)).toThrow(
+                expect.objectContaining({ code: DatabaseErrorCode.ReturningRowRejected }),
+            )
+            expect(() => subject.returnedRows([[{ id: "a" }], 1], isRow)).toThrow(
+                expect.objectContaining({ code: DatabaseErrorCode.ReturningRowRejected }),
+            )
+        })
+    })
+})

package/templates/be/skeleton/src/modules/platform/database/returned-rows.policy.ts

@@ -0,0 +1,61 @@
+import { isRecord } from "@modules/platform/primitives"
+import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
+
+/** What node-postgres hands back for one returned column; a kind ending in `?` also admits SQL null. */
+interface ColumnTypes {
+    readonly string: string
+    readonly number: number
+    readonly boolean: boolean
+    readonly date: Date
+    readonly json: unknown
+    readonly "string?": string | null
+    readonly "number?": number | null
+    readonly "boolean?": boolean | null
+    readonly "date?": Date | null
+}
+
+/** The kind one returned column is checked against. */
+type ColumnKind = keyof ColumnTypes
+
+/** The returned columns of one statement, each named as the database returns it (snake_case) with its kind. */
+type ColumnShape = Readonly<Record<string, ColumnKind>>
+
+/** The row a shape describes: every named column, typed by its kind. */
+type RowOf<Shape extends ColumnShape> = { readonly [Column in keyof Shape]: ColumnTypes[Shape[Column]] }
+
+/** A guard that proves one returned row has the shape its returned columns give it. */
+type RowGuard<Row> = (value: unknown) => value is Row
+
+/** Whether `value` is of the non-null part of a kind. */
+const KIND_CHECKS: Readonly<Record<ColumnKind, (value: unknown) => boolean>> = {
+    string: (value) => typeof value === "string",
+    number: (value) => typeof value === "number",
+    boolean: (value) => typeof value === "boolean",
+    date: (value) => value instanceof Date,
+    json: (value) => value !== undefined,
+    "string?": (value) => value === null || typeof value === "string",
+    "number?": (value) => value === null || typeof value === "number",
+    "boolean?": (value) => value === null || typeof value === "boolean",
+    "date?": (value) => value === null || value instanceof Date,
+}
+
+/**
+ * The guard of the rows a RETURNING clause answers for `shape`: an object holding every named column with a value of its kind.
+ * A column the statement does not return is refused, so the shape and the RETURNING list cannot drift apart unseen.
+ */
+export const rowShape =
+    <Shape extends ColumnShape>(shape: Shape): RowGuard<RowOf<Shape>> =>
+    (value: unknown): value is RowOf<Shape> =>
+        isRecord(value) && Object.entries(shape).every(([column, kind]) => KIND_CHECKS[kind](value[column]))
+
+/**
+ * The rows a RETURNING statement answered, each proven by `isRow`: the result of `manager.query` for an INSERT or a CTE-wrapped
+ * UPDATE or DELETE, or the `raw` of a query builder's `execute()`. A result that is not a list of rows, or a row the guard
+ * refuses, throws `DATABASE_RETURNING_ROW_REJECTED`: the statement and the shape its caller expects disagree.
+ */
+export const returnedRows = <Row>(raw: unknown, isRow: RowGuard<Row>): Array<Row> => {
+    if (!Array.isArray(raw)) throw new DatabaseError({ code: DatabaseErrorCode.ReturningRowRejected })
+    const rows: ReadonlyArray<unknown> = raw
+    if (!rows.every(isRow)) throw new DatabaseError({ code: DatabaseErrorCode.ReturningRowRejected })
+    return [...rows]
+}

package/templates/be/skeleton/src/modules/platform/http-security/persistence/rate-limit.rows.ts

@@ -1,5 +1,10 @@
+import { rowShape } from "@modules/platform/database"
+
 /** The row HIT_RATE_WINDOW answers. */
 export interface RateWindowRow {
     /** The hits of the caller's current window, this one included. */
     readonly hits: number
 }
+
+/** Proves one row HIT_RATE_WINDOW answered is a RateWindowRow. */
+export const isRateWindowRow: (value: unknown) => value is RateWindowRow = rowShape({ hits: "number" })

package/templates/be/skeleton/src/modules/platform/http-security/rate-limit.guard.ts

@@ -7,12 +7,12 @@ import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
 import { InjectReflector } from "@modules/platform/composition"
 import type { DoorDecorator } from "@modules/platform/composition"
-import { InjectPrimaryEntityManager } from "@modules/platform/database"
+import { InjectPrimaryEntityManager, returnedRows } from "@modules/platform/database"
 import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
 import { requestOf } from "./execution-request.mapper"
 import { InjectHttpSecurityOptions } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
-import type { RateWindowRow } from "./persistence/rate-limit.rows"
+import { isRateWindowRow } from "./persistence/rate-limit.rows"
 import { HIT_RATE_WINDOW, PRUNE_RATE_WINDOWS } from "./persistence/rate-limit.sql"
 
 /** The rate limit tiers of a door. */
@@ -79,7 +79,7 @@ export class RateLimitGuard implements CanActivate {
         const now = this.clock.now()
         const key = `${tier}:${requestOf(context).ip ?? "unknown"}`.slice(0, KEY_MAX)
         const resetAt = new Date(now.getTime() + this.options.rateLimit.windowMs)
-        const rows: Array<RateWindowRow> = await this.entityManager.query(HIT_RATE_WINDOW, [key, now, resetAt])
+        const rows = returnedRows(await this.entityManager.query(HIT_RATE_WINDOW, [key, now, resetAt]), isRateWindowRow)
         const hits = rows[0]?.hits ?? Number.POSITIVE_INFINITY
         if (hits === 1) await this.entityManager.query(PRUNE_RATE_WINDOWS, [now])
         if (hits <= limit) return true

package/templates/be/skeleton-lite/src/modules/platform/database/errors/database.error.ts

@@ -7,12 +7,15 @@ export enum DatabaseErrorCode {
     ConnectionUndeclared = "DATABASE_CONNECTION_UNDECLARED",
     /** A dynamic SQL identifier was not on the names its caller allows. */
     IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",
+    /** A RETURNING statement answered something other than rows of the shape its caller expects. */
+    ReturningRowRejected = "DATABASE_RETURNING_ROW_REJECTED",
 }
 
 /** How each database code travels. */
 export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {
     [DatabaseErrorCode.ConnectionUndeclared]: "internal",
     [DatabaseErrorCode.IdentifierRejected]: "internal",
+    [DatabaseErrorCode.ReturningRowRejected]: "internal",
 }
 
 /** The one error class of the database capability. */

package/templates/be/skeleton-lite/src/modules/platform/database/index.ts

@@ -4,4 +4,5 @@ export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"
 export { PRIMARY_DATA_SOURCE } from "./database.port"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
+export { returnedRows, rowShape } from "./returned-rows.policy"
 export { parsePrimaryDatabaseConfig } from "./primary.config"