@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/db/closed-connection.js

@@ -0,0 +1,95 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { requestContext } from "../api/request-context.js";
+import { createFallbackLogger } from "../logging/index.js";
+import { extractPgError } from "./pg-error.js";
+// A pool can briefly keep handing out connections the server just closed.
+// Each failed attempt discards one, so retries are bounded by pool size.
+const CLOSED_CONNECTION_CODES = new Set([
+    "CONNECTION_CLOSED", // postgres-js
+    "57P01", // PG SQLSTATE: admin_shutdown / terminated backend
+]);
+export function isClosedConnectionError(err) {
+    const code = extractPgError(err)?.code;
+    return code !== undefined && CLOSED_CONNECTION_CODES.has(code);
+}
+// Tx/reserved handles are pinned to one physical connection — a retry there
+// would run on the same dead connection, not swap in a fresh one.
+export function isPooledClient(raw) {
+    if (raw === null || (typeof raw !== "object" && typeof raw !== "function"))
+        return false;
+    return (typeof propertyOf(raw, "begin") === "function" &&
+        typeof propertyOf(raw, "savepoint") !== "function" &&
+        typeof propertyOf(raw, "release") !== "function");
+}
+const closedConnectionLog = createFallbackLogger("postgres-js");
+// The driver rejects in-flight queries with this AbortError (no code) when the
+// pool closes under them, so isClosedConnectionError can't see it.
+const DRIVER_CLOSED_ABORT_MESSAGE = "The connection was closed.";
+function isDriverClosedAbort(err) {
+    return (err instanceof Error && err.name === "AbortError" && err.message === DRIVER_CLOSED_ABORT_MESSAGE);
+}
+function isHandleLike(raw) {
+    return raw !== null && (typeof raw === "object" || typeof raw === "function");
+}
+// postgres-js pool and tx handles both carry `typed`.
+function driverOf(raw) {
+    if (!isHandleLike(raw))
+        return "unknown";
+    if (typeof raw["typed"] === "function")
+        return "postgres-js";
+    return "unknown";
+}
+function positiveNumber(v) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined;
+}
+// postgres-js configures timeouts in seconds.
+function timeoutOptionMs(options, driver, optionName) {
+    if (driver !== "postgres-js")
+        return undefined;
+    const seconds = positiveNumber(options[optionName]);
+    return seconds === undefined ? undefined : seconds * 1000;
+}
+function errorProp(err, name) {
+    return isHandleLike(err) ? err[name] : undefined;
+}
+// Deliberately excludes SQL text and parameters: app SQL can carry PII.
+export function describeClosedConnectionFailure(raw, err, attempts) {
+    if (!isClosedConnectionError(err) && !isDriverClosedAbort(err))
+        return undefined;
+    const driver = driverOf(raw);
+    const rawOptions = isHandleLike(raw) ? raw["options"] : undefined;
+    const options = isHandleLike(rawOptions) ? rawOptions : {};
+    return {
+        driver,
+        pooled: isPooledClient(raw),
+        attempts,
+        poolMax: positiveNumber(options["max"]),
+        idleTimeoutMs: timeoutOptionMs(options, driver, "idle_timeout"),
+        maxLifetimeMs: timeoutOptionMs(options, driver, "max_lifetime"),
+        connectionTimeoutMs: timeoutOptionMs(options, driver, "connect_timeout"),
+        errorName: errorProp(err, "name"),
+        errorCode: extractPgError(err)?.code ?? errorProp(err, "code"),
+        errorErrno: errorProp(err, "errno"),
+        errorMessage: errorProp(err, "message"),
+    };
+}
+export 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,
+    });
+}
+const DEFAULT_POOL_MAX = 10;
+export function poolMaxOf(raw) {
+    const max = propertyOf(propertyOf(raw, "options"), "max");
+    return typeof max === "number" && Number.isInteger(max) && max > 0 ? max : DEFAULT_POOL_MAX;
+}

package/dist/db/collect-table-metas.js

@@ -1,15 +1,14 @@
 // Canonical table source for both `kumiko schema generate` and setupTestStack
 // (entities, storeTables, projections, multiStreamProjections). One shared
