@starci/hfs 4.9.11 → 4.10.0

package/templates/app/skeleton-lite/README.md

@@ -1,20 +1,20 @@
 # {{project}}
 
-One StarCi lite app: a Nest API in `be/`, one Next web app in `fe/`, and Supabase as the schema authority.
+One StarCi lite app: a Nest API in `be/`, one Next web app in `fe/`, and its own PostgreSQL with SQL migrations in `db/` as the schema authority.
 
 ## Overview
 
-The starter keeps one deployable API and one web app, with the same code structure as a full app: the web app calls the API over GraphQL (`fe/apps/web/src/modules/api`, SWR hooks under `fe/apps/web/src/hooks/swr`) and uses Supabase only for Auth in the browser (`fe/apps/web/src/modules/auth`); every data read and write goes through the API, which verifies the access token.
+The starter keeps one deployable API and one web app, with the same code structure as a full app: the web app calls the API over GraphQL (`fe/apps/web/src/modules/api`, SWR hooks under `fe/apps/web/src/hooks/swr`) and signs in only through the API's own auth doors (`fe/apps/web/src/modules/auth`, which holds the access token in memory while the refresh token stays in an httpOnly cookie); every data read and write goes through the API, which verifies the access token against its own keys.
 
 ## Stack
 
-TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, Supabase for Auth and PostgreSQL, npm workspaces, and Turbo for front-end tasks.
+TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, PostgreSQL (the `db` service, image supabase/postgres), Passport for Google and password sign-in, S3-compatible storage (MinIO), npm workspaces, and Turbo for front-end tasks.
 
 ## Repository layout
 
-- `supabase/`: local configuration, forward-only SQL migrations, seed data, and generated database types.
-- `be/`: the API, shared platform capabilities, verified identity admission, and privileged Supabase integrations.
-- `fe/`: the web app; the only Supabase client is the Auth client of `fe/apps/web/src/modules/auth`, data goes through `fe/apps/web/src/modules/api`.
+- `db/`: forward-only SQL migrations, seed data, and generated database types.
+- `be/`: the API, shared platform capabilities, verified identity admission, and the passport and storage integrations.
+- `fe/`: the web app; it holds no credential, signs in through `fe/apps/web/src/modules/auth` and reaches data through `fe/apps/web/src/modules/api`.
 - `.starcistacks/`: value-free environment metadata and encrypted-secret custody.
 - `.starciwork/`: `.gitignore`, `.starciwork/workspace.yaml` project metadata and repo roles, and optional brand drawing records, references, and assets.
 
@@ -24,7 +24,7 @@ Declare `ci.github.repository` and `ci.github.defaultBranch` in `.starcistacks/a
 
 ## Development
 
-Every development dependency runs in Docker Linux containers. Start local Supabase with `npm run db:start` through the Supabase CLI; start any other declared dependency through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model. Compose is an implementation detail. Configure the local environment and start the API and web app using the package scripts for the declared development profile. In production, the app and its dependencies run on Docker Swarm, except Supabase, which is a hosted service; Supabase pgvector owns vector search.
+Every development dependency runs in Docker Linux containers. Create the local database once with `npm run db:create`, start it with `npm run db:start` (one container of the pinned `db` image, on 127.0.0.1:54322), export `DATABASE_URL=postgresql://supabase_admin@127.0.0.1:54322/postgres` and apply `db/bootstrap.sql` and the migrations with `npm run db:push`; start any other declared dependency through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model. Compose is an implementation detail. Configure the local environment and start the API and web app using the package scripts for the declared development profile. In production, the app and its dependencies, the database included, run on Docker Swarm; pgvector owns vector search.
 
 ```sh
 npm install
@@ -36,17 +36,17 @@ npm run build:be
 npm run build:fe
 ```
 
