pipework 0.251.0 → 0.252.1

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

@@ -0,0 +1,47 @@
+// Chooses which of a step's entity-matched touches a write is recorded under.
+//
+// A row's verb is `create` (insert, or an upsert row `before` did not match),
+// `update`, or `delete`. Among the matched touches:
+//   1. those whose verb is exactly the row's verb, if any;
+//   2. else those whose verb is not create/update/delete/read (custom verbs);
+//   3. else all matched touches but `read` ones, or all when only `read` ones match.
+// A write marks every matched touch written, so none of them also gets a read row.
+
+import type { MetaTouch } from '../../../trace/runtime/step-meta.js'
+
+export type RowVerb = 'create' | 'update' | 'delete'
+
+const NOT_CUSTOM: ReadonlySet<string> = new Set(['create', 'update', 'delete', 'read'])
+
+export function selectTouches(matched: readonly MetaTouch[], verb: RowVerb): MetaTouch[] {
+  const exact = matched.filter(t => t.verb === verb)
+  if (exact.length > 0) return exact
+  const custom = matched.filter(t => !NOT_CUSTOM.has(t.verb))
+  if (custom.length > 0) return custom
+  const writes = matched.filter(t => t.verb !== 'read')
+  return writes.length > 0 ? writes : [...matched]
+}
+
+export interface WriteSelection {
+  /** Touches that get audit rows, in declaration order. */
+  readonly touches: MetaTouch[]
+  /** Upsert only: the touches that take rows `before` did not match / did match. */
+  readonly split?: { readonly create: readonly MetaTouch[]; readonly update: readonly MetaTouch[] } | undefined
+  /** Touches to mark as written: every matched touch. */
+  readonly written: MetaTouch[]
+}
+
+export function selectForWrite(matched: readonly MetaTouch[], writeVerb: 'insert' | 'update' | 'delete' | 'upsert'): WriteSelection {
+  let touches: MetaTouch[]
+  let split: WriteSelection['split']
+  if (writeVerb === 'upsert') {
+    const create = selectTouches(matched, 'create')
+    const update = selectTouches(matched, 'update')
+    touches = matched.filter(t => create.includes(t) || update.includes(t))
+    split = { create, update }
+  } else {
+    touches = selectTouches(matched, writeVerb === 'insert' ? 'create' : writeVerb)
+  }
+  const written = [...matched]
+  return { touches, split, written }
+}

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

