pipework 0.252.0 → 0.253.0

package/src/async/steps/hash.ts

@@ -0,0 +1,40 @@
+// Content hashing for step results. A result is identified by what it was made from,
+// so two values hash alike exactly when their canonical JSON is the same.
+
+import { createHash } from 'node:crypto'
+
+/** JSON with object keys sorted at every depth; `undefined` members are dropped as in JSON.stringify. */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value))
+}
+
+function canonicalize(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(v => canonicalize(v === undefined ? null : v))
+  const toJson = (value as { toJSON?: () => unknown }).toJSON
+  if (typeof toJson === 'function') return canonicalize(toJson.call(value))
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(value).sort()) {
+    const member = (value as Record<string, unknown>)[key]
+    if (member !== undefined) out[key] = canonicalize(member)
+  }
+  return out
+}
+
+export function sha256Hex(text: string): string {
+  return createHash('sha256').update(text).digest('hex')
+}
+
+/** The hash of a step result or an element: its canonical JSON. */
+export function valueHash(value: unknown): string {
+  return sha256Hex(canonicalJson(value === undefined ? null : value))
+}
+
+/** The hash of a request input: a stored file (an object with a `sha256` string) hashes by that field alone. */
+export function inputHash(value: unknown): string {
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const sha = (value as { sha256?: unknown }).sha256
+    if (typeof sha === 'string') return sha256Hex(canonicalJson({ sha256: sha }))
+  }
+  return valueHash(value)
+}

package/src/async/steps/index.ts

@@ -0,0 +1,7 @@
+export { defineGraph } from './graph.js'
+export { StepItemRunningError } from './errors.js'
+export { steps } from './namespace.js'
+export type {
+  GraphConfig, GraphStepDefinition, GraphStepContext, GraphForEachContext, GraphRunInfo, GraphFailure, GraphRunStatus,
+  RequestOptions, RequestResult, PlanOptions, PlanResult, StepPlan, StepCounts, TaskState, RunTask, RunStatus, EndedRun, EndedRunsOptions, DecideOptions, ScopeOptions, StepResultRecord, RemoveItemOptions, RemoveItemResult, StepGraph, GraphSelection, GraphHost,
+} from './types.js'

package/src/async/steps/namespace.ts

@@ -0,0 +1,7 @@
+import { defineGraph } from './graph.js'
+
+/** Step graphs over a job queue: results recorded by their inputs, only missing steps run. */
+export const steps = {
+  /** Defines a graph of named steps over a jobs Queue. Pass it to `createWorkerSurface({ graphs })` to run its steps. */
+  define: defineGraph,
+}

package/src/async/steps/table.ts

