pipework 0.252.0 → 0.252.1

package/src/data/schema/generated/format.ts

@@ -0,0 +1,5 @@
+// Auto-generated by scaffold-namespace — do not edit re-export lines
+// Run: node scripts/scaffold-namespace.js generate manifests/zod--v4.json
+// Manual symbols are not included — they live in separate files.
+
+export { base64, base64url, cidrv4, cidrv6, cuid, cuid2, e164, email, emoji, float32, float64, guid, hex, hostname, httpUrl, int32, int64, ipv4, ipv6, jwt, ksuid, mac, nanoid, stringbool, stringFormat, uint32, uint64, ulid, url, uuid, uuidv4, uuidv6, uuidv7, xid } from 'zod/v4'

package/src/data/schema/generated/type-constructor.ts

@@ -0,0 +1,10 @@
+// Auto-generated by scaffold-namespace — do not edit re-export lines
+// Run: node scripts/scaffold-namespace.js generate manifests/zod--v4.json
+// Manual symbols are not included — they live in separate files.
+
+export type { function, null, undefined, void, enum } from 'zod/v4'
+export { _function, any, array, bigint, boolean, custom, date, file, int, json, lazy, literal, map, nan, nativeEnum, never, number, object, promise, record, set, string, symbol, tuple, unknown } from 'zod/v4'
+
+// Reserved words — runtime values exist but can't be re-exported as identifiers.
+// Provide manually in the namespace file (e.g. `enum: z.enum`):
+//   enum

package/src/data/schema/generated/type.ts

@@ -0,0 +1,6 @@
+// Auto-generated by scaffold-namespace — do not edit re-export lines
+// Run: node scripts/scaffold-namespace.js generate manifests/zod--v4.json
+// Manual symbols are not included — they live in separate files.
+
+export type { BRAND, GlobalMeta, infer, Infer, input, IssueData, JSONType, NEVER, output, RefinementCtx, SafeExtendShape, Schema, TimePrecision, TypeOf, ZodAny, ZodArray, ZodBigInt, ZodBoolean, ZodCatch, ZodCodec, ZodCustom, ZodDate, ZodDefault, ZodDiscriminatedUnion, ZodEnum, ZodError, ZodErrorMap, ZodExactOptional, ZodFile, ZodFirstPartySchemaTypes, ZodFlattenedError, ZodFormattedError, ZodFunction, ZodIntersection, ZodIssue, ZodLazy, ZodLiteral, ZodMap, ZodNaN, ZodNever, ZodNonOptional, ZodNull, ZodNullable, ZodNumber, ZodObject, ZodOptional, ZodPipe, ZodPrefault, ZodPreprocess, ZodPromise, ZodRawShape, ZodReadonly, ZodRecord, ZodSafeParseError, ZodSafeParseResult, ZodSafeParseSuccess, ZodSchema, ZodSet, ZodString, ZodSuccess, ZodSymbol, ZodTransform, ZodTuple, ZodType, ZodTypeAny, ZodUndefined, ZodUnion, ZodUnknown, ZodVoid } from 'zod/v4'
+export { ZodFirstPartyTypeKind, ZodIssueCode, ZodRealError } from 'zod/v4'

package/src/data/schema/index.ts

@@ -0,0 +1,6 @@
+export { z } from 'zod/v4'
+export type { z as ZodNamespace } from 'zod/v4'
+
+export { parse, tryParse } from './parse.js'
+export { toJsonSchema, type JsonSchema } from './json-schema.js'
+export { branded } from './branded.js'

package/src/data/schema/json-schema.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod/v4'
+import type { ZodStandardJSONSchemaPayload } from 'zod/v4/core'
+
+export type JsonSchema = ZodStandardJSONSchemaPayload<z.ZodType>
+
+export function toJsonSchema(schema: z.ZodType): JsonSchema {
+  return collapseSingleRefAllOf(z.toJSONSchema(schema, { target: 'draft-07' })) as JsonSchema
+}
+
+// zod emits a lazy reference as `{ allOf: [{ $ref }] }`; fast-json-stringify recurses
+// forever on that form when the target is recursive, and accepts the bare `$ref`.
+function collapseSingleRefAllOf(node: unknown): unknown {
+  if (Array.isArray(node)) return node.map(collapseSingleRefAllOf)
+  if (node === null || typeof node !== 'object') return node
+  const source = node as Record<string, unknown>
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(source)) {
+    if (key === 'allOf' && isSingleRef(value)) {
+      out['$ref'] = value[0]['$ref']
+    } else {
+      out[key] = collapseSingleRefAllOf(value)
+    }
+  }
+  return out
+}
+
+function isSingleRef(value: unknown): value is [{ $ref: unknown }] {
+  if (!Array.isArray(value) || value.length !== 1) return false
+  const member: unknown = value[0]
+  if (member === null || typeof member !== 'object' || Array.isArray(member)) return false
+  const keys = Object.keys(member)
+  return keys.length === 1 && keys[0] === '$ref'
+}

