@zmdb/orm 1.0.0-beta.1

package/src/dto/index.ts

@@ -0,0 +1,379 @@
+import { isRecord, type DeclaredTable } from '@zmdb/schema';
+import type { WhereDTO, UnknownRow, OrderDir, OrderBySpec, PaginationSpec } from '@zmdb/schema/dto';
+import { createQueryCompiler, type ComparisonPredicate, type SqlDialect } from '@zmdb/sql';
+import { ValidationError } from '@zmdb/validator';
+
+/**
+ * Minimal structural view of the query-compiler SelectBuilder we drive.
+ *
+ * The methods return `this` (not `WhereTarget`), so folding a DTO into a builder
+ * preserves the caller's concrete builder type. That is what lets `compileWhere`
+ * return `B` without asserting: previously the chain widened to `WhereTarget` and
+ * every helper ended in `return b as B`.
+ */
+export interface WhereTarget {
+  where(col: string, op: string, value: unknown): this;
+  orWhere(col: string, op: string, value: unknown): this;
+  whereGroup?(predicates: readonly ComparisonPredicate[]): this;
+  orWhereGroup?(predicates: readonly ComparisonPredicate[]): this;
+  whereExists?(subquery: unknown): this;
+  orWhereExists?(subquery: unknown): this;
+  whereNotExists?(subquery: unknown): this;
+  orWhereNotExists?(subquery: unknown): this;
+  whereIn?(col: string, values: readonly unknown[]): this;
+  orWhereIn?(col: string, values: readonly unknown[]): this;
+  whereNotIn?(col: string, values: readonly unknown[]): this;
+  orWhereNotIn?(col: string, values: readonly unknown[]): this;
+}
+
+/**
+ * Record view of a value, or `undefined` if it is not a plain object.
+ *
+ * Taking `unknown` is deliberate: narrowing a *generic* DTO (`WhereDTO<T>`) in
+ * place leaves the mapped type, which has no string index signature, so keyed
+ * reads would need `as Record<string, unknown>`. Routing through `unknown` lets
+ * the guard do the widening instead of an assertion.
+ */
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return isRecord(value) ? value : undefined;
+}
+
+const OP_SQL: Record<string, string> = {
+  eq: '=',
+  ne: '!=',
+  lt: '<',
+  lte: '<=',
+  gt: '>',
+  gte: '>=',
+  in: 'in',
+  nin: 'not in',
+  like: 'like',
+  ilike: 'ilike',
+  l2: 'l2',
+  cosine: 'cosine',
+  ip: 'ip',
+};
+
+// Every operator `applyField` accepts, for the error an unrecognised one raises.
+// `isNull`/`notNull` are handled ahead of the map, so they are not keys of it.
+const KNOWN_OPERATORS: readonly string[] = [...Object.keys(OP_SQL), 'isNull', 'notNull'];
+
+/**
+ * A `{ table, select?, where? }` literal in a DTO, compiled into a subquery builder.
+ *
+ * boundary: the input is `unknown` because a DTO arrives from outside the process, and what
+ * establishes the shape is the `in` checks in the `if`, not the two casts. The first reads
+ * the one property those checks have just proven is a string; the second names the rest of
+ * the shape, and each optional field is tested again before it is used — `select` for a
+ * non-zero length, `where` for presence — so the only thing a wrong payload can produce is
+ * a narrower subquery, never a call with a value of the wrong kind in it.
+ */
+function resolveSubqueryTarget(target: unknown, dialect: SqlDialect | undefined): unknown {
+  if (
+    target !== null &&
+    typeof target === 'object' &&
+    !('compile' in target) &&
+    'table' in target &&
+    typeof (target as { table: unknown }).table === 'string'
+  ) {
+    const spec = target as {
+      table: string;
+      select?: readonly string[];
+      where?: WhereDTO<UnknownRow>;
+    };
+    if (dialect === undefined) {
+      throw new ValidationError('compileWhere: a table subquery requires the builder dialect object');
+    }
+    // Both clauses, not either: `{ table, select, where }` means a projection *and* a
+    // filter, and a subquery that dropped the filter would match every row.
+    let sub = createQueryCompiler(dialect).selectFrom(spec.table);
+    if (spec.select && spec.select.length > 0) {
+      sub = sub.select(spec.select);
+    }
+    if (spec.where) {
+      sub = compileWhere(sub, spec.where);
+    }
+    return sub;
+  }
+  return target;
+}
+
+/**
+ * Fold a WhereDTO into a query-compiler builder. Bare values become `eq`.
+ * Fields/operators are applied in stable object-key order (golden SQL).
+ * `and`/`or` groups compose; `or` members are ORed.
+ */
+export function compileWhere<T extends DeclaredTable, B extends WhereTarget>(
+  builder: B,
+  where: WhereDTO<T> | undefined,
+  resolveColumn: (column: string) => string = column => column,
+): B {
+  if (!where) return builder;
+  let b: B = builder;
+  // boundary: `WhereTarget` is the structural minimum this function calls — `where`, `and`,
+  // `or` — and deliberately does not require a `dialect`, so that a caller's own builder
+  // qualifies. Reading one off it is therefore a probe for an optional property rather than
+  // a claim about the type, and the `??` is what handles the builder that has none.
+  const dialect = (builder as { dialect?: SqlDialect }).dialect;
+
+  const applyField = (col: string, spec: unknown, connector: 'and' | 'or') => {
+    const resolvedColumn = resolveColumn(col);
+    const add = (op: string, rawVal: unknown) => {
+      const value = resolveSubqueryTarget(rawVal, dialect);
+      if (connector === 'or') {
+        b = b.orWhere(resolvedColumn, op, value);
+      } else {
+        b = b.where(resolvedColumn, op, value);
+      }
+    };
+    if (
+      spec !== null &&
+      typeof spec === 'object' &&
+      !Array.isArray(spec) &&
+      !('compile' in spec) &&
+      !('table' in spec)
+    ) {
+      const ops = asRecord(spec);
+      if (ops) {
+        if (Object.keys(ops).length === 0) {
+          // `FieldOps`' keys are all optional, so `{ age: {} }` is type-legal, and it is
+          // what building a filter conditionally produces: `{ age: min === undefined ? {}
+          // : { gte: min } }`. Folding it to nothing means the query looks filtered and is
+          // not — over-disclosure on a SELECT, the whole table on an UPDATE or DELETE. An
+          // empty operator map is not a filter, and "match everything" is the least likely
+          // thing the caller meant (#608).
+          throw new ValidationError(
+            `compileWhere: column "${col}" has an empty operator map, which would match every row`,
+            [{ path: col, message: 'empty operator map', expected: KNOWN_OPERATORS.join(' | ') }],
+          );
+        }
+        for (const [op, value] of Object.entries(ops)) {
+          if (op === 'isNull') {
+            if (value) add('is null', null);
+            else add('is not null', null);
+          } else if (op === 'notNull') {
+            add(value ? 'is not null' : 'is null', null);
+          } else if (op === 'in' && Array.isArray(value)) {
+            if (connector === 'or' && b.orWhereIn) b = b.orWhereIn(resolvedColumn, value);
+            else if (connector !== 'or' && b.whereIn) b = b.whereIn(resolvedColumn, value);
+            else add('in', value);
+          } else if (op === 'nin' && Array.isArray(value)) {
+            if (connector === 'or' && b.orWhereNotIn) b = b.orWhereNotIn(resolvedColumn, value);
+            else if (connector !== 'or' && b.whereNotIn) b = b.whereNotIn(resolvedColumn, value);
+            else add('not in', value);
+          } else {
+            // `Object.hasOwn`, not a truthy read: `OP_SQL` is an object literal, so an
+            // operator named `toString`, `constructor`, `valueOf` or `__proto__` resolves
+            // through `Object.prototype` and passes a truthiness check as a function or an
+            // object. A where-DTO is the path user JSON takes into the builder, so those
+            // keys arrive from outside the process (#364).
+            const sql = Object.hasOwn(OP_SQL, op) ? OP_SQL[op] : undefined;
+            if (sql === undefined) {
+              // Fail closed. Skipping the key emitted a statement with one predicate
+              // fewer than the caller wrote, which on an UPDATE or DELETE is the whole
+              // table.
+              throw new ValidationError(`compileWhere: unknown operator "${op}" on column "${col}"`, [
+                {
+                  path: col,
+                  message: `unknown operator "${op}"`,
+                  expected: KNOWN_OPERATORS.join(' | '),
+                  value,
+                },
+              ]);
+            }
+            add(sql, value);
+          }
+        }
+      }
+    } else {
+      // bare value or direct subquery spec ⇒ eq
+      add('=', spec);
+    }
+  };
+
+  const applyExists = (spec: unknown, isNot: boolean, connector: 'and' | 'or') => {
+    const items = Array.isArray(spec) ? spec : [spec];
+    for (const item of items) {
+      const resolved = resolveSubqueryTarget(item, dialect);
+      if (connector === 'or') {
+        if (isNot) {
+          if (!b.orWhereNotExists) {
+            throw new Error('Builder does not support orWhereNotExists');
+          }
+          b = b.orWhereNotExists(resolved);
+        } else {
+          if (!b.orWhereExists) {
+            throw new Error('Builder does not support orWhereExists');
+          }
+          b = b.orWhereExists(resolved);
+        }
+      } else {
+        if (isNot) {
+          if (!b.whereNotExists) {
+            throw new Error('Builder does not support whereNotExists');
+          }
+          b = b.whereNotExists(resolved);
+        } else {
+          if (!b.whereExists) {
+            throw new Error('Builder does not support whereExists');
+          }
+          b = b.whereExists(resolved);
+        }
+      }
+    }
+  };
+
+  const { and, or } = where;
+  const fields = asRecord(where);
+  if (!fields) return b;
+  for (const key of Object.keys(fields)) {
+    if (key === 'and') {
+      if (and) for (const sub of and) b = compileWhere(b, sub, resolveColumn);
+    } else if (key === 'or') {
+      for (const sub of or ?? []) {
+        const group = asRecord(sub);
+        if (group) {
+          for (const [col, spec] of Object.entries(group)) {
+            if (col === 'exists') {
+              applyExists(spec, false, 'or');
+            } else if (col === 'notExists') {
+              applyExists(spec, true, 'or');
+            } else {
+              applyField(col, spec, 'or');
+            }
+          }
+        }
+      }
+    } else if (key === 'exists') {
+      applyExists(fields[key], false, 'and');
+    } else if (key === 'notExists') {
+      applyExists(fields[key], true, 'and');
+    } else {
+      applyField(key, fields[key], 'and');
+    }
+  }
+  return b;
+}
+
+/** Like {@link WhereTarget}: `this`-returning so folding preserves the builder type. */
+export interface OrderTarget {
+  orderBy(col: string, dir: OrderDir): this;
+  limit(n: number): this;
+  offset(n: number): this;
+}
+
+export function applyOrderBy<B extends OrderTarget>(
+  builder: B,
+  order: OrderBySpec | undefined,
+  pkColumn?: string,
+  resolveColumn: (column: string) => string = column => column,
+): B {
+  if (!order && !pkColumn) return builder;
+  let b = builder;
+  const cols: { column: PropertyKey; dir?: OrderDir }[] = order ? [...order] : [];
+  if (pkColumn && !cols.some(item => String(item.column) === pkColumn)) {
+    cols.push({ column: pkColumn, dir: 'asc' });
+  }
+  if (cols.length === 0) return builder;
+  for (const { column, dir } of cols) b = b.orderBy(resolveColumn(String(column)), dir ?? 'asc');
+  return b;
+}
+
+class BranchTarget implements WhereTarget {
+  private b: WhereTarget;
+  private firstCallInBranch: boolean;
+
+  constructor(b: WhereTarget, isFirstBranch: boolean) {
+    this.b = b;
+    this.firstCallInBranch = !isFirstBranch;
+  }
+
+  where(col: string, op: string, value: unknown): this {
+    if (this.firstCallInBranch) {
+      this.firstCallInBranch = false;
+      this.b = this.b.orWhere(col, op, value);
+    } else {
+      this.b = this.b.where(col, op, value);
+    }
+    return this;
+  }
+
+  // A keyset branch is a conjunction that is OR'd onto the branches before it,
+  // so the branch spends its OR on the first predicate and conjoins the rest.
+  // Repository filters use `whereGroup` below to preserve their own OR boundary;
+  // compileWhere's user-authored `or` tree is still flat and remains a separate
+  // predicate-tree problem.
+  orWhere(col: string, op: string, value: unknown): this {
+    return this.where(col, op, value);
+  }
+
+  whereGroup(predicates: readonly ComparisonPredicate[]): this {
+    const method = this.firstCallInBranch ? this.b.orWhereGroup : this.b.whereGroup;
+    if (method === undefined) throw new Error('keyset filters require predicate-group support');
+    this.firstCallInBranch = false;
+    this.b = method.call(this.b, predicates);
+    return this;
+  }
+
+  getBuilder(): WhereTarget {
+    return this.b;
+  }
+}
+
+export function applyKeysetFilter<B extends WhereTarget>(
+  builder: B,
+  cursorValues: Record<string, unknown>,
+  orderBy: OrderBySpec,
+  userWhere?: WhereDTO<UnknownRow>,
+  additionalWhere?: (builder: WhereTarget) => void,
+  resolveColumn: (column: string) => string = column => column,
+): B {
+  if (orderBy.length === 0) return builder;
+
+  for (const item of orderBy) {
+    if (!item) continue;
+    const colStr = String(item.column);
+    if (cursorValues[colStr] === undefined) {
+      throw new Error(`Invalid cursor: missing value for column "${colStr}"`);
+    }
+  }
+
+  let currentBuilder: WhereTarget = builder;
+  const k = orderBy.length;
+
+  for (let i = 0; i < k; i++) {
+    const itemI = orderBy[i];
+    if (!itemI) continue;
+
+    const target = new BranchTarget(currentBuilder, i === 0);
+
+    if (userWhere) {
+      compileWhere(target, userWhere, resolveColumn);
+    }
+    additionalWhere?.(target);
+
+    for (let j = 0; j < i; j++) {
+      const itemJ = orderBy[j];
+      if (!itemJ) continue;
+      const col = String(itemJ.column);
+      target.where(resolveColumn(col), '=', cursorValues[col]);
+    }
+
+    const curCol = String(itemI.column);
+    const dir = itemI.dir ?? 'asc';
+    const op = dir === 'desc' ? '<' : '>';
+    target.where(resolveColumn(curCol), op, cursorValues[curCol]);
+
+    currentBuilder = target.getBuilder();
+  }
+
+  // boundary: BranchTarget wraps B (implementing WhereTarget); getBuilder() returns the mutated query builder B.
+  return currentBuilder as B;
+}
+
+export function applyPagination<B extends OrderTarget>(builder: B, page: PaginationSpec | undefined): B {
+  if (!page) return builder;
+  let b = builder.limit(page.limit);
+  if (typeof page.offset === 'number') b = b.offset(page.offset);
+  return b;
+}

