pipework 0.252.0 → 0.252.1

package/src/data/write/audit/audit-select.ts

@@ -0,0 +1,111 @@
+// Builds the SELECT projection inside the `audit_inserts` CTE — one row per
+// (affected-db-row × `@touches` target). The verb composers (insert / update
+// / delete / upsert) supply the data-source clause (`FROM ...`) and the
+// `before` / `after` jsonb expressions; everything else — the actor/tenant/
+// trace fields, the entity/verb literals, the captured_inputs literal — is
+// constant across rows and lives here.
+//
+// `@touches Entity:verb` is multi-target: a single write can carry several
+// targets, and each one emits its own audit row per affected db row. We
+// model that as `UNION ALL` over one SELECT per target, sharing the same
+// FROM. (Postgres folds these into a single insert plan.) Empty targets is
+// a programmer error — the executor short-circuits to the vanilla branch.
+
+import { sql } from '../../db/sql.js'
+import type { SQL } from '../../db/types.js'
+import type { ActiveAuditStep } from '../../../trace/runtime/step-buffer.js'
+import type { MetaTouch } from '../../../trace/runtime/step-meta.js'
+import { quoteIdentifier } from '../../db/identifiers.js'
+import { camelToSnake } from '../../domain/naming.js'
+import { declaredPrimaryKeyFieldKeys } from './primary-key.js'
+import type { DefinedTable } from '../../domain/types.js'
+
+/**
+ * SQL for `audit_record.entity_id` read from CTE alias `alias`: the single key
+ * column cast to text, or a compact JSON array of the key columns as text for
+ * a composite key; null for a table with no declared key. Matches `auditEntityId` in `primary-key.ts`.
+ */
+export function buildEntityIdExpr(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see primaryKeyFieldKeys
+  table: DefinedTable<any>,
+  alias: string,
+): SQL {
+  const keys = declaredPrimaryKeyFieldKeys(table)
+  if (keys.length === 0) return sql`NULL::text`
+  const cols = keys.map(k => `${alias}.${quoteIdentifier(camelToSnake(k), 'pk column')}::text`)
+  return cols.length === 1
+    ? sql.raw(cols[0]!)
+    : sql.raw(`array_to_json(ARRAY[${cols.join(', ')}])::text`)
+}
+
+/**
+ * Information about the active flow_step plus the actor/tenant the row is
+ * attributed to. The CTE compiler resolves these from the active `Flow` and
+ * passes them in — keeps the SQL composer free of context-store coupling.
+ */
+export interface AuditSelectContext {
+  readonly step: ActiveAuditStep
+  /** The touches the write is recorded under — one audit row per affected row per touch. */
+  readonly touches: readonly MetaTouch[]
+  /** Upsert only: which touches take newly inserted rows (`create`) and which take updated rows (`update`). Absent: every touch takes every row. */
+  readonly split?: { readonly create: readonly MetaTouch[]; readonly update: readonly MetaTouch[] } | undefined
+  /** The touches the executor marks written once the write lands. */
+  readonly written: readonly MetaTouch[]
+  /** `auth?.userId`, or null when the trace ran without an authenticated principal. */
+  readonly actorId: string | null
+  /** `flow.tenant`, or null when the entry was not tenant-scoped. */
+  readonly tenantId: string | null
+}
+
+/**
+ * Composes the `audit_inserts` CTE body: one `SELECT` per `@touches` target,
+ * joined by `UNION ALL`, projecting onto the `audit_record` column order.
+ *
+ * The shape is positional — matches `AUDIT_COLUMNS_SQL` exactly:
+ *   id, trace_day, trace_id, trace_step_id, tenant_id, actor_id,
+ *   entity, verb, entity_id, before, after, captured_inputs, occurred_at
+ *
+ * `from` is the verb's contributing FROM clause (e.g. `FROM updated u LEFT
+ * JOIN before b ON ...`), `before` / `after` are the per-row jsonb
+ * expressions to project (or `NULL::jsonb` when the half doesn't apply).
+ */
+export function buildAuditInserts(
+  ctx: AuditSelectContext,
+  from: SQL,
+  entityId: SQL,
+  before: SQL,
+  after: SQL,
+  /** Optional per-touch predicate appended to that touch's SELECT as a WHERE. */
+  rowFilter?: (touch: MetaTouch) => SQL | null,
+): SQL {
+  const capturedInputs = ctx.step.capturedInputs
+  const capturedJson = capturedInputs === null
+    ? sql`NULL::jsonb`
+    : sql`${JSON.stringify(capturedInputs)}::jsonb`
+
+  const selects = ctx.touches.map(t => sql`
+    SELECT
+      gen_random_uuid(),
+      ${ctx.step.traceDay}::date,
+      ${ctx.step.traceId}::uuid,
+      ${ctx.step.stepId}::uuid,
+      ${ctx.tenantId}::uuid,
+      ${ctx.actorId},
+      ${t.entity},
+      ${t.verb},
+      ${entityId},
+      ${before},
+      ${after},
+      ${capturedJson},
+      now()
+    ${from}
+    ${filterFor(rowFilter, t)}
+  `)
+
+  return sql.join(selects, sql` UNION ALL `)
+}
+
+function filterFor(rowFilter: ((t: MetaTouch) => SQL | null) | undefined, t: MetaTouch): SQL {
+  const f = rowFilter?.(t) ?? null
+  return f === null ? sql`` : sql`WHERE ${f}`
+}