package/src/data/schema/namespace.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod/v4'
+import * as typeConstructors from './generated/type-constructor.js'
+import * as combinators from './generated/combinator.js'
+import * as formats from './generated/format.js'
+import * as encoding from './generated/encoding.js'
+import * as errors from './generated/error.js'
+import { parse } from './parse.js'
+import { tryParse } from './parse.js'
+import { toJsonSchema } from './json-schema.js'
+import { branded } from './branded.js'
+
+// Database schema definition layers (moved from db namespace)
+import * as col from '../db/col/index.js'
+import * as idx from '../db/idx/index.js'
+import * as schemaFeatures from '../db/schema-features.js'
+
+export type { Schema, Infer, StringSchema, NumberSchema, BooleanSchema, EnumSchema, LiteralSchema, ArraySchema, OptionalSchema, NullableSchema, ObjectSchema, ObjectOps } from './types.js'
+export type { JsonSchema } from './json-schema.js'
+
+/** Validation sub-namespace — type constructors (string, number, object, array), combinators (union, intersection), formats (email, uuid), coerce, parse, tryParse, toJsonSchema, branded. */
+const check = {
+  ...typeConstructors,
+  ...combinators,
+  ...formats,
+  ...encoding,
+  ...errors,
+  /** Enum schema from a list of string literals. */
+  enum: z.enum,
+  /** Coercion sub-namespace — coerce.number(), coerce.boolean(), etc. */
+  coerce: z.coerce,
+
+  /** Validates data against a schema, throws ValidationError with actionable message on failure. */
+  parse,
+  /** Validates data, returns { success, data } or { success: false, error } without throwing. */
+  tryParse,
+  /** Converts a schema to JSON Schema for OpenAPI or external validation. */
+  toJsonSchema,
+  /** Creates a branded type — nominal typing for IDs, slugs, etc. */
+  branded,
+} as const
+
+/** Schema definition and validation namespace — wraps zod for validation, drizzle for table/column/index definitions. */
+export const schema = {
+  /** Validation sub-namespace — type constructors, combinators, formats, coerce, parse, tryParse, toJsonSchema, branded. */
+  check,
+
+  // Table/view definition — table, view, materializedView, pgSchema, sequence, policy, role, tableCreator, withReplicas
+  ...schemaFeatures,
+
+  /** Column type builders for table definitions — text, uuid, integer, timestamp, jsonb, boolean, varchar, etc. */
+  col,
+
+  /** Index and constraint builders — index, uniqueIndex, primaryKey, foreignKey, unique, check. */
+  idx,
+} as const

package/src/data/schema/parse.ts

@@ -0,0 +1,39 @@
+import type { z } from 'zod/v4'
+import { ValidationError, type ValidationSource } from '../../core/errors/index.js'
+
+export function parse<T extends z.ZodType>(schema: T, data: unknown, source?: ValidationSource): z.infer<T> {
+  const result = schema.safeParse(data)
+  if (result.success) return result.data
+
+  const fieldErrors: Record<string, string[]> = {}
+  for (const issue of result.error.issues) {
+    const path = issue.path.length > 0 ? issue.path.join('.') : '_root'
+    if (!fieldErrors[path]) {
+      fieldErrors[path] = []
+    }
+    fieldErrors[path].push(issue.message)
+  }
+
+  throw source === undefined
+    ? new ValidationError(fieldErrors)
+    : new ValidationError(fieldErrors, undefined, { source, paths: result.error.issues.map(i => ({ path: i.path.map(String), message: i.message })) })
+}
+
+export function tryParse<T extends z.ZodType>(
+  schema: T,
+  data: unknown,
+): { success: true; data: z.infer<T> } | { success: false; error: ValidationError } {
+  const result = schema.safeParse(data)
+  if (result.success) return { success: true, data: result.data }
+
+  const fieldErrors: Record<string, string[]> = {}
+  for (const issue of result.error.issues) {
+    const path = issue.path.length > 0 ? issue.path.join('.') : '_root'
+    if (!fieldErrors[path]) {
+      fieldErrors[path] = []
+    }
+    fieldErrors[path].push(issue.message)
+  }
+
+  return { success: false, error: new ValidationError(fieldErrors) }
+}

