pipework 0.252.0 → 0.253.0

package/src/data/domain/define.ts

@@ -0,0 +1,239 @@
+import type { z } from 'zod/v4'
+import type { FieldDescriptor, DefineOptions, DefinedTable, DefinitionMethods, EffectiveDatedFields, AppendOnlyVersionsFields, AuditedFields, SoftDeletedFields } from './types.js'
+import type { AcceptReadonly } from '../db/readonly.js'
+import type { InsertProjection, SelectProjection, UpdateProjection } from './projections.js'
+import type { InferSelect } from './brand.js'
+import { projectTable } from './build-table.js'
+import { projectInsertShape, projectSelectShape, projectUpdateShape } from './build-schema.js'
+import { projectFactory } from './build-factory.js'
+import { applyTrait, effectiveDatedTrait, appendOnlyVersionsTrait, auditedTrait, softDeletedTrait } from './traits.js'
+import { hasExternalName, clearExternalNames } from './external-registry.js'
+import { scopeTable } from '../../auth/tenant/scope.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- registry erases field-level generics; concrete types flow through define()'s return type
+const registry = new Map<string, DefinedTable<any>>()
+
+export function define<TFields extends Record<string, FieldDescriptor>, TName extends string = string>(
+  name: TName,
+  initialFields: TFields,
+  options?: DefineOptions,
+): DefinedTable<TFields, TName> {
+  if (hasExternalName(name)) {
+    throw new Error(
+      `[pipework] Duplicate domain definition: "${name}" is already declared with pipe.external.\n\n` +
+      '  Each definition, external or not, must have a unique name.\n' +
+      '  Fix: rename one of them.\n',
+    )
+  }
+  if (registry.has(name)) {
+    throw new Error(
+      `[pipework] Duplicate domain definition: "${name}" is already registered.\n\n` +
+      '  Each definition must have a unique name.\n' +
+      `  Existing: ${registry.get(name)!.$options.virtual === true ? 'virtual' : 'database table'}\n` +
+      `  Duplicate: ${options?.virtual === true ? 'virtual' : 'database table'}\n`,
+    )
+  }
+
+  const result = buildDefinedTable(name, initialFields, options ?? {}, [])
+  registry.set(name, result)
+  return result
+}
+
+function buildDefinedTable<TFields extends Record<string, FieldDescriptor>, TName extends string>(
+  name: TName,
+  fields: TFields,
+  opts: DefineOptions,
+  traits: string[],
+): DefinedTable<TFields, TName> {
+  if (opts.virtual === true) {
+    return buildVirtualDefinition(name, fields, opts, traits)
+  }
+
+  const table = projectTable(name, fields as Record<string, FieldDescriptor>, opts)
+
+  const tenantFieldKey = Object.keys(fields).find(
+    (key) => (fields[key] as FieldDescriptor)._meta.tenant === true,
+  )
+  if (tenantFieldKey !== undefined) {
+    scopeTable(table, tenantFieldKey)
+  }
+
+  let cachedInsertShape: z.ZodType<InsertProjection<TFields>> | undefined
+  let cachedSelectShape: z.ZodType<SelectProjection<TFields>> | undefined
+  let cachedUpdateShape: z.ZodType<UpdateProjection<TFields>> | undefined
+
+  const methods: DefinitionMethods<TFields, TName> = {
+    $name: name,
+    get $fields() { return fields },
+    $options: opts,
+    get $traits() { return traits as readonly string[] },
+
+    table() { return table },
+
+    insertShape() {
+      if (cachedInsertShape === undefined) {
+        cachedInsertShape = projectInsertShape(fields)
+      }
+      return cachedInsertShape
+    },
+
+    selectShape() {
+      if (cachedSelectShape === undefined) {
+        cachedSelectShape = projectSelectShape(fields)
+      }
+      return cachedSelectShape
+    },
+
+    updateShape() {
+      if (cachedUpdateShape === undefined) {
+        cachedUpdateShape = projectUpdateShape(fields)
+      }
+      return cachedUpdateShape
+    },
+
+    factory() {
+      return projectFactory(result)
+    },
+
+    effectiveDated() {
+      const applied = applyTrait(name, fields as Record<string, FieldDescriptor>, traits, effectiveDatedTrait)
+      const rebuilt = buildDefinedTable(name, applied.fields as TFields & EffectiveDatedFields, opts, applied.traits)
+      registry.set(name, rebuilt)
+      return rebuilt
+    },
+
+    appendOnlyVersions() {
+      const applied = applyTrait(name, fields as Record<string, FieldDescriptor>, traits, appendOnlyVersionsTrait)
+      const rebuilt = buildDefinedTable(name, applied.fields as TFields & AppendOnlyVersionsFields, opts, applied.traits)
+      registry.set(name, rebuilt)
+      return rebuilt
+    },
+
+    audited() {
+      const applied = applyTrait(name, fields as Record<string, FieldDescriptor>, traits, auditedTrait)
+      const rebuilt = buildDefinedTable(name, applied.fields as TFields & AuditedFields, opts, applied.traits)
+      registry.set(name, rebuilt)
+      return rebuilt
+    },
+
+    softDeleted() {
+      const applied = applyTrait(name, fields as Record<string, FieldDescriptor>, traits, softDeletedTrait)
+      const rebuilt = buildDefinedTable(name, applied.fields as TFields & SoftDeletedFields, opts, applied.traits)
+      registry.set(name, rebuilt)
+      return rebuilt
+    },
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- phantom type marker, never accessed at runtime
+    get Select(): InferSelect<TFields> { return undefined as any },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- phantom type marker, never accessed at runtime
+    get Insert(): AcceptReadonly<InsertProjection<TFields>> { return undefined as any },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- phantom type marker, never accessed at runtime
+    get Update(): AcceptReadonly<UpdateProjection<TFields>> { return undefined as any },
+  }
+
+  const result = Object.assign(table, methods) as unknown as DefinedTable<TFields, TName>
+  return result
+}
+
+function buildVirtualDefinition<TFields extends Record<string, FieldDescriptor>, TName extends string>(
+  name: TName,
+  fields: TFields,
+  opts: DefineOptions,
+  traits: string[],
+): DefinedTable<TFields, TName> {
+  let cachedInsertShape: z.ZodType<InsertProjection<TFields>> | undefined
+  let cachedSelectShape: z.ZodType<SelectProjection<TFields>> | undefined
+  let cachedUpdateShape: z.ZodType<UpdateProjection<TFields>> | undefined
+
+  const definition = {
+    $name: name,
+    get $fields() { return fields },
+    $options: opts,
+    get $traits() { return traits as readonly string[] },
+
+    table() {
+      throw new Error(
+        `[pipework] "${name}" is a virtual definition — no database table.\n\n` +
+        '  Virtual definitions have no .table() projection.\n' +
+        '  Remove { virtual: true } if this definition needs a database table.\n',
+      )
+    },
+
+    insertShape() {
+      if (cachedInsertShape === undefined) {
+        cachedInsertShape = projectInsertShape(fields)
+      }
+      return cachedInsertShape
+    },
+
+    selectShape() {
+      if (cachedSelectShape === undefined) {
+        cachedSelectShape = projectSelectShape(fields)
+      }
+      return cachedSelectShape
+    },
+
+    updateShape() {
+      if (cachedUpdateShape === undefined) {
+        cachedUpdateShape = projectUpdateShape(fields)
+      }
+      return cachedUpdateShape
+    },
+
+    factory() {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- registry erases field-level generics
+      return projectFactory(definition as unknown as DefinedTable<any>)
+    },
+
+    effectiveDated() {
+      const applied = applyTrait(name, fields as Record<string, FieldDescriptor>, traits, effectiveDatedTrait)
+      const rebuilt = buildVirtualDefinition(name, applied.fields as TFields & EffectiveDatedFields, opts, applied.traits)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- registry erases field-level generics
+      registry.set(name, rebuilt as unknown as DefinedTable<any>)
+      return rebuilt
+    },
+
+    appendOnlyVersions() {
+      const applied = applyTrait(name, fields as Record<string, FieldDescriptor>, traits, appendOnlyVersionsTrait)
+      const rebuilt = buildVirtualDefinition(name, applied.fields as TFields & AppendOnlyVersionsFields, opts, applied.traits)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- registry erases field-level generics
+      registry.set(name, rebuilt as unknown as DefinedTable<any>)
+      return rebuilt
+    },
+
+    audited() {
+      const applied = applyTrait(name, fields as Record<string, FieldDescriptor>, traits, auditedTrait)
+      const rebuilt = buildVirtualDefinition(name, applied.fields as TFields & AuditedFields, opts, applied.traits)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- registry erases field-level generics
+      registry.set(name, rebuilt as unknown as DefinedTable<any>)
+      return rebuilt
+    },
+
+    softDeleted() {
+      const applied = applyTrait(name, fields as Record<string, FieldDescriptor>, traits, softDeletedTrait)
+      const rebuilt = buildVirtualDefinition(name, applied.fields as TFields & SoftDeletedFields, opts, applied.traits)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- registry erases field-level generics
+      registry.set(name, rebuilt as unknown as DefinedTable<any>)
+      return rebuilt
+    },
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- phantom type marker, never accessed at runtime
+    get Select(): InferSelect<TFields> { return undefined as any },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- phantom type marker, never accessed at runtime
+    get Insert(): AcceptReadonly<InsertProjection<TFields>> { return undefined as any },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- phantom type marker, never accessed at runtime
+    get Update(): AcceptReadonly<UpdateProjection<TFields>> { return undefined as any },
+  }
+
+  return definition as unknown as DefinedTable<TFields, TName>
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- registry erases field-level generics
+export function definitions(): ReadonlyMap<string, DefinedTable<any>> {
+  return registry
+}
+
+export function clearRegistry(): void {
+  registry.clear()
+  clearExternalNames()
+}

package/src/data/domain/external-registry.ts

@@ -0,0 +1,34 @@
+// Names and table objects of relations declared with pipe.external. Kept apart
+// from the definitions() registry so RLS, audit and startup validation never see them.
+
+const names = new Set<string>()
+const tables = new WeakSet<object>()
+
+export function hasExternalName(name: string): boolean {
+  return names.has(name)
+}
+
+export function registerExternal(name: string, table: object): void {
+  names.add(name)
+  tables.add(table)
+}
+
+export function clearExternalNames(): void {
+  names.clear()
+}
+
+/** True for a table declared with pipe.external. */
+export function isExternal(table: unknown): boolean {
+  return typeof table === 'object' && table !== null && tables.has(table)
+}
+
+/** Throws the [pipework] error a write gets when handed an external relation. */
+export function assertNotExternal(table: unknown, verb: string): void {
+  if (!isExternal(table)) return
+  const name = (table as { $name?: string }).$name ?? 'external relation'
+  throw new Error(
+    `[pipework] pipe.${verb}: "${name}" is external and read-only.\n\n` +
+    '  A relation declared with pipe.external is owned by another service; pipework never writes to it.\n' +
+    '  Fix: write through the owning service, or declare the table with pipe.define if this app owns it.\n',
+  )
+}

package/src/data/domain/external.ts

@@ -0,0 +1,77 @@
+import type { FieldDescriptor, ExternalTable } from './types.js'
+import { pgTable, pgSchema } from '../query/pg-core/index.js'
+import { buildColumns } from './build-table.js'
+import { camelToSnake } from './naming.js'
+import { definitions } from './define.js'
+import { projectSelectShape } from './build-schema.js'
+import { hasExternalName, registerExternal } from './external-registry.js'
+
+export { isExternal, clearExternalNames } from './external-registry.js'
+
+const IDENT = /^[a-z_][a-z0-9_]*$/
+
+/**
+ * Declares a table or view that another service owns, so this app can read it with
+ * typed columns and the normal query operators.
+ *
+ * Contract: read-only (pipe.insert/update/delete/upsert reject it at compile time and
+ * at runtime), never migrated (a schema module exporting it produces no statements),
+ * not tenant-scoped (filter by the tenant column in the query), and not in the
+ * definitions() registry. Tables and views read the same way, so either works.
+ * `schema` is required; `table` defaults to the snake_case of `name`.
+ */
+export function external<TFields extends Record<string, FieldDescriptor>, TName extends string = string>(
+  name: TName,
+  fields: TFields,
+  options: { schema: string; table?: string },
+): ExternalTable<TFields, TName> {
+  const schema = options.schema
+  const table = options.table ?? camelToSnake(name)
+
+  if (typeof schema !== 'string' || !IDENT.test(schema)) {
+    throw new Error(
+      `[pipework] "${name}" is external but its schema ${JSON.stringify(schema)} is not a plain identifier.\n\n` +
+      '  Fix: pass { schema: "owner_schema" } using lowercase letters, digits and underscores.\n',
+    )
+  }
+  if (!IDENT.test(table)) {
+    throw new Error(
+      `[pipework] "${name}" is external but its table ${JSON.stringify(table)} is not a plain identifier.\n\n` +
+      '  Fix: pass { table: "relation_name" } using lowercase letters, digits and underscores.\n',
+    )
+  }
+  if (hasExternalName(name) || definitions().has(name)) {
+    throw new Error(
+      `[pipework] Duplicate domain definition: "${name}" is already registered.\n\n` +
+      '  Each definition, external or not, must have a unique name.\n' +
+      '  Fix: rename one of them.\n',
+    )
+  }
+  for (const [key, descriptor] of Object.entries(fields)) {
+    if (descriptor._meta.tenant === true) {
+      throw new Error(
+        `[pipework] "${name}" is external: pipework does not scope it by tenant. ` +
+        `Fix: remove .tenant() from "${key}", and filter by the tenant column in the query.`,
+      )
+    }
+  }
+
+  const { columns } = buildColumns(fields as Record<string, FieldDescriptor>, true)
+  const base = schema === 'public' ? pgTable(table, columns) : pgSchema(schema).table(table, columns)
+
+  let cachedSelect: ReturnType<typeof projectSelectShape> | undefined
+  const methods = {
+    $name: name,
+    get $fields() { return fields },
+    $external: { schema, table },
+    selectShape() {
+      cachedSelect ??= projectSelectShape(fields)
+      return cachedSelect
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- phantom type marker, never accessed at runtime
+    get Select(): any { return undefined },
+  }
+  const result = Object.assign(base, methods) as unknown as ExternalTable<TFields, TName>
+  registerExternal(name, result)
+  return result
+}

package/src/data/domain/field.ts

@@ -0,0 +1,279 @@
+import type { z } from 'zod/v4'
+import type { FieldDescriptor, FieldMeta, FieldFlags, FieldKind, DefinedTable } from './types.js'
+import type { CollationName } from '../query/collation.js'
+import type { SQL } from '../db/types.js'
+import type { Branded, InferFieldOutput } from './brand.js'
+
+/** The one place a list column's refusals live: `.array()` against keys, tenant, generated ids and references, in either order. */
+function refuseArray(meta: FieldMeta, modifier: string, order: 'before' | 'after'): void {
+  const other = order === 'before'
+    ? (meta.primaryKey ? 'primaryKey' : meta.tenant ? 'tenant' : meta.defaultRandom ? 'defaultRandom'
+      : meta.kind === 'serial' ? 'serial' : meta.reference !== undefined ? 'references' : undefined)
+    : (meta.array ? 'array' : undefined)
+  if (other === undefined) return
+  throw new Error(
+    `[pipework] .${modifier}() cannot follow .${other}(): a list column cannot be a key, a tenant column, a generated id or a reference.\n\n` +
+    `  Fix: keep the list in its own field without .${modifier === 'array' ? other : 'array'}(), and put the key or reference on a scalar field.\n`,
+  )
+}
+
+/** A generated column is computed by Postgres: it takes no default, key, tenant role or reference, in either order. */
+function refuseGenerated(meta: FieldMeta, modifier: string, order: 'before' | 'after'): void {
+  const other = order === 'before'
+    ? (meta.hasDefault ? 'default' : meta.primaryKey ? 'primaryKey' : meta.tenant ? 'tenant' : meta.reference !== undefined ? 'references' : undefined)
+    : (meta.generated !== undefined ? 'generatedAlwaysAs' : undefined)
+  if (other === undefined) return
+  const [first, second] = order === 'before' ? [other, modifier] : [modifier, other]
+  throw new Error(
+    `[pipework] .${first}() and .${second}() cannot be combined on one field: a generated column is computed by Postgres and takes no default, key, tenant role or reference.\n\n` +
+    `  Fix: keep the generated column in its own field, and put the default, key, tenant or reference on another field.\n`,
+  )
+}
+
+function createField<TOutput = unknown, TFlags extends FieldFlags = {}>(meta: FieldMeta): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags> {
+  const self: Record<string, unknown> = {
+    _meta: meta,
+
+    nullable() {
+      return createField<TOutput | null, TFlags & { nullable: true }>({ ...meta, nullable: true })
+    },
+
+    default(value: unknown) {
+      refuseGenerated(meta, 'default', 'after')
+      return createField<TOutput, TFlags & { hasDefault: true }>({ ...meta, hasDefault: true, defaultValue: value })
+    },
+
+    primaryKey() {
+      refuseArray(meta, 'primaryKey', 'after')
+      refuseGenerated(meta, 'primaryKey', 'after')
+      return createField<TOutput, TFlags & { primaryKey: true }>({ ...meta, primaryKey: true })
+    },
+
+    defaultRandom() {
+      refuseArray(meta, 'defaultRandom', 'after')
+      refuseGenerated(meta, 'defaultRandom', 'after')
+      return createField<TOutput, TFlags & { defaultRandom: true; hasDefault: true }>({ ...meta, defaultRandom: true, hasDefault: true })
+    },
+
+    unique() {
+      return createField<TOutput, TFlags>({ ...meta, unique: true })
+    },
+
+    readOnly() {
+      return createField<TOutput, TFlags & { readOnly: true }>({ ...meta, readOnly: true })
+    },
+
+    tenant() {
+      refuseArray(meta, 'tenant', 'after')
+      refuseGenerated(meta, 'tenant', 'after')
+      return createField<TOutput, TFlags & { tenant: true }>({ ...meta, tenant: true })
+    },
+
+    generatedAlwaysAs(as: SQL | (() => SQL)) {
+      refuseGenerated(meta, 'generatedAlwaysAs', 'before')
+      return createField<TOutput, TFlags & { generated: true }>({ ...meta, generated: { as } })
+    },
+
+    collate(name: CollationName) {
+      if (meta.kind !== 'text') {
+        throw new Error(
+          `[pipework] .collate() applies to text fields; this field is "${meta.kind}".\n\n` +
+          '  Fix: declare the collation on a field.text() column.\n',
+        )
+      }
+      return createField<TOutput, TFlags>({ ...meta, collation: name })
+    },
+
+    traceSafe() {
+      return createField<TOutput, TFlags>({ ...meta, traceSafe: true })
+    },
+
+    brand(name: string) {
+      return createField({ ...meta, brand: name })
+    },
+
+    references(
+      definition: DefinedTable | (() => DefinedTable),
+      fieldName: string,
+      options?: { enforced?: boolean },
+    ) {
+      refuseArray(meta, 'references', 'after')
+      refuseGenerated(meta, 'references', 'after')
+      const enforced = options?.enforced ?? true
+      // Eager form: infer brand from the referenced field at construction.
+      // Thunk form: can't resolve yet — the caller must chain .brand()
+      // explicitly. The validator still recognises brand reuse as intentional
+      // because it resolves the thunk at validation time and compares.
+      const inferredBrand = typeof definition === 'function'
+        ? undefined
+        : definition.$fields[fieldName]?._meta.brand
+      return createField({
+        ...meta,
+        reference: { definition, field: fieldName, ...(enforced ? {} : { enforced: false }) },
+        ...(inferredBrand !== undefined && meta.brand === undefined ? { brand: inferredBrand } : {}),
+      })
+    },
+
+    array() {
+      if (meta.nullable) {
+        throw new Error('[pipework] .array() cannot follow .nullable(): the list may be null, its elements may not.\n\n  Fix: write .array().nullable().\n')
+      }
+      refuseArray(meta, 'array', 'before')
+      return createField<readonly TOutput[], TFlags>({ ...meta, array: true })
+    },
+
+    min(value: number) {
+      return createField<TOutput, TFlags>({ ...meta, min: value })
+    },
+
+    max(value: number) {
+      return createField<TOutput, TFlags>({ ...meta, max: value })
+    },
+
+    email() {
+      return createField<TOutput, TFlags>({ ...meta, email: true })
+    },
+
+    url() {
+      return createField<TOutput, TFlags>({ ...meta, url: true })
+    },
+
+    regex(pattern: RegExp) {
+      return createField<TOutput, TFlags>({ ...meta, regex: pattern })
+    },
+
+    precision(p: number, s: number) {
+      return createField<TOutput, TFlags>({ ...meta, precision: { p, s } })
+    },
+
+    serializedAs(_format: 'string') {
+      return createField<string, TFlags>({ ...meta, serializedAs: _format })
+    },
+  }
+
+  return self as unknown as FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+}
+
+export interface FieldModifiers<TOutput = unknown, TFlags extends FieldFlags = {}> {
+  nullable(): FieldDescriptor<TOutput | null, TFlags & { nullable: true }> & FieldModifiers<TOutput | null, TFlags & { nullable: true }>
+  default(value: unknown): FieldDescriptor<TOutput, TFlags & { hasDefault: true }> & FieldModifiers<TOutput, TFlags & { hasDefault: true }>
+  primaryKey(): FieldDescriptor<TOutput, TFlags & { primaryKey: true }> & FieldModifiers<TOutput, TFlags & { primaryKey: true }>
+  defaultRandom(): FieldDescriptor<TOutput, TFlags & { defaultRandom: true; hasDefault: true }> & FieldModifiers<TOutput, TFlags & { defaultRandom: true; hasDefault: true }>
+  unique(): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  readOnly(): FieldDescriptor<TOutput, TFlags & { readOnly: true }> & FieldModifiers<TOutput, TFlags & { readOnly: true }>
+  tenant(): FieldDescriptor<TOutput, TFlags & { tenant: true }> & FieldModifiers<TOutput, TFlags & { tenant: true }>
+  /** A stored generated column: Postgres writes `GENERATED ALWAYS AS (expr) STORED`; insert and update shapes omit it, and it can be indexed and used as a conflict target. */
+  generatedAlwaysAs(as: SQL | (() => SQL)): FieldDescriptor<TOutput, TFlags & { generated: true }> & FieldModifiers<TOutput, TFlags & { generated: true }>
+  /** The column's collation (text fields only): `"col" text COLLATE "name"`; a string is one identifier (`'en_US.utf8'`), `['pg_catalog', 'C']` is schema-qualified. Changing it later alters the column's collation. */
+  collate(name: CollationName): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  traceSafe(): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  brand<B extends string>(name: B): FieldDescriptor<Branded<TOutput, B>, TFlags> & FieldModifiers<Branded<TOutput, B>, TFlags>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- `any` avoids index-signature mismatch under exactOptionalPropertyTypes
+  references<TDef extends { readonly $fields: any }, TField extends string & keyof TDef['$fields']>(
+    definition: TDef,
+    field: TField,
+    options?: { enforced?: boolean },
+  ): FieldDescriptor<InferFieldOutput<TDef['$fields'][TField]>, TFlags> & FieldModifiers<InferFieldOutput<TDef['$fields'][TField]>, TFlags>
+  /**
+   * Thunk form — defers resolution past an import cycle. Brand is NOT
+   * inferred from the referenced field (the cycle prevents it); the caller
+   * must `.brand()` the field explicitly. Existing TOutput is preserved.
+   */
+  references(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- thunk target type can't be reached without re-entering the cycle
+    definition: () => DefinedTable<any>,
+    field: string,
+    options?: { enforced?: boolean },
+  ): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  /** A list of this field's type: `uuid[]` / `text[]` column, validated element by element. */
+  array(): FieldDescriptor<readonly TOutput[], TFlags> & FieldModifiers<readonly TOutput[], TFlags>
+  min(value: number): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  max(value: number): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  email(): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  url(): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  regex(pattern: RegExp): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  precision(p: number, s: number): FieldDescriptor<TOutput, TFlags> & FieldModifiers<TOutput, TFlags>
+  serializedAs(format: 'string'): FieldDescriptor<string, TFlags> & FieldModifiers<string, TFlags>
+}
+
+function baseMeta(kind: FieldKind): FieldMeta {
+  return {
+    kind,
+    nullable: false,
+    hasDefault: false,
+    primaryKey: false,
+    defaultRandom: false,
+    unique: false,
+    readOnly: false,
+    tenant: false,
+    array: false,
+    traceSafe: false,
+    autoManaged: false,
+    email: false,
+    url: false,
+  }
+}
+
+export const field = {
+  uuid(): FieldDescriptor<string, {}> & FieldModifiers<string, {}> {
+    return createField<string>(baseMeta('uuid'))
+  },
+
+  text(): FieldDescriptor<string, {}> & FieldModifiers<string, {}> {
+    return createField<string>(baseMeta('text'))
+  },
+
+  integer(): FieldDescriptor<number, {}> & FieldModifiers<number, {}> {
+    return createField<number>(baseMeta('integer'))
+  },
+
+  serial(): FieldDescriptor<number, { hasDefault: true; serial: true }> & FieldModifiers<number, { hasDefault: true; serial: true }> {
+    return createField<number, { hasDefault: true; serial: true }>({ ...baseMeta('serial'), hasDefault: true })
+  },
+
+  bigint(): FieldDescriptor<bigint, {}> & FieldModifiers<bigint, {}> {
+    return createField<bigint>(baseMeta('bigint'))
+  },
+
+  boolean(): FieldDescriptor<boolean, {}> & FieldModifiers<boolean, {}> {
+    return createField<boolean>(baseMeta('boolean'))
+  },
+
+  timestamp(): FieldDescriptor<Date, {}> & FieldModifiers<Date, {}> {
+    return createField<Date>(baseMeta('timestamp'))
+  },
+
+  date(): FieldDescriptor<string, {}> & FieldModifiers<string, {}> {
+    return createField<string>(baseMeta('date'))
+  },
+
+  enum<const V extends readonly [string, ...string[]]>(values: V): FieldDescriptor<V[number], {}> & FieldModifiers<V[number], {}> {
+    return createField<V[number]>({ ...baseMeta('enum'), enumValues: values })
+  },
+
+  jsonb<S extends z.ZodType>(shape: S): FieldDescriptor<z.infer<S>, {}> & FieldModifiers<z.infer<S>, {}> {
+    return createField<z.infer<S>>({ ...baseMeta('jsonb'), jsonbShape: shape })
+  },
+
+  decimal(): FieldDescriptor<string, {}> & FieldModifiers<string, {}> {
+    return createField<string>(baseMeta('decimal'))
+  },
+
+  money(p?: number, s?: number): FieldDescriptor<string, {}> & FieldModifiers<string, {}> {
+    const precision = { p: p ?? 18, s: s ?? 4 }
+    return createField<string>({ ...baseMeta('money'), precision })
+  },
+
+  /** PostgreSQL `pg_lsn` column — a WAL log sequence number (`'0/16B3748'`). `.default('currentWal')` emits `DEFAULT pg_current_wal_lsn()`. */
+  pgLsn(): FieldDescriptor<string, {}> & FieldModifiers<string, {}> {
+    return createField<string>(baseMeta('pgLsn'))
+  },
+
+  custom<S extends z.ZodType>(column: unknown, validator: S): FieldDescriptor<z.infer<S>, {}> & FieldModifiers<z.infer<S>, {}> {
+    return createField<z.infer<S>>({
+      ...baseMeta('custom'),
+      customColumn: column,
+      customValidator: validator,
+    })
+  },
+}

package/src/data/domain/index.ts

@@ -0,0 +1,13 @@
+export { field, type FieldModifiers } from './field.js'
+export { define, definitions, clearRegistry } from './define.js'
+export { external, isExternal } from './external.js'
+export { camelToSnake } from './naming.js'
+export { resetFactoryCounter } from './build-factory.js'
+export { appendOnlyScopeField, effectiveDatedTrait, appendOnlyVersionsTrait, auditedTrait, softDeletedTrait } from './traits.js'
+export type { Branded, Brand, InferSelect, InferFieldOutput } from './brand.js'
+export type { InsertProjection, SelectProjection, UpdateProjection } from './projections.js'
+export type { FieldKind, FieldFlags, ForeignKeyAction, CompositeForeignKey, PartitionSpec,
+  FieldDescriptor, FieldRecord, FieldMeta, DomainDefinition, DefinedTable, ExternalTable, DefinitionMethods,
+  DefineOptions, FactoryBuilder, FactoryOptions, TraitDefinition,
+  FieldColumn, ProjectedColumns,
+  EffectiveDatedFields, AppendOnlyVersionsFields, AuditedFields, SoftDeletedFields } from './types.js'

package/src/data/domain/naming.ts

@@ -0,0 +1,6 @@
+export function camelToSnake(str: string): string {
+  return str
+    .replace(/([A-Z])/g, '_$1')
+    .toLowerCase()
+    .replace(/^_/, '')
+}