@cosmicdrift/kumiko-framework 0.385.0 → 0.387.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-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 }];
@@ -299,7 +299,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
         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).
+        // 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
@@ -323,7 +323,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
                     .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.
+                // Kept in lock-step with table-builder.ts.
                 const whereParts = entity.softDelete === true
                     ? [...notNullParts, SOFT_DELETE_LIVE_ROW_PREDICATE]
                     : notNullParts;
@@ -384,7 +384,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

@@ -7,7 +7,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;

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.js

@@ -17,9 +17,9 @@ 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
-// relocation, not a redesign: unchanged from the original, now behind an
-// explicit ExecutorContext instead of the factory's local scope.
+// of event-store-executor.ts — behavior-preserving relocation, not a redesign:
+// unchanged from the original, now behind an explicit ExecutorContext instead
+// of the factory's local scope.
 // Defense-in-depth pagination guard. The handler boundary (entityListSchema)
 // already validates limit/offset, but the executor is public API for custom
 // handlers that pass their payload straight through — a non-integer limit
@@ -90,7 +90,7 @@ function keysetBoundarySql(sortCol, idCol, cursor, descending, params) {
 }
 // multiSelect stores its options as a jsonb array — a filter value is one
 // option, not the whole array, so eq/ne/in must check array containment
-// (`@>`) instead of scalar `=`/`<>`/`IN` against the jsonb column (fw#2490).
+// (`@>`) instead of scalar `=`/`<>`/`IN` against the jsonb column.
 // lt/gt/lte/gte have no containment analogue; the boot-validator already
 // blocks them for screen-declared filters (screen-filter-ops.ts
 // EQUALITY_ONLY), but a client-supplied facet filter reaches here
@@ -144,7 +144,7 @@ function applyScreenFilter(table, colSql, whereSql, params, f) {
         return;
     }
     for (const [field, value] of Object.entries(screen)) {
-        // #2015: `x <> NULL` is never true — mirror buildWhereClause's IS [NOT] NULL handling in db/query.ts.
+        // `x <> NULL` is never true — mirror buildWhereClause's IS [NOT] NULL handling in db/query.ts.
         if (value === null) {
             whereSql.push(`${colSql(field)} IS NULL`);
         }
@@ -175,7 +175,7 @@ function applyScreenFilter(table, colSql, whereSql, params, f) {
             }
         }
         else {
-            // Blind-index OR rewrite (#818), lock-step with buildWhereClause
+            // Blind-index OR rewrite, lock-step with buildWhereClause
             // in db/query.ts — equality on lookupable fields matches the
             // plaintext arm OR the HMAC arm.
             const bidxKey = configuredBlindIndexKey();
@@ -225,7 +225,7 @@ function deriveParentNarrowTypes(entity, payload) {
     }
     return narrowed;
 }
-// fw#2660 — above this many target-row matches, drop the reference clause
+// Above this many target-row matches, drop the reference clause
 // entirely instead of truncating: an arbitrary 200-row slice of "which
 // targets match" would silently hide rows a full-cardinality match would
 // have found. Native text search on the entity's own fields still applies.
@@ -237,7 +237,7 @@ const MAX_REFERENCE_SEARCH_IDS = 200;
 // treated as complete (a cap of N+1 could never be observed).
 const MAX_SEARCH_CANDIDATE_IDS = 1000;
 // Registry-declared `searchable` reference fields, plus the implicit