package/src/entity-modeling/index.ts

@@ -0,0 +1,38 @@
+// Entity modeling: lifecycle events — see ./SPEC.md.
+
+// §1 lifecycle events
+export type LifecycleEvent =
+  | 'beforeCreate'
+  | 'afterCreate'
+  | 'beforeUpdate'
+  | 'afterUpdate'
+  | 'beforeDelete'
+  | 'afterDelete';
+
+export interface Subscriber {
+  on: LifecycleEvent;
+  run: (ctx: unknown) => void | Promise<void>;
+}
+
+/**
+ * Sequential entity-lifecycle subscribers for repository write hooks.
+ *
+ * A failure intentionally stops the remaining subscribers and rejects the
+ * write, so this is not the application-event emitter. Use `createEvents` from
+ * `@zmdb/app/events` when handlers must run concurrently with isolated errors.
+ */
+export class EventBus {
+  private subs: Subscriber[] = [];
+  subscribe(s: Subscriber): () => void {
+    this.subs.push(s);
+    return () => {
+      const i = this.subs.indexOf(s);
+      if (i >= 0) this.subs.splice(i, 1);
+    };
+  }
+  async emit(event: LifecycleEvent, ctx: unknown): Promise<void> {
+    for (const s of this.subs) {
+      if (s.on === event) await s.run(ctx);
+    }
+  }
+}

