pipework 0.251.0 → 0.252.1

package/src/audit/chain/verify.ts

@@ -0,0 +1,257 @@
+// `audit.chainHead` and `audit.verify` — the read side of the audit hash chain.
+//
+// Both act on the active Flow's tenant chain; outside a tenant scope they act
+// on the chain of rows with no tenant. The recompute runs in SQL
+// (`pipework_audit_record_canonical`), so what is checked is exactly what the
+// trigger hashed.
+
+import { auditRecord } from '../schema/audit-record.js'
+import { pipeRaw } from '../../data/db/db.js'
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { withMaintenance } from '../../data/db/maintenance.js'
+import { getContext } from '../../request/context/store.js'
+import { ValidationError } from '../../core/errors/index.js'
+import {
+  CHAIN_HEAD_TABLE,
+  CHAIN_RETIRED_TABLE,
+  CHAIN_KEY_SQL,
+  NULL_TENANT_CHAIN_KEY,
+  AUDIT_ERASE_SETTING,
+} from './install.js'
+import { auditChainInstalled, removeTenantChain } from './retire.js'
+
+/** A chain position: the sequence number and the record's lowercase-hex SHA-256. */
+export interface AuditChainHead {
+  readonly seq: number
+  readonly hash: string
+}
+
+export type AuditChainBreakReason =
+  | 'hash-mismatch'
+  | 'prev-mismatch'
+  | 'missing'
+  | 'head-mismatch'
+  | 'anchor-mismatch'
+
+export interface AuditChainBreak {
+  readonly seq: number
+  /** The record at `seq`, or null when none exists. */
+  readonly recordId: string | null
+  readonly reason: AuditChainBreakReason
+}
+
+export interface AuditVerifyOptions {
+  /** Inclusive lower bound on the chain sequence. */
+  readonly fromSeq?: number
+  /** Inclusive upper bound. With any upper bound, the chain head is not compared. */
+  readonly toSeq?: number
+  /** Start at the first record with `occurredAt >= from`. */
+  readonly from?: Date
+  /** End at the last record with `occurredAt < to`. */
+  readonly to?: Date
+  /** A (seq, hash) pair the caller stored earlier; the chain must still hold it. */
+  readonly anchor?: AuditChainHead
+}
+
+export type AuditVerifyResult =
+  | { readonly ok: true; readonly checked: number; readonly head: AuditChainHead | null }
+  | { readonly ok: false; readonly checked: number; readonly break: AuditChainBreak }
+
+const BATCH_SIZE = 1000
+const GENESIS_HASH = '0'.repeat(64)
+
+function chainKey(): string {
+  return getContext()?.tenant ?? NULL_TENANT_CHAIN_KEY
+}
+
+function toSeq(value: unknown): number {
+  return Number(value)
+}
+
+async function readHead(db: DB, key: string): Promise<AuditChainHead | null> {
+  const rows = await db.execute(sql`
+    SELECT seq, encode(hash, 'hex') AS hash FROM ${sql.raw(CHAIN_HEAD_TABLE)}
+    WHERE chain_key = ${key}::uuid AND seq > 0
+  `)
+  const row = rows[0]
+  return row === undefined ? null : { seq: toSeq(row['seq']), hash: row['hash'] as string }
+}
+
+/**
+ * The newest record's position in the tenant's chain, for the app to store
+ * outside the database. `null` when the chain has no records yet.
+ */
+export async function chainHead(): Promise<AuditChainHead | null> {
+  return readHead(pipeRaw(auditRecord.$options.database), chainKey())
+}
+
+/**
+ * Walks the tenant's chain and reports the first break. Every seq in the
+ * checked range is examined: a record is recomputed from its fields, linked to
+ * the one before it, and a missing seq is a break.
+ */
+export async function verify(options: AuditVerifyOptions = {}): Promise<AuditVerifyResult> {
+  for (const [name, value] of [['fromSeq', options.fromSeq], ['toSeq', options.toSeq]] as const) {
+    if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
+      throw new ValidationError(`audit.verify: ${name} must be a positive integer (got ${String(value)}).`)
+    }
+  }
+  const db = pipeRaw(auditRecord.$options.database)
+  const key = chainKey()
+  // Rows with no tenant are visible to no tenant setting, so the tenantless chain is read as a maintenance pass.
+  if (key === NULL_TENANT_CHAIN_KEY) return withMaintenance(db, tx => verifyChain(tx, key, options))
+  return verifyChain(db, key, options)
+}
+
+async function verifyChain(db: DB, key: string, options: AuditVerifyOptions): Promise<AuditVerifyResult> {
+  const keyMatch = sql`${sql.raw(CHAIN_KEY_SQL)} = ${key}::uuid`
+  const bounded = options.toSeq !== undefined || options.to !== undefined
+
+  const head = await readHead(db, key)
+
+  // Resolve the range [lo, hi].
+  let lo = options.fromSeq ?? 1
+  if (options.fromSeq === undefined && options.from === undefined) {
+    const r = await db.execute(sql`
+      SELECT min(seq) AS seq FROM ${sql.raw(CHAIN_RETIRED_TABLE)} WHERE chain_key = ${key}::uuid
+    `)
+    if (r[0]?.['seq'] !== null && r[0]?.['seq'] !== undefined) lo = toSeq(r[0]['seq'])
+  }
+  const maxRow = await db.execute(sql`
+    SELECT max(chain_seq) AS seq FROM audit_record
+    WHERE ${keyMatch} AND chain_seq IS NOT NULL
+  `)
+  // Stop at the head read above: a row committed since then must not read as a head mismatch.
+  let hi = head !== null
+    ? head.seq
+    : maxRow[0]?.['seq'] === null || maxRow[0]?.['seq'] === undefined ? 0 : toSeq(maxRow[0]['seq'])
+  if (options.from !== undefined) {
+    const r = await db.execute(sql`
+      SELECT min(chain_seq) AS seq FROM audit_record
+      WHERE ${keyMatch} AND chain_seq IS NOT NULL AND occurred_at >= ${options.from.toISOString()}::timestamptz
+    `)
+    if (r[0]?.['seq'] === null || r[0]?.['seq'] === undefined) return { ok: true, checked: 0, head }
+    lo = Math.max(lo, toSeq(r[0]['seq']))
+  }
+  if (options.to !== undefined) {
+    const r = await db.execute(sql`
+      SELECT max(chain_seq) AS seq FROM audit_record
+      WHERE ${keyMatch} AND chain_seq IS NOT NULL AND occurred_at < ${options.to.toISOString()}::timestamptz
+    `)
+    if (r[0]?.['seq'] === null || r[0]?.['seq'] === undefined) return { ok: true, checked: 0, head }
+    hi = Math.min(hi, toSeq(r[0]['seq']))
+  }
+  if (options.toSeq !== undefined) hi = options.toSeq
+
+  // Retired entries inside the range count as present; the one just below it is the first link.
+  const retiredRows = await db.execute(sql`
+    SELECT seq, encode(hash, 'hex') AS hash FROM ${sql.raw(CHAIN_RETIRED_TABLE)}
+    WHERE chain_key = ${key}::uuid AND seq >= ${lo - 1} AND seq <= ${hi}
+  `)
+  const retired = new Map<number, string>(retiredRows.map(r => [toSeq(r['seq']), r['hash'] as string]))
+
+  let last: string | undefined
+  if (lo === 1) last = GENESIS_HASH
+  else {
+    last = retired.get(lo - 1)
+    if (last === undefined) {
+      const r = await db.execute(sql`
+        SELECT hash FROM audit_record WHERE ${keyMatch} AND chain_seq = ${lo - 1}
+      `)
+      last = r[0]?.['hash'] as string | undefined
+    }
+  }
+
+  let checked = 0
+  let expected = lo
+  let tail: AuditChainHead | null = null
+  const fail = (seq: number, recordId: string | null, reason: AuditChainBreakReason): AuditVerifyResult =>
+    ({ ok: false, checked, break: { seq, recordId, reason } })
+
+  while (expected <= hi) {
+    const batch = await db.execute(sql`
+      SELECT a.chain_seq AS seq, a.id, a.prev_hash, a.hash,
+        encode(sha256(decode(a.prev_hash, 'hex') || convert_to(pipework_audit_record_canonical(a), 'UTF8')), 'hex') = a.hash AS intact
+      FROM audit_record a
+      WHERE ${keyMatch} AND a.chain_seq >= ${expected} AND a.chain_seq <= ${hi}
+      ORDER BY a.chain_seq, a.id
+      LIMIT ${BATCH_SIZE}
+    `)
+    if (batch.length === 0) {
+      for (; expected <= hi; expected++) {
+        const hash = retired.get(expected)
+        if (hash === undefined) return fail(expected, null, 'missing')
+        last = hash
+      }
+      break
+    }
+    for (const row of batch) {
+      const seq = toSeq(row['seq'])
+      const id = row['id'] as string
+      for (; expected < seq; expected++) {
+        const hash = retired.get(expected)
+        if (hash === undefined) return fail(expected, null, 'missing')
+        last = hash
+      }
+      if (seq < expected) return fail(seq, id, 'hash-mismatch')
+      if (row['intact'] !== true) return fail(seq, id, 'hash-mismatch')
+      if (last === undefined) return fail(seq - 1, null, 'missing')
+      if (row['prev_hash'] !== last) return fail(seq, id, 'prev-mismatch')
+      last = row['hash'] as string
+      tail = { seq, hash: last }
+      checked++
+      expected = seq + 1
+    }
+  }
+
+  if (!bounded) {
+    const top = tail ?? await highestRetired(db, key)
+    const expectedHead = head
+    if ((top === null) !== (expectedHead === null) || (top !== null && expectedHead !== null &&
+        (top.seq !== expectedHead.seq || top.hash !== expectedHead.hash))) {
+      return fail(expectedHead?.seq ?? top?.seq ?? 0, null, 'head-mismatch')
+    }
+  }
+
+  if (options.anchor !== undefined) {
+    const { seq, hash } = options.anchor
+    const r = await db.execute(sql`
+      SELECT hash FROM audit_record WHERE ${keyMatch} AND chain_seq = ${seq}
+      UNION ALL
+      SELECT encode(hash, 'hex') FROM ${sql.raw(CHAIN_RETIRED_TABLE)} WHERE chain_key = ${key}::uuid AND seq = ${seq}
+    `)
+    if (!r.some(row => row['hash'] === hash)) return fail(seq, null, 'anchor-mismatch')
+  }
+
+  return { ok: true, checked, head }
+}
+
+async function highestRetired(db: DB, key: string): Promise<AuditChainHead | null> {
+  const rows = await db.execute(sql`
+    SELECT seq, encode(hash, 'hex') AS hash FROM ${sql.raw(CHAIN_RETIRED_TABLE)}
+    WHERE chain_key = ${key}::uuid ORDER BY seq DESC LIMIT 1
+  `)
+  const row = rows[0]
+  return row === undefined ? null : { seq: toSeq(row['seq']), hash: row['hash'] as string }
+}
+
+/**
+ * Deletes every audit record of one tenant, and its hash chain, for the closure
+ * of that tenant's account. Irreversible. Other tenants' records and chains are
+ * untouched and still verify. Returns the number of records removed; a second
+ * call returns 0. Runs as a maintenance pass naming this tenant, so the app
+ * role still cannot delete audit rows.
+ */
+export async function removeTenant(tenantId: string): Promise<number> {
+  if (typeof tenantId !== 'string' || tenantId.trim() === '') {
+    throw new ValidationError('audit.removeTenant: tenantId must be a non-empty string.')
+  }
+  const db = pipeRaw(auditRecord.$options.database)
+  return withMaintenance(db, async tx => {
+    await tx.execute(sql`SELECT set_config(${AUDIT_ERASE_SETTING}, ${tenantId}, true)`)
+    const removed = await tx.execute(sql`DELETE FROM audit_record WHERE tenant_id = ${tenantId}::uuid RETURNING 1`)
+    if (await auditChainInstalled(tx)) await removeTenantChain(tx, tenantId)
+    return removed.length
+  })
+}