@@ -0,0 +1,60 @@
+// UPDATE under audit: snapshots the matched rows into `before`, runs the
+// UPDATE into `updated`, then emits one audit row per affected db row per
+// `@touches` target, joining `before` and `updated` on the primary key so
+// the pre/post pair lines up. The single statement's snapshot keeps `before`
+// and `updated` consistent — no lock needed; in fact, `FOR UPDATE` inside a
+// CTE conflicts with the sibling UPDATE 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 compileUpdateAudit(db: AnyDb, state: WriteState, ctx: AuditSelectContext): SQL {
+  const pk = primaryKeyFieldKeys(state.table)
+  const set = state.set ?? {}
+  // `.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 updateChain = db.update(state.table).set(set)
+  if (state.where !== undefined) updateChain = updateChain.where(state.where)
+  const updateInner = updateChain.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} = updated.${col}`
+    })
+    .join(' AND ')
+
+  const before = buildTraceSafeProjection(state.table, 'before') ?? sql`NULL::jsonb`
+  const after = buildTraceSafeProjection(state.table, 'updated') ?? sql`NULL::jsonb`
+  const fromClause = sql.raw(`FROM updated JOIN before ON ${joinOn}`)
+  const auditSelect = buildAuditInserts(ctx, fromClause, buildEntityIdExpr(state.table, 'updated'), before, after)
+  const finalSelect = buildFinalSelect(state, 'updated')
+
+  return sql`
+    WITH before AS (${beforeInner}),
+    updated AS (${updateInner}),
+    audit_inserts AS (
+      INSERT INTO "audit_record" (${sql.raw(AUDIT_COLUMNS_SQL)})
+      ${auditSelect}
+      RETURNING 1
+    )
+    ${finalSelect}
+  `
+}

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

@@ -0,0 +1,104 @@
+// UPSERT under audit: a single INSERT ... ON CONFLICT DO UPDATE / DO NOTHING
+// that either inserts a new row or updates the conflicting one. Audit rows
+// distinguish create vs update by left-joining the upserted row with the
+// `before` snapshot (pre-write rows sharing the upserted rows' conflict-target
+// values, whoever supplied them): a NULL `before` row
+// means the upserted row was freshly inserted; non-NULL means it updated
+// an existing row. The audit's `before` jsonb is wrapped in a CASE that
+// returns NULL::jsonb for the insert branch.
+
+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 { 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'
+import type { MetaTouch } from '../../../trace/runtime/step-meta.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 compileUpsertAudit(db: AnyDb, state: WriteState, ctx: AuditSelectContext): SQL {
+  if (state.onConflictColumns === undefined || state.onConflictColumns.length === 0) {
+    throw new Error(
+      'pipe.upsert requires .onConflict([...columns]). ' +
+      'Pass the conflict-target columns that determine "this row already exists" — ' +
+      'usually the primary key or a unique index.',
+    )
+  }
+
+  const conflictCols = state.onConflictColumns
+  const targetColumns = conflictCols.map(key => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DefinedTable columns are indexed by field key; the lookup was validated at the builder surface
+    const col = (state.table as any)[key]
+    if (col === undefined) {
+      throw new Error(
+        `pipe.upsert: onConflict column "${key}" is not a field of "${state.table.$name}". ` +
+        `Use a field key declared on the table.`,
+      )
+    }
+    return col as unknown
+  })
+
+  let upsertChain = db.insert(state.table).values(state.values ?? [])
+  if (state.set === undefined) {
+    upsertChain = upsertChain.onConflictDoNothing({ target: targetColumns })
+  } else {
+    upsertChain = upsertChain.onConflictDoUpdate({ target: targetColumns, set: state.set })
+  }
+  // `.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 upsertInner = upsertChain.returning().getSQL()
+
+  const tableName = quoteIdentifier(state.table.$name, 'target table')
+  const conflictColsSql = conflictCols.map(k => quoteIdentifier(camelToSnake(k), 'conflict column')).join(', ')
+  // `before` is keyed on the rows `upserted` wrote, not the caller's values, so
+  // conflict columns pipework fills in (tenant) or defaults match too. All CTEs
+  // see the pre-statement snapshot: `before` reads the replaced row. No `FOR
+  // UPDATE`: locking inside a CTE conflicts with the sibling write on the row.
+  const beforeSelect = sql`
+    SELECT * FROM ${sql.raw(tableName)}
+    WHERE (${sql.raw(conflictColsSql)}) IN (SELECT ${sql.raw(conflictColsSql)} FROM upserted)
+  `
+
+  const joinOn = conflictCols
+    .map(k => {
+      const col = quoteIdentifier(camelToSnake(k), 'conflict column')
+      return `before.${col} = upserted.${col}`
+    })
+    .join(' AND ')
+
+  // Pivot: the conflict-key column of `before` is non-null iff the upserted
+  // row matched an existing row. Use the first conflict col as the discriminator.
+  const pivotCol = quoteIdentifier(camelToSnake(conflictCols[0]!), 'conflict column')
+  const beforeProj = buildTraceSafeProjection(state.table, 'before') ?? sql`NULL::jsonb`
+  const after = buildTraceSafeProjection(state.table, 'upserted') ?? sql`NULL::jsonb`
+  const beforeExpr = sql`CASE WHEN ${sql.raw(`before.${pivotCol}`)} IS NULL THEN NULL::jsonb ELSE (${beforeProj}) END`
+  const fromClause = sql.raw(`FROM upserted LEFT JOIN before ON ${joinOn}`)
+  // A touch in only the create set takes rows `before` did not match; only the
+  // update set, rows it did; in both (or no split), every row.
+  const split = ctx.split
+  const rowFilter = split === undefined ? undefined : (t: MetaTouch): SQL | null => {
+    const c = split.create.includes(t)
+    const u = split.update.includes(t)
+    if (c === u) return null
+    return sql.raw(`before.${pivotCol} IS ${c ? '' : 'NOT '}NULL`)
+  }
+  const auditSelect = buildAuditInserts(ctx, fromClause, buildEntityIdExpr(state.table, 'upserted'), beforeExpr, after, rowFilter)
+  const finalSelect = buildFinalSelect(state, 'upserted')
+
+  return sql`
+    WITH upserted AS (${upsertInner}),
+    before AS (${beforeSelect}),
+    audit_inserts AS (
+      INSERT INTO "audit_record" (${sql.raw(AUDIT_COLUMNS_SQL)})
+      ${auditSelect}
+      RETURNING 1
+    )
+    ${finalSelect}
+  `
+}

