@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/dist/db/blind-index-cleanup.js

@@ -15,6 +15,7 @@ import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-p
 import { isSelfPiiField } from "../crypto/is-self-pii-field.js";
 import { toSnakeCase } from "../utils/case.js";
 import { resolveTableName } from "./entity-table-meta.js";
+import { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 import { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
 import { columnNamesOf, tableExists } from "./schema-inspection.js";
 export async function nullBlindIndexesForSubject(db, features, subjectKey) {
@@ -55,7 +56,7 @@ export async function nullBlindIndexesForSubject(db, features, subjectKey) {
 async function existingTableNames(db, tableNames) {
     if (tableNames.length === 0)
         return new Set();
-    const rows = await executeRawQueryRead(db, `SELECT t.name FROM unnest($1::text[]) AS t(name) WHERE to_regclass('public.' || quote_ident(t.name)) IS NOT NULL`, [tableNames]);
+    const rows = await executeRawQueryRead(db, `SELECT t.name FROM unnest($1::text[]) AS t(name) WHERE to_regclass('public.' || quote_ident(t.name)) IS NOT NULL`, [toPostgresArrayLiteral(tableNames)]);
     return new Set(rows.map((r) => r.name));
 }
 // Tenant-scope oracle for crypto-shredding's forget-subject (mh#349): a

package/dist/db/bun-provider.js

@@ -1,12 +1,11 @@
-// Bun.SQL Provider — experimentell.
-// Default: postgres-js. Dieser Provider nur aktiv wenn DB_PROVIDER=bun.
-// Bekannter Bug: Extended-Query-Protocol Caching verursacht
-// PostgresError "bind message has 11 result formats but query has 1 columns"
-// bei sequentiellen Queries mit unterschiedlicher Spaltenzahl innerhalb
-// derselben Connection.
+// Bun.SQL provider, opt-in via DB_PROVIDER=bun; postgres-js stays the default.
+// Known bug (Bun <= 1.4.3, oven-sh/bun#29484): a cached plan is not re-prepared
+// after DDL, so e.g. `SELECT *` after ADD COLUMN fails on that connection with
+// 0A000 "cached plan must not change result type". prepare:false is no fix,
+// it changes how jsonb params are bound.
 //
-// Bun.SQL hat kein LISTEN — postgres-js-Peer für event-dispatcher.
-import postgres from "postgres";
+// LISTEN runs on Bun.SQL's own dedicated connection, which is exempt from the
+// pool's idleTimeout and maxLifetime and re-LISTENs after a drop.
 import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS, } from "./api.js";
 export function createBunConnection(url, options = {}) {
     const bunOpts = {};
@@ -17,21 +16,13 @@ export function createBunConnection(url, options = {}) {
     if (options.connectTimeoutSeconds !== undefined)
         bunOpts.connectionTimeout = options.connectTimeoutSeconds;
     const db = new Bun.SQL(url, bunOpts);
-    // LISTEN peer — 1 connection reicht für NOTIFY-Wakeups
-    const pgOpts = { max: 1 };
-    if (options.idleTimeoutSeconds !== undefined)
-        pgOpts.idle_timeout = options.idleTimeoutSeconds;
-    if (options.connectTimeoutSeconds !== undefined)
-        pgOpts.connect_timeout = options.connectTimeoutSeconds;
-    const listenClient = postgres(url, pgOpts);
     const closeTimeout = options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS;
     return {
         db,
-        client: listenClient,
-        listenClient,
+        client: db,
+        listenClient: db,
         close: async () => {
             await db.end({ timeout: closeTimeout });
-            await listenClient.end({ timeout: closeTimeout });
         },
     };
 }

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

@@ -15,6 +15,15 @@ function canonicalColumnsKey(meta) {
         .map((c) => `${c.name}|${c.pgType}|${c.notNull}|${c.defaultSql ?? ""}|${c.primaryKey ?? false}|${c.identity ?? false}|${c.bigintJsMode ?? ""}`)
         .join("\n");
 }
+function registerPass1Meta(metas, byName, meta, origin) {
+    const existing = byName.get(meta.tableName);
+    if (existing) {
+        throw new Error(`collectTableMetas: table "${meta.tableName}" is registered by ${origin} and ${existing.origin}. ` +
+            "Give one of them a different table name.");
+    }
+    metas.push(meta);
+    byName.set(meta.tableName, { meta, origin });
+}
 export function collectTableMetas(features) {
     const metas = [];
     const byName = new Map();
@@ -37,15 +46,10 @@ export function collectTableMetas(features) {
                 assertBackingTableSuperset(name, fieldMeta, tableMeta);
                 meta = tableMeta;
             }
-            metas.push(meta);
-            byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });
+            registerPass1Meta(metas, byName, meta, `entity "${name}" (${feature.name})`);
         }
         for (const entry of Object.values(feature.storeTables)) {
-            metas.push(entry.meta);
-            byName.set(entry.meta.tableName, {
-                meta: entry.meta,
-                origin: `storeTable "${entry.name}" (${feature.name})`,
-            });
+            registerPass1Meta(metas, byName, entry.meta, `storeTable "${entry.name}" (${feature.name})`);
         }
     }
     // Pass 2: table-tragende Registrierungen. Zwei Pässe, damit eine Entity-

package/dist/db/dialect.d.ts

@@ -54,7 +54,7 @@ export declare function instant(name: string, opts?: {
 }): ColumnBuilder<Temporal.Instant>;
 export declare function plainDate(name: string): ColumnBuilder<Temporal.PlainDate>;
 export declare const decimalColumn: (name: string, precision: number, scale: number) => ColumnBuilder<number>;
-export declare const moneyAmount: (name: string) => ColumnBuilder<number>;
+export declare const moneyAmount: (name: string) => ColumnBuilder<bigint>;
 export type IndexBuilder = {
     readonly __index: true;
     on(...cols: ColumnHandle[]): IndexBuilderWithCols;

package/dist/db/dialect.js

@@ -58,6 +58,8 @@ export function pgTypeToSqlType(pgType) {
 function _toSnakeCase(name) {
     return name.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`).replace(/^_/, "");
 }
+// TValue is never inferred from the factory's declared return type, so a factory that forgets its
+// type argument fails to compile instead of silently typing the column from its own annotation.
 function buildColumn(sqlName, pgType, opts) {
     let notNull = false;
     let primaryKey = false;

package/dist/db/eagerload.js

@@ -18,7 +18,7 @@
 // Custom handlers must pass the viewer explicitly so the parentRef gate is
 // never skipped silently.
 import { requestContext } from "../api/request-context.js";
-import { collectPiiEncryptedFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
+import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
 import { selectMany } from "../db/query.js";
 import { filterReadFields } from "../engine/field-access.js";
 import { buildOwnershipClause, combineClauses, shiftParams, tableNameOf, } from "../engine/ownership.js";
@@ -26,6 +26,7 @@ import { parseRefTargetEntityName } from "../engine/parse-ref-target.js";
 import { isUuid, SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { collectEncryptedFieldNames, decryptEntityFieldValues, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
 import { buildParentRefClause } from "./parent-ref-clause.js";
+import { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 import { executeRawQueryRead } from "./queries/raw-sql.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
@@ -77,7 +78,7 @@ async function resolveRefAccessScope(refEntity, refTable, refTableName, ids, db,
     // No read path exists for non-uuid ids, so nothing can be access-checked.
     if (refEntity.idType !== undefined && refEntity.idType !== "uuid")
         return { kind: "none" };
-    const params = [ids];
+    const params = [toPostgresArrayLiteral(ids)];
     let tenantClause = "";
     if (refTable["tenantId"] !== undefined && db.mode === "tenant") {
         params.push(db.tenantId, SYSTEM_TENANT_ID);
@@ -162,7 +163,7 @@ export async function enrichWithReferences(rows, entity, resolveEntity, db, view
         const rawRefRows = scope.kind === "restricted"
             ? lookedUpRows.filter((r) => scope.readableIds.has(String(r["id"])))
             : lookedUpRows;
-        const piiFields = collectPiiEncryptedFields(refEntity);
+        const piiFields = collectPiiSubjectFields(refEntity);
         const encryptedFields = collectEncryptedFieldNames(refEntity);
         const kms = configuredPiiSubjectKms();
         const map = await buildRefLookupMap(rawRefRows, refEntity, rf.refEntityName, viewer, piiFields, encryptedFields, kms);

package/dist/db/event-store-executor-context.d.ts

@@ -33,15 +33,14 @@ export type ExecutorContext = {
         readonly includeDeleted?: boolean;
     }) => Promise<Record<string, unknown> | null>;
     readonly assertStreamWritable: (db: TenantDb, id: EntityId, tenantId: TenantId) => Promise<void>;
-    readonly loadWithOwnership: (db: TenantDb, idWhere: WhereObject, ownership: {
-        kind: "pass";
-    } | {
-        kind: "empty";
-    } | {
+    readonly probeOwnershipWithStreamVersion: (db: TenantDb, idWhere: WhereObject, ownership: {
         kind: "sql";
         sqlText: string;
         params: readonly unknown[];
-    }) => Promise<Record<string, unknown>[]>;
+    }, streamTenantId: TenantId, aggregateId: string) => Promise<{
+        readonly owned: boolean;
+        readonly streamVersion: number;
+    }>;
     readonly loadDetailSnapshot: (db: TenantDb, idWhere: WhereObject, ownership: {
         kind: "pass";
     } | {
@@ -63,6 +62,7 @@ export type ExecutorContext = {
         subjectSource?: Record<string, unknown>;
         keyTenantId?: TenantId | undefined;
         ownerFallback?: Record<string, unknown>;
+        onErasedSubject?: "sentinel";
     }) => Promise<Record<string, unknown>>;
     readonly decryptForRead: (row: Record<string, unknown>, opts?: DecryptForReadOptions) => Promise<Record<string, unknown>>;
     readonly ownerTransitionRekeys: (previous: Record<string, unknown>, mergedNew: Record<string, unknown>, submittedChanges: Record<string, unknown>) => Record<string, unknown>;

package/dist/db/event-store-executor-context.js

@@ -1,5 +1,5 @@
 import { requestContext } from "../api/request-context.js";
-import { collectPiiEncryptedFields, configuredPiiSubjectKms, decryptPiiFieldValues, encryptPiiFieldValues, KeyErasedError, } from "../crypto/index.js";
+import { collectPiiEncryptedFields, collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, encryptPiiFieldValues, KeyErasedError, } from "../crypto/index.js";
 import { personalFieldsRekeyedOnOwnerTransition } from "../crypto/owner-transition-rekey.js";
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
 import { shiftParams } from "../engine/ownership.js";
@@ -173,6 +173,11 @@ export function buildExecutorContext(table, entity, options) {
     const hasEncryptedFields = encryptedFields.size > 0;
     const piiSubjectFields = collectPiiEncryptedFields(entity);
     const hasPiiFields = piiSubjectFields.length > 0;
+    // Decrypt keeps file-reference fields: rows and event payloads written by
+    // the old backfill may hold ciphertext there, and decrypt passes plaintext
+    // through untouched.
+    const piiDecryptFields = collectPiiSubjectFields(entity);
+    const hasPiiDecryptFields = piiDecryptFields.length > 0;
     function fieldCipher() {
         if (options.encryption)
             return options.encryption;
@@ -210,6 +215,7 @@ export function buildExecutorContext(table, entity, options) {
                     ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
                     ...(opts?.subjectSource !== undefined && { subjectSource: opts.subjectSource }),
                     ...(opts?.ownerFallback !== undefined && { ownerFallback: opts.ownerFallback }),
+                    ...(opts?.onErasedSubject !== undefined && { onErasedSubject: opts.onErasedSubject }),
                 });
             }
             catch (e) {
@@ -230,8 +236,8 @@ export function buildExecutorContext(table, entity, options) {
     async function decryptForRead(row, opts) {
         let out = row;
         const kms = piiKms();
-        if (hasPiiFields && kms) {
-            out = await decryptPiiFieldValues(out, piiSubjectFields, kms, kmsContextFor());
+        if (hasPiiDecryptFields && kms) {
+            out = await decryptPiiFieldValues(out, piiDecryptFields, kms, kmsContextFor());
         }
         if (hasEncryptedFields) {
             out = await decryptEntityFieldValues(out, encryptedFields, fieldCipher(), opts?.degradeUndecryptable
@@ -301,24 +307,6 @@ export function buildExecutorContext(table, entity, options) {
             throw new ArchivedStreamError(tenantId, String(id));
         }
     }
-    // SELECT a row by id with the ownership clause applied at the DB layer.
-    // Detail() uses this both on cold path and as a cache-revalidation probe.
-    async function loadWithOwnership(db, idWhere, ownership) {
-        if (ownership.kind === "empty")
-            return [];
-        if (ownership.kind === "pass") {
-            const row = await db.fetchOne(table, idWhere);
-            return row ? [row] : [];
-        }
-        // ownership has raw SQL — splice it into a raw query alongside the
-        // idFilter + tenant-filter that TenantDb would have added.
-        const tableName = String(schemaTableName(table));
-        const { whereParts, params } = buildRawIdWhere(db, idWhere, ownership);
-        const sqlText = `SELECT * FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
-        return [
-            ...(await executeRawQueryRead(tenantDbRunner(db), sqlText, params)),
-        ];
-    }
     // Tenant filter + idFilter + ownership predicate as raw SQL, mirroring what
     // TenantDb.fetchOne/readWhere add. idFilter only yields `id` and a boolean
     // `isDeleted`, so no null/IS NULL branch is needed.
@@ -351,6 +339,21 @@ export function buildExecutorContext(table, entity, options) {
         return (`(SELECT MAX("version") FROM "kumiko_events" WHERE "aggregate_id" = $${aggregateIdParam} ` +
             `AND "tenant_id" = $${tenantIdParam}) AS "__streamVersion"`);
     }
+    // Cache-hit revalidation: ownership predicate and live stream version in ONE
+    // statement, so a cache hit costs the same single roundtrip as the cold path.
+    async function probeOwnershipWithStreamVersion(db, idWhere, ownership, streamTenantId, aggregateId) {
+        const tableName = String(schemaTableName(table));
+        const { whereParts, params } = buildRawIdWhere(db, idWhere, ownership);
+        params.push(aggregateId, streamTenantId);
+        const sqlText = `SELECT 1 AS "__owned", ${streamVersionSubquerySql(params.length - 1, params.length)} ` +
+            `FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
+        const rows = await executeRawQueryRead(tenantDbRunner(db), sqlText, params);
+        const first = rows[0];
+        if (!first)
+            return { owned: false, streamVersion: 0 };
+        const version = first["__streamVersion"];
+        return { owned: true, streamVersion: typeof version === "number" ? version : 0 };
+    }
     // Row and MAX(version) in ONE statement: two reads can pair a post-write
     // version with a pre-write row, and update({version: detail.version}) would
     // then pass the optimistic lock and overwrite the newer write (lost update).
@@ -431,7 +434,7 @@ export function buildExecutorContext(table, entity, options) {
         idFilter,
         loadById,
         assertStreamWritable,
-        loadWithOwnership,
+        probeOwnershipWithStreamVersion,
         loadDetailSnapshot,
         loadExpectSnapshot,
         encryptForStorage,

package/dist/db/event-store-executor-read.js

@@ -6,7 +6,7 @@ import { coerceRow, extractTableInfo } from "../db/query.js";
 import { buildOwnershipClause, combineClauses, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { UnprocessableError } from "../errors/index.js";
-import { getStreamVersion, getStreamVersions } from "../event-store/index.js";
+import { getStreamVersion } from "../event-store/index.js";
 import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta.js";
 import { rehydrateCompoundTypes } from "./compound-types.js";
 import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
@@ -387,6 +387,7 @@ function referenceTargetTable(name, entity) {
 // Projected alongside the row when a reference sort is active, so the keyset
 // cursor carries the label that was ordered by instead of the FK's UUID.
 const SORT_LABEL_ALIAS = "__kumiko_sort_label";
+const STREAM_VERSION_ALIAS = "__streamVersion";
 // fw#2741 — resolve a `sortable: true` reference field's label inline for
 // ORDER BY. A correlated scalar subquery, not a join: the result set keeps one
 // row per entity row, the read model stays untouched, and the lookup rides the
@@ -448,7 +449,7 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
     };
 }
 export function createReadVerbs(ctx) {
-    const { table, entity, entityName, entityCache, searchAdapter, softDelete, streamTenantFor, idFilter, loadWithOwnership, loadDetailSnapshot, decryptForRead, encryptForStorage, } = ctx;
+    const { table, entity, entityName, entityCache, searchAdapter, softDelete, streamTenantFor, idFilter, probeOwnershipWithStreamVersion, loadDetailSnapshot, decryptForRead, encryptForStorage, } = ctx;
     return {
         // list + detail are unchanged from crud-executor — projections are the
         // read-model and serve these queries directly.
@@ -644,15 +645,28 @@ export function createReadVerbs(ctx) {
             const whereClauseSqlText = whereSql.length > 0 ? ` WHERE ${whereSql.join(" AND ")}` : "";
             // Project the resolved label too, so the keyset cursor below carries the
             // value that was ordered by rather than the FK column's UUID.
-            const selectList = referenceSortExpr !== undefined && sortSql !== undefined
-                ? `*, ${sortSql} AS "${SORT_LABEL_ALIAS}"`
-                : "*";
+            const sortLabelProjection = referenceSortExpr !== undefined && sortSql !== undefined
+                ? `, ${sortSql} AS "${SORT_LABEL_ALIAS}"`
+                : "";
+            // Stream version in the same statement as the rows: a separate read could pair a
+            // post-write version with a pre-write row, and update({version}) would then pass
+            // the optimistic lock against a state the client never saw (see loadDetailSnapshot).
+            params.push(streamTenantFor(user));
+            const streamVersionProjection = `, (SELECT MAX("version") FROM "kumiko_events" ` +
+                `WHERE "aggregate_id" = "${tableName}"."id" AND "tenant_id" = $${params.length}) ` +
+                `AS "${STREAM_VERSION_ALIAS}"`;
+            const selectList = `*${sortLabelProjection}${streamVersionProjection}`;
             const listSql = `SELECT ${selectList} FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
             const rawRows = await executeRawQueryRead(runner, listSql, params);
             const lastSortLabel = rawRows[rawRows.length - 1]?.[SORT_LABEL_ALIAS];
+            // Aliases are query artifacts, not columns of this entity — strip them before
+            // coercion so they never reach the caller or the entity cache.
+            const streamVersions = rawRows.map((r) => {
+                const v = r[STREAM_VERSION_ALIAS];
+                delete r[STREAM_VERSION_ALIAS];
+                return typeof v === "number" ? v : 0;
+            });
             if (referenceSortExpr !== undefined) {
-                // The alias is a sort artifact, not a column of this entity — strip it
-                // before coercion so it never reaches the caller or the entity cache.
                 for (const row of rawRows)
                     delete row[SORT_LABEL_ALIAS];
             }
@@ -668,10 +682,7 @@ export function createReadVerbs(ctx) {
             // Stream version is authoritative (see detail()): ctx.appendEvent bumps the
             // stream without touching row.version, so the raw row version would hand
             // clients a stale optimistic-lock base. Rows without events keep theirs.
-            const streamVersions = decryptedRows.length > 0
-                ? await getStreamVersions(runner, decryptedRows.map((r) => String(r["id"])), streamTenantFor(user))
-                : new Map();
-            const rows = decryptedRows.map((r) => withStreamVersion(r, streamVersions.get(String(r["id"])) ?? 0));
+            const rows = decryptedRows.map((r, i) => withStreamVersion(r, streamVersions[i] ?? 0));
             // Cache the still-encrypted raw rows (read-row version): same at-rest guarantee as
             // detail()'s encryptForStorage round-trip, without a re-encrypt; detail() rejects
             // a cached version that differs from the stream.
@@ -730,16 +741,20 @@ export function createReadVerbs(ctx) {
             if (entityCache && entityName) {
                 const cached = await entityCache.get(user.tenantId, entityName, payload.id);
                 if (cached) {
+                    let streamVersion;
                     if (ownership.kind === "sql") {
                         // Re-check ownership predicate (incl. the parent-ref gate) against
                         // the live row — the cache is keyed only by tenant + id, not by
-                        // role, so a cache hit can't bypass either gate. Deliberate price:
-                        // one extra roundtrip per cache hit once either gate produces SQL.
-                        const checkRows = await loadWithOwnership(db, idWhere, ownership);
-                        if (checkRows.length === 0)
+                        // role, so a cache hit can't bypass either gate. The probe carries
+                        // the stream version in the same statement.
+                        const probe = await probeOwnershipWithStreamVersion(db, idWhere, ownership, streamTenantFor(user), String(payload.id));
+                        if (!probe.owned)
                             return null;
+                        streamVersion = probe.streamVersion;
+                    }
+                    else {
+                        streamVersion = await getStreamVersion(tenantDbRunner(db), String(payload.id), streamTenantFor(user));
                     }
-                    const streamVersion = await getStreamVersion(tenantDbRunner(db), String(payload.id), streamTenantFor(user));
                     if (!(streamVersion > 0 && cached["version"] !== streamVersion)) {
                         // Cached rows are stored re-encrypted (see the `set` below) so an
                         // `encrypted` field's plaintext never sits in a second at-rest

package/dist/db/event-store-executor-write.d.ts

@@ -1,3 +1,3 @@
-import type { EventStoreExecutor } from "./event-store-executor.js";
+import { type EventStoreExecutor } from "./event-store-executor.js";
 import { type ExecutorContext } from "./event-store-executor-context.js";
 export declare function createWriteVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor, "create" | "update" | "delete" | "forget" | "restore">;