package/src/audit/query/cursor.ts

@@ -0,0 +1,37 @@
+// Opaque cursor for audit-trail keyset pagination. Encodes `(occurredAt, id)`
+// as a base64url JSON tuple — the same encoding the rest of pipework's
+// cursor-paginated surfaces use. `occurredAt` is the row's time as text,
+// UTC to the microsecond, because a JS Date holds only milliseconds and rows
+// within one millisecond would be lost or repeated. `id` breaks ties between
+// rows with the same time (a single CTE can emit N audit rows for fan-out
+// targets), so the (occurredAt, id) pair is unique and totally ordered.
+
+import { encodeCursor, decodeCursor } from '../../request/fixture/paginate.js'
+import { ValidationError } from '../../core/errors/index.js'
+
+export interface AuditCursor {
+  /** The row's time in UTC to the microsecond: `YYYY-MM-DDTHH:MM:SS.ffffffZ`. Older cursors carry milliseconds; both decode. */
+  readonly occurredAt: string
+  readonly id: string
+}
+
+export function encodeAuditCursor(cursor: AuditCursor): string {
+  return encodeCursor([cursor.occurredAt, cursor.id])
+}
+
+export function decodeAuditCursor(raw: string): AuditCursor {
+  const parts = decodeCursor(raw)
+  if (parts.length !== 2 || typeof parts[0] !== 'string' || typeof parts[1] !== 'string') {
+    throw new ValidationError(
+      'Invalid audit cursor: expected [occurredAt, id] tuple. ' +
+      'Cursors are opaque — pass the value returned by audit.query unchanged.',
+    )
+  }
+  if (Number.isNaN(new Date(parts[0]).getTime())) {
+    throw new ValidationError(
+      `Invalid audit cursor: "${parts[0]}" is not a valid ISO timestamp. ` +
+      'Cursors are opaque — pass the value returned by audit.query unchanged.',
+    )
+  }
+  return { occurredAt: parts[0], id: parts[1] }
+}