package/src/data/write/conflict.ts

@@ -0,0 +1,43 @@
+// `ON CONFLICT DO NOTHING` on `pipe.insert`: the target lookup shared by the
+// vanilla and audited paths, and the trace event naming the rows left alone.
+
+import { event } from '../../trace/external/record.js'
+import type { WriteState } from './state.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle's insert builder is deeply generic; the clause is applied to whatever chain the caller holds
+type AnyChain = any
+
+/** Applies the state's `ON CONFLICT DO NOTHING` to an insert chain; the chain is returned unchanged when the state has none. */
+export function applyOnConflict(q: AnyChain, state: WriteState): AnyChain {
+  const onConflict = state.onConflict
+  if (onConflict === undefined) return q
+  if (onConflict.target === undefined) return q.onConflictDoNothing()
+  const target = onConflict.target.map(key => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DefinedTable columns are indexed by field key; the lookup is validated here
+    const col = (state.table as any)[key]
+    if (col === undefined) {
+      throw new Error(
+        `pipe.insert: onConflictDoNothing target "${key}" is not a field of "${state.table.$name}". ` +
+        `Use a field key declared on the table.`,
+      )
+    }
+    return col as unknown
+  })
+  return q.onConflictDoNothing({ target })
+}
+
+/** Records the rows an `onConflictDoNothing` insert skipped; nothing when none were. */
+export function reportSkipped(state: WriteState, written: number): void {
+  if (state.onConflict === undefined) return
+  const attempted = state.values?.length ?? 0
+  if (written >= attempted) return
+  event('pipework.insert.conflict', {
+    capture: {
+      table: state.table.$name,
+      target: state.onConflict.target ?? null,
+      attempted,
+      written,
+      skipped: attempted - written,
+    },
+  })
+}

package/src/data/write/delete.ts

