pipework 0.252.0 → 0.252.1

package/src/data/domain/projections.ts

@@ -0,0 +1,57 @@
+import type { FieldDescriptor, FieldFlags, FieldRecord } from './types.js'
+import type { InferFieldOutput } from './brand.js'
+
+type FlagsOf<F> = F extends FieldDescriptor<unknown, infer TF> ? TF : FieldFlags
+type HasFlag<F, K extends keyof FieldFlags> = FlagsOf<F>[K] extends true ? true : false
+
+type InsertIncluded<F> =
+  HasFlag<F, 'autoManaged'> extends true ? false
+  : HasFlag<F, 'generated'> extends true ? false
+  : HasFlag<F, 'primaryKey'> extends true
+    ? HasFlag<F, 'defaultRandom'> extends true ? false
+      : HasFlag<F, 'serial'> extends true ? false
+      : true
+    : true
+
+type InsertOptional<F> =
+  HasFlag<F, 'nullable'> extends true ? true
+  : HasFlag<F, 'hasDefault'> extends true ? true
+  : false
+
+type InsertRequiredKeys<TFields extends FieldRecord> = {
+  [K in keyof TFields]: InsertIncluded<TFields[K]> extends true
+    ? InsertOptional<TFields[K]> extends true ? never : K
+    : never
+}[keyof TFields]
+
+type InsertOptionalKeys<TFields extends FieldRecord> = {
+  [K in keyof TFields]: InsertIncluded<TFields[K]> extends true
+    ? InsertOptional<TFields[K]> extends true ? K : never
+    : never
+}[keyof TFields]
+
+/** Insert input shape: omits auto-managed and PK+(defaultRandom|serial); marks nullable/defaulted fields optional. */
+export type InsertProjection<TFields extends FieldRecord> =
+  { -readonly [K in InsertRequiredKeys<TFields>]: InferFieldOutput<TFields[K]> }
+  & { -readonly [K in InsertOptionalKeys<TFields>]?: InferFieldOutput<TFields[K]> }
+
+/** Select output shape: includes every field with its nullable status preserved through TOutput. */
+export type SelectProjection<TFields extends FieldRecord> = {
+  -readonly [K in keyof TFields]: InferFieldOutput<TFields[K]>
+}
+
+type UpdateIncluded<F> =
+  HasFlag<F, 'primaryKey'> extends true ? false
+  : HasFlag<F, 'readOnly'> extends true ? false
+  : HasFlag<F, 'autoManaged'> extends true ? false
+  : HasFlag<F, 'generated'> extends true ? false
+  : true
+
+type UpdateIncludedKeys<TFields extends FieldRecord> = {
+  [K in keyof TFields]: UpdateIncluded<TFields[K]> extends true ? K : never
+}[keyof TFields]
+
+/** Update input shape: omits PK/readOnly/auto-managed; all remaining fields are optional. */
+export type UpdateProjection<TFields extends FieldRecord> = {
+  -readonly [K in UpdateIncludedKeys<TFields>]?: InferFieldOutput<TFields[K]>
+}

package/src/data/domain/trace-safe-projection.ts

@@ -0,0 +1,31 @@
+// The trace-safe projection of a domain definition: the subset of its fields a
+// trace step is allowed to capture into its input snapshot. A field is in the
+// projection only if it was explicitly marked `.traceSafe()` — fail-closed, so
+// a newly added field is never captured by accident.
+
+import type { FieldDescriptor } from './types.js'
+
+/** Field keys marked `.traceSafe()`, in declaration order. */
+export function traceSafeKeys(fields: Record<string, FieldDescriptor>): readonly string[] {
+  return Object.keys(fields).filter(key => fields[key]!._meta.traceSafe)
+}
+
+/**
+ * Project a row down to its trace-safe fields.
+ *
+ * Keys not declared `.traceSafe()` are dropped. Keys that are trace-safe but
+ * absent from `row` are skipped rather than emitted as `undefined`, so a
+ * partial row projects to a partial result with no holes.
+ */
+export function projectTraceSafe(
+  fields: Record<string, FieldDescriptor>,
+  row: Record<string, unknown>,
+): Record<string, unknown> {
+  const projected: Record<string, unknown> = {}
+  for (const key of traceSafeKeys(fields)) {
+    if (Object.prototype.hasOwnProperty.call(row, key)) {
+      projected[key] = row[key]
+    }
+  }
+  return projected
+}