-The API reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS`, `PRIMARY_DB_URL`, `PRIMARY_DB_SCHEMA`, `SUPABASE_URL`, and `SUPABASE_SERVICE_ROLE_KEY`. The web app reads `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, and, once the first GraphQL operation exists, `NEXT_PUBLIC_GRAPHQL_URL`. Missing configuration stops the relevant process with a named error; no template supplies credential defaults.
+The API reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS`, `PRIMARY_DB_URL`, `PRIMARY_DB_SCHEMA`, the Google OAuth keys `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` and `GOOGLE_CALLBACK_URL`, its own token keys `AUTH_JWT_ISSUER`, `AUTH_JWT_AUDIENCE`, `AUTH_JWT_KEY_ID` and `AUTH_JWT_PRIVATE_KEY`, and the storage keys `STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET`, `STORAGE_ACCESS_KEY_ID` and `STORAGE_SECRET_ACCESS_KEY`. The database tooling reads `DATABASE_URL`. The web app reads `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_API_URL`, and, once the first GraphQL operation exists, `NEXT_PUBLIC_GRAPHQL_URL`. Missing configuration stops the relevant process with a named error; no template supplies credential defaults.
 
-Production browser build values live in `.starcistacks/application-stacks.yaml` under `environments.production.deploy.images.web.buildArgs.values`. Before building deployment images, replace the placeholders with your site's public origin, your Supabase project's public URL, and its public anonymous key. These values reach every browser; keep the service role key in sealed runtime custody.
+Production browser build values live in `.starcistacks/application-stacks.yaml` under `environments.production.deploy.images.web.buildArgs.values`. Before building deployment images, replace the placeholders with your site's and your API's public origins. These values reach every browser; every credential stays in sealed runtime custody.
 
-`npm test` runs the back end's unit specs with per-file coverage. Optional integration specs run with `npm run test:integration` against the local Supabase stack (`npm run db:start`); a lite app has no e2e world.
+`npm test` runs the back end's unit specs with per-file coverage. Optional integration specs run with `npm run test:integration` against the local database (`npm run db:start`, then `npm run db:push`); a lite app has no e2e world.
 
 The public runtime template tracks only sealed member names. Scaffolding creates this app's own age recipient and encrypts generated placeholder values into the declared `.starcistacks/<environment>/secrets/*.enc` members. Keep the matching host age identity in untracked local custody, then use `starci app secret set` to replace each placeholder with an actual value before deployment. Product apps retain sealed member custody. Runtime specs use disposable copies with ephemeral identities and remove them afterwards.
 
 ## Database changes
 
-Create a forward-only migration under `supabase/migrations`, keep each table's RLS policies and grants beside the table, and run `npm run contract:emit` to refresh `supabase/types/database.types.ts`. `starci app add table <name> --fe` adds the table with its GraphQL feature on the API and its operations and SWR hooks in the web app; `npm run codegen:graphql` regenerates the web app's wire types from `be/contracts/<app>/schema.graphql`.
+Create a forward-only migration with `npm run db:new -- <kebab-name>` (it lands in `db/migrations`), keep each table's RLS policies and grants beside the table, apply it with `npm run db:push`, and run `npm run contract:emit` to refresh `db/types/database.types.ts`. `starci app add table <name> --fe` adds the table with its GraphQL feature on the API and its operations and SWR hooks in the web app; `npm run codegen:graphql` regenerates the web app's wire types from `be/contracts/<app>/schema.graphql`.
 
 ## Work
 

package/templates/app/skeleton-lite/{supabase → db}/migrations/__timestamp___baseline.sql

@@ -6,7 +6,7 @@ begin
 end;
 $$;
 
--- The attributes a Supabase migration role may change: SUPERUSER and BYPASSRLS stay as create role set them (the role migration owner is no superuser).
+-- The attributes a migration may change: SUPERUSER and BYPASSRLS stay as create role set them.
 alter role app_be login noinherit nocreatedb nocreaterole;
 
 create schema if not exists private;
@@ -24,6 +24,26 @@ begin
 end;
 $$;
 
+-- The rotating refresh sessions of integrations/passport (auth.users comes from db/bootstrap.sql).
+-- One row per issued refresh token, stored by its sha256 only. A family is one sign-in; rotation revokes the presented row
+-- and inserts its successor, and presenting a revoked row revokes the whole family (reuse detection).
+create table auth.refresh_sessions (
+    id uuid primary key default gen_random_uuid(),
+    family_id uuid not null,
+    user_id uuid not null references auth.users (id) on delete cascade,
+    token_hash char(64) not null unique,
+    expires_at timestamptz not null,
+    revoked_at timestamptz,
+    created_at timestamptz not null default now()
+);
+
+create index refresh_sessions_family_idx on auth.refresh_sessions (family_id);
+
+grant usage on schema auth to app_be;
+grant select, insert, update on table auth.users to app_be;
+grant select, insert on table auth.identities to app_be;
+grant select, insert, update on table auth.refresh_sessions to app_be;
+
 create table public.profiles (
     id uuid primary key references auth.users (id) on delete cascade,
     display_name text not null check (char_length(display_name) between 1 and 120),

package/templates/app/tool-config-lite/prettierignore

@@ -1,2 +1 @@
 {{> app/tool-config/prettierignore}}
-supabase/types/

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

@@ -1,15 +1,19 @@
 import { mockEntityManager } from "@starci/jest-preset"
 import type { EntityManager } from "typeorm"
-import { sql } from "./database.sql"
 import { DatabaseErrorCode } from "./errors/database.error"
-import { recordWebhookDelivery } from "./webhook-inbox.client"
+import { recordWebhookDelivery, webhookReceiptInsert } from "./webhook-inbox.client"
 
-// 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 INSERT = webhookReceiptInsert("spec_inbox")
 const PAYLOAD = { id: "delivery-1" }
 
 const record = (manager: EntityManager, deliveryId: string | undefined) =>
-    recordWebhookDelivery({ manager, insert: INSERT, provider: "spec", deliveryId, payload: PAYLOAD })
+    recordWebhookDelivery({ manager, table: "spec_inbox", provider: "spec", deliveryId, payload: PAYLOAD })
+
+describe("webhookReceiptInsert", () => {
+    it("refuses a table name that is not a lowercase identifier", () => {
+        expect(() => webhookReceiptInsert("spec; drop table x")).toThrow(TypeError)
+    })
+})
 
 describe("recordWebhookDelivery", () => {
     it("records a new delivery through the caller's transaction manager", async () => {

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

@@ -1,10 +1,10 @@
 import type { EntityManager } from "typeorm"
 import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
-import type { SqlText } from "./database.sql"
 
 interface RecordWebhookDelivery {
     readonly manager: EntityManager
-    readonly insert: SqlText
+    /** The provider inbox table under public, created by its db migration. */
+    readonly table: string
     readonly provider: string
     readonly deliveryId: string | undefined
     readonly payload: object
