pipework 0.252.0 → 0.253.0

package/src/infra/credit-line/handle.ts

@@ -0,0 +1,883 @@
+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 { ValidationError } from '../../core/errors/index.js'
+
+/** The span a cap sums settled work over. Calendar windows are cut in the config's `timeZone`; `{ from, to }` is half-open `[from, to)`. */
+export type CapWindow = 'calendar_year' | 'calendar_month' | { readonly from: Date; readonly to: Date }
+
+export interface CreditLineCap {
+  /** Unique within the line; this is what a refusal names and what an authorization's `replacesCaps` lists. */
+  readonly name: string
+  readonly cents: number
+  readonly window: CapWindow
+  /** Overrides the line's and the config's warn share for this cap. */
+  readonly warnShare?: number
+}
+
+export interface CreditLineConfig {
+  /** The share of a limit at which it warns, for every limit that sets none. Default 0.8. */
+  readonly warnShare?: number
+  /** The zone calendar windows are cut in. Default `'UTC'`. */
+  readonly timeZone?: string
+  /**
+   * Awaited INSIDE the transaction of the write that took a limit's use from below its warn amount to
+   * at-or-above it (reserve, a settle above its reservation, openLine lowering a limit), in a Flow whose
+   * tenant is the write's tenant and where `pipe()` is that same transaction. If it throws, the write
+   * rolls back. A release, a payment or a raised limit re-arms the warning; nothing is stored.
+   */
+  readonly onLineCrossed?: (event: LineCrossing) => void | Promise<void>
+}
+
+export interface LimitRef {
+  readonly kind: 'ceiling' | 'cap' | 'authorization'
+  /** `'ceiling'`, the cap's name, or the authorization's reference. */
+  readonly name: string
+}
+
+export interface LineCrossing {
+  readonly tenantId: string
+  readonly limit: LimitRef
+  readonly usedCents: number
+  readonly limitCents: number
+  readonly warnAtCents: number
+}
+
+export interface LineReservation {
+  readonly id: string
+  readonly tenantId: string
+  readonly jobId: string
+  readonly amountCents: number
+  readonly status: 'held' | 'settled' | 'released'
+  readonly settledAmountCents: number | null
+  /** The authorization in force when the job was reserved, if any. */
+  readonly authorizationId: string | null
+  readonly createdAt: Date
+  readonly settledAt: Date | null
+}
+
+export type LineReserveResult =
+  | { readonly ok: true; readonly reservation: LineReservation }
+  | { readonly ok: false; readonly reason: 'no-line' }
+  | {
+    readonly ok: false; readonly reason: 'limit'; readonly limit: LimitRef
+    readonly limitCents: number; readonly usedCents: number; readonly requestedCents: number
+  }
+
+/** One settled job: unpaid work until payments clear it. */
+export interface LineEntry {
+  readonly id: string
+  readonly tenantId: string
+  readonly jobId: string
+  readonly reservationId: string
+  readonly amountCents: number
+  readonly paidCents: number
+  readonly authorizationId: string | null
+  readonly at: Date
+}
+
+export interface Payment {
+  readonly id: string
+  readonly tenantId: string
+  readonly reference: string
+  readonly amountCents: number
+  /** What no entry has cleared yet; the next settle draws on it. */
+  readonly unappliedCents: number
+  readonly at: Date
+}
+
+export interface PaymentApplication {
+  readonly entryId: string
+  readonly jobId: string
+  readonly cents: number
+}
+
+export type PaymentWithEntries = Payment & { readonly applications: readonly PaymentApplication[] }
+
+export interface Authorization {
+  readonly id: string
+  readonly tenantId: string
+  readonly reference: string
+  readonly amountCents: number
+  readonly startsAt: Date
+  readonly endsAt: Date
+  readonly replacesCaps: readonly string[]
+  readonly revokedAt: Date | null
+  readonly createdAt: Date
+}
+
+export type AuthorizationStatus = Authorization & {
+  /** Settled entries tagged with it. */
+  readonly usedCents: number
+  /** Held reservations tagged with it. */
+  readonly heldCents: number
+  readonly remainingCents: number
+  /** Started, not ended, not revoked. */
+  readonly inForce: boolean
+}
+
+export interface LineCapState extends CreditLineCap {
+  readonly usedCents: number
+  /** The authorization in force replaces this cap. */
+  readonly replaced: boolean
+}
+
+export interface LineState {
+  readonly tenantId: string
+  /** False when no line was ever opened, or it is closed. */
+  readonly open: boolean
+  readonly ceilingCents: number
+  readonly warnShare: number | null
+  /** Settled work not yet paid. */
+  readonly unpaidCents: number
+  /** Reservations still held. */
+  readonly heldCents: number
+  /** What a reserve could still take: the smallest remaining of the limits that apply now, at least 0. */
+  readonly availableCents: number
+  readonly caps: readonly LineCapState[]
+  readonly authorization: AuthorizationStatus | null
+  readonly openedAt: Date | null
+  readonly closedAt: Date | null
+}
+
+export interface Statement {
+  readonly from: Date
+  readonly to: Date
+  readonly entries: readonly LineEntry[]
+  readonly payments: readonly PaymentWithEntries[]
+  readonly totals: {
+    /** Sum of the entries in the period. */
+    readonly settledCents: number
+    /** Sum of the payments in the period. */
+    readonly paidCents: number
+    /** Everything unpaid as of now, not just this period's. */
+    readonly unpaidCents: number
+  }
+}
+
+export interface OpenLineOptions {
+  readonly ceilingCents: number
+  readonly caps?: readonly CreditLineCap[]
+  readonly warnShare?: number
+}
+
+export interface AuthorizeOptions {
+  readonly reference: string
+  readonly amountCents: number
+  readonly from: Date
+  readonly to: Date
+  /** Names of caps this authorization replaces while it is in force; every other cap still applies. */
+  readonly replacesCaps?: readonly string[]
+}
+
+export interface CreditLine {
+  /** Opens the tenant's line, or updates an open one (and reopens a closed one). Audited as `CreditLine` `open`. */
+  openLine(options: OpenLineOptions): Promise<LineState>
+  openLineFor(tenantId: string, options: OpenLineOptions): Promise<LineState>
+  /** New reserves fail `'no-line'`; held reservations may still settle or release; unpaid work stays. */
+  closeLine(): Promise<LineState>
+  closeLineFor(tenantId: string): Promise<LineState>
+  /**
+   * Holds `amountCents` for a job against the ceiling (or the authorization in force) and then each cap in
+   * order; the first limit it would pass is the refusal and nothing is written. A job id that already has a
+   * reservation returns it unchanged, whatever amount is asked this time.
+   */
+  reserve(options: { jobId: string; amountCents: number }): Promise<LineReserveResult>
+  reserveFor(tenantId: string, options: { jobId: string; amountCents: number }): Promise<LineReserveResult>
+  /**
+   * Records the actual cost of a reserved job as an unpaid entry; never fails on limits. The same amount again
+   * is a no-op; a different amount, a released job or an unknown job throws. Payments with unapplied cents clear it, oldest first.
+   */
+  settle(options: { jobId: string; amountCents: number }): Promise<LineReservation>
+  settleFor(tenantId: string, options: { jobId: string; amountCents: number }): Promise<LineReservation>
+  /** Gives up a held reservation. No reservation: `{ released: false, reservation: null }`; already released: `released: false`. A settled job throws. */
+  release(options: { jobId: string }): Promise<{ released: boolean; reservation: LineReservation | null }>
+  releaseFor(tenantId: string, options: { jobId: string }): Promise<{ released: boolean; reservation: LineReservation | null }>
+  /** Records a purchase order. Idempotent by reference. Dates that overlap an unrevoked authorization throw ValidationError. */
+  authorize(options: AuthorizeOptions): Promise<{ authorization: Authorization; created: boolean }>
+  authorizeFor(tenantId: string, options: AuthorizeOptions): Promise<{ authorization: Authorization; created: boolean }>
+  revokeAuthorization(reference: string): Promise<Authorization>
+  revokeAuthorizationFor(tenantId: string, reference: string): Promise<Authorization>
+  authorizations(): Promise<AuthorizationStatus[]>
+  authorizationsFor(tenantId: string): Promise<AuthorizationStatus[]>
+  /** Idempotent by reference. Clears unpaid entries oldest first and keeps any excess as `unappliedCents`. */
+  recordPayment(options: { amountCents: number; reference: string; at?: Date }): Promise<{ payment: Payment; created: boolean }>
+  recordPaymentFor(tenantId: string, options: { amountCents: number; reference: string; at?: Date }): Promise<{ payment: Payment; created: boolean }>
+  /** The entries and payments with `at` in `[from, to)`, each payment with the entries it cleared, and totals. */
+  statement(options: { from: Date; to: Date }): Promise<Statement>
+  statementFor(tenantId: string, options: { from: Date; to: Date }): Promise<Statement>
+  line(): Promise<LineState>
+  lineFor(tenantId: string): Promise<LineState>
+}
+
+type Row = Record<string, unknown>
+
+const DEFAULT_WARN_SHARE = 0.8
+const NOW = sql`(clock_timestamp() AT TIME ZONE 'UTC')`
+
+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 utc(date: Date) {
+  return sql`(${date.toISOString()}::timestamptz AT TIME ZONE 'UTC')`
+}
+
+function rowToReservation(row: Row): LineReservation {
+  return {
+    id: row['id'] as string,
+    tenantId: row['tenant_id'] as string,
+    jobId: row['job_id'] as string,
+    amountCents: num(row['amount']),
+    status: row['status'] as LineReservation['status'],
+    settledAmountCents: numOrNull(row['settled_amount']),
+    authorizationId: (row['authorization_id'] as string | null) ?? null,
+    createdAt: toDate(row['created_at']),
+    settledAt: toDateOrNull(row['settled_at']),
+  }
+}
+
+function rowToEntry(row: Row): LineEntry {
+  return {
+    id: row['id'] as string,
+    tenantId: row['tenant_id'] as string,
+    jobId: row['job_id'] as string,
+    reservationId: row['reservation_id'] as string,
+    amountCents: num(row['amount_cents']),
+    paidCents: num(row['paid_cents']),
+    authorizationId: (row['authorization_id'] as string | null) ?? null,
+    at: toDate(row['at']),
+  }
+}
+
+function rowToPayment(row: Row): Payment {
+  return {
+    id: row['id'] as string,
+    tenantId: row['tenant_id'] as string,
+    reference: row['reference'] as string,
+    amountCents: num(row['amount_cents']),
+    unappliedCents: num(row['unapplied_cents']),
+    at: toDate(row['at']),
+  }
+}
+
+function rowToAuthorization(row: Row): Authorization {
+  const names = row['replaces_caps']
+  return {
+    id: row['id'] as string,
+    tenantId: row['tenant_id'] as string,
+    reference: row['reference'] as string,
+    amountCents: num(row['amount_cents']),
+    startsAt: toDate(row['starts_at']),
+    endsAt: toDate(row['ends_at']),
+    replacesCaps: Array.isArray(names) ? (names as string[]) : [],
+    revokedAt: toDateOrNull(row['revoked_at']),
+    createdAt: toDate(row['created_at']),
+  }
+}
+
+interface StoredCap { name: string; cents: number; window: 'calendar_year' | 'calendar_month' | { from: string; to: string }; warnShare?: number }
+
+function capsToJson(caps: readonly CreditLineCap[]): string {
+  return JSON.stringify(caps.map((c): StoredCap => ({
+    name: c.name,
+    cents: c.cents,
+    window: typeof c.window === 'string' ? c.window : { from: c.window.from.toISOString(), to: c.window.to.toISOString() },
+    ...(c.warnShare === undefined ? {} : { warnShare: c.warnShare }),
+  })))
+}
+
+function capsFromJson(value: unknown): CreditLineCap[] {
+  const list = Array.isArray(value) ? (value as StoredCap[]) : []
+  return list.map(c => ({
+    name: c.name,
+    cents: c.cents,
+    window: typeof c.window === 'string' ? c.window : { from: new Date(c.window.from), to: new Date(c.window.to) },
+    ...(c.warnShare === undefined ? {} : { warnShare: c.warnShare }),
+  }))
+}
+
+function fail(field: string, detail: string, message: string): never {
+  throw new ValidationError({ [field]: [detail] }, message)
+}
+
+function requireCents(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'
+    fail(name, detail, `Credit line ${name} ${detail} (whole cents).`)
+  }
+}
+
+function requireText(name: string, value: unknown): void {
+  if (typeof value !== 'string' || value === '') fail(name, 'must be a non-empty string', `Credit line ${name} must be a non-empty string.`)
+}
+
+function requireShare(name: string, value: number): void {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
+    fail(name, 'must be greater than 0 and at most 1', `Credit line ${name} must be greater than 0 and at most 1.`)
+  }
+}
+
+function requireSpan(name: string, from: Date, to: Date): void {
+  if (!(from instanceof Date) || !(to instanceof Date) || Number.isNaN(from.getTime()) || Number.isNaN(to.getTime()) || from.getTime() >= to.getTime()) {
+    fail(name, 'from must be a valid date before to', `Credit line ${name}: from must be a valid date before to.`)
+  }
+}
+
+function requireCaps(caps: readonly CreditLineCap[]): void {
+  const seen = new Set<string>()
+  for (const cap of caps) {
+    requireText('caps.name', cap.name)
+    if (seen.has(cap.name)) fail('caps', `name "${cap.name}" is used twice`, `Credit line cap names must be unique; "${cap.name}" appears twice.`)
+    seen.add(cap.name)
+    requireCents(`cap "${cap.name}" cents`, cap.cents, 1)
+    if (cap.warnShare !== undefined) requireShare(`cap "${cap.name}" warnShare`, cap.warnShare)
+    const window: unknown = cap.window
+    if (window === 'calendar_year' || window === 'calendar_month') continue
+    const span = (typeof window === 'object' && window !== null ? window : {}) as { from?: Date; to?: Date }
+    if (span.from === undefined || span.to === undefined) {
+      fail('caps.window', 'must be calendar_year, calendar_month or { from, to }', `Credit line cap "${cap.name}" window must be 'calendar_year', 'calendar_month' or { from, to }.`)
+    }
+    requireSpan(`cap "${cap.name}" window`, span.from, span.to)
+  }
+}
+
+interface LineRow {
+  readonly id: string
+  readonly ceilingCents: number
+  readonly warnShare: number | null
+  readonly caps: CreditLineCap[]
+  readonly openedAt: Date
+  readonly closedAt: Date | null
+}
+
+interface Limit {
+  readonly ref: LimitRef
+  readonly limitCents: number
+  readonly usedCents: number
+  readonly warnAtCents: number
+}
+
+interface Snapshot {
+  readonly line: LineRow | null
+  readonly auth: AuthorizationStatus | null
+  readonly unpaid: number
+  readonly held: number
+  readonly caps: LineCapState[]
+  /** Limits in force, in check order: the ceiling or the authorization, then the caps not replaced. */
+  readonly limits: Limit[]
+}
+
+export function createCreditLine(config: CreditLineConfig = {}): CreditLine {
+  const defaultShare = config.warnShare ?? DEFAULT_WARN_SHARE
+  requireShare('config warnShare', defaultShare)
+  const timeZone = config.timeZone ?? 'UTC'
+  try {
+    new Intl.DateTimeFormat('en', { timeZone })
+  } catch {
+    throw new Error(`[pipework] creditLine timeZone "${timeZone}" is not a time zone name (use an IANA name such as "America/New_York").\n`)
+  }
+
+  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 creditLine method needs a tenant in the Flow.\n\n' +
+        '  Call it from an authenticated tenant route, or use the ...For(tenantId, ...) form\n' +
+        '  (openLineFor, reserveFor, settleFor, ...) from a webhook or a job with no tenant.\n',
+      )
+    }
+    const tenantId = flow.tenant
+    return pipe.transaction((tx: DB) => fn(tx, tenantId, body => body()))
+  }
+
+  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 {
+    requireText('tenantId', tenantId)
+  }
+
+  async function lockTenant(tx: DB, tenantId: string): Promise<void> {
+    await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${`pipework.credit_line:${tenantId}`}, 0))`)
+  }
+
+  async function auditStep(tx: DB, tenantId: string, lineId: string, verb: string, after: Record<string, unknown>, before?: Record<string, unknown>): Promise<void> {
+    const flow = getContext()
+    if (flow === undefined) return
+    await writeInfraAudit(flow, tx, { tenantId, entity: 'CreditLine', verb, entityId: lineId, after, ...(before === undefined ? {} : { before }) })
+  }
+
+  async function loadLine(tx: DB, tenantId: string): Promise<LineRow | null> {
+    const rows = await tx.execute(sql`SELECT * FROM credit_line WHERE tenant_id = ${tenantId}`)
+    if (rows.length === 0) return null
+    const r = rows[0]!
+    return {
+      id: r['id'] as string,
+      ceilingCents: num(r['ceiling_cents']),
+      warnShare: numOrNull(r['warn_share']),
+      caps: capsFromJson(r['caps']),
+      openedAt: toDate(r['opened_at']),
+      closedAt: toDateOrNull(r['closed_at']),
+    }
+  }
+
+  async function requireLine(tx: DB, tenantId: string, what: string): Promise<LineRow> {
+    const line = await loadLine(tx, tenantId)
+    if (line === null) {
+      throw new Error(`[pipework] creditLine.${what}: tenant ${tenantId} has no line.\n\n  Call openLine({ ceilingCents }) first.\n`)
+    }
+    return line
+  }
+
+  function windowBounds(window: CapWindow) {
+    if (typeof window !== 'string') return { start: utc(window.from), end: utc(window.to) }
+    const unit = window === 'calendar_year' ? 'year' : 'month'
+    const local = sql`date_trunc(${sql.raw(`'${unit}'`)}, clock_timestamp() AT TIME ZONE ${timeZone}::text)`
+    return {
+      start: sql`((${local}) AT TIME ZONE ${timeZone}::text) AT TIME ZONE 'UTC'`,
+      end: sql`((${local} + ${sql.raw(`interval '1 ${unit}'`)}) AT TIME ZONE ${timeZone}::text) AT TIME ZONE 'UTC'`,
+    }
+  }
+
+  async function sumOf(tx: DB, query: ReturnType<typeof sql>): Promise<number> {
+    const rows = await tx.execute(query)
+    return num(rows[0]!['n'])
+  }
+
+  function authStatus(row: Row, used: number, held: number, inForce: boolean): AuthorizationStatus {
+    const a = rowToAuthorization(row)
+    return { ...a, usedCents: used, heldCents: held, remainingCents: Math.max(0, a.amountCents - used - held), inForce }
+  }
+
+  async function statusOf(tx: DB, tenantId: string, row: Row): Promise<AuthorizationStatus> {
+    const id = row['id'] as string
+    const used = await sumOf(tx, sql`SELECT COALESCE(SUM(amount_cents), 0) AS n FROM credit_line_entry WHERE tenant_id = ${tenantId} AND authorization_id = ${id}`)
+    const held = await sumOf(tx, sql`SELECT COALESCE(SUM(amount), 0) AS n FROM credit_line_reservation WHERE tenant_id = ${tenantId} AND authorization_id = ${id} AND status = 'held'`)
+    const flag = await tx.execute(sql`
+      SELECT (revoked_at IS NULL AND starts_at <= ${NOW} AND ${NOW} < ends_at) AS in_force FROM credit_line_authorization WHERE id = ${id}
+    `)
+    return authStatus(row, used, held, flag[0]!['in_force'] === true)
+  }
+
+  // Everything a limit check or a crossing needs, read in the operation's own transaction.
+  async function measure(tx: DB, tenantId: string): Promise<Snapshot> {
+    const line = await loadLine(tx, tenantId)
+    const unpaid = await sumOf(tx, sql`SELECT COALESCE(SUM(amount_cents - paid_cents), 0) AS n FROM credit_line_entry WHERE tenant_id = ${tenantId}`)
+    const held = await sumOf(tx, sql`SELECT COALESCE(SUM(amount), 0) AS n FROM credit_line_reservation WHERE tenant_id = ${tenantId} AND status = 'held'`)
+    if (line === null) return { line, auth: null, unpaid, held, caps: [], limits: [] }
+    const authRows = await tx.execute(sql`
+      SELECT * FROM credit_line_authorization
+      WHERE tenant_id = ${tenantId} AND revoked_at IS NULL AND starts_at <= ${NOW} AND ${NOW} < ends_at
+      ORDER BY starts_at DESC LIMIT 1
+    `)
+    const auth = authRows.length === 0 ? null : await statusOf(tx, tenantId, authRows[0]!)
+    const warnAt = (limit: number, own?: number | null): number =>
+      Math.floor(limit * (own ?? line.warnShare ?? defaultShare) + 1e-9)
+    const limits: Limit[] = auth === null
+      ? [{ ref: { kind: 'ceiling', name: 'ceiling' }, limitCents: line.ceilingCents, usedCents: unpaid + held, warnAtCents: warnAt(line.ceilingCents) }]
+      : [{ ref: { kind: 'authorization', name: auth.reference }, limitCents: auth.amountCents, usedCents: auth.usedCents + auth.heldCents, warnAtCents: warnAt(auth.amountCents) }]
+    const caps: LineCapState[] = []
+    for (const cap of line.caps) {
+      const { start, end } = windowBounds(cap.window)
+      const settled = await sumOf(tx, sql`
+        SELECT COALESCE(SUM(amount_cents), 0) AS n FROM credit_line_entry
+        WHERE tenant_id = ${tenantId} AND "at" >= ${start} AND "at" < ${end}
+      `)
+      const used = settled + held
+      const replaced = auth !== null && auth.replacesCaps.includes(cap.name)
+      caps.push({ ...cap, usedCents: used, replaced })
+      if (!replaced) limits.push({ ref: { kind: 'cap', name: cap.name }, limitCents: cap.cents, usedCents: used, warnAtCents: warnAt(cap.cents, cap.warnShare) })
+    }
+    return { line, auth, unpaid, held, caps, limits }
+  }
+
+  function stateOf(tenantId: string, s: Snapshot): LineState {
+    const remaining = s.limits.map(l => l.limitCents - l.usedCents)
+    return {
+      tenantId,
+      open: s.line !== null && s.line.closedAt === null,
+      ceilingCents: s.line?.ceilingCents ?? 0,
+      warnShare: s.line?.warnShare ?? null,
+      unpaidCents: s.unpaid,
+      heldCents: s.held,
+      availableCents: remaining.length === 0 ? 0 : Math.max(0, Math.min(...remaining)),
+      caps: s.caps,
+      authorization: s.auth,
+      openedAt: s.line?.openedAt ?? null,
+      closedAt: s.line?.closedAt ?? null,
+    }
+  }
+
+  // A limit warns when a write takes its use from below its warn amount to at-or-above it. Compared
+  // within the write, so nothing is stored and a fall back below re-arms it. Awaited in the tenant's
+  // Flow, so a throwing hook rolls the write back.
+  async function fireCrossings(tenantId: string, inFlow: InFlow, before: Snapshot, after: Snapshot): Promise<void> {
+    const fn = config.onLineCrossed
+    if (fn === undefined) return
+    const key = (l: Limit): string => `${l.ref.kind}:${l.ref.name}`
+    const prior = new Map(before.limits.map(l => [key(l), l]))
+    for (const l of after.limits) {
+      const b = prior.get(key(l))
+      if (b === undefined || !(b.usedCents < b.warnAtCents && l.usedCents >= l.warnAtCents)) continue
+      const event: LineCrossing = { tenantId, limit: l.ref, usedCents: l.usedCents, limitCents: l.limitCents, warnAtCents: l.warnAtCents }
+      await inFlow(async () => { await fn(event) })
+    }
+  }
+
+  async function findReservation(tx: DB, tenantId: string, jobId: string, lock: boolean): Promise<LineReservation | null> {
+    const rows = await tx.execute(lock
+      ? sql`SELECT * FROM credit_line_reservation WHERE tenant_id = ${tenantId} AND job_id = ${jobId} FOR UPDATE`
+      : sql`SELECT * FROM credit_line_reservation WHERE tenant_id = ${tenantId} AND job_id = ${jobId}`)
+    return rows.length === 0 ? null : rowToReservation(rows[0]!)
+  }
+
+  // Pays unpaid entries from a payment's unapplied cents, oldest entry first.
+  async function applyPayment(tx: DB, tenantId: string, paymentId: string, unapplied: number): Promise<number> {
+    const entries = await tx.execute(sql`
+      SELECT id, amount_cents, paid_cents FROM credit_line_entry
+      WHERE tenant_id = ${tenantId} AND amount_cents > paid_cents ORDER BY "at", id FOR UPDATE
+    `)
+    let left = unapplied
+    for (const e of entries) {
+      if (left === 0) break
+      const take = Math.min(num(e['amount_cents']) - num(e['paid_cents']), left)
+      await tx.execute(sql`UPDATE credit_line_entry SET paid_cents = paid_cents + ${take} WHERE id = ${e['id'] as string}`)
+      await tx.execute(sql`
+        INSERT INTO credit_line_payment_application (tenant_id, payment_id, entry_id, cents) VALUES (${tenantId}, ${paymentId}, ${e['id'] as string}, ${take})
+      `)
+      left -= take
+    }
+    await tx.execute(sql`UPDATE credit_line_payment SET unapplied_cents = ${left} WHERE id = ${paymentId}`)
+    return left
+  }
+
+  // Pays one new entry from payments with unapplied cents, oldest payment first.
+  async function clearEntry(tx: DB, tenantId: string, entryId: string, amount: number): Promise<number> {
+    const payments = await tx.execute(sql`
+      SELECT id, unapplied_cents FROM credit_line_payment
+      WHERE tenant_id = ${tenantId} AND unapplied_cents > 0 ORDER BY "at", id FOR UPDATE
+    `)
+    let need = amount
+    for (const p of payments) {
+      if (need === 0) break
+      const take = Math.min(num(p['unapplied_cents']), need)
+      await tx.execute(sql`UPDATE credit_line_payment SET unapplied_cents = unapplied_cents - ${take} WHERE id = ${p['id'] as string}`)
+      await tx.execute(sql`
+        INSERT INTO credit_line_payment_application (tenant_id, payment_id, entry_id, cents) VALUES (${tenantId}, ${p['id'] as string}, ${entryId}, ${take})
+      `)
+      need -= take
+    }
+    return amount - need
+  }
+
+  async function doOpen(explicit: string | null, o: OpenLineOptions): Promise<LineState> {
+    requireCents('ceilingCents', o.ceilingCents, 1)
+    if (o.warnShare !== undefined) requireShare('warnShare', o.warnShare)
+    const caps = o.caps ?? []
+    requireCaps(caps)
+    return run(explicit, async (tx, tenantId, inFlow) => {
+      await lockTenant(tx, tenantId)
+      const before = await measure(tx, tenantId)
+      const rows = await tx.execute(sql`
+        INSERT INTO credit_line (tenant_id, ceiling_cents, warn_share, caps, opened_at, closed_at)
+        VALUES (${tenantId}, ${o.ceilingCents}, ${o.warnShare ?? null}, ${capsToJson(caps)}::jsonb, ${NOW}, NULL)
+        ON CONFLICT (tenant_id) DO UPDATE
+          SET ceiling_cents = EXCLUDED.ceiling_cents, warn_share = EXCLUDED.warn_share, caps = EXCLUDED.caps, closed_at = NULL
+        RETURNING id
+      `)
+      const after = await measure(tx, tenantId)
+      const prev = before.line
+      await auditStep(tx, tenantId, rows[0]!['id'] as string, 'open', {
+        ceilingCents: o.ceilingCents, warnShare: o.warnShare ?? null, caps: JSON.parse(capsToJson(caps)) as unknown,
+      }, prev === null ? undefined : {
+        ceilingCents: prev.ceilingCents, warnShare: prev.warnShare, caps: JSON.parse(capsToJson(prev.caps)) as unknown, closed: prev.closedAt !== null,
+      })
+      await fireCrossings(tenantId, inFlow, before, after)
+      return stateOf(tenantId, after)
+    })
+  }
+
+  async function doClose(explicit: string | null): Promise<LineState> {
+    return run(explicit, async (tx, tenantId) => {
+      await lockTenant(tx, tenantId)
+      const line = await requireLine(tx, tenantId, 'closeLine')
+      if (line.closedAt === null) {
+        await tx.execute(sql`UPDATE credit_line SET closed_at = ${NOW} WHERE id = ${line.id}`)
+        await auditStep(tx, tenantId, line.id, 'close', { closed: true })
+      }
+      return stateOf(tenantId, await measure(tx, tenantId))
+    })
+  }
+
+  async function doReserve(explicit: string | null, o: { jobId: string; amountCents: number }): Promise<LineReserveResult> {
+    requireText('jobId', o.jobId)
+    requireCents('amountCents', o.amountCents, 1)
+    return run(explicit, async (tx, tenantId, inFlow): Promise<LineReserveResult> => {
+      await lockTenant(tx, tenantId)
+      const existing = await findReservation(tx, tenantId, o.jobId, false)
+      if (existing !== null) return { ok: true, reservation: existing }
+      const before = await measure(tx, tenantId)
+      if (before.line === null || before.line.closedAt !== null) return { ok: false, reason: 'no-line' }
+      for (const l of before.limits) {
+        if (l.usedCents + o.amountCents > l.limitCents) {
+          return { ok: false, reason: 'limit', limit: l.ref, limitCents: l.limitCents, usedCents: l.usedCents, requestedCents: o.amountCents }
+        }
+      }
+      const inserted = await tx.execute(sql`
+        INSERT INTO credit_line_reservation (tenant_id, job_id, amount, status, authorization_id, created_at)
+        VALUES (${tenantId}, ${o.jobId}, ${o.amountCents}, 'held', ${before.auth?.id ?? null}, ${NOW})
+        ON CONFLICT (tenant_id, job_id) DO NOTHING
+        RETURNING *
+      `)
+      if (inserted.length === 0) return { ok: true, reservation: (await findReservation(tx, tenantId, o.jobId, false))! }
+      const reservation = rowToReservation(inserted[0]!)
+      await auditStep(tx, tenantId, before.line.id, 'reserve', {
+        jobId: o.jobId, amountCents: o.amountCents, reservationId: reservation.id, authorizationId: reservation.authorizationId,
+      })
+      await fireCrossings(tenantId, inFlow, before, await measure(tx, tenantId))
+      return { ok: true, reservation }
+    })
+  }
+
+  async function doSettle(explicit: string | null, o: { jobId: string; amountCents: number }): Promise<LineReservation> {
+    requireText('jobId', o.jobId)
+    requireCents('amountCents', o.amountCents, 0)
+    return run(explicit, async (tx, tenantId, inFlow) => {
+      await lockTenant(tx, tenantId)
+      const reservation = await findReservation(tx, tenantId, o.jobId, true)
+      if (reservation === null) {
+        throw new Error(`[pipework] creditLine.settle: no reservation for job "${o.jobId}".\n\n  Call reserve({ jobId, amountCents }) before the job, with the same jobId.\n`)
+      }
+      if (reservation.status === 'released') {
+        throw new Error(`[pipework] creditLine.settle: the reservation for job "${o.jobId}" was released.\n`)
+      }
+      if (reservation.status === 'settled') {
+        if (reservation.settledAmountCents === o.amountCents) return reservation
+        throw new Error(
+          `[pipework] creditLine.settle: job "${o.jobId}" was already settled at ${reservation.settledAmountCents}, not ${o.amountCents}.\n`,
+        )
+      }
+      const line = await requireLine(tx, tenantId, 'settle')
+      const before = await measure(tx, tenantId)
+      const rows = await tx.execute(sql`
+        UPDATE credit_line_reservation SET status = 'settled', settled_amount = ${o.amountCents}, settled_at = ${NOW}
+        WHERE id = ${reservation.id} RETURNING *
+      `)
+      const entry = await tx.execute(sql`
+        INSERT INTO credit_line_entry (tenant_id, job_id, reservation_id, amount_cents, paid_cents, authorization_id, "at")
+        VALUES (${tenantId}, ${o.jobId}, ${reservation.id}, ${o.amountCents}, 0, ${reservation.authorizationId}, ${NOW})
+        RETURNING id
+      `)
+      const entryId = entry[0]!['id'] as string
+      const cleared = await clearEntry(tx, tenantId, entryId, o.amountCents)
+      if (cleared > 0) await tx.execute(sql`UPDATE credit_line_entry SET paid_cents = ${cleared} WHERE id = ${entryId}`)
+      await auditStep(tx, tenantId, line.id, 'settle', {
+        jobId: o.jobId, amountCents: o.amountCents, reservedCents: reservation.amountCents, reservationId: reservation.id,
+        entryId, authorizationId: reservation.authorizationId, clearedCents: cleared,
+      })
+      await fireCrossings(tenantId, inFlow, before, await measure(tx, tenantId))
+      return rowToReservation(rows[0]!)
+    })
+  }
+
+  async function doRelease(explicit: string | null, o: { jobId: string }): Promise<{ released: boolean; reservation: LineReservation | null }> {
+    requireText('jobId', o.jobId)
+    return run(explicit, async (tx, tenantId) => {
+      await lockTenant(tx, tenantId)
+      const reservation = await findReservation(tx, tenantId, o.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] creditLine.release: job "${o.jobId}" was already settled; settled usage cannot be released.\n`)
+      }
+      const line = await requireLine(tx, tenantId, 'release')
+      const rows = await tx.execute(sql`
+        UPDATE credit_line_reservation SET status = 'released', settled_at = ${NOW} WHERE id = ${reservation.id} RETURNING *
+      `)
+      await auditStep(tx, tenantId, line.id, 'release', {
+        jobId: o.jobId, amountCents: reservation.amountCents, reservationId: reservation.id, authorizationId: reservation.authorizationId,
+      })
+      return { released: true, reservation: rowToReservation(rows[0]!) }
+    })
+  }
+
+  async function doAuthorize(explicit: string | null, o: AuthorizeOptions): Promise<{ authorization: Authorization; created: boolean }> {
+    requireText('reference', o.reference)
+    requireCents('amountCents', o.amountCents, 1)
+    requireSpan('authorization dates', o.from, o.to)
+    const replaces = o.replacesCaps ?? []
+    for (const name of replaces) requireText('replacesCaps', name)
+    return run(explicit, async (tx, tenantId) => {
+      await lockTenant(tx, tenantId)
+      const line = await requireLine(tx, tenantId, 'authorize')
+      const found = await tx.execute(sql`SELECT * FROM credit_line_authorization WHERE tenant_id = ${tenantId} AND reference = ${o.reference}`)
+      if (found.length > 0) return { authorization: rowToAuthorization(found[0]!), created: false }
+      const clash = await tx.execute(sql`
+        SELECT reference FROM credit_line_authorization
+        WHERE tenant_id = ${tenantId} AND revoked_at IS NULL AND starts_at < ${utc(o.to)} AND ${utc(o.from)} < ends_at
+        LIMIT 1
+      `)
+      if (clash.length > 0) {
+        fail('from', `overlaps authorization "${clash[0]!['reference'] as string}"`,
+          `Credit line authorization "${o.reference}" overlaps "${clash[0]!['reference'] as string}"; revoke that one or choose dates after it ends.`)
+      }
+      const rows = await tx.execute(sql`
+        INSERT INTO credit_line_authorization (tenant_id, reference, amount_cents, starts_at, ends_at, replaces_caps, created_at)
+        VALUES (${tenantId}, ${o.reference}, ${o.amountCents}, ${utc(o.from)}, ${utc(o.to)}, ${JSON.stringify(replaces)}::jsonb, ${NOW})
+        RETURNING *
+      `)
+      const authorization = rowToAuthorization(rows[0]!)
+      await auditStep(tx, tenantId, line.id, 'authorize', {
+        reference: o.reference, amountCents: o.amountCents, from: o.from.toISOString(), to: o.to.toISOString(), replacesCaps: replaces,
+        authorizationId: authorization.id,
+      })
+      return { authorization, created: true }
+    })
+  }
+
+  async function doRevoke(explicit: string | null, reference: string): Promise<Authorization> {
+    requireText('reference', reference)
+    return run(explicit, async (tx, tenantId) => {
+      await lockTenant(tx, tenantId)
+      const line = await requireLine(tx, tenantId, 'revokeAuthorization')
+      const found = await tx.execute(sql`SELECT * FROM credit_line_authorization WHERE tenant_id = ${tenantId} AND reference = ${reference} FOR UPDATE`)
+      if (found.length === 0) {
+        throw new Error(`[pipework] creditLine.revokeAuthorization: no authorization "${reference}" for tenant ${tenantId}.\n`)
+      }
+      const current = rowToAuthorization(found[0]!)
+      if (current.revokedAt !== null) return current
+      const rows = await tx.execute(sql`UPDATE credit_line_authorization SET revoked_at = ${NOW} WHERE id = ${current.id} RETURNING *`)
+      await auditStep(tx, tenantId, line.id, 'revoke_authorization', { reference, authorizationId: current.id })
+      return rowToAuthorization(rows[0]!)
+    })
+  }
+
+  async function doAuthorizations(explicit: string | null): Promise<AuthorizationStatus[]> {
+    return run(explicit, async (tx, tenantId) => {
+      const rows = await tx.execute(sql`SELECT * FROM credit_line_authorization WHERE tenant_id = ${tenantId} ORDER BY created_at, id`)
+      const out: AuthorizationStatus[] = []
+      for (const row of rows) out.push(await statusOf(tx, tenantId, row))
+      return out
+    })
+  }
+
+  async function doPayment(explicit: string | null, o: { amountCents: number; reference: string; at?: Date }): Promise<{ payment: Payment; created: boolean }> {
+    requireText('reference', o.reference)
+    requireCents('amountCents', o.amountCents, 1)
+    if (o.at !== undefined && Number.isNaN(o.at.getTime())) fail('at', 'must be a valid date', 'Credit line payment at must be a valid date.')
+    return run(explicit, async (tx, tenantId) => {
+      await lockTenant(tx, tenantId)
+      const line = await requireLine(tx, tenantId, 'recordPayment')
+      const found = await tx.execute(sql`SELECT * FROM credit_line_payment WHERE tenant_id = ${tenantId} AND reference = ${o.reference}`)
+      if (found.length > 0) return { payment: rowToPayment(found[0]!), created: false }
+      const rows = await tx.execute(sql`
+        INSERT INTO credit_line_payment (tenant_id, reference, amount_cents, unapplied_cents, "at")
+        VALUES (${tenantId}, ${o.reference}, ${o.amountCents}, ${o.amountCents}, ${o.at === undefined ? NOW : utc(o.at)})
+        RETURNING id
+      `)
+      const id = rows[0]!['id'] as string
+      const left = await applyPayment(tx, tenantId, id, o.amountCents)
+      await auditStep(tx, tenantId, line.id, 'payment', {
+        reference: o.reference, amountCents: o.amountCents, clearedCents: o.amountCents - left, unappliedCents: left, paymentId: id,
+      })
+      const saved = await tx.execute(sql`SELECT * FROM credit_line_payment WHERE id = ${id}`)
+      return { payment: rowToPayment(saved[0]!), created: true }
+    })
+  }
+
+  async function doStatement(explicit: string | null, o: { from: Date; to: Date }): Promise<Statement> {
+    requireSpan('statement period', o.from, o.to)
+    return run(explicit, async (tx, tenantId): Promise<Statement> => {
+      const entries = (await tx.execute(sql`
+        SELECT * FROM credit_line_entry WHERE tenant_id = ${tenantId} AND "at" >= ${utc(o.from)} AND "at" < ${utc(o.to)} ORDER BY "at", id
+      `)).map(rowToEntry)
+      const paymentRows = await tx.execute(sql`
+        SELECT * FROM credit_line_payment WHERE tenant_id = ${tenantId} AND "at" >= ${utc(o.from)} AND "at" < ${utc(o.to)} ORDER BY "at", id
+      `)
+      const payments: PaymentWithEntries[] = []
+      for (const row of paymentRows) {
+        const apps = await tx.execute(sql`
+          SELECT a.entry_id, a.cents, e.job_id FROM credit_line_payment_application a
+          JOIN credit_line_entry e ON e.id = a.entry_id
+          WHERE a.tenant_id = ${tenantId} AND a.payment_id = ${row['id'] as string} ORDER BY e."at", e.id
+        `)
+        payments.push({
+          ...rowToPayment(row),
+          applications: apps.map(a => ({ entryId: a['entry_id'] as string, jobId: a['job_id'] as string, cents: num(a['cents']) })),
+        })
+      }
+      const unpaid = await sumOf(tx, sql`SELECT COALESCE(SUM(amount_cents - paid_cents), 0) AS n FROM credit_line_entry WHERE tenant_id = ${tenantId}`)
+      return {
+        from: o.from,
+        to: o.to,
+        entries,
+        payments,
+        totals: {
+          settledCents: entries.reduce((s, e) => s + e.amountCents, 0),
+          paidCents: payments.reduce((s, p) => s + p.amountCents, 0),
+          unpaidCents: unpaid,
+        },
+      }
+    })
+  }
+
+  async function doLine(explicit: string | null): Promise<LineState> {
+    return run(explicit, async (tx, tenantId) => stateOf(tenantId, await measure(tx, tenantId)))
+  }
+
+  return {
+    openLine: o => doOpen(null, o),
+    openLineFor: (t, o) => doOpen(t, o),
+    closeLine: () => doClose(null),
+    closeLineFor: t => doClose(t),
+    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),
+    authorize: o => doAuthorize(null, o),
+    authorizeFor: (t, o) => doAuthorize(t, o),
+    revokeAuthorization: r => doRevoke(null, r),
+    revokeAuthorizationFor: (t, r) => doRevoke(t, r),
+    authorizations: () => doAuthorizations(null),
+    authorizationsFor: t => doAuthorizations(t),
+    recordPayment: o => doPayment(null, o),
+    recordPaymentFor: (t, o) => doPayment(t, o),
+    statement: o => doStatement(null, o),
+    statementFor: (t, o) => doStatement(t, o),
+    line: () => doLine(null),
+    lineFor: t => doLine(t),
+  }
+}