package/src/data/write/audit/bound-transaction.ts

@@ -0,0 +1,14 @@
+// The Flow's open transaction on a database, for audit writers that must not
+// wait on it from a second connection. Null when none is bound.
+
+import type { DB } from '../../db/index.js'
+import type { Flow } from '../../../request/context/types.js'
+import { verifyTransactionBinding } from '../../../request/context/guard.js'
+
+export function boundTransaction(flow: Flow, database?: string): DB | null {
+  const name = database ?? flow.instance.config.defaultDatabaseName()
+  const bound = flow.transactions.get(name)
+  if (bound === undefined) return null
+  verifyTransactionBinding(flow, bound, name)
+  return bound.drizzle
+}

package/src/data/write/audit/cte-compile.ts

@@ -0,0 +1,32 @@
+// Entry point for the write+audit CTE generator. Routes by `state.verb` to
+// the per-verb composer. Empty `touches` is a programmer error — the caller
+// (executor) is expected to fall through to the vanilla branch when the
+// active step has no audit projection. We assert here so a regression in
+// the executor surfaces immediately rather than producing an audit row
+// with empty entity/verb.
+
+import { compileInsertAudit } from './verb-insert.js'
+import { compileUpdateAudit } from './verb-update.js'
+import { compileDeleteAudit } from './verb-delete.js'
+import { compileUpsertAudit } from './verb-upsert.js'
+import type { SQL } from '../../db/types.js'
+import type { WriteState } from '../state.js'
+import type { AuditSelectContext } from './audit-select.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle's DB type is deeply generic; the executor passes the resolved per-database handle through unchanged
+type AnyDb = any
+
+export function compileAuditWrite(db: AnyDb, state: WriteState, ctx: AuditSelectContext): SQL {
+  if (ctx.touches.length === 0) {
+    throw new Error(
+      `[pipework] compileAuditWrite called with empty touches on "${state.table.$name}". ` +
+      `Active step "${ctx.step.stepId}" has no @touches matching this table — the executor should have taken the vanilla DML branch.`,
+    )
+  }
+  switch (state.verb) {
+    case 'insert': return compileInsertAudit(db, state, ctx)
+    case 'update': return compileUpdateAudit(db, state, ctx)
+    case 'delete': return compileDeleteAudit(db, state, ctx)
+    case 'upsert': return compileUpsertAudit(db, state, ctx)
+  }
+}

package/src/data/write/audit/decode-returning.ts

