@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/db/event-store-executor-context.ts

@@ -0,0 +1,404 @@
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { requestContext } from "../api/request-context";
+import {
+  collectPiiSubjectFields,
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+  encryptPiiFieldValues,
+  type KmsContext,
+  type LocalKeyKmsAdapter,
+} from "../crypto";
+import { executeRawQuery } from "../db/queries/raw-sql";
+import type { WhereObject } from "../db/query";
+import { shiftParams } from "../engine/ownership";
+import type {
+  EntityDefinition,
+  EntityId,
+  FieldDefinition,
+  SessionUser,
+  TenantId,
+} from "../engine/types";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
+import { UniqueViolationError, type WriteFailure, writeFailure } from "../errors";
+import { ArchivedStreamError, type EventMetadata, isStreamArchived } from "../event-store";
+import type { EntityCache } from "../pipeline/entity-cache";
+import type { SearchAdapter } from "../search/types";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher";
+import { assertUnreachable } from "../utils";
+import { rehydrateCompoundTypes } from "./compound-types";
+import type { DbRow } from "./connection";
+import type { TableColumns } from "./dialect";
+import {
+  collectEncryptedFieldNames,
+  decryptEntityFieldValues,
+  encryptEntityFieldValues,
+  resolveEntityFieldEncryption,
+} from "./entity-field-encryption";
+import type { EventStoreExecutorOptions } from "./event-store-executor";
+import { constraintOf, isUniqueViolation } from "./pg-error";
+import { toSnakeCase } from "./table-builder";
+import type { TenantDb } from "./tenant-db";
+
+// Shared context-building for the event-store-executor CRUD verbs (create/
+// update/delete/forget/restore/list/detail — see event-store-executor-write.ts
+// and event-store-executor-read.ts). Precomputes entity-derived state once
+// per createEventStoreExecutor() call and bundles the crypto/ownership
+// helpers the verbs need, so the verb modules don't each re-derive them.
+
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic tables
+export type Table = TableColumns<any>;
+
+// 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,in} normalisiert; "in" mit empty-array ist
+// explizit no-match.
+export function buildFilterWhere(
+  field: string,
+  op: "eq" | "ne" | "lt" | "gt" | "in",
+  value: unknown,
+): WhereObject | null {
+  switch (op) {
+    case "eq":
+      return { [field]: value };
+    case "ne":
+      return { [field]: { ne: value } };
+    case "lt":
+      return { [field]: { lt: value } };
+    case "gt":
+      return { [field]: { gt: value } };
+    case "in":
+      if (Array.isArray(value) && value.length > 0) {
+        return { [field]: value };
+      }
+      return null; // no-match short-circuit
+    default:
+      return assertUnreachable(op, "filter op");
+  }
+}
+
+// Returns the scalar default of a field, or undefined if the field's type
+// doesn't carry a default or no default was declared. Only scalar types
+// (text/number/boolean/select) support creation-time defaults — money/date/
+// file/embedded fields don't.
+function scalarDefault(field: FieldDefinition): unknown {
+  switch (field.type) {
+    case "text":
+    case "longText":
+    case "number":
+    case "boolean":
+    case "select":
+      return field.default;
+    default:
+      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.
+//
+// Returns WriteFailure on match, null otherwise (caller re-throws).
+export function tryMapUniqueViolation(e: unknown, entityName: string): WriteFailure | null {
+  if (!isUniqueViolation(e)) return null;
+  const constraintName = constraintOf(e);
+  return writeFailure(
+    new UniqueViolationError(
+      {
+        entityName,
+        ...(constraintName !== undefined && { constraintName }),
+      },
+      { cause: e instanceof Error ? e : undefined },
+    ),
+  );
+}
+
+// Build the metadata envelope for an append. userId always set; requestId +
+// correlation + causation come from the AsyncLocalStorage request-context
+// when present (e.g. HTTP request, MSP-apply, job run). requestId is a pure
+// trace marker — HTTP-level retry idempotency runs separately via
+// pipeline/idempotency.ts (Redis-cached response replay), so a single
+// request can write N events freely without the events-table needing a
+// uniqueness constraint.
+export function buildEventMetadata(user: SessionUser): EventMetadata {
+  const reqCtx = requestContext.get();
+  return {
+    userId: String(user.id),
+    ...(reqCtx?.requestId ? { requestId: reqCtx.requestId } : {}),
+    ...(reqCtx?.correlationId ? { correlationId: reqCtx.correlationId } : {}),
+    ...(reqCtx?.causationId ? { causationId: reqCtx.causationId } : {}),
+  };
+}
+
+// Lifecycle verbs the event-store-executor auto-emits. MSPs that react
+// to entity creates/updates/etc should reference this helper instead of
+// hardcoding the string — a future rename in the executor then surfaces
+// as a type error at every call site rather than a silent miss.
+export type EntityLifecycleVerb = "created" | "updated" | "deleted" | "restored" | "forgotten";
+
+export function entityEventName(entityName: string, verb: EntityLifecycleVerb): string {
+  return `${entityName}.${verb}`;
+}
+
+export type ExecutorContext = {
+  readonly table: Table;
+  readonly entity: EntityDefinition;
+  readonly entityName: string;
+  readonly entityCache?: EntityCache;
+  readonly searchAdapter?: SearchAdapter;
+  readonly softDelete: boolean;
+  readonly streamTenantFor: (user: SessionUser) => TenantId;
+  readonly idFilter: (id: EntityId) => WhereObject;
+  readonly loadById: (id: EntityId, db: TenantDb) => 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" }
+      | { kind: "sql"; sqlText: string; params: readonly unknown[] },
+  ) => Promise<Record<string, unknown>[]>;
+  readonly encryptForStorage: (
+    row: Record<string, unknown>,
+    user: SessionUser,
+    opts?: { onlyKeys?: Iterable<string>; subjectSource?: Record<string, unknown> },
+  ) => Promise<Record<string, unknown>>;
+  readonly decryptForRead: (row: Record<string, unknown>) => Promise<Record<string, unknown>>;
+  readonly applyDefaults: (payload: Record<string, unknown>) => Record<string, unknown>;
+  readonly stripSensitive: (
+    payload: Record<string, unknown> | undefined,
+  ) => Record<string, unknown>;
+};
+
+export function buildExecutorContext(
+  table: Table,
+  entity: EntityDefinition,
+  options: EventStoreExecutorOptions,
+): ExecutorContext {
+  const { searchAdapter, entityName, entityCache } = options;
+  const softDelete = entity.softDelete ?? false;
+
+  // Stream-tenant choke-point. A systemStream entity (tenant-independent, e.g.
+  // user) lives on SYSTEM_TENANT_ID deterministically — every op addresses it
+  // there. Everything else stays on the caller's tenant (byte-identical to the
+  // old hardcoded user.tenantId). Single source of truth for the stream key.
+  const streamTenantFor = (user: SessionUser): TenantId =>
+    entity.systemStream ? SYSTEM_TENANT_ID : user.tenantId;
+
+  // idType default (undefined) is now "uuid" — the ES-pivot made UUID the
+  // only valid aggregate-id type. Explicit `idType: "serial"` is the only
+  // shape that's incompatible with the event-store and still rejected.
+  if (entity.idType !== undefined && entity.idType !== "uuid") {
+    throw new Error(
+      `event-store-executor requires entity "${entityName}" to declare idType: "uuid" — ` +
+        `got idType: "${entity.idType}". ` +
+        `The events-table keys aggregates by uuid(aggregate_id); non-UUID PKs would ` +
+        `require a schema split the framework does not currently support. ` +
+        `Fix: remove the \`idType\`-override from createEntity({...}) for "${entityName}" ` +
+        `(the default is "uuid"). The framework auto-assigns UUIDs on create — ` +
+        `you do not need to generate them yourself. ` +
+        `See docs/plans/architecture/event-sourcing-pivot.md (section "UUID-only aggregate IDs") for the full rationale.`,
+    );
+  }
+
+  // Pre-compute defaults once so create() doesn't loop the entity every call.
+  const fieldDefaults: Record<string, unknown> = {};
+  for (const [name, field] of Object.entries(entity.fields)) {
+    const def = scalarDefault(field);
+    if (def !== undefined) fieldDefaults[name] = def;
+  }
+
+  // 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).
+  const sensitiveFields = new Set<string>();
+  for (const [name, field] of Object.entries(entity.fields)) {
+    if ("sensitive" in field && field.sensitive === true) {
+      sensitiveFields.add(name);
+    }
+  }
+
+  const encryptedFields = collectEncryptedFieldNames(entity);
+  const hasEncryptedFields = encryptedFields.size > 0;
+
+  const piiSubjectFields = collectPiiSubjectFields(entity);
+  const hasPiiFields = piiSubjectFields.length > 0;
+
+  function fieldCipher(): EnvelopeCipher {
+    if (options.encryption) return options.encryption;
+    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).
+  function piiKms(): LocalKeyKmsAdapter | undefined {
+    return options.kms ?? configuredPiiSubjectKms();
+  }
+
+  function kmsContextFor(user?: SessionUser): KmsContext {
+    return {
+      requestId: requestContext.get()?.requestId ?? "event-store-executor",
+      ...(user && { tenantId: user.tenantId, userId: String(user.id) }),
+    };
+  }
+
+  // Async on purpose: the envelope cipher wraps/unwraps DEKs via the
+  // MasterKeyProvider. Callers MUST await — a missed await here writes
+  // "[object Promise]" into the projection, which the Promise return
+  // types turn into a compile error at every call site.
+  async function encryptForStorage(
+    row: Record<string, unknown>,
+    user: SessionUser,
+    opts?: { onlyKeys?: Iterable<string>; subjectSource?: Record<string, unknown> },
+  ): Promise<Record<string, unknown>> {
+    let out = row;
+    if (hasEncryptedFields) {
+      out = await encryptEntityFieldValues(out, encryptedFields, fieldCipher(), {
+        ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
+      });
+    }
+    const kms = piiKms();
+    if (hasPiiFields && kms) {
+      out = await encryptPiiFieldValues(out, entity, piiSubjectFields, kms, kmsContextFor(user), {
+        tenantId: user.tenantId,
+        ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
+        ...(opts?.subjectSource !== undefined && { subjectSource: opts.subjectSource }),
+      });
+    }
+    return out;
+  }
+
+  // Mirror of encryptForStorage IN REVERSE — a field that carries both
+  // `encrypted: true` and a subject marker (userOwned/tenantOwned/pii) is
+  // written as PII(envelope(plaintext)) (envelope wraps first, PII wraps
+  // that as its outer layer). Decrypt must peel the OUTER layer first: PII
+  // unwrap before envelope decrypt, or the envelope cipher chokes on a
+  // still-PII-wrapped string (auth-mfa.totpSecret/recoveryCodes combine both
+  // markers; see pii-subject-encryption.integration.test.ts).
+  async function decryptForRead(row: Record<string, unknown>): Promise<Record<string, unknown>> {
+    let out = row;
+    const kms = piiKms();
+    if (hasPiiFields && kms) {
+      out = await decryptPiiFieldValues(out, piiSubjectFields, kms, kmsContextFor());
+    }
+    if (hasEncryptedFields) {
+      out = await decryptEntityFieldValues(out, encryptedFields, fieldCipher());
+    }
+    return out;
+  }
+
+  function applyDefaults(payload: Record<string, unknown>): Record<string, unknown> {
+    if (Object.keys(fieldDefaults).length === 0) return payload;
+    const result: Record<string, unknown> = { ...payload };
+    for (const [name, def] of Object.entries(fieldDefaults)) {
+      if (result[name] === undefined) result[name] = def;
+    }
+    return result;
+  }
+
+  function stripSensitive(payload: Record<string, unknown> | undefined): Record<string, unknown> {
+    if (!payload) return {};
+    if (sensitiveFields.size === 0) return payload;
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(payload)) {
+      if (sensitiveFields.has(key)) continue;
+      result[key] = value;
+    }
+    return result;
+  }
+
+  function idFilter(id: EntityId): WhereObject {
+    const filter: WhereObject = { id };
+    if (softDelete && table["isDeleted"]) filter["isDeleted"] = false;
+    return filter;
+  }
+
+  async function loadById(id: EntityId, db: TenantDb): Promise<Record<string, unknown> | null> {
+    const row = await db.fetchOne(table, idFilter(id));
+    if (!row) return null;
+    return await decryptForRead(rehydrateCompoundTypes(row as DbRow, entity));
+  }
+
+  // Archive guard for the CRUD write paths. Archived streams are read-only —
+  // ctx.appendEvent (append-event-core) already enforces this, but the
+  // executor appends directly via append() and getStreamVersion() ignores
+  // the archive flag, so without this check a PATCH/DELETE on an archived
+  // entity would silently land an event and break the read-only contract
+  // (loadAggregate returns [] for the same stream). Throws ArchivedStreamError
+  // to mirror the appendEvent path exactly — same 500 + rolled-back tx.
+  // Creates skip this: a fresh UUID can't be archived, and a deterministic-id
+  // re-create onto an archived stream collides on the unique index →
+  // version_conflict, which already blocks the write.
+  async function assertStreamWritable(
+    db: TenantDb,
+    id: EntityId,
+    tenantId: TenantId,
+  ): Promise<void> {
+    if (await isStreamArchived(db.raw, tenantId, String(id))) {
+      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: TenantDb,
+    idWhere: WhereObject,
+    ownership:
+      | { kind: "pass" }
+      | { kind: "empty" }
+      | { kind: "sql"; sqlText: string; params: readonly unknown[] },
+  ): Promise<Record<string, unknown>[]> {
+    if (ownership.kind === "empty") return [];
+    if (ownership.kind === "pass") {
+      const row = await db.fetchOne(table, idWhere);
+      return row ? [row as Record<string, unknown>] : [];
+    }
+    // ownership has raw SQL — splice it into a raw query alongside the
+    // idFilter + tenant-filter that TenantDb would have added.
+    const tableName = String((table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL]);
+    const colSql = (field: string): string =>
+      `"${(table[field] as { name?: string } | undefined)?.name ?? toSnakeCase(field)}"`;
+    const whereParts: string[] = [];
+    const params: unknown[] = [];
+    if (table["tenantId"] !== undefined && db.mode === "tenant") {
+      params.push(db.tenantId, SYSTEM_TENANT_ID);
+      whereParts.push(`${colSql("tenantId")} IN ($${params.length - 1}, $${params.length})`);
+    }
+    for (const [field, value] of Object.entries(idWhere)) {
+      if (typeof value === "boolean") {
+        whereParts.push(`${colSql(field)} = ${value ? "TRUE" : "FALSE"}`);
+      } else {
+        params.push(value);
+        whereParts.push(`${colSql(field)} = $${params.length}`);
+      }
+    }
+    const shifted = shiftParams(ownership, params.length);
+    whereParts.push(shifted.sqlText);
+    for (const p of shifted.params) params.push(p);
+    const sqlText = `SELECT * FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
+    return [...(await executeRawQuery<Record<string, unknown>>(db.raw, sqlText, params))];
+  }
+
+  return {
+    table,
+    entity,
+    entityName,
+    entityCache,
+    searchAdapter,
+    softDelete,
+    streamTenantFor,
+    idFilter,
+    loadById,
+    assertStreamWritable,
+    loadWithOwnership,
+    encryptForStorage,
+    decryptForRead,
+    applyDefaults,
+    stripSensitive,
+  };
+}

package/src/db/event-store-executor-read.ts

@@ -0,0 +1,275 @@
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { computeBlindIndex, configuredBlindIndexKey } from "../crypto";
+import { executeRawQuery } from "../db/queries/raw-sql";
+import { coerceRow, extractTableInfo } from "../db/query";
+import { buildOwnershipClause, shiftParams } from "../engine/ownership";
+import type { EntityId } from "../engine/types";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
+import { getStreamVersion } from "../event-store";
+import { rehydrateCompoundTypes } from "./compound-types";
+import { decodeCursor, encodeCursor } from "./cursor";
+import type { EventStoreExecutor } from "./event-store-executor";
+import { buildFilterWhere, type ExecutorContext } from "./event-store-executor-context";
+import { toSnakeCase } from "./table-builder";
+
+// The two read verbs (list/detail) of the event-store-executor. Split out
+// of event-store-executor.ts (#1005, Welle 2) — behavior-preserving
+// relocation, not a redesign: unchanged from the original, now behind an
+// explicit ExecutorContext instead of the factory's local scope.
+
+export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor, "list" | "detail"> {
+  const {
+    table,
+    entity,
+    entityName,
+    entityCache,
+    searchAdapter,
+    softDelete,
+    streamTenantFor,
+    idFilter,
+    loadWithOwnership,
+    decryptForRead,
+    encryptForStorage,
+  } = ctx;
+
+  return {
+    // list + detail are unchanged from crud-executor — projections are the
+    // read-model and serve these queries directly.
+    async list(payload, user, db, runtimeOptions) {
+      const limit = payload.limit ?? 50;
+      const offset = payload.offset ?? 0;
+      const totalCount = payload.totalCount === true;
+
+      // H.2 — entity-level read ownership. Decide before touching search or
+      // the DB: `empty` means there's no row the user could ever see, so
+      // skip both paths and return an empty page.
+      const ownership = buildOwnershipClause(user, entity.access?.read, table);
+      if (ownership.kind === "empty") {
+        return { rows: [], nextCursor: null, ...(totalCount && { total: 0 }) };
+      }
+
+      let filterIds: EntityId[] | undefined;
+      // Build-Time options.searchAdapter gewinnt; runtime-Override ist
+      // Fallback für die defaultEntityQueryHandler-Pipe (die nutzt den
+      // ctx.searchAdapter erst zur Laufzeit weil createEventStoreExecutor
+      // beim Definition-Time noch keinen Server-Context hat).
+      const effectiveSearchAdapter = searchAdapter ?? runtimeOptions?.searchAdapter;
+      if (payload.search && effectiveSearchAdapter && entityName) {
+        const results = await effectiveSearchAdapter.search(user.tenantId, payload.search, {
+          filterType: entityName,
+        });
+        filterIds = results.map((r) => r.entityId);
+        if (filterIds.length === 0) {
+          return { rows: [], nextCursor: null, ...(totalCount && { total: 0 }) };
+        }
+      }
+
+      // Build the WHERE clause as raw SQL — ownership produces a
+      // parameterised fragment that we splice in alongside simple WhereObject
+      // conditions (cursor, search-filter-IDs, screen-filter, tenant-scope).
+      const tableName = String((table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL]);
+      const whereSql: string[] = [];
+      const params: unknown[] = [];
+      const colSql = (field: string): string =>
+        `"${(table[field] as { name?: string } | undefined)?.name ?? toSnakeCase(field)}"`;
+
+      // Tenant-Filter (replicates TenantDb's readWhere semantics).
+      if (table["tenantId"] !== undefined && db.mode === "tenant") {
+        params.push(db.tenantId, SYSTEM_TENANT_ID);
+        whereSql.push(`${colSql("tenantId")} IN ($${params.length - 1}, $${params.length})`);
+      }
+      if (softDelete && table["isDeleted"] && runtimeOptions?.includeDeleted !== true) {
+        whereSql.push(`${colSql("isDeleted")} = FALSE`);
+      }
+      if (payload.cursor) {
+        params.push(decodeCursor(payload.cursor));
+        whereSql.push(`${colSql("id")} > $${params.length}`);
+      }
+      if (filterIds) {
+        const placeholders = filterIds.map((id) => {
+          params.push(id);
+          return `$${params.length}`;
+        });
+        whereSql.push(`${colSql("id")} IN (${placeholders.join(", ")})`);
+      }
+      if (ownership.kind === "sql") {
+        const shifted = shiftParams(
+          { sqlText: ownership.sqlText, params: ownership.params },
+          params.length,
+        );
+        whereSql.push(shifted.sqlText);
+        for (const p of shifted.params) params.push(p);
+      }
+      const applyFilter = (f: {
+        readonly field: string;
+        readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+        readonly value: unknown;
+      }): void => {
+        if (table[f.field] === undefined) {
+          // skip: unknown field — not a real column, drop the filter (injection guard)
+          return;
+        }
+        const screen = buildFilterWhere(f.field, f.op, f.value);
+        if (screen === null) {
+          whereSql.push("FALSE");
+          // skip: filter is unsatisfiable → emit FALSE, no params to bind
+          return;
+        }
+        for (const [field, value] of Object.entries(screen)) {
+          if (Array.isArray(value)) {
+            const placeholders = value.map((v) => {
+              params.push(v);
+              return `$${params.length}`;
+            });
+            whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
+          } else if (typeof value === "object" && value !== null) {
+            const opMap: Record<string, string> = {
+              gt: ">",
+              gte: ">=",
+              lt: "<",
+              lte: "<=",
+              ne: "<>",
+            };
+            for (const [opKey, opSym] of Object.entries(opMap)) {
+              if (!(opKey in value)) continue;
+              params.push((value as Record<string, unknown>)[opKey]);
+              whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
+            }
+          } else {
+            // Blind-Index-OR-Rewrite (#818), lock-step mit buildWhereClause
+            // in bun-db/query.ts — Equality auf lookupable-Feldern matcht
+            // Klartext-Arm ODER HMAC-Arm.
+            const bidxKey = configuredBlindIndexKey();
+            if (bidxKey !== undefined && typeof value === "string" && table[`${field}Bidx`]) {
+              params.push(value, computeBlindIndex(bidxKey, value));
+              whereSql.push(
+                `(${colSql(field)} = $${params.length - 1} OR ${colSql(`${field}Bidx`)} = $${params.length})`,
+              );
+            } else {
+              params.push(value);
+              whereSql.push(`${colSql(field)} = $${params.length}`);
+            }
+          }
+        }
+      };
+      if (payload.filter !== undefined) applyFilter(payload.filter);
+      if (payload.filters !== undefined) for (const f of payload.filters) applyFilter(f);
+
+      const orderByClause =
+        payload.sort && table[payload.sort]
+          ? ` ORDER BY ${colSql(payload.sort)} ${payload.sortDirection === "desc" ? "DESC" : "ASC"}`
+          : "";
+      const useOffset = !payload.cursor && offset > 0;
+      const offsetClause = useOffset ? ` OFFSET ${offset}` : "";
+
+      const whereClauseSqlText = whereSql.length > 0 ? ` WHERE ${whereSql.join(" AND ")}` : "";
+      const listSql = `SELECT * FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
+
+      const rawRows = await executeRawQuery<Record<string, unknown>>(db.raw, listSql, params);
+      // Read-Side rehydrate pro Row + snake→camel coercion für driver-agnostic Feldnamen.
+      // Coerce BEFORE decrypt: the raw SELECT * rows carry snake_case column
+      // names, while the encrypted/pii field lists are camelCase — decrypting
+      // first silently skipped every multi-word field (ciphertext leaked to
+      // the caller).
+      const tableInfo = extractTableInfo(table);
+      const encryptedRows = rawRows.map((r) =>
+        coerceRow(rehydrateCompoundTypes(r, entity), tableInfo),
+      );
+      const rows = await Promise.all(encryptedRows.map((r) => decryptForRead(r)));
+
+      // list rows carry the READ-ROW version (display-only), never an optimistic-lock
+      // base — edit flows reload via detail(), which reconciles the stream version.
+      // Cache the still-encrypted form: same at-rest guarantee as detail()'s
+      // encryptForStorage round-trip, without paying a re-encrypt.
+      if (entityCache && entityName && rows.length > 0) {
+        await entityCache.mset(
+          user.tenantId,
+          entityName,
+          encryptedRows.map((r) => ({ id: r["id"] as EntityId, data: r })), // @cast-boundary engine-payload
+        );
+      }
+
+      const lastRow = rows[rows.length - 1];
+      const nextCursor =
+        rows.length === limit && lastRow ? encodeCursor(lastRow["id"] as string) : null; // @cast-boundary engine-payload
+
+      // total: extra COUNT(*) — nur wenn explizit angefordert (Pager-UI).
+      // Postgres-Cost ist O(table-scan) ohne Filter, mit Filter so teuer
+      // wie der entsprechende WHERE — bei indexed columns billig genug.
+      // Bei Search-Path ist `total = filterIds.length` ohne extra Query.
+      let total: number | undefined;
+      if (totalCount) {
+        if (filterIds) {
+          total = filterIds.length;
+        } else {
+          const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;
+          const countRows = await executeRawQuery<{ count: number }>(db.raw, countSql, params);
+          total = countRows[0]?.count ?? 0;
+        }
+      }
+
+      return { rows, nextCursor, ...(total !== undefined && { total }) };
+    },
+
+    async detail(payload, user, db) {
+      // H.2 — ownership check. `empty` → the user can never see this row
+      // regardless of its id. Return null (same shape as "not found", so a
+      // probing attacker can't distinguish "no access" from "doesn't exist").
+      const ownership = buildOwnershipClause(user, entity.access?.read, table);
+      if (ownership.kind === "empty") return null;
+
+      const idWhere = idFilter(payload.id);
+
+      // Stream-version authoritative (same policy as update/Block 0):
+      // ctx.appendEvent (lifecycle-writes like incident:post-update) bumps
+      // the stream WITHOUT touching row.version — a detail-read that hands
+      // out the stale row.version dooms the next CRUD update built on it
+      // (entityEdit loads detail.version as its optimistic-lock base) to a
+      // guaranteed version_conflict.
+      const withStreamVersion = async (
+        row: Record<string, unknown>,
+      ): Promise<Record<string, unknown>> => {
+        const streamVersion = await getStreamVersion(
+          db.raw,
+          String(payload.id),
+          streamTenantFor(user),
+        );
+        return streamVersion > 0 ? { ...row, version: streamVersion } : row;
+      };
+
+      if (entityCache && entityName) {
+        const cached = await entityCache.get(user.tenantId, entityName, payload.id);
+        if (cached) {
+          if (ownership.kind === "sql") {
+            // Re-check ownership predicate against the live row — the cache
+            // is keyed only by tenant + id, not by role.
+            const checkRows = await loadWithOwnership(db, idWhere, ownership);
+            if (checkRows.length === 0) return null;
+          }
+          // Cached rows are stored re-encrypted (see the `set` below) so an
+          // `encrypted` field's plaintext never sits in a second at-rest
+          // store (Redis) the field-encryption feature doesn't cover.
+          return withStreamVersion(await decryptForRead(cached));
+        }
+      }
+
+      const rows = await loadWithOwnership(db, idWhere, ownership);
+      const raw = rows[0];
+      if (!raw) return null;
+      const row = await decryptForRead(rehydrateCompoundTypes(raw, entity));
+      const rowInfo = extractTableInfo(table);
+      const coerced = coerceRow(row, rowInfo);
+
+      if (entityCache && entityName) {
+        await entityCache.set(
+          user.tenantId,
+          entityName,
+          payload.id,
+          await encryptForStorage(coerced, user),
+        );
+      }
+
+      return withStreamVersion(coerced);
+    },
+  };
+}