pipework 0.252.0 → 0.252.1

package/src/data/valve/namespace.ts

@@ -0,0 +1,57 @@
+import { supply } from './supply.js'
+import { gate } from './gate.js'
+import { faucet } from './faucet.js'
+import { cross, held, failed } from './decision.js'
+import { crossSupply, crossGate } from './cross.js'
+import { executeSupplyCrossing, executeGateCrossing } from './execute-crossing.js'
+import { enqueueCrossing, runCrossingJob, VALVE_CROSSING_JOB_TYPE } from './durable-crossing.js'
+import { buildValveGraph, downstreamFaucets, contextDependents } from './graph.js'
+import { diffContract } from './contract-diff.js'
+import { emitArtifact } from './artifact.js'
+import { valves, getValve, faucetsOf } from './registry.js'
+
+/** Valve namespace — typed, directional, gated boundaries between code silos. */
+export const valve = {
+  /** Declare a handoff valve — the producer side of a payload crossing. */
+  supply,
+  /** Declare a transition-gate valve — the producer side of a gated state change. */
+  gate,
+  /** Declare a faucet — the consumer side of a `supply -> faucet` edge. */
+  faucet,
+  /** Decision outcome: cross the valve, delivering the payload. */
+  cross,
+  /** Decision outcome: hold the crossing in a provisional, reviewable state. */
+  held,
+  /** Decision outcome: evaluation failed — retryable, never a thrown exception. */
+  failed,
+  /** Execute a handoff crossing in the caller's transaction (unrecorded mechanics). */
+  crossSupply,
+  /** Execute a transition-gate crossing (unrecorded mechanics). */
+  crossGate,
+  /** Execute a handoff crossing with idempotency and provenance recording. */
+  executeSupplyCrossing,
+  /** Execute a transition-gate crossing with provenance recording. */
+  executeGateCrossing,
+  /** Enqueue a handoff crossing to run durably as a retried, dead-letterable job. */
+  enqueueCrossing,
+  /** The durable-crossing job-handler body — wire into a worker. */
+  runCrossingJob,
+  /** Job type for a durable valve crossing. */
+  VALVE_CROSSING_JOB_TYPE,
+  /** Assemble the directional valve graph from every registered valve and faucet. */
+  graph: buildValveGraph,
+  /** The faucet nodes a valve feeds. */
+  downstreamFaucets,
+  /** The gates whose enrichment context depends on a valve. */
+  contextDependents,
+  /** Diff a valve contract between two versions. */
+  diffContract,
+  /** Project a handoff supply to its lightweight contract artifact. */
+  emitArtifact,
+  /** All registered producer valves, keyed by name. */
+  valves,
+  /** Look up a registered valve by name. */
+  getValve,
+  /** The faucets consuming a named valve. */
+  faucetsOf,
+}

package/src/data/valve/registry.ts

@@ -0,0 +1,50 @@
+import type { FaucetDefinition, ValveDefinition } from './types.js'
+
+// Two global registries, populated at import time when valve declarations run.
+// `registry` holds producers (supply / gate); `faucetRegistry` holds the
+// consumer side, keyed by the valve name each faucet binds to. The valve graph
+// reconciles the two into `supply -> faucet` edges.
+const registry = new Map<string, ValveDefinition>()
+const faucetRegistry = new Map<string, FaucetDefinition<unknown>[]>()
+
+/** Register a producer valve under its name. Names must be unique across the process. */
+export function registerValve(definition: ValveDefinition): void {
+  const existing = registry.get(definition.name)
+  if (existing !== undefined) {
+    throw new Error(
+      `[pipework] Duplicate valve: "${definition.name}" is already registered.\n\n` +
+      '  Each valve must have a unique name.\n' +
+      `  Existing:  ${existing.kind} (${existing.topology.producer} -> ${existing.topology.consumer})\n` +
+      `  Duplicate: ${definition.kind} (${definition.topology.producer} -> ${definition.topology.consumer})\n`,
+    )
+  }
+  registry.set(definition.name, definition)
+}
+
+/** All registered producer valves, keyed by name. */
+export function valves(): ReadonlyMap<string, ValveDefinition> {
+  return registry
+}
+
+/** Look up one producer valve by name, or `undefined` if it is not registered. */
+export function getValve(name: string): ValveDefinition | undefined {
+  return registry.get(name)
+}
+
+/** Register a faucet against the valve name it consumes. A valve may have many faucets. */
+export function registerFaucet(faucet: FaucetDefinition<unknown>): void {
+  const existing = faucetRegistry.get(faucet.valve) ?? []
+  existing.push(faucet)
+  faucetRegistry.set(faucet.valve, existing)
+}
+
+/** Every faucet that consumes the named valve, in declaration order. */
+export function faucetsOf(valveName: string): readonly FaucetDefinition<unknown>[] {
+  return faucetRegistry.get(valveName) ?? []
+}
+
+/** Empty both registries. Test support — production code never calls this. */
+export function clearValveRegistry(): void {
+  registry.clear()
+  faucetRegistry.clear()
+}