package/src/data/schema/types.ts

@@ -0,0 +1,39 @@
+import type { z } from 'zod/v4'
+
+/** Any validation schema — the base type accepted by .input(), .query(), .params() in the fitting builder. */
+export type Schema<T = unknown> = z.ZodType<T>
+/** Extracts the TypeScript type from a Schema — Infer<typeof mySchema> gives you the validated type. */
+export type Infer<T extends Schema> = z.infer<T>
+
+type Shape = z.core.$ZodShape
+
+/*
+ * The validator types check.string(), check.object(), ... return are zod's own, under pipework names.
+ * They are plain aliases: a new interface per kind (with its own optional/nullable/extend) made every
+ * comparison against Schema<T> recurse through fresh `this` types, which cost an app 5x the instantiations
+ * (#690). The zod classes are re-exported from the package root so declaration emit can name an exported
+ * validator in an app that does not depend on zod (#673).
+ */
+export type { ZodString, ZodNumber, ZodBoolean, ZodEnum, ZodLiteral, ZodArray, ZodOptional, ZodNullable, ZodObject, ZodType } from 'zod/v4'
+export type { $strip, $ZodTypeInternals } from 'zod/v4/core'
+
+/** A string validator — what check.string() returns. */
+export type StringSchema = z.ZodString
+/** A number validator — what check.number() returns. */
+export type NumberSchema = z.ZodNumber
+/** A boolean validator — what check.boolean() returns. */
+export type BooleanSchema = z.ZodBoolean
+/** An enum validator over string literals — what check.enum([...]) returns. */
+export type EnumSchema<V extends string = string> = z.ZodEnum<{ [K in V]: K }>
+/** A literal validator — what check.literal(v) returns. */
+export type LiteralSchema<V extends string | number | boolean | null = string> = z.ZodLiteral<V>
+/** An array validator — what check.array(item) returns. */
+export type ArraySchema<Item extends z.core.SomeType = z.core.SomeType> = z.ZodArray<Item>
+/** An optional validator — what check.optional(inner) and .optional() return. */
+export type OptionalSchema<Inner extends z.core.SomeType = z.core.SomeType> = z.ZodOptional<Inner>
+/** A nullable validator — what check.nullable(inner) and .nullable() return. */
+export type NullableSchema<Inner extends z.core.SomeType = z.core.SomeType> = z.ZodNullable<Inner>
+/** An object validator — what check.object({...}) returns; keeps .extend, .pick, .omit and .partial. For a shape with fields beyond the plain kinds, annotate with ObjectSchema<{ field: Schema<T> }>. */
+export type ObjectSchema<S extends Shape = Shape> = z.ZodObject<S, z.core.$strip>
+/** The object operations of ObjectSchema. */
+export type ObjectOps<S extends Shape> = Pick<ObjectSchema<S>, 'extend' | 'pick' | 'omit' | 'partial'>

package/src/data/temporal/append-only.ts

