@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/dist/api/session-cookies.js

@@ -53,10 +53,10 @@ export function expireLegacySessionCookieVariants(c, cookies) {
         // skip: the unprefixed names are the only legacy variant when the config writes __Host- names.
         return;
     }
-    if (cookies.secure) {
-        deleteCookie(c, sessionCookieName(AUTH_COOKIE_BASE, { secure: true }), hostPrefixedDelete);
-        deleteCookie(c, sessionCookieName(CSRF_COOKIE_BASE, { secure: true }), hostPrefixedDelete);
-    }
+    // Sent even with secureCookies:false: TLS may still terminate at a proxy, and over plain HTTP the
+    // browser drops the Secure delete without effect.
+    deleteCookie(c, sessionCookieName(AUTH_COOKIE_BASE, { secure: true }), hostPrefixedDelete);
+    deleteCookie(c, sessionCookieName(CSRF_COOKIE_BASE, { secure: true }), hostPrefixedDelete);
 }
 const hostPrefixedDelete = { path: "/", secure: true };
 // Expire every variant: the Domain cookie (current) and the host-only one

package/dist/api/sse-route.js

@@ -136,6 +136,20 @@ export function createSseRoute(broker, options) {
             let pendingWrites = 0;
             let lastProgressAt = now();
             const isStalled = () => pendingWrites > 0 && now() - lastProgressAt > SSE_STALLED_CLIENT_TIMEOUT_MS;
+            // Pings go through the same accounting: an awaited ping would block on a client that
+            // stopped reading, and the stall check below would never run again.
+            const writeTracked = (event, data) => {
+                if (pendingWrites === 0)
+                    lastProgressAt = now();
+                pendingWrites += 1;
+                stream
+                    .writeSSE({ event, data })
+                    .catch(closeStream)
+                    .finally(() => {
+                    pendingWrites -= 1;
+                    lastProgressAt = now();
+                });
+            };
             const clientId = broker.addClient(channel, (event) => {
                 // skip: the stream is already being torn down
                 if (stream.aborted || stream.closed)
@@ -152,17 +166,7 @@ export function createSseRoute(broker, options) {
                         // skip: this client is gone, the frame has no audience
                         return;
                     }
-                    const data = JSON.stringify(frame.data);
-                    if (pendingWrites === 0)
-                        lastProgressAt = now();
-                    pendingWrites += 1;
-                    stream
-                        .writeSSE({ event: frame.name, data })
-                        .catch(closeStream)
-                        .finally(() => {
-                        pendingWrites -= 1;
-                        lastProgressAt = now();
-                    });
+                    writeTracked(frame.name, JSON.stringify(frame.data));
                 }
                 catch {
                     // skip: an unserializable frame ends this client's stream, not the broadcast
@@ -192,7 +196,7 @@ export function createSseRoute(broker, options) {
                         stream.abort();
                         break;
                     }
-                    await stream.writeSSE({ event: "ping", data: "" });
+                    writeTracked("ping", "");
                     await Promise.race([stream.sleep(SSE_HEARTBEAT_INTERVAL_MS), ended]);
                 }
             }

package/dist/crypto/owner-transition-rekey.d.ts

@@ -1,3 +1,7 @@
 import type { EntityDefinition } from "../engine/types/fields.ts";
-export declare function isPlainUserOwnedField(field: EntityDefinition["fields"][string]): boolean;
+export declare function isPlainUserOwnedField(field: EntityDefinition["fields"][string]): field is EntityDefinition["fields"][string] & {
+    readonly userOwned: {
+        readonly ownerField: string;
+    };
+};
 export declare function personalFieldsRekeyedOnOwnerTransition(entity: EntityDefinition, previous: Record<string, unknown>, mergedNew: Record<string, unknown>, submittedChanges: Record<string, unknown>): Record<string, unknown>;

package/dist/crypto/owner-transition-rekey.js

@@ -17,7 +17,7 @@ export function isPlainUserOwnedField(field) {
 export function personalFieldsRekeyedOnOwnerTransition(entity, previous, mergedNew, submittedChanges) {
     const rekeyed = {};
     for (const [name, field] of Object.entries(entity.fields)) {
-        if (!isPlainUserOwnedField(field) || !("userOwned" in field) || !field.userOwned)
+        if (!isPlainUserOwnedField(field))
             continue;
         if (name in submittedChanges)
             continue;

package/dist/crypto/pii-field-encryption.d.ts

@@ -7,13 +7,17 @@ export declare function piiCiphertextSubject(value: string): SubjectId;
 export declare function encryptPiiValueForSubject(kms: LocalKeyKmsAdapter, subject: SubjectId, value: string, kmsCtx: KmsContext, field: string): Promise<string>;
 export declare function encryptPiiJsonValueForSubject(kms: LocalKeyKmsAdapter, subject: SubjectId, value: unknown, kmsCtx: KmsContext, field: string): Promise<string>;
 export declare function decryptPiiValueForSubject(kms: LocalKeyKmsAdapter, value: string, kmsCtx: KmsContext, field: string): Promise<string>;
+export declare const ErasedSubjectHandlings: {
+    readonly sentinel: "sentinel";
+};
+export type ErasedSubjectHandling = (typeof ErasedSubjectHandlings)[keyof typeof ErasedSubjectHandlings];
 export interface EncryptPiiOptions {
     readonly onlyKeys?: Iterable<string>;
     readonly tenantId?: TenantId;
     readonly subjectSource?: Record<string, unknown>;
     readonly entityName: string;
     readonly ownerFallback?: Record<string, unknown>;
-    readonly onErasedSubject?: "sentinel";
+    readonly onErasedSubject?: ErasedSubjectHandling;
 }
 export type PiiEncryptedRow<TRow extends Record<string, unknown>> = {
     [K in keyof TRow]: TRow[K] extends string ? string : TRow[K] | string;

package/dist/crypto/pii-field-encryption.js

@@ -130,6 +130,7 @@ export async function decryptPiiValueForSubject(kms, value, kmsCtx, field) {
         return PII_ERASED_SENTINEL;
     }
 }
+export const ErasedSubjectHandlings = { sentinel: "sentinel" };
 export async function encryptPiiFieldValues(row, entity, piiFields, kms, kmsCtx, opts) {
     if (piiFields.length === 0)
         return row;
@@ -166,7 +167,8 @@ export async function encryptPiiFieldValues(row, entity, piiFields, kms, kmsCtx,
             out[name] = encryptValue(subject, dek, plaintext, name, isJsonbField);
         }
         catch (e) {
-            if (!(e instanceof KeyErasedError) || opts.onErasedSubject !== "sentinel")
+            if (!(e instanceof KeyErasedError) ||
+                opts.onErasedSubject !== ErasedSubjectHandlings.sentinel)
                 throw e;
             out[name] = PII_ERASED_SENTINEL;
         }

package/dist/db/aggregate-sql.d.ts

@@ -0,0 +1,21 @@
+import type { AggregateDimension, AggregateKey, AggregateSpec } from "@cosmicdrift/kumiko-types/aggregate-types";
+import type { FieldDefinition } from "@cosmicdrift/kumiko-types/fields";
+import type { ListAggregateMeasureKind, ListAggregateValue } from "@cosmicdrift/kumiko-types/list-aggregate-types";
+import type { TableInfo } from "./table-info.ts";
+export declare function isTimestamptzType(pgType: string | undefined): boolean;
+export declare function aggregateKeyOf(raw: unknown): AggregateKey;
+export type AggregateFunction = "count" | "countDistinct" | "sum" | "avg" | "min" | "max";
+export declare function aggregateFunctionSql(fn: AggregateFunction, columnSql: string | undefined, filterSql?: string): string;
+export declare function aggregateMeasureSql(info: TableInfo, measure: AggregateSpec["measure"]): string;
+type FieldType = FieldDefinition["type"];
+export declare function isListAggregateMeasureSupported(kind: ListAggregateMeasureKind, fieldType: FieldType): boolean;
+export declare function isListAggregateGroupable(fieldType: FieldType, multiple: boolean): boolean;
+export declare function listAggregateKeySql(fieldType: FieldType, columnSql: string, alias: string): string;
+export declare function listAggregateMeasureSql(kind: ListAggregateMeasureKind, fieldType: FieldType, columnSql: string, filterSql?: string): string;
+export declare function groupedKeyOrderLimitSql(limit: number): string;
+export declare function decodeListAggregateValue(raw: unknown): ListAggregateValue;
+export declare function emptyListAggregateValue(kind: ListAggregateMeasureKind): ListAggregateValue;
+export declare function aggregateDimensionSql(info: TableInfo, dimension: AggregateDimension, index: number, params: unknown[]): string;
+export declare function assertValidAggregateLimits(spec: AggregateSpec): void;
+export declare function aggregateGroupOrderLimitSql(spec: AggregateSpec, dimensionCount: number): string;
+export {};

package/dist/db/aggregate-sql.js

@@ -0,0 +1,155 @@
+import { quoteIdent } from "../crypto/ciphertext-pattern.js";
+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)";
+}
+export 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);
+}
+// FILTER sits inside the aggregate so a row-dependent read clause restricts only
+// this measure; COALESCE stays outside to keep an all-filtered SUM at 0.
+export function aggregateFunctionSql(fn, columnSql, filterSql) {
+    const filter = filterSql === undefined ? "" : ` FILTER (WHERE ${filterSql})`;
+    const column = columnSql ?? "*";
+    switch (fn) {
+        case "count":
+            return `COUNT(${column})${filter}`;
+        case "countDistinct":
+            return `COUNT(DISTINCT ${column})${filter}`;
+        case "sum":
+            return `COALESCE(SUM(${column})${filter}, 0)`;
+        case "avg":
+            return `AVG(${column})${filter}`;
+        case "min":
+            return `MIN(${column})${filter}`;
+        case "max":
+            return `MAX(${column})${filter}`;
+        default:
+            throw new Error(`aggregateWhere: unknown aggregate fn "${String(fn)}"`);
+    }
+}
+export function aggregateMeasureSql(info, measure) {
+    if (measure.fn === "count")
+        return aggregateFunctionSql("count", undefined);
+    return aggregateFunctionSql(measure.fn, requireAggregateColumn(info, measure.field, "measure field"));
+}
+const NUMERIC_MEASURE_TYPES = ["number", "bigInt", "decimal", "money"];
+const ORDERED_MEASURE_TYPES = [...NUMERIC_MEASURE_TYPES, "date", "timestamp"];
+// Group keys must round-trip as a plain `field eq key` filter, which rules out
+// composite, multi-valued, currency-paired and zone-paired types.
+const GROUPABLE_TYPES = [
+    "text",
+    "longText",
+    "select",
+    "boolean",
+    "number",
+    "bigInt",
+    "decimal",
+    "date",
+    "timestamp",
+];
+export function isListAggregateMeasureSupported(kind, fieldType) {
+    if (kind === "count")
+        return true;
+    const allowed = kind === "sum" || kind === "avg" ? NUMERIC_MEASURE_TYPES : ORDERED_MEASURE_TYPES;
+    return allowed.includes(fieldType);
+}
+export function isListAggregateGroupable(fieldType, multiple) {
+    return fieldType === "reference" ? !multiple : GROUPABLE_TYPES.includes(fieldType);
+}
+export function listAggregateKeySql(fieldType, columnSql, alias) {
+    // A date column must not pass through a JS Date, so it travels as text.
+    return fieldType === "date" ? `${columnSql}::text AS ${alias}` : `${columnSql} AS ${alias}`;
+}
+const ISO_UTC_TIMESTAMP_FORMAT = `'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'`;
+// Numbers leave PG as float8 and dates/timestamps as text, so the driver never
+// hands back a bigint or numeric string that JSON could not carry.
+export function listAggregateMeasureSql(kind, fieldType, columnSql, filterSql) {
+    const fn = aggregateFunctionSql(kind, columnSql, filterSql);
+    if (kind === "count")
+        return `(${fn})::float8`;
+    if (kind === "min" || kind === "max") {
+        if (fieldType === "date")
+            return `(${fn})::text`;
+        if (fieldType === "timestamp") {
+            return `to_char((${fn}) AT TIME ZONE 'UTC', ${ISO_UTC_TIMESTAMP_FORMAT})`;
+        }
+    }
+    // Money is integer minor units, so an average rounds to one.
+    if (kind === "avg" && fieldType === "money")
+        return `ROUND(${fn})::float8`;
+    return `(${fn})::float8`;
+}
+export function groupedKeyOrderLimitSql(limit) {
+    return ` GROUP BY 1 ORDER BY 1 ASC NULLS LAST LIMIT ${limit}`;
+}
+export function decodeListAggregateValue(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw === "number" || typeof raw === "string")
+        return raw;
+    if (typeof raw === "bigint")
+        return Number(raw);
+    if (raw instanceof Date)
+        return raw.toISOString();
+    return String(raw);
+}
+// What the measure reports over zero rows, mirroring the SQL (SUM coalesces, COUNT is 0).
+export function emptyListAggregateValue(kind) {
+    return kind === "sum" || kind === "count" ? 0 : null;
+}
+export 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}`;
+}
+export 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)}"`);
+    }
+}
+export 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;
+}

package/dist/db/closed-connection.d.ts

@@ -0,0 +1,9 @@
+export declare function isClosedConnectionError(err: unknown): boolean;
+export declare function isPooledClient(raw: unknown): boolean;
+export declare function describeClosedConnectionFailure(raw: unknown, err: unknown, attempts: number): Record<string, unknown> | undefined;
+export type ClosedConnectionContext = {
+    readonly operation: string;
+    readonly table?: string;
+};
+export declare function logClosedConnection(raw: unknown, err: unknown, attempts: number, context?: ClosedConnectionContext): void;
+export declare function poolMaxOf(raw: unknown): number;

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/dialect.js

@@ -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;