package/src/data/valve/schema/valve-crossing-fields.ts

@@ -0,0 +1,23 @@
+// Column shape of `valve_crossing` — the crossing ledger. One row per crossing
+// attempt: the immutable provenance record (#307 field 6) and, for a keyed
+// crossing, the idempotency entry (#307 field 9).
+
+import { field } from '../../domain/index.js'
+import { schema } from '../../schema/namespace.js'
+
+export const valveCrossingFields = {
+  id: field.uuid().brand('ValveCrossingId').defaultRandom().primaryKey(),
+  // The valve crossed.
+  valve: field.text(),
+  // The idempotency key, or null for an un-keyed crossing.
+  idempotencyKey: field.text().nullable(),
+  // How the crossing resolved.
+  outcome: field.enum(['crossed', 'blocked', 'held', 'failed']),
+  // Snapshot of the delivered payload — set for a `crossed` outcome.
+  payload: field.jsonb(schema.check.json()).nullable(),
+  // The held reason or the failure error — set for `held` / `failed`.
+  detail: field.jsonb(schema.check.json()).nullable(),
+  // The trace / correlation id propagated across the crossing.
+  lineageId: field.text().nullable(),
+  crossedAt: field.timestamp(),
+}

package/src/data/valve/schema/valve-crossing.ts

@@ -0,0 +1,9 @@
+// The `valve_crossing` ledger — one row per crossing attempt. It is both the
+// immutable provenance record every crossing and non-crossing leaves (#307
+// field 6) and the idempotency store a keyed crossing is replayed against
+// (#307 field 9). Written transactionally with the crossing; non-partitioned.
+
+import { define } from '../../domain/index.js'
+import { valveCrossingFields } from './valve-crossing-fields.js'
+
+export const valveCrossing = define('valve_crossing', valveCrossingFields)

package/src/data/valve/supply.ts

