litedbmodel 2.2.1 → 2.2.3

package/dist/scp/index.mjs

@@ -1768,30 +1768,32 @@ function lockTail(opts) {
   return "";
 }
 function compileSelect(desc) {
-  const params = [];
+  const headParams = [];
   const selectCols = desc.select || (desc.selectColumn ?? "*");
   const formatter = formatterFor(desc.dialect);
-  if (desc.cte?.params && desc.cte.params.length > 0) params.push(...desc.cte.params);
-  if (desc.joinParams && desc.joinParams.length > 0) params.push(...desc.joinParams);
-  const whereClause2 = conditionsFor(desc.conditions ?? {}, desc.dialect).compile(params, formatter);
-  let sql2 = "";
-  if (desc.cte) sql2 = `WITH ${desc.cte.name} AS (${desc.cte.sql}) `;
-  sql2 += `SELECT ${selectCols} FROM ${desc.tableName}`;
-  if (desc.join) sql2 += ` ${desc.join}`;
-  if (whereClause2) sql2 += ` WHERE ${whereClause2}`;
-  if (desc.group) sql2 += ` GROUP BY ${desc.group}`;
+  if (desc.cte?.params && desc.cte.params.length > 0) headParams.push(...desc.cte.params);
+  if (desc.joinParams && desc.joinParams.length > 0) headParams.push(...desc.joinParams);
+  const whereClause2 = conditionsFor(desc.conditions ?? {}, desc.dialect).compile(headParams, formatter);
+  let head = "";
+  if (desc.cte) head = `WITH ${desc.cte.name} AS (${desc.cte.sql}) `;
+  head += `SELECT ${selectCols} FROM ${desc.tableName}`;
+  if (desc.join) head += ` ${desc.join}`;
+  if (whereClause2) head += ` WHERE ${whereClause2}`;
+  let tail = "";
+  if (desc.group) tail += ` GROUP BY ${desc.group}`;
   const orderClause = typeof desc.order === "string" ? desc.order : orderToString(desc.order);
-  if (orderClause) sql2 += ` ORDER BY ${orderClause}`;
+  if (orderClause) tail += ` ORDER BY ${orderClause}`;
+  const tailParams = [];
   const count = (c) => {
     if (!isBoundCount(c)) return String(c);
-    params.push(c.bind);
+    tailParams.push(c.bind);
     return "?";
   };
-  if (desc.limit !== void 0) sql2 += ` LIMIT ${count(desc.limit)}`;
-  if (desc.offset !== void 0) sql2 += ` OFFSET ${count(desc.offset)}`;
-  sql2 += lockTail(desc);
-  if (desc.append) sql2 += ` ${desc.append}`;
-  return { sql: sql2, params };
+  if (desc.limit !== void 0) tail += ` LIMIT ${count(desc.limit)}`;
+  if (desc.offset !== void 0) tail += ` OFFSET ${count(desc.offset)}`;
+  tail += lockTail(desc);
+  if (desc.append) tail += ` ${desc.append}`;
+  return { sql: head + tail, params: [...headParams, ...tailParams], head, headParams, tail, tailParams, lead: whereClause2 ? "AND" : "WHERE" };
 }
 
 // src/scp/makesql/compile-relation.ts
@@ -3980,6 +3982,24 @@ function readerWriterPair(reader, writer) {
   return { reader, writer };
 }
 var DEFAULT_CONNECTION = "default";