@@ -0,0 +1,38 @@
+// `pipe.delete(table)` — the pipework-owned delete builder. Same intent-based
+// design as UpdateBuilder; see update.ts for the rationale.
+
+import type { PgTable } from '../query/pg-core/index.js'
+import type { SQL } from '../db/types.js'
+import { assertNotExternal } from '../domain/external-registry.js'
+import type { DefinedTable } from '../domain/types.js'
+import type { WriteState } from './state.js'
+import { executeWrite } from './execute.js'
+
+export class DeleteBuilder<T extends PgTable, TResult = unknown> implements PromiseLike<TResult> {
+  constructor(private readonly state: WriteState) {}
+
+  where(condition: SQL): DeleteBuilder<T, TResult> {
+    return new DeleteBuilder<T, TResult>({ ...this.state, where: condition })
+  }
+
+  returning(): DeleteBuilder<T, Record<string, unknown>[]>
+  returning<TShape extends Record<string, unknown>>(shape: TShape): DeleteBuilder<T, Record<string, unknown>[]>
+  returning(shape?: Record<string, unknown>): DeleteBuilder<T, Record<string, unknown>[]> {
+    const returning = shape === undefined ? 'all' as const : shape
+    return new DeleteBuilder<T, Record<string, unknown>[]>({ ...this.state, returning })
+  }
+
+  then<TFulfilled = TResult, TRejected = never>(
+    onfulfilled?: ((value: TResult) => TFulfilled | PromiseLike<TFulfilled>) | null,
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): PromiseLike<TFulfilled | TRejected> {
+    return executeWrite(this.state).then(onfulfilled as (value: unknown) => TFulfilled, onrejected) as PromiseLike<TFulfilled | TRejected>
+  }
+}
+
+/** Starts a pipework-owned delete against `table`. Chain with `.where(...).returning(...)`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function remove<T extends DefinedTable<any> & PgTable>(table: T): DeleteBuilder<T, any> {
+  assertNotExternal(table, 'delete')
+  return new DeleteBuilder<T, unknown>({ verb: 'delete', table })
+}

package/src/data/write/execute.ts

@@ -0,0 +1,243 @@
+// Execution path for the write surface. Two branches: vanilla DML via drizzle
+// when there is no active audit-emitting step, and a single statement with
+// `before` / `updated|inserted|deleted|upserted` / `audit_inserts` CTEs
+// when the current `flow_step` carries a `@touches` target for the written
+// table. The two branches produce the same observable return (the CTE rows are
+// decoded through the table's columns) — the difference is whether an audit_record
+// row lands atomically with the write.
+//
+// Bulk-write chunking (Q8 / Phase 6c): when an insert/upsert under audit
+// would emit more than `trace.auditChunkSize` audit rows
+// (`values.length × touches.length`), the executor splits `state.values`
+// into chunks and runs each one as its own write+audit CTE, wrapped in a
+// transaction so the chunks commit or abort together. Update/delete are not
+// chunked — affected row counts are dynamic at SQL-generation time, so
+// chunking would need a separate strategy.
+
+import type { WriteState } from './state.js'
+import type { Flow } from '../../request/context/types.js'
+import { pipe, pipeRaw } from '../db/db.js'
+import { getContext } from '../../request/context/store.js'
+import { compileAuditWrite } from './audit/cte-compile.js'
+import { touchesForTable } from './audit/touch-match.js'
+import { selectForWrite } from './audit/verb-select.js'
+import { decodeReturning } from './audit/decode-returning.js'
+import { resolveActorId } from './audit/actor.js'
+import type { AuditSelectContext } from './audit/audit-select.js'
+import { rowsPerStatement } from '../db/insert-split.js'
+import { applyOnConflict, reportSkipped } from './conflict.js'
+
+export async function executeWrite(state: WriteState): Promise<unknown> {
+  const db = pipe(state.table.$options.database)
+  const flow = getContext()
+  if (flow !== undefined && flow.trace !== null) {
+    const stepCtx = flow.trace.buffer.currentStep()
+    // Only the touches whose entity is this table audit the write; with none,
+    // the write takes the vanilla branch below.
+    const matched = stepCtx === null ? [] : touchesForTable(state.table, stepCtx.touches)
+    if (stepCtx !== null && matched.length > 0) {
+      // Each row is recorded under the touches whose verb matches it (verb-select.ts).
+      const selection = selectForWrite(matched, state.verb)
+      const auditCtx: AuditSelectContext = {
+        step: stepCtx,
+        touches: selection.touches,
+        split: selection.split,
+        written: selection.written,
+        actorId: resolveActorId(flow),
+        tenantId: flow.tenant,
+      }
+      // The union bounds the audit rows one value can produce.
+      const chunkValueSize = computeChunkValueSize(flow, state, selection.touches.length, rowsPerStatement(state.table))
+      if (chunkValueSize !== null) {
+        return executeChunkedAuditWrite(state, auditCtx, chunkValueSize)
+      }
+      const stmt = compileAuditWrite(db, state, auditCtx)
+      // The compiled CTE is already tenant-scoped at compile time (the user
+      // write inside the CTE was built against the scoped `pipe()` DB, so it
+      // carries the tenant filter). Execute it against the raw handle — the
+      // scoped proxy refuses `.execute()` because CTEs would otherwise bypass
+      // its per-table filtering.
+      const rawDb = pipeRaw(state.table.$options.database)
+      const rows = await rawDb.execute(stmt)
+      for (const touch of selection.written) stepCtx.markWrote(touch)
+      if (state.onConflict !== undefined) reportSkipped(state, Array.isArray(rows) ? rows.length : 0)
+      return decodeReturning(state, rows)
+    }
+  }
+  if ((state.verb === 'insert' || state.verb === 'upsert') && state.values !== undefined) {
+    const size = rowsPerStatement(state.table)
+    if (state.values.length > size) return executeChunkedWrite(state, size)
+  }
+  switch (state.verb) {
+    case 'update': return executeUpdate(db, state)
+    case 'insert': return executeInsert(db, state)
+    case 'delete': return executeDelete(db, state)
+    case 'upsert': return executeUpsert(db, state)
+  }
+}
+
+/**
+ * Returns the per-chunk `values.length` to slice at, or `null` when the write
+ * fits in a single statement. Only insert/upsert are chunkable: update/delete
+ * affected-row counts depend on the `WHERE` clause, unknown at compile time.
+ */
+function computeChunkValueSize(
+  flow: Flow,
+  state: WriteState,
+  touches: number,
+  parameterSize: number,
+): number | null {
+  if (state.verb !== 'insert' && state.verb !== 'upsert') return null
+  if (state.values === undefined) return null
+  if (touches === 0) return null
+
+  const limit = flow.instance.config.trace.auditChunkSize
+  const projectedAuditRows = state.values.length * touches
+  // Floor by touches so the per-chunk audit row count never exceeds `limit`;
+  // at least one row per chunk so single-touch writes still make progress.
+  const auditSize = Math.max(1, Math.floor(limit / touches))
+  const size = Math.min(auditSize, parameterSize)
+  if (projectedAuditRows <= limit && state.values.length <= size) return null
+  return size
+}
+
+/**
+ * Vanilla insert/upsert past the parameter limit: one statement per slice of
+ * rows, in one transaction (a savepoint when nested), returned rows in input order.
+ */
+async function executeChunkedWrite(state: WriteState, size: number): Promise<unknown> {
+  const allValues = state.values ?? []
+  const collectsRows = state.returning !== undefined && state.returning !== null
+  const collected: unknown[] = []
+  let written = 0
+  const dbName = state.table.$options.database
+  const runChunks = async (): Promise<void> => {
+    for (let i = 0; i < allValues.length; i += size) {
+      const chunkState: WriteState = { ...state, values: allValues.slice(i, i + size) }
+      const db = pipe(dbName)
+      if (state.verb === 'insert') {
+        const out = await runInsert(db, chunkState)
+        written += out.written
+        if (collectsRows && Array.isArray(out.result)) for (const row of out.result) collected.push(row)
+      } else {
+        const rows = await executeUpsert(db, chunkState)
+        if (collectsRows && Array.isArray(rows)) for (const row of rows) collected.push(row)
+      }
+    }
+  }
+  if (dbName === undefined) await pipe.transaction(runChunks)
+  else await pipe.transaction(dbName, runChunks)
+  if (state.verb === 'insert') reportSkipped(state, written)
+  return collectsRows ? collected : undefined
+}
+
+async function executeChunkedAuditWrite(
+  state: WriteState,
+  ctx: AuditSelectContext,
+  chunkValueSize: number,
+): Promise<unknown> {
+  const allValues = state.values ?? []
+  const collectsRows = state.returning !== undefined && state.returning !== null
+  const collected: unknown[] = []
+  let written = 0
+  const dbName = state.table.$options.database
+
+  // `pipe.transaction` opens a transaction when none is active and a
+  // savepoint when nested — so chunked execution is atomic in both call sites
+  // (HTTP fittings with transactionPerRequest enabled, and ad-hoc callers).
+  const runChunks = async (): Promise<void> => {
+    for (let i = 0; i < allValues.length; i += chunkValueSize) {
+      const chunk = allValues.slice(i, i + chunkValueSize)
+      const chunkState: WriteState = { ...state, values: chunk }
+      const scoped = pipe(dbName)
+      const stmt = compileAuditWrite(scoped, chunkState, ctx)
+      const rawDb = pipeRaw(dbName)
+      const rows = await rawDb.execute(stmt)
+      if (Array.isArray(rows)) written += rows.length
+      if (collectsRows && Array.isArray(rows)) {
+        for (const row of rows) collected.push(row)
+      }
+    }
+  }
+  if (dbName === undefined) {
+    await pipe.transaction(runChunks)
+  } else {
+    await pipe.transaction(dbName, runChunks)
+  }
+
+  // An upsert marks the touches of both verb sets: which rows took which is not known here.
+  for (const touch of ctx.written) ctx.step.markWrote(touch)
+  if (state.onConflict !== undefined) reportSkipped(state, written)
+  return collectsRows ? decodeReturning(state, collected) : undefined
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle's DB/builder types are deeply generic; the WriteState shape has already validated the caller's input at the builder surface
+type AnyDb = any
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyChain = any
+
+async function executeUpdate(db: AnyDb, state: WriteState): Promise<unknown> {
+  let q: AnyChain = db.update(state.table).set(state.set ?? {})
+  if (state.where !== undefined) q = q.where(state.where)
+  return runWithReturning(q, state.returning)
+}
+
+async function executeInsert(db: AnyDb, state: WriteState): Promise<unknown> {
+  const out = await runInsert(db, state)
+  reportSkipped(state, out.written)
+  return out.result
+}
+
+/**
+ * One insert statement. Under `onConflictDoNothing` the rows written are the
+ * rows the statement returns, so it asks for them when the caller did not; the
+ * caller still gets what it asked for.
+ */
+async function runInsert(db: AnyDb, state: WriteState): Promise<{ result: unknown; written: number }> {
+  const q: AnyChain = applyOnConflict(db.insert(state.table).values(state.values ?? []), state)
+  if (state.onConflict === undefined) return { result: await runWithReturning(q, state.returning), written: 0 }
+  const rows = await runWithReturning(q, state.returning ?? 'all') as unknown[]
+  const caller = state.returning === undefined || state.returning === null
+  return { result: caller ? [] : rows, written: rows.length }
+}
+
+async function executeDelete(db: AnyDb, state: WriteState): Promise<unknown> {
+  let q: AnyChain = db.delete(state.table)
+  if (state.where !== undefined) q = q.where(state.where)
+  return runWithReturning(q, state.returning)
+}
+
+async function executeUpsert(db: AnyDb, state: WriteState): Promise<unknown> {
+  if (state.onConflictColumns === undefined || state.onConflictColumns.length === 0) {
+    throw new Error(
+      'pipe.upsert requires .onConflict([...columns]). ' +
+      'Pass the conflict-target columns that determine "this row already exists" — ' +
+      'usually the primary key or a unique index.',
+    )
+  }
+  const targetColumns = state.onConflictColumns.map(key => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DefinedTable columns are indexed by field key; the lookup is validated at the builder surface
+    const col = (state.table as any)[key]
+    if (col === undefined) {
+      throw new Error(
+        `pipe.upsert: onConflict column "${key}" is not a field of "${state.table.$name}". ` +
+        `Use a field key declared on the table.`,
+      )
+    }
+    return col as unknown
+  })
+
+  let q: AnyChain = db.insert(state.table).values(state.values ?? [])
+  if (state.set === undefined) {
+    q = q.onConflictDoNothing({ target: targetColumns })
+  } else {
+    q = q.onConflictDoUpdate({ target: targetColumns, set: state.set })
+  }
+  return runWithReturning(q, state.returning)
+}
+
+function runWithReturning(q: AnyChain, returning: WriteState['returning']): Promise<unknown> {
+  if (returning === undefined || returning === null) return q as Promise<unknown>
+  if (returning === 'all') return q.returning() as Promise<unknown>
+  return q.returning(returning) as Promise<unknown>
+}

