@cosmicdrift/kumiko-framework 0.387.0 → 0.389.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.d.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import type { AccessRule } from "../engine/types/index.ts";
+import type { AccessRule, OwnershipMap } from "../engine/types/index.ts";
 import { type SseBroker } from "./sse-broker.ts";
 /**
  * Heartbeat cadence for SSE streams.
@@ -27,6 +27,7 @@ export declare const SSE_MAX_PENDING_WRITES_PER_CLIENT = 10000;
 export type SseRouteOptions = {
     readonly anonymousLiveEntities: ReadonlySet<string>;
     readonly entityReadAccess: ReadonlyMap<string, readonly AccessRule[]>;
+    readonly entityRowReadMaps?: ReadonlyMap<string, OwnershipMap>;
     readonly now?: () => number;
 };
 export declare function createSseRoute(broker: SseBroker, options: SseRouteOptions): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/api/sse-route.js

@@ -84,7 +84,17 @@ function entitySignalDetail(user, aggregateType, options) {
     const granting = (options.entityReadAccess.get(aggregateType) ?? []).filter((rule) => hasAccess(user, rule));
     if (granting.length === 0)
         return "none";
-    return granting.some((rule) => "roles" in rule) ? "identified" : "anonymous";
+    if (!granting.some((rule) => "roles" in rule))
+        return "anonymous";
+    return readsEveryRow(user, options.entityRowReadMaps?.get(aggregateType))
+        ? "identified"
+        : "anonymous";
+}
+// Mirrors buildOwnershipClause: without a map every row is visible, otherwise only a role mapped to "all" sees them all.
+function readsEveryRow(user, rowReadMap) {
+    if (rowReadMap === undefined)
+        return true;
+    return user.roles.some((role) => rowReadMap[role] === "all");
 }
 function decideWireFrame(event, user, options) {
     const data = event.data;
@@ -136,6 +146,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 +176,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 +206,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/config/index.d.ts

@@ -1,5 +1,5 @@
 import type { ValidateBootOptions } from "../engine/boot-validator.ts";
-import type { FeatureDefinition } from "../engine/types/index.ts";
+import type { BundledListsOptions, FeatureDefinition } from "../engine/types/index.ts";
 export type AppInfraPorts = {
     readonly postgres?: number;
     readonly redis?: number;
@@ -35,6 +35,8 @@ export type AppConfig = {
     readonly ports: AppPorts;
     /** Passed to validateBoot by `kumiko check` and, via the app's bin files, by the runners. */
     readonly validateBootOptions?: AppValidateBootOptions;
+    /** One table block for every list of the bundled features. kumiko/schema.ts passes it to composeFeatures; the app's bin files pass it to the runners, like validateBootOptions. */
+    readonly bundledLists?: BundledListsOptions;
 };
 export declare const APP_CONFIG_FILE = "kumiko.config.ts";
 declare const INFRA_PORT_NAMES: readonly ["postgres", "redis", "meilisearch", "s3"];

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/pg-kms-adapter.d.ts

@@ -17,6 +17,7 @@ export declare class PgKmsAdapter implements LocalKeyKmsAdapter {
     readonly capabilities: {
         readonly mode: "local-key";
     };
+    private readonly connection;
     private readonly sql;
     private readonly kek;
     private readonly kekVersion;

package/dist/crypto/pg-kms-adapter.js

@@ -1,6 +1,6 @@
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
-import postgres from "postgres";
-import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "../db/connection.js";
+import { createDbConnection } from "../db/connection.js";
+import { isUniqueViolation } from "../db/pg-error.js";
 import { KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, subjectIdToKey, } from "./kms-adapter.js";
 const IV_LENGTH = 12;
 const TAG_LENGTH = 16;
@@ -28,21 +28,15 @@ function decodePlatformKek(base64) {
     }
     return kek;
 }
-const PG_UNIQUE_VIOLATION = "23505";
 // pg_advisory_xact_lock key for createSchema — serializes concurrent cold-start
 // DDL across processes sharing one subject-keys DB.
 const SCHEMA_ADVISORY_LOCK_KEY = 0x6b_6d_73_31; // 'kms1'