package/src/audit/query/index.ts

@@ -0,0 +1,9 @@
+export { query } from './query.js'
+export type {
+  AuditQueryFilters,
+  AuditQueryOptions,
+  AuditQueryResult,
+  AuditRecordRow,
+} from './query.js'
+export { encodeAuditCursor, decodeAuditCursor } from './cursor.js'
+export type { AuditCursor } from './cursor.js'

package/src/audit/query/query.ts

@@ -0,0 +1,223 @@
+// `audit.query` — the read side of the audit-trail substrate. Plumb (and any
+// other consumer) builds its audit UI against this contract; the column
+// shape of `audit_record` is the schema-versioned commitment, and `query`
+// is the surface for filtering and paging over it.
+//
+// Tenant scoping is implicit — the function uses `pipe()`, which applies the
+// active Flow's tenant filter at the proxy layer. Run outside a tenant scope
+// for cross-tenant visibility (admin / system contexts).
+//
+// Pagination is keyset on `(occurredAt, id)` — stable under inserts, no
+// `OFFSET` cost. Default order is descending (newest first); `asc: true`
+// inverts both the ORDER BY and the cursor inequality.
+
+import { auditRecord } from '../schema/audit-record.js'
+import { pipeRaw } from '../../data/db/db.js'
+import { getContext } from '../../request/context/store.js'
+import {
+  and,
+  eq,
+  gt,
+  gte,
+  lt,
+  lte,
+  inArray,
+  desc,
+  asc,
+  or,
+  getTableColumns,
+} from '../../data/query/index.js'
+import { sql } from '../../data/db/sql.js'
+import type { SQL, Column } from '../../data/db/types.js'
+import { ValidationError } from '../../core/errors/index.js'
+import {
+  encodeAuditCursor,
+  decodeAuditCursor,
+  type AuditCursor,
+} from './cursor.js'
+
+/**
+ * Inferred row shape from the `audit_record` definition. The query result is
+ * typed against this — re-exported so consumers don't have to reach into
+ * `src/audit/schema/`.
+ */
+export type AuditRecordRow = typeof auditRecord.Select
+
+export interface AuditQueryFilters {
+  /** Match audit rows whose `entity` is in this set. Single string accepted as shorthand. */
+  readonly entity?: string | readonly string[]
+  /**
+   * Match audit rows written for the row with this primary key — one row's history, served by an index on `(tenantId, entity, entityId, occurredAt, id)`. Requires `entity`. The text is the key's value, or for a composite key `audit.entityId(table, row)`; access-link rows carry the link id. Rows written before `entityId` existed, and read-touches rows, have none and never match.
+   */
+  readonly entityId?: string
+  /** Match audit rows whose `verb` is in this set. Single string accepted as shorthand. */
+  readonly verb?: string | readonly string[]
+  /** Match audit rows whose `actorId` equals this. `null` matches system-actor rows. */
+  readonly actorId?: string | null
+  /** Match audit rows emitted under this trace. */
+  readonly traceId?: string
+  /** Match audit rows emitted under this specific flow step. */
+  readonly traceStepId?: string
+  /** Inclusive lower bound on `traceDay`. The partition-pruning hint Postgres uses to skip irrelevant partitions. */
+  readonly traceDayFrom?: string
+  /** Inclusive upper bound on `traceDay`. */
+  readonly traceDayTo?: string
+  /** Inclusive lower bound on `occurredAt`. */
+  readonly occurredFrom?: Date
+  /** Exclusive upper bound on `occurredAt`. */
+  readonly occurredTo?: Date
+}
+
+export interface AuditQueryOptions {
+  /** Max rows to return. Default 50, hard cap 500 — exceeding it throws. */
+  readonly limit?: number
+  /** Opaque cursor from a previous page's result. */
+  readonly cursor?: string
+  /** `false` (default) returns newest-first; `true` returns oldest-first. */
+  readonly asc?: boolean
+}
+
+export interface AuditQueryResult {
+  readonly rows: readonly AuditRecordRow[]
+  /** Opaque cursor for the next page; `null` when this page is the last. */
+  readonly cursor: string | null
+  /** `true` when more rows exist past this page. */
+  readonly hasMore: boolean
+}
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 500
+/** Selected alongside the table's columns: the row's time to the microsecond, which a JS Date cannot hold. */
+const EXACT_TIME = '__occurredAtExact'
+
+/**
+ * Returns a page of `audit_record` rows matching `filters`, ordered by
+ * `(occurredAt, id)`. Pass `result.cursor` back as `options.cursor` to get
+ * the next page; stop when `cursor` is `null`.
+ */
+export async function query(
+  filters: AuditQueryFilters = {},
+  options: AuditQueryOptions = {},
+): Promise<AuditQueryResult> {
+  const limit = resolveLimit(options.limit)
+  const ascending = options.asc === true
+
+  const table = auditRecord.table()
+  const cols = table as unknown as Record<string, Column>
+
+  if (filters.entityId !== undefined && (filters.entity === undefined || (Array.isArray(filters.entity) && filters.entity.length === 0))) {
+    throw new ValidationError(
+      'audit.query: entityId requires entity. A row id is only meaningful within one entity — ' +
+      'pass { entity: "Item", entityId } (use audit.entityId(table, row) for a composite key).',
+    )
+  }
+
+  const conditions: SQL[] = []
+  appendFilter(conditions, filters.entity, v => buildInOrEq(cols['entity']!, v))
+  appendFilter(conditions, filters.verb, v => buildInOrEq(cols['verb']!, v))
+  if (filters.entityId !== undefined) conditions.push(eq(cols['entityId']!, filters.entityId))
+  if (filters.actorId !== undefined) {
+    conditions.push(eq(cols['actorId']!, filters.actorId))
+  }
+  if (filters.traceId !== undefined) conditions.push(eq(cols['traceId']!, filters.traceId))
+  if (filters.traceStepId !== undefined) conditions.push(eq(cols['traceStepId']!, filters.traceStepId))
+  if (filters.traceDayFrom !== undefined) conditions.push(gte(cols['traceDay']!, filters.traceDayFrom))
+  if (filters.traceDayTo !== undefined) conditions.push(lte(cols['traceDay']!, filters.traceDayTo))
+  if (filters.occurredFrom !== undefined) conditions.push(gte(cols['occurredAt']!, filters.occurredFrom))
+  if (filters.occurredTo !== undefined) conditions.push(lt(cols['occurredAt']!, filters.occurredTo))
+
+  if (options.cursor !== undefined) {
+    conditions.push(buildCursorClause(decodeAuditCursor(options.cursor), cols, ascending))
+  }
+
+  const tenant = getContext()?.tenant ?? null
+  if (tenant !== null) {
+    conditions.push(eq(cols['tenantId']!, tenant))
+  }
+
+  const exactTime = sql<string>`to_char(${cols['occurredAt']!} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`
+  const orderBy = ascending
+    ? [asc(cols['occurredAt']!), asc(cols['id']!)]
+    : [desc(cols['occurredAt']!), desc(cols['id']!)]
+
+  const db = pipeRaw(auditRecord.$options.database)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle's select/from/where chain is deeply generic; the column lookup is validated against the audit_record table at call time
+  let q: any = (db as any).select({ ...getTableColumns(table), [EXACT_TIME]: exactTime }).from(table)
+  if (conditions.length > 0) {
+    q = q.where(conditions.length === 1 ? conditions[0]! : and(...conditions))
+  }
+  q = q.orderBy(...orderBy).limit(limit + 1)
+
+  const fetched = (await q) as Array<AuditRecordRow & { [EXACT_TIME]: string }>
+  const hasMore = fetched.length > limit
+  const page = hasMore ? fetched.slice(0, limit) : fetched
+  const cursor = buildNextCursor(page, hasMore)
+  const items = page.map(row => {
+    const rest: Record<string, unknown> = { ...row }
+    delete rest[EXACT_TIME]
+    return rest as unknown as AuditRecordRow
+  })
+  return { rows: items, cursor, hasMore }
+}
+
+function resolveLimit(requested: number | undefined): number {
+  if (requested === undefined) return DEFAULT_LIMIT
+  if (!Number.isInteger(requested) || requested < 1) {
+    throw new ValidationError(
+      `audit.query: limit must be a positive integer (got ${String(requested)}). ` +
+      `Default is ${DEFAULT_LIMIT}; max is ${MAX_LIMIT}.`,
+    )
+  }
+  if (requested > MAX_LIMIT) {
+    throw new ValidationError(
+      `audit.query: limit ${requested} exceeds max ${MAX_LIMIT}. ` +
+      `Page through results instead of requesting a larger window.`,
+    )
+  }
+  return requested
+}
+
+function appendFilter<T>(
+  conditions: SQL[],
+  value: T | readonly T[] | undefined,
+  build: (value: T | readonly T[]) => SQL,
+): void {
+  if (value === undefined) return
+  if (Array.isArray(value) && value.length === 0) return
+  conditions.push(build(value))
+}
+
+function buildInOrEq(column: Column, value: string | readonly string[]): SQL {
+  if (typeof value === 'string') return eq(column, value)
+  if (value.length === 1) return eq(column, value[0])
+  return inArray(column, [...value])
+}
+
+/**
+ * Encodes the keyset lookahead `(occurredAt, id) < cursor` (or `>` when
+ * ascending). Postgres supports tuple comparison, but drizzle's operator set
+ * doesn't expose it directly, so we expand to the lexicographic form:
+ *   occurredAt < $0  OR  (occurredAt = $0 AND id < $1)
+ * The time is bound as text and cast in SQL so it keeps its microseconds.
+ */
+function buildCursorClause(cursor: AuditCursor, cols: Record<string, Column>, ascending: boolean): SQL {
+  const occurredAt = cols['occurredAt']!
+  const id = cols['id']!
+  const at = sql`${cursor.occurredAt}::timestamptz`
+  if (ascending) {
+    return or(
+      sql`${occurredAt} > ${at}`,
+      and(sql`${occurredAt} = ${at}`, gt(id, cursor.id))!,
+    )!
+  }
+  return or(
+    sql`${occurredAt} < ${at}`,
+    and(sql`${occurredAt} = ${at}`, lt(id, cursor.id))!,
+  )!
+}
+
+function buildNextCursor(items: ReadonlyArray<{ readonly id: string; readonly [EXACT_TIME]: string }>, hasMore: boolean): string | null {
+  if (!hasMore || items.length === 0) return null
+  const last = items[items.length - 1]!
+  return encodeAuditCursor({ occurredAt: last[EXACT_TIME], id: last.id })
+}