@@ -0,0 +1,47 @@
+// Decodes the CTE statement's raw rows the way drizzle decodes a vanilla
+// `.returning()`: each value is read from its physical column and run through
+// the column's `mapFromDriverValue` (timestamps to Date, bigint, json, ...),
+// nulls passing through. Keys are the table's field keys for `returning('all')`
+// and the caller's aliases for a per-key projection.
+
+import { physicalColumnName } from './final-select.js'
+import type { WriteState } from '../state.js'
+
+type Decoder = (value: unknown) => unknown
+interface Slot { readonly key: string; readonly physical: string; readonly decode: Decoder | undefined }
+
+export function decodeReturning(state: WriteState, rows: unknown): unknown {
+  const returning = state.returning
+  if (returning === undefined || returning === null) return undefined
+  if (!Array.isArray(rows)) return rows
+  const slots = slotsFor(state)
+  return rows.map(row => {
+    const raw = row as Record<string, unknown>
+    const out: Record<string, unknown> = {}
+    for (const slot of slots) {
+      const value = raw[slot.physical]
+      out[slot.key] = value === null || value === undefined || slot.decode === undefined ? value : slot.decode(value)
+    }
+    return out
+  })
+}
+
+function slotsFor(state: WriteState): Slot[] {
+  const returning = state.returning
+  const table = state.table as unknown as Record<string, unknown>
+  if (returning === 'all' || returning === null || returning === undefined || Object.keys(returning).length === 0) {
+    return Object.keys(state.table.$fields).map(key => slot(key, key, table[key]))
+  }
+  // Per-key rows are aliased by the final select, so they are read by alias.
+  return Object.keys(returning).map(key => ({ key, physical: key, decode: decoderOf(returning[key]) }))
+}
+
+function slot(key: string, alias: string, column: unknown): Slot {
+  return { key, physical: physicalColumnName(alias, column), decode: decoderOf(column) }
+}
+
+function decoderOf(column: unknown): Decoder | undefined {
+  const fn = (column as { mapFromDriverValue?: unknown } | null)?.mapFromDriverValue
+  if (typeof fn !== 'function') return undefined
+  return (v: unknown) => (fn as Decoder).call(column, v)
+}

package/src/data/write/audit/final-select.ts

@@ -0,0 +1,43 @@
+// Builds the final SELECT of the CTE statement — the row(s) the caller sees.
+// Mirrors the shape `vanilla DML` would have produced for the same `returning`:
+// no `returning` → no rows (one placeholder row per written row under onConflict); `returning('all')` → SELECT *; per-key projection
+// → aliased column list. Reads from the verb's post-image CTE (`inserted` /
+// `updated` / `deleted` / `upserted`).
+
+import { sql } from '../../db/sql.js'
+import { quoteIdentifier } from '../../db/identifiers.js'
+import { camelToSnake } from '../../domain/naming.js'
+import type { SQL } from '../../db/types.js'
+import type { WriteState } from '../state.js'
+
+export function buildFinalSelect(state: WriteState, sourceCte: string): SQL {
+  const source = quoteIdentifier(sourceCte, 'CTE alias')
+  const returning = state.returning ?? null
+  if (returning === null) {
+    // Under onConflictDoNothing the rows written are counted from the rows returned.
+    if (state.onConflict !== undefined) return sql.raw(`SELECT 1 FROM ${source}`)
+    return sql.raw(`SELECT 1 FROM ${source} WHERE FALSE`)
+  }
+  if (returning === 'all') {
+    return sql.raw(`SELECT * FROM ${source}`)
+  }
+  const keys = Object.keys(returning)
+  if (keys.length === 0) return sql.raw(`SELECT * FROM ${source}`)
+  const cols = keys.map(k => {
+    const physical = quoteIdentifier(physicalColumnName(k, returning[k]), 'returning column')
+    const alias = quoteIdentifier(k, 'returning alias')
+    return `${source}.${physical} AS ${alias}`
+  }).join(', ')
+  return sql.raw(`SELECT ${cols} FROM ${source}`)
+}
+
+/** The projected column's own SQL name when `value` is a column; otherwise the alias, snake-cased. */
+export function physicalColumnName(alias: string, value: unknown): string {
+  const name = (value as { name?: unknown } | null)?.name
+  if (isColumn(value) && typeof name === 'string') return name
+  return camelToSnake(alias)
+}
+
+export function isColumn(value: unknown): value is { name: string; mapFromDriverValue?: (v: unknown) => unknown } {
+  return typeof value === 'object' && value !== null && 'columnType' in value
+}