@@ -12,13 +12,22 @@ interface RecordWebhookDelivery {
 
 type WebhookReceiptId = string | undefined
 
+/** A provider inbox table name: a lowercase identifier, never a value. */
+const TABLE = /^[a-z_][a-z0-9_]*$/
+
+/** The conflict-safe insert of one pending delivery into `public.<table>`, answering its id only to the winning transaction. */
+export const webhookReceiptInsert = (table: string): string => {
+    if (!TABLE.test(table)) throw new TypeError(`${table} is not a provider inbox table name`)
+    return `INSERT INTO public.${table} (provider, delivery_id, payload) VALUES ($1, $2, $3::jsonb) ON CONFLICT (provider, delivery_id) DO NOTHING RETURNING id`
+}
+
 /**
  * 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 recordWebhookDelivery = async ({
     manager,
-    insert,
+    table,
     provider,
     deliveryId,
     payload,
@@ -27,7 +36,7 @@ export const recordWebhookDelivery = async ({
     if (!normalizedDeliveryId) {
         throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
     }
-    const rows: Array<{ readonly id: string }> = await manager.query(insert, [
+    const rows: Array<{ readonly id: string }> = await manager.query(webhookReceiptInsert(table), [
         provider,
         normalizedDeliveryId,
         JSON.stringify(payload),

package/templates/be/inbox/platform/client-operation-outcomes.sql.tpl

@@ -16,3 +16,50 @@ on public.inbox for delete to app_be
 using (source like 'client:%' and request_fingerprint is not null and outcome is not null);
 
 grant update, delete on table public.inbox to app_be;
+
+-- The client claim, its saved outcome and the bounded retention sweep, called through callDbFunction of platform/database (R334).
+-- A conflicting claim locks the existing row and returns its committed fingerprint and outcome after the winner commits.
+create function public.inbox_claim_client(p_source text, p_event_id text, p_fingerprint varchar, p_claimed_at timestamptz)
+returns table (request_fingerprint varchar, outcome jsonb, incomplete boolean)
+language sql
+as $$
+    insert into public.inbox as i (source, event_id, request_fingerprint, claimed_at)
+    values (p_source, p_event_id, p_fingerprint, p_claimed_at)
+    on conflict (source, event_id) do update set outcome = coalesce(i.outcome, '{}'::jsonb)
+    returning i.request_fingerprint, i.outcome,
+        (i.outcome is not null and (jsonb_typeof(i.outcome) <> 'object' or not (i.outcome ? 'value')))
+$$;
+
+create function public.inbox_save_client_outcome(p_source text, p_event_id text, p_outcome jsonb)
+returns table (outcome jsonb)
+language sql
+as $$
+    update public.inbox as i set outcome = p_outcome
+     where i.source = p_source and i.event_id = p_event_id
+    returning i.outcome
+$$;
+
+-- Retention never deletes delivery rows or an incomplete claim; its bounded batch skips rows held by active retries.
+create function public.inbox_sweep_clients(p_cutoff timestamptz, p_limit integer)
+returns table (deleted_count integer)
+language sql
+as $$
+    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 < p_cutoff
+         order by claimed_at, source, event_id limit p_limit 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(*)::integer from deleted
+$$;
+
+revoke all on function public.inbox_claim_client(text, text, varchar, timestamptz) from public;
+grant execute on function public.inbox_claim_client(text, text, varchar, timestamptz) to app_be;
+revoke all on function public.inbox_save_client_outcome(text, text, jsonb) from public;
+grant execute on function public.inbox_save_client_outcome(text, text, jsonb) to app_be;
+revoke all on function public.inbox_sweep_clients(timestamptz, integer) from public;
+grant execute on function public.inbox_sweep_clients(timestamptz, integer) to app_be;

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

@@ -3,7 +3,9 @@ import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
 import { EventBusErrorCode } from "./errors/event-bus.error"
 import { BaseEvent } from "./event-bus.contracts"
 import { EventBusService } from "./event-bus.service"
-import { INSERT_OUTBOX_EVENT } from "./persistence/event-bus.sql"
+
+// The statement callDbFunction of platform/database sends for event_bus_write.
+const INSERT_OUTBOX_EVENT = "SELECT * FROM event_bus_write($1, $2, $3, $4)"
 
 class ReceiptRecordedEvent extends BaseEvent {
     readonly eventId = "receipt-1"

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

@@ -4,7 +4,7 @@ import { isCorrelationId } from "@modules/platform/logging"
 import { EventBusError, EventBusErrorCode } from "./errors/event-bus.error"
 import type { BaseEvent, EventEnvelope } from "./event-bus.contracts"
 import type { EventBus } from "./event-bus.port"
-import { INSERT_OUTBOX_EVENT } from "./persistence/event-bus.sql"
+import { callDbFunction } from "@modules/platform/database"
 
 @Injectable()
 /** Writes a receipt event into the same transaction as its inbox receipt, without running any consumer. */
@@ -18,6 +18,6 @@ export class EventBusService implements EventBus {
             eventName: event.eventName,
             payload: event.payload,
         }
-        await tx.query(INSERT_OUTBOX_EVENT, [event.eventId, event.eventName, JSON.stringify(envelope), correlationId])
+        await callDbFunction(tx, "event_bus_write", [event.eventId, event.eventName, JSON.stringify(envelope), correlationId])
     }
 }

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

