@starci/hfs 4.10.1 → 4.11.8

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

@@ -1,7 +1,16 @@
 export { EVENT_BUS_ERROR_KINDS } from "./errors/event-bus.error"
 export { EVENT_BUS_MESSAGES } from "./messages/event-bus.messages"
-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 { BaseEvent, DEAD_QUEUE_SUFFIX, DEFAULT_MAX_DELIVERIES } from "./event-bus.contracts"
+export type {
+    DeadLetter,
+    EventClass,
+    EventDelivery,
+    EventEnvelope,
+    EventPayload,
+    EventSubscriptionOptions,
+    ParsedEvent,
+} from "./event-bus.contracts"
+export { EVENT_BUS, EVENT_CONSUMER_REGISTRY, InjectEventBus, InjectEventConsumerRegistry } from "./event-bus.decorators"
 export { EventBusModule } from "./event-bus.module"
-export type { EventBus, EventConsumer } from "./event-bus.port"
+export type { EventBusOptions } from "./event-bus.options"
+export type { EventBus, EventConsumer, EventConsumerRegistry } from "./event-bus.port"

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

@@ -9,10 +9,10 @@ import { requestFingerprint } from "./request-fingerprint.policy"
 import { PostgresInbox } from "./inbox.service"
 
 // 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 CLAIM_EVENT = 'SELECT * FROM "public"."inbox_claim_event"($1, $2)'