@@ -0,0 +1,97 @@
+// The three tables behind step graphs, all tenant-scoped (forced row-level security
+// in generated migrations). A graph registers them at define() time, so a worker
+// surface or `pipework generate` that has loaded a graph emits their DDL.
+
+import { define } from '../../data/domain/index.js'
+import { field } from '../../data/domain/field.js'
+import type { DefinedTable } from '../../data/domain/types.js'
+import { schema } from '../../data/schema/namespace.js'
+import { index, uniqueIndex } from '../../data/db/idx/index.js'
+
+export const STEP_RUN_STATUSES = ['running', 'done', 'failed', 'cancelled'] as const
+export const STEP_TASK_STATUSES = ['blocked', 'queued', 'waiting', 'done', 'reused', 'failed', 'cancelled'] as const
+
+/** Instance number of a step's single task, or of a fan-out step's expander. */
+export const SINGLE = -1
+
+export const stepRun = define('pipework_step_run', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  graph: field.text(),
+  item: field.text(),
+  targets: field.jsonb(schema.check.json()),
+  status: field.enum(STEP_RUN_STATUSES).default('running'),
+  priority: field.integer().default(0),
+  stepPriority: field.jsonb(schema.check.json()).nullable(),
+  inputs: field.jsonb(schema.check.json()),
+  traceId: field.uuid().nullable(),
+  traceRootId: field.uuid().nullable(),
+  traceStepId: field.uuid().nullable(),
+  actor: field.text().nullable(),
+  notified: field.boolean().default(false),
+  createdAt: field.timestamp().default('now'),
+  finishedAt: field.timestamp().nullable(),
+  error: field.jsonb(schema.check.json()).nullable(),
+}, {
+  indexes: (t) => ({
+    byItem: index('idx_pipework_step_run_item').on(t['tenantId'], t['graph'], t['item']),
+    byFinished: index('idx_pipework_step_run_finished').on(t['finishedAt']),
+  }),
+})
+
+export const stepTask = define('pipework_step_task', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  runId: field.uuid(),
+  step: field.text(),
+  instance: field.integer().default(SINGLE),
+  element: field.jsonb(schema.check.json()).nullable(),
+  status: field.enum(STEP_TASK_STATUSES).default('blocked'),
+  jobId: field.uuid().nullable(),
+  inputKey: field.text().nullable(),
+  resultId: field.uuid().nullable(),
+  error: field.jsonb(schema.check.json()).nullable(),
+}, {
+  indexes: (t) => ({
+    byInstance: uniqueIndex('uq_pipework_step_task_instance').on(t['runId'], t['step'], t['instance']),
+    byJob: index('idx_pipework_step_task_job').on(t['jobId']),
+  }),
+})
+
+export const stepResult = define('pipework_step_result', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  graph: field.text(),
+  item: field.text(),
+  step: field.text(),
+  version: field.integer(),
+  inputKey: field.text(),
+  instance: field.integer().default(SINGLE),
+  value: field.jsonb(schema.check.json()),
+  valueHash: field.text(),
+  createdAt: field.timestamp().default('now'),
+}, {
+  indexes: (t) => ({
+    byKey: uniqueIndex('uq_pipework_step_result_key')
+      .on(t['tenantId'], t['graph'], t['item'], t['step'], t['version'], t['inputKey'], t['instance']),
+    byCreated: index('idx_pipework_step_result_created').on(t['createdAt']),
+  }),
+})
+
+let registered = false
+
+/** Marks the step tables as in use, so `pipework generate` emits them. */
+export function registerStepTables(): void {
+  registered = true
+}
+
+/** Registered step table definitions — merged into `pipework generate` via internalDefinitions. */
+export function stepDefinitions(): ReadonlyMap<string, DefinedTable> {
+  return registered
+    ? new Map<string, DefinedTable>([
+      ['pipework_step_run', stepRun as unknown as DefinedTable],
+      ['pipework_step_task', stepTask as unknown as DefinedTable],
+      ['pipework_step_result', stepResult as unknown as DefinedTable],
+    ])
+    : new Map()
+}

package/src/async/steps/types.ts