+function assertRoutableNamedDb(db, contextDescription) {
+  if (effectiveConnection(db) === DEFAULT_CONNECTION) return;
+  throw new Error(
+    `scp connection routing: a statement names connection '${db}', but it is executing on ${contextDescription} \u2014 there is no connection registry to resolve the name against. Build the context from a RoutingConfig (setConfig/ConnectionRegistry), or drop the connection tag on the model.`
+  );
+}
+function effectiveConnection(db) {
+  return db === void 0 || db === null ? DEFAULT_CONNECTION : db;
+}
+function assertTxDbAgrees(db, txDb) {
+  if (db === void 0 || db === null) return;
+  const want = effectiveConnection(db);
+  const open = effectiveConnection(txDb);
+  if (want === open) return;
+  throw new Error(
+    `scp connection routing: a statement names connection '${want}', but it is executing inside a transaction opened on '${open}' \u2014 a transaction is ONE connection on ONE database, so the two cannot both be honored. Open the transaction on '${want}', or issue the statement outside it.`
+  );
+}
 var ConnectionRegistry = class _ConnectionRegistry {
   /** name → reader/writer pools. */
   connections;
@@ -4000,7 +4020,7 @@ var ConnectionRegistry = class _ConnectionRegistry {
   }
   /** The reader/writer pair for `name` (or {@link DEFAULT_CONNECTION} when `undefined`). Loud on a missing name. */
   pairFor(name) {
-    const key = name ?? DEFAULT_CONNECTION;
+    const key = effectiveConnection(name);
     const pair = this.connections.get(key);
     if (pair === void 0) {
       const known = [...this.connections.keys()].map((k) => `'${k}'`).join(", ");
@@ -4048,7 +4068,13 @@ function withWriter(fn) {
   return writerScopeStore.run(true, () => withReadOnlyAsync(fn));
 }
 var WriterStickyClock = class {
-  lastWriteAt = 0;
+  /**
+   * `null` until the first `mark()` — absence, NOT a value sentinel. The injectable clocks legitimately
+   * return 0 (a monotonic clock right after process start; rust's `SystemClock` does), so encoding
+   * "never marked" as the value 0 would mis-classify a `mark()` at clock t=0 as unmarked and leak the
+   * read-your-writes read to the reader replica. Absence must be distinct from the value 0.
+   */
+  lastWriteAt = null;
   enabled;
   stickyDurationMs;
   /** Injectable clock (tests advance it); defaults to `Date.now`. */
@@ -4064,12 +4090,12 @@ var WriterStickyClock = class {
   }
   /** Is a read currently sticky-to-writer (within `writerStickyDuration` of the last write)? */
   isSticky() {
-    if (!this.enabled || this.lastWriteAt === 0) return false;
+    if (!this.enabled || this.lastWriteAt === null) return false;
     return this.now() - this.lastWriteAt < this.stickyDurationMs;
   }
   /** Reset the clock (e.g. between tests / on `closeAllPools`). */
   reset() {
-    this.lastWriteAt = 0;
+    this.lastWriteAt = null;
   }
 };
 function resolvePool(intent, routing) {
@@ -4418,15 +4444,20 @@ function connectionForDriver(driver) {
 var BasicContext = class _BasicContext {
   middleware;
   base;
-  /** The pinned tx connection (present ⇒ this is a tx-scoped ctx; every statement uses it). */
+  /** The pinned tx connection (present ⇒ this is a tx-scoped ctx; every statement of the tx's own database (an unnamed one, or one naming that database) uses it). */
   pinned;
   constructor(base, middleware, pinned) {
     this.base = base;
     this.middleware = middleware;
     this.pinned = pinned;
   }
-  connectionFor(_intent) {
-    return this.pinned ?? this.base;
+  connectionFor(intent) {
+    if (this.pinned !== null) {
+      assertTxDbAgrees(intent.db, null);
+      return this.pinned;
+    }
+    assertRoutableNamedDb(intent.db, "a single-connection (non-routed) execution context");
+    return this.base;
   }
   withConnection(conn, tx) {
     return new _BasicContext(this.base, this.middleware, tx ? conn : null);
@@ -4464,7 +4495,10 @@ var PooledAsyncContext = class {
   }
   connectionFor(intent) {
     const pinned = asyncCtxStore.getStore();
-    if (pinned !== void 0) return pinned;
+    if (pinned !== void 0) {
+      assertTxDbAgrees(intent.db, pinned.db);
+      return pinned.conn;
+    }
     const pool = resolvePool(intent, this.routing);
     return {
       async execute(sql2, params) {
@@ -4508,8 +4542,8 @@ var PooledAsyncContext = class {
 function isRoutingConfig(x) {
   return typeof x === "object" && x !== null && "registry" in x && "sticky" in x;
 }
-function runWithPinnedAsyncConnection(conn, fn) {
-  return asyncCtxStore.run(conn, fn);
+function runWithPinnedAsyncConnection(conn, db, fn) {
+  return asyncCtxStore.run({ conn, db }, fn);
 }
 function currentPinnedAsyncConnection() {
   return asyncCtxStore.getStore();
@@ -4520,9 +4554,9 @@ function defaultIsConnectionError(err) {
   return message.includes("Connection terminated") || message.includes("Client has encountered a connection error") || message.includes("ECONNRESET") || message.includes("ECONNREFUSED") || message.includes("Connection lost") || message.includes("This socket has been ended by the other party") || code === "ECONNRESET" || code === "ECONNREFUSED" || code === "EPIPE" || code === "PROTOCOL_CONNECTION_LOST";
 }
 async function withTransactionAsync(ctx, fn, opts = {}, dialect = "postgres", isConnectionError2 = defaultIsConnectionError, connection) {
-  const outerConn = currentPinnedAsyncConnection();
-  if (outerConn !== void 0) {
-    return fn(ctx.withConnection(outerConn, true));
+  const outer = currentPinnedAsyncConnection();
+  if (outer !== void 0) {
+    return fn(ctx.withConnection(outer.conn, true));
   }
   const resolved = resolveTxOptions(opts);
   const begins = beginStatements(dialect, resolved.isolation);
@@ -4533,7 +4567,7 @@ async function withTransactionAsync(ctx, fn, opts = {}, dialect = "postgres", is
     const conn = await pool.acquire();
     const txCtx = ctx.withConnection(conn, true);
     let poisoned = false;
-    const attemptResult = await runWithPinnedAsyncConnection(conn, async () => {
+    const attemptResult = await runWithPinnedAsyncConnection(conn, connection ?? null, async () => {
       for (const begin of begins) await runAsync(txCtx, begin, []);
       try {
         const r = await runInTransactionScope(() => fn(txCtx));
@@ -4564,21 +4598,6 @@ async function withTransactionAsync(ctx, fn, opts = {}, dialect = "postgres", is
 function transaction(ctx, fn, options = {}, dialect = "postgres", isConnectionError2 = defaultIsConnectionError, connection) {
   return withTransactionAsync(ctx, () => fn(), options, dialect, isConnectionError2, connection);
 }
-function withTransactionSync(outer, fn, dialect = "sqlite", isolation) {
-  const ctx = outer.withConnection(outer.connectionFor({ write: true }), true);
-  for (const begin of beginStatements(dialect, isolation)) run(ctx, begin, []);
-  try {
-    const r = runInTransactionScope(() => fn(ctx));
-    run(ctx, r.commit ? "COMMIT" : "ROLLBACK", []);
-    return r.value;
-  } catch (e) {
-    try {
-      run(ctx, "ROLLBACK", []);
-    } catch {
-    }
-    throw e;
-  }
-}
 
 // src/scp/limit-config.ts
 var globalLimitConfig = {};
@@ -4658,25 +4677,20 @@ function attachToParent(parent, pkCols, byKey, single) {
 }
 
 // src/scp/leaves.ts
-var WHERE_TAIL_RE = /\s+(GROUP BY|ORDER BY|LIMIT|OFFSET|FOR UPDATE|RETURNING)\b/i;
-function spliceWhere(baseSql, whereSql) {
-  if (whereSql === "") return baseSql;
-  const tail = WHERE_TAIL_RE.exec(baseSql);
-  return tail === null ? baseSql + whereSql : baseSql.slice(0, tail.index) + whereSql + baseSql.slice(tail.index);
-}
 function assembleDynamicWhere(p) {
-  const frags = (p.whereDynamic.frags ?? []).filter((f) => f != null);
-  let whereSql = "";
-  const whereParams = [];
-  frags.forEach((f, i) => {
-    whereSql += (i === 0 ? " WHERE " : " AND ") + f.sql;
-    whereParams.push(...f.params);
-  });
-  return { sql: spliceWhere(p.sql, whereSql), params: [...whereParams, ...p.params] };
+  const plan = dynamicWherePlan(p.whereDynamic);
+  const frags = plan.frags.filter((f) => !f.skipped);
+  const clause = frags.length === 0 ? "" : ` ${plan.lead} ${frags.map((f) => f.sql).join(" AND ")}`;
+  return {
+    sql: p.sql + clause + plan.tail,
+    params: [...p.params, ...frags.flatMap((f) => f.params), ...plan.tailParams]
+  };
 }
 function effectiveStatement(p) {
-  if (p.whereDynamic == null) return p;
-  return { ...assembleDynamicWhere({ sql: p.sql, params: p.params, whereDynamic: p.whereDynamic }), write: p.write };
+  const write = p.write !== null;
+  const db = p.db ?? null;
+  if (p.whereDynamic == null) return { sql: p.sql, params: p.params, write, db };
+  return { ...assembleDynamicWhere({ sql: p.sql, params: p.params, whereDynamic: p.whereDynamic }), write, db };
 }
 function toBcInt(v) {
   return typeof v === "bigint" ? v : BigInt(v);
@@ -4698,7 +4712,7 @@ function prepareSql(p, dialect) {
   }
   sql2 = renderPlaceholders(sql2, dialect);
   const bound = encodeParams(p.params, dialect);
-  const intent = { write: p.write === true };
+  const intent = { write: p.write, ...p.db != null ? { db: p.db } : {} };
   return { sql: sql2, bound, intent };
 }
 function writeSummary(info) {
@@ -4706,14 +4720,14 @@ function writeSummary(info) {
 }
 function executeSQL(p, ctx) {
   const prepared = prepareSql(effectiveStatement(p), ctx.dialect);
-  if (p.write === true && p.returning !== true) return writeSummary(run(ctx.exec, prepared.sql, prepared.bound, prepared.intent));
+  if (p.write !== null && !p.write.returning) return writeSummary(run(ctx.exec, prepared.sql, prepared.bound, prepared.intent));
   const rows = executeSafe(ctx.exec, prepared.sql, prepared.bound, prepared.intent);
   assertRelationHardLimit(rows, p.guard);
   return rows;
 }
 async function executeSQLAsync(p, ctx) {
   const prepared = prepareSql(effectiveStatement(p), ctx.dialect);
-  if (p.write === true && p.returning !== true) return writeSummary(await runAsync(ctx.execAsync, prepared.sql, prepared.bound, prepared.intent));
+  if (p.write !== null && !p.write.returning) return writeSummary(await runAsync(ctx.execAsync, prepared.sql, prepared.bound, prepared.intent));
   const rows = await executeAsync(ctx.execAsync, prepared.sql, prepared.bound, prepared.intent);
   assertRelationHardLimit(rows, p.guard);
   return rows;
@@ -4724,40 +4738,106 @@ function pluck(p) {
 }
 function group(p) {
   const byKey = groupByKey(p.children, p.fk);
-  return p.parents.map((par) => ({ ...par, [p.into]: attachToParent(par, p.pk, byKey, p.single === true) }));
+  return p.parents.map((par) => ({ ...par, [p.into]: attachToParent(par, p.pk, byKey, p.single) }));
+}
+var PORT_TYPES = {
+  bool: (v) => typeof v === "boolean",
+  int: (v) => typeof v === "bigint",
+  string: (v) => typeof v === "string",
+  list: (v) => Array.isArray(v),
+  "string[]": (v) => Array.isArray(v) && v.every((e) => typeof e === "string"),
+  record: (v) => typeof v === "object" && v !== null && !Array.isArray(v)
+};
+function portTyped(value, what, declared) {
+  const kind = declared.endsWith("|null") ? declared.slice(0, -"|null".length) : declared;
+  if (kind !== declared && value === null) return null;
+  if (!PORT_TYPES[kind](value)) {
+    const got = JSON.stringify(value, (_k, v) => typeof v === "bigint" ? `${v}n` : v);
+    throw new Error(`scp leaf: ${what} must be ${declared}, got ${got}`);
+  }
+  return value;
 }
-function relationGuardPort(port) {
-  if (port === void 0 || port === null) return null;
-  const g = port;
-  const limit = typeof g.limit === "bigint" ? Number(g.limit) : g.limit;
-  if (typeof limit !== "number" || !Number.isInteger(limit) || typeof g.relation !== "string") {
+function requiredField(record, name, at, declared) {
+  if (!(name in record)) {
     throw new Error(
-      `scp leaf executeSQL: the 'guard' port must be a {limit:int, model?:string, relation:string} relation cap, got ${JSON.stringify(port)}`
+      `scp leaf: ${at} is missing its '${name}' field \u2014 a generated module spells every field of every struct it wires, so an ABSENT key is an ABI break (a null VALUE is how an absent write mode / plan / cap is spelled)`
     );
   }
-  return { limit, ...typeof g.model === "string" ? { model: g.model } : {}, relation: g.relation };
+  return portTyped(record[name], `${at}'s '${name}'`, declared);
+}
+var PLAN_AT = `the 'whereDynamic' plan`;
+function dynamicWherePlan(port) {
+  const plan = port;
+  const at = `a 'whereDynamic' fragment`;
+  const frags = requiredField(plan, "frags", PLAN_AT, "list").map((frag) => {
+    const f = portTyped(frag, at, "record");
+    return {
+      skipped: requiredField(f, "skipped", at, "bool"),
+      sql: requiredField(f, "sql", at, "string"),
+      params: requiredField(f, "params", at, "list")
+    };
+  });
+  return {
+    frags,
+    lead: requiredField(plan, "lead", PLAN_AT, "string"),
+    tail: requiredField(plan, "tail", PLAN_AT, "string"),
+    tailParams: requiredField(plan, "tailParams", PLAN_AT, "list")
+  };
+}
+function relationGuardPort(port) {
+  if (port === null) return null;
+  const g = port;
+  const at = `the 'guard' cap`;
+  const raw = requiredField(g, "limit", at, "int");
+  const model = requiredField(g, "model", at, "string|null");
+  return {
+    limit: Number(raw),
+    ...model === null ? {} : { model },
+    relation: requiredField(g, "relation", at, "string")
+  };
+}
+var OPTS_AT = `the 'opts' control record`;
+function optsField(opts, name) {
+  return requiredField(opts, name, OPTS_AT, "record|null");
+}
+function writeModePort(port) {
+  if (port === null) return null;
+  return { returning: requiredField(port, "returning", `the 'write' mode`, "bool") };
 }
 function executeSqlPorts(ports) {
+  const at = "the executeSQL payload";
+  const sql2 = requiredField(ports, "sql", at, "string");
+  const params = requiredField(ports, "params", at, "list");
+  const opts = "opts" in ports ? requiredField(ports, "opts", at, "record|null") : null;
+  if (opts === null) return { sql: sql2, params, write: null };
   return {
-    sql: ports.sql,
-    params: ports.params,
-    write: ports.write === true,
-    returning: ports.returning === true,
-    bigint: ports.bigint === true,
-    whereDynamic: ports.whereDynamic ?? null,
-    guard: relationGuardPort(ports.guard)
+    sql: sql2,
+    params,
+    // The NAMED database — the one control field that is a bare `string|null` rather than a struct, so
+    // it is read against its own declared type instead of through `optsField`'s `record|null`.
+    db: requiredField(opts, "db", OPTS_AT, "string|null"),
+    write: writeModePort(optsField(opts, "write")),
+    whereDynamic: optsField(opts, "whereDynamic"),
+    guard: relationGuardPort(optsField(opts, "guard"))
   };
 }
+var PLUCK_AT = "the pluck payload";
+var GROUP_AT = "the group payload";
 var shapingHandlers = {
-  pluck: (ports) => ({ ok: pluck({ rows: ports.rows, col: ports.col }) }),
+  pluck: (ports) => ({
+    ok: pluck({
+      rows: requiredField(ports, "rows", PLUCK_AT, "list"),
+      col: requiredField(ports, "col", PLUCK_AT, "string[]")
+    })
+  }),
   group: (ports) => ({
     ok: group({
-      parents: ports.parents,
-      children: ports.children,
-      pk: ports.pk,
-      fk: ports.fk,
-      into: ports.into,
-      single: ports.single === true
+      parents: requiredField(ports, "parents", GROUP_AT, "list"),
+      children: requiredField(ports, "children", GROUP_AT, "list"),
+      pk: requiredField(ports, "pk", GROUP_AT, "string[]"),
+      fk: requiredField(ports, "fk", GROUP_AT, "string[]"),
+      into: requiredField(ports, "into", GROUP_AT, "string"),
+      single: requiredField(ports, "single", GROUP_AT, "bool")
     })
   })
 };
@@ -4786,111 +4866,6 @@ function isConnectionError(error) {
   return message.includes("Connection terminated unexpectedly") || message.includes("Connection terminated") || message.includes("Client has encountered a connection error") || message.includes("read ECONNRESET") || message.includes("connect ECONNREFUSED") || message.includes("Connection lost") || message.includes("This socket has been ended by the other party") || code === "ECONNRESET" || code === "ECONNREFUSED" || code === "EPIPE" || code === "EAI_AGAIN" || code === "PROTOCOL_CONNECTION_LOST";
 }
 
-// src/scp/writes.ts
-var ENTITY_ROOT = "__entity";
-var PATH_RE = /^\$\.(input|entity)\.([A-Za-z_][A-Za-z0-9_]*)$/;
-var REF_PATH_RE = /^\$\.ref\.([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/;
-function parseEffectPath(value) {
-  const m = PATH_RE.exec(value);
-  if (m !== null) return { root: m[1], field: m[2] };
-  const r = REF_PATH_RE.exec(value);
-  if (r !== null) return { root: "ref", writeName: r[1], field: r[2] };
-  throw new Error(
-    `write-time relations: '${value}' is not a valid path-rooted value; use '$.input.<field>' (the Command input), '$.entity.<field>' (the sole written row), or '$.ref.<writeName>.<field>' (a named upstream write's RETURNING row).`
-  );
-}
-function assertPaths(map) {
-  for (const v of Object.values(map)) parseEffectPath(v);
-}
-var recorder = {
-  lifecycle(effects = {}) {
-    for (const r of effects.requires ?? []) assertPaths(r.keys);
-    if (effects.idempotency !== void 0) parseEffectPath(effects.idempotency.token);
-    for (const u of effects.unique ?? []) {
-      u.scope.forEach((p) => parseEffectPath(p));
-      u.fields.forEach((p) => parseEffectPath(p));
-    }
-    for (const d of effects.derive ?? []) assertPaths(d.keys);
-    for (const e of effects.edges ?? []) {
-      assertPaths(e.columns);
-      if (e.where !== void 0) assertPaths(e.where);
-    }
-    for (const em of effects.emits ?? []) assertPaths(em.payload);
-    return { effects: freezeEffects(effects) };
-  },
-  exists(table, keys) {
-    return { kind: "requires", table, keys };
-  },
-  unique(spec) {
-    return { kind: "unique", name: spec.name, guardTable: spec.guardTable, scope: spec.scope, fields: spec.fields };
-  },
-  increment(table, keys, attribute, amount) {
-    if (!Number.isFinite(amount)) {
-      throw new Error(`entityWrites: increment amount for '${table}.${attribute}' must be a finite number (got ${String(amount)})`);
-    }
-    return { kind: "derive", table, keys, attribute, amount };
-  },
-  edge(spec) {
-    if (spec.relation === "fk" && spec.where === void 0) {
-      throw new Error(`entityWrites: a 'fk' edge on '${spec.table}' requires a 'where' key map (the matched row's identity)`);
-    }
-    return {
-      kind: "edge",
-      relation: spec.relation,
-      action: spec.action,
-      table: spec.table,
-      columns: spec.columns,
-      ...spec.where !== void 0 ? { where: spec.where } : {}
-    };
-  },
-  event(name, outboxTable, payload) {
-    return { kind: "emit", name, outboxTable, payload };
-  },
-  idempotentBy(table, column2, token) {
-    return { kind: "idempotency", table, column: column2, token };
-  }
-};
-function freezeEffects(effects) {
-  const out = {};
-  if (effects.requires !== void 0) out.requires = effects.requires;
-  if (effects.idempotency !== void 0) out.idempotency = effects.idempotency;
-  if (effects.unique !== void 0) out.unique = effects.unique;
-  if (effects.derive !== void 0) out.derive = effects.derive;
-  if (effects.edges !== void 0) out.edges = effects.edges;
-  if (effects.emits !== void 0) out.emits = effects.emits;
-  return out;
-}
-function entityWrites(builder) {
-  const shape = builder(recorder);
-  if (shape.create === void 0 && shape.update === void 0 && shape.remove === void 0) {
-    throw new Error(
-      "entityWrites(...) must declare at least one lifecycle (`create` / `update` / `remove`)."
-    );
-  }
-  return {
-    ...shape.create !== void 0 ? { create: shape.create } : {},
-    ...shape.update !== void 0 ? { update: shape.update } : {},
-    ...shape.remove !== void 0 ? { remove: shape.remove } : {}
-  };
-}
-function edgeWrites(builder) {
-  const def = entityWrites(builder);
-  for (const phase of ["create", "update", "remove"]) {
-    const c = def[phase];
-    if (c === void 0) continue;
-    const e = c.effects;
-    if (e.requires !== void 0 || e.unique !== void 0 || e.derive !== void 0 || e.emits !== void 0 || e.idempotency !== void 0) {
-      throw new Error(
-        `edgeWrites: the '${phase}' lifecycle may declare ONLY 'edges' effects (an edge entity carries only edge writes; use entityWrites for a full save contract).`
-      );
-    }
-  }
-  return def;
-}
-function lifecycleFor(def, phase) {
-  return def[phase];
-}
-
 // src/scp/makesql/tx.ts
 function literalize(value) {
   if (value === null || value === void 0) return null;
@@ -4903,101 +4878,7 @@ function literalize(value) {
   }
   return value;
 }
-function pathToRef(value) {
-  const p = parseEffectPath(value);
-  if (p.root === "input") return { ref: [p.field] };
-  if (p.root === "entity") return { ref: [ENTITY_ROOT, p.field] };
-  return { ref: [p.writeName, p.field] };
-}
-function guardInsert(dialect, table, columns, placeholders2) {
-  const cols = `(${columns.join(", ")})`;
-  if (dialect === "mysql") return `INSERT IGNORE INTO ${table} ${cols} VALUES (${placeholders2})`;
-  return `INSERT INTO ${table} ${cols} VALUES (${placeholders2}) ON CONFLICT DO NOTHING`;
-}
-function makeIdGen() {
-  let n = 0;
-  return (role) => `tx_${role}_${n++}`;
-}
-function compileRequires(e, nextId) {
-  const cols = Object.keys(e.keys);
-  if (cols.length === 0) throw new Error(`write-plan: requires on '${e.table}' declares no keys`);
-  const whereSql = v1EqualityWhereText(cols);
-  const op = {
-    sql: `SELECT 1 FROM ${e.table} WHERE ${whereSql}`,
-    params: cols.map((c) => pathToRef(e.keys[c]))
-  };
-  return { id: nextId("requires"), role: "gate:requires", op, gate: "existsElseRollback", label: `requires ${e.table}` };
-}
-function compileIdempotency(e, nextId, dialect) {
-  const op = {
-    sql: guardInsert(dialect, e.table, [e.column], "?"),
-    params: [pathToRef(e.token)]
-  };
-  return { id: nextId("idem"), role: "gate:idempotency", op, gate: "insertedElseNoop", label: `idempotency ${e.table}` };
-}
-function compileUnique(e, nextId, dialect) {
-  const scopeCols = e.scope.map((_, i) => `s${i}`);
-  const fieldCols = e.fields.map((_, i) => `f${i}`);
-  const cols = ["name", ...scopeCols, ...fieldCols];
-  const placeholders2 = cols.map(() => "?").join(", ");
-  const params = [
-    e.name,
-    // literal discriminator (a closed-set string literal)
-    ...e.scope.map(pathToRef),
-    ...e.fields.map(pathToRef)
-  ];
-  const op = { sql: guardInsert(dialect, e.guardTable, cols, placeholders2), params };
-  return { id: nextId("unique"), role: "gate:unique", op, gate: "insertedElseRollback", label: `unique ${e.name}` };
-}
-function compileDerive(e, nextId) {
-  const keyCols = Object.keys(e.keys);
-  if (keyCols.length === 0) throw new Error(`write-plan: derive on '${e.table}' declares no keys`);
-  const whereSql = v1EqualityWhereText(keyCols);
-  const op = {
-    sql: `UPDATE ${e.table} SET ${e.attribute} = ${e.attribute} + ? WHERE ${whereSql}`,
-    // SET amount is the first param (before the WHERE keys), matching the v1 param order.
-    params: [e.amount, ...keyCols.map((c) => pathToRef(e.keys[c]))]
-  };
-  return { id: nextId("derive"), role: "derive", op, label: `derive ${e.table}.${e.attribute}` };
-}
-function compileEdge(e, nextId) {
-  if (e.relation === "m2m") {
-    const cols = Object.keys(e.columns);
-    if (e.action === "set") {
-      const placeholders2 = cols.map(() => "?").join(", ");
-      const op3 = {
-        sql: `INSERT INTO ${e.table} (${cols.join(", ")}) VALUES (${placeholders2})`,
-        params: cols.map((c) => pathToRef(e.columns[c]))
-      };
-      return { id: nextId("edge"), role: "edge", op: op3, label: `edge m2m link ${e.table}` };
-    }
-    const whereSql2 = v1EqualityWhereText(cols);
-    const op2 = {
-      sql: `DELETE FROM ${e.table} WHERE ${whereSql2}`,
-      params: cols.map((c) => pathToRef(e.columns[c]))
-    };
-    return { id: nextId("edge"), role: "edge", op: op2, label: `edge m2m unlink ${e.table}` };
-  }
-  const setCols = Object.keys(e.columns);
-  const whereCols = Object.keys(e.where);
-  const setClauses = setCols.map((c) => e.action === "set" ? `${c} = ?` : `${c} = NULL`);
-  const setParams = e.action === "set" ? setCols.map((c) => pathToRef(e.columns[c])) : [];
-  const whereSql = v1EqualityWhereText(whereCols);
-  const op = {
-    sql: `UPDATE ${e.table} SET ${setClauses.join(", ")} WHERE ${whereSql}`,
-    params: [...setParams, ...whereCols.map((c) => pathToRef(e.where[c]))]
-  };
-  return { id: nextId("edge"), role: "edge", op, label: `edge fk ${e.action} ${e.table}` };
-}
-function compileEmit(e, nextId) {
-  const payloadObj = {};
-  for (const [k, v] of Object.entries(e.payload)) payloadObj[k] = pathToRef(v);
-  const op = {
-    sql: `INSERT INTO ${e.outboxTable} (type, payload) VALUES (?, ?)`,
-    params: [e.name, { obj: payloadObj }]
-  };
-  return { id: nextId("emit"), role: "emit", op, label: `emit ${e.name}` };
-}
+var ENTITY_ROOT = "__entity";
 function stringPort(ports, name) {
   const v = ports[name];
   if (v === void 0) return void 0;
@@ -5053,11 +4934,6 @@ function v1ConditionText(conditions) {
   const probe = [];
   return new DBConditions(conditions).compile(probe);
 }
-function v1EqualityWhereText(columns) {
-  const conditions = {};
-  for (const c of columns) conditions[c] = PROBE;
-  return v1ConditionText(conditions);
-}
 function lowerWhereMember(node, at, dialect) {
   const op = opKey(node);
   if (op === void 0) throw new Error(`compileWriteNode: ${at}: a where member must be a single-operator Expression node`);
@@ -5195,7 +5071,7 @@ function compileWriteNodeSql(node, dialect, resolveColumnType) {
       const sorted = [...cols].sort();
       if (stringPort(ports, "batch") === "true") {
         if (dialect === "postgres") {
-          if (resolveColumnType === void 0) throw new Error(`compileWriteNode: batch insert on postgres needs the column-type resolver (schema SoT) to derive the UNNEST element casts \u2014 pass it through compileCreateManyBundle/compileWriteBundle (the decorator-adapter write path).`);
+          if (resolveColumnType === void 0) throw new Error(`compileWriteNode: batch insert on postgres needs the column-type resolver (schema SoT) to derive the UNNEST element casts \u2014 pass it through compileCreateManyBundle (the decorator-adapter batch write path).`);
           return pgBatchInsert(table, sorted, values, ports, resolveColumnType, dialect);
         }
         const shapeOpts = { tableName: table, columns: sorted, records: [], ...onConflictJsonOpts(ports, sorted), ...stringPort(ports, "returning") !== void 0 ? { returning: stringPort(ports, "returning") } : {} };
@@ -5223,7 +5099,7 @@ function compileWriteNodeSql(node, dialect, resolveColumnType) {
         if (keyCols.length === 0) throw new Error(`compileWriteNode: batch Update requires at least one 'key.<field>' port`);
         const updateCols = [...setCols].sort();
         if (dialect === "postgres") {
-          if (resolveColumnType === void 0) throw new Error(`compileWriteNode: batch update on postgres needs the column-type resolver (schema SoT) to derive the UNNEST element casts \u2014 pass it through compileCreateManyBundle/compileWriteBundle (the decorator-adapter write path).`);
+          if (resolveColumnType === void 0) throw new Error(`compileWriteNode: batch update on postgres needs the column-type resolver (schema SoT) to derive the UNNEST element casts \u2014 pass it through compileCreateManyBundle (the decorator-adapter batch write path).`);
           return pgBatchUpdate(table, keyCols, updateCols, key, set, ports, resolveColumnType, dialect);
         }
         const shapeOpts = { tableName: table, keyColumns: keyCols, updateColumns: updateCols, records: [], ...stringPort(ports, "returning") !== void 0 ? { returning: stringPort(ports, "returning") } : {} };
@@ -5255,133 +5131,9 @@ function compileWriteNodeSql(node, dialect, resolveColumnType) {
       throw new Error(`compileWriteNode: catalog component '${component}' has no write compile (SQL writes: Insert/Update/Delete)`);
   }
 }
-function compileWriteGroup(base, lifecycle, nextId, dialect, seqRef) {
-  const e = lifecycle.effects;
-  const nodes = [];
-  const mk = (stmt, isGate) => {
-    const consumes = refHeadsOf(stmt).filter((h) => h !== ENTITY_ROOT && !isInputHead(h, stmt));
-    return { stmt, seq: seqRef.n++, consumes, produces: stmt.binds ?? null, isGate };
-  };
-  for (const r of e.requires ?? []) nodes.push(mk(compileRequires(r, nextId), true));
-  if (e.idempotency !== void 0) nodes.push(mk(compileIdempotency(e.idempotency, nextId, dialect), true));
-  for (const u of e.unique ?? []) nodes.push(mk(compileUnique(u, nextId, dialect), true));
-  const bodyId = nextId("body");
-  const bodyStmt = {
-    id: bodyId,
-    role: "body",
-    op: base.op,
-    label: base.label,
-    ...base.name !== void 0 ? { binds: base.name } : {}
-  };
-  nodes.push(mk(bodyStmt, false));
-  for (const d of e.derive ?? []) nodes.push(mk(compileDerive(d, nextId), false));
-  for (const ed of e.edges ?? []) nodes.push(mk(compileEdge(ed, nextId), false));
-  for (const em of e.emits ?? []) nodes.push(mk(compileEmit(em, nextId), false));
-  return { nodes, bodyId };
-}
-function topoOrder(nodes) {
-  const byName = /* @__PURE__ */ new Map();
-  for (const n of nodes) {
-    if (n.produces !== null) {
-      if (byName.has(n.produces)) {
-        throw new Error(`write-plan: two writes both bind the name '${n.produces}' \u2014 write names must be unique in a composite Command.`);
-      }
-      byName.set(n.produces, n);
-    }
-  }
-  const succ = /* @__PURE__ */ new Map();
-  const indeg = /* @__PURE__ */ new Map();
-  const nodeById = /* @__PURE__ */ new Map();
-  for (const n of nodes) {
-    nodeById.set(n.stmt.id, n);
-    succ.set(n.stmt.id, /* @__PURE__ */ new Set());
-    indeg.set(n.stmt.id, 0);
-  }
-  const addEdge = (fromId, toId) => {
-    if (fromId === toId) return;
-    const s = succ.get(fromId);
-    if (!s.has(toId)) {
-      s.add(toId);
-      indeg.set(toId, indeg.get(toId) + 1);
-    }
-  };
-  for (const n of nodes) {
-    for (const dep of n.consumes) {
-      const producer = byName.get(dep);
-      if (producer === void 0) {
-        throw new Error(
-          `write-plan: statement '${n.stmt.label}' references '$.ref.${dep}.*' but no write in this Command binds the name '${dep}' \u2014 a dangling write reference (fail-closed; no silent skip).`
-        );
-      }
-      addEdge(producer.stmt.id, n.stmt.id);
-    }
-  }
-  const gates = nodes.filter((n) => n.isGate);
-  const nonGates = nodes.filter((n) => !n.isGate);
-  for (const g of gates) for (const b of nonGates) addEdge(g.stmt.id, b.stmt.id);
-  const ordered = [];
-  const ready = nodes.filter((n) => indeg.get(n.stmt.id) === 0).sort((a, b) => a.seq - b.seq);
-  while (ready.length > 0) {
-    const n = ready.shift();
-    ordered.push(n.stmt);
-    for (const depId of succ.get(n.stmt.id)) {
-      indeg.set(depId, indeg.get(depId) - 1);
-      if (indeg.get(depId) === 0) {
-        const dn = nodeById.get(depId);
-        let lo = 0;
-        while (lo < ready.length && ready[lo].seq < dn.seq) lo++;
-        ready.splice(lo, 0, dn);
-      }
-    }
-  }
-  if (ordered.length !== nodes.length) {
-    const stuck = nodes.filter((n) => !ordered.includes(n.stmt)).map((n) => n.stmt.label);
-    throw new Error(
-      `write-plan: the write-time transaction DAG has a CYCLE (unresolvable ordering among [${stuck.join(", ")}]). This is either a mutual '$.ref' data dependency or a gate that depends on a body row (a gate cannot depend on a not-yet-written row). ESCALATE: the Command's write dependencies are contradictory \u2014 no order satisfies both the data dependencies and gate-first. (Fail-closed; the derivation never guesses an order.)`
-    );
-  }
-  return ordered;
-}
-function deriveTransactionPlan(phase, bases, lifecycle, dialect = "sqlite") {
-  if (bases.length === 0) {
-    throw new Error("write-plan: a Command must declare at least one base write (Insert/Update/Delete).");
-  }
-  const nextId = makeIdGen();
-  const seqRef = { n: 0 };
-  const composite = bases.length > 1;
-  const allNodes = [];
-  const bodyIds = [];
-  bases.forEach((base, i) => {
-    const lc = base.effects !== void 0 ? { effects: base.effects } : i === 0 ? lifecycle : { effects: {} };
-    const { nodes, bodyId } = compileWriteGroup(base, lc, nextId, dialect, seqRef);
-    allNodes.push(...nodes);
-    bodyIds.push(bodyId);
-  });
-  const statements = topoOrder(allNodes);
-  const soleBody = bases[0];
-  const soleBodyId = bodyIds[0];
-  const usesEntity = referencesHead(statements, ENTITY_ROOT);
-  const soleBodyReturns = /\breturning\b/i.test(soleBody.op.sql);
-  if (usesEntity && composite) {
-    throw new Error(
-      `write-plan: a composite (multi-write) Command uses '$.entity.*' \u2014 ambiguous which write it denotes. Address each write's row by name via '$.ref.<writeName>.<field>' (fail-closed).`
-    );
-  }
-  if (usesEntity && !soleBodyReturns) {
-    throw new Error(
-      `write-plan: a derive/edges/emits stage references '$.entity.*' but the body write ('${soleBody.label}') has no RETURNING clause \u2014 the written row cannot be exposed to later stages. Add a RETURNING to the base write (fail-closed; no absent-entity default).`
-    );
-  }
-  const entityFrom = usesEntity || !composite && soleBodyReturns ? soleBodyId : null;
-  for (const base of bases) {
-    if (base.name === void 0) continue;
-    if (referencesHead(statements, base.name) && !/\breturning\b/i.test(base.op.sql)) {
-      throw new Error(
-        `write-plan: write '${base.name}' is referenced as '$.ref.${base.name}.*' by a later statement but its op has no RETURNING clause \u2014 its row cannot be bound for downstream writes. Add a RETURNING to write '${base.name}' (fail-closed; no absent-row default).`
-      );
-    }
-  }
-  return { phase, entityFrom, statements, onIdempotentHit: "rollback" };
+function makeIdGen() {
+  let n = 0;
+  return (role) => `tx_${role}_${n++}`;
 }
 function deriveBatchPlan(phase, ops) {
   if (ops.length === 0) {
@@ -5396,55 +5148,6 @@ function deriveBatchPlan(phase, ops) {
   }));
   return { phase, entityFrom: null, statements, onIdempotentHit: "rollback" };
 }
-function refHeadsOf(stmt) {
-  const heads = /* @__PURE__ */ new Set();
-  collectRefHeads(stmt.op.params, heads);
-  return [...heads];
-}
-function isInputHead(head, stmt) {
-  return refPathLengthFor(stmt.op.params, head) === 1;
-}
-function refPathLengthFor(node, head) {
-  let maxLen = 0;
-  const walk = (n) => {
-    if (n === null || typeof n !== "object") return;
-    if (Array.isArray(n)) {
-      for (const el of n) walk(el);
-      return;
-    }
-    const keys = Object.keys(n);
-    if (keys.length === 1 && keys[0] === "ref") {
-      const path = n.ref;
-      if (Array.isArray(path) && path[0] === head) maxLen = Math.max(maxLen, path.length);
-      return;
-    }
-    for (const k of keys) walk(n[k]);
-  };
-  walk(node);
-  return maxLen;
-}
-function referencesHead(statements, head) {
-  const heads = /* @__PURE__ */ new Set();
-  for (const s of statements) collectRefHeads(s.op.params, heads);
-  return heads.has(head);
-}
-function collectRefHeads(node, heads) {
-  if (node === null || typeof node !== "object") return;
-  if (Array.isArray(node)) {
-    for (const el of node) collectRefHeads(el, heads);
-    return;
-  }
-  const keys = Object.keys(node);
-  if (keys.length === 1 && keys[0] === "ref") {
-    const path = node.ref;
-    if (Array.isArray(path) && typeof path[0] === "string") heads.add(path[0]);
-    return;
-  }
-  for (const k of keys) collectRefHeads(node[k], heads);
-}
-function asContext(dbOrCtx) {
-  return "connectionFor" in dbOrCtx ? dbOrCtx : contextForDriver(dbOrCtx);
-}
 function toDriverParam(v, dialect) {
   if (typeof v === "bigint") {
     if (v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER)) return Number(v);
@@ -5462,12 +5165,6 @@ function renderStatement(op, scope, dialect) {
   const { sql: sql2, params } = evalAssemble(op, scope, dialect);
   return { sql: renderPlaceholders(sql2, dialect), params };
 }
-function execStatement(ctx, op, scope, dialect) {
-  const { sql: sql2, params } = evalAssemble(op, scope, dialect);
-  const hasReturn = /\bselect\b/i.test(sql2.slice(0, 8)) || /\breturning\b/i.test(sql2);
-  const out = executeSQL({ sql: sql2, params, write: true, returning: hasReturn, bigint: false }, { exec: ctx, dialect });
-  return hasReturn ? { rows: out, changes: out.length } : { rows: [], changes: Number(out[0]?.changes ?? 0) };
-}
 function gateShortCircuit(gate, result) {
   switch (gate) {
     case "existsElseRollback":
@@ -5480,60 +5177,13 @@ function gateShortCircuit(gate, result) {
       throw new Error(`scp write: unknown gate rule '${String(gate)}'`);
   }
 }
-function executeTransaction(db, plan, input, dialect = "sqlite") {
-  const outer = asContext(db);
-  const executed = [];
-  const scope = { ...input };
-  let entity = null;
-  const isBatch = plan.entityFrom === null && plan.statements.every((s) => s.gate === void 0 && s.binds === void 0 && s.role === "body");
-  const returnedRows = [];
-  try {
-    return withTransactionSync(
-      outer,
-      (ctx) => {
-        for (const stmt of plan.statements) {
-          const result = execStatement(ctx, stmt.op, scope, dialect);
-          executed.push(stmt.id);
-          if (stmt.gate !== void 0) {
-            const reason = gateShortCircuit(stmt.gate, result);
-            if (reason !== null) {
-              return { commit: false, value: { committed: false, shortCircuit: { statementId: stmt.id, reason }, entity: null, executed } };
-            }
-          }
-          if (stmt.id === plan.entityFrom) {
-            entity = result.rows.length > 0 ? result.rows[0] : null;
-            if (entity !== null) scope[ENTITY_ROOT] = entity;
-          }
-          if (stmt.binds !== void 0 && result.rows.length > 0) {
-            scope[stmt.binds] = result.rows[0];
-          }
-          if (isBatch && stmt.role === "body" && result.rows.length > 0) returnedRows.push(result.rows);
-        }
-        return { commit: true, value: { committed: true, entity, executed, ...returnedRows.length > 0 ? { returnedRows } : {} } };
-      },
-      dialect
-    );
-  } catch (e) {
-    throw mapSqliteError(e);
-  }
-}
-function countingDriver(db) {
-  const prepared = [];
-  const wrapped = {
-    prepare(sql2) {
-      prepared.push(sql2);
-      return db.prepare(sql2);
-    }
-  };
-  return { db: wrapped, prepared };
-}
 function renderTxStatement(op, scope, dialect = "sqlite") {
   return renderStatement(op, scope, dialect);
 }
 async function execStatementAsync(ctx, op, scope, dialect) {
   const { sql: sql2, params } = evalAssemble(op, scope, dialect);
   const hasReturn = /\bselect\b/i.test(sql2.slice(0, 8)) || /\breturning\b/i.test(sql2);
-  const out = await executeSQLAsync({ sql: sql2, params, write: true, returning: hasReturn, bigint: false }, { execAsync: ctx, dialect });
+  const out = await executeSQLAsync({ sql: sql2, params, write: { returning: hasReturn } }, { execAsync: ctx, dialect });
   return hasReturn ? { rows: out, changes: out.length } : { rows: [], changes: Number(out[0]?.changes ?? 0) };
 }
 function executeTransactionAsync(ctx, plan, input, dialect = "sqlite", options = {}) {
@@ -5743,8 +5393,8 @@ function declarationStub(leafName, args) {
   );
 }
 var Db = class {
-  static executeSQL(sql2, params, write, returning, bigint, whereDynamic, guard) {
-    return declarationStub("executeSQL", [sql2, params, write, returning, bigint, whereDynamic, guard]);
+  static executeSQL(sql2, params, opts) {
+    return declarationStub("executeSQL", [sql2, params, opts]);
   }
   static pluck(rows, col) {
     return declarationStub("pluck", [rows, col]);
@@ -5947,11 +5597,7 @@ function targetKeyCols(op) {
 }
 function relationGuard(op) {
   if (op.hardLimit === void 0) return null;
-  return {
-    limit: op.hardLimit,
-    ...op.targetTable !== void 0 ? { model: op.targetTable } : {},
-    relation: op.name
-  };
+  return { limit: op.hardLimit, model: op.targetTable, relation: op.name };
 }
 function bindKeys(op, tuples) {
   if (op.parentKeys !== void 0) return [encodeJsonParam(op.dialect, tuples.map((t) => [...t]))];
@@ -5969,7 +5615,10 @@ function runRelationOp(op, parents, db) {
   const tCols = targetKeyCols(op);
   const childCols = op.materializers;
   const boundParams = bindKeys(op, keys);
-  const rawRows = executeSafe(ctx, sql2, boundParams);
+  const rawRows = executeSafe(ctx, sql2, boundParams, {
+    write: false,
+    ...op.connection !== void 0 ? { db: op.connection } : {}
+  });
   assertRelationHardLimit(rawRows, relationGuard(op));
   const rows = materializeChildRows(rawRows, childCols);
   return { sql: sql2, keys, batch: groupByKey(rows, tCols) };
@@ -6089,27 +5738,6 @@ function annotateWriteBundleOutType(bundle, resolve) {
 }
 
 // src/scp/write-bundle.ts
-function writeLabelOf(sql2) {
-  const m = /^\s*(INSERT|UPDATE|DELETE)/i.exec(sql2);
-  return m === null ? "Write" : m[1][0].toUpperCase() + m[1].slice(1).toLowerCase();
-}
-function compileWriteBundle(name, base, writes, phase, dialectName = "sqlite", resolveColumnType) {
-  const lifecycle = lifecycleFor(writes, phase);
-  if (lifecycle === void 0) {
-    throw new Error(`scp write: the '${phase}' lifecycle is not declared in the entityWrites save contract`);
-  }
-  const plan = deriveTransactionPlan(phase, [{ op: base, label: writeLabelOf(base.sql) }], lifecycle, dialectName);
-  const bundle = { dialect: dialectName, name, statement: base, transaction: plan };
-  return resolveColumnType === void 0 ? bundle : annotateWriteBundleOutType(bundle, resolveColumnType);
-}
-function compileCompositeWriteBundle(entries, phase, dialectName = "sqlite") {
-  if (entries.length < 2) {
-    throw new Error("scp write: a composite write bundle needs at least 2 named write members (use compileWriteBundle for a single write).");
-  }
-  const bases = entries.map((e) => ({ op: e.base, label: `${writeLabelOf(e.base.sql)} ${e.name}`, name: e.name, effects: e.lifecycle.effects }));
-  const plan = deriveTransactionPlan(phase, bases, { effects: {} }, dialectName);
-  return { dialect: dialectName, name: entries[0].name, statement: entries[0].base, transaction: plan };
-}
 function flattenBatchOp(node, label) {
   const assembled = assembleMakeSQL(node);
   return { sql: assembled.sql, params: assembled.params, label };
@@ -6146,9 +5774,6 @@ function compileDeleteManyBundle(name, options, dialectName = "sqlite") {
   const plan = deriveBatchPlan("remove", ops);
   return { dialect: dialectName, name, statement: { sql: ops[0].sql, params: ops[0].params }, transaction: plan };
 }
-function executeTransactionBundle(bundle, input, options) {
-  return executeTransaction(options.db, bundle.transaction, input, bundle.dialect);
-}
 
 // src/decorators.ts
 var import_reflect_metadata = __toESM(require_Reflect());
@@ -6669,6 +6294,9 @@ function deriveModelColumns(modelClass, options = {}) {
 function tableNameOf(modelClass) {
   return modelClass.TABLE_NAME ?? modelClass.name.toLowerCase();
 }
+function connectionOf(modelClass) {
+  return modelClass.CONNECTION;
+}
 function compileCreateBundle(modelClass, name, options, dialect = "sqlite", columnsOptions) {
   const resolveColumnType = modelColumnResolver(modelClass, columnsOptions);
   return compileCreateManyBundle(name, options, dialect, resolveColumnType);
@@ -6709,12 +6337,14 @@ function relationDeclOf(rel, resolveTargetModel, dialect = "sqlite") {
   const targetTable = tableNameOf(targetModel);
   const select = targetProjection(targetModel);
   const order = rel.options?.order ? orderToString(rel.options.order()) : void 0;
+  const connection = connectionOf(targetModel);
   const base = {
     name: rel.propertyKey,
     kind: rel.type,
     targetTable,
     select,
     dialect,
+    ...connection !== void 0 ? { connection } : {},
     ...order !== void 0 ? { order } : {},
     ...rel.options?.limit !== void 0 ? { limit: rel.options.limit } : {},
     ...rel.options?.hardLimit !== void 0 ? { hardLimit: rel.options.hardLimit } : {}
@@ -6806,6 +6436,20 @@ var EmitContext = class {
   bindTypeOf(model, column2) {
     return tsScalar(sqlTypeToBcScalar(this.sqlTypeOf(model, column2)));
   }
+  /**
+   * The NAMED connection every statement of an endpoint declared over `model` runs on — read from the
+   * model, the ONE authority ({@link connectionOf}), and handed to {@link execOptions} as its `db`
+   * field. `{}` ⇒ the DEFAULT connection, which leaves a bounded read's option record unspelled
+   * entirely (native-clean).
+   *
+   * A RELATION's child fetch does NOT come through here: its connection is the TARGET model's, which
+   * `relationDeclOf` already resolved onto the compiled op (`RelationOp.connection`) — the emitter
+   * consumes that rather than re-deriving it from a second model handle.
+   */
+  dbOf(model) {
+    const db = connectionOf(model);
+    return db !== void 0 ? { db } : {};
+  }
   // ── methods ────────────────────────────────────────────────────────────────────────────────
   method(name, endpoint) {
     assertIdentifier(name, `endpoint name '${name}'`);
@@ -6869,12 +6513,7 @@ var EmitContext = class {
     const readResolve = endpoint.view !== void 0 ? (t, c) => resolve(t === alias ? baseTable : t, c) : resolve;
     const cap = this.bakedFindCap(endpoint);
     const where = endpoint.where ?? [];
-    const dynamic = where.some(isOptional);
-    if (dynamic && endpoint.view !== void 0) {
-      throw new Error(
-        `emit: endpoint '${name}': a QUERY view-model binds its own CTE params BEFORE the WHERE, and a dynamic (SKIP) WHERE is assembled at execution time \u2014 the two cannot share one param order. Declare the view's own predicate inside the view query, or drop the optional predicate.`
-      );
-    }
+    const optional = where.filter(isOptional);
     const params = [];
     for (const p of where) this.declareWhereParams(model, p, params);
     const limit = this.page(endpoint.limit ?? (cap !== null ? cap + 1 : void 0), params);
@@ -6883,15 +6522,21 @@ var EmitContext = class {
       dialect: this.spec.dialect,
       tableName: table,
       select: projection.join(", "),
-      ...dynamic ? {} : { conditions: this.conditions(model, where) },
+      // The BOUNDED predicates — this read's static WHERE, whatever else it declares. (An all-optional
+      // read compiles an EMPTY condition set, which is the same no-WHERE statement it always was.)
+      conditions: this.conditions(model, where.filter((p) => !isOptional(p))),
       ...endpoint.view !== void 0 ? { cte: cteOf(endpoint.view) } : {},
       ...endpoint.order !== void 0 ? { order: endpoint.order } : {},
       ...limit !== void 0 ? { limit } : {},
       ...offset !== void 0 ? { offset } : {},
       ...endpoint.lock === "update" ? { forUpdate: true } : endpoint.lock === "share" ? { forShare: true } : {}
     });
-    const bigint = endpoint.bigint === true;
-    const call = `${quote(compiled.sql)}, [${compiled.params.map(renderSlot).join(", ")}], false, false, ${bigint}${dynamic ? `, ${this.dynamicWherePlan(model, where)}` : ""}`;
+    const plan = optional.length > 0 ? this.dynamicWherePlan(model, optional, compiled) : void 0;
+    const [sql2, slots] = plan === void 0 ? [compiled.sql, compiled.params] : [compiled.head, compiled.headParams];
+    const call = `${quote(sql2)}, [${slots.map(renderSlot).join(", ")}]${execOptions({
+      ...this.dbOf(model),
+      ...plan !== void 0 ? { whereDynamic: plan } : {}
+    })}`;
     const rowObj = objOf(deriveReadRow(table, projection, readResolve, `endpoint '${name}'`).outType, name);
     const selections = normalizeSelections(endpoint.with ?? []);
     const fresh = freshNames(params.map((p) => p.name));
@@ -6908,24 +6553,35 @@ var EmitContext = class {
     const lines = [];
     const parentVar = fresh("rows");
     lines.push(`const ${parentVar}: WireValue[] = Db.executeSQL(${call});`);
-    const graph = this.relations(model, parentVar, rowObj, selections, lines, fresh, bigint, `endpoint '${name}'`);
+    const graph = this.relations(model, parentVar, rowObj, selections, lines, fresh, `endpoint '${name}'`);
     const rowType = this.declareInterface(`${cap1(name)}Row`, graph.obj);
     lines[lines.length - 1] = `const ${graph.terminalVar}: ${rowType}[] = ${graph.terminalCall} as ${rowType}[];`;
     lines.push(`return ${graph.terminalVar};`);
     return { name, params, returnType: `${rowType}[]`, lines };
   }
   /**
-   * The DYNAMIC WHERE plan expression: one fragment per declared predicate — `{sql, params}` from the
-   * SAME `compileWhere` that produces a bounded WHERE — with an optional one wrapped in a conditional
-   * that yields `null` when its parameter is absent. That is the whole fragment vocabulary.
+   * The DYNAMIC WHERE plan expression: ONE fragment per OPTIONAL predicate — never a bounded one, which
+   * is already in the static statement (CLAUDE.md §2) — every fragment the SAME struct
+   * `{skipped, sql, params}`, with `sql`/`params` from the SAME `compileWhere` that produces a bounded
+   * WHERE and `skipped` the per-call SKIP decision carried as DATA (`param === null`). That is the whole
+   * fragment vocabulary (SQL + params + a SKIP flag). The array is HOMOGENEOUS — never a `cond`-to-null
+   * element — so the go/rust native-codegen emitters resolve it (a variant/nullable array element is the
+   * one shape they reject); the `executeSQL` leaf drops the `skipped` fragments at run and continues the
+   * static WHERE with the survivors.
+   *
+   * The plan also carries what FINISHES the statement, taken straight off the bundle this same read
+   * compiled ({@link import('../makesql/compile-select').SelectBundle}): `lead` — the connector the first
+   * survivor joins with, which is `AND` exactly when the builder emitted a static WHERE — and `tail` /
+   * `tailParams`, the text and bound values that follow the WHERE region. The leaf then concatenates
+   * `head` + clause + `tail`; nothing on the run side has to find the boundary again, which is what a
+   * lexical scan got wrong on a nested statement (#198) and on a quoted `?` (#202).
    */
-  dynamicWherePlan(model, where) {
-    const frags = where.map((p) => {
+  dynamicWherePlan(model, optional, compiled) {
+    const frags = optional.map((p) => {
       const w = compileWhere(this.conditions(model, [p]), this.spec.dialect);
-      const frag = `{ sql: ${quote(w.sql)}, params: [${w.params.map(renderSlot).join(", ")}] }`;
-      return isParameterised(p) && p.optional === true ? `${p.param} !== null ? ${frag} : null` : frag;
+      return `{ skipped: ${p.param} === null, sql: ${quote(w.sql)}, params: [${w.params.map(renderSlot).join(", ")}] }`;
     });
-    return `{ frags: [${frags.join(", ")}] }`;
+    return `{ frags: [${frags.join(", ")}], lead: ${quote(compiled.lead)}, tail: ${quote(compiled.tail)}, tailParams: [${compiled.tailParams.map(renderSlot).join(", ")}] }`;
   }
   /**
    * Emit ONE relation LEVEL: for each selected relation, pluck the parent key set, run the ONE batched
@@ -6933,7 +6589,7 @@ var EmitContext = class {
    * selection recurses FIRST, so a grandchild level is grouped into its own parent before that parent
    * is grouped into ours (one query per depth — never one per parent).
    */
-  relations(model, parentVar, parentObj, selections, lines, fresh, bigint, at) {
+  relations(model, parentVar, parentObj, selections, lines, fresh, at) {
     let acc = parentVar;
     const obj = { ...parentObj };
     let terminalCall = "";
@@ -6945,15 +6601,20 @@ var EmitContext = class {
       lines.push(`const ${keysVar}: WireValue[] = Db.pluck(${acc}, ${jsonArray(parentKeyCols(op))});`);
       const childVar = fresh(sel.name);
       const guard = relationGuard(op);
-      const guardPorts = guard !== null ? `, null, ${JSON.stringify(guard)}` : "";
-      lines.push(`const ${childVar}: WireValue[] = Db.executeSQL(${quote(op.sql)}, [${keysVar}], false, false, ${bigint}${guardPorts});`);
+      const guardExpr = guard !== null ? `{ limit: ${guard.limit} as Int, model: ${quote(guard.model)}, relation: ${quote(guard.relation)} }` : void 0;
+      lines.push(
+        `const ${childVar}: WireValue[] = Db.executeSQL(${quote(op.sql)}, [${keysVar}]${execOptions({
+          ...op.connection !== void 0 ? { db: op.connection } : {},
+          ...guardExpr !== void 0 ? { guard: guardExpr } : {}
+        })});`
+      );
       let childRows = childVar;
       let childObj = objOf(
         deriveReadRow(decl.targetTable, decl.select, this.resolver(targetModel), `${at} relation '${sel.name}'`).outType,
         `${at} relation '${sel.name}'`
       );
       if (sel.with.length > 0) {
-        const nested = this.relations(targetModel, childVar, childObj, normalizeSelections(sel.with), lines, fresh, bigint, `${at}.${sel.name}`);
+        const nested = this.relations(targetModel, childVar, childObj, normalizeSelections(sel.with), lines, fresh, `${at}.${sel.name}`);
         childObj = nested.obj;
         childRows = nested.terminalVar;
       }
@@ -7010,7 +6671,7 @@ var EmitContext = class {
       params,
       returnType: `${rowType}[]`,
       lines: [
-        `const ${out}: ${rowType}[] = Db.executeSQL(${quote(op.sql)}, [${op.params.map(renderSlot).join(", ")}], true, ${returning !== void 0}, false) as ${rowType}[];`,
+        `const ${out}: ${rowType}[] = Db.executeSQL(${quote(op.sql)}, [${op.params.map(renderSlot).join(", ")}]${execOptions({ ...this.dbOf(model), write: { returning: returning !== void 0 } })}) as ${rowType}[];`,
         `return ${out};`
       ]
     };
@@ -7087,7 +6748,7 @@ var EmitContext = class {
       params,
       returnType: `${rowType}[]`,
       lines: [
-        `const ${out}: ${rowType}[] = Db.executeSQL(${quote(op.sql)}, [${slots.join(", ")}], true, ${endpoint.returning !== void 0}, false) as ${rowType}[];`,
+        `const ${out}: ${rowType}[] = Db.executeSQL(${quote(op.sql)}, [${slots.join(", ")}]${execOptions({ ...this.dbOf(model), write: { returning: endpoint.returning !== void 0 } })}) as ${rowType}[];`,
         `return ${out};`
       ]
     };
@@ -7115,7 +6776,7 @@ var EmitContext = class {
       params,
       returnType: `${rowType}[]`,
       lines: [
-        `const ${out}: ${rowType}[] = Db.executeSQL(${quote(op.sql)}, [${op.params.map(renderSlot).join(", ")}], true, ${endpoint.returning !== void 0}, false) as ${rowType}[];`,
+        `const ${out}: ${rowType}[] = Db.executeSQL(${quote(op.sql)}, [${op.params.map(renderSlot).join(", ")}]${execOptions({ ...this.dbOf(model), write: { returning: endpoint.returning !== void 0 } })}) as ${rowType}[];`,
         `return ${out};`
       ]
     };
@@ -7333,6 +6994,11 @@ function isParameterised(p) {
 function isOptional(p) {
   return isParameterised(p) && p.optional === true;
 }
+function execOptions(o) {
+  if (o.db === void 0 && o.write === void 0 && o.whereDynamic === void 0 && o.guard === void 0) return "";
+  const write = o.write === void 0 ? "null" : `{ returning: ${o.write.returning} }`;
+  return `, { db: ${o.db === void 0 ? "null" : quote(o.db)}, write: ${write}, whereDynamic: ${o.whereDynamic ?? "null"}, guard: ${o.guard ?? "null"} }`;
+}
 function renderSlot(slot) {
   if (slot instanceof ParamRef) return slot.expr;
   const ref = slot?.__batchArray?.ref;
@@ -7507,20 +7173,13 @@ var RelationContext = class {
   ops;
   db;
   hydrate;
-  /** CROSS-DB (V0 R1): name → driver registry; a tagged relation routes to `connections[tag]`. */
-  connections;
   /** Per-relation resolved batch (name → grouping), memoized: one batch query per relation. */
   resolved = /* @__PURE__ */ new Map();
-  constructor(siblings, ops, db, hydrate, connections) {
+  constructor(siblings, ops, db, hydrate) {
     this.siblings = siblings;
     this.ops = ops;
     this.db = db;
     this.hydrate = hydrate;
-    this.connections = connections;
-  }
-  /** The driver a relation runs against: its tagged cross-DB connection, else the primary `db`. */
-  driverFor(op) {
-    return op.connection === void 0 ? this.db : driverForOp(op, this.connections);
   }
   /**
    * Resolve `relationName` for `parent` (lazy access). The relation is batch-loaded across
@@ -7534,19 +7193,12 @@ var RelationContext = class {
     }
     let batch = this.resolved.get(relationName);
     if (batch === void 0) {
-      batch = runRelationOp(op, this.siblings, this.driverFor(op)).batch;
+      batch = runRelationOp(op, this.siblings, this.db).batch;
       this.resolved.set(relationName, batch);
     }
     return applyHydrate(distributeToParent(op, parent, batch), this.hydrate);
   }
 };
-function driverForOp(op, connections) {
-  const d = connections?.[op.connection];
-  if (d === void 0) {
-    throw new Error(`cross-DB relation '${op.name}': no driver registered for connection '${op.connection}' (pass it in ReadOptions.connections)`);
-  }
-  return d;
-}
 function readRelationContext(o) {
   const v = o[RELATION_CONTEXT];
   return v instanceof RelationContext ? v : void 0;
@@ -7584,7 +7236,7 @@ function buildResultSet(rawRows, ops, db, options = {}) {
     for (const k of Object.keys(raw)) o[k] = raw[k];
     return o;
   });
-  const ctx = new RelationContext(rows, ops, db, hydrate, options.connections);
+  const ctx = new RelationContext(rows, ops, db, hydrate);
   for (const o of rows) {
     Object.defineProperty(o, RELATION_CONTEXT, {
       value: ctx,
@@ -7596,8 +7248,7 @@ function buildResultSet(rawRows, ops, db, options = {}) {
   for (const name of Object.keys(selected)) {
     const op = ops[name];
     if (op === void 0) throw new Error(`declarative select: relation '${name}' is not declared on this model`);
-    const relDb = op.connection === void 0 ? db : driverForOp(op, options.connections);
-    const { batch } = runRelationOp(op, rows, relDb);
+    const { batch } = runRelationOp(op, rows, db);
     for (const o of rows) {
       o[name] = applyHydrate(distributeToParent(op, o, batch), hydrate);
     }
@@ -7616,7 +7267,6 @@ export {
   DEFAULT_CONNECTION,
   DEFAULT_UNCAST_SQL_TYPE,
   Db,
-  ENTITY_ROOT,
   LEAF_TRANSPORT_SYMBOLS,
   LITEDBMODEL_MAKESQL_CATALOG,
   LimitExceededError,
@@ -7653,7 +7303,6 @@ export {
   compileCompositeKeyLimited,
   compileCompositeKeyStaticUnlimited,
   compileCompositeKeyUnlimited,
-  compileCompositeWriteBundle,
   compileCreateBundle,
   compileCreateManyBundle,
   compileDeleteBundle,
@@ -7672,7 +7321,6 @@ export {
   compileUpdateManyBundle,
   compileUpdateSingle,
   compileWhere,
-  compileWriteBundle,
   compileWriteNode,
   composeMakeSQL,
   configurePgDeboxTypeParsers,
@@ -7680,7 +7328,6 @@ export {
   connectionForDriver,
   contextForConnection,
   contextForDriver,
-  countingDriver,
   createMiddleware,
   currentPinnedAsyncConnection,
   currentRegistry,
@@ -7688,20 +7335,15 @@ export {
   dbCastIn,
   deriveModelColumns,
   deriveRelationDecls,
-  deriveTransactionPlan,
   dialectFor,
   distributeToParent,
-  edgeWrites,
   emitBehaviorModule,
-  entityWrites,
   execute,
   executeAsync,
   executeSQL,
   executeSQLAsync,
   executeSafe,
-  executeTransaction,
   executeTransactionAsync,
-  executeTransactionBundle,
   failClosedMaterializeResolverFromColumnMap,
   formatterFor,
   getLimitConfig,
@@ -7716,7 +7358,6 @@ export {
   leaf2 as leaf,
   leafHandlers,
   leafHandlersAsync,
-  lifecycleFor,
   makeSqlCatalogEntry,
   makeSqlHandler,
   makeSqlHandlerSync,
@@ -7731,7 +7372,6 @@ export {
   mysqlPoolFactory,
   noCastFormatter,
   opt,
-  parseEffectPath,
   parseSchemaColumnTypes,
   pgCastFormatter,
   pgConnectionPool,
@@ -7772,7 +7412,6 @@ export {
   setLimitConfig,
   singlePoolPair,
   sleep,
-  spliceWhere,
   sqlTypeToBcScalar,
   sqlTypeToMaterializeClass,
   stripMysqlPkHint,