@ultimat3/jobs 29.4.0 → 30.0.0

package/src/outbox-pg.ts

@@ -16,9 +16,11 @@ import { nowMs } from './clock';
 import {
   SQL_OUTBOX_CLAIM,
   SQL_OUTBOX_MARK_PUBLISHED,
+  SQL_OUTBOX_MARK_PUBLISHED_MANY,
   SQL_OUTBOX_PENDING_COUNT,
   SQL_OUTBOX_RELEASE,
   SQL_OUTBOX_STAGE,
+  SQL_OUTBOX_STAGE_MANY,
 } from './driver-pg-sql';
 import type { OutboxRecord, OutboxStore } from './outbox';
 import { resolveClaimLeaseMs } from './outbox-lease';
@@ -124,6 +126,29 @@ export function postgresOutboxStore(options: PostgresOutboxStoreOptions): Outbox
       staged.set(key(tx), bucket);
     },
 
+    /** `enqueueMany`'s chunk: one statement on the same connection `stage` writes on. */
+    async stageMany(tx, records) {
+      if (records.length === 0) return;
+      const rows = records.map((record) => ({
+        id: record.id,
+        runId: record.runId,
+        job: record.job,
+        queue: record.queue,
+        input: record.input ?? null,
+        idempotencyKey: record.idempotencyKey,
+        maxAttempts: record.maxAttempts,
+        runAt: record.runAt,
+        stagedAt: record.stagedAt,
+        tenantId: record.tenantId,
+        traceparent: record.traceparent,
+        enqueuedBy: record.enqueuedBy,
+      }));
+      await options.txExecutor(tx).query(SQL_OUTBOX_STAGE_MANY, [JSON.stringify(rows)]);
+      const bucket = staged.get(key(tx)) ?? [];
+      bucket.push(...records);
+      staged.set(key(tx), bucket);
+    },
+
     /**
      * Nothing to do but report. The rows became visible when Postgres committed them — there is
      * no second write here, and that absence IS the guarantee: a commit hook that had to run
@@ -179,6 +204,16 @@ export function postgresOutboxStore(options: PostgresOutboxStoreOptions): Outbox
       ]);
     },
 
+    /** The relay's batch mark: one statement, `markPublished`'s fence on every row. */
+    async markPublishedMany(ids, at, claimant) {
+      if (ids.length === 0) return;
+      await options.executor.query(SQL_OUTBOX_MARK_PUBLISHED_MANY, [
+        ids,
+        at || nowMs(options.clock),
+        claimant ?? relayId,
+      ]);
+    },
+
     async pendingCount() {
       const rows = await options.executor.query<{ pending: number | string }>(
         SQL_OUTBOX_PENDING_COUNT,

package/src/outbox-relay.ts

@@ -8,9 +8,10 @@
 import { assert, logger, onShutdown, renderThrowable } from '@ultimat3/core';
 import { nowMs } from './clock';
 import { createDrainBudget, settleAllBy } from './drain-wait';
+import { publishRequest } from './enqueue-record';
 import { onStaged, signalEnqueued } from './enqueue-signal';
 import { createIdleBackoff } from './idle-backoff';
-import type { OutboxDeps } from './outbox';
+import type { OutboxDeps, OutboxRecord } from './outbox';
 
 export interface RelayOptions extends OutboxDeps {
   readonly batchSize?: number;
@@ -48,19 +49,68 @@ export interface OutboxRelay {
   pollDelayMs(): number;
 }
 
+/**
+ * A claimed batch in TWO statements — `driver.enqueueMany`, then `store.markPublishedMany` — where
+ * the row loop below spends two per row; `RELAY_BATCH_SIZE` holds the measured figures. Publish,
+ * then mark, the row loop's order and for its reason.
+ *
+ * `false` hands the batch to the row loop: a store without `markPublishedMany`, or a batch that
+ * failed anywhere. The loop then publishes in order up to the row that fails and releases the rest, so the order
+ * guarantee and the poison row named in `jobs.outbox.publish-failed` are the loop's, unchanged.
+ * A batch that published before its mark failed is published again by the loop, by the same ids,
+ * which `SQL_ENQUEUE` answers `deduped` without a second row.
+ */
+async function publishBatch(deps: OutboxDeps, batch: readonly OutboxRecord[]): Promise<boolean> {
+  const { driver, store } = deps;
+  if (store.markPublishedMany === undefined) return false;
+  try {
+    await driver.enqueueMany(batch.map(publishRequest));
+    // One claim stamped every row of the batch, so the first row's token is the batch's.
+    const claimant = batch[0]?.claimedBy;
+    await store.markPublishedMany(
+      batch.map((record) => record.id),
+      nowMs(deps.clock),
+      claimant,
+    );
+    return true;
+  } catch (error) {
+    logger.warn('jobs.outbox.batch-fallback', {
+      rows: batch.length,
+      error: renderThrowable(error),
+    });
+    return false;
+  }
+}
+
+/**
+ * Rows one pass claims. 500, not the 100 it was: with the batch path a pass is three statements
+ * whatever its size, so the size is the throughput. 10,000 staged rows, three runs each (Postgres,
+ * 2026-11-03, a shared box under load): 100 gave 4,259–5,052 rows/s, 500 gave 8,564–9,505. What
+ * 500 costs, all measured or bounded:
+ *
+ * - lock hold: the longest statement of a pass was 45 ms (the insert, whose row locks end at its
+ *   autocommit); the claim's `skip locked` lock ends with its own statement.
+ * - statement size: half of `ENQUEUE_CHUNK`, the bind `enqueueMany` already sends from a request.
+ * - the lease: a batch pass took ~60 ms and the row loop about 1 s for 500 rows, both far inside
+ *   `DEFAULT_OUTBOX_CLAIM_LEASE_MS` (30 s), so no healthy pass loses its claim.
+ * - fairness: relays split the backlog by `skip locked`, as before; what grows is a DEAD relay's
+ *   stranded batch — 500 rows wait out its lease instead of 100, still in staged order.
+ */
+export const RELAY_BATCH_SIZE = 500;
+
 /**
  * At-least-once by construction: publish, THEN mark published. A crash between the two
  * re-publishes, which the idempotency key collapses — the opposite order would lose jobs.
  */
 export function outboxRelay(options: RelayOptions): OutboxRelay {
-  const batchSize = options.batchSize ?? 100;
+  const batchSize = options.batchSize ?? RELAY_BATCH_SIZE;
   const intervalMs = options.intervalMs ?? 200;
   // Refused, never clamped — `worker-options.ts` carries the reason. `setInterval(fn, NaN)` reads
   // the delay as 0 and `claim(NaN)` slices `(0, NaN)`: a relay that spins and publishes nothing.
   assert(
     Number.isSafeInteger(batchSize) && batchSize >= 1,
     `outboxRelay batchSize is ${String(batchSize)} — a batch is a whole number of staged rows, at least one`,
-    'pass a finite batchSize to outboxRelay(...), or omit it for the default 100',
+    `pass a finite batchSize to outboxRelay(...), or omit it for the default ${RELAY_BATCH_SIZE}`,
   );
   assert(
     Number.isFinite(intervalMs) && intervalMs >= 0,
@@ -97,23 +147,12 @@ export function outboxRelay(options: RelayOptions): OutboxRelay {
   const tick = async (): Promise<number> => {
     const batch = await options.store.claim(batchSize);
     let published = 0;
-    for (const record of batch) {
+    if (batch.length > 0 && (await publishBatch(options, batch))) published = batch.length;
+    for (const record of published > 0 ? [] : batch) {
       try {
-        await options.driver.enqueue({
-          // The ids the staging enqueue ANSWERED. Published under them, a repeat of this publish
-          // — a crash before the mark below — meets the job this one made rather than adding one.
-          id: record.id,
-          runId: record.runId,
-          name: record.job,
-          queue: record.queue,
-          input: record.input,
-          idempotencyKey: record.idempotencyKey,
-          maxAttempts: record.maxAttempts,
-          runAt: record.runAt,
-          ...(record.tenantId === undefined ? {} : { tenantId: record.tenantId }),
-          ...(record.traceparent === undefined ? {} : { traceparent: record.traceparent }),
-          ...(record.enqueuedBy === undefined ? {} : { enqueuedBy: record.enqueuedBy }),
-        });
+        // The ids the staging enqueue ANSWERED. Published under them, a repeat of this publish
+        // — a crash before the mark below — meets the job this one made rather than adding one.
+        await options.driver.enqueue(publishRequest(record));
         // The claim's own token goes back with the mark. Without it a relay whose lease lapsed
         // mid-stall retires a row the relay that reclaimed it has not published yet — the row is
         // gone and nothing publishes it.

package/src/outbox.ts

@@ -24,21 +24,20 @@
 // test and `x dev` must enqueue with nothing wired — but it is a fallback, not the guarantee.
 
 import type { Clock } from '@ultimat3/core';
-import {
-  currentSpanContext,
-  describeValue,
-  traceparent,
-  UltimateError,
-  uuidV7,
-} from '@ultimat3/core';
+import { uuidV7 } from '@ultimat3/core';
+import { refuseAbandoned } from '@ultimat3/db';
 import type { Tx } from '@ultimat3/entity';
 import { nowMs } from './clock';
 import type { EnqueueResult, JobDriver } from './driver';
-import { DEFAULT_QUEUE, jobDriver } from './driver';
+import { jobDriver } from './driver';
+import { ambientTraceparent, directRequest, namedRunId, stagedRecord } from './enqueue-record';
 import { signalEnqueued, signalStaged } from './enqueue-signal';
 import { DriverUnavailableError, OutboxNoTxError } from './errors';
 import type { JobHandle } from './job';
+import type { EnqueueManyOptions } from './job-enqueue-many';
+import { enqueueMany } from './job-enqueue-many';
 import { resolveClaimLeaseMs } from './outbox-lease';
+import { refuseEnqueueTenant } from './tenant';
 
 export interface OutboxRecord {
   /** The outbox row's id AND the id of the job its publish creates: allocated once, at stage. */
@@ -67,6 +66,11 @@ export interface OutboxRecord {
 export interface OutboxStore {
   /** Write inside `tx`. Nothing is visible to the relay until that tx commits. */
   stage(tx: Tx, record: OutboxRecord): Promise<void>;
+  /**
+   * Stage every record in ONE write, in order — `enqueueMany`'s chunk. OPTIONAL, like `release`:
+   * absent, the facade calls `stage` once per record, which is correct and slower.
+   */
+  stageMany?(tx: Tx, records: readonly OutboxRecord[]): Promise<void>;
   /** Called by the tx runner after COMMIT. */
   commit(tx: Tx): Promise<readonly OutboxRecord[]>;
   /** Called by the tx runner after ROLLBACK. Staged rows vanish with the transaction. */
@@ -88,6 +92,11 @@ export interface OutboxStore {
   release?(ids: readonly string[], claimant?: string): Promise<void>;
   /** `claimant` fences the same way, and here it is worse to miss: this retires the row. */
   markPublished(id: string, at: number, claimant?: string): Promise<void>;
+  /**
+   * `markPublished` for a whole published batch in one write, under the same fence. OPTIONAL: the
+   * relay publishes a batch through `JobDriver.enqueueMany` only when the store has this too.
+   */
+  markPublishedMany?(ids: readonly string[], at: number, claimant?: string): Promise<void>;
   pendingCount(): Promise<number>;
 }
 
@@ -154,6 +163,12 @@ export function memoryOutboxStore(options: MemoryOutboxStoreOptions = {}): Memor
       staged.set(key(tx), bucket);
       return Promise.resolve();
     },
+    stageMany(tx, records) {
+      const bucket = staged.get(key(tx)) ?? [];
+      bucket.push(...records);
+      staged.set(key(tx), bucket);
+      return Promise.resolve();
+    },
     commit(tx) {
       const bucket = staged.get(key(tx)) ?? [];
       staged.delete(key(tx));
@@ -196,6 +211,14 @@ export function memoryOutboxStore(options: MemoryOutboxStoreOptions = {}): Memor
       claims.delete(id);
       return Promise.resolve();
     },
+    markPublishedMany(ids, _at, claimant) {
+      for (const id of ids) {
+        if (!owns(id, claimant)) continue;
+        committed.delete(id);
+        claims.delete(id);
+      }
+      return Promise.resolve();
+    },
     pendingCount() {
       let count = 0;
       for (const record of committed.values()) {
@@ -228,43 +251,6 @@ export interface EnqueueOptions {
   readonly runId?: string;
 }
 
-/**
- * The W3C `traceparent` of the span this enqueue is happening inside, or `undefined` outside a
- * trace. This is the ONE place the link is minted: `docs/idea/04-jobs.md` promises a job trace
- * linked to the enqueuing request, and before this there was no field to carry the link, so a
- * checkout's `chargeCard` opened a fresh root two seconds later with nothing pointing back.
- *
- * A context recovered from a `Ctx` has an empty `spanId` (`currentSpanContext`), which renders as
- * an all-zero parent that every collector rejects — so that case carries no header rather than a
- * malformed one, and the job opens a root as it did before.
- */
-function ambientTraceparent(): string | undefined {
-  const context = currentSpanContext();
-  if (context === undefined || context.spanId === '') return undefined;
-  return traceparent(context);
-}
-
-/** What Postgres prints for a `uuid`, and so the only spelling both drivers store identically. */
-const RUN_ID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-
-/**
- * `EnqueueOptions.runId`, refused HERE when it is not a uuid — the one screen both enqueue paths
- * read. `run_id` is a `uuid` column: the memory driver took any string, Postgres raised a raw
- * `22P02`, and on the staged path that was the caller's whole transaction failing at the outbox
- * insert. Any version, lowercase: an uppercase one would come back from Postgres re-spelled.
- */
-function namedRunId(job: string, runId: unknown): string | undefined {
-  if (runId === undefined) return undefined;
-  if (typeof runId === 'string' && RUN_ID_SHAPE.test(runId)) return runId;
-  throw new UltimateError({
-    code: 'X_ID_INVALID',
-    // `describeValue`, never the value: what arrives here wrong is as often a key as a typo.
-    cause: `enqueue of job "${job}" was given runId ${describeValue(runId)}, and a run id is a lowercase uuid (8-4-4-4-12 hex) — the queue stores it in a uuid column`,
-    fix: "pass { runId: uuidV7() } to enqueue(), with import { uuidV7 } from '@ultimat3/core'",
-    meta: { job, option: 'runId' },
-  });
-}
-
 export interface OutboxDeps {
   readonly store: OutboxStore;
   readonly driver: JobDriver;
@@ -273,7 +259,13 @@ export interface OutboxDeps {
   readonly mode?: 'default' | 'required';
 }
 
-/** Stage a job inside `tx`. Returns the row that the relay will publish after commit. */
+/**
+ * Stage a job inside `tx`. Returns the row that the relay will publish after commit.
+ *
+ * The facade's staged arm, and NOT in `index.ts`: the refusals (`refuseAbandoned`, the concurrency
+ * key, `refuseEnqueueTenant`) are the facade's and precede this call, so a public spelling of it
+ * was a second enqueue path that staged rows the facade refuses. Exported for this package's tests.
+ */
 export async function enqueueInTx<I>(
   deps: OutboxDeps,
   tx: Tx,
@@ -282,24 +274,13 @@ export async function enqueueInTx<I>(
   options: EnqueueOptions = {},
 ): Promise<OutboxRecord> {
   const runId = namedRunId(handle.name, options.runId);
-  const at = nowMs(deps.clock);
-  const trace = options.traceparent ?? ambientTraceparent();
-  const record: OutboxRecord = {
+  const record = stagedRecord(handle, input, options, {
     id: uuidV7(),
     runId: runId ?? uuidV7(),
-    job: handle.name,
-    queue: options.queue ?? handle.queue ?? DEFAULT_QUEUE,
-    input,
     idempotencyKey: handle.idempotencyKeyFor(input),
-    maxAttempts: handle.retry.attempts,
-    runAt: options.runAt ?? at,
-    stagedAt: at,
-    ...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
-    // Stamped at STAGE time and not at publish time: the relay runs after commit, in its own
-    // timer, with no request span in scope — a trace read there would be nobody's.
-    ...(trace === undefined ? {} : { traceparent: trace }),
-    ...(options.enqueuedBy === undefined ? {} : { enqueuedBy: options.enqueuedBy }),
-  };
+    at: nowMs(deps.clock),
+    trace: options.traceparent ?? ambientTraceparent(),
+  });
   await deps.store.stage(tx, record);
   // Wakes a relay in THIS process that has backed off; a relay elsewhere polls on its own.
   signalStaged();
@@ -312,6 +293,12 @@ export interface JobsFacade {
    * a job, or a script — the transactional behaviour is the framework's problem, not yours.
    */
   enqueue<I>(handle: JobHandle<I>, input: I, options?: EnqueueOptions): Promise<EnqueueResult>;
+  /** Many of one job, one statement per chunk, answered in input order (`job-enqueue-many.ts`). */
+  enqueueMany<I>(
+    handle: JobHandle<I>,
+    inputs: readonly I[],
+    options?: EnqueueManyOptions,
+  ): Promise<readonly EnqueueResult[]>;
 }
 
 export function outboxJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefined): JobsFacade {
@@ -321,10 +308,15 @@ export function outboxJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefin
       input: I,
       options: EnqueueOptions = {},
     ): Promise<EnqueueResult> {
+      // A direct `driver.enqueue` is a write the transaction guard cannot see: a scope whose caller
+      // was already answered starts no job, on either path below.
+      refuseAbandoned();
       // Asked before anything is staged, and for its refusal alone: a `concurrency.key` that
       // answers an empty string is one lock shared by every run of the job, and the caller of
       // this enqueue is the only one who can still be told (`X_JOB_DECLARATION_INVALID`).
       handle.concurrencyKeyFor(input);
+      // A payload naming one org, enqueued for — or by an actor of — another (`tenant.ts`).
+      refuseEnqueueTenant(handle.name, handle.tenantFor(input), options.tenantId);
       const tx = options.outbox === false ? undefined : currentTx();
 
       if (tx === undefined) {
@@ -333,18 +325,14 @@ export function outboxJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefin
         }
         const runId = namedRunId(handle.name, options.runId);
         const trace = options.traceparent ?? ambientTraceparent();
-        const result = await deps.driver.enqueue({
-          name: handle.name,
-          queue: options.queue ?? handle.queue,
-          input,
-          idempotencyKey: handle.idempotencyKeyFor(input),
-          maxAttempts: handle.retry.attempts,
-          runAt: options.runAt ?? nowMs(deps.clock),
-          ...(runId === undefined ? {} : { runId }),
-          ...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
-          ...(trace === undefined ? {} : { traceparent: trace }),
-          ...(options.enqueuedBy === undefined ? {} : { enqueuedBy: options.enqueuedBy }),
-        });
+        const result = await deps.driver.enqueue(
+          directRequest(handle, input, options, {
+            idempotencyKey: handle.idempotencyKeyFor(input),
+            at: nowMs(deps.clock),
+            trace,
+            ...(runId === undefined ? {} : { runId }),
+          }),
+        );
         // A worker in this process that has backed off starts its next pass now.
         signalEnqueued(options.queue ?? handle.queue);
         return result;
@@ -357,6 +345,10 @@ export function outboxJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefin
       // LIVE job holds creates nothing, and these ids then name no row.
       return { id: record.id, runId: record.runId, deduped: false };
     },
+    enqueueMany<I>(handle: JobHandle<I>, inputs: readonly I[], options: EnqueueManyOptions = {}) {
+      const tx = options.outbox === false ? undefined : currentTx();
+      return enqueueMany(deps, tx, handle, inputs, options);
+    },
   };
 }
 

package/src/purge-entities.ts

@@ -0,0 +1,92 @@
+// Single responsibility: an entity's `retain` as a `PurgeTarget` — the batched, cross-tenant delete
+// of every row older than its window — and the record of which entities a `purge()` covers, which
+// is what `x verify` reads to refuse a retention promise nothing keeps (`X_ENTITY_RETAIN_UNSWEPT`).
+
+import { assert } from '@ultimat3/core';
+import {
+  CROSS_TENANT_SETTING,
+  identifier,
+  PURGE_SETTING,
+  setLocal,
+  sql,
+  withTransaction,
+} from '@ultimat3/db';
+import { type EntityCore, registeredEntities } from '@ultimat3/entity';
+import type { PurgeTarget } from './purge';
+import { type PurgeBatching, purgeBatching, purgeInBatches } from './purge-batches';
+
+/**
+ * The sweep of one `retain` entity. Each batch is its own transaction that names this table in
+ * `x.purge` — the one thing a history table's guard lets delete — and opens `x.cross`: retention is
+ * every tenant's, and under forced row security an unset tenant would match no row at all.
+ */
+export function retainTarget(entity: EntityCore, options: PurgeBatching = {}): PurgeTarget {
+  const retain = entity.$retain;
+  assert(
+    retain !== null,
+    `retainTarget(${entity.$name}) — the entity declares no retain, so nothing says which rows expire`,
+    `add retain: { after: '90d', on: 'createdAt' } to entity('${entity.$name}'), then x db gen "retention"`,
+  );
+  const bounds = purgeBatching(`retainTarget(${entity.$name})`, options);
+  const table = identifier(entity.$table);
+  const column = identifier(retain.column);
+  return {
+    name: entity.$table,
+    purgeExpired: (nowMs) => {
+      const cutoff = new Date(nowMs - retain.afterMs);
+      return purgeInBatches(
+        (size) =>
+          withTransaction(async (tx) => {
+            await setLocal(tx, { [PURGE_SETTING]: entity.$table, [CROSS_TENANT_SETTING]: 'on' });
+            const row = await tx.one<{ removed: number | string }>(
+              sql`with gone as (delete from ${table} where ctid in (select ctid from ${table} where ${column} < ${cutoff} limit ${size}) returning 1) select count(*) as removed from gone`,
+            );
+            return Number(row?.removed ?? 0);
+          }),
+        bounds,
+      );
+    },
+  };
+}
+
+/** Every registered entity that declares `retain`, history tables included, by name. */
+export function retainedEntities(): readonly EntityCore[] {
+  return registeredEntities().flatMap((entry) =>
+    entry.core !== undefined && entry.core.$retain !== null ? [entry.core] : [],
+  );
+}
+
+let coversAll = false;
+const covered = new Set<string>();
+
+/** What `purge({ entities })` declares it sweeps: `'declared'`, or the entities it names. */
+export type PurgeEntities = 'declared' | readonly EntityCore[];
+
+/** Recorded at `purge()`, read by `x verify`. */
+export function recordPurgeCoverage(entities: PurgeEntities | undefined): void {
+  if (entities === undefined) return;
+  if (entities === 'declared') coversAll = true;
+  else for (const entity of entities) covered.add(entity.$name);
+}
+
+/** The retain entities no `purge()` covers, sorted. */
+export function unsweptEntities(): readonly string[] {
+  if (coversAll) return [];
+  return retainedEntities()
+    .map((entity) => entity.$name)
+    .filter((name) => !covered.has(name))
+    .sort();
+}
+
+/** The targets `entities` resolves to, read at each attempt as the definition's `targets` is. */
+export function entityTargets(entities: PurgeEntities | undefined): readonly PurgeTarget[] {
+  if (entities === undefined) return [];
+  const list = entities === 'declared' ? retainedEntities() : entities;
+  return list.map((entity) => retainTarget(entity));
+}
+
+/** Test seam: forget what every `purge()` declared. */
+export function resetPurgeCoverage(): void {
+  coversAll = false;
+  covered.clear();
+}

package/src/purge.ts

@@ -18,6 +18,7 @@ import type { DurationInput } from './clock';
 import { nowMs } from './clock';
 import type { JobHandle } from './job';
 import { job } from './job';
+import { entityTargets, type PurgeEntities, recordPurgeCoverage } from './purge-entities';
 import type { RetryPolicy } from './retry';
 import { DEFAULT_RETRY } from './retry';
 
@@ -83,7 +84,13 @@ export interface PurgeDefinition {
    * does not exist until later. An empty list is a pass that removes nothing, which is the honest
    * answer for a process whose boot has already stopped.
    */
-  targets(): readonly PurgeTarget[];
+  targets?(): readonly PurgeTarget[];
+  /**
+   * Entities whose `retain` this sweep keeps, beside `targets`: `'declared'` is every registered
+   * entity declaring one, history tables included (`purge-entities.ts`). Read per attempt, as
+   * `targets` is. What `x verify` reads to refuse a `retain` no purge covers.
+   */
+  readonly entities?: PurgeEntities;
   /**
    * The clock every target is measured against. Defaults to the system clock, and it must be the
    * SAME clock the stores write their instants from — see `PurgeTarget.purgeExpired`.
@@ -100,6 +107,7 @@ export const DEFAULT_PURGE_CRON = '23 * * * *';
 
 export function purge(definition: PurgeDefinition): JobHandle<PurgeInput> {
   const clock = definition.clock;
+  recordPurgeCoverage(definition.entities);
 
   return job<PurgeInput>({
     ...(definition.name === undefined ? {} : { name: definition.name }),
@@ -119,7 +127,7 @@ export function purge(definition: PurgeDefinition): JobHandle<PurgeInput> {
       // against instants a round trip apart, which is the same class of mismatch as reading the
       // server's clock — smaller, and just as unnecessary.
       const at = nowMs(clock);
-      const targets = definition.targets();
+      const targets = [...(definition.targets?.() ?? []), ...entityTargets(definition.entities)];
       const names = new Set(targets.map((target) => target.name));
       // Refused before the first delete, not discovered at the second step: `step.run` raises
       // `X_STEP_DUPLICATE` on the repeat, which dead-letters a sweep AFTER it has already emptied

package/src/queue-wake.ts

@@ -49,7 +49,7 @@ const CHANNELS = [JOBS_WAKE_CHANNEL, OUTBOX_WAKE_CHANNEL] as const;
 type Channel = (typeof CHANNELS)[number];
 
 const UNVERIFIED_FIX =
-  'point DATABASE_URL at Postgres itself or at a SESSION-pooling proxy (PgBouncer pool_mode = session) for the worker role — a transaction-pooling proxy delivers no notification. Nothing is lost meanwhile: jobs start on the poll, at most idlePollMaxMs late';
+  'point DATABASE_URL at Postgres itself or at a SESSION-pooling proxy (PgBouncer pool_mode = session) for the worker role, and unset DATABASE_POOLER for that role — a transaction-pooling proxy delivers no notification. Nothing is lost meanwhile: jobs start on the poll, at most idlePollMaxMs late';
 
 const armTimer = (run: () => void, delayMs: number): (() => void) => {
   const timer = setTimeout(run, delayMs);

package/src/refresh-view.ts

@@ -0,0 +1,76 @@
+// `refreshView()` — recompute a materialized view, declared as a `job` and never as a ninth
+// primitive. A view over an arbitrary join is refreshed WHOLE; a time window over append-mostly
+// rows is `rollup()`'s, which recomputes only recent buckets. The schedule is the app's `task`.
+
+import { db, identifier, sql } from '@ultimat3/db';
+import type { EntityCore } from '@ultimat3/entity';
+import { t } from '@ultimat3/schema';
+import type { DurationInput } from './clock';
+import type { JobHandle } from './job';
+import { job } from './job';
+import { DEFAULT_RETRY, type RetryPolicy } from './retry';
+import { RefreshViewInvalidError } from './rollup-errors';
+
+export interface RefreshViewDefinition {
+  readonly name: string;
+  /** An entity declared `view: { sql, materialized: true }`. */
+  readonly view: EntityCore;
+  /**
+   * `refresh … concurrently`: readers keep the old rows while the new ones are computed, at the
+   * price of a unique index on the view (`.unique()` on a column), refused here without one.
+   */
+  readonly concurrently?: boolean;
+  readonly queue?: string;
+  readonly retry?: RetryPolicy;
+  readonly timeout?: DurationInput;
+}
+
+/** What one run reports: the view, and whether readers were blocked while it ran. */
+export interface RefreshViewReport {
+  readonly view: string;
+  readonly concurrently: boolean;
+}
+
+const assertRefreshable = (definition: RefreshViewDefinition): boolean => {
+  const { name, view } = definition;
+  if (view.$viewQuery?.materialized !== true) {
+    throw new RefreshViewInvalidError({
+      job: name,
+      problem: `names ${view.$name}, which is ${view.$viewQuery === null ? 'a table' : 'a plain view, recomputed on every read'} — only a materialized view stores rows to refresh`,
+      fix: `entity('${view.$name}', { view: { sql, materialized: true }, columns })   # then x db gen`,
+    });
+  }
+  const concurrently = definition.concurrently === true;
+  if (concurrently && !view.$indexes.some((index) => index.unique && index.where === undefined)) {
+    throw new RefreshViewInvalidError({
+      job: name,
+      problem: `refreshes ${view.$name} concurrently, and Postgres needs a unique index on the view to do that`,
+      fix: `entity('${view.$name}', { view, columns: { <key>: uuid().unique(), … } })   # or refreshView({ name: '${name}', view, concurrently: false })`,
+    });
+  }
+  return concurrently;
+};
+
+export function refreshView(definition: RefreshViewDefinition): JobHandle<Record<string, never>> {
+  const concurrently = assertRefreshable(definition);
+  const target = identifier(definition.view.$table);
+  const statement = concurrently
+    ? sql`refresh materialized view concurrently ${target}`
+    : sql`refresh materialized view ${target}`;
+  return job<Record<string, never>, RefreshViewReport>({
+    name: definition.name,
+    input: t.object({}),
+    // One refresh at a time: a second enqueue while one runs would compute the same rows again.
+    idempotencyKey: () => `refresh-view:${definition.name}`,
+    // A materialized view spans every tenant's rows; the read path scopes them, not the refresh.
+    tenant: 'none',
+    retry: definition.retry ?? DEFAULT_RETRY,
+    ...(definition.queue === undefined ? {} : { queue: definition.queue }),
+    ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }),
+    run: ({ step }) =>
+      step.run('refresh', async () => {
+        await db().execute(statement);
+        return { view: definition.view.$name, concurrently };
+      }),
+  });
+}