@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

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

@@ -1,13 +1,13 @@
-// PII field encryption with per-subject DEKs (crypto-shredding, #724 phase C).
+// PII field encryption with per-subject DEKs (crypto-shredding).
 // Same executor hook points as `encrypted: true`, but the key belongs to the
 // erase subject — kms.eraseKey(subject) makes every value unreadable at once.
 // Storage format is a sniffable string that fits existing text columns and
 // names its subject inline, so decrypt needs no schema change and no resolver:
 //   kumiko-pii:v2:<subjectKey>:<base64(iv|tag|ciphertext)>
-// v2 GCM-binds the ciphertext to `subjectKey|field` as AAD (#1263) — subject
+// v2 GCM-binds the ciphertext to `subjectKey|field` as AAD — subject
 // selects the DEK, field stops a cut-and-paste between two fields of the
 // SAME subject (same DEK, so key selection alone can't catch that) from
-// decrypting silently. v1 (no AAD) stays decrypt-only for pre-#1263 rows;
+// decrypting silently. v1 (no AAD) stays decrypt-only for older rows;
 // every new write emits v2.
 // v3 = v2 for jsonb fields: the plaintext is JSON.stringify(value) and decrypt
 // JSON.parses it back, so a jsonb string/number/object round-trips by type.
@@ -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;
         }