package/src/filters/index.ts

@@ -0,0 +1,267 @@
+import { isRecord, type CoreSchema } from '@zmdb/schema';
+import { appTypeOf, type ColumnIR } from '@zmdb/schema/ir';
+import { type Predicate } from '@zmdb/sql';
+import { issuesFor, ValidationError } from '@zmdb/validator';
+
+/** One compiler predicate contributed by a named repository filter. */
+export interface FilterPredicate {
+  readonly col: string;
+  readonly op: string;
+  readonly value: unknown;
+  readonly connector?: 'AND' | 'OR';
+}
+
+/**
+ * A named predicate applied to repository reads unless it is disabled for one call.
+ *
+ * `table` is optional for the repository's own table and explicit for a join or
+ * populate target. That keeps target filters scoped to this repository instance;
+ * there is no process-global registry.
+ */
+export interface FilterDef<P = void> {
+  readonly name: string;
+  readonly table?: string;
+  /** Required for a target table unless the read supplies that table's schema directly. */
+  readonly schema?: CoreSchema<string>;
+  readonly where: {
+    bivarianceHack(params: P): readonly FilterPredicate[];
+  }['bivarianceHack'];
+  readonly enabled?: boolean;
+  readonly appliesToWrites?: boolean;
+}
+
+export type FilterParams<F> = F extends { readonly where: (params: infer P) => readonly FilterPredicate[] } ? P : never;
+
+export type FilterOverride<F> = [FilterParams<F>] extends [never]
+  ? unknown | false
+  : [FilterParams<F>] extends [void]
+    ? false
+    : FilterParams<F> | false;
+
+export type FilterOverrides<Defs extends readonly FilterDef<unknown>[]> = {
+  readonly [Def in Defs[number] as Def['name']]?: FilterOverride<Def>;
+};
+
+export interface ResolvedFilters {
+  readonly names: readonly string[];
+  readonly predicates: readonly FilterPredicate[];
+  readonly groups: readonly {
+    readonly name: string;
+    readonly predicates: readonly FilterPredicate[];
+  }[];
+}
+
+export interface ResolveFiltersOptions {
+  readonly method: string;
+  readonly table: string;
+  readonly columnPrefix?: string;
+  readonly schema?: CoreSchema<string>;
+  readonly qualifyColumns?: boolean;
+  readonly knownNames?: readonly string[];
+}
+
+export interface FilterTarget {
+  where(col: string, op: string, value: unknown): this;
+  orWhere?(col: string, op: string, value: unknown): this;
+  whereGroup?(predicates: readonly FilterPredicate[]): this;
+}
+
+function missingParameterError(filter: FilterDef<unknown>, method: string, names: readonly string[]): ValidationError {
+  const required = names.length === 0 ? ['parameters'] : names;
+  const rendered = required.join(', ');
+  return new ValidationError(
+    `filter \`${filter.name}\` requires parameters (${rendered}) and none were supplied; pass them per call — ` +
+      `${method}({ filters: { ${filter.name}: { ${rendered} } } }) — or disable it by name`,
+  );
+}
+
+function trackedObject(value: Record<string, unknown>, accessed: Set<string>): Record<string, unknown> {
+  return new Proxy(value, {
+    get(target, property, receiver) {
+      if (typeof property === 'string') accessed.add(property);
+      return Reflect.get(target, property, receiver);
+    },
+  });
+}
+
+function parametersFor(
+  filter: FilterDef<unknown>,
+  override: unknown,
+  supplied: boolean,
+  method: string,
+): { readonly predicates: readonly FilterPredicate[]; readonly accessed: readonly string[] } {
+  const accessed = new Set<string>();
+  const rawParameters =
+    supplied && override !== null && override !== undefined ? override : trackedObject(Object.create(null), accessed);
+  const parameters = isRecord(rawParameters) ? trackedObject(rawParameters, accessed) : rawParameters;
+
+  let predicates: readonly FilterPredicate[];
+  try {
+    predicates = filter.where(parameters);
+  } catch (error) {
+    if (
+      accessed.size > 0 &&
+      (!supplied || [...accessed].some(name => !isRecord(rawParameters) || rawParameters[name] == null))
+    ) {
+      throw missingParameterError(filter, method, [...accessed]);
+    }
+    throw error;
+  }
+
+  const missing = [...accessed].filter(name => !isRecord(rawParameters) || rawParameters[name] == null);
+  if (!supplied && accessed.size > 0) throw missingParameterError(filter, method, [...accessed]);
+  if (missing.length > 0) throw missingParameterError(filter, method, missing);
+  return { predicates, accessed: [...accessed] };
+}
+
+function validatePredicate(
+  filter: FilterDef<unknown>,
+  predicate: FilterPredicate,
+  schema: CoreSchema<string> | undefined,
+  accessed: readonly string[],
+): ColumnIR {
+  if (!isRecord(predicate) || typeof predicate.col !== 'string' || typeof predicate.op !== 'string') {
+    throw new ValidationError(`filter \`${filter.name}\` returned an invalid predicate`);
+  }
+  if (predicate.connector !== undefined && predicate.connector !== 'AND' && predicate.connector !== 'OR') {
+    throw new ValidationError(`filter \`${filter.name}\` returned an invalid connector`);
+  }
+  const validationSchema = filter.schema ?? schema;
+  if (validationSchema === undefined) {
+    throw new ValidationError(
+      `filter \`${filter.name}\` targets \`${filter.table}\` without a schema; provide FilterDef.schema so its columns and parameters can be validated`,
+    );
+  }
+
+  const columnName = predicate.col.slice(predicate.col.lastIndexOf('.') + 1);
+  const column = validationSchema.ir.columns.find(candidate => candidate.name === columnName);
+  if (column === undefined) {
+    throw new ValidationError(
+      `filter \`${filter.name}\` names column \`${predicate.col}\`, which is not declared by \`${validationSchema.ir.table}\``,
+    );
+  }
+
+  const operator = predicate.op.toLowerCase().trim();
+  if (operator === 'is null' || operator === 'is not null') return column;
+  if (
+    predicate.value !== null &&
+    typeof predicate.value === 'object' &&
+    'compile' in predicate.value &&
+    typeof predicate.value.compile === 'function'
+  ) {
+    return column;
+  }
+
+  const path = `filters.${filter.name}.${accessed[0] ?? columnName}`;
+  const values =
+    (operator === 'in' || operator === 'not in' || operator === 'nin') && Array.isArray(predicate.value)
+      ? predicate.value
+      : [predicate.value];
+  const issues = values.flatMap((value, index) =>
+    issuesFor(value, appTypeOf(column), values.length === 1 ? path : `${path}.${index}`),
+  );
+  if (issues.length > 0) {
+    throw new ValidationError(`validation failed: ${issues.map(issue => issue.path).join(', ')}`, issues);
+  }
+  return column;
+}
+
+/** Resolve disables and parameters before a builder is allowed to compile. */
+export function resolveFilters(
+  definitions: readonly FilterDef<unknown>[],
+  overrides: unknown,
+  options: ResolveFiltersOptions,
+): ResolvedFilters {
+  const values = overrides === undefined ? undefined : isRecord(overrides) ? overrides : undefined;
+  if (overrides !== undefined && values === undefined) {
+    throw new ValidationError('filters must be an object keyed by declared filter name');
+  }
+
+  const knownNames = new Set(options.knownNames ?? definitions.map(filter => filter.name));
+  for (const name of Object.keys(values ?? {})) {
+    if (!knownNames.has(name)) {
+      const declared = [...knownNames].toSorted();
+      throw new ValidationError(
+        `unknown filter \`${name}\`; declared filters: ${declared.length === 0 ? '(none)' : declared.join(', ')}`,
+      );
+    }
+  }
+
+  const names: string[] = [];
+  const predicates: FilterPredicate[] = [];
+  const groups: { readonly name: string; readonly predicates: readonly FilterPredicate[] }[] = [];
+  for (const filter of definitions) {
+    const supplied = values !== undefined && Object.hasOwn(values, filter.name);
+    const override = supplied ? values[filter.name] : undefined;
+    if (override === false || (!supplied && filter.enabled === false)) continue;
+
+    const resolved = parametersFor(filter, override, supplied, options.method);
+    if (!Array.isArray(resolved.predicates) || resolved.predicates.length === 0) {
+      throw new ValidationError(`filter \`${filter.name}\` returned no predicates`);
+    }
+
+    names.push(filter.name);
+    const group: FilterPredicate[] = [];
+    for (let index = 0; index < resolved.predicates.length; index++) {
+      const predicate = resolved.predicates[index];
+      if (predicate === undefined) throw new ValidationError(`filter \`${filter.name}\` returned an empty predicate`);
+      const column = validatePredicate(filter, predicate, options.schema, resolved.accessed);
+      const separator = predicate.col.lastIndexOf('.');
+      const physicalColumn =
+        separator === -1 ? column.physicalName : `${predicate.col.slice(0, separator + 1)}${column.physicalName}`;
+      const col =
+        options.qualifyColumns === true && separator === -1
+          ? `${options.columnPrefix ?? options.table}.${physicalColumn}`
+          : physicalColumn;
+      const qualified = {
+        ...predicate,
+        col,
+        connector: index === 0 ? 'AND' : (predicate.connector ?? 'AND'),
+      } satisfies FilterPredicate;
+      predicates.push(qualified);
+      group.push(qualified);
+    }
+    groups.push({ name: filter.name, predicates: Object.freeze(group) });
+  }
+
+  return {
+    names: Object.freeze([...new Set(names)]),
+    predicates: Object.freeze(predicates),
+    groups: Object.freeze(groups),
+  };
+}
+
+function needsGrouping(predicates: readonly FilterPredicate[]): boolean {
+  return predicates.some((predicate, index) => index > 0 && predicate.connector === 'OR');
+}
+
+/** Preserve each filter's boolean boundary when it is placed in WHERE or JOIN ON. */
+export function filtersAsPredicates(resolved: ResolvedFilters): readonly Predicate[] {
+  const predicates: Predicate[] = [];
+  for (const group of resolved.groups) {
+    if (needsGrouping(group.predicates)) {
+      predicates.push({ kind: 'group', predicates: group.predicates, connector: 'AND' });
+    } else {
+      predicates.push(...group.predicates);
+    }
+  }
+  return Object.freeze(predicates);
+}
+
+/** Conjoin an already-resolved set with the predicates a read builder already carries. */
+export function applyResolvedFilters<B extends FilterTarget>(builder: B, resolved: ResolvedFilters): B {
+  let filtered = builder;
+  for (const group of resolved.groups) {
+    if (needsGrouping(group.predicates)) {
+      if (filtered.whereGroup === undefined) {
+        throw new ValidationError('this statement builder cannot represent a grouped filter predicate');
+      }
+      filtered = filtered.whereGroup(group.predicates);
+      continue;
+    }
+    for (const predicate of group.predicates) {
+      filtered = filtered.where(predicate.col, predicate.op, predicate.value);
+    }
+  }
+  return filtered;
+}