+const CLAIM_CLIENT = 'SELECT * FROM "public"."inbox_claim_client"($1, $2, $3, $4)'
+const SAVE_CLIENT_OUTCOME = 'SELECT * FROM "public"."inbox_save_client_outcome"($1, $2, $3)'
+const SWEEP_CLIENTS = 'SELECT * FROM "public"."inbox_sweep_clients"($1, $2)'
 
 const runClient = <T>(
     inbox: PostgresInbox,

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

@@ -54,7 +54,7 @@ export class PostgresInbox implements Inbox {
         if (!normalizedEventId) {
             throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
         }
-        const rows = await callDbFunction<InboxEventRow>(tx, "inbox_claim_event", [source, normalizedEventId])
+        const rows = await callDbFunction<InboxEventRow>(tx, "public.inbox_claim_event", [source, normalizedEventId])
         return rows.length > 0
     }
 
@@ -64,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 = await callDbFunction<ClaimClientRow<T>>(tx, "inbox_claim_client", [
+        const rows = await callDbFunction<ClaimClientRow<T>>(tx, "public.inbox_claim_client", [
             source,
             request.idempotencyKey,
             fingerprint,
@@ -84,7 +84,7 @@ export class PostgresInbox implements Inbox {
         } catch (cause) {
             throw new InboxError({ code: InboxErrorCode.OutcomeInvalid, cause })
         }
-        const saved = await callDbFunction<SavedClientOutcomeRow<T>>(tx, "inbox_save_client_outcome", [
+        const saved = await callDbFunction<SavedClientOutcomeRow<T>>(tx, "public.inbox_save_client_outcome", [
             source,
             request.idempotencyKey,
             outcome,
@@ -96,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 = await callDbFunction<InboxSweepRow>(tx, "inbox_sweep_clients", [cutoff, BATCH_ROWS])
+        const rows = await callDbFunction<InboxSweepRow>(tx, "public.inbox_sweep_clients", [cutoff, BATCH_ROWS])
         return rows[0]?.deleted_count ?? 0
     }
 }

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

@@ -1,4 +1,4 @@
--- Both the claim and receipt event use the intake transaction; after-commit processing reads the outbox separately.
+-- The claim and the receipt event share the intake transaction; a consumer reads the event from its pgmq queue after commit.
 create table public.inbox (
     source text not null check (source <> ''),
     event_id text not null check (event_id <> ''),
@@ -20,35 +20,16 @@ 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 (
-    correlation_id varchar(128) not null,
-    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;
+-- The event bus is pgmq (ruling lite-pgmq-bus-bullmq-jobs; it installs into its own schema pgmq): a publish sends the typed envelope
+-- once to its topic, the event name, in the publisher's own transaction, and pgmq copies it into every consumer queue bound to that
+-- name, so a rolled-back change sends nothing and no relay runs. A reactor's migration declares its consumer: pgmq.create of
+-- '<topic>__<consumer>' and of its dead-letter queue '<topic>__<consumer>__dead', then pgmq.bind_topic('<topic>', '<topic>__<consumer>')
+-- (R258). Each consumer reads its own queue with a visibility timeout, archives a handled message, and moves one past its
+-- maxDeliveries to its dead-letter queue.
+create extension if not exists pgmq;
 
--- The claim of one delivery and the typed envelope write, called through callDbFunction of platform/database (R334).
+-- The claim of one delivery and the bus operations, called through callDbFunction of platform/database (R334). The bus functions are
+-- security definer over pgmq, so the application role holds no grant on the pgmq schema; a read names only a queue bound to a topic.
 create function public.inbox_claim_event(p_source text, p_event_id text)
 returns table (event_id text)
 language sql
@@ -58,14 +39,96 @@ as $$
     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
+create function public.event_bus_send(p_event_name text, p_envelope jsonb)
+returns integer
 language sql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+    select pgmq.send_topic(p_event_name, p_envelope)
+$$;
+
+create function public.event_bus_read(p_queue text, p_visibility_seconds integer, p_batch integer)
+returns table (msg_id bigint, read_ct integer, message jsonb)
+language sql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+    select m.msg_id, m.read_ct, m.message
+      from (select distinct b.queue_name from pgmq.topic_bindings as b where b.queue_name = p_queue) as bound
+     cross join lateral pgmq.read(bound.queue_name, p_visibility_seconds, p_batch) as m
+$$;
+
+create function public.event_bus_archive(p_queue text, p_msg_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+    select pgmq.archive(p_queue, p_msg_id)
+$$;
+
+create function public.event_bus_bury(p_queue text, p_msg_id bigint, p_read_ct integer, p_message jsonb, p_reason text)
+returns boolean
+language plpgsql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+begin
+    if not exists (select 1 from pgmq.topic_bindings as b where b.queue_name = p_queue) then
+        raise exception 'event_bus_bury: % is no consumer queue bound to a topic', p_queue;
+    end if;
+    perform pgmq.send(p_queue || '__dead', jsonb_build_object('readCount', p_read_ct, 'reason', p_reason, 'message', p_message));
+    return pgmq.archive(p_queue, p_msg_id);
+end
+$$;
+
+create function public.event_bus_dead_letters(p_queue text, p_batch integer)
+returns table (msg_id bigint, message jsonb)
+language plpgsql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+begin
+    if not exists (select 1 from pgmq.topic_bindings as b where b.queue_name = p_queue) then
+        raise exception 'event_bus_dead_letters: % is no consumer queue bound to a topic', p_queue;
+    end if;
+    return query execute format('select d.msg_id, d.message from pgmq.%I as d order by d.msg_id limit $1', 'q_' || p_queue || '__dead') using p_batch;
+end
+$$;
+
+create function public.event_bus_requeue(p_queue text, p_msg_id bigint)
+returns boolean
+language plpgsql
+security definer
+set search_path = pg_catalog, pg_temp
 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)
+declare
+    v_dead jsonb;
+begin
+    if not exists (select 1 from pgmq.topic_bindings as b where b.queue_name = p_queue) then
+        raise exception 'event_bus_requeue: % is no consumer queue bound to a topic', p_queue;
+    end if;
+    execute format('delete from pgmq.%I as d where d.msg_id = $1 returning d.message', 'q_' || p_queue || '__dead') into v_dead using p_msg_id;
+    if v_dead is null then
+        return false;
+    end if;
+    perform pgmq.send(p_queue, v_dead -> 'message');
+    return true;
+end
 $$;
 
 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;
+revoke all on function public.event_bus_send(text, jsonb) from public;
+grant execute on function public.event_bus_send(text, jsonb) to app_be;
+revoke all on function public.event_bus_read(text, integer, integer) from public;
+grant execute on function public.event_bus_read(text, integer, integer) to app_be;
+revoke all on function public.event_bus_archive(text, bigint) from public;
+grant execute on function public.event_bus_archive(text, bigint) to app_be;
+revoke all on function public.event_bus_bury(text, bigint, integer, jsonb, text) from public;
+grant execute on function public.event_bus_bury(text, bigint, integer, jsonb, text) to app_be;
+revoke all on function public.event_bus_dead_letters(text, integer) from public;
+grant execute on function public.event_bus_dead_letters(text, integer) to app_be;
+revoke all on function public.event_bus_requeue(text, bigint) from public;
+grant execute on function public.event_bus_requeue(text, bigint) to app_be;

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

@@ -63,7 +63,7 @@ describe("@@Provider@@InboxService", () => {
 
         it("rolls back the receipt when publishing fails", async () => {
             const { inbox, events, transaction } = await build(true)
-            const failure = new Error("outbox unavailable")
+            const failure = new Error("event bus unavailable")
             events.failNext("publish", failure)
 
             await expect(inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })).rejects.toBe(failure)

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

@@ -11,8 +11,8 @@ import { @@Event@@Request } from "./dto/@@event@@.request"
 @Controller("webhooks/@@provider@@")
 /**
  * POST /webhooks/@@provider@@, the signed intake door of the @@provider@@ notifier. The signature and replay window are proven
- * first; the verified delivery goes to one domain intake that records a receipt and typed outbox event in its transaction. A separate
- * reactor or job consumes the committed row and dispatches the command.
+ * first; the verified delivery goes to one domain intake that records a receipt and sends its typed event in its transaction. A separate
+ * reactor reads the committed event from its pgmq queue and dispatches the command.
  */
 export class @@Provider@@Webhook {
     constructor(

package/templates/be/patterns/jobs/platform/jobs.log-events.ts.tpl

@@ -6,4 +6,6 @@ export enum JobsLogEvent {
     DeliveryFailed = "jobs.delivery.failed",
     /** A failed delivery could not even be recorded as failed; the lease will expire and the job will be claimed again. */
     FailureNotRecorded = "jobs.delivery.failure-not-recorded",
+    /** A scheduler tick failed to fire; the next firing claims its own minute (lite, R335). */
+    TickFailed = "jobs.tick.failed",
 }

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

@@ -8,10 +8,10 @@ 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 CLAIM_JOB = 'SELECT * FROM "public"."job_claim"($1, $2, $3, $4, $5, $6)'
+const ADVANCE_JOB = 'SELECT * FROM "public"."job_advance"($1, $2, $3, $4)'
+const COMPLETE_JOB = 'SELECT * FROM "public"."job_complete"($1, $2, $3)'
+const FAIL_JOB = 'SELECT * FROM "public"."job_fail"($1, $2, $3, $4)'
 
 const AT = "2026-02-03T04:05:06.000Z"
 

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

@@ -46,7 +46,7 @@ export class JobClaimService implements JobClaims {
     /** Claims the delivery; null when the job is done or another worker holds a claim that has not expired. */
     async claim(params: ClaimParams): Promise<ClaimResult> {
         const now = this.clock.now()
-        const rows = await callDbFunction<ClaimedRecord>(this.writer(), "job_claim", [
+        const rows = await callDbFunction<ClaimedRecord>(this.writer(), "public.job_claim", [
             params.kind,
             params.jobKey,
             params.workerId,
@@ -69,17 +69,17 @@ export class JobClaimService implements JobClaims {
 
     /** Records a finished step under the token the caller holds. */
     advance(write: AdvanceWrite): Promise<void> {
-        return this.guarded("job_advance", [write.jobId, write.expectedFencingToken, write.step, this.clock.now()], write)
+        return this.guarded("public.job_advance", [write.jobId, write.expectedFencingToken, write.step, this.clock.now()], write)
     }
 
     /** Completes the job under the token the caller holds. */
     complete(write: GuardedWrite): Promise<void> {
-        return this.guarded("job_complete", [write.jobId, write.expectedFencingToken, this.clock.now()], write)
+        return this.guarded("public.job_complete", [write.jobId, write.expectedFencingToken, this.clock.now()], write)
     }
 
     /** Marks the job failed under the token the caller holds, so BullMQ can retry it. */
     fail(write: FailWrite): Promise<void> {
-        return this.guarded("job_fail", [write.jobId, write.expectedFencingToken, write.reason, this.clock.now()], write)
+        return this.guarded("public.job_fail", [write.jobId, write.expectedFencingToken, write.reason, this.clock.now()], write)
     }
 
     /** The idempotency key of one step of this claim: it includes the token, so a zombie's repeat is a different key than the live worker's. */
@@ -99,7 +99,7 @@ export class JobClaimService implements JobClaims {
 
     /** Runs a guarded function that updates only when the token still matches; no row back means a newer worker owns the job. */
     private async guarded(
-        fn: "job_advance" | "job_complete" | "job_fail",
+        fn: "public.job_advance" | "public.job_complete" | "public.job_fail",
         parameters: Array<unknown>,
         write: GuardedWrite,
     ): Promise<void> {

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

@@ -0,0 +1,65 @@
+import { SchedulerRegistry } from "@nestjs/schedule"
+import { Test } from "@nestjs/testing"
+import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { LOGGER } from "@modules/platform/logging"
+import { QUEUE_OUTBOX } from "@modules/platform/queue"
+import type { JobTick } from "./job-ticks.contracts"
+import { JOBS_MANAGERS } from "./jobs.decorators"
+import { JobTickService, tickMinute } from "./job-tick.service"
+
+// The statements advisoryXactLock and callDbFunction of platform/database send for one firing.
+const LOCK_TICK = "SELECT pg_advisory_xact_lock(hashtextextended($1, 0))"
+const CLAIM_TICK = 'SELECT * FROM "public"."job_tick_claim"($1, $2)'
+
+const AT = "2026-02-03T04:05:06.000Z"
+const TICK: JobTick = { name: "nightly-digest", cron: "0 2 * * *", timeZone: "UTC", queue: "digests", payload: { kind: "nightly" } }
+
+const build = async (claimed: boolean) => {
+    const transaction = fakeTransaction(mockEntityManager({ query: [[LOCK_TICK, []], [CLAIM_TICK, [{ claimed }]]] }))
+    const outbox = { write: jest.fn().mockResolvedValue(undefined) }
+    const registry = { addCronJob: jest.fn() }
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            JobTickService,
+            { provide: SchedulerRegistry, useValue: registry },
+            { provide: JOBS_MANAGERS, useValue: [transaction.em] },
+            { provide: QUEUE_OUTBOX, useValue: outbox },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: LOGGER, useValue: { info: jest.fn(), warn: jest.fn(), error: jest.fn() } },
+        ],
+    }).compile()
+    return { ticks: moduleRef.get(JobTickService), transaction, outbox, registry }
+}
+
+describe("JobTickService", () => {
+    it("names a tick's slot by its UTC minute", () => {
+        expect(tickMinute(new Date(AT))).toBe("2026-02-03T04:05")
+    })
+
+    it("locks the tick, claims its minute and enqueues one job in the same transaction", async () => {
+        const { ticks, transaction, outbox } = await build(true)
+
+        await expect(ticks.fire(TICK)).resolves.toBe(true)
+
+        expect(transaction.em.query).toHaveBeenNthCalledWith(1, LOCK_TICK, ["tick:nightly-digest"])
+        expect(transaction.em.query).toHaveBeenNthCalledWith(2, CLAIM_TICK, ["nightly-digest", "2026-02-03T04:05"])
+        expect(outbox.write).toHaveBeenCalledWith(expect.anything(), "digests", { kind: "nightly" }, "tick:nightly-digest:2026-02-03T04:05")
+    })
+
+    it("enqueues nothing when another replica already fired the tick this minute", async () => {
+        const { ticks, outbox } = await build(false)
+
+        await expect(ticks.fire(TICK)).resolves.toBe(false)
+
+        expect(outbox.write).not.toHaveBeenCalled()
+    })
+
+    it("registers no cron job while the tick list is empty", async () => {
+        const { ticks, registry } = await build(true)
+
+        ticks.onApplicationBootstrap()
+
+        expect(registry.addCronJob).not.toHaveBeenCalled()
+    })
+})

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

@@ -0,0 +1,78 @@
+import { Injectable } from "@nestjs/common"
+import type { OnApplicationBootstrap } from "@nestjs/common"
+import { SchedulerRegistry } from "@nestjs/schedule"
+import { CronJob } from "cron"
+import type { EntityManager } from "typeorm"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { advisoryXactLock, callDbFunction } from "@modules/platform/database"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { InjectQueueOutbox } from "@modules/platform/queue"
+import type { QueueOutbox } from "@modules/platform/queue"
+import { JobsError, JobsErrorCode } from "./errors/jobs.error"
+import { JOB_TICKS } from "./job-ticks.contracts"
+import type { JobTick } from "./job-ticks.contracts"
+import { InjectJobsManagers } from "./jobs.decorators"
+import { JobsLogEvent } from "./jobs.log-events"
+
+/** The record job_tick_claim returns. */
+interface TickClaim {
+    /** True when this firing moved the tick to its minute and must enqueue. */
+    readonly claimed: boolean
+}
+
+/** The UTC minute of `at` (`YYYY-MM-DDTHH:MM`): the slot a tick fires once in. */
+export const tickMinute = (at: Date): string => at.toISOString().slice(0, 16)
+
+@Injectable()
+/**
+ * The one scheduler of the app (R335): @nestjs/schedule fires every tick of JOB_TICKS on every replica, and each firing takes
+ * advisoryXactLock("tick:<name>"), claims the tick's minute through job_tick_claim and, only when it moved the tick, writes one
+ * job into the queue outbox in the same transaction, so the deployment enqueues the tick once per minute.
+ */
+export class JobTickService implements OnApplicationBootstrap {
+    constructor(
+        private readonly registry: SchedulerRegistry,
+        @InjectJobsManagers() private readonly managers: ReadonlyArray<EntityManager>,
+        @InjectQueueOutbox() private readonly outbox: QueueOutbox,
+        @InjectClock() private readonly clock: Clock,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    /** Registers one cron job per tick, read in the tick's time zone; a failed firing is logged and the next one runs. */
+    onApplicationBootstrap(): void {
+        for (const tick of JOB_TICKS) {
+            this.registry.addCronJob(tick.name, CronJob.from({
+                cronTime: tick.cron,
+                timeZone: tick.timeZone,
+                onTick: async () => {
+                    await this.fire(tick)
+                },
+                errorHandler: (cause: unknown) => {
+                    this.logger.error(JobsLogEvent.TickFailed, cause, { tick: tick.name })
+                },
+                start: true,
+            }))
+        }
+    }
+
+    /** Fires the tick for the current minute; true when this replica enqueued its job, false when another one already had. */
+    async fire(tick: JobTick): Promise<boolean> {
+        const minute = tickMinute(this.clock.now())
+        return this.writer().transaction(async (tx) => {
+            await advisoryXactLock(tx, `tick:${tick.name}`)
+            const [claim] = await callDbFunction<TickClaim>(tx, "public.job_tick_claim", [tick.name, minute])
+            if (claim?.claimed !== true) return false
+            await this.outbox.write(tx, tick.queue, tick.payload, `tick:${tick.name}:${minute}`)
+            return true
+        })
+    }
+
+    /** The entity manager of the connection that holds the tick table. */
+    private writer(): EntityManager {
+        const [manager] = this.managers
+        if (manager === undefined) throw new JobsError({ code: JobsErrorCode.ConnectionMissing })
+        return manager
+    }
+}

package/templates/be/patterns/jobs/platform-lite/job-ticks.contracts.ts.tpl

@@ -0,0 +1,16 @@
+/** One recurring tick of platform/jobs: at each minute its cron expression names, one job of `queue` is enqueued with `payload` (R335). */
+export interface JobTick {
+    /** The stable name: the advisory lock key, the minute claim and the correlation id carry it. */
+    readonly name: string
+    /** The five-field cron expression of the minutes the tick fires at. */
+    readonly cron: string
+    /** The time zone the expression is read in; ticks run in UTC. */
+    readonly timeZone: "UTC"
+    /** The queue the tick enqueues one job of. */
+    readonly queue: string
+    /** The payload of that job: ids and literals only. */
+    readonly payload: object
+}
+
+/** The ticks of this app, as data: JobTickService registers one cron job per entry. */
+export const JOB_TICKS: ReadonlyArray<JobTick> = []

package/templates/be/patterns/jobs/platform-lite/jobs.module.ts.tpl

@@ -0,0 +1,40 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { ScheduleModule } from "@nestjs/schedule"
+import type { EntityManager } from "typeorm"
+import { JOB_CLAIMS, JOB_PROCESSOR_REGISTRY, JOBS_MANAGERS } from "./jobs.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./jobs.module-definition"
+import { JobClaimService } from "./job-claim.service"
+import { JobRunnerService } from "./job-runner.service"
+import { JobTickService } from "./job-tick.service"
+
+@Module({})
+/**
+ * The fenced jobs of a service: the claim service that owns the job row, the runner that subscribes processors to their queues and
+ * the one tick scheduler (R335), which composes @nestjs/schedule here and nowhere else. Needs the queue capability registered in
+ * the same app.
+ */
+export class JobsModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app that runs jobs. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            imports: [...(base.imports ?? []), ScheduleModule.forRoot()],
+            providers: [
+                ...(base.providers ?? []),
+                {
+                    provide: JOBS_MANAGERS,
+                    useFactory: (manager: EntityManager) => [manager],
+                    inject: [options.connection],
+                },
+                JobClaimService,
+                JobRunnerService,
+                JobTickService,
+                { provide: JOB_CLAIMS, useExisting: JobClaimService },
+                { provide: JOB_PROCESSOR_REGISTRY, useExisting: JobRunnerService },
+            ],
+            exports: [JOB_CLAIMS, JOB_PROCESSOR_REGISTRY],
+        }
+    }
+}

package/templates/be/patterns/jobs/platform-lite/jobs.sql.tpl

@@ -93,3 +93,47 @@ revoke all on function public.job_complete(uuid, bigint, timestamptz) from publi
 grant execute on function public.job_complete(uuid, bigint, timestamptz) to app_be;
 revoke all on function public.job_fail(uuid, bigint, text, timestamptz) from public;
 grant execute on function public.job_fail(uuid, bigint, text, timestamptz) to app_be;
+
+-- The scheduler ticks of platform/jobs (R335): one row per tick holds the last UTC minute it fired. Every replica's
+-- @nestjs/schedule fires the tick; under advisoryXactLock('tick:<name>') job_tick_claim moves the row to the new minute and
+-- answers claimed, so exactly one replica enqueues the tick's job per minute and a replica that comes later answers not claimed.
+create table public.job_ticks (
+    name varchar(200) not null,
+    minute varchar(16) not null,
+    constraint job_ticks_pkey primary key (name)
+);
+
+alter table public.job_ticks enable row level security;
+alter table public.job_ticks force row level security;
+
+create policy job_ticks_app_be_select
+on public.job_ticks for select to app_be
+using (name is not null);
+
+create policy job_ticks_app_be_insert
+on public.job_ticks for insert to app_be
+with check (name is not null);
+
+create policy job_ticks_app_be_update
+on public.job_ticks for update to app_be
+using (name is not null)
+with check (name is not null);
+
+revoke all on table public.job_ticks from public, anon, authenticated;
+grant select, insert, update on table public.job_ticks to app_be;
+
+create function public.job_tick_claim(p_name varchar, p_minute varchar)
+returns table (claimed boolean)
+language sql
+as $$
+    with moved as (
+        insert into public.job_ticks as t (name, minute) values (p_name, p_minute)
+        on conflict (name) do update set minute = excluded.minute
+         where t.minute < excluded.minute
+        returning true as claimed
+    )
+    select coalesce((select m.claimed from moved as m), false)
+$$;
+
+revoke all on function public.job_tick_claim(varchar, varchar) from public;
+grant execute on function public.job_tick_claim(varchar, varchar) to app_be;

package/templates/be/patterns/queues/platform-lite/queue-outbox.service.spec.ts.tpl

@@ -4,7 +4,7 @@ import { CLOCK } from "@modules/platform/clock"
 import { QueueOutboxService } from "./queue-outbox.service"
 
 // The statement callDbFunction of platform/database sends for queue_write.
-const INSERT_QUEUE_ROW = "SELECT * FROM queue_write($1, $2, $3, $4)"
+const INSERT_QUEUE_ROW = 'SELECT * FROM "public"."queue_write"($1, $2, $3, $4)'
 import { QueueErrorCode } from "./errors/queue.error"
 
 const AT = "2026-02-03T04:05:06.000Z"

package/templates/be/patterns/queues/platform-lite/queue-outbox.service.ts.tpl

@@ -15,6 +15,6 @@ export class QueueOutboxService implements QueueOutbox {
     /** Writes the job in the outbox of the transaction `tx`; the relay adds it to BullMQ after the commit. */
     async write(tx: EntityManager, queue: string, payload: object, correlationId: string): Promise<void> {
         if (!isCorrelationId(correlationId)) throw new QueueError({ code: QueueErrorCode.CorrelationInvalid })
-        await callDbFunction(tx, "queue_write", [queue, JSON.stringify(payload), this.clock.now(), correlationId])
+        await callDbFunction(tx, "public.queue_write", [queue, JSON.stringify(payload), this.clock.now(), correlationId])
     }
 }

package/templates/be/patterns/queues/platform-lite/queue-relay.service.spec.ts.tpl

@@ -11,8 +11,8 @@ import { QueueRelayService } from "./queue-relay.service"
 import type { QueueTransport } from "./queue-transport.port"
 
 // The statements callDbFunction of platform/database sends for the relay's functions.
-const SELECT_WAITING_ROWS = "SELECT * FROM queue_waiting($1)"
-const MARK_ROWS_SENT = "SELECT * FROM queue_mark_sent($1, $2)"
+const SELECT_WAITING_ROWS = 'SELECT * FROM "public"."queue_waiting"($1)'
+const MARK_ROWS_SENT = 'SELECT * FROM "public"."queue_mark_sent"($1, $2)'
 
 const AT = "2026-02-03T04:05:06.000Z"
 

package/templates/be/patterns/queues/platform-lite/queue-relay.service.ts.tpl

@@ -44,7 +44,7 @@ export class QueueRelayService extends OutboxRelayPolicy<QueueRow> {
     }
 
     protected async select(tx: EntityManager): Promise<Array<QueueRow>> {
-        return [...(await callDbFunction<QueueRow>(tx, "queue_waiting", [this.options.relayBatch]))]
+        return [...(await callDbFunction<QueueRow>(tx, "public.queue_waiting", [this.options.relayBatch]))]
     }
 
     protected async deliver(rows: ReadonlyArray<QueueRow>): Promise<void> {
@@ -53,7 +53,7 @@ export class QueueRelayService extends OutboxRelayPolicy<QueueRow> {
     }
 
     protected async mark(tx: EntityManager, rows: ReadonlyArray<QueueRow>): Promise<void> {
-        await callDbFunction(tx, "queue_mark_sent", [rows.map((row) => row.id), this.clock.now()])
+        await callDbFunction(tx, "public.queue_mark_sent", [rows.map((row) => row.id), this.clock.now()])
     }
 
     protected idle(): Promise<void> {

package/templates/be/skeleton/apps/__app__/src/__app__.env.ts

@@ -1,6 +1,7 @@
 import type { EnvSource } from "@modules/platform/config"
 import { parseServerConfig } from "@modules/platform/config"
 import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
+import { parseHttpConfig } from "@modules/platform/http"
 import { parseHttpSecurityConfig } from "@modules/platform/http-security"
 
 /** The {{app}} environment values required before composition. */
@@ -9,6 +10,8 @@ export interface {{appPascal}}Env {
     readonly server: ReturnType<typeof parseServerConfig>
     /** The origin allowlist and rate limits. */
     readonly httpSecurity: ReturnType<typeof parseHttpSecurityConfig>
+    /** What the outbound HTTP client trusts beyond Node's bundled certificate authorities. */
+    readonly http: ReturnType<typeof parseHttpConfig>
     /** The primary database connection. */
     readonly database: ReturnType<typeof parsePrimaryDatabaseConfig>
 }
@@ -17,5 +20,6 @@ export interface {{appPascal}}Env {
 export const read{{appPascal}}Env = (env: EnvSource): {{appPascal}}Env => ({
     server: parseServerConfig(env),
     httpSecurity: parseHttpSecurityConfig(env),
+    http: parseHttpConfig(env),
     database: parsePrimaryDatabaseConfig(env),
 })