@@ -7,7 +7,12 @@ 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_CLIENT, CLAIM_EVENT, SAVE_CLIENT_OUTCOME, SWEEP_CLIENTS } from "./persistence/inbox.sql"
+
+// The statements callDbFunction of platform/database sends for each inbox function.
+const CLAIM_EVENT = "SELECT * FROM inbox_claim_event($1, $2)"
+const CLAIM_CLIENT = "SELECT * FROM inbox_claim_client($1, $2, $3, $4)"
+const SAVE_CLIENT_OUTCOME = "SELECT * FROM inbox_save_client_outcome($1, $2, $3)"
+const SWEEP_CLIENTS = "SELECT * FROM inbox_sweep_clients($1, $2)"
 
 const runClient = <T>(
     inbox: PostgresInbox,

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

@@ -2,14 +2,46 @@ import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
-import { BATCH_ROWS, DatabaseError, DatabaseErrorCode } from "@modules/platform/database"
+import { BATCH_ROWS, DatabaseError, DatabaseErrorCode, callDbFunction } 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"
+
+/** The JSON envelope makes a completed null value distinct from a pending SQL-null outcome. */
+interface ClientOutcomeRow<T> {
+    /** The operation's complete JSON result, including expected refusals. */
+    readonly value: T
+}
+
+/** The row returned by the atomic client claim. */
+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. */
+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. */
+interface InboxEventRow {
+    /** The event or client key owned by the row. */
+    readonly event_id: string
+}
+
+/** The bounded retention batch's aggregate result. */
+interface InboxSweepRow {
+    /** Number of completed client claims removed by this transaction. */
+    readonly deleted_count: number
+}
 
 @Injectable()
 /** Claims a delivery with the receipt transaction, so a failure can be retried without losing the delivery. */
@@ -22,7 +54,7 @@ export class PostgresInbox implements Inbox {
         if (!normalizedEventId) {
             throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
         }
-        const rows: Array<InboxEventRow> = await tx.query(CLAIM_EVENT, [source, normalizedEventId])
+        const rows = await callDbFunction<InboxEventRow>(tx, "inbox_claim_event", [source, normalizedEventId])
         return rows.length > 0
     }
 
@@ -32,7 +64,7 @@ export class PostgresInbox implements Inbox {
             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, [
+        const rows = await callDbFunction<ClaimClientRow<T>>(tx, "inbox_claim_client", [
             source,
             request.idempotencyKey,
             fingerprint,
@@ -52,7 +84,7 @@ export class PostgresInbox implements Inbox {
         } catch (cause) {
             throw new InboxError({ code: InboxErrorCode.OutcomeInvalid, cause })
         }
-        const saved: Array<SavedClientOutcomeRow<T>> = await tx.query(SAVE_CLIENT_OUTCOME, [
+        const saved = await callDbFunction<SavedClientOutcomeRow<T>>(tx, "inbox_save_client_outcome", [
             source,
             request.idempotencyKey,
             outcome,
@@ -64,7 +96,7 @@ export class PostgresInbox implements Inbox {
 
     /** 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])
+        const rows = await callDbFunction<InboxSweepRow>(tx, "inbox_sweep_clients", [cutoff, BATCH_ROWS])
         return rows[0]?.deleted_count ?? 0
     }
 }

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

@@ -47,3 +47,25 @@ 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;
+
+-- The claim of one delivery and the typed envelope write, called through callDbFunction of platform/database (R334).
+create function public.inbox_claim_event(p_source text, p_event_id text)
+returns table (event_id text)
+language sql
+as $$
+    insert into public.inbox as i (source, event_id) values (p_source, p_event_id)
+    on conflict (source, event_id) do nothing
+    returning i.event_id
+$$;
+
+create function public.event_bus_write(p_event_id text, p_event_name text, p_payload jsonb, p_correlation_id varchar)
+returns void
+language sql
+as $$
+    insert into public.event_bus (event_id, event_name, payload, correlation_id) values (p_event_id, p_event_name, p_payload, p_correlation_id)
+$$;
+
+revoke all on function public.inbox_claim_event(text, text) from public;
+grant execute on function public.inbox_claim_event(text, text) to app_be;
+revoke all on function public.event_bus_write(text, text, jsonb, varchar) from public;
+grant execute on function public.event_bus_write(text, text, jsonb, varchar) to app_be;

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

@@ -1,13 +1,13 @@
 import { fakeInbox, fakeTransaction, mockEntityManager, recordingEventBus } from "@starci/jest-preset"
 import { Test } from "@nestjs/testing"
-import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { PRIMARY_ENTITY_MANAGER, webhookReceiptInsert } 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 { INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
 import { @@Provider@@InboxService } from "./@@provider@@-inbox.service"
 
 const DELIVERY = { id: "delivery-1" }
+const INSERT_@@providerUpper@@_INBOX = webhookReceiptInsert("@@table@@")
 
 const build = async (fresh: boolean, recorded: ReadonlyArray<{ readonly id: string }> = [{ id: "inbox-1" }]) => {
     const entityManager = mockEntityManager({ query: [INSERT_@@providerUpper@@_INBOX, recorded] })

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

@@ -6,7 +6,6 @@ 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 { INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
 
 interface @@Provider@@Delivery {
     readonly id: string
@@ -34,7 +33,7 @@ export class @@Provider@@InboxService {
             if (!(await this.inbox.claim("webhook.@@provider@@", request.eventId, manager))) return
             const receiptId = await recordWebhookDelivery({
                 manager,
-                insert: INSERT_@@providerUpper@@_INBOX,
+                table: "@@table@@",
                 provider: "@@provider@@",
                 deliveryId: request.eventId,
                 payload: request.delivery,

package/templates/be/patterns/jobs/platform-lite/job-claim.service.spec.ts.tpl

@@ -0,0 +1,156 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock, mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { JobsError, JobsErrorCode } from "./errors/jobs.error"
+import type { ClaimedJob } from "./jobs.contracts"
+import { JOBS_MANAGERS } from "./jobs.decorators"
+import { JobClaimService } from "./job-claim.service"
+
+// The statements callDbFunction of platform/database sends for each job function.
+const CLAIM_JOB = "SELECT * FROM job_claim($1, $2, $3, $4, $5, $6)"
+const ADVANCE_JOB = "SELECT * FROM job_advance($1, $2, $3, $4)"
+const COMPLETE_JOB = "SELECT * FROM job_complete($1, $2, $3)"
+const FAIL_JOB = "SELECT * FROM job_fail($1, $2, $3, $4)"
+
+const AT = "2026-02-03T04:05:06.000Z"
+
+const build = async (manager: MockEntityManager) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            JobClaimService,
+            { provide: JOBS_MANAGERS, useValue: [manager] },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+        ],
+    }).compile()
+    return { claims: moduleRef.get(JobClaimService) }
+}
+
+const buildWithoutConnection = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            JobClaimService,
+            { provide: JOBS_MANAGERS, useValue: [] },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+        ],
+    }).compile()
+    return { claims: moduleRef.get(JobClaimService) }
+}
+
+const claimed: ClaimedJob = { correlationId: "request-1", jobId: "j-1", kind: "mail", fencingToken: 3, currentStep: null, payload: { id: "m-1" } }
+
+describe("JobClaimService", () => {
+    describe("claim", () => {
+        it("claims the delivery in one statement and returns the job with the bumped token", async () => {
+            const manager = mockEntityManager({
+                query: [
+                    CLAIM_JOB,
+                    [{ id: "j-1", kind: "mail", fencing_token: "3", current_step: null, payload: { id: "m-1" } }],
+                ],
+            })
+            const { claims } = await build(manager)
+
+            const job = await claims.claim({
+                kind: "mail",
+                jobKey: "k-1",
+                correlationId: "request-1",
+                payload: { id: "m-1" },
+                workerId: "w-1",
+                leaseMs: 60000,
+            })
+
+            expect(job).toEqual(claimed)
+            expect(manager.query).toHaveBeenCalledWith(CLAIM_JOB, [
+                "mail",
+                "k-1",
+                "w-1",
+                new Date("2026-02-03T04:06:06.000Z"),
+                JSON.stringify({ id: "m-1" }),
+                new Date(AT),
+            ])
+        })
+
+        it("answers null when the job is done or another worker holds a live claim", async () => {
+            const manager = mockEntityManager({ query: [CLAIM_JOB, []] })
+            const { claims } = await build(manager)
+
+            await expect(
+                claims.claim({ correlationId: "request-1", kind: "mail", jobKey: "k-1", payload: {}, workerId: "w-1", leaseMs: 1000 }),
+            ).resolves.toBeNull()
+        })
+    })
+
+    describe("guarded writes", () => {
+        it("records a step, completes and fails under the token the caller holds", async () => {
+            const manager = mockEntityManager({
+                query: [
+                    [ADVANCE_JOB, [{ id: "j-1" }]],
+                    [COMPLETE_JOB, [{ id: "j-1" }]],
+                    [FAIL_JOB, [{ id: "j-1" }]],
+                ],
+            })
+            const { claims } = await build(manager)
+
+            await claims.advance({ jobId: "j-1", expectedFencingToken: 3, step: "send" })
+            await claims.complete({ jobId: "j-1", expectedFencingToken: 3 })
+            await claims.fail({ jobId: "j-1", expectedFencingToken: 3, reason: "boom" })
+
+            expect(manager.query).toHaveBeenNthCalledWith(1, ADVANCE_JOB, ["j-1", 3, "send", new Date(AT)])
+            expect(manager.query).toHaveBeenNthCalledWith(2, COMPLETE_JOB, ["j-1", 3, new Date(AT)])
+            expect(manager.query).toHaveBeenNthCalledWith(3, FAIL_JOB, ["j-1", 3, "boom", new Date(AT)])
+        })
+
+        it("throws JobFencedOut when a write finds no row at its token: a newer worker owns the job", async () => {
+            const manager = mockEntityManager({
+                query: [
+                    [ADVANCE_JOB, []],
+                    [COMPLETE_JOB, []],
+                    [FAIL_JOB, []],
+                ],
+            })
+            const { claims } = await build(manager)
+
+            const attempts = [
+                claims.advance({ jobId: "j-1", expectedFencingToken: 2, step: "send" }),
+                claims.complete({ jobId: "j-1", expectedFencingToken: 2 }),
+                claims.fail({ jobId: "j-1", expectedFencingToken: 2, reason: "boom" }),
+            ]
+
+            for (const attempt of attempts) {
+                await expect(attempt).rejects.toMatchObject({
+                    code: JobsErrorCode.FencedOut,
+                    params: { jobId: "j-1", token: 2 },
+                })
+                await expect(attempt).rejects.toBeInstanceOf(JobsError)
+            }
+        })
+    })
+
+    describe("runKey", () => {
+        it("includes the job, the step and the fencing token, so a zombie's key differs from the live worker's", async () => {
+            const { claims } = await build(mockEntityManager())
+
+            expect(claims.runKey(claimed, "send")).toBe("j-1:send:3")
+            expect(claims.runKey({ ...claimed, fencingToken: 4 }, "send")).toBe("j-1:send:4")
+        })
+
+        it("refuses a step name that carries the separator, because the key would be ambiguous", async () => {
+            const { claims } = await build(mockEntityManager())
+
+            expect(() => claims.runKey(claimed, "send:twice")).toThrow(JobsError)
+            expect(() => claims.runKey(claimed, "send:twice")).toThrow(JobsErrorCode.RunKeyInvalid)
+        })
+    })
+
+    describe("registration", () => {
+        it("refuses to claim with no connection to hold the job table", async () => {
+            const { claims } = await buildWithoutConnection()
+
+            await expect(
+                claims.claim({ correlationId: "request-1", kind: "mail", jobKey: "k-1", payload: {}, workerId: "w-1", leaseMs: 1000 }),
+            ).rejects.toMatchObject({
+                code: JobsErrorCode.ConnectionMissing,
+            })
+        })
+    })
+})