@@ -187,7 +189,7 @@ export async function decryptPiiFieldValues(row, piiFields, kms, kmsCtx) {
     for (const name of piiFields) {
         const value = out[name];
         // Pre-engine plaintext rows pass through unchanged (mixed-state reads
-        // work during rollout; backfill is tracked in kumiko-framework#799).
+        // work during rollout).
         if (!isPiiCiphertext(value))
             continue;
         const { subject, blob, hasAad, isJson } = parseCiphertext(value);

package/dist/crypto/subject-resolver.d.ts

@@ -33,5 +33,5 @@ export declare function isRecordKeyedField(field: EntityDefinition["fields"][str
 export declare function collectPiiSubjectFields(entity: EntityDefinition): readonly string[];
 export declare function collectPiiEncryptedFields(entity: EntityDefinition): readonly string[];
 export declare function collectPiiFileReferenceFields(entity: EntityDefinition): readonly string[];
-/** Subject-annotated fields that may be plaintext in the derived search index (#1610). */
+/** Subject-annotated fields that may be plaintext in the derived search index. */
 export declare function collectSearchableSubjectFields(entity: EntityDefinition): readonly string[];

package/dist/crypto/subject-resolver.js

@@ -107,7 +107,7 @@ function resolveEnvelopeRecordSubject(fieldName, envelope) {
 // backfill catalog path (backfillEventPiiEncryption) — the reason the two
 // can never encrypt the same field under different subjects. A "user"
 // subject whose owner field is empty falls back to the declared whenAbsent
-// stance and throws when none is declared (fw#2776); "tenant"/"self" throw
+// stance and throws when none is declared; "tenant"/"self" throw
 // on an empty envelope, since their facts are structural.
 export function resolveEventSubject(fieldName, spec, payload, envelope) {
     const normalized = normalizeEventPiiSubject(spec);
@@ -177,7 +177,7 @@ export function collectPiiFileReferenceFields(entity) {
         .filter(([, field]) => hasSubjectAnnotation(field) && isFileReferenceField(field))
         .map(([name]) => name);
 }
-/** Subject-annotated fields that may be plaintext in the derived search index (#1610). */
+/** Subject-annotated fields that may be plaintext in the derived search index. */
 export function collectSearchableSubjectFields(entity) {
     return Object.entries(entity.fields)
         .filter(([, field]) => {

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/apply-entity-event.d.ts

@@ -3,7 +3,7 @@ import type { EntityDefinition } from "../engine/types/index.ts";
 import type { StoredEvent } from "../event-store/index.ts";
 import type { DbRow } from "./connection.ts";
 import type { TableColumns } from "./dialect.ts";
-type Table = TableColumns<any>;
+type Table = TableColumns;
 export type AutoVerb = "created" | "updated" | "deleted" | "restored" | "forgotten";
 export type ApplyResult = {
     readonly kind: "applied";
@@ -12,11 +12,11 @@ export type ApplyResult = {
 } | {
     readonly kind: "skipped";
 };
-/** Parsed event.type → AutoVerb wenn das Event eines der Auto-Verben
- *  auf dem gegebenen Aggregate ist. null sonst (Domain-Event). */
+/** Parses event.type into an AutoVerb when the event is an auto-verb
+ *  for the given aggregate; otherwise returns null (a domain event). */
 export declare function parseAutoVerb(event: StoredEvent): AutoVerb | null;
-/** Idempotente Anwendung eines Auto-Events auf die Entity-Tabelle.
- *  Wird sowohl beim Live-Append (innerhalb der Write-TX) als auch beim
- *  Rebuild (innerhalb der Rebuild-TX) gerufen — identische Logik. */
+/** Applies an auto-event idempotently to the entity table.
+ *  Called both during live append (inside the write TX) and during rebuild
+ *  (inside the rebuild TX), using identical logic. */
 export declare function applyEntityEvent(event: StoredEvent, table: Table, entity: EntityDefinition, tx: ExecutorManagedRunner): Promise<ApplyResult>;
 export {};

package/dist/db/apply-entity-event.js

@@ -1,17 +1,17 @@
-// applyEntityEvent — die EINZIGE Schreib-Logik für r.entity-Tabellen aus
-// Stored-Events. Beide Aufrufer benutzen sie:
+// applyEntityEvent — the ONLY write logic for r.entity tables from
+// StoredEvents. Both callers use it:
 //
-//   - createEventStoreExecutor (live, im Write-TX) — übergibt das gerade
-//     appendete StoredEvent direkt; sensitive Felder liegen als Tabellen-
-//     Ciphertext im Payload (boot-validiert pii/encrypted, #967).
-//   - rebuildProjection via ImplicitProjection (replay, im Rebuild-TX) —
-//     übergibt dasselbe StoredEvent; apply kopiert Ciphertext byte-gleich
-//     zurück, bidx wird unten neu berechnet.
+//   - createEventStoreExecutor (live, in the write TX) passes the just-appended
+//     StoredEvent directly; sensitive fields are table ciphertext in the payload
+//     (validated at boot as pii/encrypted).
+//   - rebuildProjection via ImplicitProjection (replay, in the rebuild TX)
+//     passes the same StoredEvent; apply copies ciphertext byte-for-byte,
+//     while bidx is recalculated below.
 //
-// Live==Rebuild-Equivalence ist damit by-construction für ALLE Felder —
-// eine geänderte Schreib-Logik muss nur an EINER Stelle gepflegt werden,
-// kein Sync-Contract mehr. Einzige legitime Divergenz: Crypto-Shredding
-// (DEK erased → Wert unlesbar, bidx NULL). Load-bearing Test:
+// Live==Rebuild equivalence therefore holds by construction for ALL fields —
+// changed write logic needs to be maintained in only ONE place, with no sync
+// contract. The only legitimate divergence is crypto-shredding
+// (DEK erased → value unreadable, bidx NULL). Load-bearing test:
 // db/__tests__/implicit-projection-equivalence.integration.test.ts.
 //
 // Tenant isolation: applyEntityEvent expects an ExecutorManagedRunner (tx or pool), NOT
@@ -23,26 +23,27 @@
 //      the TenantDb wrapper default.
 // The missing TenantDb wrapper in this function is therefore not a hole.
 //
-// Auto-Verben:
+// Auto-verbs:
 //   <entity>.created   → INSERT
 //   <entity>.updated   → UPDATE WHERE id=aggregateId
-//   <entity>.deleted   → soft-delete-UPDATE wenn entity.softDelete, sonst hard-DELETE
-//   <entity>.restored  → undelete-UPDATE (nur bei softDelete sinnvoll)
-//   <entity>.forgotten → hard-DELETE immer (Art.17-Purge, auch bei softDelete);
-//                        via executor.forget(). Rebuild replayt created→forgotten
-//                        → Row weg, rebuild-safe (was ein direktes deleteMany nicht ist).
+//   <entity>.deleted   → soft-delete-UPDATE if entity.softDelete, otherwise hard-DELETE
+//   <entity>.restored  → undelete-UPDATE (meaningful only for softDelete)
+//   <entity>.forgotten → always hard-DELETE (Art.17 purge, including softDelete);
+//                        via executor.forget(). Rebuild replays created→forgotten
+//                        → the row is gone, making this rebuild-safe (unlike a
+//                        direct deleteMany).
 //
-// Domain-Events (r.defineEvent) auf demselben Aggregate werden hier NICHT
-// behandelt — die liefen im Live-Pfad nie durch den Executor und müssen
-// von expliziten r.projection-apply-Handlern oder r.multiStreamProjection
-// behandelt werden. ImplicitProjection registriert die Auto-Verben.
+// Domain events (r.defineEvent) on the same aggregate are NOT handled here —
+// they never went through the Executor in the live path and must be handled by
+// explicit r.projection-apply handlers or r.multiStreamProjection.
+// ImplicitProjection registers the auto-verbs.
 //
-// Return-Shape: ApplyResult mit `kind` + optionaler `row`.
-//   - "applied" → Schreibung lief durch. `row` enthält die geschriebene
-//     Row für create/update/soft-delete/restore. Bei hard-delete ist
-//     `row` null (DELETE-Statements geben keine returning-Row her).
-//   - "skipped" → Event ist kein Auto-Verb (Domain-Event auf demselben
-//     Aggregate). Caller no-op.
+// Return shape: ApplyResult with `kind` and an optional `row`.
+//   - "applied" → the write completed. `row` contains the written row for
+//     create/update/soft-delete/restore. For hard-delete, `row` is null
+//     (DELETE statements do not provide a returning row).
+//   - "skipped" → the event is not an auto-verb (a domain event on the same
+//     aggregate). Caller no-op.
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { requestContext } from "../api/request-context.js";
 import { collectLookupableFields, computeBlindIndexValues } from "../crypto/blind-index.js";
@@ -51,8 +52,8 @@ import { collectPiiFileReferenceFields } from "../crypto/subject-resolver.js";
 import { deleteMany, insertOne, updateMany } from "../db/query.js";
 import { InternalError } from "../errors/index.js";
 const AUTO_VERBS = ["created", "updated", "deleted", "restored", "forgotten"];
-/** Parsed event.type → AutoVerb wenn das Event eines der Auto-Verben
- *  auf dem gegebenen Aggregate ist. null sonst (Domain-Event). */
+/** Parses event.type into an AutoVerb when the event is an auto-verb
+ *  for the given aggregate; otherwise returns null (a domain event). */
 export function parseAutoVerb(event) {
     const prefix = `${event.aggregateType}.`;
     if (!event.type.startsWith(prefix))
@@ -81,9 +82,9 @@ async function decryptFileReferenceCiphertext(entity, values) {
     }
     return decrypted;
 }
-/** Idempotente Anwendung eines Auto-Events auf die Entity-Tabelle.
- *  Wird sowohl beim Live-Append (innerhalb der Write-TX) als auch beim
- *  Rebuild (innerhalb der Rebuild-TX) gerufen — identische Logik. */
+/** Applies an auto-event idempotently to the entity table.
+ *  Called both during live append (inside the write TX) and during rebuild
+ *  (inside the rebuild TX), using identical logic. */
 export async function applyEntityEvent(event, table, entity, tx) {
     const verb = parseAutoVerb(event);
     if (verb === null)
@@ -91,17 +92,17 @@ export async function applyEntityEvent(event, table, entity, tx) {
     const softDelete = entity.softDelete ?? false;
     switch (verb) {
         case "created": {
-            // tenantId-Resolution explizit, nicht via Spread-Reihenfolge:
-            // Live-Pfad nutzt tx=tenantDbRunner(db) (kein TenantDb-Wrapper-Auto-Inject),
-            // beim Replay erst recht keiner. Default = event.tenantId; payload
-            // gewinnt NUR wenn gültig string mit length > 0 (seedTenantMembership-
-            // Pfad: Operator schreibt im Ziel-Tenant, Event im Operator-Tenant).
-            // Pinst durch db/__tests__/apply-entity-event-tenant.integration.ts.
+            // Resolve tenantId explicitly rather than through spread order:
+            // the live path uses tx=tenantDbRunner(db) (with no TenantDb wrapper
+            // auto-injection), and replay has no wrapper either. The default is
+            // event.tenantId; the payload wins ONLY when it is a non-empty string
+            // (seedTenantMembership path: the operator writes in the target tenant,
+            // while the event belongs to the operator tenant).
             //
-            // Fail-loud wenn payload.tenantId gesetzt aber invalid (leer/null/
-            // non-string): das ist tenant-isolation-kritisch — silent fallback
-            // auf event.tenantId würde eine Bug-payload in den Operator-Tenant
-            // schreiben statt zu failen, was Cross-Tenant-Datendrift erzeugt.
+            // Fail loudly when payload.tenantId is set but invalid (empty/null/
+            // non-string): this is critical for tenant isolation. Silently falling
+            // back to event.tenantId would write a bad payload into the operator
+            // tenant and cause cross-tenant data drift.
             const payloadTenantId = event.payload["tenantId"];
             let tenantId;
             if (payloadTenantId === undefined) {
@@ -117,10 +118,10 @@ export async function applyEntityEvent(event, table, entity, tx) {
             }
             const row = await insertOne(tx, table, {
                 ...(await decryptFileReferenceCiphertext(entity, event.payload)),
-                // Blind-Index-Spalten aus dem Payload-Wert (ciphertext → decrypt →
-                // HMAC, plaintext → HMAC, erased → NULL). Hier statt im Executor,
-                // damit Live-Write und Rebuild denselben Wert produzieren und der
-                // deterministische HMAC nie im Event-Log landet.
+                // Compute blind-index columns from the payload value (ciphertext → decrypt →
+                // HMAC, plaintext → HMAC, erased → NULL). This is done here rather
+                // than in the Executor so live writes and rebuilds produce the same
+                // value and the deterministic HMAC never enters the event log.
                 ...(await computeBlindIndexValues(event.payload, collectLookupableFields(entity))),
                 tenantId,
                 id: event.aggregateId,
@@ -131,7 +132,7 @@ export async function applyEntityEvent(event, table, entity, tx) {
             return { kind: "applied", verb, row: row ?? null };
         }
         case "updated": {
-            // payload-Shape: { changes, previous } — siehe event-store-executor.ts.
+            // Payload shape: { changes, previous } — see event-store-executor.ts.
             const rawChanges = (event.payload["changes"] ?? {}); // @cast-boundary engine-payload
             const changes = {};
             for (const [key, value] of Object.entries(await decryptFileReferenceCiphertext(entity, rawChanges))) {
@@ -146,7 +147,7 @@ export async function applyEntityEvent(event, table, entity, tx) {
             }
             const rows = await updateMany(tx, table, {
                 ...changes,
-                // bidx nur für die geänderten lookupable-Felder (siehe created).
+                // Recompute bidx only for the lookupable fields that changed (see created).
                 ...(await computeBlindIndexValues(changes, collectLookupableFields(entity))),
                 version: event.version,
                 modifiedAt: event.createdAt,
@@ -166,16 +167,15 @@ export async function applyEntityEvent(event, table, entity, tx) {
                 }, { id: event.aggregateId });
                 return { kind: "applied", verb, row: rows[0] ?? null };
             }
-            // Hard-Delete: DELETE-Statement gibt keine returning-Row her und
-            // der Live-Pfad nutzt eh `existing` (pre-delete-Snapshot) für die
-            // Response. Beim Replay ist das fine, der Caller braucht die Row
-            // nicht weiter.
+            // Hard-delete: the DELETE statement provides no returning row, and
+            // the live path already uses `existing` (the pre-delete snapshot) for
+            // the response. During replay, the caller does not need the row.
             await deleteMany(tx, table, { id: event.aggregateId });
             return { kind: "applied", verb, row: null };
         }
         case "restored": {
-            // Restore ist nur bei softDelete sinnvoll. Hard-Delete-Entities sollten
-            // keine restored-Events erhalten — falls doch, defensive skip.
+            // Restore is meaningful only for softDelete. Hard-delete entities should
+            // not receive restored events; if they do, defensively skip them.
             if (!softDelete)
                 return { kind: "skipped" };
             const rows = await updateMany(tx, table, {

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

@@ -1,4 +1,4 @@
-// Immediate blind-index nulling after a subject erase (#818).
+// Immediate blind-index nulling after a subject erase.
 //
 // After kms.eraseKey the ciphertext is unreadable, but the deterministic
 // bidx column would stay matchable until the next write/rebuild — a
@@ -33,9 +33,9 @@ export async function nullBlindIndexesForSubject(db, features, subjectKey) {
         }
     }
     // Skip entities whose projection was never migrated — same class as
-    // subjectRowExistsInTenant (fw#2348). A throw here runs AFTER eraseKey
+    // subjectRowExistsInTenant. A throw here runs AFTER eraseKey
     // in forget-subject and would leave deterministic bidx columns still
-    // linkable (fw#2550). One batched existence query instead of one
+    // linkable. One batched existence query instead of one
     // roundtrip per entity.
     const existing = await existingTableNames(db, candidates.map((c) => c.tableName));
     for (const { tableName, lookupable } of candidates) {
@@ -59,7 +59,7 @@ async function existingTableNames(db, 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
+// Tenant-scope oracle for crypto-shredding's forget-subject: a
 // "user"-kind subject id is often not a real user (share-token recipient,
 // email subscriber, ...) — those entities self-own their PII (`pii: true`,
 // i.e. their own row id IS the subject) and carry a real tenant_id,
@@ -71,14 +71,14 @@ async function existingTableNames(db, tableNames) {
 // Invariant: `id` must never be client-settable on self-PII entities — the
 // framework create path strips client ids; app write paths MUST do the same
 // or a DPO could plant a foreign subject id in their tenant and pass this
-// oracle (#2348). Upgrade path: require an event-store provenance check
+// oracle. Upgrade path: require an event-store provenance check
 // (`aggregate_id = subjectId` under the actor tenant) when apps need
 // client-supplied ids.
 export async function subjectRowExistsInTenant(db, features, subjectId, tenantId) {
     // Prefetch which self-PII projection tables actually exist — probing a
     // missing relation used to throw (and get swallowed), which both hid
     // real schema bugs and risked poisoning the driver connection for the
-    // rest of the forget TX (fw#2348 / framework#356).
+    // rest of the forget TX.
     const candidateTables = [];
     for (const feature of features.values()) {
         for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
@@ -121,7 +121,7 @@ function findEntityByExactName(features, entityName) {
 //
 // Invariant: sound only because `id` is a single-column PK per entity
 // table (globally unique, unspoofable via a client-supplied explicitId
-// at create) — a composite PK or shared table would break this (#2348).
+// at create) — a composite PK or shared table would break this.
 export async function recordRowExistsInTenant(db, features, entityName, recordId, tenantId) {
     const entity = findEntityByExactName(features, entityName);
     if (!entity)

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;