@@ -0,0 +1,318 @@
+import type { DB } from '../../data/db/index.js'
+import type { Queue } from '../jobs/queue.js'
+import type { Handler } from '../../request/di/types.js'
+import type { Manifold } from '../../core/pipework.js'
+import type { DeadLetterInfo } from '../jobs/queue.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- a recorded result has the shape its step returned; the graph cannot know it, and callers read fields off it directly
+export type StepValue = any
+
+/** What a step's `run` (and `autoAccept`) is handed. */
+export interface GraphStepContext {
+  /** Each needed request input by its value; each needed step by its result — an array in instance order for a fan-out step, or that instance's one result for a step named in `byElement`. */
+  readonly needs: Readonly<Record<string, StepValue>>
+  /** The element this instance was made for; undefined outside a fan-out step. */
+  readonly element: StepValue
+  /** The instance number; null outside a fan-out step. */
+  readonly index: number | null
+  readonly item: string
+  /** The request inputs this step declared in `needs`. */
+  readonly inputs: Readonly<Record<string, unknown>>
+  readonly runId: string
+  /** The step job's 1-based attempt, counting an attempt a lost worker used. Not available in `autoAccept`. */
+  readonly attempt: number
+  /** The step job's attempt limit: the step's `maxAttempts`, else the queue's default. Not available in `autoAccept`. */
+  readonly maxAttempts: number
+  /** Aborted when `cancel()` is called in this process while the step runs. */
+  readonly signal: AbortSignal
+  /**
+   * Runs `fn` in its own short transaction on the graph's database, as the run's tenant (RLS applies),
+   * and commits it on return. `run` itself holds no transaction: it is never open while the step waits.
+   * In `autoAccept`, `fn` runs in the transaction that advances the run.
+   */
+  checkpoint<R>(fn: (tx: DB) => Promise<R>): Promise<R>
+  /**
+   * Registers `fn` to run, in registration order, in the transaction that records this step's result:
+   * the rows it writes and the result commit together or not at all. If `fn` throws, neither is kept,
+   * the attempt fails and the task stays queued. Not available in `autoAccept` (throws).
+   */
+  withResult(fn: (tx: DB) => Promise<void>): void
+}
+
+/** What a `forEach` is handed: the step's needs, before any element exists. */
+export type GraphForEachContext = Omit<GraphStepContext, 'element' | 'index' | 'signal' | 'checkpoint' | 'withResult' | 'attempt' | 'maxAttempts'>
+
+export interface GraphStepDefinition {
+  /** Part of the content key: bump it and the step (and what depends on it) runs again. */
+  readonly version: number
+  /** Request inputs and other steps this step reads. */
+  readonly needs?: readonly string[]
+  /** Makes this a fan-out step: one instance per element of the returned list. */
+  readonly forEach?: (ctx: GraphForEachContext) => readonly unknown[] | Promise<readonly unknown[]>
+  /**
+   * Names from `needs` that only choose the list. `forEach` sees them; they are not part of an instance's
+   * content key, and `run` and `autoAccept` do not see them. They are still needs: the step waits for them.
+   */
+  readonly forEachOnly?: readonly string[]
+  /**
+   * Names from `needs` that are fan-out steps. Makes this step a fan-out over the same list as they: it has
+   * no `forEach`; instance i's element is their instance i's element, it waits only for their instance i,
+   * its content key hashes only their instance i's result, and `needs[name]` holds that one result (not an
+   * array). Every name must share one list: each is a step with `forEach` or itself has `byElement` leading
+   * back to the same `forEach` step. A step needing a `byElement` step without listing it here gets the
+   * whole array, as for any fan-out step.
+   */
+  readonly byElement?: readonly string[]
+  /** The step's work; its JSON return value is the recorded result. */
+  readonly run?: (ctx: GraphStepContext) => unknown
+  /** The step waits for `decide()`, holding no worker. */
+  readonly person?: boolean
+  /** Person steps: a returned value (not undefined) records it and skips the wait. */
+  readonly autoAccept?: (ctx: Omit<GraphStepContext, 'attempt' | 'maxAttempts'>) => unknown
+  /**
+   * The priority of this step's own jobs (an integer), in place of the run's, for every run and every instance of a
+   * fan-out step. Higher is claimed first, across runs, per worker class. A measurement step sets one below every
+   * run priority in use: it is claimed after every other step, and its run still finishes. The steps it needs and
+   * the steps that need it keep the run's priority, as does the run's finish job.
+   */
+  readonly priority?: number
+  /** Attempts the step's job gets. Default: the queue's. */
+  readonly maxAttempts?: number
+  /**
+   * The longest one try of `run` may take, in milliseconds (a positive integer). A try that exceeds it is aborted
+   * through `signal` and counted as a failed attempt, so `maxAttempts` and dead-lettering apply; a `run` that
+   * ignores its signal still ends the try on time. The class's job timeout, if any, still applies on top.
+   */
+  readonly timeoutMs?: number
+  /**
+   * The class of worker that takes this step: letters, digits, "_" and "-", starting with a letter. Default "default".
+   * The step's job type is `pipework.step.<graph>` for the default class, `pipework.step.<graph>:<class>` otherwise.
+   */
+  readonly workers?: string
+}
+
+/** The run a callback is about. */
+export interface GraphRunInfo {
+  readonly runId: string
+  readonly item: string
+  readonly tenant: string
+}
+
+export interface GraphFailure extends GraphRunInfo {
+  readonly step: string
+  readonly error: unknown
+}
+
+export interface GraphConfig {
+  /** The graph's name; its step jobs have type `pipework.step.<name>`. */
+  readonly name: string
+  /** The queue whose table holds the step jobs. A worker surface running them must read the same table. */
+  readonly queue: Queue
+  /** Request input names a step may list in `needs`. */
+  readonly inputs?: readonly string[]
+  readonly steps: Readonly<Record<string, GraphStepDefinition>>
+  /** Default priority of a run. Default 0. */
+  readonly priority?: number
+  /** `sweep()` deletes results older than this many days. Default: never. */
+  readonly resultRetentionDays?: number
+  /** Session variable the tenant policies read. Default: the Manifold's `rls.sessionVar`, else `pipework.tenant_id`. */
+  readonly sessionVar?: string
+  /** Called once when a run is done, in the run's tenant Flow and a transaction. A throw fails the attempt that finished the run. */
+  readonly onDone?: (run: GraphRunInfo) => void | Promise<void>
+  /** Called once when a run fails, in the run's tenant Flow, in a savepoint; a throw is logged and swallowed. With tracing on it runs in its own job trace, under the failed step job's parent, inside a `pipework/steps:on-failed` step. */
+  readonly onFailed?: (failure: GraphFailure) => void | Promise<void>
+}
+
+export interface RequestOptions {
+  readonly item: string
+  /** The steps whose results are wanted. */
+  readonly targets: readonly string[]
+  readonly inputs?: Readonly<Record<string, unknown>>
+  readonly priority?: number
+  /** Priorities for named steps of this run only, in place of their definitions' `priority` and the run's. Keys must be steps of the graph; values integers. */
+  readonly stepPriority?: Readonly<Record<string, number>>
+  /** Default: the active Flow's tenant. */
+  readonly tenant?: string
+  /** Record the requesting Flow's actor (`auth.userId`) on the run; its step jobs, onDone and onFailed run with `auth = { userId }`. Default true. */
+  readonly carryActor?: boolean
+}
+
+export interface RequestResult {
+  readonly runId: string
+  /** Tasks already satisfied by a recorded result at the moment of the request. */
+  readonly reused: number
+  /** Step jobs the request enqueued. */
+  readonly queued: number
+}
+
+export interface PlanOptions {
+  readonly item: string
+  readonly targets: readonly string[]
+  readonly inputs?: Readonly<Record<string, unknown>>
+  readonly tenant?: string
+}
+
+export interface StepPlan {
+  /** Instances whose result is recorded. */
+  readonly reusable: number
+  /** Instances that must run; null when a fan-out step's list is not yet known. */
+  readonly toRun: number | null
+}
+
+export interface PlanResult {
+  readonly steps: Readonly<Record<string, StepPlan>>
+}
+
+export interface StepCounts {
+  readonly total: number
+  readonly done: number
+  readonly reused: number
+  readonly running: number
+  readonly waiting: number
+  readonly failed: number
+  readonly cancelled: number
+  /** Fan-out steps only: whether the step's list is known, i.e. its instances exist. */
+  readonly listKnown?: boolean
+}
+
+/** A task's state, classified as the step counts are. */
+export type TaskState = 'done' | 'reused' | 'running' | 'waiting' | 'failed' | 'cancelled'
+
+/** One task of a run. */
+export interface RunTask {
+  readonly step: string
+  /** The fan-out instance's index; -1 for a single step and for a fan-out's list task. */
+  readonly instance: number
+  /** The fan-out list's item for this instance; null for instance -1. */
+  readonly element: unknown
+  readonly state: TaskState
+}
+
+export type GraphRunStatus = 'running' | 'done' | 'failed' | 'cancelled'
+
+export interface RunStatus {
+  readonly status: GraphRunStatus
+  readonly steps: Readonly<Record<string, StepCounts>>
+  /** Every task of the run, in step order then instance order, fan-out list tasks (instance -1) included. */
+  readonly tasks: readonly RunTask[]
+  /** The inputs the run was requested with. */
+  readonly inputs: Readonly<Record<string, unknown>>
+  /** When the run ended; null while it runs. */
+  readonly finishedAt: Date | null
+}
+
+export interface EndedRunsOptions extends ScopeOptions {
+  /** Only these runs. */
+  readonly ids?: readonly string[]
+  /** Only runs that finished before this time. */
+  readonly finishedBefore?: Date
+  /** At most this many, oldest finish first. Default 1000. */
+  readonly limit?: number
+}
+
+/** A run of the graph that is no longer running. */
+export interface EndedRun {
+  readonly id: string
+  readonly tenant: string
+  readonly item: string
+  readonly status: Exclude<GraphRunStatus, 'running'>
+  readonly finishedAt: Date
+  /** The row's delivery flag: for a done run, true once onDone has run (or the graph has none); set at once for a failed run, so it does not show that onFailed ran. */
+  readonly notified: boolean
+}
+
+/** The tenant a call acts for; default the active Flow's. Needed under row-level security on a connection that has not set it. */
+export interface ScopeOptions {
+  readonly tenant?: string
+}
+
+/** One recorded result of a step. `instance` is -1 for a step that does not fan out. */
+export interface StepResultRecord {
+  readonly id: string
+  readonly step: string
+  readonly version: number
+  readonly instance: number
+  readonly value: unknown
+  readonly createdAt: Date
+}
+
+export interface RemoveItemOptions extends ScopeOptions {
+  /** A run still in progress: 'refuse' (default) throws StepItemRunningError and deletes nothing; 'cancel' cancels it first. */
+  readonly running?: 'refuse' | 'cancel'
+}
+
+export interface RemoveItemResult {
+  readonly runs: number
+  readonly tasks: number
+  readonly results: number
+}
+
+export interface DecideOptions extends ScopeOptions {
+  readonly runId: string
+  readonly step: string
+  /** The instance, for a fan-out person step. */
+  readonly index?: number
+  readonly value: unknown
+}
+
+/** Where a worker surface runs a graph: the Manifold and the database name its handlers use. */
+export interface GraphHost {
+  readonly instance: Manifold
+  readonly database: string | undefined
+}
+
+/** Some classes of a graph's steps, for a worker surface to take. */
+export interface GraphSelection {
+  readonly graph: StepGraph
+  readonly classes: readonly string[]
+}
+
+export interface StepGraph {
+  readonly name: string
+  /** `pipework.step.<name>`: the job type of the default class. */
+  readonly jobType: string
+  /** The job type of every class the graph's steps use. */
+  readonly jobTypes: readonly string[]
+  /** The queue the step jobs are enqueued on. */
+  readonly queue: Queue
+  /** Asks for the targets of an item. Only steps without a recorded result for their inputs run. */
+  request(db: DB, options: RequestOptions): Promise<RequestResult>
+  /** What a request would reuse and what it would run, without running anything. */
+  plan(db: DB, options: PlanOptions): Promise<PlanResult>
+  status(db: DB, runId: string, options?: ScopeOptions): Promise<RunStatus>
+  /** Cancels a running run: pending work is cancelled, no callback fires. */
+  cancel(db: DB, runId: string, options?: ScopeOptions): Promise<void>
+  /** Records a person's value on a waiting person step, or replaces it on a finished one. */
+  decide(db: DB, options: DecideOptions): Promise<void>
+  /** Resolves with the run's final status, or 'timeout'. */
+  wait(db: DB, runId: string, options: { readonly timeoutMs: number; readonly tenant?: string }): Promise<GraphRunStatus | 'timeout'>
+  /**
+   * Deletes, for one tenant, the results and the finished runs (with their tasks) older than `resultRetentionDays`;
+   * returns how many results. Runs in `options.tenant` or the Flow's; under forced row-level security a sweep with
+   * neither sees no rows, so sweep each tenant. On an owner connection with no tenant it sweeps all of them.
+   */
+  sweep(db: DB, options?: ScopeOptions): Promise<number>
+  /**
+   * The runs of this graph that have ended, oldest finish first, in `options.tenant` or the Flow's; under forced
+   * row-level security a call with neither sees no rows. On an owner connection with no tenant it lists every tenant's.
+   */
+  ended(db: DB, options?: EndedRunsOptions): Promise<readonly EndedRun[]>
+  /** Deletes a tenant's runs, tasks and results. */
+  removeTenant(db: DB, tenantId: string): Promise<void>
+  /** The results recorded for one item of this graph, in the tenant; their values hold whatever the steps returned (e.g. file references to remove). */
+  results(db: DB, item: string, options?: ScopeOptions): Promise<readonly StepResultRecord[]>
+  /** Deletes one item's runs, tasks and results in the caller's transaction and tenant. A done run not yet delivered gets no onDone. */
+  removeItem(db: DB, item: string, options?: RemoveItemOptions): Promise<RemoveItemResult>
+  /**
+   * A selection of the steps of the named worker classes, for `WorkerSurfaceConfig.graphs`; the graph itself selects all.
+   * Concurrency is per surface: run one worker surface per class, each with its own `concurrency`.
+   * Throws naming the graph and class when no step uses a class.
+   */
+  workers(...classes: string[]): GraphSelection
+  /** Used by the worker surface. */
+  readonly worker: {
+    /** One handler per class, or per selected class. */
+    handlers(database: string | undefined, classes?: readonly string[]): Handler<Record<string, unknown>, unknown>[]
+    onDeadLetter(tx: DB, job: DeadLetterInfo, host: GraphHost): Promise<void>
+  }
+}

