@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/bun-db/query.js

@@ -0,0 +1,1145 @@
+// Typed query API over Bun.sql. No drizzle internally. Same signature as the
+// legacy `db/query-api.ts` — app-code migration is just an import-path swap,
+// not a call-site refactor.
+//
+// API:
+//   selectMany<T>(db, table, where?, opts?) → readonly T[]
+//   fetchOne<T>(db, table, where) → T | undefined
+//   insertOne<T>(db, table, values) → T | undefined
+//   updateMany<T>(db, table, set, where) → readonly T[]
+//   deleteMany(db, table, where) → void
+//   countWhere(db, table, where?) → number
+//   upsertByPk / upsertOnConflict / incrementCounter
+//   deleteManyBatched(db, table, where, { limit }) → { deleted, batches }
+//   transaction<T>(db, fn) → T
+//
+// `table` can be either:
+//   - EntityTableMeta (preferred, plain data)
+//   - drizzle pgTable (legacy, has Symbol-based tableName) — extracted via
+//     drizzle's getTableName + getTableColumns (drizzle kept only as a type
+//     reference, never as a runtime API call)
+import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+// Static polyfill import (not getTemporal()): coercion results stay on one
+// Temporal implementation repo-wide, even when Bun exposes a global (#1480).
+import { Temporal } from "temporal-polyfill";
+import { requestContext } from "../api/request-context.js";
+import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
+import { SQL_EXPR_BRAND } from "../db/dialect.js";
+import { extractPgError } from "../db/pg-error.js";
+import { toSnakeCase } from "../db/table-builder.js";
+import { camelCase as envCamelCase } from "../env/index.js";
+import { InternalError } from "../errors/index.js";
+import { createFallbackLogger } from "../logging/index.js";
+import { parseJsonSafe } from "../utils/safe-json.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);
+}
+// Drizzle pgTable inspection via raw Symbol access (no drizzle-orm import).
+// 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`/…
+// would overwrite the matching meta key — reading the meta from the symbol is
+// the only collision-safe path.
+function isEntityTableMeta(v) {
+    return (v !== null &&
+        typeof v === "object" &&
+        typeof v.tableName === "string" &&
+        Array.isArray(v.columns) &&
+        Array.isArray(v.indexes) &&
+        (v.source === "managed" || v.source === "unmanaged"));
+}
+// Resolve any framework table input to its canonical EntityTableMeta:
+//  - table()/buildEntityTable outputs carry it under KUMIKO_META_SYMBOL, immune
+//    to a column-handle shadowing a meta key.
+//  - deriveEntityTableMeta / defineUnmanagedTable return a plain meta with no
+//    handle-spread, so its structural shape is itself unshadowable.
+export function asEntityTableMeta(table) {
+    if (table === null || typeof table !== "object")
+        return undefined;
+    const fromSymbol = table[KUMIKO_META_SYMBOL];
+    if (isEntityTableMeta(fromSymbol))
+        return fromSymbol;
+    return isEntityTableMeta(table) ? table : undefined;
+}
+export function asRawClient(db) {
+    const dbAny = db;
+    // Direct: Bun.SQL / postgres-js Sql / postgres-js TransactionSql. All three
+    // expose `.unsafe`; only Sql/Bun.SQL have `.begin` — TransactionSql uses
+    // `.savepoint` for nested-tx. We only require `.unsafe` here; callers that
+    // need `.begin` (e.g. `transaction()`) verify it themselves.
+    if (typeof dbAny["unsafe"] === "function") {
+        return dbAny;
+    }
+    // TenantDb (ctx.db) has no unfiltered escape via asRawClient anymore — fail
+    // closed instead of silently unwrapping a tenant-scoped handle.
+    if (isTenantDbShape(db)) {
+        throw new Error("asRawClient: received a tenant-scoped TenantDb (ctx.db). Raw SQL helpers do not apply the " +
+            "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw(reason) with escapeHatch: " +
+            "{ reason } on the handler/hook (r.systemScope() features: ctx.systemDb.unsafeRaw(reason)).");
+    }
+    // Drizzle DbConnection (legacy compat): $client = postgres-js Sql.
+    const $client = dbAny["$client"];
+    if ($client && typeof $client["unsafe"] === "function") {
+        return $client;
+    }
+    // Drizzle pg-transaction (legacy compat): session.client = postgres-js Sql.
+    const session = dbAny["session"];
+    const sessionClient = session?.["client"];
+    if (sessionClient && typeof sessionClient["unsafe"] === "function") {
+        return sessionClient;
+    }
+    throw new Error("bun-db: db argument has no .unsafe() — pass Bun.SQL, postgres-js Sql, or a transaction handle.");
+}
+// postgres.js / Bun.SQL reject the WHOLE begin() when any statement inside
+// it errored — even if the JS error was caught (the driver tracks per-block
+// query failures). Error confinement therefore must go through the driver's
+// own savepoint(), not manual SAVEPOINT statements. The callback receives
+// the savepoint-scoped tx; run every confined statement on THAT handle.
+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 / Bun.SQL).");
+    }
+    return raw.savepoint(fn);
+}
+// 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 TransactionSql-shaped db still exposes `.savepoint`, and calling
+// it fails with PG 25P01 ("no active sql transaction") 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.
+export async function runInSavepointIfSupported(db, fn) {
+    const raw = asRawClient(db);
+    // @cast-boundary driver savepoint handle → DbRunner at the single seam
+    const asRunner = (sp) => sp;
+    if (typeof raw.savepoint !== "function")
+        return fn(asRunner(db));
+    try {
+        return await raw.savepoint((sp) => fn(asRunner(sp)));
+    }
+    catch (e) {
+        if (extractPgError(e)?.code === "25P01") {
+            throw new InternalError({
+                message: "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,
+            });
+        }
+        throw e;
+    }
+}
+// Duck-types TenantDb: five scoped methods + tenantId, no `.unsafe` of its own.
+// A throwing systemScope guard Proxy fails closed here too — intended, not a bug.
+function isTenantDbShape(db) {
+    if (typeof db !== "object" || db === null)
+        return false;
+    const d = db;
+    if (typeof d["unsafe"] === "function")
+        return false;
+    return (typeof d["selectMany"] === "function" &&
+        typeof d["fetchOne"] === "function" &&
+        typeof d["insertOne"] === "function" &&
+        typeof d["updateMany"] === "function" &&
+        typeof d["deleteMany"] === "function" &&
+        "tenantId" in d);
+}
+function tenantDbDelegate(db) {
+    return isTenantDbShape(db) ? db : undefined;
+}
+// Fails loudly for helpers that don't delegate to TenantDb (upsert/increment/insertMany) —
+// passing one here would otherwise reach asRawClient and throw with a less specific message.
+// @wrapper-known semantic-alias
+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(reason) (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", "like"];
+const _whereOperatorKeysExhaustive = true;
+void _whereOperatorKeysExhaustive;
+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) => WHERE_OPERATOR_KEYS.includes(k));
+}
+export function extractTableInfo(table) {
+    const meta = asEntityTableMeta(table);
+    if (!meta) {
+        throw new Error("bun-db.extractTableInfo: table is not a kumiko EntityTableMeta — " +
+            "build it via buildEntityTable / deriveEntityTableMeta / table().");
+    }
+    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 (typeof v === "object" &&
+        v !== null &&
+        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 (typeof v === "object" &&
+        v !== null &&
+        v[Symbol.toStringTag] === "Temporal.PlainDate");
+}
+function isTemporalPlainDateTimeLike(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        (v[Symbol.toStringTag] === "Temporal.PlainDateTime" ||
+            v[Symbol.toStringTag] === "Temporal.ZonedDateTime") &&
+        typeof v.toPlainDate === "function");
+}
+// Verified empirically against Bun.SQL (kumiko-framework#1924): 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.
+function plainDateFromDriver(value) {
+    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) {
+        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) {
+    const out = {};
+    let changed = false;
+    for (const key of Object.keys(row)) {
+        // Blind-index columns (#818) 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);
+            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")) {
+            // Bun.SQL / some drivers 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: pre-#1924 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 };
+}
+function prepareValue(value, pgType) {
+    if (isSqlExpression(value)) {
+        return { kind: "literal", literal: value.text };
+    }
+    if (pgType === "jsonb" && value !== null) {
+        const prepared = prepareJsonbValue(value);
+        if (prepared)
+            return prepared;
+    }
+    if ((pgType === "timestamptz" || pgType === "timestamptz(3)") && isTemporalInstant(value)) {
+        return { kind: "param", sql: "", bound: value.toString() };
+    }
+    if (pgType === "date") {
+        const prepared = prepareDateValue(value);
+        if (prepared)
+            return prepared;
+    }
+    return { kind: "param", sql: "", bound: value };
+}
+function buildWhereClause(info, where, startIndex) {
+    const conditions = [];
+    const values = [];
+    let idx = startIndex;
+    // 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 (fw#2490).
+    // 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(`${quoteIdent(col)} @> $${idx++}${p.sql}`);
+                values.push(p.bound);
+            }
+        }
+        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(`${quoteIdent(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(`${quoteIdent(col)} IN (${parts.join(", ")})`);
+            }
+        }
+        else if (isWhereOperator(value)) {
+            if (value.ne === null && Object.keys(value).length === 1) {
+                conditions.push(`${quoteIdent(col)} IS NOT NULL`);
+                continue;
+            }
+            const opMap = {
+                gt: ">",
+                gte: ">=",
+                lt: "<",
+                lte: "<=",
+                ne: "<>",
+                like: "LIKE",
+            };
+            for (const [opKey, opSym] of Object.entries(opMap)) {
+                const opVal = value[opKey];
+                if (opVal === undefined)
+                    continue;
+                if (opKey === "ne" && pgType === "jsonb" && isJsonbScalar(opVal)) {
+                    const p = prepareJsonbValue([opVal]);
+                    if (p && p.kind === "param") {
+                        conditions.push(`NOT (${quoteIdent(col)} @> $${idx++}${p.sql})`);
+                        values.push(p.bound);
+                        continue;
+                    }
+                }
+                const p = prepareValue(opVal, pgType);
+                if (p.kind === "literal") {
+                    conditions.push(`${quoteIdent(col)} ${opSym} ${p.literal}`);
+                }
+                else {
+                    conditions.push(`${quoteIdent(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(`${quoteIdent(col)} 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(`${quoteIdent(col)} = ${p.literal}`);
+            }
+            else {
+                // Blind-index OR rewrite (#818): 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(`(${quoteIdent(col)} = $${idx++} OR ${quoteIdent(bidxCol)} = $${idx++})`);
+                    values.push(p.bound, computeBlindIndex(bidxKey, value));
+                }
+                else {
+                    conditions.push(`${quoteIdent(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
+    "ERR_POSTGRES_CONNECTION_CLOSED", // Bun.SQL
+    "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;
+    // @cast-boundary driver handle shape — begin/savepoint/release are optional across drivers
+    const r = raw;
+    return (typeof r.begin === "function" &&
+        typeof r.savepoint !== "function" &&
+        typeof r.release !== "function");
+}
+const closedConnectionLog = createFallbackLogger("bun-db");
+// 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");
+}
+// Bun.SQL is not instanceof-checkable (Bun.SQL.prototype is invalid) and its tx
+// handles are plain function objects, so discriminate by members only one driver
+// has: `flush` on Bun.SQL (pool and tx), `typed` on postgres-js (pool and tx).
+function driverOf(raw) {
+    if (!isHandleLike(raw))
+        return "unknown";
+    if (typeof raw["flush"] === "function")
+        return "bun-sql";
+    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, Bun.SQL in milliseconds.
+function timeoutOptionMs(options, driver, bunName, postgresJsName) {
+    if (driver === "postgres-js") {
+        const seconds = positiveNumber(options[postgresJsName]);
+        return seconds === undefined ? undefined : seconds * 1000;
+    }
+    return positiveNumber(options[bunName]);
+}
+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, "idleTimeout", "idle_timeout"),
+        maxLifetimeMs: timeoutOptionMs(options, driver, "maxLifetime", "max_lifetime"),
+        connectionTimeoutMs: timeoutOptionMs(options, driver, "connectionTimeout", "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
+// bun-db, rethrow unchanged.
+async function unsafeLoggingClosedConnection(db, sqlText, params, context) {
+    const raw = asRawClient(db);
+    try {
+        return await raw.unsafe(sqlText, params);
+    }
+    catch (err) {
+        logClosedConnection(raw, err, 1, context);
+        throw err;
+    }
+}
+function poolMaxOf(raw) {
+    // @cast-boundary driver pool options — both postgres-js and Bun.SQL expose options.max
+    const max = raw.options?.max;
+    return typeof max === "number" && Number.isInteger(max) && max > 0 ? max : 10;
+}
+// Exported so raw-SQL query modules outside bun-db (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.
+// READS ONLY — retry re-executes the statement; never pass INSERT/UPDATE/DELETE.
+export async function unsafeReadRetrying(db, sqlText, params) {
+    const raw = asRawClient(db);
+    try {
+        return (await raw.unsafe(sqlText, params));
+    }
+    catch (err) {
+        if (!isPooledClient(raw) || !isClosedConnectionError(err)) {
+            logClosedConnection(raw, err, 1);
+            throw err;
+        }
+        const maxAttempts = poolMaxOf(raw) + 1;
+        let lastErr = err;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                return (await raw.unsafe(sqlText, params));
+            }
+            catch (retryErr) {
+                lastErr = retryErr;
+                if (!isClosedConnectionError(retryErr)) {
+                    logClosedConnection(raw, retryErr, attempt + 2);
+                    throw retryErr;
+                }
+            }
+        }
+        logClosedConnection(raw, lastErr, maxAttempts + 1);
+        throw lastErr;
+    }
+}
+// biome-ignore lint/suspicious/noExplicitAny: opt-in default loosens row type for unannotated test fixtures
+export async function selectMany(db, table, where, options) {
+    const scoped = tenantDbDelegate(db);
+    if (scoped) {
+        return scoped.selectMany(table, where, options);
+    }
+    const info = extractTableInfo(table);
+    let sqlText = `SELECT * FROM ${quoteIdent(info.name)}`;
+    let values = [];
+    if (where && Object.keys(where).length > 0) {
+        const w = buildWhereClause(info, where, 1);
+        sqlText += ` WHERE ${w.sqlText}`;
+        values = w.values;
+    }
+    if (options?.orderBy) {
+        const clauses = Array.isArray(options.orderBy) ? options.orderBy : [options.orderBy];
+        const parts = clauses.map((c) => {
+            const col = info.columnOf(c.col);
+            const dir = c.direction === "desc" ? "DESC" : "ASC";
+            return `${quoteIdent(col)} ${dir}`;
+        });
+        if (parts.length > 0)
+            sqlText += ` ORDER BY ${parts.join(", ")}`;
+    }
+    if (options?.limit !== undefined) {
+        // Interpolated, not bound — guard against a non-integer slipping in via an
+        // `any`-typed call site and injecting SQL.
+        if (!Number.isInteger(options.limit) || options.limit < 0) {
+            throw new Error(`selectMany: limit must be a non-negative integer, got ${options.limit}`);
+        }
+        sqlText += ` LIMIT ${options.limit}`;
+    }
+    const raw = (await unsafeReadRetrying(db, sqlText, values));
+    return coerceRows(raw, info);
+}
+// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
+export async function fetchOne(db, table, where) {
+    const rows = await selectMany(db, table, where, { limit: 1 });
+    return rows[0];
+}
+// Bulk INSERT — same shape as insertOne but takes an array of rows and
+// produces one multi-VALUES statement. Mirrors drizzle's
+// `db.insert(t).values(rows[])`. Empty input is a no-op.
+// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
+export async function insertMany(db, table, rows) {
+    if (rows.length === 0)
+        return [];
+    assertNotTenantScoped(db, "insertMany");
+    const info = extractTableInfo(table);
+    // Use the column-set from the first row; assume all rows share keys.
+    const firstRow = rows[0];
+    if (firstRow === undefined)
+        return [];
+    // Filter out fields that don't exist as columns in the table (like drizzle did implicitly)
+    const fields = Object.keys(firstRow).filter((k) => info.hasColumn(k));
+    if (fields.length === 0)
+        throw new Error("insertMany: empty row object");
+    const cols = fields.map((k) => quoteIdent(info.columnOf(k))).join(", ");
+    const params = [];
+    const valuesClauses = [];
+    for (const row of rows) {
+        const placeholders = [];
+        for (const f of fields) {
+            const col = info.columnOf(f);
+            const pgType = info.pgTypeOf(col);
+            const p = prepareValue(row[f], pgType);
+            if (p.kind === "literal") {
+                placeholders.push(p.literal);
+            }
+            else {
+                params.push(p.bound);
+                placeholders.push(`$${params.length}${p.sql}`);
+            }
+        }
+        valuesClauses.push(`(${placeholders.join(", ")})`);
+    }
+    const sqlText = `INSERT INTO ${quoteIdent(info.name)} (${cols}) VALUES ${valuesClauses.join(", ")} RETURNING *`;
+    const raw = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+        operation: "insertMany",
+        table: info.name,
+    }));
+    return coerceRows(raw, info);
+}
+// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
+export async function insertOne(db, table, values) {
+    const scoped = tenantDbDelegate(db);
+    if (scoped) {
+        return scoped.insertOne(table, values);
+    }
+    const info = extractTableInfo(table);
+    const entries = Object.entries(values)
+        .filter(([k]) => info.hasColumn(k))
+        .map(([k, v]) => {
+        const col = info.columnOf(k);
+        const pgType = info.pgTypeOf(col);
+        return { col, prepared: prepareValue(v, pgType) };
+    });
+    if (entries.length === 0)
+        throw new Error("insertOne: empty values object");
+    const cols = entries.map((e) => quoteIdent(e.col)).join(", ");
+    const params = [];
+    const placeholders = entries
+        .map((e) => {
+        if (e.prepared.kind === "literal")
+            return e.prepared.literal;
+        params.push(e.prepared.bound);
+        return `$${params.length}${e.prepared.sql}`;
+    })
+        .join(", ");
+    const sqlText = `INSERT INTO ${quoteIdent(info.name)} (${cols}) VALUES (${placeholders}) RETURNING *`;
+    const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+        operation: "insertOne",
+        table: info.name,
+    }));
+    const first = rows[0];
+    if (!first)
+        return undefined;
+    return coerceRow(first, info);
+}
+// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
+export async function updateMany(db, table, set, where) {
+    const scoped = tenantDbDelegate(db);
+    if (scoped) {
+        return scoped.updateMany(table, set, where);
+    }
+    const info = extractTableInfo(table);
+    const setEntries = Object.entries(set)
+        .filter(([k]) => info.hasColumn(k))
+        .map(([k, v]) => {
+        const col = info.columnOf(k);
+        const pgType = info.pgTypeOf(col);
+        return { col, prepared: prepareValue(v, pgType) };
+    });
+    if (setEntries.length === 0)
+        throw new Error("updateMany: empty set object");
+    const values = [];
+    let idx = 1;
+    const setParts = [];
+    for (const e of setEntries) {
+        if (e.prepared.kind === "literal") {
+            setParts.push(`${quoteIdent(e.col)} = ${e.prepared.literal}`);
+        }
+        else {
+            setParts.push(`${quoteIdent(e.col)} = $${idx++}${e.prepared.sql}`);
+            values.push(e.prepared.bound);
+        }
+    }
+    const w = buildWhereClause(info, where, idx);
+    let sqlText = `UPDATE ${quoteIdent(info.name)} SET ${setParts.join(", ")}`;
+    if (w.sqlText) {
+        sqlText += ` WHERE ${w.sqlText}`;
+        for (const v of w.values)
+            values.push(v);
+    }
+    sqlText += " RETURNING *";
+    const raw = (await unsafeLoggingClosedConnection(db, sqlText, values, {
+        operation: "updateMany",
+        table: info.name,
+    }));
+    return coerceRows(raw, info);
+}
+export async function deleteMany(db, table, where) {
+    const scoped = tenantDbDelegate(db);
+    if (scoped) {
+        return scoped.deleteMany(table, where);
+    }
+    const info = extractTableInfo(table);
+    const w = buildWhereClause(info, where, 1);
+    let sqlText = `DELETE FROM ${quoteIdent(info.name)}`;
+    if (w.sqlText)
+        sqlText += ` WHERE ${w.sqlText}`;
+    await unsafeLoggingClosedConnection(db, sqlText, w.values, {
+        operation: "deleteMany",
+        table: info.name,
+    });
+}
+function insertEntries(info, values) {
+    return Object.entries(values)
+        .filter(([k]) => info.hasColumn(k))
+        .map(([k, v]) => {
+        const col = info.columnOf(k);
+        return { field: k, col, prepared: prepareValue(v, info.pgTypeOf(col)) };
+    });
+}
+// Exported for the shadow-proof regression test — `table.columns` would be the
+// drizzle handle (not the PK list) when an entity has a field named `columns`.
+export function resolveConflictColumns(table, info, conflictKeys) {
+    if (conflictKeys !== undefined && conflictKeys.length > 0) {
+        return conflictKeys.map((field) => info.columnOf(field));
+    }
+    // Read the shadow-proof meta — `table.columns` directly would be the handle
+    // object when an entity has a field named `columns`.
+    const meta = asEntityTableMeta(table);
+    if (meta) {
+        const pks = meta.columns.filter((c) => c.primaryKey).map((c) => c.name);
+        if (pks.length > 0)
+            return pks;
+    }
+    if (info.hasColumn("id"))
+        return [info.columnOf("id")];
+    throw new Error("upsert: cannot infer conflict keys — pass conflictKeys explicitly");
+}
+function buildInsertSql(info, entries) {
+    if (entries.length === 0)
+        throw new Error("insert: empty values object");
+    const cols = entries.map((e) => quoteIdent(e.col)).join(", ");
+    const params = [];
+    const placeholders = entries
+        .map((e) => {
+        if (e.prepared.kind === "literal")
+            return e.prepared.literal;
+        params.push(e.prepared.bound);
+        return `$${params.length}${e.prepared.sql}`;
+    })
+        .join(", ");
+    const sqlPrefix = `INSERT INTO ${quoteIdent(info.name)} (${cols}) VALUES (${placeholders})`;
+    return { sqlPrefix, params };
+}
+export async function countWhere(db, table, where = {}) {
+    const info = extractTableInfo(table);
+    let sqlText = `SELECT COUNT(*)::int AS count FROM ${quoteIdent(info.name)}`;
+    let values = [];
+    if (Object.keys(where).length > 0) {
+        const w = buildWhereClause(info, where, 1);
+        sqlText += ` WHERE ${w.sqlText}`;
+        values = w.values;
+    }
+    const rows = (await unsafeReadRetrying(db, sqlText, values));
+    return rows[0]?.count ?? 0;
+}
+// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
+export async function upsertOnConflict(db, table, values, options) {
+    assertNotTenantScoped(db, "upsertOnConflict");
+    const info = extractTableInfo(table);
+    const entries = insertEntries(info, values);
+    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)}`);
+        }
+    }
+    if (updateParts.length === 0) {
+        throw new Error("upsertOnConflict: nothing to update on conflict");
+    }
+    const conflictList = conflictCols.map((c) => quoteIdent(c)).join(", ");
+    const sqlText = `${sqlPrefix} ON CONFLICT (${conflictList}) DO UPDATE SET ${updateParts.join(", ")} RETURNING *`;
+    const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+        operation: "upsertOnConflict",
+        table: info.name,
+    }));
+    const first = rows[0];
+    if (!first)
+        return undefined;
+    return coerceRow(first, info);
+}
+// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
+export async function upsertByPk(db, table, values, updateOnConflict) {
+    const info = extractTableInfo(table);
+    const conflictKeys = resolveConflictColumns(table, info, undefined);
+    const fieldKeys = conflictKeys.map((col) => info.fieldOf(col));
+    return upsertOnConflict(db, table, values, {
+        conflictKeys: fieldKeys,
+        ...(updateOnConflict !== undefined ? { update: updateOnConflict } : {}),
+    });
+}
+// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
+export async function incrementCounter(db, table, values, increments, options = {}) {
+    assertNotTenantScoped(db, "incrementCounter");
+    const info = extractTableInfo(table);
+    const entries = insertEntries(info, values);
+    const conflictCols = resolveConflictColumns(table, info, options.conflictKeys);
+    const conflictSet = new Set(conflictCols);
+    const { sqlPrefix, params } = buildInsertSql(info, entries);
+    const tableQ = quoteIdent(info.name);
+    const updateParts = [];
+    let idx = params.length + 1;
+    for (const [field, delta] of Object.entries(increments)) {
+        const col = info.columnOf(field);
+        updateParts.push(`${quoteIdent(col)} = ${tableQ}.${quoteIdent(col)} + $${idx++}`);
+        params.push(delta);
+    }
+    if (options.set !== undefined) {
+        for (const [field, value] of Object.entries(options.set)) {
+            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);
+            }
+        }
+    }
+    for (const e of entries) {
+        if (conflictSet.has(e.col))
+            continue;
+        if (Object.hasOwn(increments, e.field))
+            continue;
+        if (options.set !== undefined && Object.hasOwn(options.set, e.field))
+            continue;
+        updateParts.push(`${quoteIdent(e.col)} = EXCLUDED.${quoteIdent(e.col)}`);
+    }
+    if (updateParts.length === 0) {
+        throw new Error("incrementCounter: nothing to update on conflict");
+    }
+    const conflictList = conflictCols.map((c) => quoteIdent(c)).join(", ");
+    const sqlText = `${sqlPrefix} ON CONFLICT (${conflictList}) DO UPDATE SET ${updateParts.join(", ")} RETURNING *`;
+    const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+        operation: "incrementCounter",
+        table: info.name,
+    }));
+    const first = rows[0];
+    if (!first)
+        return undefined;
+    return coerceRow(first, info);
+}
+export async function deleteManyBatched(db, table, where, options) {
+    const info = extractTableInfo(table);
+    const w = buildWhereClause(info, where, 1);
+    if (!w.sqlText) {
+        throw new Error("deleteManyBatched: where clause required — refusing unbounded batch delete");
+    }
+    const limit = options.limit;
+    if (!Number.isFinite(limit) || limit <= 0) {
+        throw new Error("deleteManyBatched: limit must be a positive number");
+    }
+    const idField = options.idColumn ?? "id";
+    const idCol = info.columnOf(idField);
+    const tableQ = quoteIdent(info.name);
+    const idQ = quoteIdent(idCol);
+    const maxBatches = options.maxBatches ?? Number.POSITIVE_INFINITY;
+    let deleted = 0;
+    let batches = 0;
+    while (batches < maxBatches) {
+        const limitIdx = w.values.length + 1;
+        const params = [...w.values, limit];
+        const sqlText = `DELETE FROM ${tableQ} WHERE ${idQ} IN (
+      SELECT ${idQ} FROM ${tableQ} WHERE ${w.sqlText} LIMIT $${limitIdx}
+    ) RETURNING ${idQ}`;
+        const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+            operation: "deleteManyBatched",
+            table: info.name,
+        }));
+        batches++;
+        deleted += rows.length;
+        if (rows.length < limit)
+            break;
+    }
+    return { deleted, batches };
+}
+export async function transaction(db, fn) {
+    return (await asRawClient(db).begin(async (tx) => fn(tx)));
+}
+// A tx/savepoint handle has no begin(); fail closed instead of nesting silently or TypeError-ing.
+export async function runInNewTransaction(db, fn) {
+    const raw = asRawClient(db);
+    if (typeof raw.begin !== "function") {
+        throw new InternalError({
+            message: "runInNewTransaction: runner has no begin() — already inside a transaction or savepoint.",
+        });
+    }
+    // @cast-boundary driver tx handle → DbRunner at the single seam
+    return raw.begin((tx) => fn(tx));
+}