@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/db/eagerload.js

@@ -24,12 +24,15 @@ import { filterReadFields } from "../engine/field-access.js";
 import { buildOwnershipClause, combineClauses, shiftParams, tableNameOf, } from "../engine/ownership.js";
 import { parseRefTargetEntityName } from "../engine/parse-ref-target.js";
 import { isUuid, SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
+import { scrubLogValue } from "../logging/scrub.js";
+import { createFallbackLogger } from "../logging/utils.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";
+const log = createFallbackLogger("eagerload");
 function isReferenceField(field) {
     return field.type === "reference";
 }
@@ -105,7 +108,11 @@ async function buildRefLookupMap(rawRefRows, refEntity, refEntityName, viewer, p
             decrypted = await decryptReferencedRow(r, piiFields, encryptedFields, kms);
         }
         catch (e) {
-            console.warn(`[eagerload] failed to decrypt referenced row entity=${refEntityName} id=${String(r["id"])}: ${e instanceof Error ? e.message : String(e)}`);
+            log.warn("failed to decrypt referenced row", {
+                entity: refEntityName,
+                id: String(r["id"]),
+                err: scrubLogValue(e),
+            });
             continue;
         }
         const id = decrypted["id"];
@@ -126,26 +133,26 @@ function collectRefIds(rows, rf) {
     }
     return ids;
 }