@@ -0,0 +1,134 @@
+import type { DB, SQL } from '../db/types.js'
+import type { DefinedTable } from '../domain/types.js'
+import { sql } from '../db/sql.js'
+import { identifier } from '../db/expressions.js'
+import { advisoryLock } from '../db/advisory-lock.js'
+import { camelToSnake } from '../domain/naming.js'
+import { appendOnlyScopeField } from '../domain/traits.js'
+import { insert } from '../write/insert.js'
+import { and, desc, lte } from '../query/index.js'
+import { TemporalIntegrityError } from './errors.js'
+
+// The definition's field generics erase at this boundary, as in `pipe.insert`.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyDefinition = DefinedTable<any>
+
+export interface SetVersionOptions {
+  /** The transaction the write runs in. It must be the context's bound transaction (`pipe.transaction`), because the insert goes through `pipe.insert`. */
+  readonly tx: DB
+  readonly definition: AnyDefinition
+  /** The version's own fields, plus the scope field when the definition has a tenant field. */
+  readonly data: Record<string, unknown>
+  /** When the version comes into force. Defaults to the moment it is set; never earlier than the transaction's now(). */
+  readonly effectiveFrom?: Date
+  readonly userId?: string
+}
+
+const MANAGED_FIELDS = ['effectiveFrom', 'version', 'setBy'] as const
+
+function requireAppendOnly(definition: AnyDefinition, fnName: string): void {
+  if (!definition.$traits.includes('appendOnlyVersions')) {
+    throw new TemporalIntegrityError(
+      `temporal.${fnName}() requires an append-only-versions definition.\n\n` +
+      `  "${definition.$name}" does not have the .appendOnlyVersions() trait.\n\n` +
+      `  Add .appendOnlyVersions() to your definition:\n` +
+      `    pipe.define('${definition.$name}', { ... }).appendOnlyVersions()\n`,
+    )
+  }
+}
+
+export async function setVersion(
+  options: SetVersionOptions,
+): Promise<Record<string, unknown>> {
+  const { tx, definition, data } = options
+  requireAppendOnly(definition, 'setVersion')
+  const table = definition.$name
+
+  for (const key of MANAGED_FIELDS) {
+    if (key in data) {
+      throw new TemporalIntegrityError(
+        `temporal.setVersion() sets "${key}" itself; remove it from data for "${table}".`,
+        { table, field: key },
+      )
+    }
+  }
+
+  const scopeField = appendOnlyScopeField(definition)
+  let scopeCondition: SQL = sql`TRUE`
+  const lockKeys = [`pipework.versions:${table}`]
+  if (scopeField !== undefined) {
+    const scopeValue = data[scopeField]
+    if (scopeValue === undefined || scopeValue === null) {
+      throw new TemporalIntegrityError(
+        `temporal.setVersion() on "${table}" needs data.${scopeField}: versions are numbered per ${scopeField}.`,
+        { table, field: scopeField },
+      )
+    }
+    scopeCondition = sql`${identifier(camelToSnake(scopeField))} = ${scopeValue}`
+    lockKeys.push(String(scopeValue))
+  }
+
+  await advisoryLock(tx, ...lockKeys)
+
+  const latestRows = await tx.execute(
+    sql`SELECT version, effective_from FROM ${identifier(table)} WHERE ${scopeCondition} ORDER BY version DESC LIMIT 1`,
+  )
+  const latest = latestRows[0]
+
+  let effectiveFrom: Date | SQL
+  if (options.effectiveFrom === undefined) {
+    // Read after the lock, so it is later than every version already committed
+    // in scope; the transaction's now() may predate the latest of them.
+    effectiveFrom = sql`clock_timestamp()`
+  } else {
+    const iso = options.effectiveFrom.toISOString()
+    const nowRows = await tx.execute(sql`SELECT ${iso}::timestamptz < now() AS before_now, now() AS now`)
+    if (nowRows[0]!['before_now'] === true) {
+      throw new TemporalIntegrityError(
+        `Cannot set a version of "${table}" effective ${iso}: it is earlier than now (${toIso(nowRows[0]!['now'])}). ` +
+        `A version cannot be in force before the moment it is set.`,
+        { table, effectiveFrom: iso },
+      )
+    }
+    if (latest !== undefined) {
+      const cmp = await tx.execute(sql`SELECT ${iso}::timestamptz <= ${latest['effective_from'] as Date}::timestamptz AS not_after`)
+      if (cmp[0]!['not_after'] === true) {
+        throw new TemporalIntegrityError(
+          `Cannot set a version of "${table}" effective ${iso}: it is not after the latest version's effectiveFrom ` +
+          `(${toIso(latest['effective_from'])}, version ${String(latest['version'])}).`,
+          { table, effectiveFrom: iso },
+        )
+      }
+    }
+    effectiveFrom = options.effectiveFrom
+  }
+
+  const version = latest === undefined ? 1 : Number(latest['version']) + 1
+  const rows = await insert(definition as never).values({
+    ...data,
+    effectiveFrom,
+    version,
+    setBy: options.userId ?? null,
+  } as never).returning()
+  return (rows as Record<string, unknown>[])[0]!
+}
+
+export async function versionAt(
+  db: DB,
+  definition: AnyDefinition,
+  t: Date,
+  where?: SQL,
+): Promise<Record<string, unknown> | undefined> {
+  requireAppendOnly(definition, 'versionAt')
+  const columns = definition as unknown as { effectiveFrom: never }
+  const inForce = lte(columns.effectiveFrom, t)
+  const condition = where !== undefined ? and(inForce, where) : inForce
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle select chain requires concrete table generics
+  const rows: Record<string, unknown>[] = await (db as any)
+    .select().from(definition.table()).where(condition).orderBy(desc(columns.effectiveFrom)).limit(1)
+  return rows[0]
+}
+
+function toIso(value: unknown): string {
+  return value instanceof Date ? value.toISOString() : String(value)
+}