package/src/data/domain/traits.ts

@@ -0,0 +1,108 @@
+import { field } from './field.js'
+import type { FieldDescriptor, TraitDefinition } from './types.js'
+
+function autoManaged(f: FieldDescriptor): FieldDescriptor {
+  return { _meta: { ...f._meta, autoManaged: true } }
+}
+
+function autoManagedReadOnly(f: FieldDescriptor): FieldDescriptor {
+  return { _meta: { ...f._meta, autoManaged: true, readOnly: true } }
+}
+
+export const effectiveDatedTrait: TraitDefinition = {
+  name: 'effectiveDated',
+  fields: {
+    effectiveFrom: autoManaged(field.timestamp().default('now')),
+    effectiveTo: autoManaged(field.timestamp().nullable()),
+    version: autoManaged(field.integer().default(1)),
+  },
+}
+
+/**
+ * Versions that are only ever appended: each row is in force from its
+ * `effectiveFrom` until the next row's, so no column is ever set on an earlier
+ * version. Numbered per scope (the tenant field if the definition has one,
+ * otherwise the whole table). Write with `temporal.setVersion`, read with
+ * `temporal.versionAt`.
+ *
+ * `pipework migrate generate` adds a trigger refusing UPDATE and DELETE and a
+ * unique index on (scope, version) — only in the migration that has the
+ * CREATE TABLE for the table, like tenant RLS.
+ */
+export const appendOnlyVersionsTrait: TraitDefinition = {
+  name: 'appendOnlyVersions',
+  fields: {
+    effectiveFrom: autoManaged(field.timestamp()),
+    version: autoManaged(field.integer()),
+    setBy: autoManaged(field.text().nullable()),
+  },
+}
+
+export const auditedTrait: TraitDefinition = {
+  name: 'audited',
+  fields: {
+    createdAt: autoManagedReadOnly(field.timestamp().default('now')),
+    updatedAt: autoManaged(field.timestamp().default('now')),
+    createdBy: autoManagedReadOnly(field.text().nullable()),
+    updatedBy: autoManaged(field.text().nullable()),
+  },
+}
+
+export const softDeletedTrait: TraitDefinition = {
+  name: 'softDeleted',
+  fields: {
+    deletedAt: autoManaged(field.timestamp().nullable()),
+    deletedBy: autoManaged(field.text().nullable()),
+  },
+}
+
+const TRAIT_CONFLICTS: ReadonlyArray<readonly [string, string, string]> = [
+  ['appendOnlyVersions', 'effectiveDated',
+    'effectiveDated closes the previous version by UPDATE-ing effectiveTo and both define effectiveFrom and version, while appendOnlyVersions forbids every UPDATE.'],
+  ['appendOnlyVersions', 'softDeleted',
+    'softDeleted marks a row deleted by UPDATE, while appendOnlyVersions forbids every UPDATE and DELETE.'],
+]
+
+export function applyTrait(
+  definitionName: string,
+  existingFields: Record<string, FieldDescriptor>,
+  existingTraits: string[],
+  trait: TraitDefinition,
+): { fields: Record<string, FieldDescriptor>; traits: string[] } {
+  if (existingTraits.includes(trait.name)) {
+    throw new Error(
+      `[pipework] Trait "${trait.name}" is already applied to "${definitionName}".`,
+    )
+  }
+
+  for (const [a, b, why] of TRAIT_CONFLICTS) {
+    const other = trait.name === a ? b : trait.name === b ? a : undefined
+    if (other !== undefined && existingTraits.includes(other)) {
+      throw new Error(
+        `[pipework] Traits "${a}" and "${b}" cannot be combined on "${definitionName}".\n\n` +
+        `  ${why}\n` +
+        `  Use one of them.`,
+      )
+    }
+  }
+
+  for (const fieldName of Object.keys(trait.fields)) {
+    if (fieldName in existingFields) {
+      throw new Error(
+        `[pipework] Trait "${trait.name}" adds field "${fieldName}" which already exists in "${definitionName}".\n\n` +
+        `  Remove the field from your definition or choose a different name.\n` +
+        `  Trait "${trait.name}" provides: ${Object.keys(trait.fields).join(', ')}`,
+      )
+    }
+  }
+
+  return {
+    fields: { ...existingFields, ...trait.fields },
+    traits: [...existingTraits, trait.name],
+  }
+}
+
+/** The field versions are numbered within: the definition's tenant field, else undefined (the whole table). */
+export function appendOnlyScopeField(definition: { readonly $fields: Record<string, FieldDescriptor> }): string | undefined {
+  return Object.keys(definition.$fields).find((key) => definition.$fields[key]!._meta.tenant === true)
+}