-/** Eagerload für eine Liste von Rows. Mutiert nicht — gibt eine
- *  flache Kopie der Rows mit hinzugefügtem `_refs`-Property zurück. */
+/** Eagerloads a list of rows without mutating them; returns shallow copies
+ *  with an added `_refs` property. */
 export async function enrichWithReferences(rows, entity, resolveEntity, db, viewer) {
     const refFields = collectReferenceFields(entity);
     if (refFields.length === 0 || rows.length === 0) {
         return rows.map((r) => ({ ...r }));
     }
-    // Pro reference-Field: deduped Set der IDs sammeln, dann ein
-    // einziger SELECT WHERE id IN (...). Maps werden parallel gebaut
-    // damit die Lookups nicht serialisieren (Promise.all).
+    // For each reference field, collect IDs in a deduplicated Set, then run one
+    // SELECT WHERE id IN (...). Build the maps in parallel so the lookups do
+    // not run serially (Promise.all).
     const lookupMaps = await Promise.all(refFields.map(async (rf) => {
         const ids = collectRefIds(rows, rf);
         if (ids.size === 0)
             return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
         const refEntity = resolveEntity(rf.refEntityName);
         if (refEntity === undefined) {
-            // Author-Fehler oder Race-Condition (entity gerade umbenannt
-            // ohne registry-Reload). Boot-Validator hat das normalerweise
-            // gepinnt; Runtime-Defense: leere Map → Renderer fällt auf
-            // UUID zurück, kein Crash.
+            // Authoring error or race condition (the entity was renamed without a
+            // registry reload). The boot validator normally catches this;
+            // as a runtime safeguard, an empty map makes the renderer fall back
+            // to the UUID instead of crashing.
             return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
         }
         const refTable = buildEntityTable(rf.refEntityName, refEntity);
@@ -159,7 +166,9 @@ export async function enrichWithReferences(rows, entity, resolveEntity, db, view
         const scope = await resolveRefAccessScope(refEntity, refTable, refTableName, idArray, db, viewer);
         if (scope.kind === "none")
             return emptyLookup;
-        const lookedUpRows = (await selectMany(db, refTable, { id: idArray }));
+        const lookedUpRows = await selectMany(db, refTable, {
+            id: idArray,
+        });
         const rawRefRows = scope.kind === "restricted"
             ? lookedUpRows.filter((r) => scope.readableIds.has(String(r["id"])))
             : lookedUpRows;
@@ -190,7 +199,7 @@ export async function enrichWithReferences(rows, entity, resolveEntity, db, view
         return { ...row, _refs: refs };
     });
 }
-/** Single-Row-Variante für detail-Calls. */
+/** Single-row variant for detail calls. */
 export async function enrichRowWithReferences(row, entity, resolveEntity, db, viewer) {
     const enriched = await enrichWithReferences([row], entity, resolveEntity, db, viewer);
     return enriched[0] ?? { ...row, _refs: {} };

package/dist/db/entity-field-encryption.d.ts

@@ -3,6 +3,7 @@ import { type Logger } from "../logging/index.ts";
 import type { EnvelopeCipher } from "../secrets/envelope-cipher.ts";
 export declare function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string>;
 export declare function isSensitiveLabelField(entity: EntityDefinition, field: string): boolean;
+export declare function holdsCiphertextOrSecret(entity: EntityDefinition, field: string): boolean;
 export declare function isListFilterAllowed(entity: EntityDefinition, field: string, filter: {
     readonly op: string;
     readonly value: unknown;

package/dist/db/entity-field-encryption.js

@@ -24,7 +24,7 @@ export function isSensitiveLabelField(entity, field) {
 }
 // A `sensitive` (find: "secret") field is never comparable either, even while its value is still
 // legacy plaintext.
-function holdsCiphertextOrSecret(entity, field) {
+export function holdsCiphertextOrSecret(entity, field) {
     const def = entity.fields[field];
     if (def === undefined)
         return false;

package/dist/db/entity-table-meta.d.ts

@@ -11,7 +11,7 @@ export declare function resolveTableName(entityName: string, entity: EntityDefin
  * (convention: `store_*`) — or build columns by hand with `defineUnmanagedTable`.
  *
  * Named `derive*` (not `build*Meta`) so it is not mistaken for the unmanaged
- * escape hatch (#1208).
+ * escape hatch.
  */
 export declare function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options: BuildEntityTableMetaOptions & {
     readonly source: "unmanaged";
@@ -20,7 +20,7 @@ export declare function deriveEntityTableMeta(entityName: string, entity: Entity
 export declare function assertBackingTableSuperset(entityName: string, fieldMeta: EntityTableMeta, tableMeta: EntityTableMeta): void;
 /**
  * Hand-built EntityTableMeta for direct-write stores (no entity base columns).
- * Prefer a `store_*` table name; `read_` is reserved for managed projections (#1220).
+ * Prefer a `store_*` table name; `read_` is reserved for managed projections.
  *
  * Escape hatch, not a shortcut: no audit trail, no automatic tenant_id index,
  * no softDelete — the app author owns tenant-scoping and retention for this

package/dist/db/entity-table-meta.js

@@ -173,7 +173,7 @@ function fieldToColumnMeta(name, field, entity) {
             return [{ name: snake, pgType: "jsonb", notNull: true, defaultSql: "'{}'::jsonb" }];
         case "date":
             // Real PG `date` — Temporal.PlainDate, no time-of-day/timezone
-            // component. See plainDate() in dialect.ts (kumiko-framework#1924).
+            // component. See plainDate() in dialect.ts.
             return [{ name: snake, pgType: "date", notNull: field.required === true }];
         case "timestamp":
             return [{ name: snake, pgType: "timestamptz", notNull: field.required === true }];
@@ -210,30 +210,48 @@ export function resolveTableName(entityName, entity, featureName) {
 export function deriveEntityTableMeta(entityName, entity, options) {
     const tableName = resolveTableName(entityName, entity, options?.featureName);
     const source = options?.source ?? "managed";
-    if (source === "unmanaged") {
-        assertUnmanagedTableName(tableName, "deriveEntityTableMeta");
-    }
     const idType = entity.idType ?? "uuid";
-    if (source === "unmanaged" && idType === "serial") {
-        // Unmanaged direct-write stores bypass validateRecordOwnedSubjects (it only walks
-        // feature.entities), yet encryptForDirectWrite still keys recordOwned and
-        // whenAbsent: "self" fields as `record:<entity>:<id>`; forgetSubject requires a UUID,
-        // so the value could never be shredded.
-        const recordOwnedField = Object.entries(entity.fields).find(([, field]) => isRecordKeyedField(field));
-        if (recordOwnedField) {
-            throw new Error(`deriveEntityTableMeta("${entityName}", { source: "unmanaged" }): field "${recordOwnedField[0]}" is recordOwned (or whenAbsent: "self") but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field could never be shredded. Use idType: "uuid", or give the field a different personal stance.`);
-        }
+    if (source === "unmanaged")
+        assertUnmanagedRules(entityName, entity, tableName, idType);
+    const layout = collectEntityColumns(entity, idType);
+    const indexes = [
+        { name: `${tableName}_tenant_id_idx`, columns: ["tenant_id"] },
+        ...foreignKeyIndexes(tableName, entity, options?.relations, layout.fieldNameToSnake),
+        ...blindIndexIndexes(tableName, layout.bidxSnakeByFieldSnake),
+        ...declaredIndexes(tableName, entity, layout),
+    ];
+    const piiSubjectFields = collectPiiEncryptedFields(entity);
+    const meta = {
+        tableName,
+        columns: layout.columns,
+        indexes,
+        source,
+        ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
+        ...(entity.tenancy === "global" && { tenancy: "global" }),
+    };
+    return source === "unmanaged" ? brandWritable(meta) : meta;
+}
+function assertUnmanagedRules(entityName, entity, tableName, idType) {
+    assertUnmanagedTableName(tableName, "deriveEntityTableMeta");
+    if (idType === "serial")
+        assertRecordSubjectsShreddable(entityName, entity);
+}
+// Unmanaged direct-write stores bypass validateRecordOwnedSubjects (it only walks
+// feature.entities), yet encryptForDirectWrite still keys recordOwned and
+// whenAbsent: "self" fields as `record:<entity>:<id>`; forgetSubject requires a UUID,
+// so the value could never be shredded.
+function assertRecordSubjectsShreddable(entityName, entity) {
+    const recordOwnedField = Object.entries(entity.fields).find(([, field]) => isRecordKeyedField(field));
+    if (recordOwnedField) {
+        throw new Error(`deriveEntityTableMeta("${entityName}", { source: "unmanaged" }): field "${recordOwnedField[0]}" is recordOwned (or whenAbsent: "self") but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field could never be shredded. Use idType: "uuid", or give the field a different personal stance.`);
     }
-    // Base columns first, then user-fields. User-fields with the same
-    // pg-name as a base-column OVERRIDE the base-column (last-wins, same
-    // behavior as drizzle's `{ ...base, ...fields }` spread in the table
-    // builder). Use case: user-session has `tenantId` as a field to enforce
-    // access control, fileRef has `insertedAt` as a field for sortable/
-    // filterable marking. The DB column stays the same, only the application
-    // metadata on the field side changes.
-    const baseCols = fullBaseColumns(idType, entity.softDelete === true);
+}
+// A field column with a base column's pg name overrides it in place (last wins,
+// like `{ ...base, ...fields }`): user-session declares `tenantId` for access
+// control, fileRef `insertedAt` for sort/filter flags; the DB column is unchanged.
+function collectEntityColumns(entity, idType) {
     const colByName = new Map();
-    for (const c of baseCols)
+    for (const c of fullBaseColumns(idType, entity.softDelete === true))
         colByName.set(c.name, c);
     const fieldNameToSnake = new Map();
     const bidxSnakeByFieldSnake = new Map();
@@ -242,8 +260,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
         for (const c of fieldCols)
             colByName.set(c.name, c);
         // Multi-column fields map to their primary column when its name IS the
-        // field's snake (text+bidx, money+currency) — matches the toSnakeCase
-        // fallback below, so explicit indexes keep resolving.
+        // field's snake (text+bidx, money+currency), so explicit indexes keep resolving.
         const primary = fieldCols[0];
         if (primary && primary.name === toSnakeCase(name))
             fieldNameToSnake.set(name, primary.name);
@@ -251,101 +268,77 @@ export function deriveEntityTableMeta(entityName, entity, options) {
         if (primary && bidxCol)
             bidxSnakeByFieldSnake.set(primary.name, bidxCol.name);
     }
-    // Preserve base-col order, then any new user-col-names in fields-order.
-    const columns = [];
-    const seen = new Set();
-    for (const c of baseCols) {
-        const final = colByName.get(c.name);
-        if (final && !seen.has(final.name)) {
-            columns.push(final);
-            seen.add(final.name);
-        }
-    }
-    for (const c of colByName.values()) {
-        if (!seen.has(c.name)) {
-            columns.push(c);
-            seen.add(c.name);
-        }
-    }
-    const indexes = [{ name: `${tableName}_tenant_id_idx`, columns: ["tenant_id"] }];
-    // FK-Indexes: file/image-Felder + belongsTo-Relations
+    // Map insertion order keeps base columns first (overrides stay in place), then new field columns.
+    return { columns: [...colByName.values()], fieldNameToSnake, bidxSnakeByFieldSnake };
+}
+function foreignKeyIndexes(tableName, entity, relations, fieldNameToSnake) {
     const fkSnakeNames = new Set();
     for (const [name, field] of Object.entries(entity.fields)) {
         if (field.type === "file" || field.type === "image")
             fkSnakeNames.add(toSnakeCase(name));
     }
-    if (options?.relations) {
-        for (const rel of Object.values(options.relations)) {
-            if (rel.type === "belongsTo") {
-                const snake = fieldNameToSnake.get(rel.foreignKey) ?? toSnakeCase(rel.foreignKey);
-                fkSnakeNames.add(snake);
-            }
-        }
-    }
-    for (const snake of fkSnakeNames) {
-        indexes.push({ name: `${tableName}_${snake}_idx`, columns: [snake] });
-    }
-    // lookupable fields: index on the bidx column — the query compiler's
-    // OR rewrite hits it on every equality lookup.
-    for (const bidxSnake of bidxSnakeByFieldSnake.values()) {
-        indexes.push({ name: `${tableName}_${bidxSnake}_idx`, columns: [bidxSnake] });
-    }
-    // Explicitly declared indexes (EntityIndexDef). `def.where` is a
-    // SqlExpression (`sql\`…\`` from @cosmicdrift/kumiko-framework/db) —
-    // renderable via `.text`. Unknown where-shapes stay needsManualWhere.
-    for (const def of entity.indexes ?? []) {
-        const cols = def.columns.map((fieldName) => fieldNameToSnake.get(fieldName) ?? toSnakeCase(fieldName));
-        const suffix = def.unique === true ? "unique" : "idx";
-        const indexName = def.name ?? `${tableName}_${cols.join("_")}_${suffix}`;
-        const explicitWhereSql = sqlExpressionText(def.where);
-        // Soft-deleted rows keep their value, so a full unique index would
-        // permanently block reuse; kept in lock-step with table-builder.ts (framework#2593).
-        const whereSql = explicitWhereSql ??
-            (def.where === undefined && def.unique === true && entity.softDelete === true
-                ? SOFT_DELETE_LIVE_ROW_PREDICATE
-                : undefined);
-        indexes.push({
-            name: indexName,
-            columns: cols,
-            ...(def.unique === true && { unique: true }),
-            ...(whereSql !== undefined && { whereSql }),
-            ...(def.where !== undefined && explicitWhereSql === undefined && { needsManualWhere: true }),
-        });
-        // Unique index over lookupable columns: partial bidx counterpart, so
-        // uniqueness also holds for encrypted rows. The original stays
-        // for plaintext legacy rows; partial (IS NOT NULL) because bidx is
-        // NULL for erased/key-less rows.
-        if (def.unique === true && def.where === undefined) {
-            const bidxCols = cols.map((c) => bidxSnakeByFieldSnake.get(c) ?? c);
-            if (bidxCols.some((c, i) => c !== cols[i])) {
-                const notNullParts = bidxCols
-                    .filter((c, i) => c !== cols[i])
-                    .map((c) => `"${c}" IS NOT NULL`);
-                // Soft-deleted rows keep their bidx hash — without this, a restored
-                // row can't reuse a value a soft-deleted sibling still holds
-                // (framework#2464). Kept in lock-step with table-builder.ts.
-                const whereParts = entity.softDelete === true
-                    ? [...notNullParts, SOFT_DELETE_LIVE_ROW_PREDICATE]
-                    : notNullParts;
-                indexes.push({
-                    name: `${indexName}_bidx`,
-                    columns: bidxCols,
-                    unique: true,
-                    whereSql: whereParts.join(" AND "),
-                });
-            }
+    for (const rel of Object.values(relations ?? {})) {
+        if (rel.type === "belongsTo") {
+            fkSnakeNames.add(fieldNameToSnake.get(rel.foreignKey) ?? toSnakeCase(rel.foreignKey));
         }
     }
-    const piiSubjectFields = collectPiiEncryptedFields(entity);
-    const meta = {
-        tableName,
-        columns,
-        indexes,
-        source,
-        ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
-        ...(entity.tenancy === "global" && { tenancy: "global" }),
+    return [...fkSnakeNames].map((snake) => ({
+        name: `${tableName}_${snake}_idx`,
+        columns: [snake],
+    }));
+}
+// The query compiler's OR rewrite hits the bidx column on every equality lookup.
+function blindIndexIndexes(tableName, bidxSnakeByFieldSnake) {
+    return [...bidxSnakeByFieldSnake.values()].map((bidxSnake) => ({
+        name: `${tableName}_${bidxSnake}_idx`,
+        columns: [bidxSnake],
+    }));
+}
+function declaredIndexes(tableName, entity, layout) {
+    return (entity.indexes ?? []).flatMap((def) => declaredIndexWithBidxCounterpart(tableName, entity, def, layout));
+}
+// `def.where` is a SqlExpression renderable via `.text`; unknown where-shapes
+// stay needsManualWhere.
+function declaredIndexWithBidxCounterpart(tableName, entity, def, layout) {
+    const cols = def.columns.map((fieldName) => layout.fieldNameToSnake.get(fieldName) ?? toSnakeCase(fieldName));
+    const suffix = def.unique === true ? "unique" : "idx";
+    const indexName = def.name ?? `${tableName}_${cols.join("_")}_${suffix}`;
+    const explicitWhereSql = sqlExpressionText(def.where);
+    // Soft-deleted rows keep their value, so a full unique index would
+    // permanently block reuse; kept in lock-step with table-builder.ts.
+    const whereSql = explicitWhereSql ??
+        (def.where === undefined && def.unique === true && entity.softDelete === true
+            ? SOFT_DELETE_LIVE_ROW_PREDICATE
+            : undefined);
+    const declared = {
+        name: indexName,
+        columns: cols,
+        ...(def.unique === true && { unique: true }),
+        ...(whereSql !== undefined && { whereSql }),
+        ...(def.where !== undefined && explicitWhereSql === undefined && { needsManualWhere: true }),
+    };
+    if (def.unique !== true || def.where !== undefined)
+        return [declared];
+    const counterpart = bidxUniqueCounterpart(indexName, cols, entity.softDelete === true, layout.bidxSnakeByFieldSnake);
+    return counterpart ? [declared, counterpart] : [declared];
+}
+// Unique index over lookupable columns gets a partial bidx counterpart so
+// uniqueness also holds for encrypted rows; IS NOT NULL because bidx is NULL
+// for erased/key-less rows.
+function bidxUniqueCounterpart(indexName, cols, softDelete, bidxSnakeByFieldSnake) {
+    const bidxCols = cols.map((c) => bidxSnakeByFieldSnake.get(c) ?? c);
+    const notNullParts = bidxCols.filter((c, i) => c !== cols[i]).map((c) => `"${c}" IS NOT NULL`);
+    if (notNullParts.length === 0)
+        return undefined;
+    // Soft-deleted rows keep their bidx hash, so without the live-row predicate a
+    // restored row could not reuse a value a soft-deleted sibling still holds.
+    const whereParts = softDelete ? [...notNullParts, SOFT_DELETE_LIVE_ROW_PREDICATE] : notNullParts;
+    return {
+        name: `${indexName}_bidx`,
+        columns: bidxCols,
+        unique: true,
+        whereSql: whereParts.join(" AND "),
     };
-    return source === "unmanaged" ? brandWritable(meta) : meta;
 }
 function sqlExpressionText(where) {
     return isSqlExpression(where) ? where.text : undefined;
@@ -384,7 +377,7 @@ function columnsByNameMeta(meta) {
 }
 /**
  * Hand-built EntityTableMeta for direct-write stores (no entity base columns).
- * Prefer a `store_*` table name; `read_` is reserved for managed projections (#1220).
+ * Prefer a `store_*` table name; `read_` is reserved for managed projections.
  *
  * Escape hatch, not a shortcut: no audit trail, no automatic tenant_id index,
  * no softDelete — the app author owns tenant-scoping and retention for this

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

@@ -1,3 +1,4 @@
+import type { ErasedSubjectHandling } from "../crypto/pii-field-encryption.ts";
 import type { WhereObject } from "../db/query.ts";
 import type { EntityDefinition, EntityId, SessionUser, TenantId } from "../engine/types/index.ts";
 import { type WriteFailure } from "../errors/index.ts";
@@ -7,7 +8,7 @@ import type { SearchAdapter } from "../search/types.ts";
 import type { TableColumns } from "./dialect.ts";
 import type { EventStoreExecutorOptions } from "./event-store-executor.ts";
 import type { TenantDb } from "./tenant-db.ts";
-export type Table = TableColumns<any>;
+export type Table = TableColumns;
 export declare function buildFilterWhere(field: string, op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in", value: unknown): WhereObject | null;
 export declare function ownershipSubject(user: SessionUser, streamTenantId: TenantId | undefined): SessionUser;
 export declare function isForeignTenantOnGlobalEntity(entity: EntityDefinition, tenantIdValue: unknown): boolean;
@@ -62,7 +63,7 @@ export type ExecutorContext = {
         subjectSource?: Record<string, unknown>;
         keyTenantId?: TenantId | undefined;
         ownerFallback?: Record<string, unknown>;
-        onErasedSubject?: "sentinel";
+        onErasedSubject?: ErasedSubjectHandling;
     }) => 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

@@ -13,10 +13,10 @@ import { constraintOf, isUniqueViolation } from "./pg-error.js";
 import { toSnakeCase } from "./table-builder.js";
 import { columnHandleName, schemaTableName } from "./table-introspection.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
-// Screen-Filter (Tier 2.7c) — Op-Mapping als Where-Operator. Boot-
-// Validator pinst field-Existenz + filterable + op-vs-Type-Compat.
-// `op` ist auf {eq,ne,lt,gt,lte,gte,in} normalisiert; "in" mit
-// empty-array ist explizit no-match.
+// Screen filter: maps an operator to a WhereObject condition.
+// The boot validator checks field existence, filterability, and operator/type compatibility.
+// `op` is normalized to {eq,ne,lt,gt,lte,gte,in}; "in" with an
+// empty array explicitly matches nothing.
 export function buildFilterWhere(field, op, value) {
     switch (op) {
         case "eq":
@@ -70,11 +70,11 @@ function scalarDefault(field) {
             return undefined;
     }
 }
-// F8 helper: PG-23505 (unique-violation) catched aus applyEntityEvent
-// (create + update Pfade) → WriteFailure(UniqueViolationError 409).
-// Andere Errors propagieren via re-throw. Lokal extrahiert weil das
-// Pattern an zwei Stellen im executor lebt — der Caller wrap't den
-// applyEntityEvent-call in try-catch und delegiert das Mapping hierher.
+// Maps PG-23505 (unique-violation) caught from applyEntityEvent
+// (create and update paths) to WriteFailure(UniqueViolationError 409).
+// Other errors propagate via re-throw. Extracted because this pattern
+// occurs in two places in the executor; the caller wraps the
+// applyEntityEvent call in try-catch and delegates the mapping here.
 //
 // Returns WriteFailure on match, null otherwise (caller re-throws).
 export function tryMapUniqueViolation(e, entityName) {
@@ -161,8 +161,8 @@ export function buildExecutorContext(table, entity, options) {
     }
     // Pre-compute the set of sensitive field names once. The event log stores
     // these fields as table ciphertext (boot validates sensitive ⇒ pii |
-    // encrypted, #967) — the set only strips the caller-facing event echo so
-    // responses never carry the value (#820).
+    // encrypted) — the set only strips the caller-facing event echo so
+    // responses never carry the value.
     const sensitiveFields = new Set();
     for (const [name, field] of Object.entries(entity.fields)) {
         if ("sensitive" in field && field.sensitive === true) {
@@ -184,8 +184,8 @@ export function buildExecutorContext(table, entity, options) {
         return resolveEntityFieldEncryption();
     }
     // No adapter configured = crypto-shredding off; pii fields stay plaintext
-    // (pre-#724 behavior). The hard boot gate ships with the prod-grade
-    // PgKmsAdapter (phase E).
+    // (previous behavior). The hard boot gate ships with the prod-grade
+    // PgKmsAdapter.
     function piiKms() {
         return options.kms ?? configuredPiiSubjectKms();
     }

package/dist/db/event-store-executor-read-aggregate.d.ts

@@ -0,0 +1,8 @@
+import type { ListAggregatePayload, ListAggregateResult } from "@cosmicdrift/kumiko-types/list-aggregate-types";
+import type { SessionUser } from "../engine/types/index.ts";
+import type { ExecutorContext } from "./event-store-executor-context.ts";
+import { type ListRuntimeOptions, type ListWherePayload } from "./event-store-executor-read-where.ts";
+import type { TenantDb } from "./tenant-db.ts";
+export declare function aggregateList(ctx: ExecutorContext, payload: ListWherePayload & {
+    readonly aggregate: ListAggregatePayload;
+}, user: SessionUser, db: TenantDb, runtimeOptions: ListRuntimeOptions | undefined): Promise<ListAggregateResult>;

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

@@ -0,0 +1,112 @@
+import { ValidationError } from "../errors/index.js";
+import { aggregateKeyOf, decodeListAggregateValue, emptyListAggregateValue, groupedKeyOrderLimitSql, isListAggregateGroupable, isListAggregateMeasureSupported, listAggregateKeySql, listAggregateMeasureSql, } from "./aggregate-sql.js";
+import { holdsCiphertextOrSecret } from "./entity-field-encryption.js";
+import { appendShiftedClause, bindShiftedClause, } from "./event-store-executor-read-filter.js";
+import { buildListWhere, createFieldReadClause, } from "./event-store-executor-read-where.js";
+import { executeRawQueryRead } from "./queries/raw-sql.js";
+import { schemaTableName } from "./table-introspection.js";
+import { tenantDbRunner } from "./tenant-db-runner.js";
+// One group more than the cap is fetched to tell "exactly 200" from "more".
+const MAX_AGGREGATE_GROUPS = 200;
+function rejectAggregate(path, field, hint) {
+    throw new ValidationError({
+        fields: [
+            {
+                path,
+                code: "field_not_aggregatable",
+                i18nKey: "errors.validation.invalid_value",
+                params: { field, hint },
+            },
+        ],
+    });
+}
+// Unknown and unreadable fields share one silent outcome so the response cannot
+// confirm that a field exists; only then are the sensitive-field and type gates applied.
+function gateField(ctx, fieldReadClause, field, path) {
+    const def = ctx.entity.fields[field];
+    if (def === undefined ||
+        !Object.hasOwn(ctx.entity.fields, field) ||
+        !Object.hasOwn(ctx.table, field))
+        return { kind: "silent" };
+    const clause = fieldReadClause(field);
+    if (clause.kind === "empty")
+        return { kind: "silent" };
+    if (holdsCiphertextOrSecret(ctx.entity, field)) {
+        rejectAggregate(path, field, "Encrypted, personal and secret fields cannot be aggregated.");
+    }
+    return { kind: "ok", def, clause };
+}
+function planAggregate(ctx, fieldReadClause, aggregate) {
+    const groupBy = aggregate.groupBy === undefined
+        ? undefined
+        : {
+            field: aggregate.groupBy,
+            gate: gateField(ctx, fieldReadClause, aggregate.groupBy, "aggregate.groupBy"),
+        };
+    if (groupBy?.gate.kind === "ok") {
+        const { def } = groupBy.gate;
+        const multiple = def.type === "reference" && def.multiple === true;
+        if (!isListAggregateGroupable(def.type, multiple)) {
+            rejectAggregate("aggregate.groupBy", groupBy.field, "This field type cannot be grouped by.");
+        }
+    }
+    const measures = aggregate.measures.map((m, i) => {
+        const path = `aggregate.measures.${i}`;
+        const gate = gateField(ctx, fieldReadClause, m.field, path);
+        if (gate.kind === "ok" && !isListAggregateMeasureSupported(m.kind, gate.def.type)) {
+            rejectAggregate(path, m.field, `"${m.kind}" is not supported on a ${gate.def.type} field.`);
+        }
+        return { kind: m.kind, field: m.field, gate };
+    });
+    return { groupBy, measures };
+}
+function emptyMeasureValues(plan) {
+    return plan.measures.map((m) => m.gate.kind === "silent" ? null : emptyListAggregateValue(m.kind));
+}
+function renderSelectList(plan, where) {
+    const parts = [];
+    if (plan.groupBy?.gate.kind === "ok") {
+        const { def, clause } = plan.groupBy.gate;
+        parts.push(listAggregateKeySql(def.type, where.colSql(plan.groupBy.field), "k0"));
+        // WHERE, not CASE: rows the viewer may not read must not collapse into the real NULL group.
+        if (clause.kind === "sql")
+            appendShiftedClause(where, clause);
+    }
+    parts.push("COUNT(*)::float8 AS c");
+    for (const [i, m] of plan.measures.entries()) {
+        if (m.gate.kind === "silent")
+            continue; // skip: an unreadable measure stays out of the SELECT and decodes to null
+        const filterSql = m.gate.clause.kind === "sql" ? bindShiftedClause(where.params, m.gate.clause) : undefined;
+        parts.push(`${listAggregateMeasureSql(m.kind, m.gate.def.type, where.colSql(m.field), filterSql)} AS m${i}`);
+    }
+    return parts.join(", ");
+}
+export async function aggregateList(ctx, payload, user, db, runtimeOptions) {
+    const plan = planAggregate(ctx, createFieldReadClause(ctx, user), payload.aggregate);
+    const grouped = plan.groupBy !== undefined;
+    if (plan.groupBy?.gate.kind === "silent")
+        return { groups: [] };
+    const built = await buildListWhere(ctx, payload, user, db, runtimeOptions);
+    if (built.kind === "empty") {
+        return {
+            groups: grouped ? [] : [{ key: null, count: 0, measures: emptyMeasureValues(plan) }],
+        };
+    }
+    const { where, searchTruncated } = built;
+    const selectList = renderSelectList(plan, where);
+    const whereText = where.whereSql.length > 0 ? ` WHERE ${where.whereSql.join(" AND ")}` : "";
+    const groupText = grouped ? groupedKeyOrderLimitSql(MAX_AGGREGATE_GROUPS + 1) : "";
+    const tableName = String(schemaTableName(ctx.table));
+    const rows = await executeRawQueryRead(tenantDbRunner(db), `SELECT ${selectList} FROM "${tableName}"${whereText}${groupText}`, where.params);
+    const truncated = rows.length > MAX_AGGREGATE_GROUPS;
+    const groups = rows.slice(0, MAX_AGGREGATE_GROUPS).map((row) => ({
+        key: grouped ? aggregateKeyOf(row["k0"]) : null,
+        count: Number(row["c"]),
+        measures: plan.measures.map((m, i) => m.gate.kind === "silent" ? null : decodeListAggregateValue(row[`m${i}`])),
+    }));
+    return {
+        groups,
+        ...(truncated && { truncated: true }),
+        ...(searchTruncated && { searchTruncated: true }),
+    };
+}

package/dist/db/event-store-executor-read-filter.d.ts

@@ -0,0 +1,31 @@
+import { type OwnershipClause } from "../engine/ownership.ts";
+import type { EntityDefinition } from "../engine/types/index.ts";
+import { type Table } from "./event-store-executor-context.ts";
+export type ListWhere = {
+    readonly whereSql: string[];
+    readonly params: unknown[];
+    readonly colSql: (field: string) => string;
+};
+export declare function bindShiftedClause(params: unknown[], clause: {
+    readonly sqlText: string;
+    readonly params: readonly unknown[];
+}): string;
+export declare function appendShiftedClause(where: ListWhere, clause: {
+    readonly sqlText: string;
+    readonly params: readonly unknown[];
+}): void;
+export declare function bindPlaceholders(params: unknown[], values: readonly unknown[]): string;
+export type ListFilter = {
+    readonly field: string;
+    readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+    readonly value: unknown;
+};
+export declare function deriveParentNarrowTypes(entity: EntityDefinition, payload: {
+    readonly filter?: ListFilter;
+    readonly filters?: readonly ListFilter[];
+}): ReadonlySet<string> | undefined;
+export declare function collectListFilters(payload: {
+    readonly filter?: ListFilter | undefined;
+    readonly filters?: readonly ListFilter[] | undefined;
+}): readonly ListFilter[];
+export declare function applyListFilter(where: ListWhere, f: ListFilter, table: Table, entity: EntityDefinition, fieldReadClause: (field: string) => OwnershipClause): void;