@@ -0,0 +1,154 @@
+import { registerValve } from './registry.js'
+import type {
+  ContractPayload,
+  ContractShape,
+  HandoffTrigger,
+  SupplyDefinition,
+} from './types.js'
+
+/**
+ * The producer-side builder for a handoff valve. Type parameters narrow as the
+ * chain progresses: `.from()` fixes the source row type, `.contract()` fixes
+ * the payload type, and `.guard()` / `.project()` / `.idempotentBy()` are then
+ * checked against them. `.to()` is terminal — it registers the valve.
+ */
+export interface SupplyBuilder<TSource, TPayload> {
+  /** The source entity and the state transition (or push) that fires the crossing. */
+  from<TFromSource = TSource>(source: string, trigger: HandoffTrigger): SupplyBuilder<TFromSource, TPayload>
+  /** The payload schema — `.project()` must produce exactly this shape. */
+  contract<TShape extends ContractShape>(shape: TShape): SupplyBuilder<TSource, ContractPayload<TShape>>
+  /** A guard predicate; the payload may not cross unless it holds. */
+  guard(predicate: (row: TSource) => boolean): SupplyBuilder<TSource, TPayload>
+  /** Projects the source row to the contract payload — a snapshot taken at crossing time. */
+  project(projection: (row: TSource) => TPayload): SupplyBuilder<TSource, TPayload>
+  /** Names a post-condition that holds across the crossing (checked via the valve graph). */
+  invariant(name: string): SupplyBuilder<TSource, TPayload>
+  /** The source field carrying the trace/correlation id propagated across the crossing. */
+  lineage(field: string): SupplyBuilder<TSource, TPayload>
+  /** Derives the idempotency key for a crossing from the source row. */
+  idempotentBy(key: (row: TSource) => string): SupplyBuilder<TSource, TPayload>
+  /** Run the crossing as a durable retried job rather than in the caller's transaction. */
+  durable(retry?: 'backoff' | 'fixed'): SupplyBuilder<TSource, TPayload>
+  /** The consumer silo. Terminal — registers the valve and returns its definition. */
+  to(consumer: string): SupplyDefinition<TSource, TPayload>
+}
+
+interface SupplyState {
+  readonly name: string
+  readonly producer: string
+  source: string | undefined
+  trigger: HandoffTrigger | undefined
+  contract: ContractShape | undefined
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the builder erases per-stage source/payload generics; SupplyBuilder is the precise public surface
+  guard: ((row: any) => boolean) | undefined
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see above
+  project: ((row: any) => unknown) | undefined
+  invariants: string[]
+  lineageField: string | undefined
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see above
+  idempotentBy: ((row: any) => string) | undefined
+  crossing: SupplyDefinition<unknown, unknown>['crossing']
+}
+
+function finalize(state: SupplyState, consumer: string): SupplyDefinition<unknown, unknown> {
+  if (state.source === undefined || state.trigger === undefined) {
+    throw new Error(
+      `[pipework] Valve "${state.name}" is missing .from(...).\n\n` +
+      '  A supply must declare its source entity and trigger before .to(...).\n' +
+      '  Example: supply("frozen-outcome", "compensation")\n' +
+      '             .from("outcomes", { on: "status", from: "open", to: "frozen" })\n',
+    )
+  }
+  if (state.contract === undefined) {
+    throw new Error(
+      `[pipework] Valve "${state.name}" is missing .contract(...).\n\n` +
+      '  A supply must declare its payload contract before .to(...).\n',
+    )
+  }
+  if (state.project === undefined) {
+    throw new Error(
+      `[pipework] Valve "${state.name}" is missing .project(...).\n\n` +
+      '  A supply must declare how the source row projects to the contract payload before .to(...).\n',
+    )
+  }
+  const definition: SupplyDefinition<unknown, unknown> = {
+    name: state.name,
+    kind: 'handoff',
+    topology: { producer: state.producer, consumer },
+    source: state.source,
+    trigger: state.trigger,
+    contract: state.contract,
+    guard: state.guard,
+    project: state.project,
+    invariants: [...state.invariants],
+    lineageField: state.lineageField,
+    idempotentBy: state.idempotentBy,
+    crossing: state.crossing,
+  }
+  registerValve(definition)
+  return definition
+}
+
+/**
+ * Declare a handoff valve. `name` identifies the valve; `producer` is the silo
+ * the data crosses *from*. Chain the anatomy and finish with `.to(consumer)`.
+ */
+export function supply(name: string, producer: string): SupplyBuilder<unknown, unknown> {
+  const state: SupplyState = {
+    name,
+    producer,
+    source: undefined,
+    trigger: undefined,
+    contract: undefined,
+    guard: undefined,
+    project: undefined,
+    invariants: [],
+    lineageField: undefined,
+    idempotentBy: undefined,
+    crossing: { durable: false },
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- builder type params narrow per stage; the public SupplyBuilder type is precise
+  const builder: any = {
+    from(source: string, trigger: HandoffTrigger) {
+      state.source = source
+      state.trigger = trigger
+      return builder
+    },
+    contract(shape: ContractShape) {
+      state.contract = shape
+      return builder
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- predicate generic erased into state; see SupplyState
+    guard(predicate: (row: any) => boolean) {
+      state.guard = predicate
+      return builder
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- projection generic erased into state; see SupplyState
+    project(projection: (row: any) => unknown) {
+      state.project = projection
+      return builder
+    },
+    invariant(invariantName: string) {
+      state.invariants.push(invariantName)
+      return builder
+    },
+    lineage(field: string) {
+      state.lineageField = field
+      return builder
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- key generic erased into state; see SupplyState
+    idempotentBy(key: (row: any) => string) {
+      state.idempotentBy = key
+      return builder
+    },
+    durable(retry?: 'backoff' | 'fixed') {
+      state.crossing = { durable: true, retry: retry ?? 'backoff' }
+      return builder
+    },
+    to(consumer: string) {
+      return finalize(state, consumer)
+    },
+  }
+  return builder as SupplyBuilder<unknown, unknown>
+}

package/src/data/valve/types.ts

@@ -0,0 +1,143 @@
+import type { Schema, Infer } from '../schema/types.js'
+import type { DB } from '../db/namespace.js'
+import type { DecisionOutcome } from './decision.js'
+
+/**
+ * The two valve forms. A `handoff` moves a payload across a silo / ownership
+ * boundary; a `transition-gate` modulates a state change within one silo.
+ */
+export type ValveKind = 'handoff' | 'transition-gate'
+
+/**
+ * Directional producer -> consumer topology. For a transition gate the
+ * producer and consumer silo coincide — the crossing is an intra-silo edge.
+ */
+export interface ValveTopology {
+  readonly producer: string
+  readonly consumer: string
+}
+
+/**
+ * A registered valve. The builders (`supply`, `gate`, `faucet`) produce
+ * concrete definitions assignable to this base; the registry stores them
+ * keyed by `name`, and the valve graph is assembled from their topology.
+ */
+export interface ValveDefinition {
+  readonly name: string
+  readonly kind: ValveKind
+  readonly topology: ValveTopology
+}
+
+/**
+ * A handoff trigger — either a source state transition (`status: open -> frozen`)
+ * or an explicit push.
+ */
+export type HandoffTrigger =
+  | { readonly on: string, readonly from: string, readonly to: string }
+  | { readonly push: true }
+
+/**
+ * How a crossing executes — synchronously in the caller's transaction, or as a
+ * durable retried job that dead-letters on retry exhaustion.
+ */
+export type CrossingMode =
+  | { readonly durable: false }
+  | { readonly durable: true, readonly retry: 'backoff' | 'fixed' }
+
+/** A contract shape — payload field name -> validation schema. */
+export type ContractShape = Record<string, Schema>
+
+/** The payload type a contract shape validates to. */
+export type ContractPayload<TShape extends ContractShape> = {
+  readonly [K in keyof TShape]: Infer<TShape[K]>
+}
+
+/**
+ * A handoff valve, produced by `supply(...).to(...)`. Carries the full anatomy
+ * the crossing executor and the valve graph read back.
+ */
+export interface SupplyDefinition<TSource, TPayload> extends ValveDefinition {
+  readonly kind: 'handoff'
+  readonly source: string
+  readonly trigger: HandoffTrigger
+  readonly contract: ContractShape
+  readonly guard: ((row: TSource) => boolean) | undefined
+  readonly project: (row: TSource) => TPayload
+  readonly invariants: readonly string[]
+  readonly lineageField: string | undefined
+  readonly idempotentBy: ((row: TSource) => string) | undefined
+  readonly crossing: CrossingMode
+}
+
+/**
+ * A transition-gate trigger. A gate fires on admission of a source row, on the
+ * birth of a new instance version, or by an explicit operator action — the
+ * manual trigger carrying a permission and batch semantics.
+ */
+export type GateTrigger =
+  | { readonly trigger: 'admission' }
+  | { readonly trigger: 'new-version' }
+  | { readonly trigger: 'manual', readonly permission: string, readonly batch: boolean }
+
+/** Retraction config — which trigger supersedes and invalidates the prior crossing. */
+export interface GateRetraction {
+  readonly on: 'new-version'
+}
+
+/**
+ * The decision hook — the load-bearing seam (#307 field 13). Async, and returns
+ * a partitioned outcome (`cross` / `held` / `failed`) — never a bare verdict.
+ */
+export type GateDecision<TEvent> = (
+  event: TEvent,
+  context: Readonly<Record<string, unknown>>,
+) => Promise<DecisionOutcome<unknown, unknown>>
+
+/**
+ * A transition-gate valve, produced by `gate(...).decision(...)`. Its producer
+ * and consumer silo coincide — it modulates an intra-silo state change.
+ */
+export interface GateDefinition<TEvent> extends ValveDefinition {
+  readonly kind: 'transition-gate'
+  readonly source: string
+  readonly triggers: readonly GateTrigger[]
+  readonly context: Readonly<Record<string, string>>
+  readonly signals: readonly string[]
+  readonly fanOut: ((event: TEvent) => readonly unknown[]) | undefined
+  readonly decision: GateDecision<TEvent>
+  readonly retraction: GateRetraction | undefined
+}
+
+/**
+ * A faucet's intake handler — receives the re-validated payload and the
+ * transaction the crossing runs in, and lands the payload in the consumer.
+ */
+export type FaucetHandler<TPayload> = (payload: TPayload, tx: DB) => Promise<void>
+
+/**
+ * A faucet — the consumer side of a `supply -> faucet` edge. It binds to a
+ * valve by name (never to the producer silo) and re-validates every payload.
+ */
+export interface FaucetDefinition<TPayload> {
+  readonly valve: string
+  readonly target: string
+  readonly handler: FaucetHandler<TPayload>
+}
+
+/** The crossing proceeded — `payload` was delivered. */
+export interface CrossedResult { readonly kind: 'crossed', readonly payload: unknown }
+/** A handoff guard rejected the row — nothing crossed. */
+export interface BlockedResult { readonly kind: 'blocked' }
+/** A gate held the crossing in a provisional, reviewable state. */
+export interface HeldResult { readonly kind: 'held', readonly reason: unknown }
+/** A gate's decision evaluation failed. */
+export interface FailedResult { readonly kind: 'failed', readonly error: Error }
+/** A keyed crossing was replayed — its prior `crossed` outcome already landed. */
+export interface SkippedResult { readonly kind: 'skipped' }
+
+/** A handoff crossing resolves as crossed or blocked. */
+export type SupplyCrossingResult = CrossedResult | BlockedResult
+/** A transition-gate crossing resolves as crossed, held, or failed. */
+export type GateCrossingResult = CrossedResult | HeldResult | FailedResult
+/** Any crossing outcome — the recorded layer additionally yields `skipped`. */
+export type CrossingResult = CrossedResult | BlockedResult | HeldResult | FailedResult | SkippedResult

package/src/data/vector/columns.ts

@@ -0,0 +1,27 @@
+import { customType } from '../db/col/index.js'
+
+export function vector(name: string, config: { dimensions: number }) {
+  return customType<{ data: number[]; driverParam: string }>({
+    dataType() {
+      return `vector(${config.dimensions})`
+    },
+    toDriver(value: number[]): string {
+      return `[${value.join(',')}]`
+    },
+    fromDriver(value: unknown): number[] {
+      if (typeof value === 'string') {
+        const trimmed = value.startsWith('[') ? value.slice(1, -1) : value
+        return trimmed.split(',').map(Number)
+      }
+      return value as number[]
+    },
+  })(name)
+}
+
+export function tsvector(name: string) {
+  return customType<{ data: unknown; driverParam: unknown }>({
+    dataType() {
+      return 'tsvector'
+    },
+  })(name)
+}

package/src/data/vector/index.ts

@@ -0,0 +1,4 @@
+export { vector, tsvector } from './columns.js'
+export { cosineDistance, cosineSimilarity, l2Distance, innerProduct, toTsvector, toTsquery, plainToTsquery, matches, headline, tsRank } from './query.js'
+export type { HeadlineOptions } from './query.js'
+export { validateVectorExtension } from './validate.js'

package/src/data/vector/namespace.ts

@@ -0,0 +1,33 @@
+import { vector as vectorColumn, tsvector } from './columns.js'
+import { cosineDistance, cosineSimilarity, l2Distance, innerProduct, toTsvector, toTsquery, plainToTsquery, matches, headline, tsRank } from './query.js'
+import { validateVectorExtension } from './validate.js'
+
+/** Vector and full-text search namespace — pgvector column types, similarity queries, and FTS operators. */
+export const vector = {
+  /** Defines a vector(N) column for embeddings. */
+  column: vectorColumn,
+  /** Defines a tsvector column for full-text search. */
+  tsvector,
+  /** Cosine distance between a column and a query vector (lower = more similar). */
+  cosine: cosineDistance,
+  /** Cosine similarity (higher = more similar) — 1 - cosineDistance. */
+  cosineSimilarity,
+  /** L2 (Euclidean) distance between a column and a query vector. */
+  l2: l2Distance,
+  /** Inner product between a column and a query vector. */
+  innerProduct,
+  /** Converts text to a tsvector for full-text indexing. */
+  toTsvector,
+  /** Converts a search query string to a tsquery using to_tsquery (supports operators like &, |, !). */
+  toTsquery,
+  /** Converts natural language text to a tsquery using plainto_tsquery (no operator syntax required). */
+  plainToTsquery,
+  /** The @@ match operator — tests whether a tsvector column matches a tsquery. */
+  matches,
+  /** Generates a ts_headline search snippet with highlighted matches. */
+  headline,
+  /** Computes ts_rank for full-text search result ordering. Accepts a pre-built tsquery SQL or a raw query string. */
+  rank: tsRank,
+  /** Verifies the pgvector extension is installed and accessible. */
+  validate: validateVectorExtension,
+}

package/src/data/vector/query.ts

@@ -0,0 +1,85 @@
+import { sql } from '../db/sql.js'
+import type { SQL, Column } from '../db/types.js'
+
+export function cosineDistance(column: Column, query: readonly number[]): SQL<number> {
+  const vectorStr = `[${query.join(',')}]`
+  return sql<number>`${column} <=> ${vectorStr}::vector`
+}
+
+export function cosineSimilarity(column: Column, query: readonly number[]): SQL<number> {
+  const vectorStr = `[${query.join(',')}]`
+  return sql<number>`1 - (${column} <=> ${vectorStr}::vector)`
+}
+
+export function l2Distance(column: Column, query: readonly number[]): SQL<number> {
+  const vectorStr = `[${query.join(',')}]`
+  return sql<number>`${column} <-> ${vectorStr}::vector`
+}
+
+export function innerProduct(column: Column, query: readonly number[]): SQL<number> {
+  const vectorStr = `[${query.join(',')}]`
+  return sql<number>`${column} <#> ${vectorStr}::vector`
+}
+
+export function toTsvector(text: Column | string | SQL, config?: string): SQL {
+  const tsConfig = config ?? 'english'
+  if (typeof text === 'string') {
+    return sql`to_tsvector(${tsConfig}, ${text})`
+  }
+  return sql`to_tsvector(${tsConfig}, ${text})`
+}
+
+export function toTsquery(query: string, config?: string): SQL {
+  const tsConfig = config ?? 'english'
+  return sql`to_tsquery(${tsConfig}, ${query})`
+}
+
+export function plainToTsquery(query: string, config?: string): SQL {
+  const tsConfig = config ?? 'english'
+  return sql`plainto_tsquery(${tsConfig}, ${query})`
+}
+
+export function matches(column: Column | SQL, query: SQL): SQL<boolean> {
+  return sql<boolean>`${column} @@ ${query}`
+}
+
+export interface HeadlineOptions {
+  maxWords?: number
+  minWords?: number
+  shortWord?: number
+  highlightAll?: boolean
+  maxFragments?: number
+  fragmentDelimiter?: string
+  startSel?: string
+  stopSel?: string
+}
+
+export function headline(column: Column | SQL, query: SQL, config?: string, options?: HeadlineOptions): SQL<string> {
+  const tsConfig = config ?? 'english'
+  if (options === undefined) {
+    return sql<string>`ts_headline(${tsConfig}, ${column}, ${query})`
+  }
+  const optStr = formatHeadlineOptions(options)
+  return sql<string>`ts_headline(${tsConfig}, ${column}, ${query}, ${optStr})`
+}
+
+function formatHeadlineOptions(options: HeadlineOptions): string {
+  const parts: string[] = []
+  if (options.maxWords !== undefined) parts.push(`MaxWords=${String(options.maxWords)}`)
+  if (options.minWords !== undefined) parts.push(`MinWords=${String(options.minWords)}`)
+  if (options.shortWord !== undefined) parts.push(`ShortWord=${String(options.shortWord)}`)
+  if (options.highlightAll !== undefined) parts.push(`HighlightAll=${options.highlightAll ? 'TRUE' : 'FALSE'}`)
+  if (options.maxFragments !== undefined) parts.push(`MaxFragments=${String(options.maxFragments)}`)
+  if (options.fragmentDelimiter !== undefined) parts.push(`FragmentDelimiter=${options.fragmentDelimiter}`)
+  if (options.startSel !== undefined) parts.push(`StartSel=${options.startSel}`)
+  if (options.stopSel !== undefined) parts.push(`StopSel=${options.stopSel}`)
+  return parts.join(', ')
+}
+
+export function tsRank(column: Column | SQL, query: string | SQL, config?: string): SQL<number> {
+  const tsConfig = config ?? 'english'
+  if (typeof query === 'string') {
+    return sql<number>`ts_rank(${column}, to_tsquery(${tsConfig}, ${query}))`
+  }
+  return sql<number>`ts_rank(${column}, ${query})`
+}

package/src/data/vector/validate.ts

@@ -0,0 +1,16 @@
+import { sql } from '../db/sql.js'
+import type { DB } from '../db/index.js'
+
+export async function validateVectorExtension(db: DB): Promise<void> {
+  const result = await db.execute(
+    sql`SELECT extname FROM pg_extension WHERE extname = 'vector'`,
+  )
+
+  if (result.length === 0) {
+    throw new Error(
+      '[pipework] pgvector extension not installed on this database.\n' +
+      "Run: CREATE EXTENSION IF NOT EXISTS vector;\n" +
+      "Or add 'vector' to your database's extensions list in pipework.config.ts.",
+    )
+  }
+}

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

@@ -0,0 +1,15 @@
+// Resolves the audit row's `actor_id` from the current `Flow.auth`. Audit
+// lives downstream of auth, but it doesn't impose a brand — the audit row
+// stores whatever the auth surface gave us as a free text. Mirrors the
+// extraction the logging layer uses: `auth.userId` when present and string,
+// null otherwise. Anything else (cron, worker without principal) → null.
+
+import type { Flow } from '../../../request/context/types.js'
+
+export function resolveActorId(flow: Flow): string | null {
+  const auth = flow.auth
+  if (auth === null || typeof auth !== 'object') return null
+  if (!('userId' in auth)) return null
+  const userId = (auth as { userId: unknown }).userId
+  return typeof userId === 'string' ? userId : null
+}

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

@@ -0,0 +1,18 @@
+// The shared column list for `audit_record` INSERT statements. Compiled once
+// at module load from `auditRecordFields` (the same registry the table is
+// built from) so the column order baked into every CTE-form INSERT matches
+// the table's declared order. Re-ordering or adding fields on
+// `auditRecordFields` is enough — the audit CTE generator picks it up.
+
+import { quoteIdentifier } from '../../db/identifiers.js'
+import { camelToSnake } from '../../domain/naming.js'
+import { auditRecordFields, AUDIT_CHAIN_FIELD_KEYS } from '../../../audit/schema/audit-record-fields.js'
+
+/** Field keys on `audit_record` an INSERT supplies (the chain columns are trigger-owned), in declaration order — the SELECT projection's positional order. */
+export const AUDIT_FIELD_KEYS = (Object.keys(auditRecordFields) as ReadonlyArray<keyof typeof auditRecordFields>)
+  .filter(k => !AUDIT_CHAIN_FIELD_KEYS.has(k))
+
+/** Quoted column list, comma-separated — the `INSERT INTO audit_record (...)` parenthetical. */
+export const AUDIT_COLUMNS_SQL = AUDIT_FIELD_KEYS
+  .map(k => quoteIdentifier(camelToSnake(k), 'audit_record column'))
+  .join(', ')