@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/db/query.js

@@ -1,4 +1,4 @@
-// Typed query helpers over the postgres-js driver: EntityTableMeta in, rows out.
+// Typed query helpers over the Bun.SQL driver: EntityTableMeta in, rows out.
 //
 // API:
 //   selectMany<T>(db, table, where?, opts?) → readonly T[]
@@ -12,33 +12,19 @@
 //   transaction<T>(db, fn) → T
 //
 // `table` is an EntityTableMeta; the legacy table objects carrying it under a Symbol are accepted too.
-// Static import (not getTemporal()): coercion works without an installed
-// global and returns the same Temporal classes as the rest of the repo.
-import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { isOneOf, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
-import { requestContext } from "../api/request-context.js";
-import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
-import { isPiiCiphertext } from "../crypto/pii-ciphertext-format.js";
-import { camelCase as envCamelCase } from "../env/index.js";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { quoteIdent } from "../crypto/ciphertext-pattern.js";
 import { InternalError } from "../errors/index.js";
-import { createFallbackLogger } from "../logging/index.js";
-import { parseJsonSafe } from "../utils/safe-json.js";
-import { SQL_EXPR_BRAND } from "./dialect.js";
+import { aggregateDimensionSql, aggregateGroupOrderLimitSql, aggregateKeyOf, aggregateMeasureSql, assertValidAggregateLimits, } from "./aggregate-sql.js";
+import { isClosedConnectionError, isPooledClient, logClosedConnection, poolMaxOf, } from "./closed-connection.js";
 import { buildDistinctOnClause } from "./distinct-on.js";
+import { coerceDriverRow } from "./driver-row-coercion.js";
+import { prepareValue } from "./driver-value-preparation.js";
 import { executorManagedWriteDenied } from "./executor-managed-tables.js";
 import { extractPgError } from "./pg-error.js";
-import { toSnakeCase } from "./table-builder.js";
+import { extractTableInfo } from "./table-info.js";
 import { asEntityTableMeta, requireEntityTableMeta } from "./table-introspection.js";
-// Idempotent snake_case → camelCase. `env.camelCase` always lowercases first
-// (designed for SHOUT_CASE input) — for already-camelCase keys (mock rows
-// in tests, projection-aliased columns) it would silently produce "tenantid"
-// instead of leaving "tenantId" alone. Guard with an underscore check so
-// the conversion only fires when the key is actually snake-shaped.
-function snakeToCamel(key) {
-    if (!key.includes("_"))
-        return key;
-    return envCamelCase(key);
-}
+import { buildWhereClause } from "./where-clause.js";
 // table() (dialect) stores the canonical, shadow-proof EntityTableMeta under
 // `Symbol.for("kumiko:schema:Meta")`. The column handles on the table object are
 // enumerable props, so an entity field named `source`/`columns`/`tableName`/…
@@ -53,9 +39,9 @@ function isRawClient(value) {
     return typeof propertyOf(value, "unsafe") === "function";
 }
 export function asRawClient(db) {
-    // Direct: postgres-js Sql / TransactionSql. Both
-    // expose `.unsafe`; only Sql has `.begin` — TransactionSql uses
-    // `.savepoint` for nested-tx. We only require `.unsafe` here; callers that
+    // Direct: Bun.SQL pool / transaction handle. Both
+    // expose `.unsafe`; only the pool starts a transaction — a transaction handle uses
+    // `.savepoint` for nesting. We only require `.unsafe` here; callers that
     // need `.begin` (e.g. `transaction()`) verify it themselves.
     if (isRawClient(db))
         return db;
@@ -66,15 +52,15 @@ export function asRawClient(db) {
             "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw() with escapeHatch: " +
             "{ reason } on the handler/hook (r.systemScope() features: ctx.systemDb.unsafeRaw(reason)).");
     }
-    // Wrapper handle: $client = postgres-js Sql.
+    // Wrapper handle: $client = Bun.SQL pool.
     const $client = propertyOf(db, "$client");
     if (isRawClient($client))
         return $client;
-    // Wrapper transaction handle: session.client = postgres-js Sql.
+    // Wrapper transaction handle: session.client = Bun.SQL pool.
     const sessionClient = propertyOf(propertyOf(db, "session"), "client");
     if (isRawClient(sessionClient))
         return sessionClient;
-    throw new Error("asRawClient: db argument has no .unsafe() — pass a postgres-js Sql or a transaction handle.");
+    throw new Error("asRawClient: db argument has no .unsafe() — pass a Bun.SQL pool or a transaction handle.");
 }
 export function runnerCanBeginTransaction(db) {
     return hasBegin(asRawClient(db));
@@ -86,10 +72,31 @@ function savepointRunnerOf(sp) {
 export async function runInSavepoint(tx, fn) {
     const raw = asRawClient(tx);
     if (typeof raw.savepoint !== "function") {
-        throw new Error("runInSavepoint: transaction handle has no savepoint() — pass the driver tx (postgres.js TransactionSql).");
+        throw new Error("runInSavepoint: transaction handle has no savepoint() — pass the driver tx (Bun.SQL TransactionSQL).");
     }
     return raw.savepoint((sp) => fn(savepointRunnerOf(sp)));
 }
+// Same error-confinement as runInSavepoint, but for call sites that don't
+// know whether `db` is a bare pool connection or an active transaction
+// (e.g. the CRUD executor, invoked both from a dispatcher tx and directly
+// against the pool by seeds/tests). A pool connection has no savepoint() —
+// and doesn't need one, since each statement there is its own auto-committed
+// unit and a failed statement can't poison anything downstream.
+//
+// `.savepoint` being present isn't proof the transaction is still open: a
+// committed transaction handle still exposes `.savepoint`, and calling it
+// fails (Bun.SQL: ERR_POSTGRES_INVALID_TRANSACTION_STATE, Postgres: 25P01)
+// since there's no BEGIN left to nest into. That is now a programming error, not something
+// to paper over by re-running `fn` without the savepoint's isolation.
+const CONNECTION_CLOSED_CODE = "ERR_POSTGRES_CONNECTION_CLOSED";
+const SAVEPOINT_ON_COMMITTED_CODES = new Set([
+    "25P01",
+    "ERR_POSTGRES_INVALID_TRANSACTION_STATE",
+]);
+function isSavepointOnDeadTransactionCode(code) {
+    return (code !== undefined &&
+        (code === CONNECTION_CLOSED_CODE || SAVEPOINT_ON_COMMITTED_CODES.has(code)));
+}
 export async function runInSavepointIfSupported(db, fn) {
     const raw = asRawClient(db);
     if (typeof raw.savepoint !== "function")
@@ -104,17 +111,17 @@ export async function runInSavepointIfSupported(db, fn) {
     }
     catch (e) {
         const code = extractPgError(e)?.code;
-        if (!fnStarted && (code === "25P01" || code === "ERR_POSTGRES_CONNECTION_CLOSED")) {
+        if (!fnStarted && isSavepointOnDeadTransactionCode(code)) {
             throw new InternalError({
-                message: code === "25P01"
-                    ? "runInSavepointIfSupported: savepoint on a transaction that has already committed — " +
-                        "this is almost always database work in an afterCommit hook. afterCommit is the default " +
-                        "phase of r.hook/postSave/postDelete. Use HookPhases.inTransaction for writes that must " +
-                        "roll back with the trigger, or ctx.dbOutsideTransaction for work that must survive a rollback."
-                    : "runInSavepointIfSupported: the transaction handle's connection is gone — the transaction " +
+                message: code === CONNECTION_CLOSED_CODE
+                    ? "runInSavepointIfSupported: the transaction handle's connection is gone — the transaction " +
                         "already committed (almost always database work in an afterCommit hook) or the connection dropped. " +
                         "afterCommit is the default phase of r.hook/postSave/postDelete. Use HookPhases.inTransaction " +
-                        "for writes that must roll back with the trigger, or ctx.dbOutsideTransaction for work that must survive a rollback.",
+                        "for writes that must roll back with the trigger, or ctx.dbOutsideTransaction for work that must survive a rollback."
+                    : "runInSavepointIfSupported: savepoint on a transaction that has already committed — " +
+                        "this is almost always database work in an afterCommit hook. afterCommit is the default " +
+                        "phase of r.hook/postSave/postDelete. Use HookPhases.inTransaction for writes that must " +
+                        "roll back with the trigger, or ctx.dbOutsideTransaction for work that must survive a rollback.",
                 cause: e instanceof Error ? e : undefined,
             });
         }
@@ -145,677 +152,20 @@ function assertNotTenantScoped(db, fnName) {
     if (tenantDbDelegate(db) !== undefined) {
         throw new Error(`${fnName}: received a tenant-scoped db but this helper does not apply the tenant filter. ` +
             "Pass ctx.db.unsafeRaw() (with escapeHatch: { reason } on the handler/hook) for an " +
-            "explicit cross-tenant op, or use a scoped TenantDb method.");
-    }
-}
-const WHERE_OPERATOR_KEYS = [
-    "gt",
-    "gte",
-    "lt",
-    "lte",
-    "ne",
-    "in",
-    "notIn",
-    "like",
-    "jsonText",
-];
-const _whereOperatorKeysExhaustive = true;
-void _whereOperatorKeysExhaustive;
-function isJsonTextMatchList(value) {
-    return Array.isArray(value);
-}
-function isWhereOperator(v) {
-    if (v === null || typeof v !== "object" || Array.isArray(v))
-        return false;
-    // Don't false-positive on Date / Temporal / other domain-objects.
-    // WhereOperator is plain object literal with at most these keys.
-    const keys = Object.keys(v);
-    if (keys.length === 0)
-        return false;
-    return keys.every((k) => isOneOf(WHERE_OPERATOR_KEYS, k));
-}
-export function extractTableInfo(table) {
-    const meta = asEntityTableMeta(table);
-    if (!meta) {
-        throw new Error("extractTableInfo: table is not a kumiko EntityTableMeta — " +
-            "build it via buildEntityTable / deriveEntityTableMeta / table().");
+            "explicit cross-tenant op, or use a scoped TenantDb method " +
+            "(for an upsert: ctx.db.upsert(table, values, { conflictTarget })).");
     }
-    const colByField = new Map();
-    const fieldByCol = new Map();
-    const typeByCol = new Map();
-    const bigintModeByCol = new Map();
-    for (const c of meta.columns) {
-        typeByCol.set(c.name, c.pgType);
-        if (c.bigintJsMode !== undefined)
-            bigintModeByCol.set(c.name, c.bigintJsMode);
-        // EntityTableMeta column names are snake_case. Map snake → snake AND
-        // derive a camelCase JS field-name so result rows can be renamed back
-        // to the API shape (`aggregate_id` → `aggregateId`).
-        colByField.set(c.name, c.name);
-        const camel = snakeToCamel(c.name);
-        if (camel !== c.name)
-            colByField.set(camel, c.name);
-        fieldByCol.set(c.name, camel === c.name ? c.name : camel);
-    }
-    return {
-        name: meta.tableName,
-        columnOf: (field) => colByField.get(field) ?? toSnakeCase(field),
-        pgTypeOf: (col) => typeByCol.get(col),
-        bigintJsModeOf: (col) => bigintModeByCol.get(col),
-        fieldOf: (col) => fieldByCol.get(col) ?? snakeToCamel(col),
-        hasColumn: (fieldOrColumn) => colByField.has(fieldOrColumn) || fieldByCol.has(fieldOrColumn),
-    };
-}
-function quoteIdent(name) {
-    return `"${name.replace(/"/g, '""')}"`;
-}
-// --- Value coercion at the driver boundary ------------------------------
-//
-// postgres-js returns timestamptz as JS Date (or ISO string depending on
-// driver config). Framework contract says timestamptz surfaces as
-// Temporal.Instant — without coercion every read hands callers a Date and
-// downstream code that does .epochMilliseconds / .add(...) crashes.
-//
-// Symmetric on write: Temporal.Instant doesn't bind directly into postgres-js
-// params — convert to ISO string when the column pgType is timestamptz.
-function isTemporalInstant(v) {
-    return propertyOf(v, Symbol.toStringTag) === "Temporal.Instant";
 }
-// Postgres bigint → JS: safe integers become `number` (matches createBigIntField /
-// drizzle mode:"number"); values outside ±2^53 stay `bigint` (money cents, raw
-// unmanaged columns). Uses BigInt equality check so 9007199254740993n never
-// silently rounds to a safe integer.
-function coerceBigIntFromDriver(value) {
-    let bi;
-    if (typeof value === "string") {
-        try {
-            bi = BigInt(value);
-        }
-        catch {
-            return value;
-        }
-    }
-    else {
-        bi = value;
-    }
-    const min = BigInt(Number.MIN_SAFE_INTEGER);
-    const max = BigInt(Number.MAX_SAFE_INTEGER);
-    if (bi >= min && bi <= max) {
-        const n = Number(bi);
-        if (BigInt(n) === bi)
-            return n;
-    }
-    return bi;
-}
-function instantFromDriver(value) {
-    if (value === null || value === undefined)
-        return null;
-    if (isTemporalInstant(value))
-        return value;
-    // Number coercion via +date — equivalent to .getTime() without a Date-API
-    // method (guard-no-date-api). Date → epoch milliseconds, then to Temporal.Instant.
-    if (value instanceof Date)
-        return Temporal.Instant.fromEpochMilliseconds(+value);
-    if (typeof value === "string") {
-        try {
-            return Temporal.Instant.from(value);
-        }
-        catch {
-            return null;
-        }
-    }
-    if (typeof value === "number")
-        return Temporal.Instant.fromEpochMilliseconds(value);
-    return null;
-}
-function isTemporalPlainDate(v) {
-    return propertyOf(v, Symbol.toStringTag) === "Temporal.PlainDate";
-}
-function isTemporalPlainDateTimeLike(v) {
-    const tag = propertyOf(v, Symbol.toStringTag);
-    return ((tag === "Temporal.PlainDateTime" || tag === "Temporal.ZonedDateTime") &&
-        typeof v === "object" &&
-        v !== null &&
-        "toPlainDate" in v &&
-        typeof v.toPlainDate === "function");
-}
-// Verified empirically: a `date`
-// column comes back as a native JS Date, but ALWAYS anchored at UTC
-// midnight regardless of process TZ — epochMilliseconds is stable across
-// zones, only the local wall-clock read of that Date would drift the day
-// (e.g. America/Los_Angeles reads back the 14th for a stored 15th). Routing
-// through Instant→ZonedDateTimeISO("UTC")→PlainDate reads the calendar day
-// back deterministically without ever touching a local Date getter — the
-// same +value idiom instantFromDriver uses (guard-no-date-api: no
-// `.getTime()`), just anchored to a fixed zone instead of process-local.
-// A real `date` column always arrives as a UTC-midnight Date. Anything else means the column is
-// still timestamptz (declared `date` before its ALTER ran); the UTC anchor then silently shifts
-// the day, so say so once per column instead of returning the wrong day quietly.
-const warnedNonMidnightDateColumns = new Set();
-const MS_PER_DAY = 86_400_000;
-const dateColumnDriftLog = createFallbackLogger("postgres-js");
-function warnIfNotDateColumn(epochMs, column) {
-    // skip: midnight value is a correct date column, and an already-warned column is deduped
-    if (epochMs % MS_PER_DAY === 0 || warnedNonMidnightDateColumns.has(column))
-        return;
-    warnedNonMidnightDateColumns.add(column);
-    dateColumnDriftLog.warn(`column "${column}" is declared as date but returned a non-midnight timestamp; it is probably still timestamptz. Run the ALTER ... TYPE date migration, otherwise days can shift.`);
-}
-function plainDateFromDriver(value, column) {
-    if (value === null || value === undefined)
-        return null;
-    if (isTemporalPlainDate(value))
-        return value;
-    if (typeof value === "string") {
-        const isoDay = /^\d{4}-\d{2}-\d{2}/.exec(value)?.[0];
-        if (isoDay === undefined)
-            return null;
-        try {
-            return Temporal.PlainDate.from(isoDay);
-        }
-        catch {
-            return null;
-        }
-    }
-    if (value instanceof Date) {
-        warnIfNotDateColumn(+value, column);
-        return Temporal.Instant.fromEpochMilliseconds(+value).toZonedDateTimeISO("UTC").toPlainDate();
-    }
-    return null;
-}
-// Walk the driver-row, applying three boundary-conversions per known column:
-//   - rename key snake_case → camelCase JS field-name (drizzle did this
-//     invisibly via its column-mapper; native dialect rebuild lost it)
-//   - parse jsonb string → object (postgres-js returns jsonb as text by
-//     default, not parsed JSON)
-//   - coerce timestamptz Date/string → Temporal.Instant
-//
-// Unknown columns (computed/aliased) pass through unchanged.
 export function coerceRow(row, info) {
     // @cast-boundary db-row — the driver row (raw column names/types) becomes the caller's entity row shape here, and only here
     return coerceDriverRow(row, info);
 }
-function coerceDriverRow(row, info) {
-    const out = {};
-    let changed = false;
-    for (const key of Object.keys(row)) {
-        // Blind-index columns are pure lookup artifacts — the
-        // deterministic HMAC must never leak into caller/API responses.
-        if ((key.endsWith("_bidx") || key.endsWith("Bidx")) && info.hasColumn(key)) {
-            changed = true;
-            continue;
-        }
-        const pgType = info.pgTypeOf(key);
-        const value = row[key];
-        let coerced = value;
-        if (pgType === "timestamptz" || pgType === "timestamptz(3)") {
-            const t = instantFromDriver(value);
-            if (t !== null)
-                coerced = t;
-        }
-        else if (pgType === "date") {
-            const d = plainDateFromDriver(value, key);
-            if (d !== null)
-                coerced = d;
-        }
-        else if (pgType === "jsonb" && typeof value === "string") {
-            coerced = parseJsonSafe(value, value);
-        }
-        else if ((pgType === "bigint" || pgType === "bigserial") &&
-            (typeof value === "string" || typeof value === "bigint")) {
-            const jsMode = info.bigintJsModeOf(key);
-            if (jsMode === "number") {
-                coerced = coerceBigIntFromDriver(value);
-            }
-            else if (typeof value === "string") {
-                try {
-                    coerced = BigInt(value);
-                }
-                catch {
-                    // leave as string on parse error
-                }
-            }
-            else {
-                coerced = value;
-            }
-        }
-        else if ((pgType === "integer" || pgType === "int4" || pgType === "smallint" || pgType === "int2") &&
-            (typeof value === "bigint" || typeof value === "string")) {
-            // Drivers may return int4 as bigint or numeric string.
-            // Drizzle coerced to number for numberField columns — match that.
-            const n = Number(value);
-            if (!Number.isNaN(n))
-                coerced = n;
-        }
-        else if (typeof pgType === "string" &&
-            pgType.startsWith("numeric") &&
-            (typeof value === "string" || typeof value === "bigint")) {
-            // pg returns numeric(p,s) as a string to preserve precision; the
-            // decimal-field contract surfaces it as JS number (safe ≤ 2^53). A
-            // non-numeric string would be DB corruption — leave it untouched so it
-            // surfaces loud downstream rather than becoming a silent NaN.
-            const n = Number(value);
-            if (!Number.isNaN(n))
-                coerced = n;
-        }
-        const fieldName = info.fieldOf(key);
-        if (fieldName !== key)
-            changed = true;
-        if (coerced !== value)
-            changed = true;
-        out[fieldName] = coerced;
-    }
-    return changed ? out : row;
-}
 function coerceRows(rows, info) {
     return rows.map((r) => coerceRow(r, info));
 }
-// Checks the brand Symbol, not the `kind` string — a client-supplied jsonb
-// value can fake `kind: "sql-expr"` over JSON but can never carry a Symbol,
-// so request data can't be smuggled in as a raw SQL literal.
-function isSqlExpression(v) {
-    return typeof v === "object" && v !== null && SQL_EXPR_BRAND in v;
-}
-// A `date` column takes a plain "yyyy-mm-dd" string (or PlainDate.toString())
-// as-is — no Instant detour. Postgres parses a DATE literal without ever
-// consulting the session timezone, so this is TZ-independent by construction
-// (verified empirically — see plainDateFromDriver above for the read side).
-// Compat cushion: code (this field used to be an Instant) may still
-// hand a Temporal.Instant into a where-filter or write on a `date` column —
-// same UTC anchor as plainDateFromDriver's read side, so a filter built with
-// `Temporal.Now.instant()` keeps working instead of binding a raw Instant the
-// driver can't serialize.
-function prepareDateValue(value) {
-    if (isTemporalPlainDate(value)) {
-        return { kind: "param", sql: "", bound: value.toString() };
-    }
-    if (isTemporalPlainDateTimeLike(value)) {
-        return { kind: "param", sql: "", bound: value.toPlainDate().toString() };
-    }
-    if (isTemporalInstant(value)) {
-        const day = value.toZonedDateTimeISO("UTC").toPlainDate();
-        return { kind: "param", sql: "", bound: day.toString() };
-    }
-    return undefined;
-}
-// structured values bind directly with an ::jsonb cast; JSON.stringify first
-// would produce a JSON-string scalar instead of the structured value.
-function prepareJsonbValue(value) {
-    if (typeof value === "boolean") {
-        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
-    }
-    if (typeof value !== "object" || isTemporalInstant(value)) {
-        return undefined;
-    }
-    if (!Array.isArray(value)) {
-        return { kind: "param", sql: "::jsonb", bound: value };
-    }
-    // All-boolean arrays are inferred as boolean[] by postgres-js; route via text::jsonb.
-    if (value.length > 0 && value.every((entry) => typeof entry === "boolean")) {
-        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
-    }
-    return { kind: "param", sql: "::jsonb", bound: value };
-}
-const INTEGER_PG_TYPES = new Set([
-    "integer",
-    "int4",
-    "smallint",
-    "int2",
-    "bigint",
-    "int8",
-    "serial",
-    "bigserial",
-]);
-// Postgres rounds sub-millisecond params into timestamptz(3); truncating to ms here keeps the
-// stored instant identical across drivers and equal to what postgres.js sends via Date.
-export function instantToTimestamptzParam(instant) {
-    return Temporal.Instant.fromEpochMilliseconds(instant.epochMilliseconds).toString();
-}
-function prepareDriverNeutralScalar(value, pgType) {
-    if ((pgType === "timestamptz" || pgType === "timestamptz(3)") && isTemporalInstant(value)) {
-        return { kind: "param", sql: "", bound: instantToTimestamptzParam(value) };
-    }
-    // postgres.js sends text, so Postgres rejects 3.5 for an integer column instead of rounding it.
-    if (typeof value === "number" && pgType !== undefined && INTEGER_PG_TYPES.has(pgType)) {
-        return { kind: "param", sql: "", bound: String(value) };
-    }
-    return undefined;
-}
-function prepareValue(value, pgType) {
-    if (isSqlExpression(value)) {
-        return { kind: "literal", literal: value.text };
-    }
-    // A PII-encrypted jsonb field is a JSON string scalar; a raw string bound to
-    // ::jsonb would be parsed as JSON text (or double-encoded).
-    if (pgType === "jsonb" && isPiiCiphertext(value)) {
-        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
-    }
-    if (pgType === "jsonb" && value !== null) {
-        const prepared = prepareJsonbValue(value);
-        if (prepared)
-            return prepared;
-    }
-    const scalar = prepareDriverNeutralScalar(value, pgType);
-    if (scalar)
-        return scalar;
-    if (pgType === "date") {
-        const prepared = prepareDateValue(value);
-        if (prepared)
-            return prepared;
-    }
-    return { kind: "param", sql: "", bound: value };
-}
-function buildWhereClause(info, where, startIndex, qualifier) {
-    const conditions = [];
-    const values = [];
-    let idx = startIndex;
-    // Single place that renders a column reference, so a join qualifier reaches
-    // every arm (blind index, jsonb containment, IS NULL, jsonText) alike.
-    const ref = (column) => qualifier === undefined ? quoteIdent(column) : `${quoteIdent(qualifier)}.${quoteIdent(column)}`;
-    // multiSelect (and any other jsonb-array-of-scalars column) stores an
-    // array — a filter value is one option, not the whole array, so eq/ne/in
-    // must check array containment (`@>`) instead of scalar `=`/`<>`/`IN`
-    // against the jsonb column, which Postgres rejects outright.
-    // Mirrors event-store-executor-read.ts's applyFilter — keep in lock-step.
-    function jsonbContainsAny(col, candidates) {
-        if (candidates.length === 0)
-            return "FALSE";
-        const parts = [];
-        for (const v of candidates) {
-            const p = prepareJsonbValue([v]);
-            // prepareJsonbValue never returns kind:"literal" (only prepareValue's
-            // isSqlExpression branch does) — narrow anyway, PreparedValue is a union.
-            if (p && p.kind === "param") {
-                parts.push(`${ref(col)} @> $${idx++}${p.sql}`);
-                values.push(p.bound);
-            }
-            // A jsonb column holding the scalar itself is never `@>` an array of it.
-            if (isJsonbScalar(v)) {
-                parts.push(`${ref(col)} = $${idx++}::text::jsonb`);
-                values.push(JSON.stringify(v));
-            }
-        }
-        return parts.length > 0 ? `(${parts.join(" OR ")})` : "FALSE";
-    }
-    function isJsonbScalar(value) {
-        return value !== null && typeof value !== "object";
-    }
-    for (const [field, value] of Object.entries(where)) {
-        const col = info.columnOf(field);
-        const pgType = info.pgTypeOf(col);
-        if (value === null) {
-            conditions.push(`${ref(col)} IS NULL`);
-        }
-        else if (Array.isArray(value)) {
-            if (value.length === 0) {
-                conditions.push("FALSE");
-            }
-            else if (pgType === "jsonb") {
-                conditions.push(jsonbContainsAny(col, value));
-            }
-            else {
-                const parts = [];
-                for (const v of value) {
-                    const p = prepareValue(v, pgType);
-                    if (p.kind === "literal") {
-                        parts.push(p.literal);
-                    }
-                    else {
-                        parts.push(`$${idx++}${p.sql}`);
-                        values.push(p.bound);
-                    }
-                }
-                conditions.push(`${ref(col)} IN (${parts.join(", ")})`);
-            }
-        }
-        else if (isWhereOperator(value)) {
-            if (value.jsonText !== undefined) {
-                if (Object.keys(value).length > 1) {
-                    throw new Error(`where: jsonText on column "${col}" cannot be combined with other operators`);
-                }
-                if (pgType !== "jsonb") {
-                    throw new Error(`where: jsonText requires a jsonb column, "${col}" is ${pgType}`);
-                }
-                const matches = isJsonTextMatchList(value.jsonText) ? value.jsonText : [value.jsonText];
-                if (matches.length === 0) {
-                    conditions.push("FALSE");
-                    continue;
-                }
-                for (const match of matches) {
-                    if (match === null ||
-                        typeof match !== "object" ||
-                        !Array.isArray(match.keys) ||
-                        match.keys.length === 0 ||
-                        !match.keys.every((k) => typeof k === "string") ||
-                        typeof match.eq !== "string") {
-                        throw new Error(`where: jsonText on column "${col}" needs non-empty string keys and a string eq`);
-                    }
-                    const lookups = match.keys.map((key) => {
-                        values.push(key);
-                        return `${ref(col)}->>$${idx++}::text`;
-                    });
-                    const lhs = lookups.length === 1 ? lookups[0] : `COALESCE(${lookups.join(", ")})`;
-                    values.push(match.eq);
-                    conditions.push(`(${lhs} = $${idx++})`);
-                }
-                continue;
-            }
-            if (value.ne === null && Object.keys(value).length === 1) {
-                conditions.push(`${ref(col)} IS NOT NULL`);
-                continue;
-            }
-            const opMap = {
-                gt: ">",
-                gte: ">=",
-                lt: "<",
-                lte: "<=",
-                ne: "<>",
-                like: "LIKE",
-            };
-            for (const [opKey, opSym] of Object.entries(opMap)) {
-                const opVal = Reflect.get(value, opKey);
-                if (opVal === undefined)
-                    continue;
-                // Mirrors applyMultiSelectFilter: ordering/pattern ops have no meaning on a jsonb
-                // option array (`like` would crash as `jsonb ~~ jsonb`), so match nothing.
-                if (pgType === "jsonb" && opKey !== "ne") {
-                    conditions.push("FALSE");
-                    continue;
-                }
-                // Mirrors applyMultiSelectFilter: an array `ne` means "does not contain all of these".
-                if (opKey === "ne" && pgType === "jsonb" && Array.isArray(opVal)) {
-                    if (opVal.length === 0) {
-                        conditions.push("FALSE");
-                        continue;
-                    }
-                    const p = prepareJsonbValue(opVal);
-                    if (p && p.kind === "param") {
-                        conditions.push(`(${ref(col)} IS NULL OR NOT (${ref(col)} @> $${idx++}${p.sql}))`);
-                        values.push(p.bound);
-                        continue;
-                    }
-                }
-                if (opKey === "ne" && pgType === "jsonb" && isJsonbScalar(opVal)) {
-                    const p = prepareJsonbValue([opVal]);
-                    if (p && p.kind === "param") {
-                        conditions.push(`(${ref(col)} IS NULL OR NOT (${ref(col)} @> $${idx++}${p.sql} OR ${ref(col)} = $${idx++}::text::jsonb))`);
-                        values.push(p.bound, JSON.stringify(opVal));
-                        continue;
-                    }
-                }
-                const p = prepareValue(opVal, pgType);
-                if (p.kind === "literal") {
-                    conditions.push(`${ref(col)} ${opSym} ${p.literal}`);
-                }
-                else {
-                    conditions.push(`${ref(col)} ${opSym} $${idx++}${p.sql}`);
-                    values.push(p.bound);
-                }
-            }
-            const inVal = value.in;
-            if (Array.isArray(inVal)) {
-                if (pgType === "jsonb") {
-                    conditions.push(jsonbContainsAny(col, inVal));
-                }
-                else if (inVal.length === 0) {
-                    conditions.push("FALSE");
-                }
-                else {
-                    const parts = [];
-                    for (const v of inVal) {
-                        const p = prepareValue(v, pgType);
-                        if (p.kind === "literal") {
-                            parts.push(p.literal);
-                        }
-                        else {
-                            parts.push(`$${idx++}${p.sql}`);
-                            values.push(p.bound);
-                        }
-                    }
-                    conditions.push(`${ref(col)} IN (${parts.join(", ")})`);
-                }
-            }
-            const notInVal = value.notIn;
-            if (Array.isArray(notInVal)) {
-                if (pgType === "jsonb") {
-                    throw new Error(`where: notIn is not supported on jsonb column "${col}"`);
-                }
-                const parts = [];
-                for (const v of notInVal) {
-                    const p = prepareValue(v, pgType);
-                    if (p.kind === "literal") {
-                        parts.push(p.literal);
-                    }
-                    else {
-                        parts.push(`$${idx++}${p.sql}`);
-                        values.push(p.bound);
-                    }
-                }
-                conditions.push(parts.length === 0 ? "TRUE" : `${ref(col)} NOT IN (${parts.join(", ")})`);
-            }
-        }
-        else if (pgType === "jsonb" && isJsonbScalar(value)) {
-            conditions.push(jsonbContainsAny(col, [value]));
-        }
-        else {
-            const p = prepareValue(value, pgType);
-            if (p.kind === "literal") {
-                conditions.push(`${ref(col)} = ${p.literal}`);
-            }
-            else {
-                // Blind-index OR rewrite: if the column has a bidx
-                // counterpart (suffix convention `<col>_bidx`, framework-reserved)
-                // and a key is configured, equality matches both arms —
-                // plaintext legacy rows via the plaintext arm, encrypted rows
-                // via the HMAC. The `kumiko-pii:` prefix on ciphertexts makes
-                // a random match on the plaintext arm practically impossible.
-                const bidxKey = configuredBlindIndexKey();
-                const bidxCol = `${col}_bidx`;
-                if (bidxKey !== undefined &&
-                    typeof value === "string" &&
-                    !col.endsWith("_bidx") &&
-                    info.hasColumn(bidxCol)) {
-                    conditions.push(`(${ref(col)} = $${idx++} OR ${ref(bidxCol)} = $${idx++})`);
-                    values.push(p.bound, computeBlindIndex(bidxKey, value));
-                }
-                else {
-                    conditions.push(`${ref(col)} = $${idx++}${p.sql}`);
-                    values.push(p.bound);
-                }
-            }
-        }
-    }
-    return { sqlText: conditions.join(" AND "), values };
-}
-// A pool can briefly keep handing out connections the server just closed.
-// Each failed attempt discards one, so retries are bounded by pool size.
-const CLOSED_CONNECTION_CODES = new Set([
-    "CONNECTION_CLOSED", // postgres-js
-    "57P01", // PG SQLSTATE: admin_shutdown / terminated backend
-]);
-export function isClosedConnectionError(err) {
-    const code = extractPgError(err)?.code;
-    return code !== undefined && CLOSED_CONNECTION_CODES.has(code);
-}
-// Tx/reserved handles are pinned to one physical connection — a retry there
-// would run on the same dead connection, not swap in a fresh one.
-function isPooledClient(raw) {
-    if (raw === null || (typeof raw !== "object" && typeof raw !== "function"))
-        return false;
-    return (typeof propertyOf(raw, "begin") === "function" &&
-        typeof propertyOf(raw, "savepoint") !== "function" &&
-        typeof propertyOf(raw, "release") !== "function");
-}
-const closedConnectionLog = createFallbackLogger("postgres-js");
-// The driver rejects in-flight queries with this AbortError (no code) when the
-// pool closes under them, so isClosedConnectionError can't see it.
-const DRIVER_CLOSED_ABORT_MESSAGE = "The connection was closed.";
-function isDriverClosedAbort(err) {
-    return (err instanceof Error && err.name === "AbortError" && err.message === DRIVER_CLOSED_ABORT_MESSAGE);
-}
-function isHandleLike(raw) {
-    return raw !== null && (typeof raw === "object" || typeof raw === "function");
-}
-// postgres-js pool and tx handles both carry `typed`.
-function driverOf(raw) {
-    if (!isHandleLike(raw))
-        return "unknown";
-    if (typeof raw["typed"] === "function")
-        return "postgres-js";
-    return "unknown";
-}
-function positiveNumber(v) {
-    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined;
-}
-// postgres-js configures timeouts in seconds.
-function timeoutOptionMs(options, driver, optionName) {
-    if (driver !== "postgres-js")
-        return undefined;
-    const seconds = positiveNumber(options[optionName]);
-    return seconds === undefined ? undefined : seconds * 1000;
-}
-function errorProp(err, name) {
-    return isHandleLike(err) ? err[name] : undefined;
-}
-// Deliberately excludes SQL text and parameters: app SQL can carry PII.
-export function describeClosedConnectionFailure(raw, err, attempts) {
-    if (!isClosedConnectionError(err) && !isDriverClosedAbort(err))
-        return undefined;
-    const driver = driverOf(raw);
-    const rawOptions = isHandleLike(raw) ? raw["options"] : undefined;
-    const options = isHandleLike(rawOptions) ? rawOptions : {};
-    return {
-        driver,
-        pooled: isPooledClient(raw),
-        attempts,
-        poolMax: positiveNumber(options["max"]),
-        idleTimeoutMs: timeoutOptionMs(options, driver, "idle_timeout"),
-        maxLifetimeMs: timeoutOptionMs(options, driver, "max_lifetime"),
-        connectionTimeoutMs: timeoutOptionMs(options, driver, "connect_timeout"),
-        errorName: errorProp(err, "name"),
-        errorCode: extractPgError(err)?.code ?? errorProp(err, "code"),
-        errorErrno: errorProp(err, "errno"),
-        errorMessage: errorProp(err, "message"),
-    };
-}
-function logClosedConnection(raw, err, attempts, context) {
-    const failure = describeClosedConnectionFailure(raw, err, attempts);
-    // skip: not a closed-connection error, nothing to diagnose
-    if (!failure)
-        return;
-    // Request identity lets this line be joined to the route's `handler failed` log.
-    const request = requestContext.get();
-    closedConnectionLog.warn("closed connection surfaced", {
-        ...failure,
-        ...context,
-        requestId: request?.requestId,
-        correlationId: request?.correlationId,
-        handler: request?.handler,
-    });
-}
 // Write and other non-retried paths: log when a closed-connection error leaves
 // the db layer, rethrow unchanged.
-async function unsafeLoggingClosedConnection(db, sqlText, params, context) {
+export async function unsafeLoggingClosedConnection(db, sqlText, params, context) {
     const raw = asRawClient(db);
     try {
         return await raw.unsafe(sqlText, params);
@@ -825,11 +175,6 @@ async function unsafeLoggingClosedConnection(db, sqlText, params, context) {
         throw err;
     }
 }
-const DEFAULT_POOL_MAX = 10;
-function poolMaxOf(raw) {
-    const max = propertyOf(propertyOf(raw, "options"), "max");
-    return typeof max === "number" && Number.isInteger(max) && max > 0 ? max : DEFAULT_POOL_MAX;
-}
 // Exported so raw-SQL query modules outside the db layer (e.g. bundled-features'
 // db/queries/*.ts) can opt into the same closed-connection retry instead of
 // calling asRawClient(db).unsafe(...) directly and losing it.
@@ -1130,14 +475,14 @@ export async function deleteMany(db, table, where) {
         operation: "deleteMany",
         table: info.name,
     });
-    // postgres-js reports the affected-row count of a DELETE on the result, no RETURNING needed.
+    // Bun.SQL reports the affected-row count of a DELETE on the result, no RETURNING needed.
     const count = propertyOf(result, "count");
     if (typeof count !== "number") {
         throw new Error(`deleteMany(${info.name}): the driver result carries no affected-row count`);
     }
     return count;
 }
-function insertEntries(info, values) {
+export function insertEntries(info, values) {
     return Object.entries(values)
         .filter(([k]) => info.hasColumn(k))
         .map(([k, v]) => {
@@ -1163,7 +508,31 @@ export function resolveConflictColumns(table, info, conflictKeys) {
         return [info.columnOf("id")];
     throw new Error("upsert: cannot infer conflict keys — pass conflictKeys explicitly");
 }
-function buildInsertSql(info, entries) {
+// Appends bound values to `params`; `skipCols` only applies to the default EXCLUDED set.
+export function conflictUpdateParts(info, entries, update, skipCols, params) {
+    const parts = [];
+    if (update === undefined) {
+        for (const e of entries) {
+            if (skipCols.has(e.col))
+                continue;
+            parts.push(`${quoteIdent(e.col)} = EXCLUDED.${quoteIdent(e.col)}`);
+        }
+        return parts;
+    }
+    for (const [field, value] of Object.entries(update)) {
+        const col = info.columnOf(field);
+        const p = prepareValue(value, info.pgTypeOf(col));
+        if (p.kind === "literal") {
+            parts.push(`${quoteIdent(col)} = ${p.literal}`);
+        }
+        else {
+            params.push(p.bound);
+            parts.push(`${quoteIdent(col)} = $${params.length}${p.sql}`);
+        }
+    }
+    return parts;
+}
+export function buildInsertSql(info, entries) {
     if (entries.length === 0)
         throw new Error("insert: empty values object");
     const cols = entries.map((e) => quoteIdent(e.col)).join(", ");
@@ -1191,82 +560,6 @@ export async function countWhere(db, table, where = {}) {
     const rows = await unsafeReadRetrying(db, sqlText, values);
     return rows[0]?.count ?? 0;
 }
-const AGGREGATE_BUCKET_UNITS = ["hour", "day"];
-const AGGREGATE_ORDER_DIRECTIONS = ["asc", "desc"];
-function requireAggregateColumn(info, field, role) {
-    if (!info.hasColumn(field)) {
-        throw new Error(`aggregateWhere: ${role} "${field}" is not a column of ${info.name}`);
-    }
-    return quoteIdent(info.columnOf(field));
-}
-export function isTimestamptzType(pgType) {
-    return pgType === "timestamptz" || pgType === "timestamptz(3)";
-}
-function aggregateKeyOf(raw) {
-    if (raw === null || raw === undefined)
-        return null;
-    if (typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean")
-        return raw;
-    if (typeof raw === "bigint")
-        return Number(raw);
-    if (raw instanceof Date)
-        return raw.toISOString();
-    return String(raw);
-}
-function aggregateMeasureSql(info, measure) {
-    switch (measure.fn) {
-        case "count":
-            return "COUNT(*)";
-        case "countDistinct":
-            return `COUNT(DISTINCT ${requireAggregateColumn(info, measure.field, "measure field")})`;
-        case "sum":
-            return `COALESCE(SUM(${requireAggregateColumn(info, measure.field, "measure field")}), 0)`;
-        case "avg":
-            return `AVG(${requireAggregateColumn(info, measure.field, "measure field")})`;
-        default:
-            throw new Error(`aggregateWhere: unknown measure fn "${String(Reflect.get(measure, "fn"))}"`);
-    }
-}
-function aggregateDimensionSql(info, dimension, index, params) {
-    const column = requireAggregateColumn(info, dimension.field, "groupBy field");
-    if (!("bucket" in dimension))
-        return `${column} AS k${index}`;
-    if (!AGGREGATE_BUCKET_UNITS.includes(dimension.bucket)) {
-        throw new Error(`aggregateWhere: unknown bucket "${String(dimension.bucket)}"`);
-    }
-    if (!isTimestamptzType(info.pgTypeOf(info.columnOf(dimension.field)))) {
-        throw new Error(`aggregateWhere: bucket on "${dimension.field}" requires a timestamptz column`);
-    }
-    params.push(dimension.timeZone);
-    return `(EXTRACT(EPOCH FROM date_trunc('${dimension.bucket}', ${column}, $${params.length}::text)) * 1000)::float8 AS k${index}`;
-}
-function assertValidAggregateLimits(spec) {
-    if (spec.limit !== undefined && (!Number.isInteger(spec.limit) || spec.limit < 0)) {
-        throw new Error(`aggregateWhere: limit must be a non-negative integer, got ${spec.limit}`);
-    }
-    if (spec.orderByValue !== undefined && !AGGREGATE_ORDER_DIRECTIONS.includes(spec.orderByValue)) {
-        throw new Error(`aggregateWhere: unknown orderByValue "${String(spec.orderByValue)}"`);
-    }
-    if (spec.orderByKeys !== undefined && !AGGREGATE_ORDER_DIRECTIONS.includes(spec.orderByKeys)) {
-        throw new Error(`aggregateWhere: unknown orderByKeys "${String(spec.orderByKeys)}"`);
-    }
-}
-function aggregateGroupOrderLimitSql(spec, dimensionCount) {
-    let sqlText = "";
-    if (dimensionCount > 0) {
-        const positions = Array.from({ length: dimensionCount }, (_, index) => String(index + 1));
-        sqlText += ` GROUP BY ${positions.join(", ")}`;
-        const keyDirection = spec.orderByKeys === "desc" ? "DESC" : "ASC";
-        const keyParts = positions.map((position) => `${position} ${keyDirection}`);
-        const orderParts = spec.orderByValue === undefined
-            ? keyParts
-            : [`${dimensionCount + 1} ${spec.orderByValue === "desc" ? "DESC" : "ASC"}`, ...keyParts];
-        sqlText += ` ORDER BY ${orderParts.join(", ")}`;
-    }
-    if (spec.limit !== undefined)
-        sqlText += ` LIMIT ${spec.limit}`;
-    return sqlText;
-}
 export async function aggregateWhere(db, table, spec, where = {}) {
     const scoped = tenantDbDelegate(db);
     if (scoped) {
@@ -1309,28 +602,7 @@ async function upsertOnConflictChecked(db, table, values, options) {
     const conflictCols = resolveConflictColumns(table, info, options.conflictKeys);
     const conflictSet = new Set(conflictCols);
     const { sqlPrefix, params } = buildInsertSql(info, entries);
-    const updateParts = [];
-    let idx = params.length + 1;
-    if (options.update !== undefined) {
-        for (const [field, value] of Object.entries(options.update)) {
-            const col = info.columnOf(field);
-            const p = prepareValue(value, info.pgTypeOf(col));
-            if (p.kind === "literal") {
-                updateParts.push(`${quoteIdent(col)} = ${p.literal}`);
-            }
-            else {
-                updateParts.push(`${quoteIdent(col)} = $${idx++}${p.sql}`);
-                params.push(p.bound);
-            }
-        }
-    }
-    else {
-        for (const e of entries) {
-            if (conflictSet.has(e.col))
-                continue;
-            updateParts.push(`${quoteIdent(e.col)} = EXCLUDED.${quoteIdent(e.col)}`);
-        }
-    }
+    const updateParts = conflictUpdateParts(info, entries, options.update, conflictSet, params);
     if (updateParts.length === 0) {
         throw new Error("upsertOnConflict: nothing to update on conflict");
     }