package/src/data/temporal/close.ts

@@ -0,0 +1,27 @@
+import { sql } from '../db/sql.js'
+import { identifier, now } from '../db/expressions.js'
+import type { TemporalOptions } from './types.js'
+import { resolveTableName, assertAtMostOneActive } from './resolve.js'
+
+export async function close(options: TemporalOptions): Promise<number> {
+  const { tx, where } = options
+  const table = resolveTableName(options.table)
+
+  const rows = await tx.execute(
+    sql`SELECT id FROM ${identifier(table)} WHERE ${where} AND effective_to IS NULL FOR UPDATE`,
+  )
+
+  if (rows.length === 0) {
+    return 0
+  }
+
+  assertAtMostOneActive(rows, table)
+
+  const currentId = rows[0]!['id'] as string
+
+  await tx.execute(
+    sql`UPDATE ${identifier(table)} SET effective_to = ${now()} WHERE id = ${currentId}::uuid`,
+  )
+
+  return 1
+}

package/src/data/temporal/columns.ts

@@ -0,0 +1,10 @@
+import { timestamp, integer, text } from '../db/col/index.js'
+
+export function temporalColumns() {
+  return {
+    effectiveFrom: timestamp('effective_from', { withTimezone: true }).notNull().defaultNow(),
+    effectiveTo: timestamp('effective_to', { withTimezone: true }),
+    version: integer('version').notNull().default(1),
+    createdBy: text('created_by'),
+  }
+}

package/src/data/temporal/definition-queries.ts

@@ -0,0 +1,70 @@
+import type { DB, SQL } from '../db/types.js'
+import type { DefinedTable, FieldRecord } from '../domain/types.js'
+import type { ReviseOptions, ReviseResult } from './types.js'
+import { atTime } from './query.js'
+import { revise } from './revise.js'
+import { TemporalIntegrityError } from './errors.js'
+import { and } from '../query/index.js'
+
+export interface DefinitionReviseOptions<TFields extends FieldRecord = FieldRecord> {
+  readonly tx: DB
+  readonly definition: DefinedTable<TFields>
+  readonly where: SQL
+  readonly data: Record<string, unknown>
+  readonly userId?: string
+}
+
+function requireEffectiveDated<TFields extends FieldRecord>(definition: DefinedTable<TFields>, fnName: string): void {
+  if (!definition.$traits.includes('effectiveDated')) {
+    throw new TemporalIntegrityError(
+      `temporal.${fnName}() requires an effective-dated definition.\n\n` +
+      `  "${definition.$name}" does not have the .effectiveDated() trait.\n\n` +
+      `  Add .effectiveDated() to your definition:\n` +
+      `    pipe.define('${definition.$name}', { ... }).effectiveDated()\n`,
+    )
+  }
+}
+
+export async function asOf<TFields extends FieldRecord>(
+  db: DB,
+  definition: DefinedTable<TFields>,
+  date: Date,
+  where?: SQL,
+): Promise<Record<string, unknown>[]> {
+  requireEffectiveDated(definition, 'asOf')
+  const table = definition.table()
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- atTime expects column accessors typed by HasTemporalColumns
+  const temporal = atTime(table as any, date)
+  const condition = where !== undefined ? and(temporal, where) : temporal
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle select chain requires concrete table generics
+  return await (db as any).select().from(table).where(condition)
+}
+
+export async function allVersions<TFields extends FieldRecord>(
+  db: DB,
+  definition: DefinedTable<TFields>,
+  where?: SQL,
+): Promise<Record<string, unknown>[]> {
+  requireEffectiveDated(definition, 'allVersions')
+  const table = definition.table()
+  if (where !== undefined) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle select chain requires concrete table generics
+    return await (db as any).select().from(table).where(where)
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle select chain requires concrete table generics
+  return await (db as any).select().from(table)
+}
+
+export async function effectiveUpdate<TFields extends FieldRecord>(options: DefinitionReviseOptions<TFields>): Promise<ReviseResult> {
+  requireEffectiveDated(options.definition, 'effectiveUpdate')
+  const reviseOptions: ReviseOptions = {
+    tx: options.tx,
+    table: options.definition.$name,
+    where: options.where,
+    data: options.data,
+  }
+  if (options.userId !== undefined) {
+    return revise({ ...reviseOptions, userId: options.userId })
+  }
+  return revise(reviseOptions)
+}