package/src/audit/chain/index.ts

@@ -0,0 +1,9 @@
+export { installAuditChain } from './install.js'
+export { chainHead, verify, removeTenant } from './verify.js'
+export type {
+  AuditChainHead,
+  AuditChainBreak,
+  AuditChainBreakReason,
+  AuditVerifyOptions,
+  AuditVerifyResult,
+} from './verify.js'

package/src/audit/chain/install.ts

@@ -0,0 +1,113 @@
+// Installs the audit hash chain: head/retired bookkeeping tables, the
+// canonical-form function, and the triggers on `audit_record`. Everything is
+// CREATE OR REPLACE / IF NOT EXISTS, so installing twice is a no-op.
+//
+// The chain is written only by the BEFORE INSERT trigger: it locks the tenant's
+// head row, so concurrent writers to one chain queue behind each other and the
+// sequence is gapless (a rolled-back transaction releases the lock and leaves
+// no gap). A second trigger rejects UPDATE and DELETE; partition DROP, which
+// is how retention works, does not fire row triggers.
+
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { quoteIdentifier } from '../../data/db/identifiers.js'
+import { MAINTENANCE_SETTING } from '../../data/db/maintenance.js'
+
+/** Chain key of rows with no tenant — they form their own chain. */
+export const NULL_TENANT_CHAIN_KEY = '00000000-0000-0000-0000-000000000000'
+
+/** Set transaction-locally by `audit.removeTenant` to the one tenant whose rows may be deleted. */
+export const AUDIT_ERASE_SETTING = 'pipework.audit_erase_tenant'
+
+export const CHAIN_HEAD_TABLE = 'pipework_audit_chain_head'
+export const CHAIN_RETIRED_TABLE = 'pipework_audit_chain_retired'
+
+/** SQL expression for a row's chain key; the chain index is built on exactly this. */
+export const CHAIN_KEY_SQL = `coalesce(tenant_id, '${NULL_TENANT_CHAIN_KEY}'::uuid)`
+
+const GENESIS_HASH_HEX = '00'.repeat(32)
+
+/**
+ * The text hashed for one row. `jsonb_build_array(...)::text` of, in order:
+ * chain_seq, id, trace_day (YYYY-MM-DD), trace_id, trace_step_id, tenant_id,
+ * actor_id, entity, verb, before, after, captured_inputs, occurred_at (UTC,
+ * `YYYY-MM-DD"T"HH24:MI:SS.US"Z"`), then entity_id only when it is not null.
+ * A row without an entity_id (read-touches, rows written before the column
+ * existed) hashes exactly as it always did. Independent of the session TimeZone.
+ */
+export const CANONICAL_FUNCTION_SQL = `
+CREATE OR REPLACE FUNCTION pipework_audit_record_canonical(r audit_record) RETURNS text
+LANGUAGE sql IMMUTABLE SET search_path = pg_catalog AS $$
+  SELECT (jsonb_build_array(
+    r.chain_seq, r.id, to_char(r.trace_day, 'YYYY-MM-DD'), r.trace_id, r.trace_step_id,
+    r.tenant_id, r.actor_id, r.entity, r.verb, r.before, r.after, r.captured_inputs,
+    to_char(r.occurred_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')
+  ) || CASE WHEN r.entity_id IS NULL THEN '[]'::jsonb ELSE jsonb_build_array(r.entity_id) END)::text
+$$`
+
+function insertTriggerFunctionSql(schema: string): string {
+  return `
+CREATE OR REPLACE FUNCTION pipework_audit_chain_before_insert() RETURNS trigger
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, ${schema} AS $$
+DECLARE
+  k uuid := coalesce(NEW.tenant_id, '${NULL_TENANT_CHAIN_KEY}'::uuid);
+  h record;
+BEGIN
+  INSERT INTO ${CHAIN_HEAD_TABLE} (chain_key, seq, hash)
+    VALUES (k, 0, decode('${GENESIS_HASH_HEX}', 'hex'))
+    ON CONFLICT DO NOTHING;
+  SELECT seq, hash INTO h FROM ${CHAIN_HEAD_TABLE} WHERE chain_key = k FOR UPDATE;
+  NEW.chain_seq := h.seq + 1;
+  NEW.prev_hash := encode(h.hash, 'hex');
+  NEW.hash := encode(sha256(h.hash || convert_to(pipework_audit_record_canonical(NEW), 'UTF8')), 'hex');
+  UPDATE ${CHAIN_HEAD_TABLE} SET seq = NEW.chain_seq, hash = decode(NEW.hash, 'hex') WHERE chain_key = k;
+  RETURN NEW;
+END
+$$`
+}
+
+const APPEND_ONLY_FUNCTION_SQL = `
+CREATE OR REPLACE FUNCTION pipework_audit_chain_append_only() RETURNS trigger
+LANGUAGE plpgsql SET search_path = pg_catalog AS $$
+BEGIN
+  IF TG_OP = 'DELETE'
+     AND current_setting('${MAINTENANCE_SETTING}', true) = 'on'
+     AND OLD.tenant_id::text = current_setting('${AUDIT_ERASE_SETTING}', true) THEN
+    RETURN OLD;
+  END IF;
+  RAISE EXCEPTION 'audit_record is append-only: % is not allowed', TG_OP
+    USING ERRCODE = 'restrict_violation';
+END
+$$`
+
+/**
+ * Install the audit hash chain on `audit_record`. The table must exist.
+ * Idempotent.
+ */
+export async function installAuditChain(db: DB): Promise<void> {
+  const schemaRows = await db.execute(sql`SELECT current_schema() AS schema`)
+  const schema = quoteIdentifier(String(schemaRows[0]!['schema']), 'schema')
+
+  await db.execute(sql.raw(
+    `CREATE TABLE IF NOT EXISTS ${CHAIN_HEAD_TABLE} (` +
+    `chain_key uuid PRIMARY KEY, seq bigint NOT NULL, hash bytea NOT NULL)`,
+  ))
+  await db.execute(sql.raw(
+    `CREATE TABLE IF NOT EXISTS ${CHAIN_RETIRED_TABLE} (` +
+    `chain_key uuid NOT NULL, seq bigint NOT NULL, hash bytea NOT NULL, PRIMARY KEY (chain_key, seq))`,
+  ))
+  await db.execute(sql.raw(CANONICAL_FUNCTION_SQL))
+  await db.execute(sql.raw(insertTriggerFunctionSql(schema)))
+  await db.execute(sql.raw(APPEND_ONLY_FUNCTION_SQL))
+  await db.execute(sql.raw(
+    `CREATE OR REPLACE TRIGGER pipework_audit_chain_insert BEFORE INSERT ON audit_record ` +
+    `FOR EACH ROW EXECUTE FUNCTION pipework_audit_chain_before_insert()`,
+  ))
+  await db.execute(sql.raw(
+    `CREATE OR REPLACE TRIGGER pipework_audit_chain_append_only BEFORE UPDATE OR DELETE ON audit_record ` +
+    `FOR EACH ROW EXECUTE FUNCTION pipework_audit_chain_append_only()`,
+  ))
+  await db.execute(sql.raw(
+    `CREATE INDEX IF NOT EXISTS audit_record_chain_idx ON audit_record ((${CHAIN_KEY_SQL}), chain_seq)`,
+  ))
+}