-// source so the test-DB push and migrations cannot drift apart again (#255, #3102).
+// source so the test-DB push and migrations cannot drift apart again.
 import { compareByCodepoint } from "../utils/index.js";
 import { assertBackingTableSuperset, deriveEntityTableMeta, } from "./entity-table-meta.js";
 import { enumerateFeatureTableSources } from "./feature-table-sources.js";
 import { asEntityTableMeta } from "./query.js";
 function canonicalColumnsKey(meta) {
-    // Spalten-Identität unabhängig von Deklarations-Reihenfolge und
-    // Objekt-Key-Order. Indexes bleiben außen vor: eine Projection-Table
-    // (buildEntityTable ohne relations) trägt legitim weniger FK-Indexes
-    // als das Entity-Meta derselben Tabelle.
+    // Column identity independent of declaration order and object-key order.
+    // Indexes are excluded: a projection table (buildEntityTable without relations)
+    // legitimately has fewer FK indexes than the entity metadata for the same table.
     return [...meta.columns]
         .sort((a, b) => compareByCodepoint(a.name, b.name))
         .map((c) => `${c.name}|${c.pgType}|${c.notNull}|${c.defaultSql ?? ""}|${c.primaryKey ?? false}|${c.identity ?? false}|${c.bigintJsMode ?? ""}`)
@@ -27,8 +26,8 @@ function registerPass1Meta(metas, byName, meta, origin) {
 export function collectTableMetas(features) {
     const metas = [];
     const byName = new Map();
-    // Pass 1: kanonische Schema-Quellen, identisch zum bisherigen Template-
-    // Verhalten (gleiche Reihenfolge, gleiche deriveEntityTableMeta-Optionen).
+    // Pass 1: canonical schema sources, matching the previous template behavior
+    // (same order, same deriveEntityTableMeta options).
     for (const feature of features) {
         for (const [name, ent] of Object.entries(feature.entities ?? {})) {
             const fieldMeta = deriveEntityTableMeta(name, ent, { relations: feature.relations[name] });
@@ -52,10 +51,10 @@ export function collectTableMetas(features) {
             registerPass1Meta(metas, byName, entry.meta, `storeTable "${entry.name}" (${feature.name})`);
         }
     }
-    // Pass 2: table-tragende Registrierungen. Zwei Pässe, damit eine Entity-
-    // Tabelle aus Feature B gegen eine gleichnamige Projection-Table aus
-    // Feature A gewinnt — Entity-Metas sind die reichere Quelle (FK-Indexes
-    // aus relations).
+    // Pass 2: table-bearing registrations. Two passes ensure that an entity table
+    // from Feature B takes precedence over a same-named projection table from
+    // Feature A—entity metadata is the richer source because of FK indexes from
+    // relations.
     for (const feature of features) {
         for (const { table, origin } of enumerateFeatureTableSources(feature)) {
             const meta = asEntityTableMeta(table);

package/dist/db/compound-types.d.ts

@@ -4,6 +4,6 @@ import type { EntityDefinition } from "../engine/types/index.ts";
  */
 export declare function flattenCompoundTypes(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
 /**
- * DB-Form (flat) → API-Form (combined). Wird nach jedem Read aufgerufen.
+ * DB form (flat) → API form (combined). Called after every read.
  */
 export declare function rehydrateCompoundTypes(row: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;

package/dist/db/compound-types.js

@@ -1,20 +1,20 @@
-// Compound-Type Pipeline für den Executor.
+// Compound-type pipeline for the executor.
 //
-// Ein Compound-Type ist ein Field das aus EINEM API-Object und MEHREREN
-// DB-Spalten besteht. Beispiele:
+// A compound type is a field represented by ONE API object and MULTIPLE
+// DB columns. Examples:
 //   - locatedTimestamp: { at, tz, utc } ↔ <name>Utc + <name>Tz
 //   - money: { amount, currency } ↔ <name> + <name>Currency
-//   - (kommt) address: { street, zip, city } ↔ <name>Street + <name>Zip + <name>City
+//   - (upcoming) address: { street, zip, city } ↔ <name>Street + <name>Zip + <name>City
 //
-// Statt jeden Helper im Executor an 4 Stellen verschachtelt aufzurufen,
-// pipeline-iert diese Funktion alle Compound-Type-Konvertierungen in
-// einem Pass. Beim Hinzufügen eines neuen Compound-Types nur EINE Stelle
-// erweitern (das Array hier), nicht alle Executor-Aufrufe.
+// Instead of nesting every helper in the executor at four different points,
+// this function pipelines all compound-type conversions in one pass. Adding
+// a new compound type requires extending only ONE place (this array), rather
+// than every executor call.
 import { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp.js";
 import { flattenMoney, rehydrateMoney } from "./money.js";
-// Reihenfolge ist egal solange die Konverter sich nicht gegenseitig
-// überlappen (z.B. money darf nicht ein Feld berühren das locatedTimestamp
-// schon erzeugt hat). Aktuell überlappen sie nicht — types sind disjunkt.
+// Order is irrelevant as long as the converters do not overlap (for example,
+// money must not touch a field already produced by locatedTimestamp). They do
+// not currently overlap—types are disjoint.
 const FLATTENERS = [flattenLocatedTimestamp, flattenMoney];
 const REHYDRATORS = [rehydrateLocatedTimestamp, rehydrateMoney];
 /**
@@ -24,7 +24,7 @@ export function flattenCompoundTypes(payload, entity) {
     return FLATTENERS.reduce((acc, fn) => fn(acc, entity), payload);
 }
 /**
- * DB-Form (flat) → API-Form (combined). Wird nach jedem Read aufgerufen.
+ * DB form (flat) → API form (combined). Called after every read.
  */
 export function rehydrateCompoundTypes(row, entity) {
     return REHYDRATORS.reduce((acc, fn) => fn(acc, entity), row);

package/dist/db/cursor.js

@@ -1,8 +1,7 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-// String-basiert damit UUIDs (Default seit Sprint F) + Integer-Auto-Increment
-// durch denselben Cursor-Pfad laufen. UUIDv7 erfüllt die lex-Monotonie
-// (time-ordered Prefix); UUIDv4 nicht — wer den nutzt, kriegt inkorrekte
-// cursor-Reihenfolge (Default ist v7).
+// Uses strings so UUIDs and integer auto-increment IDs can share the same cursor path.
+// UUIDv7 preserves lexicographic monotonicity through its time-ordered prefix; UUIDv4 does not,
+// so UUIDv4 produces incorrect cursor ordering. The default is v7.
 export function encodeCursor(id) {
     return Buffer.from(String(id)).toString("base64url");
 }

package/dist/db/dialect.d.ts

@@ -3,8 +3,8 @@ import { type ColumnHandle, type SchemaTable } from "@cosmicdrift/kumiko-types/s
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { PgType } from "./entity-table-meta.ts";
 export type { ColumnHandle, SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
-export type TableColumns<_T = any> = SchemaTable;
-export type SelectQuery = any;
+export type TableColumns<_T = unknown> = SchemaTable;
+export type SelectQuery = unknown;
 export declare function pgTypeToSqlType(pgType: PgType): string;
 type ColumnFinal = {
     readonly sqlName: string;

package/dist/db/dialect.js

@@ -15,7 +15,7 @@
 //
 // Static import of the shared Temporal module, not the ambient global: the
 // global may be absent (Hermes/Safari) or torn down in tests, and instantToDriver
-// crashed on timestamptz writes without it (#1480).
+// crashed on timestamptz writes without it.
 import { KUMIKO_COLUMNS_SYMBOL, KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { brandWritable, schemaTableName } from "./table-introspection.js";
@@ -190,7 +190,7 @@ export function instant(name, opts) {
 // PG `date` — no time-of-day, no timezone. Calendar-day fields (invoice
 // date, lease term) round-trip as Temporal.PlainDate, never through an
 // Instant — that detour is exactly what made `type:"date"` TZ-dependent on
-// both read and write (kumiko-framework#1924).
+// both read and write.
 export function plainDate(name) {
     return buildColumn(name, "date");
 }
@@ -251,7 +251,7 @@ export function primaryKey(opts) {
 // Limits: no nested SqlExpression composition (drizzle's recursive
 // `sql\`${other}\``) — schema-files use single-level expressions only.
 // Unforgeable via JSON — a client-supplied jsonb value can fake `kind:
-// "sql-expr"` but can never carry a Symbol, so isSqlExpression() (db/query.ts)
+// "sql-expr"` but can never carry a Symbol, so isSqlExpression() (db/driver-value-preparation.ts)
 // can't be tricked into treating request data as a raw SQL literal. The same
 // brand gate is enforced here in the schema DSL (sql`...` interpolation +
 // literalDefault) and in entity-table-meta's sqlExpressionText — a duck-typed

package/dist/db/distinct-on.d.ts

@@ -1,5 +1,5 @@
 import type { OrderByClause } from "@cosmicdrift/kumiko-types/where-clause-types";
-import type { TableInfo } from "./query.ts";
+import type { TableInfo } from "./table-info.ts";
 type DistinctOnClause = {
     /** Physical column names, unquoted. */
     readonly columns: readonly string[];

package/dist/db/driver-row-coercion.d.ts

@@ -0,0 +1,2 @@
+import type { TableInfo } from "./table-info.ts";
+export declare function coerceDriverRow(row: Record<string, unknown>, info: TableInfo): Record<string, unknown>;

package/dist/db/driver-row-coercion.js

@@ -0,0 +1,186 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { createFallbackLogger } from "../logging/index.js";
+import { parseJsonSafe } from "../utils/safe-json.js";
+import { isTemporalInstant, isTemporalPlainDate } from "./temporal-value-guards.js";
+// --- 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.
+// 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;
+}
+// Verified empirically: a `date`
+// column comes back as a native JS Date, but ALWAYS anchored at UTC
+// midnight regardless of process TZ — epochMilliseconds is stable across
+// zones, only the local wall-clock read of that Date would drift the day
+// (e.g. America/Los_Angeles reads back the 14th for a stored 15th). Routing
+// through Instant→ZonedDateTimeISO("UTC")→PlainDate reads the calendar day
+// back deterministically without ever touching a local Date getter — the
+// same +value idiom instantFromDriver uses (guard-no-date-api: no
+// `.getTime()`), just anchored to a fixed zone instead of process-local.
+// A real `date` column always arrives as a UTC-midnight Date. Anything else means the column is
+// still timestamptz (declared `date` before its ALTER ran); the UTC anchor then silently shifts
+// the day, so say so once per column instead of returning the wrong day quietly.
+const warnedNonMidnightDateColumns = new Set();
+const MS_PER_DAY = 86_400_000;
+const dateColumnDriftLog = createFallbackLogger("postgres-js");
+function warnIfNotDateColumn(epochMs, column) {
+    // skip: midnight value is a correct date column, and an already-warned column is deduped
+    if (epochMs % MS_PER_DAY === 0 || warnedNonMidnightDateColumns.has(column))
+        return;
+    warnedNonMidnightDateColumns.add(column);
+    dateColumnDriftLog.warn(`column "${column}" is declared as date but returned a non-midnight timestamp; it is probably still timestamptz. Run the ALTER ... TYPE date migration, otherwise days can shift.`);
+}
+function plainDateFromDriver(value, column) {
+    if (value === null || value === undefined)
+        return null;
+    if (isTemporalPlainDate(value))
+        return value;
+    if (typeof value === "string") {
+        const isoDay = /^\d{4}-\d{2}-\d{2}/.exec(value)?.[0];
+        if (isoDay === undefined)
+            return null;
+        try {
+            return Temporal.PlainDate.from(isoDay);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (value instanceof Date) {
+        warnIfNotDateColumn(+value, column);
+        return Temporal.Instant.fromEpochMilliseconds(+value).toZonedDateTimeISO("UTC").toPlainDate();
+    }
+    return null;
+}
+function coerceTimestamptz(value) {
+    const instant = instantFromDriver(value);
+    return instant !== null ? instant : value;
+}
+function coerceDate(value, column) {
+    const day = plainDateFromDriver(value, column);
+    return day !== null ? day : value;
+}
+function coerceJsonb(value) {
+    return typeof value === "string" ? parseJsonSafe(value, value) : value;
+}
+function coerceBigIntColumn(value, column, info) {
+    if (typeof value !== "string" && typeof value !== "bigint")
+        return value;
+    if (info.bigintJsModeOf(column) === "number")
+        return coerceBigIntFromDriver(value);
+    if (typeof value === "string") {
+        try {
+            return BigInt(value);
+        }
+        catch {
+            // leave as string on parse error
+            return value;
+        }
+    }
+    return value;
+}
+function numberUnlessNaN(value) {
+    if (typeof value !== "string" && typeof value !== "bigint")
+        return value;
+    const n = Number(value);
+    return Number.isNaN(n) ? value : n;
+}
+// Keyed by the driver's pgType string, not PgType: legacy tables report int4/smallint/int2.
+const DRIVER_VALUE_COERCERS = new Map([
+    ["timestamptz", coerceTimestamptz],
+    ["timestamptz(3)", coerceTimestamptz],
+    ["date", coerceDate],
+    ["jsonb", coerceJsonb],
+    ["bigint", coerceBigIntColumn],
+    ["bigserial", coerceBigIntColumn],
+    // Drivers may return int4 as bigint or numeric string.
+    // Drizzle coerced to number for numberField columns — match that.
+    ["integer", numberUnlessNaN],
+    ["int4", numberUnlessNaN],
+    ["smallint", numberUnlessNaN],
+    ["int2", numberUnlessNaN],
+]);
+// 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.
+function driverValueCoercerFor(pgType) {
+    if (pgType === undefined)
+        return undefined;
+    const coercer = DRIVER_VALUE_COERCERS.get(pgType);
+    if (coercer)
+        return coercer;
+    return pgType.startsWith("numeric") ? numberUnlessNaN : undefined;
+}
+export function coerceDriverRow(row, info) {
+    const out = {};
+    let changed = false;
+    for (const key of Object.keys(row)) {
+        // Blind-index columns are pure lookup artifacts — the
+        // deterministic HMAC must never leak into caller/API responses.
+        if ((key.endsWith("_bidx") || key.endsWith("Bidx")) && info.hasColumn(key)) {
+            changed = true;
+            continue;
+        }
+        const value = row[key];
+        const coercer = driverValueCoercerFor(info.pgTypeOf(key));
+        const coerced = coercer ? coercer(value, key, info) : value;
+        const fieldName = info.fieldOf(key);
+        if (fieldName !== key)
+            changed = true;
+        if (coerced !== value)
+            changed = true;
+        out[fieldName] = coerced;
+    }
+    return changed ? out : row;
+}

package/dist/db/driver-value-preparation.d.ts

@@ -0,0 +1,16 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+export type PreparedValue = {
+    readonly kind: "param";
+    readonly sql: string;
+    readonly bound: unknown;
+} | {
+    readonly kind: "literal";
+    readonly literal: string;
+};
+export declare function isSqlExpression(v: unknown): v is {
+    kind: "sql-expr";
+    text: string;
+};
+export declare function prepareJsonbValue(value: unknown): PreparedValue | undefined;
+export declare function instantToTimestamptzParam(instant: Temporal.Instant): string;
+export declare function prepareValue(value: unknown, pgType: string | undefined): PreparedValue;

package/dist/db/driver-value-preparation.js

@@ -0,0 +1,99 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { isPiiCiphertext } from "../crypto/pii-ciphertext-format.js";
+import { SQL_EXPR_BRAND } from "./dialect.js";
+import { isTemporalInstant, isTemporalPlainDate, isTemporalPlainDateTimeLike, } from "./temporal-value-guards.js";
+// 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.
+export function isSqlExpression(v) {
+    return typeof v === "object" && v !== null && SQL_EXPR_BRAND in v;
+}
+// A `date` column takes a plain "yyyy-mm-dd" string (or PlainDate.toString())
+// as-is — no Instant detour. Postgres parses a DATE literal without ever
+// consulting the session timezone, so this is TZ-independent by construction
+// (verified empirically — see plainDateFromDriver above for the read side).
+// Compat cushion: code (this field used to be an Instant) may still
+// hand a Temporal.Instant into a where-filter or write on a `date` column —
+// same UTC anchor as plainDateFromDriver's read side, so a filter built with
+// `Temporal.Now.instant()` keeps working instead of binding a raw Instant the
+// driver can't serialize.
+function prepareDateValue(value) {
+    if (isTemporalPlainDate(value)) {
+        return { kind: "param", sql: "", bound: value.toString() };
+    }
+    if (isTemporalPlainDateTimeLike(value)) {
+        return { kind: "param", sql: "", bound: value.toPlainDate().toString() };
+    }
+    if (isTemporalInstant(value)) {
+        const day = value.toZonedDateTimeISO("UTC").toPlainDate();
+        return { kind: "param", sql: "", bound: day.toString() };
+    }
+    return undefined;
+}
+// structured values bind directly with an ::jsonb cast; JSON.stringify first
+// would produce a JSON-string scalar instead of the structured value.
+export function prepareJsonbValue(value) {
+    if (typeof value === "boolean") {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
+    if (typeof value !== "object" || isTemporalInstant(value)) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        return { kind: "param", sql: "::jsonb", bound: value };
+    }
+    // All-boolean arrays are inferred as boolean[] by postgres-js; route via text::jsonb.
+    if (value.length > 0 && value.every((entry) => typeof entry === "boolean")) {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
+    return { kind: "param", sql: "::jsonb", bound: value };
+}
+const INTEGER_PG_TYPES = new Set([
+    "integer",
+    "int4",
+    "smallint",
+    "int2",
+    "bigint",
+    "int8",
+    "serial",
+    "bigserial",
+]);
+// Postgres rounds sub-millisecond params into timestamptz(3); truncating to ms here keeps the
+// stored instant identical across drivers and equal to what postgres.js sends via Date.
+export function instantToTimestamptzParam(instant) {
+    return Temporal.Instant.fromEpochMilliseconds(instant.epochMilliseconds).toString();
+}
+function prepareDriverNeutralScalar(value, pgType) {
+    if ((pgType === "timestamptz" || pgType === "timestamptz(3)") && isTemporalInstant(value)) {
+        return { kind: "param", sql: "", bound: instantToTimestamptzParam(value) };
+    }
+    // postgres.js sends text, so Postgres rejects 3.5 for an integer column instead of rounding it.
+    if (typeof value === "number" && pgType !== undefined && INTEGER_PG_TYPES.has(pgType)) {
+        return { kind: "param", sql: "", bound: String(value) };
+    }
+    return undefined;
+}
+export function prepareValue(value, pgType) {
+    if (isSqlExpression(value)) {
+        return { kind: "literal", literal: value.text };
+    }
+    // A PII-encrypted jsonb field is a JSON string scalar; a raw string bound to
+    // ::jsonb would be parsed as JSON text (or double-encoded).
+    if (pgType === "jsonb" && isPiiCiphertext(value)) {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
+    if (pgType === "jsonb" && value !== null) {
+        const prepared = prepareJsonbValue(value);
+        if (prepared)
+            return prepared;
+    }
+    const scalar = prepareDriverNeutralScalar(value, pgType);
+    if (scalar)
+        return scalar;
+    if (pgType === "date") {
+        const prepared = prepareDateValue(value);
+        if (prepared)
+            return prepared;
+    }
+    return { kind: "param", sql: "", bound: value };
+}

package/dist/db/eagerload.d.ts

@@ -15,9 +15,9 @@ export type EagerLoadViewer = {
     readonly user: SessionUser;
     readonly parentVisibility: ParentVisibilityOption;
 };
-/** Eagerload für eine Liste von Rows. Mutiert nicht — gibt eine
- *  flache Kopie der Rows mit hinzugefügtem `_refs`-Property zurück. */
+/** Eagerloads a list of rows without mutating them; returns shallow copies
+ *  with an added `_refs` property. */
 export declare function enrichWithReferences(rows: ReadonlyArray<Record<string, unknown>>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb, viewer: EagerLoadViewer): Promise<Array<Record<string, unknown>>>;
-/** Single-Row-Variante für detail-Calls. */
+/** Single-row variant for detail calls. */
 export declare function enrichRowWithReferences(row: Record<string, unknown>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb, viewer: EagerLoadViewer): Promise<Record<string, unknown>>;
 export {};