package/src/audit/schema/audit-record-fields.ts

@@ -0,0 +1,68 @@
+// The column shape for `audit_record` — the durable per-(entity × affected
+// row) projection of `@touches`-annotated flow steps. The audit substrate
+// shares the trace's day-partition key (`traceDay`) so audit rows file under
+// the same calendar day as the trace step that emitted them, but the audit
+// table has independent retention: long / indefinite, configured separately
+// from the hot trace tables. There is no `_retained` cousin — audit_record
+// IS the durable store.
+//
+// Each row is one (entity, affected db row) tuple from a write-touches CTE
+// (write path) or a single emission at step completion (read-touches). The
+// `before` / `after` jsonb columns carry server-side `.traceSafe()`
+// projections — never raw rows. `capturedInputs` is a convenience copy of
+// the originating trace_step's captured inputs so audit queries don't have
+// to join. `occurredAt` records when the operation completed.
+
+import { field } from '../../data/domain/index.js'
+import { schema } from '../../data/schema/namespace.js'
+import { trace } from '../../trace/schema/trace.js'
+import { traceStep } from '../../trace/schema/trace-step.js'
+
+export const auditRecordFields = {
+  id: field.uuid().brand('AuditRecordId').defaultRandom(),
+  // Partition key — the parent trace's `openedDay`. The audit row files under
+  // the same calendar day as its trace step; retention is independent of
+  // trace storage so the partition can outlive the trace it came from.
+  traceDay: field.date(),
+  // Logical reference to the originating trace. `enforced: false` means the
+  // brand is inherited (TraceId) but no FK constraint is emitted — trace's
+  // partition can retire while the audit row is still in retention.
+  traceId: field.uuid().references(trace, 'id', { enforced: false }),
+  // Logical reference to the originating trace step. Same retention argument
+  // as `traceId` — branded TraceStepId without an enforced FK.
+  traceStepId: field.uuid().references(traceStep, 'id', { enforced: false }),
+  tenantId: field.uuid().tenant().nullable(),
+  // The user who performed the action. Null for system-actor traces (cron,
+  // worker-claimed jobs without an auth principal). Plain text, not branded —
+  // audit lives downstream of auth, no need to enforce a userId brand here.
+  actorId: field.text().nullable(),
+  // The `@touches Entity:verb` annotation, split into entity and verb. Both
+  // non-null — a `@touches` annotation requires both halves.
+  entity: field.text(),
+  verb: field.text(),
+  // The audited row's primary key as text: the single key's value, or for a
+  // composite key a JSON array of the key values (as text, in key order). Null
+  // on read-touches rows and on rows written before the column existed.
+  // Indexed with the tenant and entity so one row's history is an index range.
+  entityId: field.text().nullable(),
+  // Server-side `.traceSafe()` projection of the row before/after the write.
+  // Both nullable: create-verb has no `before`, delete-verb has no `after`,
+  // read-touches has neither.
+  before: field.jsonb(schema.check.json()).nullable(),
+  after: field.jsonb(schema.check.json()).nullable(),
+  // Convenience copy of the emitting trace_step's `captured_inputs`, so audit
+  // queries don't have to join into the (possibly already-retired) trace_step
+  // partition. Null when the step had no Tier-2 capture (no `meta.capture`,
+  // or `captureInputs: false`).
+  capturedInputs: field.jsonb(schema.check.json()).nullable(),
+  occurredAt: field.timestamp(),
+  // Hash chain (opt-in, blueprint `audit.chain`). Written only by the
+  // `audit_record` insert trigger; null on rows written before chaining was
+  // enabled. `prevHash` / `hash` are lowercase hex SHA-256.
+  chainSeq: field.bigint().nullable(),
+  prevHash: field.text().nullable(),
+  hash: field.text().nullable(),
+}
+
+/** Fields the chain trigger owns — never part of an application INSERT's column list. */
+export const AUDIT_CHAIN_FIELD_KEYS: ReadonlySet<string> = new Set(['chainSeq', 'prevHash', 'hash'])