package/src/data/write/audit/infra-audit.ts

@@ -0,0 +1,36 @@
+// Writes one audit_record for an infrastructure operation (access links,
+// credits) into the open trace step, in the operation's own transaction.
+// No trace or no open step: nothing is written. A failed write fails the
+// operation: the error reaches the caller and its transaction rolls back, so
+// no row commits without its audit record. The database error stays on `cause`.
+
+import { sql } from '../../db/sql.js'
+import type { DB } from '../../db/index.js'
+import type { Flow } from '../../../request/context/types.js'
+import { resolveActorId } from './actor.js'
+
+export interface InfraAudit {
+  readonly tenantId: string
+  readonly entity: string
+  readonly verb: string
+  readonly entityId: string
+  readonly before?: Record<string, unknown>
+  readonly after: Record<string, unknown>
+}
+
+export async function writeInfraAudit(flow: Flow, tx: DB, record: InfraAudit): Promise<void> {
+  const trace = flow.trace
+  const stepId = trace?.buffer.openStepId ?? null
+  if (trace === null || stepId === null) return
+  try {
+    await tx.execute(sql`
+      INSERT INTO audit_record
+        (trace_day, trace_id, trace_step_id, tenant_id, actor_id, entity, verb, entity_id, before, after, occurred_at)
+      VALUES (${trace.openedDay}, ${trace.id}, ${stepId}, ${record.tenantId}, ${resolveActorId(flow)},
+        ${record.entity}, ${record.verb}, ${record.entityId},
+        ${record.before === undefined ? null : JSON.stringify(record.before)}::jsonb, ${JSON.stringify(record.after)}::jsonb, now())
+    `)
+  } catch (err) {
+    throw new Error(`Failed to write the ${record.entity} ${record.verb} audit record`, { cause: err })
+  }
+}

package/src/data/write/audit/primary-key.ts

@@ -0,0 +1,65 @@
+// Primary-key resolution for the audit CTE generator. The UPDATE / DELETE /
+// UPSERT verbs need a key to join the `before` snapshot with the post-image
+// (`updated` / `deleted` / `upserted`) so the audit row pairs the right
+// pre/post pair per affected db row. We honor the two ways a `pipe.define()`
+// table declares its key: composite via the `primaryKey` option, or single
+// via a field-level `.primaryKey()`.
+
+import type { DefinedTable, FieldRecord } from '../../domain/types.js'
+
+/**
+ * Returns the primary-key field keys in declaration order. Throws when the
+ * table declares no primary key — the audit CTE needs one to pair rows.
+ */
+export function primaryKeyFieldKeys(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DefinedTable's field generics erase at this boundary; we only read $fields and $options
+  table: DefinedTable<any>,
+): readonly string[] {
+  const keys = declaredPrimaryKeyFieldKeys(table)
+  if (keys.length === 0) {
+    throw new Error(
+      `[pipework] Cannot emit audit CTE for "${table.$name}": ` +
+      `the table declares no primary key.\n\n` +
+      `  An audit-emitting write needs a primary key so the pre-image\n` +
+      `  and post-image rows can be paired. Add .primaryKey() to a field\n` +
+      `  or pass { primaryKey: ['col1', 'col2'] } to the table options.\n`,
+    )
+  }
+  return keys
+}
+
+/** The declared primary-key field keys in declaration order; empty when the table has none. */
+export function declaredPrimaryKeyFieldKeys(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see primaryKeyFieldKeys
+  table: DefinedTable<any>,
+): readonly string[] {
+  const composite = table.$options.primaryKey
+  if (composite !== undefined && composite.length > 0) return composite
+  const fields = table.$fields as FieldRecord
+  const single: string[] = []
+  for (const [key, descriptor] of Object.entries(fields)) {
+    if (descriptor._meta.primaryKey) single.push(key)
+  }
+  return single
+}
+
+/**
+ * The audited row's primary key as `audit_record.entity_id` text: the single
+ * key's value, or for a composite key a compact JSON array of the key values
+ * as strings, in key order (`["a","7"]`).
+ */
+export function auditEntityId(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see primaryKeyFieldKeys
+  table: DefinedTable<any>,
+  row: Readonly<Record<string, unknown>>,
+): string {
+  const keys = primaryKeyFieldKeys(table)
+  const values = keys.map(k => {
+    const v = row[k]
+    if (v === null || v === undefined) {
+      throw new Error(`audit entity id for "${table.$name}": primary key field "${k}" is missing from the row.`)
+    }
+    return v instanceof Date ? v.toISOString() : String(v)
+  })
+  return keys.length === 1 ? values[0]! : JSON.stringify(values)
+}