package/src/audit/chain/retire.ts

@@ -0,0 +1,52 @@
+// Retention for the audit chain: before an `audit_record` day partition is
+// dropped, its (seq, hash) pairs move to the retired table so the rows that
+// remain still link to the ones that went.
+
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { CHAIN_HEAD_TABLE, CHAIN_RETIRED_TABLE, CHAIN_KEY_SQL } from './install.js'
+
+/** True when the chain tables exist, i.e. the chain was installed on this database. */
+export async function auditChainInstalled(db: DB): Promise<boolean> {
+  const rows = await db.execute(sql`
+    SELECT to_regclass(${CHAIN_HEAD_TABLE}) IS NOT NULL
+       AND to_regclass(${CHAIN_RETIRED_TABLE}) IS NOT NULL AS installed
+  `)
+  return rows[0]?.['installed'] === true
+}
+
+/**
+ * Removes one tenant's chain: its head and its retired entries. Run inside the
+ * same maintenance transaction that deletes the tenant's records.
+ */
+export async function removeTenantChain(tx: DB, tenantId: string): Promise<void> {
+  await tx.execute(sql`DELETE FROM ${sql.raw(CHAIN_HEAD_TABLE)} WHERE chain_key = ${tenantId}::uuid`)
+  await tx.execute(sql`DELETE FROM ${sql.raw(CHAIN_RETIRED_TABLE)} WHERE chain_key = ${tenantId}::uuid`)
+}
+
+/**
+ * Retire and drop one audit partition. Run inside a transaction. `child` is the
+ * already-quoted partition name.
+ *
+ * After the drop, a chain keeps only the retired entries at or above
+ * `(lowest remaining seq) - 1` — the one entry the oldest remaining row links
+ * to. A chain with no rows left keeps just its highest retired entry.
+ */
+export async function retireAuditPartition(tx: DB, child: string): Promise<void> {
+  // The pruning DELETE below scans every audit partition; with a few hundred
+  // partitions Postgres spends tens of seconds JIT-compiling it (measured 10s
+  // with no row-level security, 20s with it) to save milliseconds.
+  await tx.execute(sql`SELECT set_config('jit', 'off', true)`)
+  await tx.execute(sql.raw(
+    `INSERT INTO ${CHAIN_RETIRED_TABLE} (chain_key, seq, hash) ` +
+    `SELECT ${CHAIN_KEY_SQL}, chain_seq, decode(hash, 'hex') FROM ${child} ` +
+    `WHERE chain_seq IS NOT NULL ON CONFLICT DO NOTHING`,
+  ))
+  await tx.execute(sql.raw(`DROP TABLE IF EXISTS ${child}`))
+  await tx.execute(sql.raw(
+    `DELETE FROM ${CHAIN_RETIRED_TABLE} r WHERE r.seq < coalesce(` +
+    `(SELECT min(a.chain_seq) - 1 FROM audit_record a ` +
+    `WHERE ${CHAIN_KEY_SQL.replace('tenant_id', 'a.tenant_id')} = r.chain_key AND a.chain_seq IS NOT NULL), ` +
+    `(SELECT max(x.seq) FROM ${CHAIN_RETIRED_TABLE} x WHERE x.chain_key = r.chain_key))`,
+  ))
+}