@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/db/dialect.d.ts

@@ -85,6 +85,7 @@ export type SqlExpression = {
     readonly params: readonly unknown[];
     readonly [SQL_EXPR_BRAND]: true;
 };
+export declare function isSqlExpression(value: unknown): value is SqlExpression;
 export declare function sql(strings: TemplateStringsArray, ...values: readonly unknown[]): SqlExpression;
 export declare namespace sql {
     var raw: (text: string) => SqlExpression;

package/dist/db/dialect.js

@@ -18,6 +18,7 @@
 // crashed on timestamptz writes without it (#1480).
 import { KUMIKO_COLUMNS_SYMBOL, KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { schemaTableName } from "./table-introspection.js";
 function isNumericPgType(t) {
     return t.startsWith("numeric(");
 }
@@ -76,9 +77,8 @@ function buildColumn(sqlName, pgType, opts) {
             return value ? "true" : "false";
         if (typeof value === "bigint")
             return value.toString();
-        if (value && typeof value === "object" && SQL_EXPR_BRAND in value) {
+        if (isSqlExpression(value))
             return value.text;
-        }
         if (typeof value === "function")
             return null; // function-defaults stay JS-side
         // Object/array → jsonb literal
@@ -256,6 +256,13 @@ export function primaryKey(opts) {
 // `{ kind: "sql-expr" }` from a client-controlled schema definition is never
 // spliced into SQL text anywhere.
 export const SQL_EXPR_BRAND = Symbol("sql-expr");
+export function isSqlExpression(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        SQL_EXPR_BRAND in value &&
+        "text" in value &&
+        typeof value.text === "string");
+}
 export function sql(strings, ...values) {
     const parts = [];
     const params = [];
@@ -263,7 +270,7 @@ export function sql(strings, ...values) {
         parts.push(strings[i] ?? "");
         if (i < values.length) {
             const v = values[i];
-            if (v && typeof v === "object" && SQL_EXPR_BRAND in v) {
+            if (isSqlExpression(v)) {
                 parts.push(v.text);
             }
             else {
@@ -279,6 +286,15 @@ sql.raw = (text) => ({
     params: [],
     [SQL_EXPR_BRAND]: true,
 });
+function isIndexOrPkList(opts) {
+    return Array.isArray(opts);
+}
+function isPrimaryKeyDescriptor(value) {
+    return "__pk" in value && value.__pk === true;
+}
+function isIndexBuilderWithCols(value) {
+    return "__index" in value && value.__index === true;
+}
 export function table(tableName, cols, optsFn) {
     // Finalise columns + build the column-handle map.
     const handles = {};
@@ -316,25 +332,24 @@ export function table(tableName, cols, optsFn) {
     if (optsFn) {
         const tHandle = handles;
         const opts = optsFn(tHandle);
-        const entries = Array.isArray(opts)
+        const entries = isIndexOrPkList(opts)
             ? opts.map((v, i) => [String(i), v])
             : Object.entries(opts);
         for (const [key, value] of entries) {
             if (!value)
                 continue;
-            if ("__pk" in value && value.__pk === true) {
+            if (isPrimaryKeyDescriptor(value)) {
                 compositePrimaryKey = {
                     name: value.name ?? `${tableName}_pk`,
                     columns: value.columns,
                 };
             }
-            else if ("__index" in value && value.__index === true) {
-                const idx = value;
+            else if (isIndexBuilderWithCols(value)) {
                 indexes.push({
-                    name: idx.name,
-                    columns: idx.columns,
-                    ...(idx.unique && { unique: true }),
-                    ...(idx.whereSql !== undefined && { whereSql: idx.whereSql }),
+                    name: value.name,
+                    columns: value.columns,
+                    ...(value.unique && { unique: true }),
+                    ...(value.whereSql !== undefined && { whereSql: value.whereSql }),
                 });
             }
             else {
@@ -367,8 +382,8 @@ export function extractTableName(table, context = "extractTableName") {
     if (typeof table !== "object" || table === null) {
         throw new Error(`${context}: table is not an object`);
     }
-    const name = table[KUMIKO_NAME_SYMBOL];
-    if (typeof name !== "string") {
+    const name = schemaTableName(table);
+    if (name === undefined) {
         throw new Error(`${context}: table missing kumiko:schema:Name symbol`);
     }
     return name;

package/dist/db/eagerload.js

@@ -18,7 +18,7 @@
 // Custom handlers must pass the viewer explicitly so the parentRef gate is
 // never skipped silently.
 import { requestContext } from "../api/request-context.js";
-import { collectPiiEncryptedFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
+import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
 import { selectMany } from "../db/query.js";
 import { filterReadFields } from "../engine/field-access.js";
 import { buildOwnershipClause, combineClauses, shiftParams, tableNameOf, } from "../engine/ownership.js";
@@ -162,7 +162,7 @@ export async function enrichWithReferences(rows, entity, resolveEntity, db, view
         const rawRefRows = scope.kind === "restricted"
             ? lookedUpRows.filter((r) => scope.readableIds.has(String(r["id"])))
             : lookedUpRows;
-        const piiFields = collectPiiEncryptedFields(refEntity);
+        const piiFields = collectPiiSubjectFields(refEntity);
         const encryptedFields = collectEncryptedFieldNames(refEntity);
         const kms = configuredPiiSubjectKms();
         const map = await buildRefLookupMap(rawRefRows, refEntity, rf.refEntityName, viewer, piiFields, encryptedFields, kms);

package/dist/db/entity-table-from-registry.js

@@ -17,7 +17,7 @@ export function entityTableFromRegistry(registry, entityName, entity) {
             continue;
         if (projection.source !== entityName)
             continue;
-        // @cast-boundary registry-projection — ProjectionDefinition.table is the
+        // @cast-boundary projection-table — ProjectionDefinition.table is the
         // untyped table object every projection registrar accepts.
         return projection.table;
     }

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

@@ -16,7 +16,7 @@
 //      hand-built path; app author owns tenant scoping / versioning. Prefer a
 //      `store_` table name — `read_` is reserved for managed projections (#1208/#1220).
 import { collectPiiEncryptedFields } from "../crypto/index.js";
-import { SQL_EXPR_BRAND } from "./dialect.js";
+import { isSqlExpression } from "./dialect.js";
 import { READ_MODEL_PREFIX, SOFT_DELETE_LIVE_ROW_PREDICATE, toSnakeCase, toTableName, } from "./table-builder.js";
 // Standard base columns for event-sourced read-model tables. Mirrors
 // `buildBaseColumns()` from table-builder.ts (drizzle variant).
@@ -226,9 +226,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
         // Unmanaged direct-write stores bypass validateRecordOwnedSubjects (it only walks
         // feature.entities), yet encryptForDirectWrite still keys recordOwned fields as
         // `record:<entity>:<id>`; forgetSubject requires a UUID, so the value could never be shredded.
-        const recordOwnedField = Object.entries(entity.fields).find(
-        // @cast-boundary schema-walk — PII flags live on the resolved field annotation
-        ([, field]) => field.recordOwned === true);
+        const recordOwnedField = Object.entries(entity.fields).find(([, field]) => "recordOwned" in field && field.recordOwned === true);
         if (recordOwnedField) {
             throw new Error(`deriveEntityTableMeta("${entityName}", { source: "unmanaged" }): field "${recordOwnedField[0]}" is recordOwned 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.`);
         }
@@ -302,7 +300,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
     // 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 ?? [])) {
+    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}`;
@@ -358,13 +356,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
 /** @deprecated Use {@link deriveEntityTableMeta} — the old name read as an unmanaged escape hatch (#1208). */
 export const buildEntityTableMeta = deriveEntityTableMeta;
 function sqlExpressionText(where) {
-    if (typeof where === "object" &&
-        where !== null &&
-        SQL_EXPR_BRAND in where &&
-        typeof where.text === "string") {
-        return where.text;
-    }
-    return undefined;
+    return isSqlExpression(where) ? where.text : undefined;
 }
 // Validates that a backing Drizzle table (declared via `r.entity(name, def,
 // { table })`) is a SUPERSET of the field-derived meta: every column the
@@ -423,7 +415,7 @@ export function defineUnmanagedTable(input) {
         }),
         source: "unmanaged",
         ...(input.tenancy === "global" && { tenancy: "global" }),
-        // @cast-boundary type-brand — TenancyBrand<T> is a phantom marker with no runtime representation.
+        // @cast-boundary phantom-brand — TenancyBrand<T> is a phantom marker with no runtime representation.
     };
 }
 function assertUnmanagedTableName(tableName, via) {

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

@@ -33,15 +33,14 @@ export type ExecutorContext = {
         readonly includeDeleted?: boolean;
     }) => Promise<Record<string, unknown> | null>;
     readonly assertStreamWritable: (db: TenantDb, id: EntityId, tenantId: TenantId) => Promise<void>;
-    readonly loadWithOwnership: (db: TenantDb, idWhere: WhereObject, ownership: {
-        kind: "pass";
-    } | {
-        kind: "empty";
-    } | {
+    readonly probeOwnershipWithStreamVersion: (db: TenantDb, idWhere: WhereObject, ownership: {
         kind: "sql";
         sqlText: string;
         params: readonly unknown[];
-    }) => Promise<Record<string, unknown>[]>;
+    }, streamTenantId: TenantId, aggregateId: string) => Promise<{
+        readonly owned: boolean;
+        readonly streamVersion: number;
+    }>;
     readonly loadDetailSnapshot: (db: TenantDb, idWhere: WhereObject, ownership: {
         kind: "pass";
     } | {

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

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

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

@@ -1,4 +1,4 @@
-import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { escapeLikePattern } from "../crypto/ciphertext-pattern.js";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/index.js";
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
@@ -6,7 +6,7 @@ import { coerceRow, extractTableInfo } from "../db/query.js";
 import { buildOwnershipClause, combineClauses, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { UnprocessableError } from "../errors/index.js";
-import { getStreamVersion, getStreamVersions } from "../event-store/index.js";
+import { getStreamVersion } from "../event-store/index.js";
 import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta.js";
 import { rehydrateCompoundTypes } from "./compound-types.js";
 import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
@@ -14,6 +14,7 @@ import { hasSearchablePlaintext, isSensitiveLabelField } from "./entity-field-en
 import { buildFilterWhere, } from "./event-store-executor-context.js";
 import { buildParentRefClause } from "./parent-ref-clause.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
+import { schemaTableName } from "./table-introspection.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
 // The two read verbs (list/detail) of the event-store-executor. Split out
 // of event-store-executor.ts (#1005, Welle 2) — behavior-preserving
@@ -57,7 +58,7 @@ function toCursorSortText(value) {
     if (value instanceof Date)
         return value.toISOString();
     if (typeof value === "object") {
-        const tag = value[Symbol.toStringTag];
+        const tag = Reflect.get(value, Symbol.toStringTag);
         if (typeof tag === "string" && tag.startsWith("Temporal."))
             return String(value);
         return JSON.stringify(value);
@@ -154,9 +155,8 @@ function applyScreenFilter(table, colSql, whereSql, params, f) {
             });
             whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
         }
-        else if (typeof value === "object") {
-            const valueObj = value;
-            if (valueObj["ne"] === null && Object.keys(valueObj).length === 1) {
+        else if (isPlainObject(value)) {
+            if (value["ne"] === null && Object.keys(value).length === 1) {
                 whereSql.push(`${colSql(field)} IS NOT NULL`);
                 continue;
             }
@@ -362,7 +362,7 @@ async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db
         return undefined;
     }
     const targetTable = referenceTargetTable(descriptor.targetEntityName, targetEntity);
-    const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
+    const targetTableName = String(schemaTableName(targetTable));
     if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
         return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db);
     }
@@ -387,6 +387,7 @@ function referenceTargetTable(name, entity) {
 // Projected alongside the row when a reference sort is active, so the keyset
 // cursor carries the label that was ordered by instead of the FK's UUID.
 const SORT_LABEL_ALIAS = "__kumiko_sort_label";
+const STREAM_VERSION_ALIAS = "__streamVersion";
 // fw#2741 — resolve a `sortable: true` reference field's label inline for
 // ORDER BY. A correlated scalar subquery, not a join: the result set keeps one
 // row per entity row, the read model stays untouched, and the lookup rides the
@@ -419,7 +420,7 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
     const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
     if (ownership.kind === "empty")
         return undefined;
-    const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
+    const targetTableName = String(schemaTableName(targetTable));
     const labelCol = physicalColumnName(targetTable, descriptor.labelField);
     const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
     const tenantCol = tenantScoped ? physicalColumnName(targetTable, "tenantId") : "";
@@ -448,7 +449,7 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
     };
 }
 export function createReadVerbs(ctx) {
-    const { table, entity, entityName, entityCache, searchAdapter, softDelete, streamTenantFor, idFilter, loadWithOwnership, loadDetailSnapshot, decryptForRead, encryptForStorage, } = ctx;
+    const { table, entity, entityName, entityCache, searchAdapter, softDelete, streamTenantFor, idFilter, probeOwnershipWithStreamVersion, loadDetailSnapshot, decryptForRead, encryptForStorage, } = ctx;
     return {
         // list + detail are unchanged from crud-executor — projections are the
         // read-model and serve these queries directly.
@@ -456,7 +457,7 @@ export function createReadVerbs(ctx) {
             const runner = tenantDbRunner(db);
             const { limit, offset } = resolveListPagination(payload);
             const totalCount = payload.totalCount === true;
-            const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+            const tableName = String(schemaTableName(table));
             // H.2 — entity-level read ownership, AND-ed with the parent-ref
             // read-gate (join-row entities derive their visibility from a host
             // row's own read path — see db/parent-ref-clause.ts). Decide before
@@ -644,15 +645,28 @@ export function createReadVerbs(ctx) {
             const whereClauseSqlText = whereSql.length > 0 ? ` WHERE ${whereSql.join(" AND ")}` : "";
             // Project the resolved label too, so the keyset cursor below carries the
             // value that was ordered by rather than the FK column's UUID.
-            const selectList = referenceSortExpr !== undefined && sortSql !== undefined
-                ? `*, ${sortSql} AS "${SORT_LABEL_ALIAS}"`
-                : "*";
+            const sortLabelProjection = referenceSortExpr !== undefined && sortSql !== undefined
+                ? `, ${sortSql} AS "${SORT_LABEL_ALIAS}"`
+                : "";
+            // Stream version in the same statement as the rows: a separate read could pair a
+            // post-write version with a pre-write row, and update({version}) would then pass
+            // the optimistic lock against a state the client never saw (see loadDetailSnapshot).
+            params.push(streamTenantFor(user));
+            const streamVersionProjection = `, (SELECT MAX("version") FROM "kumiko_events" ` +
+                `WHERE "aggregate_id" = "${tableName}"."id" AND "tenant_id" = $${params.length}) ` +
+                `AS "${STREAM_VERSION_ALIAS}"`;
+            const selectList = `*${sortLabelProjection}${streamVersionProjection}`;
             const listSql = `SELECT ${selectList} FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
             const rawRows = await executeRawQueryRead(runner, listSql, params);
             const lastSortLabel = rawRows[rawRows.length - 1]?.[SORT_LABEL_ALIAS];
+            // Aliases are query artifacts, not columns of this entity — strip them before
+            // coercion so they never reach the caller or the entity cache.
+            const streamVersions = rawRows.map((r) => {
+                const v = r[STREAM_VERSION_ALIAS];
+                delete r[STREAM_VERSION_ALIAS];
+                return typeof v === "number" ? v : 0;
+            });
             if (referenceSortExpr !== undefined) {
-                // The alias is a sort artifact, not a column of this entity — strip it
-                // before coercion so it never reaches the caller or the entity cache.
                 for (const row of rawRows)
                     delete row[SORT_LABEL_ALIAS];
             }
@@ -668,10 +682,7 @@ export function createReadVerbs(ctx) {
             // Stream version is authoritative (see detail()): ctx.appendEvent bumps the
             // stream without touching row.version, so the raw row version would hand
             // clients a stale optimistic-lock base. Rows without events keep theirs.
-            const streamVersions = decryptedRows.length > 0
-                ? await getStreamVersions(runner, decryptedRows.map((r) => String(r["id"])), streamTenantFor(user))
-                : new Map();
-            const rows = decryptedRows.map((r) => withStreamVersion(r, streamVersions.get(String(r["id"])) ?? 0));
+            const rows = decryptedRows.map((r, i) => withStreamVersion(r, streamVersions[i] ?? 0));
             // Cache the still-encrypted raw rows (read-row version): same at-rest guarantee as
             // detail()'s encryptForStorage round-trip, without a re-encrypt; detail() rejects
             // a cached version that differs from the stream.
@@ -709,7 +720,7 @@ export function createReadVerbs(ctx) {
             };
         },
         async detail(payload, user, db, options) {
-            const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+            const tableName = String(schemaTableName(table));
             // H.2 — ownership check, AND-ed with the parent-ref read-gate (see
             // db/parent-ref-clause.ts). `empty` → the user can never see this row
             // regardless of its id. Return null (same shape as "not found", so a
@@ -730,16 +741,20 @@ export function createReadVerbs(ctx) {
             if (entityCache && entityName) {
                 const cached = await entityCache.get(user.tenantId, entityName, payload.id);
                 if (cached) {
+                    let streamVersion;
                     if (ownership.kind === "sql") {
                         // Re-check ownership predicate (incl. the parent-ref gate) against
                         // the live row — the cache is keyed only by tenant + id, not by
-                        // role, so a cache hit can't bypass either gate. Deliberate price:
-                        // one extra roundtrip per cache hit once either gate produces SQL.
-                        const checkRows = await loadWithOwnership(db, idWhere, ownership);
-                        if (checkRows.length === 0)
+                        // role, so a cache hit can't bypass either gate. The probe carries
+                        // the stream version in the same statement.
+                        const probe = await probeOwnershipWithStreamVersion(db, idWhere, ownership, streamTenantFor(user), String(payload.id));
+                        if (!probe.owned)
                             return null;
+                        streamVersion = probe.streamVersion;
+                    }
+                    else {
+                        streamVersion = await getStreamVersion(tenantDbRunner(db), String(payload.id), streamTenantFor(user));
                     }
-                    const streamVersion = await getStreamVersion(tenantDbRunner(db), String(payload.id), streamTenantFor(user));
                     if (!(streamVersion > 0 && cached["version"] !== streamVersion)) {
                         // Cached rows are stored re-encrypted (see the `set` below) so an
                         // `encrypted` field's plaintext never sits in a second at-rest

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

@@ -3,7 +3,6 @@ import { instructionFieldNames } from "../engine/instruction-fields.js";
 import { userCanCreateFieldRow, userCanWriteFieldRow } from "../engine/ownership.js";
 import { buildInsertSchema, buildUpdateSchema } from "../engine/schema-builder.js";
 import { findUnavailableSelectOptions, isRecordLocked, } from "../engine/screen-helpers.js";
-import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { AccessDeniedError, VersionConflictError as FrameworkVersionConflict, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RecordLockedError, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { append, IdempotentAppendConflictError as EventStoreIdempotentAppendConflict, VersionConflictError as EventStoreVersionConflict, getStreamVersion, } from "../event-store/index.js";
 import { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "../pipeline/irreversible-operation-gate.js";
@@ -12,10 +11,11 @@ import { generateId } from "../utils/index.js";
 import { applyEntityEvent } from "./apply-entity-event.js";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
 import { buildEventMetadata, entityEventName, isForeignTenantOnGlobalEntity, ownershipSubject, tryMapUniqueViolation, } from "./event-store-executor-context.js";
+import { isFrameworkSystemUser, isLockGuardBypassed } from "./lock-guard.js";
 import { projectionRegistryOf } from "./projection-registry-binding.js";
 import { runInSavepointIfSupported } from "./query.js";
 import { assertPersonalDataWrite, tableNameOf } from "./tenant-db.js";
-import { tenantDbRunner } from "./tenant-db-runner.js";
+import { tenantDbWriteRunner } from "./tenant-db-runner.js";
 // Custom projections for a write that did not go through the dispatcher (hook or
 // job writing a second aggregate). Savepoint like applyEntityEvent: a throwing
 // projection fails the write and the caller's transaction rolls it back.
@@ -29,12 +29,6 @@ async function projectEntityEvent(db, runner, event) {
         return;
     await runInSavepointIfSupported(runner, (sp) => runProjectionsForEvent(event, registry, sp));
 }
-// Art. 17 erasure runs as the framework operator, not as a row owner; a
-// per-role ownership map can never cover it, and a silent deny means the
-// erasure never happened.
-function isFrameworkSystemUser(user) {
-    return user.id === SYSTEM_USER_ID && user.roles.includes(SYSTEM_ROLE);
-}
 // The five write verbs (create/update/delete/forget/restore) of the event-
 // store-executor. Split out of event-store-executor.ts (#1005, Welle 2) —
 // behavior-preserving relocation, not a redesign: every closure below is
@@ -126,9 +120,7 @@ export function createWriteVerbs(ctx) {
     // statutory deletion must reach locked rows, and forget (Art. 17) never checks the lock
     // at all. The options are server-code only; no request field is ever copied into them.
     function recordLockedFailure(row, id, user, options) {
-        if (options?.unsafeSkipLockGuard === true ||
-            (options?.writePurpose !== undefined && isFrameworkSystemUser(user)) ||
-            !isRecordLocked(entity.lockedWhen, row)) {
+        if (isLockGuardBypassed(user, options) || !isRecordLocked(entity.lockedWhen, row)) {
             return undefined;
         }
         return writeFailure(new RecordLockedError({ entityName, entityId: id }));
@@ -180,7 +172,7 @@ export function createWriteVerbs(ctx) {
             const streamTenantMismatch = streamTenantCreateFailure(db, payload, streamTenantId);
             if (streamTenantMismatch)
                 return streamTenantMismatch;
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor create");
             // Respect an explicit id in the payload (seed pattern, SCIM import). Without
             // one the framework mints a fresh UUIDv7 via generateId. Strip it out of the
             // event payload so defaults + downstream consumers don't see a redundant id field.
@@ -349,7 +341,7 @@ export function createWriteVerbs(ctx) {
             };
         },
         async update(payload, user, db, updateOptions) {
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor update");
             if (isForeignTenantOnGlobalEntity(entity, payload.changes["tenantId"])) {
                 throw new AccessDeniedError({
                     message: `${entityName}.update: entity is tenancy: "global" — payload.changes.tenantId must ` +
@@ -582,7 +574,7 @@ export function createWriteVerbs(ctx) {
             if (isIrreversibleEntityVerb("delete", entity)) {
                 assertIrreversibleOperationAllowed(`${entityName}.delete (entity has no softDelete)`);
             }
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor delete");
             const existing = await loadById(payload.id, db);
             if (!existing)
                 return writeFailure(new NotFoundError(entityName, payload.id));
@@ -664,6 +656,7 @@ export function createWriteVerbs(ctx) {
                     data: existing,
                     entityName,
                     event: echoEvent,
+                    ...(isLockGuardBypassed(user, options) && { lockGuardBypassed: true }),
                 },
             };
         },
@@ -673,7 +666,7 @@ export function createWriteVerbs(ctx) {
         // without the isDeleted filter so trashed (soft-deleted) rows are erased too.
         async forget(payload, user, db, options) {
             assertIrreversibleOperationAllowed(`${entityName}.forget`);
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor forget");
             const raw = await db.fetchOne(table, { id: payload.id });
             if (!raw)
                 return writeFailure(new NotFoundError(entityName, payload.id));
@@ -744,6 +737,7 @@ export function createWriteVerbs(ctx) {
                     data: existing,
                     entityName,
                     event: echoEvent,
+                    lockGuardBypassed: true,
                 },
             };
         },
@@ -753,7 +747,7 @@ export function createWriteVerbs(ctx) {
                     i18nKey: "errors.softDeleteNotEnabled",
                 }));
             }
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor restore");
             const streamTenantId = options?.streamTenantId;
             const target = await loadSoftDeletedRow(db, payload.id, streamTenantId);
             if ("failure" in target)
@@ -780,8 +774,13 @@ export function createWriteVerbs(ctx) {
             // Restore carries the soft-deleted snapshot as `previous` — mirror of
             // delete for symmetry. Projections that decremented on delete use
             // `previous` to re-increment on restore without re-querying the entity
-            // table. `data` is the raw stored row — pii/encrypted fields are
-            // already ciphertext, no re-encrypt needed.
+            // table. Rows predating the subject-KMS rollout may still hold plaintext
+            // pii, and envelope encryption is not idempotent: decrypt, then
+            // re-encrypt as delete does.
+            const previousPlain = await decryptForRead(data);
+            const previousForStorage = await encryptForStorage(previousPlain, user, {
+                keyTenantId: streamTenantId,
+            });
             let event;
             try {
                 event = await runInSavepointIfSupported(runner, (sp) => append(sp, {
@@ -791,7 +790,7 @@ export function createWriteVerbs(ctx) {
                     expectedVersion: currentVersion,
                     type: entityEventName(entityName, "restored"),
                     eventVersion,
-                    payload: { previous: data },
+                    payload: { previous: previousForStorage },
                     metadata: buildEventMetadata(user),
                 }));
             }
@@ -835,7 +834,6 @@ export function createWriteVerbs(ctx) {
             // same as every other executor method — `data`/`restored` are raw rows
             // (db.fetchOne / applyEntityEvent), never decrypted before this point.
             const restoredHydrated = await decryptForRead(rehydrateCompoundTypes(restored, entity));
-            const previousPlain = await decryptForRead(data);
             const echoEvent = { ...event, payload: { previous: stripSensitive(previousPlain) } };
             await projectEntityEvent(db, runner, echoEvent);
             return {

package/dist/db/index.d.ts

@@ -35,4 +35,4 @@ export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFramework
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
 export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db.js";
-export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, } from "./tenant-db.js";
+export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";