package/src/data/write/audit/projection.ts

@@ -0,0 +1,41 @@
+// Server-side `.traceSafe()` projection. Builds a `jsonb_build_object(...)`
+// fragment from the table's `traceSafeKeys` so the audit row's `before` /
+// `after` columns are populated entirely inside the SQL — never by a
+// round-trip to the runtime. The projection is fail-closed: only fields
+// explicitly marked `.traceSafe()` participate; a new field is never
+// audited by accident.
+//
+// `null` is returned when the table has no trace-safe fields. The verb
+// composers turn that into `NULL::jsonb` in the audit row, so a write
+// against an unprojectable table still emits an audit row — just with
+// empty before/after halves.
+
+import { sql } from '../../db/sql.js'
+import { quoteIdentifier } from '../../db/identifiers.js'
+import { camelToSnake } from '../../domain/naming.js'
+import { traceSafeKeys } from '../../domain/trace-safe-projection.js'
+import type { SQL } from '../../db/types.js'
+import type { DefinedTable, FieldRecord } from '../../domain/types.js'
+
+/**
+ * `jsonb_build_object('field', "source"."column", ...)` over each trace-safe
+ * field, qualified by `sourceAlias` (the CTE name the column resolves through:
+ * `before` for the pre-image, `updated` / `deleted` / `inserted` / `upserted`
+ * for the post-image). Returns `null` when the table has no trace-safe fields
+ * — the caller substitutes `NULL::jsonb`.
+ */
+export function buildTraceSafeProjection(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DefinedTable's field generics erase at this boundary; we only read $fields
+  table: DefinedTable<any>,
+  sourceAlias: string,
+): SQL | null {
+  const keys = traceSafeKeys(table.$fields as FieldRecord)
+  if (keys.length === 0) return null
+  const aliasIdent = quoteIdentifier(sourceAlias, 'CTE alias')
+  const parts: SQL[] = []
+  for (const key of keys) {
+    const col = quoteIdentifier(camelToSnake(key), 'trace-safe column')
+    parts.push(sql.raw(`'${key}', ${aliasIdent}.${col}`))
+  }
+  return sql`jsonb_build_object(${sql.join(parts, sql.raw(', '))})`
+}

package/src/data/write/audit/read-touches.ts

