pipework 0.251.0 → 0.252.1

package/src/infra/credits/handle.ts

@@ -0,0 +1,706 @@
+import { sql } from '../../data/db/sql.js'
+import { pipe } from '../../data/db/db.js'
+import type { DB } from '../../data/db/index.js'
+import { requireContext, getContext, runInContext } from '../../request/context/store.js'
+import { writeInfraAudit } from '../../data/write/audit/infra-audit.js'
+import { inTenant } from '../../auth/tenant/in-tenant.js'
+import { bindTransaction } from '../../request/context/guard.js'
+import type { Flow } from '../../request/context/types.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { recordFault, faultMessage } from '../alerts/faults.js'
+import { ValidationError } from '../../core/errors/index.js'
+
+export interface CreditsConfig {
+  /**
+   * The low-balance line for tenants that have not set their own (`setLowBalanceLine`).
+   * When available credits fall from at-or-above a tenant's line to below it, the crossing
+   * fires once: `onLowBalanceCrossed`, `onLowBalance` and a `credits low balance` warning.
+   */
+  readonly lowBalanceThreshold?: number
+  /** Fires after the operation's transaction body, once per crossing; errors are logged and dropped. */
+  readonly onLowBalance?: (event: { tenantId: string; available: number }) => void
+  /**
+   * Awaited INSIDE the transaction of the operation that crossed the line (reserve, settle, expire,
+   * setLowBalanceLine), after its ledger write, in a Flow whose tenant is the operation's tenant and
+   * where `pipe()` is that same transaction: what it writes commits or rolls back with the operation.
+   * If it throws, the operation fails and rolls back.
+   */
+  readonly onLowBalanceCrossed?: (event: LowBalanceCrossing) => void | Promise<void>
+  /** Called when a `reserve` is refused for lack of credits. */
+  readonly onInsufficient?: (event: { tenantId: string; jobId: string; requested: number; available: number }) => void
+}
+
+export interface LowBalanceCrossing {
+  readonly tenantId: string
+  readonly available: number
+  /** The line that was crossed. */
+  readonly line: number
+}
+
+/** A tenant's low-balance line and whether its balance is under it. */
+export interface LowBalanceState {
+  /** The effective line; `null` when there is none. */
+  readonly line: number | null
+  /** `'tenant'`: set by the tenant; `'default'`: the config's `lowBalanceThreshold`; `'none'`: no line. */
+  readonly source: 'tenant' | 'default' | 'none'
+  readonly available: number
+  /** Available is under the line; false when there is no line. */
+  readonly below: boolean
+}
+
+export interface CreditGrant {
+  readonly id: string
+  readonly tenantId: string
+  readonly kind: string
+  readonly amount: number
+  readonly remaining: number
+  readonly grantedAt: Date
+  /** `null` = never expires. */
+  readonly expiresAt: Date | null
+  readonly sourceRef: string | null
+  readonly metadata: unknown
+}
+
+export interface GrantOptions {
+  /** Positive integer, in the app's own unit. */
+  readonly amount: number
+  /** `'allocation'`, `'pack'`, or any string the app uses. */
+  readonly kind: string
+  readonly expiresAt?: Date
+  /** Idempotency key for the grant, e.g. a payment event id: the same ref again credits nothing. */
+  readonly sourceRef?: string
+  readonly metadata?: unknown
+}
+
+export interface CreditReservation {
+  readonly id: string
+  readonly tenantId: string
+  readonly jobId: string
+  readonly amount: number
+  readonly status: 'held' | 'settled' | 'released'
+  readonly settledAmount: number | null
+  /** Units a settle used beyond what the grants could cover. */
+  readonly overdraft: number
+  readonly createdAt: Date
+  readonly settledAt: Date | null
+}
+
+export type GrantResult = { readonly grant: CreditGrant; readonly created: boolean }
+
+export type ReserveResult =
+  | { readonly ok: true; readonly reservation: CreditReservation }
+  | { readonly ok: false; readonly reason: 'insufficient'; readonly available: number; readonly requested: number }
+
+export interface CreditBalance {
+  /** Sum of `remaining` over grants that have not expired (reserved credits are already drawn out of it). */
+  readonly available: number
+  /** Sum of the amounts of reservations still held. */
+  readonly held: number
+  readonly grants: readonly { id: string; kind: string; remaining: number; expiresAt: Date | null }[]
+}
+
+export interface CreditLedgerEntry {
+  readonly id: string
+  readonly tenantId: string
+  readonly at: Date
+  readonly kind: 'grant' | 'reserve' | 'settle' | 'release' | 'expire'
+  /** Signed: what the entry did to the available balance. */
+  readonly amount: number
+  readonly grantId: string | null
+  readonly reservationId: string | null
+  readonly jobId: string | null
+  readonly availableAfter: number
+}
+
+export interface HistoryOptions {
+  readonly limit?: number
+  /** The `next` of a previous page. */
+  readonly before?: string
+}
+
+export interface HistoryPage {
+  readonly entries: CreditLedgerEntry[]
+  /** Pass as `before` for the next (older) page; `null` at the end. */
+  readonly next: string | null
+}
+
+export interface Credits {
+  grant(options: GrantOptions): Promise<GrantResult>
+  grantFor(tenantId: string, options: GrantOptions): Promise<GrantResult>
+  /**
+   * Holds `amount` for a job, drawn soonest-expiring first. A job id that already has a
+   * reservation returns it unchanged, whatever amount is asked this time.
+   */
+  reserve(options: { jobId: string; amount: number }): Promise<ReserveResult>
+  reserveFor(tenantId: string, options: { jobId: string; amount: number }): Promise<ReserveResult>
+  /**
+   * Records the actual usage of a reserved job. Less than reserved refunds the difference to the
+   * grants it came from (latest-expiring first; a refund to an expired grant is lost). More draws
+   * the excess and records what could not be covered as `overdraft`; it never fails for lack of
+   * balance. The same amount again is a no-op; a different amount, a released job or an unknown job throws.
+   */
+  settle(options: { jobId: string; amount: number }): Promise<CreditReservation>
+  settleFor(tenantId: string, options: { jobId: string; amount: number }): Promise<CreditReservation>
+  /** Gives back everything a held reservation drew. No reservation: `{ released: false, reservation: null }`; already released: `released: false`. A settled job throws. */
+  release(options: { jobId: string }): Promise<{ released: boolean; reservation: CreditReservation | null }>
+  releaseFor(tenantId: string, options: { jobId: string }): Promise<{ released: boolean; reservation: CreditReservation | null }>
+  /** The tenant's reservations still held, oldest first. */
+  held(): Promise<CreditReservation[]>
+  /** The given tenant's reservations still held, oldest first. */
+  heldFor(tenantId: string): Promise<CreditReservation[]>
+  balance(): Promise<CreditBalance>
+  balanceFor(tenantId: string): Promise<CreditBalance>
+  /** Ledger entries newest first. */
+  history(options?: HistoryOptions): Promise<HistoryPage>
+  historyFor(tenantId: string, options?: HistoryOptions): Promise<HistoryPage>
+  /** Writes one `expire` entry per grant past its expiry that still has credits, and zeroes it. For a cron; `balance` is right without it. Returns the number of grants expired. */
+  expire(): Promise<number>
+  expireFor(tenantId: string): Promise<number>
+  /**
+   * Sets the tenant's own low-balance line, or `null` to go back to the config's `lowBalanceThreshold`.
+   * Takes effect for the next operation. A change that puts the current balance under the new line
+   * (it was at-or-above the old line, or there was none) is a crossing and fires exactly as an
+   * operation's does, inside this call's transaction. Audited as `CreditAccount` `set_low_balance_line`.
+   * Throws ValidationError unless the line is a non-negative safe integer or null.
+   */
+  setLowBalanceLine(line: number | null): Promise<LowBalanceState>
+  setLowBalanceLineFor(tenantId: string, line: number | null): Promise<LowBalanceState>
+  /** The tenant's line, where it comes from, its available balance and whether that is under the line. Read-only. */
+  lowBalance(): Promise<LowBalanceState>
+  lowBalanceFor(tenantId: string): Promise<LowBalanceState>
+}
+
+const DEFAULT_HISTORY_LIMIT = 50
+const MAX_HISTORY_LIMIT = 500
+
+function toDate(value: unknown): Date {
+  if (value instanceof Date) return value
+  const text = String(value)
+  return new Date(/(Z|[+-]\d\d(:?\d\d)?)$/.test(text) ? text : `${text.replace(' ', 'T')}Z`)
+}
+
+function toDateOrNull(value: unknown): Date | null {
+  return value === null || value === undefined ? null : toDate(value)
+}
+
+function num(value: unknown): number {
+  return Number(value)
+}
+
+function numOrNull(value: unknown): number | null {
+  return value === null || value === undefined ? null : Number(value)
+}
+
+function rowToGrant(row: Record<string, unknown>): CreditGrant {
+  return {
+    id: row['id'] as string,
+    tenantId: row['tenant_id'] as string,
+    kind: row['kind'] as string,
+    amount: num(row['amount']),
+    remaining: num(row['remaining']),
+    grantedAt: toDate(row['granted_at']),
+    expiresAt: toDateOrNull(row['expires_at']),
+    sourceRef: (row['source_ref'] as string | null) ?? null,
+    metadata: row['metadata'] ?? null,
+  }
+}
+
+function rowToReservation(row: Record<string, unknown>): CreditReservation {
+  return {
+    id: row['id'] as string,
+    tenantId: row['tenant_id'] as string,
+    jobId: row['job_id'] as string,
+    amount: num(row['amount']),
+    status: row['status'] as CreditReservation['status'],
+    settledAmount: numOrNull(row['settled_amount']),
+    overdraft: num(row['overdraft']),
+    createdAt: toDate(row['created_at']),
+    settledAt: toDateOrNull(row['settled_at']),
+  }
+}
+
+function rowToEntry(row: Record<string, unknown>): CreditLedgerEntry {
+  return {
+    id: row['id'] as string,
+    tenantId: row['tenant_id'] as string,
+    at: toDate(row['at']),
+    kind: row['kind'] as CreditLedgerEntry['kind'],
+    amount: num(row['amount']),
+    grantId: (row['grant_id'] as string | null) ?? null,
+    reservationId: (row['reservation_id'] as string | null) ?? null,
+    jobId: (row['job_id'] as string | null) ?? null,
+    availableAfter: num(row['available_after']),
+  }
+}
+
+function requireUnits(name: string, value: number, min: 0 | 1): void {
+  if (!Number.isSafeInteger(value) || value < min) {
+    const detail = min === 1 ? 'must be a positive integer' : 'must be a non-negative integer'
+    throw new ValidationError({ [name]: [detail] }, `Credits ${name} ${detail}.`)
+  }
+}
+
+function requireJobId(jobId: string): void {
+  if (typeof jobId !== 'string' || jobId === '') {
+    throw new ValidationError({ jobId: ['must be a non-empty string'] }, 'Credits jobId must be a non-empty string.')
+  }
+}
+
+const LIVE = sql`remaining > 0 AND (expires_at IS NULL OR expires_at > now())`
+
+interface Measured<T> {
+  readonly value: T
+  /** The line this operation crossed, if it did. */
+  readonly crossed?: { line: number; available: number }
+  readonly insufficient?: { jobId: string; requested: number; available: number }
+}
+
+export function createCredits(config: CreditsConfig = {}): Credits {
+  const threshold = config.lowBalanceThreshold
+  if (threshold !== undefined && (!Number.isSafeInteger(threshold) || threshold < 0)) {
+    throw new Error('[pipework] credits lowBalanceThreshold must be a non-negative integer.\n')
+  }
+
+  function callback(name: string, fn: () => void): void {
+    try {
+      fn()
+    } catch (err) {
+      getBaseLogger().error({ err }, `credits ${name} callback threw`)
+      void recordFault('credits-callback', `credits ${name} callback threw: ${faultMessage(err)}`, { callback: name })
+    }
+  }
+
+  // Runs `fn` in a transaction for the tenant: the Flow's own (joining the
+  // request's transaction) or, for the `...For` forms, an explicit one.
+  type InFlow = <R>(body: () => Promise<R>) => Promise<R>
+
+  async function run<T>(explicit: string | null, fn: (tx: DB, tenantId: string, inFlow: InFlow) => Promise<T>): Promise<T> {
+    if (explicit !== null) {
+      requireTenantId(explicit)
+      const flow = requireContext()
+      return inTenant(flow, explicit, tx => fn(tx, explicit, body => runForTenant(flow, explicit, tx, body)))
+    }
+    const flow = requireContext()
+    if (flow.tenant === null) {
+      throw new Error(
+        '[pipework] This credits method needs a tenant in the Flow.\n\n' +
+        '  Call it from an authenticated tenant route, or use the ...For(tenantId, ...) form\n' +
+        '  (grantFor, reserveFor, settleFor, ...) from a webhook or a job with no tenant.\n',
+      )
+    }
+    const tenantId = flow.tenant
+    // pipe.transaction already runs its body in a child Flow with the transaction bound.
+    return pipe.transaction((tx: DB) => fn(tx, tenantId, body => body()))
+  }
+
+  // The `...For` transaction is not bound into the Flow, and the Flow's tenant is not the
+  // explicit one: run `body` in a child Flow that is both, as pipe.transaction does.
+  function runForTenant<R>(flow: Flow, tenantId: string, tx: DB, body: () => Promise<R>): Promise<R> {
+    const dbName = flow.instance.config.defaultDatabaseName()
+    const child: Flow = { ...flow, tenant: tenantId, transactions: new Map(flow.transactions) }
+    child.transactions.set(dbName, bindTransaction(child, dbName, tx))
+    return runInContext(child, body)
+  }
+
+  function requireTenantId(tenantId: string): void {
+    if (typeof tenantId !== 'string' || tenantId === '') {
+      throw new ValidationError({ tenantId: ['must be a non-empty string'] }, 'Credits tenantId must be a non-empty string.')
+    }
+  }
+
+  // Every mutating operation takes the tenant's lock first, so operations on one
+  // tenant's credits run one after another; the grant rows are also locked FOR UPDATE.
+  async function lockTenant(tx: DB, tenantId: string): Promise<void> {
+    await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${`pipework.credits:${tenantId}`}, 0))`)
+  }
+
+  async function availableOf(tx: DB, tenantId: string): Promise<number> {
+    const rows = await tx.execute(sql`
+      SELECT COALESCE(SUM(remaining), 0) AS n FROM credit_grant WHERE tenant_id = ${tenantId} AND ${LIVE}
+    `)
+    return num(rows[0]!['n'])
+  }
+
+  // The tenant's effective line, read in the operation's own transaction.
+  async function lineOf(tx: DB, tenantId: string): Promise<{ line: number | null; source: LowBalanceState['source']; stored: number | null }> {
+    const rows = await tx.execute(sql`SELECT low_balance_line AS line FROM credit_account WHERE tenant_id = ${tenantId}`)
+    const stored = rows.length === 0 ? null : numOrNull(rows[0]!['line'])
+    if (stored !== null) return { line: stored, source: 'tenant', stored }
+    return threshold === undefined ? { line: null, source: 'none', stored } : { line: threshold, source: 'default', stored }
+  }
+
+  // Applies the crossing rule to a balance change measured in this transaction; on a crossing
+  // awaits `onLowBalanceCrossed` in the tenant's Flow, so its error rolls the operation back.
+  async function cross<T>(tx: DB, tenantId: string, inFlow: InFlow, value: T, before: number, after: number): Promise<Measured<T>> {
+    if (after >= before) return { value }
+    const { line } = await lineOf(tx, tenantId)
+    if (line === null || before < line || after >= line) return { value }
+    const crossed = { line, available: after }
+    const fn = config.onLowBalanceCrossed
+    if (fn !== undefined) await inFlow(async () => { await fn({ tenantId, available: after, line }) })
+    return { value, crossed }
+  }
+
+  async function writeLedger(tx: DB, tenantId: string, entry: {
+    kind: CreditLedgerEntry['kind']; amount: number; grantId?: string | null; reservationId?: string | null; jobId?: string | null
+  }): Promise<void> {
+    const availableAfter = await availableOf(tx, tenantId)
+    const written = await tx.execute(sql`
+      INSERT INTO credit_ledger (tenant_id, at, kind, amount, grant_id, reservation_id, job_id, available_after)
+      VALUES (${tenantId}, clock_timestamp(), ${entry.kind}, ${entry.amount}, ${entry.grantId ?? null},
+        ${entry.reservationId ?? null}, ${entry.jobId ?? null}, ${availableAfter})
+      RETURNING id
+    `)
+    const flow = getContext()
+    if (flow === undefined) return
+    await writeInfraAudit(flow, tx, {
+      tenantId, entity: 'CreditLedger', verb: entry.kind, entityId: written[0]!['id'] as string,
+      after: {
+        kind: entry.kind, amount: entry.amount, jobId: entry.jobId ?? null, grantId: entry.grantId ?? null,
+        reservationId: entry.reservationId ?? null, availableAfter,
+      },
+    })
+  }
+
+  // Draws up to `need` from live grants, soonest-expiring first; returns what it drew.
+  async function drawFrom(tx: DB, tenantId: string, reservationId: string, need: number, firstSeq: number): Promise<number> {
+    const grants = await tx.execute(sql`
+      SELECT id, remaining FROM credit_grant WHERE tenant_id = ${tenantId} AND ${LIVE}
+      ORDER BY expires_at ASC NULLS LAST, granted_at, id FOR UPDATE
+    `)
+    let left = need
+    let seq = firstSeq
+    for (const grant of grants) {
+      if (left === 0) break
+      const take = Math.min(num(grant['remaining']), left)
+      await tx.execute(sql`UPDATE credit_grant SET remaining = remaining - ${take} WHERE id = ${grant['id'] as string}`)
+      await tx.execute(sql`
+        INSERT INTO credit_draw (tenant_id, reservation_id, grant_id, amount, seq)
+        VALUES (${tenantId}, ${reservationId}, ${grant['id'] as string}, ${take}, ${seq})
+      `)
+      left -= take
+      seq += 1
+    }
+    return need - left
+  }
+
+  // Gives back up to `amount` of a reservation's draws, latest draw first, to grants
+  // that have not expired; returns what reached a grant.
+  async function refund(tx: DB, tenantId: string, reservationId: string, amount: number): Promise<number> {
+    const draws = await tx.execute(sql`
+      SELECT id, grant_id, amount FROM credit_draw
+      WHERE tenant_id = ${tenantId} AND reservation_id = ${reservationId} AND amount > 0
+      ORDER BY seq DESC FOR UPDATE
+    `)
+    let left = amount
+    let refunded = 0
+    for (const draw of draws) {
+      if (left === 0) break
+      const take = Math.min(num(draw['amount']), left)
+      await tx.execute(sql`UPDATE credit_draw SET amount = amount - ${take} WHERE id = ${draw['id'] as string}`)
+      const back = await tx.execute(sql`
+        UPDATE credit_grant SET remaining = remaining + ${take}
+        WHERE id = ${draw['grant_id'] as string} AND (expires_at IS NULL OR expires_at > now())
+        RETURNING id
+      `)
+      if (back.length > 0) refunded += take
+      left -= take
+    }
+    return refunded
+  }
+
+  async function findReservation(tx: DB, tenantId: string, jobId: string, lock: boolean): Promise<CreditReservation | null> {
+    const rows = await tx.execute(lock
+      ? sql`SELECT * FROM credit_reservation WHERE tenant_id = ${tenantId} AND job_id = ${jobId} FOR UPDATE`
+      : sql`SELECT * FROM credit_reservation WHERE tenant_id = ${tenantId} AND job_id = ${jobId}`)
+    return rows.length === 0 ? null : rowToReservation(rows[0]!)
+  }
+
+  // Calls the callbacks once the operation's transaction body has finished.
+  function signal<T>(tenantId: string, measured: Measured<T>): T {
+    if (measured.insufficient !== undefined && config.onInsufficient !== undefined) {
+      const event = { tenantId, ...measured.insufficient }
+      const fn = config.onInsufficient
+      callback('onInsufficient', () => fn(event))
+    }
+    if (measured.crossed !== undefined) {
+      const available = measured.crossed.available
+      getBaseLogger().warn({ event: 'credits low balance', tenantId, available }, 'credits low balance')
+      const fn = config.onLowBalance
+      if (fn !== undefined) callback('onLowBalance', () => fn({ tenantId, available }))
+    }
+    return measured.value
+  }
+
+  async function doGrant(explicit: string | null, options: GrantOptions): Promise<GrantResult> {
+    requireUnits('amount', options.amount, 1)
+    if (typeof options.kind !== 'string' || options.kind === '') {
+      throw new ValidationError({ kind: ['must be a non-empty string'] }, 'Credits grant kind must be a non-empty string.')
+    }
+    if (options.sourceRef !== undefined && options.sourceRef === '') {
+      throw new ValidationError({ sourceRef: ['must not be empty'] }, 'Credits grant sourceRef must not be empty.')
+    }
+    return run(explicit, async (tx, tenantId) => {
+      await lockTenant(tx, tenantId)
+      if (options.sourceRef !== undefined) {
+        const existing = await tx.execute(sql`
+          SELECT * FROM credit_grant WHERE tenant_id = ${tenantId} AND source_ref = ${options.sourceRef}
+        `)
+        if (existing.length > 0) return { grant: rowToGrant(existing[0]!), created: false }
+      }
+      const metadata = options.metadata === undefined ? null : JSON.stringify(options.metadata)
+      const rows = await tx.execute(sql`
+        INSERT INTO credit_grant (tenant_id, kind, amount, remaining, granted_at, expires_at, source_ref, metadata)
+        VALUES (${tenantId}, ${options.kind}, ${options.amount}, ${options.amount}, now(),
+          ${options.expiresAt?.toISOString() ?? null}, ${options.sourceRef ?? null},
+          ${metadata === null ? sql`NULL` : sql`${metadata}::jsonb`})
+        RETURNING *
+      `)
+      const grant = rowToGrant(rows[0]!)
+      await writeLedger(tx, tenantId, { kind: 'grant', amount: options.amount, grantId: grant.id })
+      return { grant, created: true }
+    })
+  }
+
+  async function doReserve(explicit: string | null, options: { jobId: string; amount: number }): Promise<ReserveResult> {
+    requireJobId(options.jobId)
+    requireUnits('amount', options.amount, 1)
+    const done = await run(explicit, async (tx, tenantId, inFlow): Promise<{ tenantId: string; measured: Measured<ReserveResult> }> => {
+      await lockTenant(tx, tenantId)
+      const existing = await findReservation(tx, tenantId, options.jobId, false)
+      if (existing !== null) {
+        return { tenantId, measured: { value: { ok: true, reservation: existing } } }
+      }
+      const before = await availableOf(tx, tenantId)
+      if (before < options.amount) {
+        return {
+          tenantId,
+          measured: {
+            value: { ok: false, reason: 'insufficient', available: before, requested: options.amount },
+            insufficient: { jobId: options.jobId, requested: options.amount, available: before },
+          },
+        }
+      }
+      const inserted = await tx.execute(sql`
+        INSERT INTO credit_reservation (tenant_id, job_id, amount, status)
+        VALUES (${tenantId}, ${options.jobId}, ${options.amount}, 'held')
+        ON CONFLICT (tenant_id, job_id) DO NOTHING
+        RETURNING *
+      `)
+      if (inserted.length === 0) {
+        const winner = (await findReservation(tx, tenantId, options.jobId, false))!
+        return { tenantId, measured: { value: { ok: true, reservation: winner } } }
+      }
+      const reservation = rowToReservation(inserted[0]!)
+      await drawFrom(tx, tenantId, reservation.id, options.amount, 1)
+      await writeLedger(tx, tenantId, { kind: 'reserve', amount: -options.amount, reservationId: reservation.id, jobId: options.jobId })
+      return { tenantId, measured: await cross<ReserveResult>(tx, tenantId, inFlow, { ok: true, reservation }, before, before - options.amount) }
+    })
+    return signal(done.tenantId, done.measured)
+  }
+
+  async function doSettle(explicit: string | null, options: { jobId: string; amount: number }): Promise<CreditReservation> {
+    requireJobId(options.jobId)
+    requireUnits('amount', options.amount, 0)
+    const done = await run(explicit, async (tx, tenantId, inFlow) => {
+      await lockTenant(tx, tenantId)
+      const reservation = await findReservation(tx, tenantId, options.jobId, true)
+      if (reservation === null) {
+        throw new Error(`[pipework] credits.settle: no reservation for job "${options.jobId}".\n\n  Call reserve({ jobId, amount }) before the job, with the same jobId.\n`)
+      }
+      if (reservation.status === 'released') {
+        throw new Error(`[pipework] credits.settle: the reservation for job "${options.jobId}" was released.\n`)
+      }
+      if (reservation.status === 'settled') {
+        if (reservation.settledAmount === options.amount) {
+          return { tenantId, measured: { value: reservation } as Measured<CreditReservation> }
+        }
+        throw new Error(
+          `[pipework] credits.settle: job "${options.jobId}" was already settled at ${reservation.settledAmount}, ` +
+          `not ${options.amount}.\n`,
+        )
+      }
+      const before = await availableOf(tx, tenantId)
+      const delta = options.amount - reservation.amount
+      let change = 0
+      let overdraft = 0
+      if (delta < 0) {
+        change = await refund(tx, tenantId, reservation.id, -delta)
+      } else if (delta > 0) {
+        const seqRows = await tx.execute(sql`SELECT COALESCE(MAX(seq), 0) AS n FROM credit_draw WHERE reservation_id = ${reservation.id}`)
+        const drawn = await drawFrom(tx, tenantId, reservation.id, delta, num(seqRows[0]!['n']) + 1)
+        change = -drawn
+        overdraft = delta - drawn
+      }
+      const rows = await tx.execute(sql`
+        UPDATE credit_reservation
+        SET status = 'settled', settled_amount = ${options.amount}, overdraft = ${overdraft}, settled_at = now()
+        WHERE id = ${reservation.id}
+        RETURNING *
+      `)
+      await writeLedger(tx, tenantId, { kind: 'settle', amount: change, reservationId: reservation.id, jobId: options.jobId })
+      return { tenantId, measured: await cross<CreditReservation>(tx, tenantId, inFlow, rowToReservation(rows[0]!), before, before + change) }
+    })
+    return signal(done.tenantId, done.measured)
+  }
+
+  async function doRelease(explicit: string | null, options: { jobId: string }): Promise<{ released: boolean; reservation: CreditReservation | null }> {
+    requireJobId(options.jobId)
+    return run(explicit, async (tx, tenantId) => {
+      await lockTenant(tx, tenantId)
+      const reservation = await findReservation(tx, tenantId, options.jobId, true)
+      if (reservation === null) return { released: false, reservation: null }
+      if (reservation.status === 'released') return { released: false, reservation }
+      if (reservation.status === 'settled') {
+        throw new Error(`[pipework] credits.release: job "${options.jobId}" was already settled; settled usage cannot be released.\n`)
+      }
+      const refunded = await refund(tx, tenantId, reservation.id, reservation.amount)
+      const rows = await tx.execute(sql`
+        UPDATE credit_reservation SET status = 'released', settled_at = now() WHERE id = ${reservation.id} RETURNING *
+      `)
+      await writeLedger(tx, tenantId, { kind: 'release', amount: refunded, reservationId: reservation.id, jobId: options.jobId })
+      return { released: true, reservation: rowToReservation(rows[0]!) }
+    })
+  }
+
+  async function doBalance(explicit: string | null): Promise<CreditBalance> {
+    return run(explicit, async (tx, tenantId) => {
+      const grants = await tx.execute(sql`
+        SELECT id, kind, remaining, expires_at FROM credit_grant WHERE tenant_id = ${tenantId} AND ${LIVE}
+        ORDER BY expires_at ASC NULLS LAST, granted_at, id
+      `)
+      const held = await tx.execute(sql`
+        SELECT COALESCE(SUM(amount), 0) AS n FROM credit_reservation WHERE tenant_id = ${tenantId} AND status = 'held'
+      `)
+      const list = grants.map(g => ({
+        id: g['id'] as string, kind: g['kind'] as string, remaining: num(g['remaining']), expiresAt: toDateOrNull(g['expires_at']),
+      }))
+      return { available: list.reduce((sum, g) => sum + g.remaining, 0), held: num(held[0]!['n']), grants: list }
+    })
+  }
+
+  async function doHeld(explicit: string | null): Promise<CreditReservation[]> {
+    return run(explicit, async (tx, tenantId) => {
+      const found = await tx.execute(sql`
+        SELECT * FROM credit_reservation WHERE tenant_id = ${tenantId} AND status = 'held' ORDER BY created_at, id
+      `)
+      return found.map(rowToReservation)
+    })
+  }
+
+  async function doHistory(explicit: string | null, options: HistoryOptions = {}): Promise<HistoryPage> {
+    const limit = options.limit ?? DEFAULT_HISTORY_LIMIT
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_HISTORY_LIMIT) {
+      throw new ValidationError({ limit: [`must be an integer from 1 to ${MAX_HISTORY_LIMIT}`] }, 'Credits history limit is out of range.')
+    }
+    let cursor: { at: string; id: string } | null = null
+    if (options.before !== undefined) {
+      const cut = options.before.lastIndexOf('|')
+      if (cut < 1) throw new ValidationError({ before: ['is not a cursor from history()'] }, 'Credits history cursor is not valid.')
+      cursor = { at: options.before.slice(0, cut), id: options.before.slice(cut + 1) }
+    }
+    return run(explicit, async (tx, tenantId) => {
+      const rows = await tx.execute(cursor === null
+        ? sql`
+          SELECT *, "at"::text AS at_text FROM credit_ledger WHERE tenant_id = ${tenantId}
+          ORDER BY "at" DESC, id DESC LIMIT ${limit + 1}`
+        : sql`
+          SELECT *, "at"::text AS at_text FROM credit_ledger
+          WHERE tenant_id = ${tenantId} AND ("at", id) < (${cursor.at}::timestamp, ${cursor.id}::uuid)
+          ORDER BY "at" DESC, id DESC LIMIT ${limit + 1}`)
+      const page = rows.slice(0, limit)
+      const last = page[page.length - 1]
+      return {
+        entries: page.map(rowToEntry),
+        next: rows.length > limit && last !== undefined ? `${last['at_text'] as string}|${last['id'] as string}` : null,
+      }
+    })
+  }
+
+  async function doExpire(explicit: string | null): Promise<number> {
+    const done = await run(explicit, async (tx, tenantId, inFlow) => {
+      await lockTenant(tx, tenantId)
+      const due = await tx.execute(sql`
+        SELECT id, remaining FROM credit_grant
+        WHERE tenant_id = ${tenantId} AND remaining > 0 AND expires_at IS NOT NULL AND expires_at <= now()
+        ORDER BY expires_at, id FOR UPDATE
+      `)
+      // `available` already leaves out an expired grant, so the balance the ledger last
+      // recorded is the live balance plus what the due grants still hold.
+      const lapsing = due.reduce((sum, grant) => sum + num(grant['remaining']), 0)
+      const before = (await availableOf(tx, tenantId)) + lapsing
+      for (const grant of due) {
+        await tx.execute(sql`UPDATE credit_grant SET remaining = 0 WHERE id = ${grant['id'] as string}`)
+        await writeLedger(tx, tenantId, { kind: 'expire', amount: -num(grant['remaining']), grantId: grant['id'] as string })
+      }
+      const after = await availableOf(tx, tenantId)
+      return { tenantId, measured: await cross<number>(tx, tenantId, inFlow, due.length, before, after) }
+    })
+    return signal(done.tenantId, done.measured)
+  }
+
+  async function stateOf(tx: DB, tenantId: string): Promise<LowBalanceState> {
+    const { line, source } = await lineOf(tx, tenantId)
+    const available = await availableOf(tx, tenantId)
+    return { line, source, available, below: line !== null && available < line }
+  }
+
+  async function doLowBalance(explicit: string | null): Promise<LowBalanceState> {
+    return run(explicit, (tx, tenantId) => stateOf(tx, tenantId))
+  }
+
+  async function doSetLine(explicit: string | null, line: number | null): Promise<LowBalanceState> {
+    if (line !== null) requireUnits('line', line, 0)
+    const done = await run(explicit, async (tx, tenantId, inFlow) => {
+      await lockTenant(tx, tenantId)
+      const old = await lineOf(tx, tenantId)
+      const written = await tx.execute(sql`
+        INSERT INTO credit_account (tenant_id, low_balance_line, updated_at) VALUES (${tenantId}, ${line}, now())
+        ON CONFLICT (tenant_id) DO UPDATE SET low_balance_line = EXCLUDED.low_balance_line, updated_at = now()
+        RETURNING id
+      `)
+      const flow = getContext()
+      if (flow !== undefined) {
+        await writeInfraAudit(flow, tx, {
+          tenantId, entity: 'CreditAccount', verb: 'set_low_balance_line', entityId: written[0]!['id'] as string,
+          before: { lowBalanceLine: old.stored }, after: { lowBalanceLine: line },
+        })
+      }
+      const state = await stateOf(tx, tenantId)
+      // Crossing: at-or-above the old effective line (or none), under the new one.
+      const wasAbove = old.line === null || state.available >= old.line
+      let measured: Measured<LowBalanceState> = { value: state }
+      if (state.below && wasAbove && state.line !== null) {
+        const crossed = { line: state.line, available: state.available }
+        const fn = config.onLowBalanceCrossed
+        if (fn !== undefined) await inFlow(async () => { await fn({ tenantId, ...crossed }) })
+        measured = { value: state, crossed }
+      }
+      return { tenantId, measured }
+    })
+    return signal(done.tenantId, done.measured)
+  }
+
+  return {
+    grant: o => doGrant(null, o),
+    grantFor: (t, o) => doGrant(t, o),
+    reserve: o => doReserve(null, o),
+    reserveFor: (t, o) => doReserve(t, o),
+    settle: o => doSettle(null, o),
+    settleFor: (t, o) => doSettle(t, o),
+    release: o => doRelease(null, o),
+    releaseFor: (t, o) => doRelease(t, o),
+    held: () => doHeld(null),
+    heldFor: t => doHeld(t),
+    balance: () => doBalance(null),
+    balanceFor: t => doBalance(t),
+    history: o => doHistory(null, o),
+    historyFor: (t, o) => doHistory(t, o),
+    expire: () => doExpire(null),
+    expireFor: t => doExpire(t),
+    setLowBalanceLine: l => doSetLine(null, l),
+    setLowBalanceLineFor: (t, l) => doSetLine(t, l),
+    lowBalance: () => doLowBalance(null),
+    lowBalanceFor: t => doLowBalance(t),
+  }
+}