tempest-db-js 0.8.0 → 0.9.0

package/dist/{chunk-NH6K5LTX.js → chunk-HXK6WIBP.js}

@@ -1,3 +1,6 @@
+import { execFile } from 'child_process';
+import { copyFile } from 'fs/promises';
+import { promisify } from 'util';
 import { createRequire } from 'module';
 
 // src/conditions.ts
@@ -110,12 +113,34 @@ var Expression = class {
     return this.compare("isNull", value);
   }
 };
+function conditionFromNode(node) {
+  return wrap(node);
+}
+function expressionFromNode(node) {
+  return new Expression(node);
+}
 function col(name) {
   return new Expression({ kind: "column", name });
 }
 function val(value) {
   return new Expression({ kind: "value", value });
 }
+function caseWhen(branches, fallback) {
+  if (branches.length === 0) {
+    throw new Error("caseWhen() needs at least one [condition, result] branch.");
+  }
+  return new Expression({
+    kind: "case",
+    branches: branches.map(([when, result]) => ({
+      when: toCondNode(when),
+      result: toExprNode(result)
+    })),
+    fallback: fallback === void 0 ? null : toExprNode(fallback)
+  });
+}
+function cast(operand, to) {
+  return new Expression({ kind: "cast", operand: toArg(operand), to });
+}
 var FUNCTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function toArg(arg) {
   return typeof arg === "string" ? { kind: "column", name: arg } : arg.node;
@@ -163,7 +188,39 @@ function not(input) {
   return wrap({ kind: "not", part: toCondNode(input) });
 }
 
+// src/aliased.ts
+function aliased(model, alias) {
+  const aliasedModel = class extends model {
+  };
+  Object.defineProperty(aliasedModel, "tablename", { value: alias, writable: true });
+  Object.defineProperty(aliasedModel, "naming", {
+    value: model.naming,
+    writable: true
+  });
+  Object.defineProperty(aliasedModel, "tableArgs", {
+    value: void 0,
+    writable: true
+  });
+  Object.defineProperty(aliasedModel, "aliasOf", { value: model, writable: true });
+  return aliasedModel;
+}
+function aliasOf(model) {
+  return model.aliasOf ?? null;
+}
+
 // src/query.ts
+function exists(subquery) {
+  return conditionFromNode({ kind: "exists", select: nodeOf(subquery), negate: false });
+}
+function notExists(subquery) {
+  return conditionFromNode({ kind: "exists", select: nodeOf(subquery), negate: true });
+}
+function scalar(subquery) {
+  return expressionFromNode({ kind: "scalar", select: subquery.node });
+}
+function nodeOf(subquery) {
+  return subquery.node;
+}
 function isSubquery(value) {
   return typeof value === "object" && value !== null && value.node?.kind === "select";
 }
@@ -177,6 +234,7 @@ var OPERATORS = [
   "like",
   "ilike",
   "ieq",
+  "iContains",
   "in",
   "notIn",
   "between",
@@ -197,16 +255,16 @@ function count() {
   return new Agg("count", "*");
 }
 function sum(column2) {
-  return new Agg("sum", column2);
+  return new Agg("sum", typeof column2 === "string" ? column2 : column2.node);
 }
 function avg(column2) {
-  return new Agg("avg", column2);
+  return new Agg("avg", typeof column2 === "string" ? column2 : column2.node);
 }
 function min(column2) {
-  return new Agg("min", column2);
+  return new Agg("min", typeof column2 === "string" ? column2 : column2.node);
 }
 function max(column2) {
-  return new Agg("max", column2);
+  return new Agg("max", typeof column2 === "string" ? column2 : column2.node);
 }
 var SelectBuilder = class _SelectBuilder {
   constructor(node, source) {
@@ -291,9 +349,35 @@ var SelectBuilder = class _SelectBuilder {
    * @param direction `"asc"` (default) or `"desc"`.
    * @returns A builder carrying the ordering term.
    */
+  /**
+   * Project extra expressions alongside the columns, by alias.
+   *
+   * This is where a window function lands: unlike `aggregate()`, it does **not**
+   * group — every row stays, with the computed value attached.
+   *
+   * @param map Alias → expression.
+   * @returns A builder whose row type carries the aliases.
+   *
+   * @example
+   * ```ts
+   * select(Sale).compute({
+   *   rank: over(rowNumber(), { partitionBy: ["region"], orderBy: [["total", "desc"]] }),
+   * });
+   * ```
+   */
+  compute(map) {
+    const computed = { ...this.node.computed ?? {} };
+    for (const [alias, expression2] of Object.entries(map)) {
+      computed[alias] = expression2.node;
+    }
+    return this.with({ computed });
+  }
   orderBy(column2, direction = "asc") {
     return this.with({
-      orderBy: [...this.node.orderBy, { column: column2, direction }]
+      orderBy: [
+        ...this.node.orderBy,
+        { column: typeof column2 === "string" ? column2 : column2.node, direction }
+      ]
     });
   }
   /** Limit the number of rows. */
@@ -386,10 +470,12 @@ function buildLock(strength, options) {
   return { strength, wait, of: options?.of ?? [] };
 }
 function select(model, columns) {
+  const base = aliasOf(model);
   return new SelectBuilder(
     {
       kind: "select",
-      table: model.tablename,
+      table: base ? base.tablename : model.tablename,
+      alias: base ? model.tablename : void 0,
       columns: columns ?? "*",
       distinct: false,
       aggregates: [],
@@ -398,12 +484,67 @@ function select(model, columns) {
       orderBy: [],
       limit: void 0,
       offset: void 0,
-      names: columnNamesOf(model) ?? void 0
+      names: columnNamesOf(model) ?? void 0,
+      codecs: codecsOf(model) ?? void 0
     },
     model
   );
 }
 
+// src/window.ts
+function functionNode(fn2) {
+  if ("call" in fn2) return fn2.call;
+  if (fn2 instanceof Agg) {
+    const arg = fn2.column === "*" ? { kind: "star" } : typeof fn2.column === "string" ? { kind: "column", name: fn2.column } : fn2.column;
+    return { kind: "fn", name: fn2.fn, args: [arg] };
+  }
+  return fn2.node;
+}
+function over(fn2, spec = {}) {
+  return expressionFromNode({
+    kind: "window",
+    fn: functionNode(fn2),
+    partitionBy: [...spec.partitionBy ?? []],
+    orderBy: (spec.orderBy ?? []).map(
+      (term) => typeof term === "string" ? { column: term, direction: "asc" } : { column: term[0], direction: term[1] }
+    ),
+    frame: spec.frame ?? null
+  });
+}
+function windowFn(name, args = []) {
+  return { call: { kind: "fn", name, args } };
+}
+function rowNumber() {
+  return windowFn("row_number");
+}
+function rank() {
+  return windowFn("rank");
+}
+function denseRank() {
+  return windowFn("dense_rank");
+}
+function percentRank() {
+  return windowFn("percent_rank");
+}
+function lag(column2, offset = 1) {
+  return windowFn("lag", [
+    { kind: "column", name: column2 },
+    { kind: "value", value: offset }
+  ]);
+}
+function lead(column2, offset = 1) {
+  return windowFn("lead", [
+    { kind: "column", name: column2 },
+    { kind: "value", value: offset }
+  ]);
+}
+function firstValue(column2) {
+  return windowFn("first_value", [{ kind: "column", name: column2 }]);
+}
+function lastValue(column2) {
+  return windowFn("last_value", [{ kind: "column", name: column2 }]);
+}
+
 // src/serialize.ts
 var ValidationError = class extends Error {
   constructor(table, issues) {
@@ -429,8 +570,20 @@ function fromBase64(value) {
   for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
   return bytes;
 }
+function baseOf(column2) {
+  return new Column(
+    column2.type,
+    column2.flags,
+    column2.defaultValue,
+    column2.onUpdateValue,
+    column2.reference,
+    column2.dbName,
+    null
+  );
+}
 function encodeValue(column2, value) {
   if (value === null || value === void 0) return null;
+  if (column2.codec) return encodeValue(baseOf(column2), column2.codec.toDb(value));
   switch (column2.type.kind) {
     case "bigint":
       return typeof value === "bigint" ? value.toString() : value;
@@ -446,6 +599,7 @@ function encodeValue(column2, value) {
 }
 function decodeValue(column2, value) {
   if (value === null || value === void 0) return null;
+  if (column2.codec) return column2.codec.fromDb(decodeValue(baseOf(column2), value));
   switch (column2.type.kind) {
     case "bigint":
       return typeof value === "bigint" ? value : BigInt(value);
@@ -565,6 +719,12 @@ function mapperFor(model) {
   const decoders = /* @__PURE__ */ new Map();
   for (const [prop, col2] of Object.entries(columnsOf(model))) {
     const decoder = decoderFor(col2.type);
+    const codec = col2.codec;
+    if (codec) {
+      const decode2 = decoder ? (value) => value === null || value === void 0 ? value : codec.fromDb(decoder(value)) : (value) => value === null || value === void 0 ? value : codec.fromDb(value);
+      decoders.set(names?.[prop] ?? prop, decode2);
+      continue;
+    }
     if (decoder) decoders.set(names?.[prop] ?? prop, decoder);
   }
   const mapper = { props, decoders };
@@ -600,7 +760,9 @@ function assertWritableValues(model, values, clause) {
       issues.push(`${clause}: "${key}" is not a column of ${model.tablename}`);
       continue;
     }
-    if (isSqlExpression(value) || isBindableScalar(value)) continue;
+    if (isExpression(value) || isSqlExpression(value) || isBindableScalar(value)) {
+      continue;
+    }
     if (typeof value === "object" && STRUCTURED_KINDS.has(col2.type.kind)) continue;
     issues.push(
       `${clause}: "${key}" got ${describeValue(value)}, which cannot be bound to a ${col2.type.kind} column \u2014 use sql.raw()/sql.expr\`...\` for a SQL expression`
@@ -608,11 +770,23 @@ function assertWritableValues(model, values, clause) {
   }
   if (issues.length > 0) throw new ValidationError(model.tablename, issues);
 }
+function encodeWriteValues(model, values) {
+  const codecs = codecsOf(model);
+  if (!codecs) return values;
+  const out = { ...values };
+  for (const [key, codec] of Object.entries(codecs)) {
+    if (!(key in out)) continue;
+    const value = out[key];
+    if (isSqlExpression(value) || isExpression(value)) continue;
+    out[key] = codec.toDb(value);
+  }
+  return out;
+}
 function assertConsistentRows(model, rows) {
   if (rows.length < 2) return;
-  const union = /* @__PURE__ */ new Set();
-  for (const row of rows) for (const key of Object.keys(row)) union.add(key);
-  const inconsistent = [...union].filter((key) => rows.some((row) => !(key in row)));
+  const union2 = /* @__PURE__ */ new Set();
+  for (const row of rows) for (const key of Object.keys(row)) union2.add(key);
+  const inconsistent = [...union2].filter((key) => rows.some((row) => !(key in row)));
   if (inconsistent.length === 0) return;
   const columns = columnsOf(model);
   const defaulted = inconsistent.filter((key) => columns[key]?.flags.hasDefault);
@@ -650,9 +824,10 @@ var InsertBuilder = class _InsertBuilder {
    */
   values(rows) {
     const list = Array.isArray(rows) ? rows : [rows];
-    for (const row of list) assertWritableValues(this.source, row, "values");
-    assertConsistentRows(this.source, list);
-    return this.with({ values: list });
+    const encoded = list.map((row) => encodeWriteValues(this.source, row));
+    for (const row of encoded) assertWritableValues(this.source, row, "values");
+    assertConsistentRows(this.source, encoded);
+    return this.with({ values: encoded });
   }
   /**
    * On a unique/PK conflict on `target`, do nothing (skip the row).
@@ -703,6 +878,34 @@ var InsertBuilder = class _InsertBuilder {
       }
     });
   }
+  /**
+   * Fill the table from another query — `INSERT INTO t (a, b) SELECT …`.
+   *
+   * The rows never leave the database, which is the point: archiving or copying a
+   * million rows should not become a million round trips through this process.
+   *
+   * @param columns The target columns, in the order the query projects them.
+   * @param query The query producing the rows.
+   * @returns A builder ready to execute.
+   * @throws Error When no target column is given.
+   *
+   * @example
+   * ```ts
+   * insert(ArchivedOrder).fromSelect(
+   *   ["id", "total"],
+   *   select(Order, ["id", "total"]).where({ createdAt: { lt: cutoff } }),
+   * );
+   * ```
+   */
+  fromSelect(columns, query) {
+    if (columns.length === 0) {
+      throw new Error("fromSelect() needs at least one target column.");
+    }
+    return this.with({
+      values: [],
+      fromSelect: { columns: [...columns], select: query.node }
+    });
+  }
   returning(columns) {
     return this.with({ returning: columns ?? "*" });
   }
@@ -714,11 +917,21 @@ function insert(model) {
       table: model.tablename,
       values: [],
       returning: null,
-      names: columnNamesOf(model) ?? void 0
+      names: columnNamesOf(model) ?? void 0,
+      codecs: codecsOf(model) ?? void 0
     },
     model
   );
 }
+function withOnUpdateValues(model, values) {
+  const merged = { ...values };
+  for (const [name, col2] of Object.entries(columnsOf(model))) {
+    if (col2.onUpdateValue !== null && !(name in merged)) {
+      merged[name] = defaultAsWriteValue(col2.onUpdateValue);
+    }
+  }
+  return merged;
+}
 var UpdateBuilder = class _UpdateBuilder {
   constructor(node, source) {
     this.node = node;
@@ -749,8 +962,30 @@ var UpdateBuilder = class _UpdateBuilder {
    * ```
    */
   set(values) {
-    assertWritableValues(this.source, values, "set");
-    return this.with({ set: values });
+    const encoded = encodeWriteValues(this.source, values);
+    assertWritableValues(this.source, encoded, "set");
+    return this.with({
+      set: withOnUpdateValues(this.source, encoded)
+    });
+  }
+  /**
+   * Read from another table while updating — `UPDATE t SET … FROM other WHERE …`.
+   *
+   * The join condition goes in `where`, where SQL wants it:
+   * `.where({ customerId: col("c.id") })`.
+   *
+   * PostgreSQL and SQLite (3.33+) only. MySQL spells this as a multi-table
+   * `UPDATE a JOIN b`, which is out of this project's active scope, so it throws
+   * there rather than emitting something the server rejects.
+   *
+   * @param model The extra source.
+   * @param alias The name to reference it by.
+   * @returns A builder carrying the extra source.
+   */
+  from(model, alias) {
+    return this.with({
+      from: [...this.node.from ?? [], { table: model.tablename, alias }]
+    });
   }
   /** Restrict the rows to update. Marks the builder safe to execute. */
   where(input) {
@@ -776,7 +1011,8 @@ function update(model) {
       where: void 0,
       guarded: false,
       returning: null,
-      names: columnNamesOf(model) ?? void 0
+      names: columnNamesOf(model) ?? void 0,
+      codecs: codecsOf(model) ?? void 0
     },
     model
   );
@@ -791,6 +1027,22 @@ var DeleteBuilder = class _DeleteBuilder {
   with(patch) {
     return new _DeleteBuilder({ ...this.node, ...patch }, this.source);
   }
+  /**
+   * Delete by matching another table — `DELETE FROM t USING other WHERE …`.
+   *
+   * PostgreSQL only. SQLite and MySQL have no `USING` here; there the portable
+   * form is `where({ id: { in: select(Other, ["id"]).where(...).asSubquery("id") } })`,
+   * and this throws rather than pretending.
+   *
+   * @param model The extra source.
+   * @param alias The name to reference it by.
+   * @returns A builder carrying the extra source.
+   */
+  using(model, alias) {
+    return this.with({
+      using: [...this.node.using ?? [], { table: model.tablename, alias }]
+    });
+  }
   /** Restrict the rows to delete. Marks the builder safe to execute. */
   where(input) {
     return this.with({
@@ -814,7 +1066,8 @@ function del(model) {
       where: void 0,
       guarded: false,
       returning: null,
-      names: columnNamesOf(model) ?? void 0
+      names: columnNamesOf(model) ?? void 0,
+      codecs: codecsOf(model) ?? void 0
     },
     model
   );
@@ -918,10 +1171,15 @@ function detectDialect(url) {
 }
 
 // src/expressions.ts
+function renderExcluded(column2, bare, dialect) {
+  return dialect === "mysql" ? `VALUES(${bare})` : `excluded.${column2}`;
+}
 function renderPortableToken(token, dialect) {
   switch (token) {
     case "now":
-      return dialect === "postgresql" ? "now()" : "CURRENT_TIMESTAMP";
+      if (dialect === "postgresql") return "now()";
+      if (dialect === "sqlite") return "strftime('%Y-%m-%dT%H:%M:%fZ', 'now')";
+      return "CURRENT_TIMESTAMP";
     case "current_date":
       return "CURRENT_DATE";
     case "current_time":
@@ -933,8 +1191,76 @@ function renderPortableToken(token, dialect) {
   }
 }
 
+// src/search.ts
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+function tokenize(term) {
+  return term.split(/\s+/).filter((token) => token.length > 0);
+}
+function contains(columns, term, options) {
+  if (columns.length === 0) {
+    throw new Error("contains() needs at least one column to search.");
+  }
+  const tokens = tokenize(term);
+  if (tokens.length === 0) return alwaysFalse();
+  const perToken = tokens.map(
+    (token) => or(
+      ...columns.map((column2) => ({ [column2]: { iContains: token } }))
+    )
+  );
+  if (options?.match === "any") return or(...perToken);
+  return perToken.length === 1 ? perToken[0] : and(...perToken);
+}
+function alwaysFalse() {
+  return conditionFromNode({
+    kind: "compare",
+    left: { kind: "value", value: 1 },
+    op: "eq",
+    right: { kind: "value", value: 0 }
+  });
+}
+function fullText(columns, term, options) {
+  if (columns.length === 0) {
+    throw new Error("fullText() needs at least one column to search.");
+  }
+  return conditionFromNode({
+    kind: "fullText",
+    columns: [...columns],
+    term,
+    language: options?.language ?? "english",
+    fallback: contains(columns, term).node
+  });
+}
+function fullTextRank(columns, term, options) {
+  if (columns.length === 0) {
+    throw new Error("fullTextRank() needs at least one column to rank on.");
+  }
+  return expressionFromNode({
+    kind: "rank",
+    columns: [...columns],
+    term,
+    language: options?.language ?? "english"
+  });
+}
+
 // src/dialect.ts
 var OPERATOR_SET = new Set(OPERATORS);
+var MULTI_VALUE_OPERATORS = /* @__PURE__ */ new Set(["in", "notIn", "between"]);
+function encodeOperand(op, operand, encode) {
+  if (op === "isNull") return operand;
+  if (MULTI_VALUE_OPERATORS.has(op)) {
+    return Array.isArray(operand) ? operand.map(encode) : operand;
+  }
+  return encode(operand);
+}
+function codecEncoder(codecs) {
+  if (!codecs) return (_key, value) => value;
+  return (key, value) => {
+    const codec = codecs[key];
+    return codec ? codec.toDb(value) : value;
+  };
+}
 function isOperatorObject(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || value instanceof Uint8Array) {
     return false;
@@ -953,6 +1279,18 @@ var Params = class {
     return this.placeholder(this.values.length);
   }
 };
+var LiteralParams = class extends Params {
+  constructor() {
+    super(() => "");
+  }
+  bind(value) {
+    if (value === null || value === void 0) return "NULL";
+    if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+    if (typeof value === "number" || typeof value === "bigint") return String(value);
+    if (value instanceof Date) return `'${value.toISOString()}'`;
+    return `'${String(value).replace(/'/g, "''")}'`;
+  }
+};
 function insertColumns(rows) {
   const columns = [];
   const seen = /* @__PURE__ */ new Set();
@@ -988,6 +1326,20 @@ var BaseDialect = class _BaseDialect {
   static insertTemplates = /* @__PURE__ */ new Map();
   /** Quoted-identifier cache (see {@link quoteId}). Shared across dialects. */
   static quotedIds = /* @__PURE__ */ new Map();
+  /**
+   * Render a case-insensitive LIKE whose pattern carries escaped wildcards.
+   *
+   * The `ESCAPE` clause is not decoration: PostgreSQL treats `\` as the escape
+   * character by default, **SQLite has none at all** until one is declared, so
+   * without this the escaping done on our side would be meaningless there.
+   *
+   * @param column The rendered column.
+   * @param param The bound pattern.
+   * @returns The rendered comparison.
+   */
+  ilikeEscaped(column2, param) {
+    return `${this.ilike(column2, param)} ESCAPE '\\'`;
+  }
   /**
    * Validate a subquery operand before it is rendered, for dialects that restrict
    * what an `IN (SELECT ...)` may contain. The default accepts everything.
@@ -1047,9 +1399,105 @@ var BaseDialect = class _BaseDialect {
       case "join_select":
         sql2 = this.compileJoin(node, params);
         break;
+      case "set_op":
+        sql2 = this.compileSetOp(node, params);
+        break;
     }
     return { sql: sql2, params: params.values };
   }
+  /**
+   * Render a condition as schema SQL, with values inlined.
+   *
+   * Same compiler as a `WHERE`, different parameter strategy — so a `CHECK` and
+   * the query language cannot drift apart in what they mean.
+   *
+   * @param node The condition.
+   * @param params A {@link LiteralParams}.
+   * @returns The rendered predicate.
+   */
+  renderConditionLiteral(node, params) {
+    return this.compileCondition(node, params, (key) => this.columnId(key, void 0));
+  }
+  /**
+   * Render the `WITH` clause of a statement.
+   *
+   * `RECURSIVE` is a property of the **clause**, not of an entry: one recursive
+   * entry makes the whole `WITH` recursive, which is what the SQL standard says
+   * and what PostgreSQL and SQLite both implement.
+   *
+   * @param entries The `WITH` entries, if any.
+   * @param params The parameter collector.
+   * @returns The clause with a trailing space, or an empty string.
+   */
+  compileWith(entries, params) {
+    if (!entries || entries.length === 0) return "";
+    const recursive = entries.some((entry) => entry.recursive) ? "RECURSIVE " : "";
+    const rendered = entries.map((entry) => {
+      const body = entry.body.kind === "set_op" ? this.compileSetOp(entry.body, params) : this.compileSelect(entry.body, params);
+      const hint = entry.materialized === null ? "" : entry.materialized ? " MATERIALIZED" : " NOT MATERIALIZED";
+      return `${this.quoteId(entry.name)} AS${hint} (${body})`;
+    });
+    return `WITH ${recursive}${rendered.join(", ")} `;
+  }
+  /**
+   * The `EXPLAIN` prefix for this dialect.
+   *
+   * @param analyze Whether to measure by actually running the statement.
+   * @returns The prefix to put in front of the statement.
+   * @throws Error When the dialect cannot do what was asked.
+   */
+  explainPrefix(analyze) {
+    return analyze ? "EXPLAIN (FORMAT JSON, ANALYZE)" : "EXPLAIN (FORMAT JSON)";
+  }
+  /**
+   * The SQL keyword for a set operation.
+   *
+   * @param op The operator.
+   * @returns The keyword.
+   * @throws Error On a dialect that does not implement it.
+   */
+  setOperator(op) {
+    switch (op) {
+      case "union":
+        return "UNION";
+      case "unionAll":
+        return "UNION ALL";
+      case "intersect":
+        return "INTERSECT";
+      case "except":
+        return "EXCEPT";
+    }
+  }
+  /**
+   * Compile a set operation.
+   *
+   * A branch carrying its own `ORDER BY`/`LIMIT` is parenthesized: without the
+   * parentheses those clauses bind to the **combined** result, which is a
+   * different query and a classic source of silently wrong output.
+   *
+   * @param node The set-operation node.
+   * @param params The parameter collector.
+   * @returns The rendered statement.
+   */
+  compileSetOp(node, params) {
+    const keyword = ` ${this.setOperator(node.op)} `;
+    const branches = node.branches.map((branch) => {
+      const sql3 = branch.kind === "join_select" ? this.compileJoin(branch, params) : this.compileSelect(branch, params);
+      const scoped = branch.orderBy.length > 0 || branch.limit !== void 0;
+      return scoped ? `(${sql3})` : sql3;
+    });
+    let sql2 = branches.join(keyword);
+    if (node.orderBy.length > 0) {
+      const terms = node.orderBy.map((t) => {
+        const id = typeof t.column === "string" ? this.quoteId(t.column) : this.renderExpr(t.column, params, (k) => this.quoteId(k));
+        return `${id} ${t.direction === "desc" ? "DESC" : "ASC"}`;
+      }).join(", ");
+      sql2 += ` ORDER BY ${terms}`;
+    }
+    if (node.limit !== void 0) sql2 += ` LIMIT ${params.bind(node.limit)}`;
+    if (node.offset !== void 0) sql2 += ` OFFSET ${params.bind(node.offset)}`;
+    return sql2;
+  }
   /**
    * Render a qualified `alias.column` ref as `"alias"."column"`, translating the
    * property name to the real column name for that alias's model.
@@ -1077,7 +1525,13 @@ var BaseDialect = class _BaseDialect {
    * @returns The quoted database identifier.
    */
   columnId(prop, names) {
-    return this.quoteId(names?.[prop] ?? prop);
+    const mapped = names?.[prop];
+    if (mapped !== void 0) return this.quoteId(mapped);
+    const dot = prop.indexOf(".");
+    if (dot > 0 && dot < prop.length - 1) {
+      return `${this.quoteId(prop.slice(0, dot))}.${this.quoteId(prop.slice(dot + 1))}`;
+    }
+    return this.quoteId(prop);
   }
   /**
    * Render a {@link SqlExpression} inline, binding the parameters it carries.
@@ -1094,6 +1548,9 @@ var BaseDialect = class _BaseDialect {
     const token = expr.expression;
     if (typeof token === "string") return renderPortableToken(token, this.name);
     if ("raw" in token) return token.raw;
+    if ("excluded" in token) {
+      return renderExcluded(this.quoteId(token.excluded), token.excluded, this.name);
+    }
     const parts = token.parts;
     let sql2 = parts[0] ?? "";
     for (let i = 1; i < parts.length; i++) {
@@ -1103,7 +1560,29 @@ var BaseDialect = class _BaseDialect {
   }
   /** Render one write value: a SQL expression inline, anything else as a parameter. */
   renderValue(value, params) {
-    return isSqlExpression(value) ? this.renderExpression(value, params) : params.bind(value);
+    if (isSqlExpression(value)) return this.renderExpression(value, params);
+    if (isExpression(value)) {
+      return this.renderExpr(value.node, params, (k) => this.columnId(k, void 0));
+    }
+    return params.bind(value);
+  }
+  /**
+   * The statements that open a transaction with the requested characteristics.
+   *
+   * Returned as a list because the dialects disagree on shape: PostgreSQL takes
+   * everything on the `BEGIN` itself, MySQL needs a separate `SET TRANSACTION`
+   * before it, and SQLite has no syntax at all.
+   *
+   * @param options The requested isolation level and read-only flag.
+   * @returns The statements to run, in order.
+   * @throws Error When the dialect cannot honor what was asked.
+   */
+  beginStatements(options) {
+    const parts = ["BEGIN"];
+    if (options?.isolation)
+      parts.push(`ISOLATION LEVEL ${options.isolation.toUpperCase()}`);
+    if (options?.readOnly) parts.push("READ ONLY");
+    return [parts.join(" ")];
   }
   /**
    * Render a row-level locking clause (`FOR UPDATE ...`).
@@ -1139,18 +1618,24 @@ var BaseDialect = class _BaseDialect {
     if (node.aggregates.length > 0) {
       const groupSel = node.groupBy.map((c) => this.columnId(c, names));
       const aggSel = node.aggregates.map((a) => {
-        const inner = a.column === "*" ? "*" : this.columnId(a.column, names);
+        const inner = this.aggregateOperand(a, params, names);
         return `${a.fn.toUpperCase()}(${inner}) AS ${this.quoteId(a.alias)}`;
       });
       cols = [...groupSel, ...aggSel].join(", ");
     } else {
       cols = node.columns === "*" ? "*" : node.columns.map((c) => this.columnId(c, names)).join(", ");
     }
-    let sql2 = `SELECT ${node.distinct ? "DISTINCT " : ""}${cols} FROM ${this.quoteId(node.table)}`;
+    const computed = Object.entries(node.computed ?? {}).map(
+      ([alias, expr]) => `${this.renderExpr(expr, params, (k) => this.columnId(k, names))} AS ${this.quoteId(alias)}`
+    );
+    if (computed.length > 0) cols = [cols, ...computed].join(", ");
+    const from = node.alias ? `${this.quoteId(node.table)} AS ${this.quoteId(node.alias)}` : this.quoteId(node.table);
+    let sql2 = `${this.compileWith(node.with, params)}SELECT ${node.distinct ? "DISTINCT " : ""}${cols} FROM ${from}`;
     const where = this.compileCondition(
       node.where,
       params,
-      (k) => this.columnId(k, names)
+      (k) => this.columnId(k, names),
+      codecEncoder(node.codecs)
     );
     if (where) sql2 += ` WHERE ${where}`;
     if (node.groupBy.length > 0) {
@@ -1161,14 +1646,14 @@ var BaseDialect = class _BaseDialect {
       const having = this.compileCondition(node.having, params, (key) => {
         const agg = aggByAlias.get(key);
         if (!agg) return this.columnId(key, names);
-        const inner = agg.column === "*" ? "*" : this.columnId(agg.column, names);
+        const inner = this.aggregateOperand(agg, params, names);
         return `${agg.fn.toUpperCase()}(${inner})`;
       });
       if (having) sql2 += ` HAVING ${having}`;
     }
     if (node.orderBy.length > 0) {
       const terms = node.orderBy.map((t) => {
-        const id = aggByAlias.has(t.column) ? this.quoteId(t.column) : this.columnId(t.column, names);
+        const id = typeof t.column !== "string" ? this.renderExpr(t.column, params, (k) => this.columnId(k, names)) : aggByAlias.has(t.column) ? this.quoteId(t.column) : this.columnId(t.column, names);
         return `${id} ${t.direction === "desc" ? "DESC" : "ASC"}`;
       }).join(", ");
       sql2 += ` ORDER BY ${terms}`;
@@ -1194,6 +1679,13 @@ var BaseDialect = class _BaseDialect {
    * SQL order, so placeholder positions stay correct.
    */
   compileInsert(node, params) {
+    if (node.fromSelect) {
+      const target = node.fromSelect.columns.map((c) => this.columnId(c, node.names)).join(", ");
+      const source = node.fromSelect.select;
+      const query = source.kind === "join_select" ? this.compileJoin(source, params) : source.kind === "set_op" ? this.compileSetOp(source, params) : this.compileSelect(source, params);
+      const returning = this.compileReturning(node.returning, node.names);
+      return `INSERT INTO ${this.quoteId(node.table)} (${target}) ${query}${returning}`;
+    }
     const columns = insertColumns(node.values);
     const conflict = node.onConflict;
     const cacheable = conflict?.targetWhere === void 0 && conflict?.updateWhere === void 0 && !insertHasExpression(node);
@@ -1309,10 +1801,12 @@ var BaseDialect = class _BaseDialect {
       ([col2, value]) => `${this.columnId(col2, names)} = ${this.renderValue(value, params)}`
     ).join(", ");
     let sql2 = `UPDATE ${this.quoteId(node.table)} SET ${sets}`;
+    sql2 += this.compileExtraSources("FROM", node.from);
     const where = this.compileCondition(
       node.where,
       params,
-      (k) => this.columnId(k, names)
+      (k) => this.columnId(k, names),
+      codecEncoder(node.codecs)
     );
     if (where) sql2 += ` WHERE ${where}`;
     sql2 += this.compileReturning(node.returning, names);
@@ -1321,10 +1815,12 @@ var BaseDialect = class _BaseDialect {
   compileDelete(node, params) {
     const names = node.names;
     let sql2 = `DELETE FROM ${this.quoteId(node.table)}`;
+    sql2 += this.compileExtraSources("USING", node.using);
     const where = this.compileCondition(
       node.where,
       params,
-      (k) => this.columnId(k, names)
+      (k) => this.columnId(k, names),
+      codecEncoder(node.codecs)
     );
     if (where) sql2 += ` WHERE ${where}`;
     sql2 += this.compileReturning(node.returning, names);
@@ -1334,9 +1830,10 @@ var BaseDialect = class _BaseDialect {
     const names = node.names;
     const cols = node.selections.map((s) => {
       const ref = `${s.alias}.${s.column}`;
-      return `${this.qualify(ref, names)} AS ${this.quoteId(ref)}`;
+      const label = node.pick ? s.column : ref;
+      return `${this.qualify(ref, names)} AS ${this.quoteId(label)}`;
     }).join(", ");
-    let sql2 = `SELECT ${cols} FROM ${this.quoteId(node.base.table)} AS ${this.quoteId(node.base.alias)}`;
+    let sql2 = `${this.compileWith(node.with, params)}SELECT ${cols} FROM ${this.quoteId(node.base.table)} AS ${this.quoteId(node.base.alias)}`;
     for (const j of node.joins) {
       const kw = j.kind === "left" ? "LEFT JOIN" : "INNER JOIN";
       const on = j.on.map(([l, r]) => `${this.qualify(l, names)} = ${this.qualify(r, names)}`).join(" AND ");
@@ -1359,6 +1856,22 @@ var BaseDialect = class _BaseDialect {
     return sql2;
   }
   // ---- clauses ----------------------------------------------------------
+  /**
+   * Render the extra sources of an `UPDATE ... FROM` / `DELETE ... USING`.
+   *
+   * The dialects that do not have the clause override this and throw: emitting it
+   * anyway would produce a statement the server rejects, and quietly dropping it
+   * would change which rows are written.
+   *
+   * @param keyword `FROM` or `USING`.
+   * @param sources The extra tables, if any.
+   * @returns The clause with a leading space, or an empty string.
+   */
+  compileExtraSources(keyword, sources) {
+    if (!sources || sources.length === 0) return "";
+    const list = sources.map((s) => `${this.quoteId(s.table)} AS ${this.quoteId(s.alias)}`).join(", ");
+    return ` ${keyword} ${list}`;
+  }
   compileReturning(returning, names) {
     if (returning === null) return "";
     if (returning === "*") return " RETURNING *";
@@ -1369,20 +1882,40 @@ var BaseDialect = class _BaseDialect {
    * key to a quoted identifier — `quoteId` for single-table, `qualify` for joins —
    * so select/update/delete/join all share this one compiler.
    */
-  compileCondition(node, params, idFor) {
+  compileCondition(node, params, idFor, encode = (_key, value) => value) {
     if (!node) return "";
     switch (node.kind) {
       case "fields": {
         const conditions = [];
         for (const [key, value] of Object.entries(node.fields)) {
           const id = idFor(key);
-          if (isOperatorObject(value)) {
+          if (isExpression(value)) {
+            conditions.push(
+              this.compileExprOperator(
+                id,
+                "eq",
+                this.renderExpr(value.node, params, idFor)
+              )
+            );
+          } else if (isOperatorObject(value)) {
             for (const [op, operand] of Object.entries(value)) {
-              conditions.push(this.compileOperator(id, op, operand, params));
+              conditions.push(
+                isExpression(operand) ? this.compileExprOperator(
+                  id,
+                  op,
+                  this.renderExpr(operand.node, params, idFor)
+                ) : this.compileOperator(
+                  id,
+                  op,
+                  encodeOperand(op, operand, (v) => encode(key, v)),
+                  params
+                )
+              );
             }
           } else {
+            const operand = encode(key, value);
             conditions.push(
-              value === null ? `${id} IS NULL` : `${id} = ${params.bind(value)}`
+              operand === null ? `${id} IS NULL` : `${id} = ${params.bind(operand)}`
             );
           }
         }
@@ -1390,15 +1923,23 @@ var BaseDialect = class _BaseDialect {
       }
       case "and":
       case "or": {
-        const parts = node.parts.map((p) => this.compileCondition(p, params, idFor)).filter((s) => s.length > 0);
+        const parts = node.parts.map((p) => this.compileCondition(p, params, idFor, encode)).filter((s) => s.length > 0);
         if (parts.length === 0) return "";
         const sep = node.kind === "and" ? " AND " : " OR ";
         return parts.map((p) => `(${p})`).join(sep);
       }
       case "not": {
-        const inner = this.compileCondition(node.part, params, idFor);
+        const inner = this.compileCondition(node.part, params, idFor, encode);
         return inner ? `NOT (${inner})` : "";
       }
+      case "exists": {
+        const select2 = node.select;
+        this.checkSubquery(select2);
+        const keyword = node.negate ? "NOT EXISTS" : "EXISTS";
+        return `${keyword} (${this.compileSelect(select2, params)})`;
+      }
+      case "fullText":
+        return this.compileFullText(node, params, idFor);
       case "compare": {
         const left = this.renderExpr(node.left, params, idFor);
         if (node.right.kind === "value") {
@@ -1412,6 +1953,22 @@ var BaseDialect = class _BaseDialect {
       }
     }
   }
+  /**
+   * Compile a full-text condition.
+   *
+   * PostgreSQL gets the real thing (`@@ websearch_to_tsquery`); the dialects with
+   * no text-search engine override this and compile the node's prebuilt substring
+   * fallback instead, so the query still returns the right rows.
+   *
+   * @param node The full-text condition node.
+   * @param params The parameter collector.
+   * @param idFor Column-name resolver.
+   * @returns The rendered condition.
+   */
+  compileFullText(node, params, idFor) {
+    const config = params.bind(node.language);
+    return `${this.tsVector(node.columns, config, idFor)} @@ websearch_to_tsquery(${config}::regconfig, ${params.bind(node.term)})`;
+  }
   /**
    * Render one side of a comparison.
    *
@@ -1424,6 +1981,23 @@ var BaseDialect = class _BaseDialect {
    * @param idFor The identifier resolver for the enclosing statement.
    * @returns The SQL text of the expression.
    */
+  /**
+   * Render what an aggregate is applied to: `*`, a column, or an expression.
+   *
+   * An expression operand is what makes a conditional aggregate
+   * (`SUM(CASE WHEN ... END)`) expressible — one pass over the table instead of a
+   * query per bucket.
+   *
+   * @param agg The aggregate term.
+   * @param params The parameter collector.
+   * @param names The node's column-name map.
+   * @returns The rendered operand.
+   */
+  aggregateOperand(agg, params, names) {
+    if (agg.column === "*") return "*";
+    if (typeof agg.column === "string") return this.columnId(agg.column, names);
+    return this.renderExpr(agg.column, params, (k) => this.columnId(k, names));
+  }
   renderExpr(node, params, idFor) {
     switch (node.kind) {
       case "column":
@@ -1434,6 +2008,109 @@ var BaseDialect = class _BaseDialect {
         const args = node.args.map((a) => this.renderExpr(a, params, idFor)).join(", ");
         return `${node.name}(${args})`;
       }
+      case "case": {
+        const branches = node.branches.map(
+          (b) => `WHEN ${this.compileCondition(b.when, params, idFor)} THEN ${this.renderExpr(b.result, params, idFor)}`
+        ).join(" ");
+        const fallback = node.fallback === null ? "" : ` ELSE ${this.renderExpr(node.fallback, params, idFor)}`;
+        return `CASE ${branches}${fallback} END`;
+      }
+      case "cast":
+        return `CAST(${this.renderExpr(node.operand, params, idFor)} AS ${this.castTypeName(node.to)})`;
+      case "scalar": {
+        const select2 = node.select;
+        this.checkSubquery(select2);
+        return `(${this.compileSelect(select2, params)})`;
+      }
+      case "rank":
+        return this.renderRank(node.columns, node.term, node.language, params, idFor);
+      case "star":
+        return "*";
+      case "window": {
+        const call2 = this.renderExpr(node.fn, params, idFor);
+        const parts = [];
+        if (node.partitionBy.length > 0) {
+          parts.push(`PARTITION BY ${node.partitionBy.map(idFor).join(", ")}`);
+        }
+        if (node.orderBy.length > 0) {
+          const terms = node.orderBy.map((t) => `${idFor(t.column)} ${t.direction === "desc" ? "DESC" : "ASC"}`).join(", ");
+          parts.push(`ORDER BY ${terms}`);
+        }
+        if (node.frame) parts.push(node.frame);
+        return `${call2} OVER (${parts.join(" ")})`;
+      }
+    }
+  }
+  /**
+   * Render a full-text relevance score.
+   *
+   * PostgreSQL has `ts_rank`; the others have nothing equivalent, and they
+   * override this to a constant so that ordering by it is a no-op rather than a
+   * compile error — the fallback keeps returning the right rows, only unranked.
+   *
+   * @param columns The columns making up the document.
+   * @param term The search term.
+   * @param language The text-search configuration.
+   * @param params The parameter collector.
+   * @param idFor Column-name resolver.
+   * @returns The rendered score expression.
+   */
+  renderRank(columns, term, language, params, idFor) {
+    const config = params.bind(language);
+    return `ts_rank(${this.tsVector(columns, config, idFor)}, websearch_to_tsquery(${config}::regconfig, ${params.bind(term)}))`;
+  }
+  /**
+   * Build the `to_tsvector(...)` document out of the searched columns.
+   *
+   * `coalesce(col, '')` matters: in SQL a `NULL` anywhere in a concatenation makes
+   * the whole document `NULL`, so one empty column would silently exclude the row.
+   *
+   * @param columns The columns making up the document.
+   * @param config The already-bound placeholder for the text-search config.
+   * @param idFor Column-name resolver.
+   * @returns The rendered `to_tsvector(...)` call.
+   */
+  tsVector(columns, config, idFor) {
+    const document = columns.map((c) => `coalesce(${idFor(c)}, '')`).join(" || ' ' || ");
+    return `to_tsvector(${config}::regconfig, ${document})`;
+  }
+  /**
+   * The SQL type name this dialect accepts in a `CAST`.
+   *
+   * The base mapping is the standard one PostgreSQL takes; SQLite and MySQL
+   * override it, because the names genuinely differ (MySQL's `CAST(x AS SIGNED)`
+   * is not `INTEGER`, and SQLite only has five storage classes to aim at).
+   *
+   * @param to The portable cast target.
+   * @returns The dialect's own type name.
+   */
+  castTypeName(to) {
+    switch (to) {
+      case "integer":
+        return "INTEGER";
+      case "bigint":
+        return "BIGINT";
+      case "real":
+        return "DOUBLE PRECISION";
+      case "numeric":
+        return "NUMERIC";
+      case "text":
+        return "TEXT";
+      case "boolean":
+        return "BOOLEAN";
+      case "date":
+        return "DATE";
+      case "datetime":
+      case "timestamp":
+        return "TIMESTAMP";
+      case "uuid":
+        return "UUID";
+      case "json":
+        return "JSON";
+      case "jsonb":
+        return "JSONB";
+      case "blob":
+        return "BYTEA";
     }
   }
   /**
@@ -1470,6 +2147,10 @@ var BaseDialect = class _BaseDialect {
         return this.ilike(left, right);
       case "ieq":
         return `lower(${left}) = lower(${right})`;
+      case "iContains":
+        throw new Error(
+          'The "iContains" operator matches a literal, so it takes a value, not an expression.'
+        );
       case "contains":
       case "containedBy":
       case "overlaps":
@@ -1498,6 +2179,8 @@ var BaseDialect = class _BaseDialect {
         return this.ilike(id, params.bind(operand));
       case "ieq":
         return operand === null ? `${id} IS NULL` : `lower(${id}) = lower(${params.bind(operand)})`;
+      case "iContains":
+        return this.ilikeEscaped(id, params.bind(`%${escapeLike(String(operand))}%`));
       case "contains":
         return `${id} ${this.arrayOperator("contains")} ${params.bind(operand)}`;
       case "containedBy":
@@ -1549,12 +2232,93 @@ var BaseDialect = class _BaseDialect {
 };
 var SqliteDialect = class extends BaseDialect {
   name = "sqlite";
+  /**
+   * SQLite explains with `EXPLAIN QUERY PLAN`, and has no `ANALYZE` — the plain
+   * `EXPLAIN` there dumps bytecode, which answers a different question.
+   */
+  explainPrefix(analyze) {
+    if (analyze) {
+      throw new Error(
+        "SQLite has no EXPLAIN ANALYZE; use EXPLAIN QUERY PLAN (analyze: false)."
+      );
+    }
+    return "EXPLAIN QUERY PLAN";
+  }
+  /**
+   * SQLite has `UPDATE ... FROM` (3.33+) but no `DELETE ... USING`.
+   *
+   * The portable shape there is a subquery — `where({ id: { in: … } })` — so this
+   * throws and says so, rather than emitting a clause SQLite does not parse.
+   */
+  compileExtraSources(keyword, sources) {
+    if (keyword === "USING" && sources && sources.length > 0) {
+      throw new Error(
+        'SQLite has no DELETE ... USING; filter with a subquery instead: where({ id: { in: select(Other, ["id"]).asSubquery("id") } }).'
+      );
+    }
+    return super.compileExtraSources(keyword, sources);
+  }
+  /**
+   * SQLite has no text-search engine, so the prebuilt substring fallback is
+   * compiled instead. The rows are right; the ranking is what is missing.
+   */
+  compileFullText(node, params, idFor) {
+    return this.compileCondition(node.fallback, params, idFor);
+  }
+  /** No text-search engine means no score: a constant, so ordering by it is inert. */
+  renderRank() {
+    return "0";
+  }
+  /**
+   * SQLite has five storage classes, so most targets collapse onto `TEXT` or
+   * `INTEGER`. Naming a type it does not know would not fail — SQLite applies the
+   * closest affinity — but it would make the cast mean something different here
+   * than on the other databases, which is what this mapping avoids.
+   */
+  castTypeName(to) {
+    switch (to) {
+      case "integer":
+      case "bigint":
+      case "boolean":
+        return "INTEGER";
+      case "real":
+        return "REAL";
+      case "numeric":
+        return "NUMERIC";
+      case "blob":
+        return "BLOB";
+      default:
+        return "TEXT";
+    }
+  }
   placeholder() {
     return "?";
   }
   ilike(column2, param) {
     return `${column2} LIKE ${param}`;
   }
+  /**
+   * SQLite runs one writer at a time, so its only isolation level **is**
+   * serializable — there is no syntax to ask for another, and no weaker level to
+   * fall back to. Asking for one is an error rather than a silent no-op, since a
+   * caller who wrote `repeatable read` was reasoning about a guarantee.
+   *
+   * `readOnly` likewise has no per-transaction form here (`PRAGMA query_only` is
+   * per connection), so it is refused instead of quietly ignored.
+   */
+  beginStatements(options) {
+    if (options?.isolation && options.isolation !== "serializable") {
+      throw new Error(
+        `SQLite only implements the "serializable" isolation level; ${JSON.stringify(options.isolation)} has no equivalent here.`
+      );
+    }
+    if (options?.readOnly) {
+      throw new Error(
+        "SQLite has no read-only transaction; open the engine with { sqlite: { ... } } on a read-only connection instead."
+      );
+    }
+    return ["BEGIN"];
+  }
   /**
    * SQLite has no row-level locking, so a lock request is an error rather than a
    * silently unlocked `SELECT` — a lock that does not exist only shows up as
@@ -1568,8 +2332,8 @@ var SqliteDialect = class extends BaseDialect {
 };
 var PostgresDialect = class extends BaseDialect {
   name = "postgresql";
-  placeholder(index) {
-    return `$${index}`;
+  placeholder(index2) {
+    return `$${index2}`;
   }
   ilike(column2, param) {
     return `${column2} ILIKE ${param}`;
@@ -1589,30 +2353,114 @@ var MysqlDialect = class extends BaseDialect {
   ilike(column2, param) {
     return `${column2} LIKE ${param}`;
   }
-  quoteId(name) {
-    const cached = mysqlQuotedIds.get(name);
-    if (cached !== void 0) return cached;
-    const quoted = `\`${name.replace(/`/g, "``")}\``;
-    mysqlQuotedIds.set(name, quoted);
-    return quoted;
+  /** MySQL's `EXPLAIN FORMAT=JSON` spells the option differently. */
+  explainPrefix(analyze) {
+    return analyze ? "EXPLAIN ANALYZE" : "EXPLAIN FORMAT=JSON";
   }
   /**
-   * MySQL rejects `LIMIT` inside an `IN` subquery with
-   * `ER_NOT_SUPPORTED_YET: This version of MySQL doesn't yet support
-   * 'LIMIT & IN/ALL/ANY/SOME subquery'`. Failing at compile time names the fix
-   * instead of surfacing that error from the driver at runtime.
+   * MySQL only gained `INTERSECT`/`EXCEPT` in 8.0.31, and this project does not
+   * invest in MySQL beyond what already works — so they are refused here rather
+   * than emitted against a server that may reject them.
    */
-  checkSubquery(node) {
-    if (node.limit !== void 0 || node.offset !== void 0) {
+  setOperator(op) {
+    if (op === "intersect" || op === "except") {
       throw new Error(
-        "MySQL does not support LIMIT/OFFSET inside an IN subquery. Select the ids first and pass them as a list, or wrap the subquery in a derived table."
+        `MySQL support for ${op.toUpperCase()} is out of scope for tempest-db-js; express it with a join or NOT EXISTS.`
       );
     }
+    return super.setOperator(op);
   }
-  renderConflict(onConflict, conflictCols, nextValue, names) {
-    if (onConflict.targetWhere || onConflict.updateWhere) {
+  /**
+   * MySQL writes multi-table updates as `UPDATE a JOIN b`, and has no
+   * `DELETE ... USING` in this shape. Both are out of the project's active scope,
+   * so they are refused rather than emitted against a server that rejects them.
+   */
+  compileExtraSources(keyword, sources) {
+    if (sources && sources.length > 0) {
       throw new Error(
-        "MySQL's ON DUPLICATE KEY UPDATE has no conflict-target predicate \u2014 a partial unique index is PostgreSQL/SQLite only."
+        `MySQL does not take ${keyword} on a write in this form; it spells multi-table writes as UPDATE a JOIN b, which is out of scope for tempest-db-js.`
+      );
+    }
+    return "";
+  }
+  /**
+   * MySQL's full-text search needs a `FULLTEXT` index and different syntax, and it
+   * is outside this project's active scope — the substring fallback is compiled,
+   * like on SQLite.
+   */
+  compileFullText(node, params, idFor) {
+    return this.compileCondition(node.fallback, params, idFor);
+  }
+  /** No `ts_rank` equivalent in scope: a constant, so ordering by it is inert. */
+  renderRank() {
+    return "0";
+  }
+  /**
+   * MySQL sets the level with a statement **before** the transaction opens, and
+   * spells the read-only flag on `START TRANSACTION` rather than on `BEGIN`.
+   */
+  beginStatements(options) {
+    const statements = [];
+    if (options?.isolation) {
+      statements.push(
+        `SET TRANSACTION ISOLATION LEVEL ${options.isolation.toUpperCase()}`
+      );
+    }
+    statements.push(options?.readOnly ? "START TRANSACTION READ ONLY" : "BEGIN");
+    return statements;
+  }
+  /**
+   * MySQL's `CAST` takes its own vocabulary — `SIGNED`, not `INTEGER`; `CHAR`,
+   * not `TEXT` — and rejects the standard names outright.
+   */
+  castTypeName(to) {
+    switch (to) {
+      case "integer":
+      case "bigint":
+      case "boolean":
+        return "SIGNED";
+      case "real":
+      case "numeric":
+        return "DECIMAL";
+      case "text":
+      case "uuid":
+        return "CHAR";
+      case "date":
+        return "DATE";
+      case "datetime":
+      case "timestamp":
+        return "DATETIME";
+      case "json":
+      case "jsonb":
+        return "JSON";
+      case "blob":
+        return "BINARY";
+    }
+  }
+  quoteId(name) {
+    const cached = mysqlQuotedIds.get(name);
+    if (cached !== void 0) return cached;
+    const quoted = `\`${name.replace(/`/g, "``")}\``;
+    mysqlQuotedIds.set(name, quoted);
+    return quoted;
+  }
+  /**
+   * MySQL rejects `LIMIT` inside an `IN` subquery with
+   * `ER_NOT_SUPPORTED_YET: This version of MySQL doesn't yet support
+   * 'LIMIT & IN/ALL/ANY/SOME subquery'`. Failing at compile time names the fix
+   * instead of surfacing that error from the driver at runtime.
+   */
+  checkSubquery(node) {
+    if (node.limit !== void 0 || node.offset !== void 0) {
+      throw new Error(
+        "MySQL does not support LIMIT/OFFSET inside an IN subquery. Select the ids first and pass them as a list, or wrap the subquery in a derived table."
+      );
+    }
+  }
+  renderConflict(onConflict, conflictCols, nextValue, names) {
+    if (onConflict.targetWhere || onConflict.updateWhere) {
+      throw new Error(
+        "MySQL's ON DUPLICATE KEY UPDATE has no conflict-target predicate \u2014 a partial unique index is PostgreSQL/SQLite only."
       );
     }
     if (onConflict.update === "nothing") {
@@ -1679,7 +2527,7 @@ var JoinBuilder = class _JoinBuilder {
   clause(kind, model, alias, on) {
     return {
       kind,
-      table: model.tablename,
+      table: aliasOf(model)?.tablename ?? model.tablename,
       alias,
       on: Object.entries(on)
     };
@@ -1698,6 +2546,38 @@ var JoinBuilder = class _JoinBuilder {
       model
     );
   }
+  /**
+   * Project **one** source, flat, instead of the composite row.
+   *
+   * The join still happens — it just stops being what comes back. Needed wherever
+   * the result has to match a single table's shape: the recursive branch of a
+   * CTE, an `INSERT ... SELECT`, a `UNION` branch.
+   *
+   * @param alias The source to project.
+   * @returns A builder whose rows are that source's rows.
+   *
+   * @example
+   * ```ts
+   * join(Category, "c").innerJoin(subtree, "s", { "c.parentId": "s.id" }).pick("c");
+   * // SELECT "c"."id" AS "id", "c"."name" AS "name" ... — not "c.id"
+   * ```
+   */
+  pick(alias) {
+    const model = this.sources[alias];
+    if (!model) {
+      throw new Error(
+        `pick(${JSON.stringify(alias)}): no source is joined under that alias.`
+      );
+    }
+    return new _JoinBuilder(
+      {
+        ...this.node,
+        selections: selectionsFor(alias, model),
+        pick: alias
+      },
+      this.sources
+    );
+  }
   /** Filter by `alias.column` references (object form) or an `and`/`or`/`not`. */
   where(input) {
     return new _JoinBuilder(
@@ -1726,7 +2606,7 @@ function join(model, alias) {
   return new JoinBuilder(
     {
       kind: "join_select",
-      base: { table: model.tablename, alias },
+      base: { table: aliasOf(model)?.tablename ?? model.tablename, alias },
       joins: [],
       selections: selectionsFor(alias, model),
       where: void 0,
@@ -1739,46 +2619,388 @@ function join(model, alias) {
   );
 }
 
+// src/mixins.ts
+function withTimestamps(Base) {
+  class WithTimestamps extends Base {
+    /** When the row was inserted. */
+    createdAt = column.datetime().notNull().default(sql.now());
+    /** When the row was last updated — refreshed by every `UPDATE`. */
+    updatedAt = column.datetime().notNull().default(sql.now()).onUpdate(sql.now());
+  }
+  return WithTimestamps;
+}
+function withSoftDelete(Base) {
+  class WithSoftDelete extends Base {
+    /** When the row was soft-deleted, or `null` while it is alive. */
+    deletedAt = column.datetime();
+  }
+  return WithSoftDelete;
+}
+function notDeleted() {
+  return { deletedAt: { isNull: true } };
+}
+function onlyDeleted() {
+  return { deletedAt: { isNull: false } };
+}
+function withAudit(Base, actor = () => column.uuid()) {
+  class WithAudit extends Base {
+    /** Who created the row, or `null` when nobody was attributed. */
+    createdBy = actor();
+    /** Who last updated the row, or `null`. */
+    updatedBy = actor();
+  }
+  return WithAudit;
+}
+
+// src/integrity.ts
+var POSTGRES_VIOLATIONS = {
+  "23505": "unique",
+  "23503": "foreignKey",
+  "23502": "notNull",
+  "23514": "check",
+  "23P01": "exclusion"
+};
+var SQLITE_ERRCODES = {
+  1555: "unique",
+  // SQLITE_CONSTRAINT_PRIMARYKEY
+  2067: "unique",
+  // SQLITE_CONSTRAINT_UNIQUE
+  787: "foreignKey",
+  // SQLITE_CONSTRAINT_FOREIGNKEY
+  1299: "notNull",
+  // SQLITE_CONSTRAINT_NOTNULL
+  275: "check"
+  // SQLITE_CONSTRAINT_CHECK
+};
+var SQLITE_CODES = {
+  SQLITE_CONSTRAINT_PRIMARYKEY: "unique",
+  SQLITE_CONSTRAINT_UNIQUE: "unique",
+  SQLITE_CONSTRAINT_FOREIGNKEY: "foreignKey",
+  SQLITE_CONSTRAINT_NOTNULL: "notNull",
+  SQLITE_CONSTRAINT_CHECK: "check"
+};
+function str(error, key) {
+  const value = error[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function postgresDetailColumns(detail) {
+  if (!detail) return [];
+  const match = /Key \(([^)]+)\)=/.exec(detail);
+  if (!match?.[1]) return [];
+  return match[1].split(",").map((c) => c.trim().replace(/^"|"$/g, ""));
+}
+function sqliteTargets(list) {
+  const columns = [];
+  let table = null;
+  for (const entry of list.split(",")) {
+    const [left, right] = entry.trim().split(".");
+    if (right === void 0) {
+      if (left) columns.push(left);
+      continue;
+    }
+    table = left ?? null;
+    columns.push(right);
+  }
+  return { table, columns };
+}
+function fromPostgres(error) {
+  const code = str(error, "code");
+  const violation = code ? POSTGRES_VIOLATIONS[code] : void 0;
+  if (!violation) return null;
+  const detail = str(error, "detail");
+  const columns = postgresDetailColumns(detail);
+  const column2 = str(error, "column_name");
+  return {
+    violation,
+    constraint: str(error, "constraint_name"),
+    table: str(error, "table_name"),
+    columns: columns.length > 0 ? columns : column2 ? [column2] : [],
+    detail: str(error, "message") ?? detail ?? ""
+  };
+}
+function fromSqlite(error) {
+  const code = str(error, "code");
+  const errcode = error.errcode;
+  const violation = (code ? SQLITE_CODES[code] : void 0) ?? (typeof errcode === "number" ? SQLITE_ERRCODES[errcode] : void 0);
+  if (!violation) return null;
+  const message = str(error, "message") ?? "";
+  if (violation === "check") {
+    const named = /CHECK constraint failed: (.+)$/.exec(message);
+    return {
+      violation,
+      constraint: named?.[1] ?? null,
+      table: null,
+      columns: [],
+      detail: message
+    };
+  }
+  const targets = /constraint failed: (.+)$/.exec(message);
+  if (!targets?.[1]) {
+    return { violation, constraint: null, table: null, columns: [], detail: message };
+  }
+  const { table, columns } = sqliteTargets(targets[1]);
+  return { violation, constraint: null, table, columns, detail: message };
+}
+function parseIntegrityError(error, model) {
+  let current = error;
+  for (let depth = 0; depth < 5 && current !== null && current !== void 0; depth++) {
+    if (typeof current === "object") {
+      const record = current;
+      const failure = fromPostgres(record) ?? fromSqlite(record);
+      if (failure) return model ? withModelNames(failure, model) : failure;
+      current = record.cause;
+      continue;
+    }
+    return null;
+  }
+  return null;
+}
+function withModelNames(failure, model) {
+  const props = columnPropsOf(model);
+  if (!props || failure.columns.length === 0) return failure;
+  return { ...failure, columns: failure.columns.map((c) => props[c] ?? c) };
+}
+
+// src/signals.ts
+var registry = /* @__PURE__ */ new WeakMap();
+var registered = /* @__PURE__ */ new Set();
+function onSignal(model, signal, handler) {
+  let bySignal = registry.get(model);
+  if (!bySignal) {
+    bySignal = /* @__PURE__ */ new Map();
+    registry.set(model, bySignal);
+    registered.add(model);
+  }
+  let handlers = bySignal.get(signal);
+  if (!handlers) {
+    handlers = /* @__PURE__ */ new Set();
+    bySignal.set(signal, handlers);
+  }
+  handlers.add(handler);
+  return () => {
+    handlers?.delete(handler);
+  };
+}
+function hasHandlers(model, signal) {
+  return (registry.get(model)?.get(signal)?.size ?? 0) > 0;
+}
+async function emitSignal(signal, payload) {
+  const handlers = registry.get(payload.model)?.get(signal);
+  if (!handlers || handlers.size === 0) return;
+  for (const handler of [...handlers]) {
+    await handler(payload);
+  }
+}
+function clearSignals(model) {
+  if (model) {
+    registry.delete(model);
+    registered.delete(model);
+    return;
+  }
+  for (const registeredModel of registered) registry.delete(registeredModel);
+  registered.clear();
+}
+
+// src/setops.ts
+var SetBuilder = class _SetBuilder {
+  constructor(node, source) {
+    this.node = node;
+    this.source = source;
+  }
+  node;
+  source;
+  with(patch) {
+    return new _SetBuilder({ ...this.node, ...patch }, this.source);
+  }
+  /**
+   * Order the combined result.
+   *
+   * @param column A column of the projected row.
+   * @param direction Sort direction (default ascending).
+   * @returns A builder carrying the ordering.
+   */
+  orderBy(column2, direction = "asc") {
+    return this.with({ orderBy: [...this.node.orderBy, { column: column2, direction }] });
+  }
+  /** Limit the combined result. */
+  limit(count2) {
+    return this.with({ limit: count2 });
+  }
+  /** Skip rows of the combined result. */
+  offset(count2) {
+    return this.with({ offset: count2 });
+  }
+};
+function branchSource(branch) {
+  if (branch.source) return branch.source;
+  const pick = branch.node.pick;
+  return pick ? branch.sources?.[pick] : void 0;
+}
+function combine(op, branches) {
+  if (branches.length < 2) {
+    throw new Error(`${op}() combines at least two queries.`);
+  }
+  const first = branches[0];
+  const source = branchSource(first);
+  if (!source) {
+    throw new Error(
+      `${op}(): the first branch must project a single source \u2014 narrow a join with .pick(alias).`
+    );
+  }
+  return new SetBuilder(
+    {
+      kind: "set_op",
+      op,
+      branches: branches.map((b) => b.node),
+      orderBy: [],
+      limit: void 0,
+      offset: void 0
+    },
+    source
+  );
+}
+function union(...branches) {
+  return combine("union", branches);
+}
+function unionAll(...branches) {
+  return combine("unionAll", branches);
+}
+function intersect(...branches) {
+  return combine("intersect", branches);
+}
+function except(...branches) {
+  return combine("except", branches);
+}
+
 // src/repository.ts
-var RecordNotFound = class extends Error {
-  constructor(table, id) {
-    super(`${table} not found for id ${JSON.stringify(id)}`);
-    this.name = "RecordNotFound";
+var InvalidCursor = class extends Error {
+  constructor(reason) {
+    super(`Invalid pagination cursor: ${reason}`);
+    this.name = "InvalidCursor";
   }
 };
-function primaryKeyOf(model) {
-  for (const [name, col2] of Object.entries(columnsOf(model))) {
-    if (col2.flags.primaryKey) return name;
+function encodeCursor(columns, keys, row) {
+  const k = {};
+  for (const key of keys) {
+    k[key] = encodeValue(columns[key], row[key]);
+  }
+  const payload = { v: 1, k };
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+function decodeCursor(columns, keys, cursor) {
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+  } catch {
+    throw new InvalidCursor("not a cursor this repository produced");
+  }
+  if (payload === null || typeof payload !== "object" || payload.v !== 1) {
+    throw new InvalidCursor("unknown cursor version");
+  }
+  const values = {};
+  for (const key of keys) {
+    if (!(key in payload.k)) {
+      throw new InvalidCursor(
+        `it does not carry ${JSON.stringify(key)} \u2014 the ordering changed between pages`
+      );
+    }
+    values[key] = decodeValue(columns[key], payload.k[key]);
   }
-  throw new Error(`${model.tablename} has no primary key`);
+  return values;
 }
+function afterCursor(keys, values, ascending) {
+  const op = ascending ? "gt" : "lt";
+  const build = (index2) => {
+    const key = keys[index2];
+    const strict = { [key]: { [op]: values[key] } };
+    if (index2 === keys.length - 1) return strict;
+    return or(
+      strict,
+      and({ [key]: values[key] }, build(index2 + 1))
+    );
+  };
+  return build(0);
+}
+var RecordNotFound = class extends Error {
+  constructor(table, key) {
+    super(`${table} not found for key ${JSON.stringify(key)}`);
+    this.name = "RecordNotFound";
+  }
+};
 var BaseRepository = class {
   constructor(model, session) {
     this.model = model;
     this.session = session;
-    this.pk = primaryKeyOf(model);
+    this.pks = primaryKeysOf(model);
   }
   model;
   session;
-  pk;
+  pks;
+  /**
+   * Narrow every read this repository performs.
+   *
+   * The extension point a scoped repository overrides: returning a filter that
+   * always carries the scope's predicate is what makes it impossible for one
+   * query site to forget it. The base implementation adds nothing.
+   *
+   * @param filters The caller's filters.
+   * @returns The filters actually sent to the database.
+   */
+  scopeFilters(filters) {
+    return filters;
+  }
+  /**
+   * Stamp every row this repository writes.
+   *
+   * The write-side counterpart of {@link scopeFilters}. The base implementation
+   * writes the row unchanged.
+   *
+   * @param data The row being written.
+   * @returns The row actually written.
+   */
+  scopeWrite(data) {
+    return data;
+  }
   /** All rows matching `filters` (or everything). Empty list when none match. */
-  async list(filters) {
+  async list(input) {
+    const filters = this.scopeFilters(input);
     const query = filters ? select(this.model).where(filters) : select(this.model);
     return this.session.execute(query).all();
   }
   /** The first row matching `filters`, or `null`. */
-  async first(filters) {
+  async first(input) {
+    const filters = this.scopeFilters(input);
     const query = filters ? select(this.model).where(filters) : select(this.model);
     return this.session.execute(query).first();
   }
-  /** A single row by primary key, or `null`. */
+  /**
+   * A single row by primary key, or `null`.
+   *
+   * @param id The key — a bare value for a single-column key, an object
+   *   (`{ orderId, lineNumber }`) for a composite one.
+   * @returns The row, or `null` when nothing matches.
+   * @throws Error When a scalar is given for a composite key, or the key is
+   *   incomplete.
+   */
   async getByIdOrNull(id) {
-    return this.session.execute(select(this.model).where({ [this.pk]: id })).first();
+    const filter = this.scopeFilters(
+      primaryKeyFilter(this.model, id)
+    );
+    return this.session.execute(select(this.model).where(filter)).first();
   }
-  /** A single row by primary key; throws `RecordNotFound` when absent. */
+  /**
+   * A single row by primary key; throws `RecordNotFound` when absent.
+   *
+   * @param id The key — see {@link getByIdOrNull}.
+   * @returns The row.
+   * @throws RecordNotFound When no row carries that key.
+   */
   async getById(id) {
-    const row = await this.getByIdOrNull(id);
-    if (row === null) throw new RecordNotFound(this.model.tablename, id);
+    const filter = this.scopeFilters(
+      primaryKeyFilter(this.model, id)
+    );
+    const row = await this.session.execute(select(this.model).where(filter)).first();
+    if (row === null) throw new RecordNotFound(this.model.tablename, filter);
     return row;
   }
   /** Whether any row matches `filters`. */
@@ -1786,199 +3008,905 @@ var BaseRepository = class {
     return await this.first(filters) !== null;
   }
   /** How many rows match `filters` (or the whole table). */
-  async count(filters) {
-    const query = filters ? select(this.model, [this.pk]).where(filters) : select(this.model, [this.pk]);
+  async count(input) {
+    const filters = this.scopeFilters(input);
+    const query = filters ? select(this.model, [this.pks[0]]).where(filters) : select(this.model, [this.pks[0]]);
     return (await this.session.execute(query).all()).length;
   }
-  /** Insert one row, returning the created row. */
+  /**
+   * Insert one row, returning the created row.
+   *
+   * Fires `preSave` (which can veto by throwing) and then `postSave`.
+   *
+   * @param data The row to insert.
+   * @returns The stored row.
+   */
   async create(data) {
-    return this.session.execute(insert(this.model).values(data).returning()).one();
+    const scoped = this.scopeWrite(data);
+    await this.fire("preSave", scoped, true);
+    const row = await this.session.execute(
+      insert(this.model).values(scoped).returning()
+    ).one();
+    await this.fire("postSave", row, true);
+    return row;
   }
-  /** Insert many rows, returning the created rows. */
+  /**
+   * Insert many rows, returning the created rows.
+   *
+   * Signals fire per row, so a handler sees one row at a time whether it was
+   * inserted alone or in a batch.
+   *
+   * @param data The rows to insert.
+   * @returns The stored rows.
+   */
   async createMany(data) {
     if (data.length === 0) return [];
-    return this.session.execute(insert(this.model).values(data).returning()).all();
+    const scoped = data.map(
+      (row) => this.scopeWrite(row)
+    );
+    for (const row of scoped) {
+      await this.fire("preSave", row, true);
+    }
+    const rows = await this.session.execute(
+      insert(this.model).values(scoped).returning()
+    ).all();
+    for (const row of rows) await this.fire("postSave", row, true);
+    return rows;
+  }
+  /**
+   * Update rows matching `filters`; returns the number of rows affected.
+   *
+   * With a `preSave`/`postSave` handler registered, the matching rows are read
+   * first so the handler can see them — that extra `SELECT` is skipped entirely
+   * when nothing is listening.
+   *
+   * @param filters Which rows to update.
+   * @param set The columns to change.
+   * @returns The number of rows affected.
+   */
+  async update(input, set) {
+    const filters = this.scopeFilters(input);
+    const listening = hasHandlers(this.model, "preSave") || hasHandlers(this.model, "postSave");
+    const before = listening ? await this.list(filters) : [];
+    for (const row of before) await this.fire("preSave", { ...row, ...set }, false);
+    const affected = await this.session.execute(update(this.model).set(set).where(filters)).rowsAffected();
+    if (hasHandlers(this.model, "postSave")) {
+      for (const row of await this.list(filters)) await this.fire("postSave", row, false);
+    }
+    return affected;
+  }
+  /**
+   * Delete rows matching `filters`; returns the number of rows affected.
+   *
+   * `preDelete` and `postDelete` receive the row as it was **before** the delete —
+   * the only chance to see it. Reading it costs a `SELECT`, which is skipped when
+   * no handler is registered.
+   *
+   * @param filters Which rows to delete.
+   * @returns The number of rows affected.
+   */
+  async delete(input) {
+    const filters = this.scopeFilters(input);
+    const listening = hasHandlers(this.model, "preDelete") || hasHandlers(this.model, "postDelete");
+    const doomed = listening ? await this.list(filters) : [];
+    for (const row of doomed) await this.fire("preDelete", row, false);
+    const affected = await this.session.execute(del(this.model).where(filters)).rowsAffected();
+    for (const row of doomed) await this.fire("postDelete", row, false);
+    return affected;
+  }
+  /**
+   * Fire one signal for one row on this repository's model and session.
+   *
+   * @param signal Which signal.
+   * @param row The row it is about.
+   * @param isInsert Whether the write was an insert.
+   */
+  async fire(signal, row, isInsert) {
+    await emitSignal(signal, {
+      row,
+      model: this.model,
+      session: this.session,
+      isInsert
+    });
+  }
+  /**
+   * A page of rows plus metadata. `total` counts all matching rows.
+   *
+   * @param filter Page, size, ordering and filters.
+   * @returns The page and pagination metadata.
+   */
+  async paginate(filter = {}) {
+    const page = Math.max(1, filter.page ?? 1);
+    const pageSize = Math.max(1, filter.pageSize ?? 20);
+    const where = this.scopeFilters(filter.filters);
+    let query = where ? select(this.model).where(where) : select(this.model);
+    if (filter.orderBy) {
+      query = query.orderBy(filter.orderBy, filter.ascending === false ? "desc" : "asc");
+    }
+    query = query.limit(pageSize).offset((page - 1) * pageSize);
+    const items = await this.session.execute(query).all();
+    const total = await this.count(where);
+    return {
+      items,
+      total,
+      page,
+      pageSize,
+      pages: Math.max(1, Math.ceil(total / pageSize))
+    };
+  }
+  /**
+   * A cursor-paginated page: the rows after `cursor`, plus the cursor for the
+   * next page.
+   *
+   * No `COUNT(*)` runs, and the page boundary is stable under concurrent inserts —
+   * the two reasons to reach for this instead of {@link paginate} on a large table.
+   * The trade-off is losing random access: there is no "page 7".
+   *
+   * The primary key is always appended as a tie-break, so rows sharing an
+   * `orderBy` value cannot be skipped or repeated across pages.
+   *
+   * @param filter Cursor, page size, ordering and filters.
+   * @returns The page and the next cursor (`null` on the last page).
+   * @throws InvalidCursor When the cursor is malformed or was built for a
+   *   different ordering.
+   */
+  async cursorPaginate(filter = {}) {
+    const limit = Math.max(1, Math.trunc(filter.limit ?? 20));
+    const ascending = filter.ascending === true;
+    const columns = columnsOf(this.model);
+    const primary = filter.orderBy ?? this.pks[0];
+    const keys = [primary, ...this.pks.filter((k) => k !== primary)];
+    const parts = [];
+    const scoped = this.scopeFilters(filter.filters);
+    if (scoped) parts.push(scoped);
+    if (filter.cursor) {
+      parts.push(
+        afterCursor(
+          keys,
+          decodeCursor(columns, keys, filter.cursor),
+          ascending
+        )
+      );
+    }
+    let query = parts.length === 0 ? select(this.model) : select(this.model).where(
+      parts.length === 1 ? parts[0] : and(...parts)
+    );
+    for (const key of keys) {
+      query = query.orderBy(
+        key,
+        ascending ? "asc" : "desc"
+      );
+    }
+    const rows = await this.session.execute(query.limit(limit + 1)).all();
+    const items = rows.slice(0, limit);
+    const last = items[items.length - 1];
+    return {
+      items,
+      nextCursor: rows.length > limit && last !== void 0 ? encodeCursor(columns, keys, last) : null
+    };
+  }
+  /**
+   * Whether any **other** row matches `filters`.
+   *
+   * The uniqueness check for an update: "is this e-mail taken by somebody else?"
+   * A plain `exists` would find the row being edited and report a false conflict.
+   *
+   * @param filters What to look for.
+   * @param key The primary key to exclude — the row being updated.
+   * @returns True when a different row matches.
+   */
+  async existsExcluding(filters, key) {
+    const excluded = primaryKeyFilter(this.model, key);
+    const condition = and(filters, not(excluded));
+    return await this.first(condition) !== null;
+  }
+  /**
+   * The rows that changed since a high-water mark — the delta-sync read.
+   *
+   * Rows come back oldest change first, tie-broken by primary key, so a client
+   * can advance its watermark monotonically and resume mid-stream with the
+   * cursor. The filter is **strict** (`updatedAt > since`).
+   *
+   * Soft-deleted rows are included on purpose: they are the tombstones that tell
+   * the client to delete its local copy. Filtering them out would strand deleted
+   * rows on the device forever.
+   *
+   * @param filter The watermark, cursor, page size and domain filters.
+   * @returns The page, plus the `serverTime` to persist as the next watermark.
+   * @throws Error When the model has no `updatedAt` column (see `withTimestamps`).
+   */
+  async changesSince(filter = {}) {
+    this.requireColumn("updatedAt", "changesSince");
+    const serverTime = /* @__PURE__ */ new Date();
+    const clauses = [];
+    if (filter.filters) clauses.push(filter.filters);
+    if (filter.since) {
+      clauses.push({
+        updatedAt: { gt: filter.since }
+      });
+    }
+    const page = await this.cursorPaginate({
+      cursor: filter.cursor ?? null,
+      limit: filter.limit ?? 50,
+      orderBy: "updatedAt",
+      ascending: true,
+      ...clauses.length === 0 ? {} : {
+        filters: clauses.length === 1 ? clauses[0] : and(...clauses)
+      }
+    });
+    return { ...page, serverTime };
+  }
+  /**
+   * Insert many rows, overwriting the ones that conflict — one statement.
+   *
+   * @param rows The rows to write.
+   * @param options The conflict target, and optionally which columns to overwrite.
+   * @returns The stored rows.
+   * @throws Error When no conflict column is given.
+   */
+  async bulkUpsert(rows, options) {
+    if (rows.length === 0) return [];
+    if (options.conflictColumns.length === 0) {
+      throw new Error("bulkUpsert needs at least one conflict column.");
+    }
+    const target = new Set(options.conflictColumns);
+    const columns = options.update ?? [
+      ...new Set(rows.flatMap((row) => Object.keys(row)))
+    ].filter((name) => !target.has(name));
+    const patch = {};
+    for (const name of columns) patch[name] = sql.excluded(name);
+    return this.session.execute(
+      insert(this.model).values(rows).onConflictDoUpdate(options.conflictColumns, patch).returning()
+    ).all();
+  }
+  /**
+   * Mark a row deleted without removing it (`deletedAt = now()`).
+   *
+   * @param key The primary key.
+   * @returns The updated row.
+   * @throws Error When the model has no `deletedAt` column (see `withSoftDelete`).
+   * @throws RecordNotFound When no row carries that key.
+   */
+  async softDelete(key) {
+    this.requireColumn("deletedAt", "softDelete");
+    const filter = primaryKeyFilter(this.model, key);
+    const affected = await this.update(filter, {
+      deletedAt: sql.now()
+    });
+    if (affected === 0) throw new RecordNotFound(this.model.tablename, filter);
+    return this.getById(key);
+  }
+  /**
+   * Bring a soft-deleted row back (`deletedAt = null`).
+   *
+   * @param key The primary key.
+   * @returns The updated row.
+   * @throws Error When the model has no `deletedAt` column.
+   * @throws RecordNotFound When no row carries that key.
+   */
+  async restore(key) {
+    this.requireColumn("deletedAt", "restore");
+    const filter = primaryKeyFilter(this.model, key);
+    const affected = await this.update(filter, {
+      deletedAt: null
+    });
+    if (affected === 0) throw new RecordNotFound(this.model.tablename, filter);
+    return this.getById(key);
+  }
+  /**
+   * Delete many rows by primary key, in one statement.
+   *
+   * @param keys The primary keys.
+   * @returns The number of rows actually deleted (keys that matched nothing are
+   *   not an error — deleting what is already gone is the desired end state).
+   * @throws Error When the model has a composite primary key: `IN` over a tuple is
+   *   not portable, and the caller should loop or build the condition explicitly.
+   */
+  async deleteBatch(keys) {
+    if (keys.length === 0) return 0;
+    if (this.pks.length > 1) {
+      throw new Error(
+        `${this.model.tablename} has a composite primary key (${this.pks.join(", ")}); deleteBatch takes single-column keys only.`
+      );
+    }
+    const pk = this.pks[0];
+    const values = keys.map(
+      (key) => primaryKeyFilter(this.model, key)[pk]
+    );
+    return this.delete({ [pk]: { in: values } });
+  }
+  /**
+   * Fail loudly when a method needs a column the model does not declare.
+   *
+   * @param column The property name required.
+   * @param method The method asking, for the message.
+   * @throws Error When the column is absent.
+   */
+  requireColumn(column2, method) {
+    if (column2 in columnsOf(this.model)) return;
+    throw new Error(
+      `${this.model.tablename} has no "${column2}" column, which ${method}() requires \u2014 add it with the matching mixin.`
+    );
+  }
+};
+
+// src/outbox.ts
+function outboxModel(name) {
+  class OutboxBase extends Model {
+    static tablename = name;
+    /** Monotonic id; also the claim order, so events publish in the order written. */
+    id = column.bigInteger().primaryKey();
+    /** The routing key the relay publishes under. */
+    topic = column.varchar(200).notNull();
+    /** The event body. */
+    payload = column.json().notNull();
+    /** Lifecycle state. */
+    status = column.enum("pending", "sending", "sent", "failed").notNull().default("pending");
+    /** How many publish attempts have been made. */
+    attempts = column.integer().notNull().default(0);
+    /** Epoch milliseconds before which the row must not be claimed (backoff). */
+    availableAt = column.bigInteger().notNull().default(0n);
+    /** When the row was written. */
+    createdAt = column.datetime().notNull().default(sql.now());
+    /** When the relay confirmed the publish. */
+    sentAt = column.datetime();
+    /** The last failure's message, kept for triage. */
+    lastError = column.text();
+  }
+  return OutboxBase;
+}
+var OutboxRepository = class extends BaseRepository {
+  /**
+   * Write events to the outbox.
+   *
+   * Call it inside the same `transaction()` as the business write — that is the
+   * whole point, and it is why this does not open a transaction of its own.
+   *
+   * @param events One event, or many.
+   * @returns The stored rows.
+   */
+  async publish(events) {
+    const list = Array.isArray(events) ? events : [events];
+    if (list.length === 0) return [];
+    const now2 = Date.now();
+    return this.createMany(
+      list.map(
+        (event) => ({
+          topic: event.topic,
+          payload: event.payload,
+          status: "pending",
+          attempts: 0,
+          availableAt: BigInt(now2 + (event.delayMs ?? 0))
+        })
+      )
+    );
+  }
+  /**
+   * Claim a batch of due events for this relay, in one statement.
+   *
+   * Uses `FOR UPDATE SKIP LOCKED` over a subquery, so two relays running at once
+   * take **disjoint** batches instead of fighting over the same rows. SQLite has
+   * no row locking and throws — a single-process relay there can claim with
+   * `pending()` plus an update.
+   *
+   * @param limit How many events to take.
+   * @param options Topic filter, and a clock override for tests.
+   * @returns The claimed rows, oldest first.
+   */
+  async claim(limit, options) {
+    const now2 = options?.now ?? Date.now();
+    const due = this.dueQuery(now2, options?.topics).orderBy("id").limit(limit).forUpdate({ skipLocked: true }).asSubquery("id");
+    return this.session.execute(
+      update(this.model).set({
+        status: "sending",
+        attempts: sql.raw("attempts + 1")
+      }).where({ id: { in: due } }).returning()
+    ).all();
+  }
+  /**
+   * The events that are due, without claiming them.
+   *
+   * @param limit How many to read.
+   * @param options Topic filter and clock override.
+   * @returns The due rows, oldest first.
+   */
+  async pending(limit, options) {
+    const now2 = options?.now ?? Date.now();
+    return this.session.execute(
+      this.dueQuery(now2, options?.topics).orderBy("id").limit(limit)
+    ).all();
+  }
+  /**
+   * Confirm that events were published.
+   *
+   * @param ids The claimed ids.
+   * @returns How many rows were marked sent.
+   */
+  async markSent(ids) {
+    if (ids.length === 0) return 0;
+    return this.update(
+      { id: { in: ids } },
+      {
+        status: "sent",
+        sentAt: sql.now()
+      }
+    );
+  }
+  /**
+   * Record a failed publish, scheduling a retry unless it is permanent.
+   *
+   * The attempt counter was already incremented by {@link claim}, so a row that
+   * keeps failing carries its own history — which is what a dead-letter policy
+   * reads.
+   *
+   * @param id The event's id.
+   * @param error The failure, for triage.
+   * @param options Backoff delay, or `permanent` to stop retrying.
+   * @returns How many rows were updated (0 or 1).
+   */
+  async markFailed(id, error, options) {
+    const message = error instanceof Error ? error.message : String(error);
+    return this.update(
+      { id },
+      {
+        status: options?.permanent ? "failed" : "pending",
+        availableAt: BigInt(Date.now() + (options?.retryInMs ?? 0)),
+        lastError: message.slice(0, 1e3)
+      }
+    );
+  }
+  /**
+   * The SELECT of events that may be claimed now.
+   *
+   * @param now The current epoch milliseconds.
+   * @param topics Optional topic filter.
+   * @returns The builder, unordered.
+   */
+  dueQuery(now2, topics) {
+    const where = {
+      status: "pending",
+      availableAt: { lte: BigInt(now2) }
+    };
+    if (topics && topics.length > 0) where.topic = { in: topics };
+    return select(this.model).where(where);
   }
-  /** Update rows matching `filters`; returns the number of rows affected. */
-  async update(filters, set) {
-    return this.session.execute(update(this.model).set(set).where(filters)).rowsAffected();
+};
+
+// src/explain.ts
+function isReadOnlyStatement(sql2) {
+  return /^\s*(select|with)\b/i.test(sql2);
+}
+function summarizePlan(plan) {
+  if (Array.isArray(plan)) {
+    const rows = plan;
+    const details = rows.map((row) => row.detail ?? row["QUERY PLAN"]).filter((detail) => typeof detail === "string");
+    if (details.length > 0) return details.join(" | ");
+  }
+  const node = plan?.Plan;
+  if (node) return describePostgresNode(node);
+  return JSON.stringify(plan);
+}
+function describePostgresNode(node) {
+  const parts = [];
+  const type = node["Node Type"];
+  const relation = node["Relation Name"];
+  const index2 = node["Index Name"];
+  parts.push(
+    [type, relation ? `on ${relation}` : "", index2 ? `using ${index2}` : ""].filter((piece) => piece !== "").join(" ")
+  );
+  const children = node.Plans;
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      parts.push(describePostgresNode(child));
+    }
   }
-  /** Delete rows matching `filters`; returns the number of rows affected. */
-  async delete(filters) {
-    return this.session.execute(del(this.model).where(filters)).rowsAffected();
+  return parts.join(" -> ");
+}
+async function buildReport(session, statements, prefix, options) {
+  const analyze = options?.analyze === true;
+  const plans = [];
+  for (const statement of statements) {
+    if (options?.filter && !options.filter(statement.sql)) continue;
+    if (analyze && !isReadOnlyStatement(statement.sql)) {
+      throw new Error(
+        `EXPLAIN ANALYZE executes the statement, so it is refused for a write: ${statement.sql.slice(0, 80)}`
+      );
+    }
+    const rows = await session.raw(`${prefix(analyze)} ${statement.sql}`, statement.params).all();
+    const plan = extractPlan(rows);
+    plans.push({
+      sql: statement.sql,
+      params: statement.params,
+      plan,
+      summary: () => summarizePlan(plan)
+    });
+  }
+  return {
+    plans,
+    summary: () => plans.map((p) => `${p.summary()}
+  ${p.sql}`).join("\n")
+  };
+}
+function extractPlan(rows) {
+  const first = rows[0];
+  if (rows.length === 1 && first) {
+    const value = first["QUERY PLAN"] ?? Object.values(first)[0];
+    const parsed = typeof value === "string" ? tryParseJson(value) : value;
+    if (Array.isArray(parsed) && parsed.length === 1) return parsed[0];
+    if (parsed !== void 0 && typeof parsed === "object") return parsed;
+  }
+  return rows;
+}
+function tryParseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+// src/tenant.ts
+var TenantScopedRepository = class extends BaseRepository {
+  scope;
+  /**
+   * Bind a repository to one tenant.
+   *
+   * @param model The model class.
+   * @param session The session to run on.
+   * @param scope The tenant column and id.
+   * @throws Error When the model has no such column — a scope that silently
+   *   matches nothing is worse than no scope at all.
+   */
+  constructor(model, session, scope) {
+    super(model, session);
+    if (!(scope.column in columnsOf(model))) {
+      throw new Error(
+        `${model.tablename} has no "${scope.column}" column to scope by tenant.`
+      );
+    }
+    this.scope = scope;
+  }
+  /** The tenant this repository is bound to. */
+  get tenantId() {
+    return this.scope.id;
+  }
+  /**
+   * Merge the tenant predicate into every read.
+   *
+   * The caller's filters are **added to**, never replaced: passing another
+   * tenant's id produces a contradiction that matches nothing, which is the safe
+   * outcome.
+   *
+   * @param filters The caller's filters.
+   * @returns The filters plus the tenant predicate.
+   */
+  scopeFilters(filters) {
+    const tenant = { [this.scope.column]: this.scope.id };
+    if (!filters) return tenant;
+    return and(filters, tenant);
   }
   /**
-   * A page of rows plus metadata. `total` counts all matching rows.
+   * Stamp the tenant onto every row written.
    *
-   * @param filter Page, size, ordering and filters.
-   * @returns The page and pagination metadata.
+   * A row that arrives carrying a **different** tenant is refused rather than
+   * overwritten: silently rewriting it would turn a caller's bug into data that
+   * looks deliberate.
+   *
+   * @param data The row being written.
+   * @returns The row with the tenant column set.
+   * @throws Error When the row names another tenant.
    */
-  async paginate(filter = {}) {
-    const page = Math.max(1, filter.page ?? 1);
-    const pageSize = Math.max(1, filter.pageSize ?? 20);
-    const where = filter.filters;
-    let query = where ? select(this.model).where(where) : select(this.model);
-    if (filter.orderBy) {
-      query = query.orderBy(filter.orderBy, filter.ascending === false ? "desc" : "asc");
+  scopeWrite(data) {
+    const given = data[this.scope.column];
+    if (given !== void 0 && given !== null && given !== this.scope.id) {
+      throw new Error(
+        `Refusing to write ${this.model.tablename}.${this.scope.column} = ${JSON.stringify(given)} from a repository scoped to ${JSON.stringify(this.scope.id)}.`
+      );
     }
-    query = query.limit(pageSize).offset((page - 1) * pageSize);
-    const items = await this.session.execute(query).all();
-    const total = await this.count(where);
-    return {
-      items,
-      total,
-      page,
-      pageSize,
-      pages: Math.max(1, Math.ceil(total / pageSize))
-    };
+    return { ...data, [this.scope.column]: this.scope.id };
   }
 };
 
-// src/active-record.ts
-function primaryKeyOf2(model) {
-  for (const [name, col2] of Object.entries(columnsOf(model))) {
-    if (col2.flags.primaryKey) return name;
+// src/audit.ts
+function auditLogModel(name) {
+  class AuditBase extends Model {
+    static tablename = name;
+    /** Monotonic id — also the order the changes happened in. */
+    id = column.bigInteger().primaryKey();
+    /** The audited table. */
+    tableName = column.varchar(200).notNull();
+    /** The audited row's primary key, as an object. */
+    rowKey = column.json().notNull();
+    /** What happened. */
+    action = column.enum("insert", "update", "delete").notNull();
+    /** Who did it, when the caller could say. */
+    actor = column.varchar(200);
+    /** The changed columns as `[before, after]`; the whole row on insert/delete. */
+    changes = column.json().notNull();
+    /** When the entry was written. */
+    at = column.datetime().notNull().default(sql.now());
+  }
+  return AuditBase;
+}
+function snapshot(model, row, exclude = []) {
+  const columns = columnsOf(model);
+  const out = {};
+  for (const [name, col2] of Object.entries(columns)) {
+    if (exclude.includes(name)) continue;
+    if (!(name in row)) continue;
+    out[name] = encodeValue(col2, row[name]);
   }
-  throw new Error(`${model.tablename} has no primary key`);
+  return out;
 }
-var ActiveRecord = class {
-  constructor(model, session, data) {
-    this.model = model;
+function diffSnapshots(before, after) {
+  const diff = {};
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])) {
+    const from = before[key] ?? null;
+    const to = after[key] ?? null;
+    if (JSON.stringify(from) !== JSON.stringify(to)) diff[key] = [from, to];
+  }
+  return diff;
+}
+var pending = /* @__PURE__ */ new WeakMap();
+function pendingKey(model, key) {
+  return `${model.tablename}:${JSON.stringify(key)}`;
+}
+function enableAudit(model, options) {
+  const exclude = options.exclude ?? [];
+  const write = async (session, action, row, changes) => {
+    await new BaseRepository(options.log, session).create({
+      tableName: model.tablename,
+      rowKey: primaryKeyFilter(model, row),
+      action,
+      actor: options.actor?.() ?? null,
+      changes
+    });
+  };
+  const offs = [
+    onSignal(model, "preSave", async ({ row, session, isInsert }) => {
+      if (isInsert) return;
+      const key = primaryKeyFilter(model, row);
+      const before = await new BaseRepository(model, session).first(key);
+      if (!before) return;
+      let bySession = pending.get(session);
+      if (!bySession) {
+        bySession = /* @__PURE__ */ new Map();
+        pending.set(session, bySession);
+      }
+      bySession.set(
+        pendingKey(model, key),
+        snapshot(model, before, exclude)
+      );
+    }),
+    onSignal(model, "postSave", async ({ row, session, isInsert }) => {
+      const record = row;
+      const after = snapshot(model, record, exclude);
+      if (isInsert) {
+        await write(session, "insert", record, toInsertDiff(after));
+        return;
+      }
+      const key = pendingKey(model, primaryKeyFilter(model, record));
+      const before = pending.get(session)?.get(key) ?? {};
+      pending.get(session)?.delete(key);
+      const changes = diffSnapshots(before, after);
+      if (Object.keys(changes).length === 0) return;
+      await write(session, "update", record, changes);
+    }),
+    onSignal(model, "preDelete", async ({ row, session }) => {
+      const record = row;
+      await write(
+        session,
+        "delete",
+        record,
+        toDeleteDiff(snapshot(model, record, exclude))
+      );
+    })
+  ];
+  return () => {
+    for (const off of offs) off();
+  };
+}
+function toInsertDiff(after) {
+  const diff = {};
+  for (const [key, value] of Object.entries(after)) diff[key] = [null, value];
+  return diff;
+}
+function toDeleteDiff(before) {
+  const diff = {};
+  for (const [key, value] of Object.entries(before)) diff[key] = [value, null];
+  return diff;
+}
+
+// src/unit-of-work.ts
+var UnitOfWork = class {
+  constructor(session) {
     this.session = session;
-    this.data = data;
-    this.pk = primaryKeyOf2(model);
   }
-  model;
   session;
-  data;
-  pk;
-  /** The primary-key value of the wrapped row. */
-  pkValue() {
-    return this.data[this.pk];
-  }
-  pkFilter() {
-    return { [this.pk]: this.pkValue() };
+  entries = /* @__PURE__ */ new Map();
+  /** How many rows are being tracked. */
+  get size() {
+    return this.entries.size;
   }
   /**
-   * Persist the current `data` — insert if new, otherwise overwrite the existing
-   * row (upsert on the primary key). Refreshes `data` from the returned row.
+   * Load a row by primary key, or return the one already loaded.
    *
-   * @returns This wrapper, for chaining.
+   * The second call for the same key does **not** hit the database and returns
+   * the **same object** as the first.
+   *
+   * @param model The model class.
+   * @param key The primary key — a value, or an object for a composite key.
+   * @returns The tracked row, or `null` when there is none.
    */
-  async save() {
-    const cols = columnsOf(this.model);
-    const rowData = this.data;
-    const setPatch = {};
-    for (const c of Object.keys(rowData)) {
-      if (c !== this.pk && c in cols) setPatch[c] = rowData[c];
-    }
-    const saved = await this.session.execute(
-      insert(this.model).values(this.data).onConflictDoUpdate(
-        [this.pk],
-        setPatch
-      ).returning()
-    ).one();
-    this.data = saved;
-    return this;
+  async get(model, key) {
+    const id = this.identity(model, key);
+    const known = this.entries.get(id);
+    if (known)
+      return known.state === "removed" ? null : known.row;
+    const row = await new BaseRepository(model, this.session).getByIdOrNull(key);
+    if (row === null) return null;
+    const tracked = { ...row };
+    this.entries.set(id, {
+      model,
+      row: tracked,
+      snapshot: { ...tracked },
+      state: "clean"
+    });
+    return tracked;
   }
   /**
-   * Update the given columns for this row and merge them into `data`.
+   * Track an existing row that was loaded elsewhere.
    *
-   * @param patch The columns to change.
-   * @returns This wrapper, for chaining.
+   * @param model The model class.
+   * @param row The row, as loaded.
+   * @returns The tracked object — the same one, if this row is already known.
    */
-  async update(patch) {
-    await this.session.execute(update(this.model).set(patch).where(this.pkFilter()));
-    this.data = { ...this.data, ...patch };
-    return this;
+  track(model, row) {
+    const id = this.identity(model, row);
+    const known = this.entries.get(id);
+    if (known) return known.row;
+    const tracked = { ...row };
+    this.entries.set(id, {
+      model,
+      row: tracked,
+      snapshot: { ...tracked },
+      state: "clean"
+    });
+    return tracked;
   }
   /**
-   * Delete this row.
+   * Schedule an insert.
    *
-   * @returns The number of rows affected (0 or 1).
+   * @param model The model class.
+   * @param data The row to insert; it must carry the primary key, since the
+   *   identity map is keyed by it and a database-generated id is not known yet.
+   * @returns The tracked row.
+   * @throws Error When the key is incomplete.
    */
-  async delete() {
-    return this.session.execute(del(this.model).where(this.pkFilter())).rowsAffected();
+  add(model, data) {
+    const row = { ...data };
+    const id = this.identity(model, row);
+    this.entries.set(id, { model, row, snapshot: null, state: "new" });
+    return row;
   }
   /**
-   * Re-fetch this row by primary key and refresh `data`.
+   * Schedule a delete.
    *
-   * @returns This wrapper, for chaining.
-   * @throws When the row no longer exists.
+   * A row added and then removed before the flush simply disappears — no
+   * statement is emitted for it.
+   *
+   * @param model The model class.
+   * @param row The row to delete.
    */
-  async reload() {
-    const fresh = await this.session.execute(select(this.model).where(this.pkFilter())).first();
-    if (fresh === null) {
-      throw new Error(
-        `${this.model.tablename} row ${JSON.stringify(this.pkValue())} not found on reload`
-      );
+  remove(model, row) {
+    const id = this.identity(model, row);
+    const known = this.entries.get(id);
+    if (known?.state === "new") {
+      this.entries.delete(id);
+      return;
     }
-    this.data = fresh;
-    return this;
+    if (known) {
+      known.state = "removed";
+      return;
+    }
+    this.entries.set(id, {
+      model,
+      row: { ...row },
+      snapshot: { ...row },
+      state: "removed"
+    });
   }
-};
-function activeRecord(model, session) {
-  const pk = primaryKeyOf2(model);
-  return {
-    wrap: (row) => new ActiveRecord(model, session, row),
-    create: (data) => new ActiveRecord(model, session, data),
-    async get(id) {
-      const row = await session.execute(select(model).where({ [pk]: id })).first();
-      return row === null ? null : new ActiveRecord(model, session, row);
+  /**
+   * Write every pending change, in one transaction.
+   *
+   * Order is inserts, then updates, then deletes — the order that keeps a
+   * foreign key satisfied when a new parent and its children are flushed
+   * together. It is **not** a topological sort: a graph that needs one should be
+   * flushed in stages.
+   *
+   * A statement that fails takes the whole flush with it, since it all runs in
+   * one transaction. The tracked state is left untouched in that case, so the
+   * caller can fix and flush again.
+   *
+   * @returns How many rows were inserted, updated and deleted.
+   */
+  async flush() {
+    const inserts = [...this.entries.values()].filter((e) => e.state === "new");
+    const removals = [...this.entries.values()].filter((e) => e.state === "removed");
+    const updates = [...this.entries.values()].filter((e) => e.state === "clean" && e.snapshot !== null).map((entry) => ({ entry, patch: diffRow(entry) })).filter(({ patch }) => Object.keys(patch).length > 0);
+    if (inserts.length === 0 && updates.length === 0 && removals.length === 0) {
+      return { inserted: 0, updated: 0, deleted: 0 };
     }
-  };
-}
-
-// src/relations.ts
-function hasMany(target, keys) {
-  return {
-    kind: "hasMany",
-    target,
-    localKey: keys.localKey,
-    foreignKey: keys.foreignKey
-  };
-}
-function belongsTo(target, keys) {
-  return {
-    kind: "belongsTo",
-    target,
-    localKey: keys.localKey,
-    foreignKey: keys.foreignKey
-  };
-}
-async function loadRelations(session, rows, spec) {
-  const out = rows.map((r) => ({ ...r }));
-  for (const [name, rel] of Object.entries(spec)) {
-    const target = rel.target();
-    const localValues = [...new Set(rows.map((r) => r[rel.localKey]))];
-    const related = localValues.length > 0 ? await session.execute(
-      select(target).where({
-        [rel.foreignKey]: { in: localValues }
-      })
-    ).all() : [];
-    if (rel.kind === "hasMany") {
-      const grouped = /* @__PURE__ */ new Map();
-      for (const row of related) {
-        const key = row[rel.foreignKey];
-        const list = grouped.get(key) ?? [];
-        list.push(row);
-        grouped.set(key, list);
+    const result = await this.session.transaction(async (tx) => {
+      let inserted = 0;
+      let updated = 0;
+      let deleted = 0;
+      for (const entry of inserts) {
+        await new BaseRepository(entry.model, tx).create(
+          entry.row
+        );
+        inserted += 1;
       }
-      out.forEach((r, i) => {
-        r[name] = grouped.get(rows[i]?.[rel.localKey]) ?? [];
-      });
-    } else {
-      const byKey = /* @__PURE__ */ new Map();
-      for (const row of related) {
-        byKey.set(row[rel.foreignKey], row);
+      for (const { entry, patch } of updates) {
+        updated += await new BaseRepository(entry.model, tx).update(
+          primaryKeyFilter(entry.model, entry.row),
+          patch
+        );
       }
-      out.forEach((r, i) => {
-        r[name] = byKey.get(rows[i]?.[rel.localKey]) ?? null;
-      });
+      for (const entry of removals) {
+        deleted += await new BaseRepository(entry.model, tx).delete(
+          primaryKeyFilter(entry.model, entry.row)
+        );
+      }
+      return { inserted, updated, deleted };
+    });
+    for (const entry of inserts) entry.state = "clean";
+    for (const { entry } of updates) entry.snapshot = { ...entry.row };
+    for (const entry of inserts) entry.snapshot = { ...entry.row };
+    for (const entry of removals) {
+      this.entries.delete(this.identity(entry.model, entry.row));
     }
+    return result;
   }
-  return out;
+  /** Forget everything tracked, without writing. */
+  clear() {
+    this.entries.clear();
+  }
+  /**
+   * The identity-map key for a row or a primary key.
+   *
+   * @param model The model class.
+   * @param key The row, or the key.
+   * @returns A stable string key.
+   */
+  identity(model, key) {
+    return `${model.tablename}:${JSON.stringify(primaryKeyFilter(model, key))}`;
+  }
+};
+function diffRow(entry) {
+  const patch = {};
+  const snapshot2 = entry.snapshot ?? {};
+  for (const name of Object.keys(columnsOf(entry.model))) {
+    if (!(name in entry.row)) continue;
+    const before = snapshot2[name] ?? null;
+    const after = entry.row[name] ?? null;
+    if (!sameValue(before, after)) patch[name] = entry.row[name];
+  }
+  return patch;
+}
+function sameValue(a, b) {
+  if (a === b) return true;
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  if (a instanceof Uint8Array && b instanceof Uint8Array) {
+    return a.length === b.length && a.every((byte, i) => byte === b[i]);
+  }
+  if (typeof a === "object" && typeof b === "object" && a !== null && b !== null) {
+    return JSON.stringify(a) === JSON.stringify(b);
+  }
+  return false;
 }
+
+// src/engine.ts
 var nodeRequire = createRequire(import.meta.url);
 function encodeSqliteParam(value) {
   if (value === void 0 || value === null) return null;
@@ -2107,7 +4035,7 @@ var BetterSqliteDriver = class _BetterSqliteDriver {
   }
 };
 function returnsRows(sql2) {
-  return /^\s*(select|pragma)/i.test(sql2) || /\breturning\b/i.test(sql2);
+  return /^\s*(select|with|values|table|pragma|explain)\b/i.test(sql2) || /\breturning\b/i.test(sql2);
 }
 function splitJoinRow(node, sources, raw) {
   const leftAliases = new Set(
@@ -2131,6 +4059,10 @@ function coerceOne(builder, raw) {
   const node = builder.node;
   if (node.kind === "join_select") {
     const b2 = builder;
+    if (node.pick) {
+      const model = b2.sources[node.pick];
+      if (model) return coerceRow(model, raw);
+    }
     return splitJoinRow(b2.node, b2.sources, raw);
   }
   const b = builder;
@@ -2168,13 +4100,30 @@ var QueryExecutionError = class extends Error {
   sql;
   params;
 };
-function emitLog(logger, sql2, params) {
+function emitLog(hooks, sql2, params) {
+  const logger = hooks?.onQuery;
   if (!logger) return;
   try {
     logger({ sql: sql2, params });
   } catch {
   }
 }
+function now() {
+  return performance.now();
+}
+function emitQueryEnd(hooks, event) {
+  const logger = hooks?.onQueryEnd;
+  if (!logger) return;
+  const threshold = hooks?.slowQueryMs;
+  if (threshold !== void 0 && event.durationMs < threshold) return;
+  try {
+    logger(event);
+  } catch {
+  }
+}
+function resultRowCount(result) {
+  return result.rows.length > 0 ? result.rows.length : result.changes;
+}
 function firstScalar(row) {
   if (!row) return null;
   const keys = Object.keys(row);
@@ -2262,21 +4211,45 @@ function assertRawParams(params) {
     );
   }
 }
+function assertNoNestedOptions(options) {
+  if (options?.isolation || options?.readOnly) {
+    throw new Error(
+      "Transaction characteristics can only be set on the outermost transaction() \u2014 a nested block joins the one already open."
+    );
+  }
+}
 var SyncSession = class {
-  constructor(driver, dialect, logger) {
+  constructor(driver, dialect, hooks) {
     this.driver = driver;
     this.dialect = dialect;
-    this.logger = logger;
+    this.hooks = hooks;
   }
   driver;
   dialect;
-  logger;
-  /** Log, run, and error-wrap one raw statement. */
+  hooks;
+  /** Open `transaction()` blocks on this session; only the outermost commits. */
+  depth = 0;
+  /** Log, run, time, and error-wrap one raw statement. */
   exec(sql2, params) {
-    emitLog(this.logger, sql2, params);
+    emitLog(this.hooks, sql2, params);
+    const startedAt = now();
     try {
-      return this.driver.execute(sql2, params);
+      const result = this.driver.execute(sql2, params);
+      emitQueryEnd(this.hooks, {
+        sql: sql2,
+        params,
+        durationMs: now() - startedAt,
+        rowCount: resultRowCount(result)
+      });
+      return result;
     } catch (error) {
+      emitQueryEnd(this.hooks, {
+        sql: sql2,
+        params,
+        durationMs: now() - startedAt,
+        rowCount: 0,
+        error
+      });
       throw new QueryExecutionError(error, sql2, params);
     }
   }
@@ -2327,8 +4300,44 @@ var SyncSession = class {
     return new SyncResult(rows, result.changes);
   }
   /** Run `fn` inside a transaction: commit on success, rollback on throw. */
-  transaction(fn2) {
-    this.exec("BEGIN", []);
+  /**
+   * How many `transaction()` blocks are open on this session.
+   *
+   * The counter is what makes a service that orchestrates two repositories work:
+   * both hold the same session, so an inner block **joins** the outer one instead
+   * of emitting a second `BEGIN`, and only the outermost exit commits.
+   */
+  get transactionDepth() {
+    return this.depth;
+  }
+  /** Whether a `transaction()` block is currently open on this session. */
+  get inTransaction() {
+    return this.depth > 0;
+  }
+  /**
+   * Run `fn` inside a transaction, committing on a clean exit and rolling back on
+   * a throw.
+   *
+   * **Re-entrant:** a nested call joins the block already open on this session —
+   * one `BEGIN`, one `COMMIT`, and an inner failure rolls the whole thing back.
+   * To recover from an inner failure without discarding the outer work, use
+   * {@link beginNested}, which is a real savepoint.
+   *
+   * @param fn The body; receives the session to work through.
+   * @returns Whatever `fn` returned.
+   */
+  transaction(fn2, options) {
+    if (this.depth > 0) {
+      assertNoNestedOptions(options);
+      this.depth += 1;
+      try {
+        return fn2(this);
+      } finally {
+        this.depth -= 1;
+      }
+    }
+    for (const stmt of this.dialect.beginStatements(options)) this.exec(stmt, []);
+    this.depth = 1;
     try {
       const out = fn2(this);
       this.exec("COMMIT", []);
@@ -2336,6 +4345,8 @@ var SyncSession = class {
     } catch (error) {
       this.exec("ROLLBACK", []);
       throw error;
+    } finally {
+      this.depth = 0;
     }
   }
   /** Run `fn` inside a SAVEPOINT (nested transaction). */
@@ -2359,15 +4370,31 @@ var SyncSession = class {
   *stream(builder) {
     const node = builder.node;
     const { sql: sql2, params } = this.dialect.compile(node);
-    emitLog(this.logger, sql2, params);
+    emitLog(this.hooks, sql2, params);
     if (this.driver.iterate) {
+      const startedAt = now();
+      let rowCount = 0;
       try {
         for (const raw of this.driver.iterate(sql2, params)) {
+          rowCount++;
           yield coerceOne(builder, raw);
         }
       } catch (error) {
+        emitQueryEnd(this.hooks, {
+          sql: sql2,
+          params,
+          durationMs: now() - startedAt,
+          rowCount,
+          error
+        });
         throw new QueryExecutionError(error, sql2, params);
       }
+      emitQueryEnd(this.hooks, {
+        sql: sql2,
+        params,
+        durationMs: now() - startedAt,
+        rowCount
+      });
       return;
     }
     for (const raw of this.exec(sql2, params).rows) {
@@ -2383,20 +4410,37 @@ var SyncSession = class {
   }
 };
 var AsyncSession = class _AsyncSession {
-  constructor(driver, dialect, logger) {
+  constructor(driver, dialect, hooks) {
     this.driver = driver;
     this.dialect = dialect;
-    this.logger = logger;
+    this.hooks = hooks;
   }
   driver;
   dialect;
-  logger;
-  /** Log, run, and error-wrap one raw statement. */
+  hooks;
+  /** Open `transaction()` blocks on this session; only the outermost commits. */
+  depth = 0;
+  /** Log, run, time, and error-wrap one raw statement. */
   async exec(sql2, params) {
-    emitLog(this.logger, sql2, params);
+    emitLog(this.hooks, sql2, params);
+    const startedAt = now();
     try {
-      return await this.driver.execute(sql2, params);
+      const result = await this.driver.execute(sql2, params);
+      emitQueryEnd(this.hooks, {
+        sql: sql2,
+        params,
+        durationMs: now() - startedAt,
+        rowCount: resultRowCount(result)
+      });
+      return result;
     } catch (error) {
+      emitQueryEnd(this.hooks, {
+        sql: sql2,
+        params,
+        durationMs: now() - startedAt,
+        rowCount: 0,
+        error
+      });
       throw new QueryExecutionError(error, sql2, params);
     }
   }
@@ -2486,17 +4530,17 @@ var AsyncSession = class _AsyncSession {
     const selectSql = this.dialect.compile(
       node.returning === "*" || node.returning === null ? readBack.node : { ...readBack.node, columns: node.returning }
     );
-    const run = async (driver) => {
-      const scoped = new _AsyncSession(driver, this.dialect, this.logger);
+    const run2 = async (driver) => {
+      const scoped = new _AsyncSession(driver, this.dialect, this.hooks);
       const written = await scoped.exec(insertSql.sql, insertSql.params);
       const read = await scoped.exec(selectSql.sql, selectSql.params);
       const rows = read.rows.map((row) => coerceRow(model, row));
       return new SyncResult(rows, written.changes);
     };
-    if (!this.driver.reserve) return run(this.driver);
+    if (!this.driver.reserve) return run2(this.driver);
     const reserved = await this.driver.reserve();
     try {
-      return await run(reserved);
+      return await run2(reserved);
     } finally {
       await reserved.release();
     }
@@ -2505,15 +4549,31 @@ var AsyncSession = class _AsyncSession {
   async *stream(builder) {
     const node = builder.node;
     const { sql: sql2, params } = this.dialect.compile(node);
-    emitLog(this.logger, sql2, params);
+    emitLog(this.hooks, sql2, params);
     if (this.driver.iterate) {
+      const startedAt = now();
+      let rowCount = 0;
       try {
         for await (const raw of this.driver.iterate(sql2, params)) {
+          rowCount++;
           yield coerceOne(builder, raw);
         }
       } catch (error) {
+        emitQueryEnd(this.hooks, {
+          sql: sql2,
+          params,
+          durationMs: now() - startedAt,
+          rowCount,
+          error
+        });
         throw new QueryExecutionError(error, sql2, params);
       }
+      emitQueryEnd(this.hooks, {
+        sql: sql2,
+        params,
+        durationMs: now() - startedAt,
+        rowCount
+      });
       return;
     }
     const result = await this.exec(sql2, params);
@@ -2521,12 +4581,56 @@ var AsyncSession = class _AsyncSession {
       yield coerceOne(builder, raw);
     }
   }
-  async transaction(fn2) {
+  /**
+   * How many `transaction()` blocks are open on this session.
+   *
+   * The counter is what makes a service that orchestrates two repositories work:
+   * both hold the same session, so an inner block **joins** the outer one instead
+   * of emitting a second `BEGIN`, and only the outermost exit commits.
+   */
+  get transactionDepth() {
+    return this.depth;
+  }
+  /** Whether a `transaction()` block is currently open on this session. */
+  get inTransaction() {
+    return this.depth > 0;
+  }
+  /**
+   * Run `fn` inside a transaction, committing on a clean exit and rolling back on
+   * a throw.
+   *
+   * **Re-entrant:** a nested call joins the block already open on this session,
+   * so a service orchestrating several repositories bound to the same session
+   * gets one `BEGIN` and one `COMMIT`, not two of each. An inner failure rolls the
+   * whole block back; use {@link beginNested} for a savepoint that can be
+   * recovered from.
+   *
+   * Pooled drivers (PostgreSQL) pin one connection for the block: `BEGIN`/`COMMIT`
+   * and every statement between them have to run on the same connection, or
+   * postgres.js rejects the raw transaction. Single-connection drivers (SQLite)
+   * skip the reservation.
+   *
+   * @param fn The body; receives the session to work through (the pinned one, on a
+   *   pooled driver).
+   * @returns Whatever `fn` returned.
+   */
+  async transaction(fn2, options) {
+    if (this.depth > 0) {
+      assertNoNestedOptions(options);
+      this.depth += 1;
+      try {
+        return await fn2(this);
+      } finally {
+        this.depth -= 1;
+      }
+    }
+    const begin = this.dialect.beginStatements(options);
     if (this.driver.reserve) {
       const reserved = await this.driver.reserve();
-      const scoped = new _AsyncSession(reserved, this.dialect, this.logger);
+      const scoped = new _AsyncSession(reserved, this.dialect, this.hooks);
       try {
-        await scoped.exec("BEGIN", []);
+        for (const stmt of begin) await scoped.exec(stmt, []);
+        scoped.depth = 1;
         const out = await fn2(scoped);
         await scoped.exec("COMMIT", []);
         return out;
@@ -2534,10 +4638,12 @@ var AsyncSession = class _AsyncSession {
         await scoped.exec("ROLLBACK", []);
         throw error;
       } finally {
+        scoped.depth = 0;
         await reserved.release();
       }
     }
-    await this.exec("BEGIN", []);
+    for (const stmt of begin) await this.exec(stmt, []);
+    this.depth = 1;
     try {
       const out = await fn2(this);
       await this.exec("COMMIT", []);
@@ -2545,8 +4651,49 @@ var AsyncSession = class _AsyncSession {
     } catch (error) {
       await this.exec("ROLLBACK", []);
       throw error;
+    } finally {
+      this.depth = 0;
+    }
+  }
+  /**
+   * Run `fn` inside a `SAVEPOINT` (a nested transaction that can be rolled back on
+   * its own).
+   *
+   * This is the difference from a nested {@link transaction}: a savepoint that
+   * fails discards **only** its own work, so the enclosing block can catch the
+   * error and carry on. A nested `transaction()` joins the outer block, and its
+   * failure takes the whole block down.
+   *
+   * Must run inside an open transaction — PostgreSQL rejects a savepoint outside a
+   * transaction block.
+   *
+   * @param fn The body; receives the same session.
+   * @returns Whatever `fn` returned.
+   */
+  async beginNested(fn2) {
+    savepointCounter += 1;
+    const name = `qsp_${savepointCounter}`;
+    await this.exec(`SAVEPOINT ${name}`, []);
+    try {
+      const out = await fn2(this);
+      await this.exec(`RELEASE ${name}`, []);
+      return out;
+    } catch (error) {
+      await this.exec(`ROLLBACK TO ${name}`, []);
+      throw error;
     }
   }
+  /**
+   * Open an opt-in {@link UnitOfWork} over this session.
+   *
+   * The default stays a plain object written when you ask; this is the other
+   * model, for code that prefers to mutate and flush once.
+   *
+   * @returns A new, empty unit of work.
+   */
+  unitOfWork() {
+    return new UnitOfWork(this);
+  }
   async close() {
     await this.driver.close();
   }
@@ -2555,6 +4702,14 @@ var AsyncSession = class _AsyncSession {
     await this.close();
   }
 };
+function queryHooks(options) {
+  if (!options?.onQuery && !options?.onQueryEnd) return void 0;
+  return {
+    onQuery: options.onQuery,
+    onQueryEnd: options.onQueryEnd,
+    slowQueryMs: options.slowQueryMs
+  };
+}
 function emitNotice(logger, notice) {
   if (!logger) return;
   try {
@@ -2563,18 +4718,18 @@ function emitNotice(logger, notice) {
   }
 }
 var SyncEngine = class {
-  constructor(driver, logger) {
+  constructor(driver, hooks) {
     this.driver = driver;
-    this.logger = logger;
+    this.hooks = hooks;
   }
   driver;
-  logger;
+  hooks;
   dialect = "sqlite";
   session() {
-    return new SyncSession(this.driver, getDialect("sqlite"), this.logger);
+    return new SyncSession(this.driver, getDialect("sqlite"), this.hooks);
   }
-  transaction(fn2) {
-    return this.session().transaction(fn2);
+  transaction(fn2, options) {
+    return this.session().transaction(fn2, options);
   }
   close() {
     this.driver.close();
@@ -2585,19 +4740,68 @@ var SyncEngine = class {
   }
 };
 var AsyncEngine = class {
-  constructor(driver, dialect, logger) {
+  constructor(driver, dialect, hooks) {
     this.driver = driver;
     this.dialect = dialect;
-    this.logger = logger;
+    this.hooks = hooks;
   }
   driver;
   dialect;
-  logger;
+  hooks;
   session() {
-    return new AsyncSession(this.driver, getDialect(this.dialect), this.logger);
+    return new AsyncSession(this.driver, getDialect(this.dialect), this.hooks);
   }
-  transaction(fn2) {
-    return this.session().transaction(fn2);
+  transaction(fn2, options) {
+    return this.session().transaction(fn2, options);
+  }
+  /**
+   * Run `fn` and return the query plan of every statement it ran.
+   *
+   * The block gets its own session over a **recording** driver, so the plans are
+   * built from the statements and the parameters the code really used — not from
+   * SQL copied out of a log by hand. A development tool: it runs the block once
+   * and then one `EXPLAIN` per statement, so keep it out of the hot path.
+   *
+   * @param fn The code to observe; receives the recording session.
+   * @param options `analyze: true` to measure (refused for writes), `filter` to
+   *   explain only some statements.
+   * @returns The report, one plan per statement in execution order.
+   * @throws Error When `analyze` is requested for a statement that writes, or on
+   *   a dialect that has no `EXPLAIN ANALYZE`.
+   *
+   * @example
+   * ```ts
+   * const report = await engine.explain(async (session) => {
+   *   await new BaseRepository(Order, session).paginate({ page: 3 });
+   * });
+   * console.log(report.summary());
+   * ```
+   */
+  async explain(fn2, options) {
+    const statements = [];
+    const recorder = {
+      execute: async (sql2, params) => {
+        statements.push({ sql: sql2, params });
+        return this.driver.execute(sql2, params);
+      },
+      close: () => Promise.resolve(),
+      ...this.driver.iterate ? {
+        iterate: (sql2, params) => {
+          statements.push({ sql: sql2, params });
+          return this.driver.iterate(
+            sql2,
+            params
+          );
+        }
+      } : {}
+    };
+    await fn2(new AsyncSession(recorder, getDialect(this.dialect), this.hooks));
+    return buildReport(
+      this.session(),
+      statements,
+      (analyze) => getDialect(this.dialect).explainPrefix(analyze),
+      options
+    );
   }
   async close() {
     await this.driver.close();
@@ -2663,9 +4867,76 @@ function resolveSqliteDriver(parsed, options) {
   const fromUrl = parsed.driver ? SQLITE_DRIVER_ALIASES[parsed.driver.toLowerCase()] : void 0;
   return fromUrl ?? "node:sqlite";
 }
+var SQLITE_SYNCHRONOUS_LEVELS = [
+  "off",
+  "normal",
+  "full",
+  "extra"
+];
+function readPragma(driver, name) {
+  const { rows } = driver.execute(`PRAGMA ${name}`, []);
+  const first = rows[0];
+  if (!first) return null;
+  return Object.values(first)[0] ?? null;
+}
+function applySqlitePragmas(driver, options, path) {
+  const foreignKeys = options?.foreignKeys ?? true;
+  driver.execute(`PRAGMA foreign_keys = ${foreignKeys ? "ON" : "OFF"}`, []);
+  if (Number(readPragma(driver, "foreign_keys")) !== (foreignKeys ? 1 : 0)) {
+    throw new Error(
+      `SQLite refused PRAGMA foreign_keys = ${foreignKeys ? "ON" : "OFF"} \u2014 the build may lack foreign-key support.`
+    );
+  }
+  const journalMode = options?.journalMode;
+  if (journalMode) {
+    driver.execute(`PRAGMA journal_mode = ${journalMode}`, []);
+    const actual = String(readPragma(driver, "journal_mode") ?? "").toLowerCase();
+    if (actual !== journalMode) {
+      const hint = journalMode === "wal" && actual === "memory" ? " \u2014 an in-memory database cannot use WAL." : ".";
+      throw new Error(
+        `SQLite refused PRAGMA journal_mode = ${journalMode} for ${JSON.stringify(path)} and stayed on ${JSON.stringify(actual)}${hint}`
+      );
+    }
+  }
+  const busyTimeoutMs = options?.busyTimeoutMs;
+  if (busyTimeoutMs !== void 0) {
+    if (!Number.isInteger(busyTimeoutMs) || busyTimeoutMs < 0) {
+      throw new Error(
+        `busyTimeoutMs must be a non-negative integer, got ${JSON.stringify(busyTimeoutMs)}.`
+      );
+    }
+    driver.execute(`PRAGMA busy_timeout = ${busyTimeoutMs}`, []);
+    if (Number(readPragma(driver, "busy_timeout")) !== busyTimeoutMs) {
+      throw new Error(`SQLite refused PRAGMA busy_timeout = ${busyTimeoutMs}.`);
+    }
+  }
+  const synchronous = options?.synchronous;
+  if (synchronous) {
+    driver.execute(`PRAGMA synchronous = ${synchronous}`, []);
+    const actual = SQLITE_SYNCHRONOUS_LEVELS[Number(readPragma(driver, "synchronous"))];
+    if (actual !== synchronous) {
+      throw new Error(
+        `SQLite refused PRAGMA synchronous = ${synchronous} and stayed on ${JSON.stringify(actual ?? "unknown")}.`
+      );
+    }
+  }
+}
+function checkSqliteOptions(dialect, options) {
+  if (!options?.sqlite) return;
+  throw new Error(
+    `The "sqlite" engine options are SQLite-only; ${dialect} has no per-connection pragmas.`
+  );
+}
 function openSqliteDriver(parsed, options) {
   const path = parsed.database ?? ":memory:";
-  return resolveSqliteDriver(parsed, options) === "better-sqlite3" ? BetterSqliteDriver.open(path, options?.driverOptions) : NodeSqliteDriver.open(path, options?.driverOptions);
+  const driver = resolveSqliteDriver(parsed, options) === "better-sqlite3" ? BetterSqliteDriver.open(path, options?.driverOptions) : NodeSqliteDriver.open(path, options?.driverOptions);
+  try {
+    applySqlitePragmas(driver, options?.sqlite, path);
+  } catch (error) {
+    driver.close();
+    throw error;
+  }
+  return driver;
 }
 function createSyncEngine(url, options) {
   const parsed = parseDatabaseUrl(url);
@@ -2674,7 +4945,7 @@ function createSyncEngine(url, options) {
       `createSyncEngine supports only SQLite; ${parsed.dialect} is async-only \u2014 use createEngine.`
     );
   }
-  return new SyncEngine(openSqliteDriver(parsed, options), options?.onQuery);
+  return new SyncEngine(openSqliteDriver(parsed, options), queryHooks(options));
 }
 function createEngine(url, options) {
   const parsed = parseDatabaseUrl(url);
@@ -2682,22 +4953,24 @@ function createEngine(url, options) {
     return new AsyncEngine(
       asAsync(openSqliteDriver(parsed, options)),
       "sqlite",
-      options?.onQuery
+      queryHooks(options)
     );
   }
   if (parsed.dialect === "mysql") {
     checkServerDriver("mysql", options?.driver);
+    checkSqliteOptions("mysql", options);
     return new AsyncEngine(
       createMysqlDriver(parsed.raw, options),
       "mysql",
-      options?.onQuery
+      queryHooks(options)
     );
   }
   checkServerDriver("postgresql", options?.driver);
+  checkSqliteOptions("postgresql", options);
   return new AsyncEngine(
     createPostgresDriver(parsed.raw, options),
     "postgresql",
-    options?.onQuery
+    queryHooks(options)
   );
 }
 function encodeMysqlParam(value) {
@@ -2726,6 +4999,11 @@ function createMysqlDriver(url, options) {
       moduleName
     );
     const opts = { uri: url };
+    if (pool?.prePing || pool?.recycleMs !== void 0) {
+      throw new Error(
+        "pool.prePing and pool.recycleMs are PostgreSQL-only; mysql2 has no equivalent knob."
+      );
+    }
     if (pool?.size !== void 0) opts.connectionLimit = pool.size;
     if (pool?.idleTimeoutMs !== void 0) opts.idleTimeout = pool.idleTimeoutMs;
     if (pool?.connectTimeoutMs !== void 0) opts.connectTimeout = pool.connectTimeoutMs;
@@ -2780,6 +5058,9 @@ function createPostgresDriver(url, options) {
     if (pool?.connectTimeoutMs !== void 0) {
       opts.connect_timeout = Math.ceil(pool.connectTimeoutMs / 1e3);
     }
+    if (pool?.recycleMs !== void 0) {
+      opts.max_lifetime = Math.ceil(pool.recycleMs / 1e3);
+    }
     opts.onnotice = (notice) => emitNotice(options?.onNotice, notice);
     Object.assign(opts, options?.driverOptions ?? {});
     client = (mod.default ?? mod)(url, opts);
@@ -2791,7 +5072,16 @@ function createPostgresDriver(url, options) {
     },
     async reserve() {
       await ensure();
-      const conn = await client.reserve();
+      let conn = await client.reserve();
+      if (pool?.prePing) {
+        try {
+          await conn.unsafe("SELECT 1", []);
+        } catch {
+          conn.release();
+          conn = await client.reserve();
+          await conn.unsafe("SELECT 1", []);
+        }
+      }
       return {
         async execute(sql2, params) {
           return toPostgresResult(await conn.unsafe(sql2, params));
@@ -2810,6 +5100,302 @@ function createPostgresDriver(url, options) {
   };
 }
 
+// src/backup.ts
+var run = promisify(execFile);
+var BackupToolMissing = class extends Error {
+  constructor(tool) {
+    super(`${tool} is not on the PATH; install the PostgreSQL client tools to back up.`);
+    this.name = "BackupToolMissing";
+  }
+};
+var UnsupportedBackupBackend = class extends Error {
+  constructor(dialect) {
+    super(
+      `Backups are implemented for PostgreSQL and SQLite; ${dialect} is not covered.`
+    );
+    this.name = "UnsupportedBackupBackend";
+  }
+};
+function backupFormat(file) {
+  return file.endsWith(".sql") ? "plain" : "custom";
+}
+function postgresEnv(password) {
+  return password ? { ...process.env, PGPASSWORD: password } : { ...process.env };
+}
+function toolUrl(url) {
+  return url.replace(/^([a-z0-9]+)\+[a-z0-9_-]+:/i, "$1:");
+}
+async function spawn(tool, args, env) {
+  try {
+    await run(tool, [...args], { env, maxBuffer: 1024 * 1024 * 64 });
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new BackupToolMissing(tool);
+    }
+    throw error;
+  }
+}
+async function backupDatabase(url, file, options) {
+  const parsed = parseDatabaseUrl(url);
+  if (parsed.dialect === "sqlite") {
+    const source = parsed.database ?? ":memory:";
+    const driver = NodeSqliteDriver.open(source);
+    try {
+      driver.execute("VACUUM INTO ?", [file]);
+    } finally {
+      driver.close();
+    }
+    return { file, dialect: "sqlite", via: "VACUUM INTO" };
+  }
+  if (parsed.dialect !== "postgresql") {
+    throw new UnsupportedBackupBackend(parsed.dialect);
+  }
+  const format = backupFormat(file);
+  await spawn(
+    "pg_dump",
+    [
+      "--dbname",
+      toolUrl(url),
+      ...format === "custom" ? ["--format=custom"] : [],
+      "--file",
+      file,
+      ...options?.extraArgs ?? []
+    ],
+    postgresEnv(parsed.password)
+  );
+  return { file, dialect: "postgresql", via: "pg_dump" };
+}
+async function restoreDatabase(url, file, options) {
+  const parsed = parseDatabaseUrl(url);
+  if (parsed.dialect === "sqlite") {
+    const target = parsed.database ?? ":memory:";
+    await copyFile(file, target);
+    return { file, dialect: "sqlite", via: "copy" };
+  }
+  if (parsed.dialect !== "postgresql") {
+    throw new UnsupportedBackupBackend(parsed.dialect);
+  }
+  const env = postgresEnv(parsed.password);
+  if (backupFormat(file) === "plain") {
+    await spawn(
+      "psql",
+      ["--dbname", toolUrl(url), "--file", file, ...options?.extraArgs ?? []],
+      env
+    );
+    return { file, dialect: "postgresql", via: "psql" };
+  }
+  await spawn(
+    "pg_restore",
+    [
+      "--dbname",
+      toolUrl(url),
+      ...options?.force ? ["--clean", "--if-exists"] : [],
+      file,
+      ...options?.extraArgs ?? []
+    ],
+    env
+  );
+  return { file, dialect: "postgresql", via: "pg_restore" };
+}
+
+// src/cte.ts
+function cteModel(model, name) {
+  const relation = class extends model {
+  };
+  Object.defineProperty(relation, "tablename", { value: name, writable: true });
+  Object.defineProperty(relation, "naming", {
+    value: model.naming,
+    writable: true
+  });
+  Object.defineProperty(relation, "tableArgs", { value: void 0, writable: true });
+  return relation;
+}
+var Cte = class {
+  constructor(model, node) {
+    this.model = model;
+    this.node = node;
+  }
+  model;
+  node;
+  select(columns) {
+    const builder = columns ? select(this.model, columns) : select(this.model);
+    return attach(builder, this.node);
+  }
+};
+function attach(builder, node) {
+  const current = builder.node.with ?? [];
+  const next = { ...builder.node, with: [...current, node] };
+  return Object.assign(Object.create(Object.getPrototypeOf(builder)), builder, {
+    node: next
+  });
+}
+function cte(name, model, body, options) {
+  return new Cte(cteModel(model, name), {
+    name,
+    recursive: false,
+    body: body.node,
+    materialized: options?.materialized ?? null
+  });
+}
+function cteRecursive(name, model, build, options) {
+  const self = cteModel(model, name);
+  return new Cte(self, {
+    name,
+    recursive: true,
+    body: build(self).node,
+    materialized: options?.materialized ?? null
+  });
+}
+
+// src/active-record.ts
+var ActiveRecord = class {
+  constructor(model, session, data) {
+    this.model = model;
+    this.session = session;
+    this.data = data;
+    this.pks = primaryKeysOf(model);
+  }
+  model;
+  session;
+  data;
+  pks;
+  /**
+   * The primary-key values of the wrapped row, as an object.
+   *
+   * Composite keys are the reason this is an object and not a value: identifying
+   * the row by one column of a two-column key hits the wrong row.
+   */
+  pkValue() {
+    const row = this.data;
+    const key = {};
+    for (const name of this.pks) key[name] = row[name];
+    return key;
+  }
+  pkFilter() {
+    return this.pkValue();
+  }
+  /**
+   * Persist the current `data` — insert if new, otherwise overwrite the existing
+   * row (upsert on the primary key). Refreshes `data` from the returned row.
+   *
+   * @returns This wrapper, for chaining.
+   */
+  async save() {
+    const cols = columnsOf(this.model);
+    const rowData = this.data;
+    const setPatch = {};
+    for (const c of Object.keys(rowData)) {
+      if (!this.pks.includes(c) && c in cols) setPatch[c] = rowData[c];
+    }
+    const saved = await this.session.execute(
+      insert(this.model).values(this.data).onConflictDoUpdate(
+        this.pks,
+        setPatch
+      ).returning()
+    ).one();
+    this.data = saved;
+    return this;
+  }
+  /**
+   * Update the given columns for this row and merge them into `data`.
+   *
+   * @param patch The columns to change.
+   * @returns This wrapper, for chaining.
+   */
+  async update(patch) {
+    await this.session.execute(update(this.model).set(patch).where(this.pkFilter()));
+    this.data = { ...this.data, ...patch };
+    return this;
+  }
+  /**
+   * Delete this row.
+   *
+   * @returns The number of rows affected (0 or 1).
+   */
+  async delete() {
+    return this.session.execute(del(this.model).where(this.pkFilter())).rowsAffected();
+  }
+  /**
+   * Re-fetch this row by primary key and refresh `data`.
+   *
+   * @returns This wrapper, for chaining.
+   * @throws When the row no longer exists.
+   */
+  async reload() {
+    const fresh = await this.session.execute(select(this.model).where(this.pkFilter())).first();
+    if (fresh === null) {
+      throw new Error(
+        `${this.model.tablename} row ${JSON.stringify(this.pkValue())} not found on reload`
+      );
+    }
+    this.data = fresh;
+    return this;
+  }
+};
+function activeRecord(model, session) {
+  primaryKeysOf(model);
+  return {
+    wrap: (row) => new ActiveRecord(model, session, row),
+    create: (data) => new ActiveRecord(model, session, data),
+    async get(id) {
+      const filter = primaryKeyFilter(model, id);
+      const row = await session.execute(select(model).where(filter)).first();
+      return row === null ? null : new ActiveRecord(model, session, row);
+    }
+  };
+}
+
+// src/relations.ts
+function hasMany(target, keys) {
+  return {
+    kind: "hasMany",
+    target,
+    localKey: keys.localKey,
+    foreignKey: keys.foreignKey
+  };
+}
+function belongsTo(target, keys) {
+  return {
+    kind: "belongsTo",
+    target,
+    localKey: keys.localKey,
+    foreignKey: keys.foreignKey
+  };
+}
+async function loadRelations(session, rows, spec) {
+  const out = rows.map((r) => ({ ...r }));
+  for (const [name, rel] of Object.entries(spec)) {
+    const target = rel.target();
+    const localValues = [...new Set(rows.map((r) => r[rel.localKey]))];
+    const related = localValues.length > 0 ? await session.execute(
+      select(target).where({
+        [rel.foreignKey]: { in: localValues }
+      })
+    ).all() : [];
+    if (rel.kind === "hasMany") {
+      const grouped = /* @__PURE__ */ new Map();
+      for (const row of related) {
+        const key = row[rel.foreignKey];
+        const list = grouped.get(key) ?? [];
+        list.push(row);
+        grouped.set(key, list);
+      }
+      out.forEach((r, i) => {
+        r[name] = grouped.get(rows[i]?.[rel.localKey]) ?? [];
+      });
+    } else {
+      const byKey = /* @__PURE__ */ new Map();
+      for (const row of related) {
+        byKey.set(row[rel.foreignKey], row);
+      }
+      out.forEach((r, i) => {
+        r[name] = byKey.get(rows[i]?.[rel.localKey]) ?? null;
+      });
+    }
+  }
+  return out;
+}
+
 // src/index.ts
 var DEFAULT_FLAGS = {
   primaryKey: false,
@@ -2821,6 +5407,9 @@ var EXPRESSION = /* @__PURE__ */ Symbol.for("tempest-db-js.expression");
 function expression(token, params = []) {
   return { [EXPRESSION]: true, kind: "expression", expression: token, params };
 }
+function defaultAsWriteValue(value) {
+  return value.kind === "literal" ? value.value : expression(value.expression);
+}
 function isSqlExpression(value) {
   return typeof value === "object" && value !== null && value[EXPRESSION] === true;
 }
@@ -2833,6 +5422,18 @@ var sql = {
   currentTime: () => expression("current_time"),
   /** A freshly generated UUID v4 (`gen_random_uuid()` / portable fallback). */
   uuidv4: () => expression("uuidv4"),
+  /**
+   * The **incoming** value of a column, valid only inside an upsert's
+   * `onConflictDoUpdate` patch.
+   *
+   * A multi-row upsert cannot spell the new value as a literal — each row has its
+   * own — so the assignment has to name the row being inserted:
+   * `EXCLUDED."total"` on PostgreSQL and SQLite, `VALUES(total)` on MySQL.
+   *
+   * @param column The column's property name.
+   * @returns The expression, for use as a write value.
+   */
+  excluded: (column2) => expression({ excluded: column2 }),
   /**
    * Escape hatch: a verbatim SQL expression rendered as-is, with no parameters.
    *
@@ -2882,13 +5483,14 @@ function parseReference(ref, options) {
   };
 }
 var Column = class _Column {
-  constructor(type, flags, defaultValue = null, onUpdateValue = null, reference = null, dbName = null) {
+  constructor(type, flags, defaultValue = null, onUpdateValue = null, reference = null, dbName = null, codec = null) {
     this.type = type;
     this.flags = flags;
     this.defaultValue = defaultValue;
     this.onUpdateValue = onUpdateValue;
     this.reference = reference;
     this.dbName = dbName;
+    this.codec = codec;
   }
   type;
   flags;
@@ -2896,6 +5498,7 @@ var Column = class _Column {
   onUpdateValue;
   reference;
   dbName;
+  codec;
   /** Clone this column with one facet replaced, carrying every other over. */
   derive(patch) {
     return new _Column(
@@ -2904,7 +5507,8 @@ var Column = class _Column {
       patch.defaultValue !== void 0 ? patch.defaultValue : this.defaultValue,
       patch.onUpdateValue !== void 0 ? patch.onUpdateValue : this.onUpdateValue,
       patch.reference !== void 0 ? patch.reference : this.reference,
-      patch.dbName !== void 0 ? patch.dbName : this.dbName
+      patch.dbName !== void 0 ? patch.dbName : this.dbName,
+      patch.codec !== void 0 ? patch.codec : this.codec
     );
   }
   primaryKey() {
@@ -3000,6 +5604,40 @@ var Column = class _Column {
     return this.derive({ onUpdateValue: resolved });
   }
 };
+function customType(spec) {
+  const codec = {
+    toDb: (value) => value === null || value === void 0 ? value : spec.toDb(value),
+    fromDb: (value) => value === null || value === void 0 ? value : spec.fromDb(value)
+  };
+  return () => {
+    const base = spec.base();
+    return new Column(
+      base.type,
+      base.flags,
+      base.defaultValue,
+      base.onUpdateValue,
+      base.reference,
+      base.dbName,
+      codec
+    );
+  };
+}
+var codecCache = /* @__PURE__ */ new WeakMap();
+function codecsOf(model) {
+  const cached = codecCache.get(model);
+  if (cached !== void 0) return cached;
+  const codecs = {};
+  let found = false;
+  for (const [prop, col2] of Object.entries(columnsOf(model))) {
+    if (col2.codec) {
+      codecs[prop] = col2.codec;
+      found = true;
+    }
+  }
+  const result = found ? codecs : null;
+  codecCache.set(model, result);
+  return result;
+}
 function makeColumn(kind, meta = {}) {
   return new Column({ kind, meta }, DEFAULT_FLAGS);
 }
@@ -3077,6 +5715,62 @@ function unique(...columns) {
   }
   return { kind: "unique", columns };
 }
+function check(expression2, options) {
+  const node = toCondNode(expression2);
+  return {
+    kind: "check",
+    name: options?.name,
+    expression: node,
+    columns: options?.columns ?? conditionColumns(node)
+  };
+}
+function index(columns, options) {
+  if (columns.length === 0) {
+    throw new Error("index() requires at least one column.");
+  }
+  return {
+    kind: "index",
+    name: options?.name,
+    columns: [...columns],
+    unique: options?.unique,
+    where: options?.where === void 0 ? void 0 : toCondNode(options.where)
+  };
+}
+function conditionColumns(node) {
+  const found = [];
+  const visitExpr = (expr) => {
+    if (expr.kind === "column") {
+      if (!found.includes(expr.name)) found.push(expr.name);
+      return;
+    }
+    if (expr.kind === "fn") for (const arg of expr.args) visitExpr(arg);
+    if (expr.kind === "cast") visitExpr(expr.operand);
+  };
+  const visit = (current) => {
+    switch (current.kind) {
+      case "fields":
+        for (const key of Object.keys(current.fields)) {
+          if (!found.includes(key)) found.push(key);
+        }
+        return;
+      case "and":
+      case "or":
+        for (const part of current.parts) visit(part);
+        return;
+      case "not":
+        visit(current.part);
+        return;
+      case "compare":
+        visitExpr(current.left);
+        visitExpr(current.right);
+        return;
+      default:
+        return;
+    }
+  };
+  visit(node);
+  return found;
+}
 function foreignKey(columns, refTable, refColumns, options) {
   if (columns.length === 0 || columns.length !== refColumns.length) {
     throw new Error(
@@ -3166,7 +5860,38 @@ function columnPropsOf(model) {
 function dbColumn(names, prop) {
   return names?.[prop] ?? prop;
 }
+function primaryKeysOf(model) {
+  const keys = [];
+  for (const [name, col2] of Object.entries(columnsOf(model))) {
+    if (col2.flags.primaryKey) keys.push(name);
+  }
+  if (keys.length === 0) throw new Error(`${model.tablename} has no primary key`);
+  return keys;
+}
+function primaryKeyFilter(model, id) {
+  const keys = primaryKeysOf(model);
+  const asObject = typeof id === "object" && id !== null && !Array.isArray(id) && !(id instanceof Date) ? id : null;
+  const first = keys[0];
+  if (keys.length === 1) {
+    return { [first]: asObject && first in asObject ? asObject[first] : id };
+  }
+  if (asObject === null) {
+    throw new Error(
+      `${model.tablename} has a composite primary key (${keys.join(", ")}); pass an object like { ${keys.join(", ")} } instead of a scalar.`
+    );
+  }
+  const filter = {};
+  for (const key of keys) {
+    if (!(key in asObject)) {
+      throw new Error(
+        `${model.tablename} has a composite primary key (${keys.join(", ")}); the key is missing ${JSON.stringify(key)}.`
+      );
+    }
+    filter[key] = asObject[key];
+  }
+  return filter;
+}
 
-export { ActiveRecord, Agg, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, BetterSqliteDriver, Column, DeleteBuilder, Expression, InsertBuilder, InvalidDatabaseUrl, JoinBuilder, Model, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, Params, PostgresDialect, QueryExecutionError, RecordNotFound, SelectBuilder, SqliteDialect, SyncEngine, SyncResult, SyncSession, UpdateBuilder, ValidationError, activeRecord, and, avg, belongsTo, col, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, fn, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isExpression, isSqlExpression, isSubquery, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, renderPortableToken, select, sql, stringify, sum, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, unique, update, val };
-//# sourceMappingURL=chunk-NH6K5LTX.js.map
-//# sourceMappingURL=chunk-NH6K5LTX.js.map
+export { ActiveRecord, Agg, AsyncEngine, AsyncResult, AsyncSession, BackupToolMissing, BaseDialect, BaseRepository, BetterSqliteDriver, Column, Cte, DeleteBuilder, Expression, InsertBuilder, InvalidCursor, InvalidDatabaseUrl, JoinBuilder, LiteralParams, Model, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, OutboxRepository, Params, PostgresDialect, QueryExecutionError, RecordNotFound, SelectBuilder, SetBuilder, SqliteDialect, SyncEngine, SyncResult, SyncSession, TenantScopedRepository, UnitOfWork, UnsupportedBackupBackend, UpdateBuilder, ValidationError, activeRecord, aliasOf, aliased, and, attach, auditLogModel, avg, backupDatabase, backupFormat, belongsTo, caseWhen, cast, check, clearSignals, codecsOf, col, column, columnNamesOf, columnPropsOf, columnsOf, contains, count, createEngine, createSyncEngine, cte, cteRecursive, customType, dbColumn, decodeValue, defaultAsWriteValue, del, denseRank, detectDialect, diffSnapshots, emitSignal, enableAudit, encodeValue, escapeLike, except, exists, firstValue, fn, foreignKey, fromDict, fullText, fullTextRank, getDialect, hasHandlers, hasMany, index, insert, intersect, isCondition, isExpression, isReadOnlyStatement, isSqlExpression, isSubquery, join, lag, lastValue, lead, loadRelations, max, min, not, notDeleted, notExists, onSignal, onlyDeleted, or, outboxModel, over, parse, parseDatabaseUrl, parseIntegrityError, percentRank, primaryKeyFilter, primaryKeysOf, rank, renderPortableToken, restoreDatabase, rowNumber, scalar, select, snapshot, sql, stringify, sum, summarizePlan, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, tokenize, toolUrl, union, unionAll, unique, update, val, withAudit, withSoftDelete, withTimestamps };
+//# sourceMappingURL=chunk-HXK6WIBP.js.map
+//# sourceMappingURL=chunk-HXK6WIBP.js.map