package/src/data/temporal/errors.ts

@@ -0,0 +1,10 @@
+import { PipeworkError } from '../../core/errors/base.js'
+
+export class TemporalIntegrityError extends PipeworkError {
+  readonly code = 'TEMPORAL_INTEGRITY' as const
+  readonly httpStatus = 409 as const
+
+  constructor(message: string, details: Record<string, unknown> = {}) {
+    super(message, details)
+  }
+}

package/src/data/temporal/get-current.ts

@@ -0,0 +1,22 @@
+import { sql } from '../db/sql.js'
+import { identifier } from '../db/expressions.js'
+import type { TemporalOptions, GetCurrentResult } from './types.js'
+import { resolveTableName, assertAtMostOneActive } from './resolve.js'
+
+export async function getCurrent(options: TemporalOptions): Promise<GetCurrentResult | null> {
+  const { tx, where } = options
+  const table = resolveTableName(options.table)
+
+  const rows = await tx.execute(
+    sql`SELECT id::text, version FROM ${identifier(table)} WHERE ${where} AND effective_to IS NULL`,
+  )
+
+  if (rows.length === 0) {
+    return null
+  }
+
+  assertAtMostOneActive(rows, table)
+
+  const row = rows[0]!
+  return { id: row['id'] as string, version: row['version'] as number }
+}

package/src/data/temporal/index.ts

@@ -0,0 +1,9 @@
+export { temporalColumns } from './columns.js'
+export { atTime, current, between } from './query.js'
+export { revise } from './revise.js'
+export { close } from './close.js'
+export { getCurrent } from './get-current.js'
+export { TemporalIntegrityError } from './errors.js'
+export { asOf, allVersions, effectiveUpdate, type DefinitionReviseOptions } from './definition-queries.js'
+export type { TemporalOptions, ReviseOptions, ReviseResult, GetCurrentResult } from './types.js'
+export { setVersion, versionAt, type SetVersionOptions } from './append-only.js'

package/src/data/temporal/namespace.ts

@@ -0,0 +1,36 @@
+import { temporalColumns } from './columns.js'
+import { revise } from './revise.js'
+import { close } from './close.js'
+import { getCurrent } from './get-current.js'
+import { atTime, between } from './query.js'
+import { TemporalIntegrityError } from './errors.js'
+import { setVersion, versionAt } from './append-only.js'
+import { asOf, allVersions, effectiveUpdate } from './definition-queries.js'
+
+/** Temporal (bitemporal) data namespace — version history with effective date ranges. */
+export const temporal = {
+  /** Returns the standard temporal column definitions (effectiveFrom, effectiveTo, version, createdBy) for table schemas. */
+  columns: temporalColumns,
+  /** Creates a new version of a temporal record, closing the previous version's effectiveTo. */
+  revise,
+  /** Closes a temporal record by setting effectiveTo to now. Returns number of rows affected. */
+  close,
+  /** Fetches the currently-effective version of a temporal record (effectiveTo IS NULL). */
+  current: getCurrent,
+  /** Returns a SQL condition for records effective at a specific point in time. */
+  atTime,
+  /** Returns a SQL condition for records overlapping a date range. */
+  between,
+  /** Thrown when a temporal operation would violate version continuity. */
+  TemporalIntegrityError,
+  /** Query records effective at a specific date, using a domain definition with .effectiveDated() trait. */
+  asOf,
+  /** Query all versions of temporal records (no date filter). */
+  allVersions,
+  /** Close the current version and create a new one with updated data. */
+  effectiveUpdate,
+  /** Append the next version of an append-only-versions definition: serialised per scope, numbered, never back-dated, audited. */
+  setVersion,
+  /** The version in force at a moment: the row with the greatest effectiveFrom at or before it. */
+  versionAt,
+}