package/src/data/domain/types.ts

@@ -0,0 +1,289 @@
+import type { CollationName } from '../query/collation.js'
+import type { z } from 'zod/v4'
+import type { SQL, Table } from '../db/types.js'
+import type { InferSelect, InferFieldOutput } from './brand.js'
+import type { AnyPgColumn, PgTable } from '../query/pg-core/index.js'
+import type { AcceptReadonly } from '../db/readonly.js'
+import type { InsertProjection, SelectProjection, UpdateProjection } from './projections.js'
+
+export type FieldKind =
+  | 'uuid'
+  | 'text'
+  | 'integer'
+  | 'serial'
+  | 'bigint'
+  | 'boolean'
+  | 'timestamp'
+  | 'date'
+  | 'enum'
+  | 'jsonb'
+  | 'decimal'
+  | 'money'
+  | 'pgLsn'
+  | 'custom'
+
+export interface FieldMeta {
+  readonly kind: FieldKind
+  readonly nullable: boolean
+  readonly hasDefault: boolean
+  readonly defaultValue?: unknown
+  readonly primaryKey: boolean
+  readonly defaultRandom: boolean
+  readonly unique: boolean
+  readonly readOnly: boolean
+  readonly tenant: boolean
+  /** A stored generated column: Postgres computes it from `as`; writers never send it. */
+  readonly generated?: { readonly as: SQL | (() => SQL) }
+  /** The column's collation (text fields only): `COLLATE "name"` in generated migrations. */
+  readonly collation?: CollationName
+  /** A list of the field's type (`uuid[]`, `text[]`); `.min/.max/...` apply to each element. */
+  readonly array: boolean
+  /**
+   * Whether this field may be captured into a trace step's input snapshot.
+   * Fail-closed: fields are trace-unsafe unless `.traceSafe()` opts them in,
+   * so a new field is never captured by accident.
+   */
+  readonly traceSafe: boolean
+  readonly brand?: string
+  readonly reference?: {
+    /**
+     * Eager DefinedTable, or a thunk returning one. The thunk form lets a
+     * field reference its own table (self-reference) or a table defined later
+     * in the same import cycle (forward-reference) — the thunk is only
+     * resolved at table build / validation time, after the cycle has settled.
+     */
+    readonly definition: DomainDefinition | (() => DomainDefinition)
+    readonly field: string
+    /**
+     * When `false`, the brand and the validator's brand-reuse check inherit
+     * from the referenced field, but no FK constraint is emitted in the
+     * generated DDL. Used for cross-partition references where an enforced
+     * FK would prevent independent partition lifecycle (e.g. `audit_record`
+     * keeping `traceId` after the trace partition is dropped). Default true.
+     */
+    readonly enforced?: boolean
+  }
+  readonly min?: number
+  readonly max?: number
+  readonly autoManaged: boolean
+  readonly email: boolean
+  readonly url: boolean
+  readonly regex?: RegExp
+  readonly precision?: { readonly p: number; readonly s: number }
+  readonly enumValues?: readonly string[]
+  readonly jsonbShape?: z.ZodType
+  readonly serializedAs?: 'string'
+  readonly customColumn?: unknown
+  readonly customValidator?: z.ZodType
+}
+
+/**
+ * Phantom flags tracked at the type level so insert/select/update projection
+ * types can omit auto-managed columns, mark primary-key+defaulted columns as
+ * optional, etc. The runtime reads from `_meta`; `_flags` exists only for the
+ * type system.
+ */
+export interface FieldFlags {
+  readonly nullable?: boolean
+  readonly hasDefault?: boolean
+  readonly primaryKey?: boolean
+  readonly defaultRandom?: boolean
+  readonly autoManaged?: boolean
+  readonly readOnly?: boolean
+  /** A stored generated column; omitted from insert and update shapes. */
+  readonly generated?: boolean
+  readonly serial?: boolean
+  /** The tenant column; a scoped write fills it from the flow, so inserts may omit it. */
+  readonly tenant?: boolean
+}
+
+/** A field in a domain definition — carries runtime metadata and phantom output/flag types. */
+export interface FieldDescriptor<TOutput = unknown, TFlags extends FieldFlags = FieldFlags> {
+  readonly _meta: FieldMeta
+  readonly _output?: TOutput
+  readonly _flags?: TFlags
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- variance-safe constraint for exactOptionalPropertyTypes
+type AnyFieldDescriptor = FieldDescriptor<any, any>
+
+/** Constraint alias for generic bounds — safe under exactOptionalPropertyTypes. */
+export type FieldRecord = Record<string, AnyFieldDescriptor>
+
+/** Referential action for a foreign key on UPDATE / DELETE. */
+export type ForeignKeyAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default'
+
+/** A multi-column foreign key — the only way to reference a partitioned table's composite key. */
+export interface CompositeForeignKey {
+  /** Local field keys forming the key, in order. */
+  readonly columns: readonly string[]
+  readonly references: {
+    /**
+     * Eager DefinedTable or a thunk returning one. The thunk form lets a
+     * composite FK target a table from the same import cycle (e.g.
+     * `trace_step` referencing `trace` where both modules import each other
+     * via field-level thunked references).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DefinedTable's PgTable base is invariant under exactOptionalPropertyTypes; the concrete field generics are irrelevant here
+    readonly definition: DefinedTable<any> | (() => DefinedTable<any>)
+    /** Foreign field keys, positionally matched to `columns`. */
+    readonly columns: readonly string[]
+  }
+  /**
+   * `{ setNull: [...] }` / `{ setDefault: [...] }` clear only the listed local
+   * fields (Postgres 15+), so a tenant column in the key stays in place.
+   */
+  readonly onDelete?: ForeignKeyAction | { readonly setNull: readonly string[] } | { readonly setDefault: readonly string[] }
+  readonly onUpdate?: ForeignKeyAction
+}
+
+/** Resolves a possibly-lazy definition reference to its concrete DefinedTable. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- structural pass-through; concrete generics flow at the call site
+export function resolveDefinitionRef<T extends DefinedTable<any>>(ref: T | (() => T)): T {
+  return typeof ref === 'function' ? ref() : ref
+}
+
+/** Declares a table as RANGE-partitioned. The partition column must be part of the primary key. */
+export interface PartitionSpec {
+  readonly strategy: 'range'
+  /** Field key of the partition column. */
+  readonly column: string
+}
+
+/** Options for pipe.define() — database affinity, virtual mode, custom indexes, keys, partitioning. */
+export interface DefineOptions {
+  readonly database?: string
+  readonly virtual?: boolean
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle column/index types are deeply generic
+  readonly indexes?: (columns: Record<string, any>) => Record<string, any>
+  /** Composite primary key by field key. Mutually exclusive with field-level .primaryKey(). */
+  readonly primaryKey?: readonly string[]
+  /** Multi-column foreign keys. Single-column FKs use field-level .references(). */
+  readonly foreignKeys?: readonly CompositeForeignKey[]
+  /** Marks the table RANGE-partitioned. Partitions are managed outside the migration. */
+  readonly partitionBy?: PartitionSpec
+  /**
+   * The `@touches` entity name writes to this table are audited under. When set it
+   * must equal the touch's entity exactly; otherwise the touch matches by normalized
+   * name (case-insensitive, underscores ignored, table name optionally plural).
+   */
+  readonly auditEntity?: string
+}
+
+/** Column type projected from a FieldDescriptor — carries the right data type for Drizzle operators. */
+export type FieldColumn<F extends FieldDescriptor, TName extends string = string> = AnyPgColumn<{
+  data: NonNullable<InferFieldOutput<F>>
+  notNull: null extends InferFieldOutput<F> ? false : true
+  // A tenant column counts as defaulted: the scoped `pipe()` DB fills it from the flow (auth/tenant/scoped-db.ts wrapInsertBuilder).
+  hasDefault: F extends FieldDescriptor<unknown, infer TF> ? (TF['hasDefault'] extends true ? true : TF['tenant'] extends true ? true : TF['generated'] extends true ? true : false) : false
+  tableName: TName
+}> & {
+  // Plain columns are neither generated nor identity, so drizzle's insert model lists them as optional when nullable/defaulted;
+  // a `.generatedAlwaysAs()` field is generated, which drizzle's insert and update models omit.
+  readonly _: { readonly generated: F extends FieldDescriptor<unknown, infer TF> ? (TF['generated'] extends true ? { type: 'always' } : undefined) : undefined; readonly identity: undefined }
+}
+
+/** Maps field definitions to typed Drizzle column references. */
+export type ProjectedColumns<TFields extends FieldRecord, TName extends string = string> = {
+  readonly [K in keyof TFields & string]: FieldColumn<TFields[K], TName>
+}
+
+/** Definition metadata and projection methods — the non-table surface of a DefinedTable. */
+export interface DefinitionMethods<TFields extends FieldRecord = FieldRecord, TName extends string = string> {
+  readonly $name: TName
+  readonly $fields: TFields
+  readonly $options: DefineOptions
+  readonly $traits: readonly string[]
+  table(): Table
+  insertShape(): z.ZodType<InsertProjection<TFields>>
+  selectShape(): z.ZodType<SelectProjection<TFields>>
+  updateShape(): z.ZodType<UpdateProjection<TFields>>
+  factory(): FactoryBuilder
+  effectiveDated(): DefinedTable<TFields & EffectiveDatedFields, TName>
+  /** Versions never updated or deleted; see `temporal.setVersion` / `temporal.versionAt`. Not combinable with effectiveDated or softDeleted. */
+  appendOnlyVersions(): DefinedTable<TFields & AppendOnlyVersionsFields, TName>
+  audited(): DefinedTable<TFields & AuditedFields, TName>
+  softDeleted(): DefinedTable<TFields & SoftDeletedFields, TName>
+  readonly Select: InferSelect<TFields>
+  readonly Insert: AcceptReadonly<InsertProjection<TFields>>
+  readonly Update: AcceptReadonly<UpdateProjection<TFields>>
+}
+
+/**
+ * A domain definition that IS a Drizzle PgTable — columns are direct properties,
+ * usable in from(), eq(), orderBy(), joins, and partial selects.
+ *
+ * Created by pipe.define(). Metadata uses $ prefix ($name, $fields, $options, $traits)
+ * to avoid collisions with column properties.
+ *
+ * The PgTable base is parameterized with ProjectedColumns so that Drizzle's
+ * _['columns'] carries named, branded column types. Without this, select()
+ * and returning() fall back to index-signature records.
+ */
+export type DefinedTable<TFields extends FieldRecord = FieldRecord, TName extends string = string> =
+  PgTable<{ name: TName; schema: string | undefined; columns: ProjectedColumns<TFields, TName>; dialect: 'pg' }>
+  & ProjectedColumns<TFields, TName>
+  & DefinitionMethods<TFields, TName>
+
+/**
+ * A table or view owned by another service, declared with pipe.external. Readable
+ * with every query operator; not a DefinedTable, so the write builders reject it.
+ */
+export type ExternalTable<TFields extends FieldRecord = FieldRecord, TName extends string = string> =
+  PgTable<{ name: TName; schema: string; columns: ProjectedColumns<TFields, TName>; dialect: 'pg' }>
+  & ProjectedColumns<TFields, TName>
+  & {
+    readonly $name: TName
+    readonly $fields: TFields
+    readonly $external: { readonly schema: string; readonly table: string }
+    selectShape(): z.ZodType<SelectProjection<TFields>>
+    readonly Select: InferSelect<TFields>
+  }
+
+/**
+ * @deprecated Use DefinedTable instead. DomainDefinition is kept for backward compatibility
+ * with code that hasn't migrated to the direct-column-access API.
+ */
+export type DomainDefinition<TFields extends FieldRecord = FieldRecord, TName extends string = string> =
+  DefinedTable<TFields, TName>
+
+/** A named set of fields that can be applied to a domain definition via trait methods. */
+export interface TraitDefinition {
+  readonly name: string
+  readonly fields: FieldRecord
+}
+
+export interface EffectiveDatedFields {
+  readonly effectiveFrom: FieldDescriptor<Date, { autoManaged: true; hasDefault: true }>
+  readonly effectiveTo: FieldDescriptor<Date | null, { autoManaged: true; nullable: true }>
+  readonly version: FieldDescriptor<number, { autoManaged: true; hasDefault: true }>
+}
+
+export interface AppendOnlyVersionsFields {
+  readonly effectiveFrom: FieldDescriptor<Date, { autoManaged: true }>
+  readonly version: FieldDescriptor<number, { autoManaged: true }>
+  readonly setBy: FieldDescriptor<string | null, { autoManaged: true; nullable: true }>
+}
+
+export interface AuditedFields {
+  readonly createdAt: FieldDescriptor<Date, { autoManaged: true; readOnly: true; hasDefault: true }>
+  readonly updatedAt: FieldDescriptor<Date, { autoManaged: true; hasDefault: true }>
+  readonly createdBy: FieldDescriptor<string | null, { autoManaged: true; readOnly: true; nullable: true }>
+  readonly updatedBy: FieldDescriptor<string | null, { autoManaged: true; nullable: true }>
+}
+
+export interface SoftDeletedFields {
+  readonly deletedAt: FieldDescriptor<Date | null, { autoManaged: true; nullable: true }>
+  readonly deletedBy: FieldDescriptor<string | null, { autoManaged: true; nullable: true }>
+}
+
+/** Test data factory — inserts rows and resolves FK dependencies automatically. */
+export interface FactoryBuilder {
+  create(overrides?: Partial<Record<string, unknown>>, options?: FactoryOptions): Promise<Record<string, unknown>>
+  createMany(count: number, overrides?: Partial<Record<string, unknown>> | ((index: number) => Partial<Record<string, unknown>>), options?: FactoryOptions): Promise<Record<string, unknown>[]>
+}
+
+export interface FactoryOptions {
+  readonly db?: unknown
+  readonly tenantId?: string
+}

package/src/data/jsonb/composed.ts

@@ -0,0 +1,18 @@
+import type { SQL, Column } from '../db/types.js'
+import { cast } from '../db/expressions.js'
+import { pathText } from './query.js'
+
+/** Extracts a boolean from a JSONB column: `(column->>'key')::boolean`. Supports nested paths. */
+export function boolean(column: Column | SQL, ...keys: string[]): SQL<boolean> {
+  return cast<boolean>(pathText(column, ...keys), 'boolean')
+}
+
+/** Extracts a number from a JSONB column: `(column->>'key')::numeric`. Supports nested paths. */
+export function number(column: Column | SQL, ...keys: string[]): SQL<number> {
+  return cast<number>(pathText(column, ...keys), 'numeric')
+}
+
+/** Extracts an integer from a JSONB column: `(column->>'key')::integer`. Supports nested paths. */
+export function integer(column: Column | SQL, ...keys: string[]): SQL<number> {
+  return cast<number>(pathText(column, ...keys), 'integer')
+}

package/src/data/jsonb/index.ts

@@ -0,0 +1 @@
+export { contains, containedBy, hasKey } from './query.js'

package/src/data/jsonb/namespace.ts

@@ -0,0 +1,30 @@
+import { contains, merge, remove, containedBy, hasKey, text, json, path, pathText } from './query.js'
+import { boolean, number, integer } from './composed.js'
+
+/** JSONB query operators — typed helpers for PostgreSQL JSONB containment, key checks, and field extraction. */
+export const jsonb = {
+  /** The @> containment operator — tests whether a JSONB column contains the given value. */
+  contains,
+  /** Merges an object into a JSONB column in `.set()`: `coalesce(col, '{}') || value`. Top-level keys overwrite; others are kept. */
+  merge,
+  /** Removes top-level keys from a JSONB column in `.set()`: `col - 'key'`. Composes as the column of `jsonb.merge`. */
+  remove,
+  /** The <@ contained-by operator — tests whether a JSONB column is contained by the given value. */
+  containedBy,
+  /** The ? key-existence operator — tests whether a JSONB column has the given top-level key. */
+  hasKey,
+  /** Extracts a text value: `column->>'key'`. Composable with pipe.filter operators. */
+  text,
+  /** Extracts a JSONB value: `column->'key'`. Returns JSONB — use with jsonb.contains() etc. */
+  json,
+  /** Extracts a nested JSONB value: `column->'a'->'b'`. Returns JSONB. */
+  path,
+  /** Extracts a nested text value: `column->'a'->>'b'`. Intermediate keys use `->`, final uses `->>`. */
+  pathText,
+  /** Extracts a boolean: `(column->>'key')::boolean`. Supports nested paths. */
+  boolean,
+  /** Extracts a number: `(column->>'key')::numeric`. Supports nested paths. */
+  number,
+  /** Extracts an integer: `(column->>'key')::integer`. Supports nested paths. */
+  integer,
+}

package/src/data/jsonb/query.ts

@@ -0,0 +1,86 @@
+import { sql } from '../db/sql.js'
+import type { SQL, Column } from '../db/types.js'
+
+export function contains(column: Column | SQL, value: unknown): SQL<boolean> {
+  return sql<boolean>`${column} @> ${JSON.stringify(value)}::jsonb`
+}
+
+export function containedBy(column: Column | SQL, value: unknown): SQL<boolean> {
+  return sql<boolean>`${column} <@ ${JSON.stringify(value)}::jsonb`
+}
+
+export function hasKey(column: Column | SQL, key: string): SQL<boolean> {
+  return sql<boolean>`${column} ? ${key}`
+}
+
+/** Extracts a text value from a JSONB column: `column->>'key'`. Composable with pipe.filter operators (eq, ilike, etc.). */
+export function text(column: Column | SQL, key: string): SQL<string> {
+  return sql<string>`${column}->>${key}`
+}
+
+/** Extracts a JSONB value from a JSONB column: `column->'key'`. Returns JSONB, not text — use with jsonb.contains() etc. */
+export function json(column: Column | SQL, key: string): SQL {
+  return sql`${column}->${key}`
+}
+
+/** Extracts a nested JSONB value: `column->'a'->'b'`. Returns JSONB. For text output, use `pathText`. */
+export function path(column: Column | SQL, ...keys: string[]): SQL {
+  if (keys.length === 0) return sql`${column}`
+  let result: SQL = sql`${column}`
+  for (const key of keys) {
+    result = sql`${result}->${key}`
+  }
+  return result
+}
+
+/** Extracts a nested text value: `column->'a'->>'b'`. Intermediate keys use `->`, final key uses `->>`. */
+export function pathText(column: Column | SQL, ...keys: string[]): SQL<string> {
+  if (keys.length === 0) return sql<string>`${column}`
+  if (keys.length === 1) return text(column, keys[0]!)
+  const intermediateKeys = keys.slice(0, -1)
+  const finalKey = keys[keys.length - 1]!
+  const intermediate = path(column, ...intermediateKeys)
+  return text(intermediate, finalKey)
+}
+
+/**
+ * Merges `value` into a JSONB column for `.set()`: `coalesce(col, '{}'::jsonb) || value::jsonb`. Top-level keys
+ * in `value` overwrite; others are kept; a null column becomes `value`. The merge happens in the statement,
+ * so concurrent updates that touch different keys both survive.
+ */
+export function merge(column: Column | SQL, value: Record<string, unknown>): SQL {
+  const checked: unknown = value
+  if (typeof checked !== 'object' || checked === null || Array.isArray(checked)) {
+    throw new Error(
+      `[pipework] jsonb.merge() needs a plain object, got ${checked === null ? 'null' : Array.isArray(checked) ? 'an array' : typeof checked}.\n\n` +
+      '  Only an object can be merged into an object.\n' +
+      "  Fix: pass an object: jsonb.merge(col, { key: 'value' }).\n",
+    )
+  }
+  return sql`coalesce(${column}, '{}'::jsonb) || ${JSON.stringify(value)}::jsonb`
+}
+
+/**
+ * Removes top-level keys from a JSONB column for `.set()`: `col - key`, or `col - array[k1, k2]::text[]` for
+ * several. Missing keys are ignored; a null column stays null. Composes as the column of `jsonb.merge`.
+ */
+export function remove(column: Column | SQL, ...keys: string[]): SQL {
+  if (keys.length === 0) {
+    throw new Error(
+      '[pipework] jsonb.remove() needs at least one key.\n\n' +
+      '  With no keys there is nothing to remove.\n' +
+      "  Fix: pass the keys to drop: jsonb.remove(col, 'key').\n",
+    )
+  }
+  for (const key of keys as unknown[]) {
+    if (typeof key !== 'string') {
+      throw new Error(
+        `[pipework] jsonb.remove() keys must be strings, got ${key === null ? 'null' : Array.isArray(key) ? 'an array' : typeof key}.\n\n` +
+        '  Each key names a top-level key of the object.\n' +
+        "  Fix: pass strings as separate arguments: jsonb.remove(col, 'a', 'b').\n",
+      )
+    }
+  }
+  if (keys.length === 1) return sql`${column} - ${keys[0]!}::text`
+  return sql`${column} - array[${sql.join(keys.map(k => sql`${k}`), sql`, `)}]::text[]`
+}

package/src/data/migrate/append-only-generate.ts

@@ -0,0 +1,47 @@
+import type { DefinedTable } from '../domain/types.js'
+import { camelToSnake } from '../domain/naming.js'
+import { appendOnlyScopeField } from '../domain/traits.js'
+
+// A fresh matcher per call: a shared `g` regex carries lastIndex between runs.
+const createTableMatcher = (): RegExp => /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|([a-z_][a-z0-9_]*))/gi
+
+const REFUSE_FUNCTION =
+  `CREATE OR REPLACE FUNCTION pipework_refuse_version_rewrite() RETURNS trigger LANGUAGE plpgsql AS $$ ` +
+  `BEGIN RAISE EXCEPTION '% is append-only: % is not allowed', TG_TABLE_NAME, TG_OP ` +
+  `USING ERRCODE = 'restrict_violation'; END $$`
+
+/**
+ * For each table the migration creates whose definition has the
+ * `.appendOnlyVersions()` trait, appends the trigger that refuses UPDATE and
+ * DELETE and the unique index on (scope, version). Only a CREATE TABLE in this
+ * migration triggers it.
+ */
+export function generateAppendOnlyStatements(
+  migrationSql: string,
+  definitions: ReadonlyMap<string, DefinedTable<any>>, // eslint-disable-line @typescript-eslint/no-explicit-any -- registry erases field generics
+): string {
+  const blocks: string[] = []
+  const seen = new Set<string>()
+  const createTableRe = createTableMatcher()
+  let match: RegExpExecArray | null
+  while ((match = createTableRe.exec(migrationSql)) !== null) {
+    const tableName = match[1] ?? match[2]
+    if (tableName === undefined || seen.has(tableName)) continue
+    const definition = definitions.get(tableName)
+    if (definition === undefined || !definition.$traits.includes('appendOnlyVersions')) continue
+    seen.add(tableName)
+
+    const scope = appendOnlyScopeField(definition)
+    const indexColumns = scope === undefined
+      ? `"version"`
+      : `"${camelToSnake(scope)}", "version"`
+    blocks.push(
+      `CREATE TRIGGER pipework_append_only BEFORE UPDATE OR DELETE ON "${tableName}" ` +
+      `FOR EACH ROW EXECUTE FUNCTION pipework_refuse_version_rewrite()`,
+      `CREATE UNIQUE INDEX "${tableName}_version_unique" ON "${tableName}" (${indexColumns})`,
+    )
+  }
+
+  if (blocks.length === 0) return migrationSql
+  return migrationSql + '\n\n' + [REFUSE_FUNCTION, ...blocks].join(';\n\n') + ';'
+}