@@ -0,0 +1,86 @@
+// Read-touches audit emission. A flow_step that declared `@touches Entity:verb`
+// but performed no `pipe.*` write to its entity is recording a read, not a mutation: the step
+// observed the entity in service of the request, and the audit substrate must
+// record that observation for compliance and trail-reconstruction. The
+// CTE-form write path covers the touches it wrote (recorded by
+// `markWrote(touch)`); this module covers the rest.
+//
+// Atomicity: the emit goes through `pipeRaw()` so a bound transaction on the
+// active Flow carries the insert. If the caller wrapped the step in
+// `pipe.transaction(...)`, the audit row lands in that transaction; otherwise
+// it's a standalone write. Either way it's not pool-direct (unlike trace_step
+// flush), so a request-level rollback discards the audit too — read-touches is
+// a record of what *actually* happened, not what was attempted.
+//
+// The emit uses raw drizzle (`db.insert(table).values(...)`) rather than
+// `pipe.insert` to bypass the executor's audit branch — going through
+// `pipe.insert(auditRecord)` while the active step has `@touches` would route
+// through `compileAuditWrite` and try to project audit_record itself, which is
+// nonsense.
+
+import { auditRecord } from '../../../audit/schema/audit-record.js'
+import { pipeRaw } from '../../db/db.js'
+import { getBaseLogger } from '../../../core/logging/index.js'
+import { recordFault, faultMessage } from '../../../infra/alerts/faults.js'
+import type { Flow } from '../../../request/context/types.js'
+import type { BegunStep } from '../../../trace/runtime/step-buffer.js'
+import { resolveActorId } from './actor.js'
+
+interface AuditRecordInsert {
+  readonly traceDay: string
+  readonly traceId: string
+  readonly traceStepId: string
+  readonly tenantId: string | null
+  readonly actorId: string | null
+  readonly entity: string
+  readonly verb: string
+  readonly before: null
+  readonly after: null
+  readonly capturedInputs: unknown
+  readonly occurredAt: Date
+}
+
+/**
+ * Emits one `audit_record` row per `@touches` target that no write of the
+ * completed step audited. Resolves when the insert settles. Failures are
+ * logged at error level and swallowed — an audit-emit failure must not
+ * propagate to the user-visible step outcome (the step already succeeded).
+ */
+export async function emitReadTouches(flow: Flow, begun: BegunStep): Promise<void> {
+  const unwritten = begun.touches.filter(t => !begun.wroteTouches.has(t))
+  if (unwritten.length === 0) return
+  if (flow.trace === null) return
+
+  const traceDay = flow.trace.openedDay
+  const traceId = flow.trace.id
+  const tenantId = flow.tenant
+  const actorId = resolveActorId(flow)
+  const capturedInputs = begun.capturedInputs
+  const occurredAt = new Date()
+
+  const rows: AuditRecordInsert[] = unwritten.map(t => ({
+    traceDay,
+    traceId,
+    traceStepId: begun.stepId,
+    tenantId,
+    actorId,
+    entity: t.entity,
+    verb: t.verb,
+    before: null,
+    after: null,
+    capturedInputs,
+    occurredAt,
+  }))
+
+  try {
+    const db = pipeRaw(auditRecord.$options.database)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle's insert needs the concrete runtime table type
+    await (db as any).insert(auditRecord.table()).values(rows)
+  } catch (err) {
+    getBaseLogger().error(
+      { err, traceId, stepId: begun.stepId, touches: unwritten.length },
+      'Failed to emit read-touches audit row — the audit trail is missing a read observation',
+    )
+    void recordFault('audit-write', faultMessage(err), { entity: 'ReadTouch', touches: unwritten.length })
+  }
+}

package/src/data/write/audit/touch-match.ts