-function isPgUniqueViolation(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === PG_UNIQUE_VIOLATION);
-}
 // Default production adapter: DEKs live in a separate Postgres cluster,
 // KEK-wrapped at rest. Schema is created lazily on first use — the
 // subject-keys cluster has no drizzle migration pipeline of its own.
 export class PgKmsAdapter {
     capabilities = { mode: "local-key" };
+    connection;
     sql;
     kek;
     kekVersion;
@@ -60,12 +54,11 @@ export class PgKmsAdapter {
             previous.set(v, decodePlatformKek(kek));
         }
         this.previousKeks = previous;
-        this.sql = postgres(options.databaseUrl, {
-            max: options.maxConnections ?? 4,
-            // The connection is exclusive to this adapter and its only DDL is
-            // idempotent IF NOT EXISTS — notices are pure boot-log noise.
-            onnotice: () => { },
+        this.connection = createDbConnection({
+            url: options.databaseUrl,
+            maxConnections: options.maxConnections ?? 4,
         });
+        this.sql = this.connection.client;
     }
     async createKey(subject, ctx) {
         await this.ensureSchema();
@@ -76,7 +69,7 @@ export class PgKmsAdapter {
         VALUES (${subjectIdToKey(subject)}, ${wrapped}, ${this.kekVersion}, ${ctx.userId ?? null})`;
         }
         catch (error) {
-            if (isPgUniqueViolation(error))
+            if (isUniqueViolation(error))
                 throw new KeyAlreadyExistsError(subject);
             throw error;
         }
@@ -128,7 +121,7 @@ export class PgKmsAdapter {
         return { ok: true, latencyMs: Date.now() - start };
     }
     async close() {
-        await this.sql.end({ timeout: DEFAULT_DB_CLOSE_TIMEOUT_SECONDS });
+        await this.connection.close();
     }
     ensureSchema() {
         // A failed attempt resets the memo so a transient DB outage does not
@@ -178,7 +171,8 @@ export async function rewrapSubjectKeys(options) {
         fromKeks.set(Number(version), decodePlatformKek(kek));
     }
     const batchSize = options.batchSize ?? 200;
-    const sql = postgres(options.databaseUrl, { max: 2, onnotice: () => { } });
+    const connection = createDbConnection({ url: options.databaseUrl, maxConnections: 2 });
+    const sql = connection.client;
     const failures = [];
     const result = { scanned: 0, rewrapped: 0, skippedErased: 0, failures };
     try {
@@ -226,7 +220,7 @@ export async function rewrapSubjectKeys(options) {
         }
     }
     finally {
-        await sql.end();
+        await connection.close();
     }
     return result;
 }

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,23 @@
+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 isPerCurrencyMeasure(kind: ListAggregateMeasureKind, fieldType: FieldType): boolean;
+export declare function listCurrencyMeasureSql(kind: ListAggregateMeasureKind, 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,165 @@
+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 isPerCurrencyMeasure(kind, fieldType) {
+    return fieldType === "money" && kind !== "count";
+}
+// No COALESCE on SUM: a currency absent from a group must read NULL so it can be left out.
+export function listCurrencyMeasureSql(kind, columnSql, filterSql) {
+    const fn = kind === "sum"
+        ? `SUM(${columnSql}) FILTER (WHERE ${filterSql})`
+        : aggregateFunctionSql(kind, columnSql, filterSql);
+    return kind === "avg" ? `ROUND(${fn})::float8` : `(${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,88 @@
+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([
+    "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.
+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("bun-sql");
+function isHandleLike(raw) {
+    return raw !== null && (typeof raw === "object" || typeof raw === "function");
+}
+// Bun.SQL pool and tx handles both carry `flush`.
+function driverOf(raw) {
+    if (!isHandleLike(raw))
+        return "unknown";
+    if (typeof raw["flush"] === "function")
+        return "bun-sql";
+    return "unknown";
+}
+function positiveNumber(v) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined;
+}
+// Bun.SQL reports its timeout options in milliseconds.
+function timeoutOptionMs(options, driver, optionName) {
+    if (driver !== "bun-sql")
+        return undefined;
+    return positiveNumber(options[optionName]);
+}
+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))
+        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"),
+        maxLifetimeMs: timeoutOptionMs(options, driver, "maxLifetime"),
+        connectionTimeoutMs: timeoutOptionMs(options, driver, "connectionTimeout"),
+        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/connection.d.ts

@@ -1,14 +1,12 @@
-import type { DbConnection, PgClient } from "@cosmicdrift/kumiko-types/db-connection";
-import postgres from "postgres";
+import type { DbConnection, PgClient, PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
 export type * from "@cosmicdrift/kumiko-types/db-connection";
-type PostgresDriverOptions = NonNullable<Parameters<typeof postgres>[1]>;
+type BunSqlOptions = Bun.SQL.PostgresOrMySQLOptions;
 export type DbConnectionOptions = {
     readonly maxConnections?: number;
     readonly idleTimeoutSeconds?: number;
     readonly connectTimeoutSeconds?: number;
     readonly closeTimeoutSeconds?: number;
-    readonly ssl?: PostgresDriverOptions["ssl"];
-    readonly onNotice?: (notice: postgres.Notice) => void;
+    readonly ssl?: BunSqlOptions["tls"];
     readonly statementTimeoutMs?: number;
     readonly idleInTransactionSessionTimeoutMs?: number;
     readonly lockTimeoutMs?: number;
@@ -19,6 +17,7 @@ export type CreateDbConnectionOptions = DbConnectionOptions & {
 export type DbConnectionHandle = {
     db: DbConnection;
     client: PgClient;
+    listenClient: PgListenClient;
     close: () => Promise<void>;
 };
 export declare const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;