-// tenantId→tenant.name row-meta reference (fw#2660) — both resolve a text
+// tenantId→tenant.name row-meta reference — both resolve a text
 // search term against a target row's label instead of the raw FK column.
 function collectReferenceSearchDescriptors(table, referenceSearch, dbMode) {
     if (!referenceSearch)
@@ -264,9 +264,9 @@ function isSoftDeletedTargetHidden(targetEntity, targetTable) {
     return targetEntity.softDelete === true && targetTable["isDeleted"] !== undefined;
 }
 // Tenant-scoped ILIKE lookup against one reference target — never raw/
-// unscoped SQL, a match in a foreign tenant must never surface a row here
-// (fw#2660's hard constraint). Mirrors the main table's own tenant filter
-// (see the `table["tenantId"]` check further down in list()).
+// unscoped SQL, a match in a foreign tenant must never surface a row here.
+// Mirrors the main table's own tenant filter (see the `table["tenantId"]`
+// check further down in list()).
 async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db) {
     // The label must not leak through match counts: a viewer who cannot read the
     // target row or its label field would otherwise probe names by searching.
@@ -388,14 +388,14 @@ function referenceTargetTable(name, entity) {
 // 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
+// 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
 // target's primary key. Tenant-scoped exactly like the search path — a foreign
 // tenant's label must never influence this tenant's ordering.
 // undefined means "cannot order by this label", which drops the sort to plain
 // id order; falling back to the UUID column would look deliberate to the user
-// while being arbitrary, which the issue calls worse than no sorting.
+// while being arbitrary, which is worse than no sorting.
 function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolveEntity, db, user) {
     const targetEntity = resolveEntity(descriptor.targetEntityName);
     if (targetEntity === undefined) {
@@ -479,20 +479,19 @@ export function createReadVerbs(ctx) {
             const colSql = (field) => `"${physicalCol(field)}"`;
             // Field-level read access gates filtering and sorting the same way it
             // gates the projected row: a caller who cannot read a field must not be
-            // able to probe its values through result counts or ordering (fw#2629).
-            // Hoisted above the search block (fw#2660) — a searchable-reference
-            // clause is the same probe surface as a filter/sort and must be gated
-            // the same way, before the reference-match query even runs.
+            // able to probe its values through result counts or ordering.
+            // Hoisted above the search block — a searchable-reference clause is the
+            // same probe surface as a filter/sort and must be gated the same way,
+            // before the reference-match query even runs.
             const fieldReadClause = (field) => buildOwnershipClause(user, normalizeAccessEntry(entity.fields[field]?.access?.read), table);
-            // 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).
+            // The build-time options.searchAdapter takes precedence; use the runtime override
+            // as a fallback because defaultEntityQueryHandler receives the search adapter only
+            // at runtime, when createEventStoreExecutor has no server context yet.
             const effectiveSearchAdapter = searchAdapter ?? runtimeOptions?.searchAdapter;
             let searchTruncated = false;
             if (payload.search) {
                 const searchTerm = payload.search;
-                // #2032 — a search term with no adapter wired must fail loud, not
+                // A search term with no adapter wired must fail loud, not
                 // silently return the unfiltered list dressed up as a search result.
                 if (!effectiveSearchAdapter) {
                     throw new UnprocessableError("search_adapter_not_wired", {
@@ -504,7 +503,7 @@ export function createReadVerbs(ctx) {
                 }
                 // Same choke-point as writes/index: systemStream docs live under
                 // SYSTEM_TENANT_ID; everything else under the session tenant — db.mode
-                // must not invent a second predicate (kumiko-framework#2412).
+                // must not invent a second predicate.
                 const searchTenantId = streamTenantFor(user);
                 const results = await effectiveSearchAdapter.search(searchTenantId, searchTerm, {
                     filterType: entityName,
@@ -512,14 +511,14 @@ export function createReadVerbs(ctx) {
                 });
                 searchTruncated = results.length >= MAX_SEARCH_CANDIDATE_IDS;
                 filterIds = results.map((r) => r.entityId);
-                // fw#2660 — union in reference-column label matches: a searchable
+                // Union in reference-column label matches: a searchable
                 // reference field (or the implicit tenantId→tenant.name row-meta
                 // reference) whose target row's labelField matches the search term
                 // also counts as a hit on this entity, not just a raw text-field hit.
                 const referenceSearch = runtimeOptions?.referenceSearch;
-                // fw#2629 parity: a caller who cannot read the reference column itself
-                // must not be able to infer its value by matching the target's label —
-                // same probe surface as filtering/sorting on it directly.
+                // A caller who cannot read the reference column itself must not be able
+                // to infer its value by matching the target's label — same probe
+                // surface as filtering/sorting on it directly.
                 const descriptors = collectReferenceSearchDescriptors(table, referenceSearch, db.mode).filter((d) => fieldReadClause(d.ownColumn).kind === "pass");
                 const referenceMatches = referenceSearch
                     ? (await Promise.all(descriptors.map((d) => resolveReferenceMatches(d, searchTerm, referenceSearch.resolveEntity, db, user, effectiveSearchAdapter)))).filter((m) => m !== undefined)
@@ -556,7 +555,7 @@ export function createReadVerbs(ctx) {
                 ? payload.sort
                 : undefined;
             const sortDescending = payload.sortDirection === "desc";
-            // fw#2741 — a reference column stores a UUID, so it is never sorted by
+            // A reference column stores a UUID, so it is never sorted by
             // directly: either the field opted into `sortable` and we order by the
             // target row's label, or the sort is dropped to plain id order.
             let sortField;

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

@@ -36,7 +36,7 @@ async function projectEntityEvent(db, runner, event) {
     await runInSavepointIfSupported(runner, (sp) => runProjectionsForEvent(event, registry, sp));
 }
 // The five write verbs (create/update/delete/forget/restore) of the event-
-// store-executor. Split out of event-store-executor.ts (#1005, Welle 2) —
+// store-executor. Split out of event-store-executor.ts —
 // behavior-preserving relocation, not a redesign: every closure below is
 // unchanged from the original, just relocated behind an explicit
 // ExecutorContext instead of capturing the factory's local scope directly.
@@ -61,10 +61,10 @@ function selectOptionNotAvailableFailure(entries) {
     }));
 }
 // preSave runs before ownership checks: authorization must evaluate the row
-// as it will actually be persisted, including hook-derived fields
-// (kumiko-framework#1672). A throwing hook is an app-author bug (bad
-// business rule, not a framework fault) — map it to a clean writeFailure
-// instead of letting it propagate as an internal_error 500.
+// as it will actually be persisted, including hook-derived fields. A throwing
+// hook is an app-author bug (bad business rule, not a framework fault) — map it
+// to a clean writeFailure instead of letting it propagate as an internal_error
+// 500.
 async function runPreSave(preSave, changes, previous, isNew, entityName, action, outputSchema) {
     if (!preSave)
         return { data: changes };
@@ -72,7 +72,7 @@ async function runPreSave(preSave, changes, previous, isNew, entityName, action,
         const hookResult = await preSave(changes, previous, isNew);
         // A hook that echoes `id`/`version` back (e.g. `{ ...changes, id: x }`)
         // must not leak them into the persisted row — aggregateId already comes
-        // from generateId()/the loaded row, not from hook output (fw#1685).
+        // from generateId()/the loaded row, not from hook output.
         const { id: _hookId, version: _hookVersion, ...safe } = hookResult;
         // Hook output skips the handler's input validation yet goes straight into the projection.
         // Validated only, not replaced by the parse result: hooks may set fields in storage form.
@@ -245,12 +245,11 @@ export function createWriteVerbs(ctx) {
             // per declared field. Role-level was already checked by the
             // dispatcher; here we enforce ownership-rules against the new row.
             //
-            // Which fields get checked is scoped to the pre-hook payload (fw#1685)
+            // Which fields get checked is scoped to the pre-hook payload
             // — a hook-derived field the user never submitted must not be
             // field-ownership-checked against the user. The rule for a checked
             // field is still evaluated against the full post-hook row (`data`) —
-            // an ownership rule can reference a column only a hook populates
-            // (kumiko-framework#1672).
+            // an ownership rule can reference a column only a hook populates.
             const fieldDeniedCreate = checkWriteFieldOwnership(entity, applyDefaults(payloadWithoutId), ownershipSubject(user, streamTenantId), undefined, data);
             if (fieldDeniedCreate) {
                 return writeFailure(new UnprocessableError("ownership_denied", {
@@ -267,39 +266,37 @@ export function createWriteVerbs(ctx) {
             const unavailableOnCreate = selectOptionNotAvailableFailure(findUnavailableSelectOptions(entity.fields, data));
             if (unavailableOnCreate)
                 return unavailableOnCreate;
-            // Alle Compound-Types (locatedTimestamp, money, ...) gehen durch
-            // dieselbe Pipeline. Caller schickt combined API-Form, Framework
-            // speichert flat DB-Form. Siehe db/compound-types.ts.
-            // subjectSource carries the freshly minted aggregateId: the create
-            // payload has no id column, but a pii:true self-subject resolves from it.
+            // All compound types (locatedTimestamp, money, ...) use the same pipeline: the
+            // caller sends the combined API form, the framework stores the flat DB form (see
+            // db/compound-types.ts).
+            // subjectSource carries the freshly minted aggregateId: the create payload has no id
+            // column, but a pii:true self-subject resolves from it.
             const flatCreateData = flattenCompoundTypes(data, entity);
             const flatData = await encryptForStorage(flatCreateData, user, {
                 subjectSource: { ...flatCreateData, id: aggregateId },
                 keyTenantId: streamTenantId,
             });
-            // 1. Append event (same TX as the projection write — both must succeed
-            //    or both roll back; the dispatcher wraps both in one transaction).
-            //    flatData is already table ciphertext for pii/encrypted fields, so
-            //    the immutable log never sees plaintext and replay reproduces the
-            //    row byte-identically (#967).
+            // 1. Append the event in the same transaction as the projection write — both must
+            //    succeed or both roll back; the dispatcher wraps them in one transaction.
+            //    flatData is already table ciphertext for pii/encrypted fields, so the immutable
+            //    log never sees plaintext and replay reproduces the row byte-for-byte.
             //
-            //    `expectedVersion: 0` heißt: stream existiert noch nicht. Bei
-            //    deterministic-aggregate-id-Patterns (z.B. uuidv5(tenantId|naturalKey))
-            //    ist es legitim dass create kollidiert — selbe id, schon vorhandener
-            //    stream → version_conflict statt internal_error. Update hat den
-            //    selben catch (siehe line 493+).
+            //    `expectedVersion: 0` means the stream does not yet exist. With deterministic
+            //    aggregate-ID patterns (for example, uuidv5(tenantId|naturalKey)), a create can
+            //    legitimately collide — the same ID has an existing stream — so return
+            //    version_conflict instead of internal_error. Update uses the same catch.
             let event;
             try {
                 // Savepoint-scoped: postgres.js poisons the WHOLE surrounding
                 // begin() once any statement inside it errors, even if the JS error
-                // is caught (kumiko-framework#1778) — a losing concurrent create's
-                // unique-violation would otherwise abort the caller's outer
-                // transaction and surface as internal_error at commit time instead
-                // of the version_conflict this catch classifies. runInSavepointIfSupported
-                // confines the failed INSERT to a nested scope that rolls back on
-                // its own (same pattern as ctx.tryAppendEvent), and falls back to a
-                // plain call when the runner is a bare pool connection with no active
-                // transaction to poison (seeds/tests calling the executor directly).
+                // is caught — a losing concurrent create's unique-violation
+                // would otherwise abort the caller's outer transaction and surface as
+                // internal_error at commit time instead of the version_conflict this
+                // catch classifies. runInSavepointIfSupported confines the failed
+                // INSERT to a nested scope that rolls back on its own (same pattern as
+                // ctx.tryAppendEvent), and falls back to a plain call when the runner
+                // is a bare pool connection with no active transaction to poison
+                // (seeds/tests calling the executor directly).
                 event = await runInSavepointIfSupported(runner, async (sp) => append(sp, {
                     aggregateId,
                     aggregateType: entityName,
@@ -325,22 +322,20 @@ export function createWriteVerbs(ctx) {
                 }
                 throw e;
             }
-            // 2. Update projection via applyEntityEvent — derselbe Code-Pfad den
-            //    rebuildProjection für Replay nutzt, mit demselben StoredEvent →
-            //    Live==Rebuild by-construction (#967).
+            // 2. Update the projection through applyEntityEvent — the same code path used by
+            //    rebuildProjection for replay, with the same StoredEvent, so live and rebuild
+            //    produce the same result by construction.
             //
-            //    F8-Patch: app-level unique-violations (z.B. (tenantId, email)
-            //    auf User-Entity, (tenantId, slug) auf Article) werfen pg-23505
-            //    aus der projection-INSERT. Ohne den catch propagiert das als
-            //    unhandled exception → 500 internal_error. Map auf
-            //    UniqueViolationError 409 damit Designer/Frontend einen sauberen
-            //    "duplicate" zeigen können statt cryptic "internal server error".
-            // Savepoint like the append above: an unclassified DB error out of the
-            // projection INSERT would otherwise poison the enclosing tx (postgres-js
-            // rejects the whole begin() once any statement in it failed), so a later
-            // write sharing that tx — a sibling write after a failed nested one —
-            // throws raw as a 500 instead of failing cleanly. The savepoint rolls the
-            // failed INSERT back; the error still propagates and stays catchable.
+            //    Application-level unique violations (for example, (tenantId, email) on a User
+            //    entity or (tenantId, slug) on an Article) produce pg-23505 from the projection
+            //    INSERT. Without this catch, the error propagates as an unhandled exception and
+            //    becomes a 500 internal_error. Map it to UniqueViolationError 409 so the
+            //    designer/frontend can show a clear "duplicate" message instead of a cryptic
+            //    "internal server error".
+            // Savepoint like the append above: an unclassified DB error from the projection
+            // INSERT would otherwise poison the enclosing transaction (postgres-js rejects the
+            // whole begin() once any statement in it fails). The savepoint rolls back the failed
+            // INSERT while allowing the error to propagate and remain catchable.
             let result;
             try {
                 result = await runInSavepointIfSupported(withExecutorManagedWrites(runner), async (sp) => applyEntityEvent(event, table, entity, sp));
@@ -355,8 +350,8 @@ export function createWriteVerbs(ctx) {
                 return writeFailure(new InternalError({ message: "projection insert returned no row" }));
             }
             const row = result.row;
-            // Read-Side Auto-Convert: DB-Form → API-combined-Form für alle
-            // Compound-Types in einem Pass.
+            // Read-side conversion: DB form → combined API form for all
+            // compound types in one pass.
             const projection = await decryptForRead(rehydrateCompoundTypes(row, entity));
             if (entityCache && entityName) {
                 await entityCache.del(streamTenantId ?? user.tenantId, entityName, aggregateId);
@@ -376,7 +371,7 @@ export function createWriteVerbs(ctx) {
                     isNew: true,
                     entityName,
                     // Persisted event carries ciphertext by design — the caller-facing
-                    // echo must be plaintext like every other response field (#820).
+                    // echo must be plaintext like every other response field.
                     event: echoEvent,
                 }),
             };
@@ -430,7 +425,7 @@ export function createWriteVerbs(ctx) {
             // touch on this specific row.
             //
             // Which fields get checked is scoped to `payload.changes` (the user's
-            // actual submission), NOT `changes` (post-preSave-hook data, fw#1685)
+            // actual submission), NOT `changes` (post-preSave-hook data)
             // — a hook-derived field the user never submitted (e.g. a system hook
             // setting `assignedTo`) has no business being field-ownership-checked
             // against the *user*, and doing so rejects writes the user is fully
@@ -438,7 +433,7 @@ export function createWriteVerbs(ctx) {
             // already runs on this same pre-hook payload for consistency. The rule
             // for a checked field is still evaluated against the full post-hook
             // row (`changes` merged onto `previous`) — an ownership rule can
-            // reference a column only a hook populates (kumiko-framework#1672).
+            // reference a column only a hook populates.
             const fieldDeniedUpdate = checkWriteFieldOwnership(entity, payload.changes, ownershipSubject(user, streamTenantId), previous, changes);
             if (fieldDeniedUpdate) {
                 return writeFailure(new UnprocessableError("ownership_denied", {
@@ -497,16 +492,17 @@ export function createWriteVerbs(ctx) {
                 }
             }
             try {
-                // Compound-Types Auto-Convert (alle in einem Pass).
+                // Compound-type conversion in one pass.
                 // subjectSource: partial changes may carry a pii field without its
-                // ownerField — the merged row still names the subject.
-                // skipUnchanged (#464) is opt-in: an identical resubmitted key is dropped before
-                // encryption so pii/encrypted fields get no fresh ciphertext for no real change.
-                // Direct callers (KEK rotation, #494 backfill) rely on the default to force a re-encrypt.
+                // ownerField — the merged row still identifies the subject.
+                // skipUnchanged is opt-in: an identical resubmitted key is dropped before
+                // encryption so pii/encrypted fields receive no fresh ciphertext when nothing
+                // actually changed.
+                // Direct callers (KEK rotation, backfill) rely on the default to force re-encryption.
                 const submittedChanges = updateOptions?.skipUnchanged
                     ? Object.fromEntries(Object.entries(changes).filter(([key, value]) => !isUnchangedValue(value, previous[key])))
                     : changes;
-                // fw#3670: crypto-shredding follows the current owner, so personal
+                // Crypto-shredding follows the current owner, so personal
                 // fields not in this update are re-written under the new owner's key.
                 // Owner -> absent is not re-keyed; the value stays under the old owner.
                 const changesToPersist = {
@@ -529,8 +525,8 @@ export function createWriteVerbs(ctx) {
                 // re-encrypt it before it's persisted so plaintext of pii/encrypted
                 // fields doesn't land in the immutable log (flatChanges is already
                 // ciphertext from encryptForStorage above).
-                // Owner chain for the ownerless-then-assigned row: previous owner, then the
-                // owner this event sets, then whenAbsent (fw#3654).
+                // Owner chain for the ownerless-then-assigned row: previous owner, then
+                // the owner this event sets, then whenAbsent.
                 const encryptedPrevious = await encryptForStorage(previous, user, {
                     keyTenantId: streamTenantId,
                     ownerFallback: submittedChanges,
@@ -552,17 +548,16 @@ export function createWriteVerbs(ctx) {
                     },
                     metadata: buildEventMetadata(user),
                 }));
-                // Live==Rebuild via applyEntityEvent mit demselben StoredEvent —
-                // apply liest nur `changes`, und die sind live wie im Replay
-                // identischer Ciphertext (#967).
+                // Live and rebuild use applyEntityEvent with the same StoredEvent —
+                // apply reads only `changes`, which contain identical ciphertext in live writes
+                // and replays.
                 //
-                // F8-Patch: dasselbe unique-violation-handling wie im create-Pfad
-                // — ein update das einen unique-Index verletzt (z.B. email-update
-                // auf einen schon-existierenden Wert) wird mit 409 unique_violation
-                // statt 500 internal_error rückgemeldet.
-                // Savepoint like the create path: a raw DB error out of the projection
-                // UPDATE poisons the enclosing tx otherwise, so a sibling write after a
-                // failed nested one throws 500 instead of failing cleanly.
+                // An update that violates a unique index (for example, an email update to an
+                // already-existing value) is reported as 409 unique_violation instead of 500
+                // internal_error.
+                // Savepoint like the create path: a raw DB error from the projection UPDATE would
+                // otherwise poison the enclosing transaction, so a sibling write after a failed
+                // nested one would throw 500 instead of failing cleanly.
                 let result;
                 try {
                     result = await runInSavepointIfSupported(withExecutorManagedWrites(runner), async (sp) => applyEntityEvent(event, table, entity, sp));