@@ -0,0 +1,78 @@
+// Maps a flow step's `@touches Entity:verb` targets onto the table a write hits.
+//
+// A touch's `Entity` matches a table when:
+//   (a) the definition declares `define(name, fields, { auditEntity })` and it
+//       equals `Entity` exactly; otherwise
+//   (b) the normalized names agree: lowercase with underscores removed, with the
+//       table name optionally ending in `s` or `es` (`Version` matches
+//       `version` / `versions`; `DocumentVersion` matches `document_versions`).
+//
+// A write is audited only under the touches that match its table. A touch whose
+// entity matches no registered definition cannot be audited by any write, so a
+// write under it is refused rather than silently unaudited.
+
+import { definitions } from '../../domain/define.js'
+import type { DefinedTable } from '../../domain/types.js'
+import type { MetaTouch } from '../../../trace/runtime/step-meta.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- registry erases field-level generics
+type AnyDefinition = DefinedTable<any>
+
+function normalize(name: string): string {
+  return name.toLowerCase().replace(/_/g, '')
+}
+
+export function touchMatchesTable(entity: string, table: AnyDefinition): boolean {
+  const declared = table.$options.auditEntity
+  if (declared !== undefined) return declared === entity
+  const want = normalize(entity)
+  const have = normalize(table.$name)
+  if (have === want) return true
+  return (have.endsWith('es') && have.slice(0, -2) === want) ||
+    (have.endsWith('s') && have.slice(0, -1) === want)
+}
+
+/**
+ * The touches a write to `table` is audited under. Throws when any of the
+ * step's touches names an entity no registered definition matches.
+ */
+export function touchesForTable(table: AnyDefinition, touches: readonly MetaTouch[]): MetaTouch[] {
+  const all = [...definitions().values()]
+  for (const t of touches) {
+    if (touchMatchesTable(t.entity, table)) continue
+    if (all.some(d => touchMatchesTable(t.entity, d))) continue
+    const near = closest(t.entity, all.map(d => d.$name))
+    throw new Error(
+      `[pipework] @touches entity "${t.entity}" matches no defined table, so a write under it cannot be audited. ` +
+      (near.length > 0 ? `Closest table names: ${near.join(', ')}. ` : '') +
+      'Name the entity after the table (case-insensitive, underscores ignored, plural allowed) ' +
+      "or set define(name, fields, { auditEntity: '<Entity>' }) on the table.",
+    )
+  }
+  return touches.filter(t => touchMatchesTable(t.entity, table))
+}
+
+function closest(entity: string, names: readonly string[]): string[] {
+  const want = normalize(entity)
+  return names
+    .map(n => ({ n, d: editDistance(want, normalize(n)) }))
+    .sort((a, b) => a.d - b.d)
+    .slice(0, 3)
+    .map(x => x.n)
+}
+
+function editDistance(a: string, b: string): number {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j)
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i]
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j]! + 1,
+        cur[j - 1]! + 1,
+        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+    }
+    prev = cur
+  }
+  return prev[b.length]!
+}

package/src/data/write/audit/verb-delete.ts