package/src/audit/schema/audit-record.ts

@@ -0,0 +1,23 @@
+// The `audit_record` table — durable per-(entity × affected row) audit
+// projection. RANGE-partitioned by `traceDay`; retention is independent of
+// the trace tables (long / indefinite, configured separately). The `traceId`
+// and `traceStepId` columns declare a logical reference (`enforced: false`)
+// to inherit the TraceId/TraceStepId brands without emitting an FK — the
+// audit partition is free to outlive its source trace partition.
+
+import { define } from '../../data/domain/index.js'
+import { index } from '../../data/db/idx/index.js'
+import { auditRecordFields } from './audit-record-fields.js'
+
+/** One row's history: `audit.query({ entity, entityId })` is a range scan of this index. */
+export const AUDIT_ENTITY_INDEX = 'audit_record_entity_idx'
+export const AUDIT_ENTITY_INDEX_SQL =
+  `CREATE INDEX IF NOT EXISTS ${AUDIT_ENTITY_INDEX} ON audit_record (tenant_id, entity, entity_id, occurred_at, id)`
+
+export const auditRecord = define('audit_record', auditRecordFields, {
+  primaryKey: ['id', 'traceDay'],
+  partitionBy: { strategy: 'range', column: 'traceDay' },
+  indexes: (t) => ({
+    entity: index(AUDIT_ENTITY_INDEX).on(t['tenantId'], t['entity'], t['entityId'], t['occurredAt'], t['id']),
+  }),
+})

