@cosmicdrift/kumiko-framework 0.367.0 → 0.369.0

package/dist/db/query.js

@@ -1,3 +1,1450 @@
-// Provider-neutrale Query-API. Re-exported aus bun-db/query.
-// Alle Consumer importieren von hier, nicht direkt aus bun-db/.
-export { aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "../bun-db/query.js";
+// Typed query helpers over the postgres-js driver: EntityTableMeta in, rows out.
+//
+// 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` 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 (#1480).
+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 { 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 { extractPgError } from "./pg-error.js";
+import { toSnakeCase } from "./table-builder.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);
+}
+// 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.
+export { asEntityTableMeta, requireEntityTableMeta };
+export function hasBegin(client) {
+    // Bun.SQL tx/savepoint handles keep a begin() that throws; only savepoint() tells them apart from a pool.
+    return typeof client.begin === "function" && typeof client.savepoint !== "function";
+}
+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
+    // need `.begin` (e.g. `transaction()`) verify it themselves.
+    if (isRawClient(db))
+        return db;
+    // 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() with escapeHatch: " +
+            "{ reason } on the handler/hook (r.systemScope() features: ctx.systemDb.unsafeRaw(reason)).");
+    }
+    // Wrapper handle: $client = postgres-js Sql.
+    const $client = propertyOf(db, "$client");
+    if (isRawClient($client))
+        return $client;
+    // Wrapper transaction handle: session.client = postgres-js Sql.
+    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.");
+}
+export function runnerCanBeginTransaction(db) {
+    return hasBegin(asRawClient(db));
+}
+// 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 db-runner savepoint handle → DbRunner at the single seam
+    const asRunner = (sp) => sp;
+    if (typeof raw.savepoint !== "function")
+        return fn(asRunner(db));
+    // An error from inside fn must never be remapped, even if it carries a closed-connection code.
+    let fnStarted = false;
+    try {
+        return await raw.savepoint((sp) => {
+            fnStarted = true;
+            return fn(asRunner(sp));
+        });
+    }
+    catch (e) {
+        const code = extractPgError(e)?.code;
+        if (!fnStarted && (code === "25P01" || code === "ERR_POSTGRES_CONNECTION_CLOSED")) {
+            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 " +
+                        "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.",
+                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;
+    if (typeof propertyOf(db, "unsafe") === "function")
+        return false;
+    return (typeof propertyOf(db, "selectMany") === "function" &&
+        typeof propertyOf(db, "fetchOne") === "function" &&
+        typeof propertyOf(db, "insertOne") === "function" &&
+        typeof propertyOf(db, "updateMany") === "function" &&
+        typeof propertyOf(db, "deleteMany") === "function" &&
+        "tenantId" in db);
+}
+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() (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", "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("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 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 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.
+// 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("bun-db");
+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 (#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, 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")) {
+            // 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 };
+}
+const INTEGER_PG_TYPES = new Set([
+    "integer",
+    "int4",
+    "smallint",
+    "int2",
+    "bigint",
+    "int8",
+    "serial",
+    "bigserial",
+]);
+// postgres.js truncates timestamptz params to ms via Date; Bun.SQL sends µs and Postgres
+// rounds into timestamptz(3). Truncating here keeps both drivers storing the same instant.
+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) };
+    }
+    // Bun.SQL binds JS numbers typed, so Postgres would round 3.5 into an integer column; postgres.js sends text and rejects 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 under Bun.SQL).
+    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 (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(`${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(", ")})`);
+                }
+            }
+        }
+        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 (#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(`(${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
+    "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;
+    return (typeof propertyOf(raw, "begin") === "function" &&
+        typeof propertyOf(raw, "savepoint") !== "function" &&
+        typeof propertyOf(raw, "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;
+    }
+}
+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 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;
+        }
+        // Enough retries to flush every dead pooled connection plus one fresh one; total calls = maxRetries + 1.
+        const maxRetries = poolMaxOf(raw) + 1;
+        let lastErr = err;
+        for (let attempt = 0; attempt < maxRetries; 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, maxRetries + 1);
+        throw lastErr;
+    }
+}
+function selectColumnList(info, fields) {
+    if (fields === undefined)
+        return "*";
+    if (fields.length === 0) {
+        throw new Error(`selectMany: fields must not be empty for "${info.name}"`);
+    }
+    return fields
+        .map((field) => {
+        if (!info.hasColumn(field)) {
+            throw new Error(`selectMany: fields entry "${field}" is not a column of "${info.name}"`);
+        }
+        return quoteIdent(info.columnOf(field));
+    })
+        .join(", ");
+}
+// 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 ${selectColumnList(info, options?.fields)} 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];
+}
+const JOIN_LEFT_ALIAS = "l";
+const JOIN_RIGHT_ALIAS = "r";
+function requireJoinColumn(info, field, role) {
+    if (!info.hasColumn(field)) {
+        throw new Error(`selectInnerJoin: ${role} "${field}" is not a column of "${info.name}"`);
+    }
+    return info.columnOf(field);
+}
+export async function selectInnerJoin(db, spec) {
+    assertNotTenantScoped(db, "selectInnerJoin");
+    const leftInfo = extractTableInfo(spec.left);
+    const rightInfo = extractTableInfo(spec.right);
+    if (spec.limit !== undefined && (!Number.isInteger(spec.limit) || spec.limit < 0)) {
+        throw new Error(`selectInnerJoin: limit must be a non-negative integer, got ${spec.limit}`);
+    }
+    const leftColumns = (spec.leftFields ??
+        requireEntityTableMeta(spec.left, "selectInnerJoin").columns.map((c) => c.name)).map((field) => requireJoinColumn(leftInfo, field, "leftFields entry"));
+    const rightColumns = (spec.rightFields ?? []).map((field) => requireJoinColumn(rightInfo, field, "rightFields entry"));
+    // Positional aliases: a `<side>__<column>` scheme would hit Postgres' 63-byte
+    // identifier truncation for long column names.
+    const projected = [
+        ...leftColumns.map((column) => ({ side: "left", column })),
+        ...rightColumns.map((column) => ({ side: "right", column })),
+    ];
+    if (projected.length === 0) {
+        throw new Error("selectInnerJoin: no columns selected");
+    }
+    const selectList = projected
+        .map(({ side, column }, index) => `${quoteIdent(side === "left" ? JOIN_LEFT_ALIAS : JOIN_RIGHT_ALIAS)}.${quoteIdent(column)} AS "c${index}"`)
+        .join(", ");
+    const onPairs = spec.on.map((pair) => {
+        const leftColumn = requireJoinColumn(leftInfo, pair.left, "on.left");
+        const rightColumn = requireJoinColumn(rightInfo, pair.right, "on.right");
+        const leftRef = `${quoteIdent(JOIN_LEFT_ALIAS)}.${quoteIdent(leftColumn)}`;
+        const rightRef = `${quoteIdent(JOIN_RIGHT_ALIAS)}.${quoteIdent(rightColumn)}`;
+        return leftInfo.pgTypeOf(leftColumn) === rightInfo.pgTypeOf(rightColumn)
+            ? `${leftRef} = ${rightRef}`
+            : `${leftRef}::text = ${rightRef}::text`;
+    });
+    let sqlText = `SELECT ${selectList} FROM ${quoteIdent(leftInfo.name)} AS ${quoteIdent(JOIN_LEFT_ALIAS)} ` +
+        `INNER JOIN ${quoteIdent(rightInfo.name)} AS ${quoteIdent(JOIN_RIGHT_ALIAS)} ON ${onPairs.join(" AND ")}`;
+    const conditions = [];
+    const values = [];
+    if (spec.leftWhere && Object.keys(spec.leftWhere).length > 0) {
+        const w = buildWhereClause(leftInfo, spec.leftWhere, values.length + 1, JOIN_LEFT_ALIAS);
+        conditions.push(w.sqlText);
+        values.push(...w.values);
+    }
+    if (spec.rightWhere && Object.keys(spec.rightWhere).length > 0) {
+        const w = buildWhereClause(rightInfo, spec.rightWhere, values.length + 1, JOIN_RIGHT_ALIAS);
+        conditions.push(w.sqlText);
+        values.push(...w.values);
+    }
+    if (conditions.length > 0)
+        sqlText += ` WHERE ${conditions.join(" AND ")}`;
+    if (spec.limit !== undefined)
+        sqlText += ` LIMIT ${spec.limit}`;
+    const raw = await unsafeReadRetrying(db, sqlText, values);
+    return raw.map((row) => {
+        const leftRow = {};
+        const rightRow = {};
+        projected.forEach(({ side, column }, index) => {
+            (side === "left" ? leftRow : rightRow)[column] = row[`c${index}`];
+        });
+        return {
+            left: coerceRow(leftRow, leftInfo),
+            right: coerceRow(rightRow, rightInfo),
+        };
+    });
+}
+// 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).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;
+}
+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) {
+        return scoped.aggregate(table, spec, where);
+    }
+    const info = extractTableInfo(table);
+    const params = [];
+    const measureSql = aggregateMeasureSql(info, spec.measure);
+    const dimensions = spec.groupBy ?? [];
+    const dimensionSql = dimensions.map((dimension, index) => aggregateDimensionSql(info, dimension, index, params));
+    assertValidAggregateLimits(spec);
+    const selectList = [...dimensionSql, `(${measureSql})::float8 AS value`].join(", ");
+    let sqlText = `SELECT ${selectList} FROM ${quoteIdent(info.name)}`;
+    if (Object.keys(where).length > 0) {
+        const w = buildWhereClause(info, where, params.length + 1);
+        sqlText += ` WHERE ${w.sqlText}`;
+        params.push(...w.values);
+    }
+    sqlText += aggregateGroupOrderLimitSql(spec, dimensions.length);
+    const raw = await unsafeReadRetrying(db, sqlText, params);
+    return raw.map((row) => {
+        const value = row["value"];
+        return {
+            keys: dimensions.map((_, index) => aggregateKeyOf(row[`k${index}`])),
+            value: value === null || value === undefined ? null : Number(value),
+        };
+    });
+}
+// 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 insertOnConflictDoNothing(db, table, values, options) {
+    assertNotTenantScoped(db, "insertOnConflictDoNothing");
+    const info = extractTableInfo(table);
+    const entries = insertEntries(info, values);
+    const conflictCols = resolveConflictColumns(table, info, options?.conflictKeys);
+    const { sqlPrefix, params } = buildInsertSql(info, entries);
+    const conflictList = conflictCols.map((c) => quoteIdent(c)).join(", ");
+    const sqlText = `${sqlPrefix} ON CONFLICT (${conflictList}) DO NOTHING RETURNING *`;
+    const rows = await unsafeLoggingClosedConnection(db, sqlText, params, {
+        operation: "insertOnConflictDoNothing",
+        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 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) {
+    const raw = asRawClient(db);
+    if (!hasBegin(raw)) {
+        throw new InternalError({
+            message: "transaction: runner has no begin() — already inside a transaction or savepoint.",
+        });
+    }
+    return raw.begin(fn);
+}
+// 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 (!hasBegin(raw)) {
+        throw new InternalError({
+            message: "runInNewTransaction: runner has no begin() — already inside a transaction or savepoint.",
+        });
+    }
+    return raw.begin(fn);
+}