package/src/data/write/index.ts

@@ -0,0 +1,11 @@
+// Re-exports the pipework-owned write surface. Wired into the `pipe` namespace
+// in src/data/db/namespace.ts as `pipe.update / pipe.insert / pipe.delete /
+// pipe.upsert` — the only consumer-facing way to mutate pipework-managed
+// tables (Q8). The raw-write lint rule (#47) enforces that callers don't
+// reach past this surface into drizzle directly.
+
+export { update, UpdateBuilder } from './update.js'
+export { insert, InsertBuilder } from './insert.js'
+export { remove, DeleteBuilder } from './delete.js'
+export { upsert, UpsertBuilder } from './upsert.js'
+export type { WriteState, WriteVerb, ReturningShape } from './state.js'

package/src/data/write/insert.ts

@@ -0,0 +1,63 @@
+// `pipe.insert(table)` — the pipework-owned insert builder. Same intent-based
+// design as UpdateBuilder; see update.ts for the rationale.
+
+import type { PgTable } from '../query/pg-core/index.js'
+import { assertNotExternal } from '../domain/external-registry.js'
+import type { DefinedTable } from '../domain/types.js'
+import type { WriteState } from './state.js'
+import type { InsertValues } from './values.js'
+import { executeWrite } from './execute.js'
+
+export class InsertBuilder<T extends PgTable, TResult = unknown> implements PromiseLike<TResult> {
+  constructor(private readonly state: WriteState) {}
+
+  values(rows: InsertValues<T> | ReadonlyArray<InsertValues<T>>): InsertBuilder<T, TResult> {
+    const normalized = Array.isArray(rows) ? rows : [rows]
+    return new InsertBuilder<T, TResult>({
+      ...this.state,
+      values: normalized as ReadonlyArray<Record<string, unknown>>,
+    })
+  }
+
+  /**
+   * Leaves a row that conflicts with an existing one and inserts the rest.
+   * Without `target`, any unique or exclusion constraint conflict is skipped.
+   * `.returning()` yields only the rows written, so a fully skipped insert
+   * returns `[]`. Under `@touches`, a skipped row gets no audit row; a traced
+   * flow records an `external:pipework.insert.conflict` step with the counts.
+   */
+  onConflictDoNothing(options?: { target?: readonly (keyof T['$inferSelect'] & string)[] }): InsertBuilder<T, TResult> {
+    const target = options?.target
+    if (target !== undefined && target.length === 0) {
+      throw new Error(
+        'pipe.insert onConflictDoNothing target must not be empty. ' +
+        'Pass the field keys of the unique constraint, or omit target to skip a conflict on any constraint.',
+      )
+    }
+    return new InsertBuilder<T, TResult>({
+      ...this.state,
+      onConflict: target === undefined ? { action: 'nothing' } : { action: 'nothing', target: target as readonly string[] },
+    })
+  }
+
+  returning(): InsertBuilder<T, Record<string, unknown>[]>
+  returning<TShape extends Record<string, unknown>>(shape: TShape): InsertBuilder<T, Record<string, unknown>[]>
+  returning(shape?: Record<string, unknown>): InsertBuilder<T, Record<string, unknown>[]> {
+    const returning = shape === undefined ? 'all' as const : shape
+    return new InsertBuilder<T, Record<string, unknown>[]>({ ...this.state, returning })
+  }
+
+  then<TFulfilled = TResult, TRejected = never>(
+    onfulfilled?: ((value: TResult) => TFulfilled | PromiseLike<TFulfilled>) | null,
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): PromiseLike<TFulfilled | TRejected> {
+    return executeWrite(this.state).then(onfulfilled as (value: unknown) => TFulfilled, onrejected) as PromiseLike<TFulfilled | TRejected>
+  }
+}
+
+/** Starts a pipework-owned insert against `table`. Chain with `.values(...).returning(...)`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function insert<T extends DefinedTable<any> & PgTable>(table: T): InsertBuilder<T, any> {
+  assertNotExternal(table, 'insert')
+  return new InsertBuilder<T, unknown>({ verb: 'insert', table })
+}

package/src/data/write/state.ts

@@ -0,0 +1,43 @@
+// The intent of a pending write — the data shape every write builder hands to
+// the executor. Today (#44) the executor compiles it to vanilla DML through
+// drizzle. The CTE generator (#45) reads the same shape to compile to a single
+// statement with `before` / `updated` / `diffs` / `audit_inserts` CTEs when an
+// active flow_step carries `@touches`. Keeping the intent on a plain data
+// object — never on the builder's drizzle handle — is what makes both paths
+// produce the same observable behavior.
+
+import type { SQL } from '../db/types.js'
+import type { DefinedTable, FieldRecord } from '../domain/types.js'
+
+export type WriteVerb = 'insert' | 'update' | 'delete' | 'upsert'
+
+/**
+ * What the caller asked the write to return.
+ *
+ * - `null` (default) — no `RETURNING` clause; the executor resolves to `void`.
+ * - `'all'` — `RETURNING *`; the executor resolves to every column on the row.
+ * - `Record<string, unknown>` — a per-field projection, as accepted by
+ *   drizzle's `.returning(...)` (column references, sql expressions, etc.).
+ */
+export type ReturningShape = Record<string, unknown> | 'all' | null
+
+export interface WriteState {
+  readonly verb: WriteVerb
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DefinedTable's field generics erase at the write boundary; the executor only needs the table-level surface ($options, drizzle columns)
+  readonly table: DefinedTable<any>
+  /** `set` clause for `update` / `upsert`. */
+  readonly set?: Record<string, unknown>
+  /** Row values for `insert` / `upsert`. */
+  readonly values?: ReadonlyArray<Record<string, unknown>>
+  /** `where` clause for `update` / `delete`. */
+  readonly where?: SQL
+  /** Conflict-target columns for `upsert`. */
+  readonly onConflictColumns?: readonly string[]
+  /** `ON CONFLICT DO NOTHING` for `insert`; `target` is field keys, absent for the bare clause. */
+  readonly onConflict?: { readonly action: 'nothing'; readonly target?: readonly string[] }
+  /** What `RETURNING` should produce. `null` (default) emits no RETURNING. */
+  readonly returning?: ReturningShape
+}
+
+/** Carrier type used by the builders' chain methods to mutate `WriteState` immutably. */
+export type FieldRecordTable = DefinedTable<FieldRecord>