@@ -0,0 +1,62 @@
+// DELETE under audit: snapshots the matched rows into `before`, runs the
+// DELETE into `deleted`, then emits one audit row per deleted db row per
+// `@touches` target. The audit's `after` is always `NULL::jsonb` — there is
+// no post-image for a delete. The statement's snapshot keeps `before` and
+// `deleted` consistent — no lock needed; `FOR UPDATE` inside a CTE conflicts
+// with the sibling DELETE on the same row and silently yields zero rows from
+// `before`, suppressing the audit insert.
+
+import { sql } from '../../db/sql.js'
+import { quoteIdentifier } from '../../db/identifiers.js'
+import { camelToSnake } from '../../domain/naming.js'
+import { buildTraceSafeProjection } from './projection.js'
+import { buildAuditInserts, buildEntityIdExpr, type AuditSelectContext } from './audit-select.js'
+import { primaryKeyFieldKeys } from './primary-key.js'
+import { AUDIT_COLUMNS_SQL } from './audit-columns.js'
+import { buildFinalSelect } from './final-select.js'
+import type { SQL } from '../../db/types.js'
+import type { WriteState } from '../state.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle's DB type is deeply generic; the executor passes the resolved per-database handle through unchanged
+type AnyDb = any
+
+export function compileDeleteAudit(db: AnyDb, state: WriteState, ctx: AuditSelectContext): SQL {
+  const pk = primaryKeyFieldKeys(state.table)
+
+  // `.getSQL()` strips the auto-paren drizzle adds around SQLWrapper builders
+  // when they are templated — we add explicit parens at the CTE boundary so
+  // the WITH clause keeps a uniform shape across verbs.
+  let deleteChain = db.delete(state.table)
+  if (state.where !== undefined) deleteChain = deleteChain.where(state.where)
+  const deleteInner = deleteChain.returning().getSQL()
+
+  let beforeChain = db.select().from(state.table)
+  if (state.where !== undefined) beforeChain = beforeChain.where(state.where)
+  const beforeInner = beforeChain.getSQL()
+
+  const joinOn = pk
+    .map(k => {
+      const col = quoteIdentifier(camelToSnake(k), 'pk column')
+      return `before.${col} = deleted.${col}`
+    })
+    .join(' AND ')
+
+  const before = buildTraceSafeProjection(state.table, 'before') ?? sql`NULL::jsonb`
+  // Source the audit from `deleted` — RETURNING * gives every column we need
+  // for the pre-image join, and `deleted` includes only the rows that actually
+  // matched. Joining onto `before` carries the FOR UPDATE lock.
+  const fromClause = sql.raw(`FROM deleted JOIN before ON ${joinOn}`)
+  const auditSelect = buildAuditInserts(ctx, fromClause, buildEntityIdExpr(state.table, 'deleted'), before, sql`NULL::jsonb`)
+  const finalSelect = buildFinalSelect(state, 'deleted')
+
+  return sql`
+    WITH before AS (${beforeInner}),
+    deleted AS (${deleteInner}),
+    audit_inserts AS (
+      INSERT INTO "audit_record" (${sql.raw(AUDIT_COLUMNS_SQL)})
+      ${auditSelect}
+      RETURNING 1
+    )
+    ${finalSelect}
+  `
+}

package/src/data/write/audit/verb-insert.ts

@@ -0,0 +1,36 @@
+// INSERT under audit: no `before` snapshot. The audit row pairs `NULL::jsonb`
+// with the `.traceSafe()` projection of the inserted row, drawn from the
+// `inserted` CTE's RETURNING *. One audit row per inserted db row per
+// `@touches` target.
+
+import { sql } from '../../db/sql.js'
+import { buildTraceSafeProjection } from './projection.js'
+import { buildAuditInserts, buildEntityIdExpr, type AuditSelectContext } from './audit-select.js'
+import { AUDIT_COLUMNS_SQL } from './audit-columns.js'
+import { buildFinalSelect } from './final-select.js'
+import { applyOnConflict } from '../conflict.js'
+import type { SQL } from '../../db/types.js'
+import type { WriteState } from '../state.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle's DB type is deeply generic; the executor passes the resolved per-database handle through unchanged
+type AnyDb = any
+
+export function compileInsertAudit(db: AnyDb, state: WriteState, ctx: AuditSelectContext): SQL {
+  // `.getSQL()` strips the auto-paren drizzle adds around SQLWrapper builders
+  // when they are templated — we add explicit parens at the CTE boundary so
+  // the WITH clause keeps a uniform shape across verbs.
+  const inner = applyOnConflict(db.insert(state.table).values(state.values ?? []), state).returning().getSQL()
+  const after = buildTraceSafeProjection(state.table, 'inserted') ?? sql`NULL::jsonb`
+  const auditSelect = buildAuditInserts(ctx, sql`FROM inserted`, buildEntityIdExpr(state.table, 'inserted'), sql`NULL::jsonb`, after)
+  const finalSelect = buildFinalSelect(state, 'inserted')
+
+  return sql`
+    WITH inserted AS (${inner}),
+    audit_inserts AS (
+      INSERT INTO "audit_record" (${sql.raw(AUDIT_COLUMNS_SQL)})
+      ${auditSelect}
+      RETURNING 1
+    )
+    ${finalSelect}
+  `
+}