package/src/auth/auth/audit.ts

@@ -0,0 +1,31 @@
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { getContext } from '../../request/context/store.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { recordFault, faultMessage } from '../../infra/alerts/faults.js'
+
+/**
+ * Writes an audit record with no tenant and no actor (the person is not yet signed in)
+ * under the Flow's open trace step; does nothing when no step is open. A failure is logged, not thrown.
+ */
+export async function auditUnauthenticated(
+  db: DB, entity: string, verb: string, entityId: string | null, details: Record<string, unknown>,
+): Promise<void> {
+  const flow = getContext()
+  const trace = flow?.trace
+  const stepId = trace?.buffer.openStepId ?? null
+  if (trace === undefined || trace === null || stepId === null) return
+  try {
+    await db.transaction(async (sp: DB) => {
+      await sp.execute(sql`
+        INSERT INTO audit_record
+          (trace_day, trace_id, trace_step_id, tenant_id, actor_id, entity, verb, entity_id, after, occurred_at)
+        VALUES (${trace.openedDay}, ${trace.id}, ${stepId}, NULL, NULL,
+          ${entity}, ${verb}, ${entityId}, ${JSON.stringify(details)}::jsonb, now())
+      `)
+    })
+  } catch (err) {
+    getBaseLogger().error({ err, traceId: trace.id }, `Failed to write the ${entity} ${verb} audit record`)
+    void recordFault('audit-write', faultMessage(err), { entity, verb })
+  }
+}