package/src/data/temporal/query.ts

@@ -0,0 +1,25 @@
+import { and, lte, gt, isNull, or } from '../query/index.js'
+import type { SQL, Column } from '../db/types.js'
+
+interface HasTemporalColumns {
+  effectiveFrom: Column
+  effectiveTo: Column
+}
+
+export function atTime<T extends HasTemporalColumns>(table: T, asOf: Date): SQL {
+  return and(
+    lte(table.effectiveFrom, asOf),
+    or(isNull(table.effectiveTo), gt(table.effectiveTo, asOf)),
+  )!
+}
+
+export function current<T extends HasTemporalColumns>(table: T): SQL {
+  return isNull(table.effectiveTo)
+}
+
+export function between<T extends HasTemporalColumns>(table: T, from: Date, to: Date): SQL {
+  return and(
+    lte(table.effectiveFrom, to),
+    or(isNull(table.effectiveTo), gt(table.effectiveTo, from)),
+  )!
+}

package/src/data/temporal/resolve.ts

@@ -0,0 +1,17 @@
+import { getTableName } from '../query/index.js'
+import type { Table } from '../db/types.js'
+import { TemporalIntegrityError } from './errors.js'
+
+export function resolveTableName(table: string | Table): string {
+  return typeof table === 'string' ? table : getTableName(table)
+}
+
+export function assertAtMostOneActive(rows: readonly unknown[], table: string): void {
+  if (rows.length > 1) {
+    throw new TemporalIntegrityError(
+      `Multiple open versions detected in "${table}" — data integrity violation. ` +
+      `Expected at most one row with effective_to IS NULL, found ${rows.length}.`,
+      { table, count: rows.length },
+    )
+  }
+}

package/src/data/temporal/revise.ts

@@ -0,0 +1,67 @@
+import { sql } from '../db/sql.js'
+import { identifier, now } from '../db/expressions.js'
+import type { ReviseOptions, ReviseResult } from './types.js'
+import { TemporalIntegrityError } from './errors.js'
+import { assertValidIdentifier } from '../db/identifiers.js'
+import { resolveTableName, assertAtMostOneActive } from './resolve.js'
+
+export async function revise(options: ReviseOptions): Promise<ReviseResult> {
+  const { tx, where, data, userId } = options
+  const table = resolveTableName(options.table)
+
+  const current = await tx.execute(
+    sql`SELECT id, version FROM ${identifier(table)} WHERE ${where} AND effective_to IS NULL FOR UPDATE`,
+  )
+
+  if (current.length === 0) {
+    throw new TemporalIntegrityError(
+      `No current version found. Cannot revise a record in "${table}" — ` +
+      `ensure the entity exists and has an open version (effective_to IS NULL).`,
+      { table },
+    )
+  }
+
+  assertAtMostOneActive(current, table)
+
+  const currentRow = current[0]!
+  const currentId = currentRow['id'] as string
+  const currentVersion = currentRow['version'] as number
+
+  await tx.execute(
+    sql`UPDATE ${identifier(table)} SET effective_to = ${now()} WHERE id = ${currentId}::uuid`,
+  )
+
+  const columns = Object.keys(data)
+  const values = Object.values(data)
+
+  for (const col of columns) {
+    assertValidIdentifier(col, 'column')
+  }
+
+  const allColumns = [...columns, 'effective_from', 'effective_to', 'version', 'created_by']
+  const colIdentifiers = allColumns.map(c => identifier(c))
+
+  const serializedValues = values.map((v) => {
+    if (v === null || v === undefined) return null
+    if (typeof v === 'object') return JSON.stringify(v)
+    return v
+  })
+
+  const valueParts = [
+    ...serializedValues.map((v) => sql`${v ?? null}`),
+    now(),
+    sql`NULL`,
+    sql`${currentVersion + 1}`,
+    sql`${userId ?? null}`,
+  ]
+
+  const valuesList = sql.join(valueParts, sql`, `)
+
+  assertValidIdentifier(table, 'table')
+  const result = await tx.execute(
+    sql`INSERT INTO ${identifier(table)} (${sql.join(colIdentifiers, sql`, `)}) VALUES (${valuesList}) RETURNING id::text, version`,
+  )
+
+  const row = result[0]!
+  return { id: row['id'] as string, version: row['version'] as number }
+}