@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/crypto/kms-adapter.js

@@ -1,18 +1,16 @@
 import { RECORD_ENTITY_PATTERN, subjectIdToKey, } from "@cosmicdrift/kumiko-types/kms-adapter-types";
 import * as z from "zod";
 export * from "@cosmicdrift/kumiko-types/kms-adapter-types";
-// The KMS error classes live here and not in kumiko-types (#1629): callers
+// The KMS error classes live here and not in kumiko-types: callers
 // branch on them with `instanceof`, which needs a single copy of the class.
 // `satisfies z.ZodType<SubjectId>` plus the reverse check in subject-id-schema.test.ts bind this to the TS type
-// at compile time (fw#2801) — mint (subjectKeyForRecord) and shred (forget-subject) can no
-// longer drift apart on which subjects are valid, the way #2809 happened.
+// at compile time — mint (subjectKeyForRecord) and shred (forget-subject) can no
+// longer drift apart on which subjects are valid, the way it happened.
 export const subjectIdSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("user"), userId: z.uuid() }),
     z.object({
         kind: z.literal("tenant"),
-        // z.uuid() only proves string shape; TenantId is a nominal brand on top
-        // of that, minted here right after validation (@cast-boundary).
-        tenantId: z.uuid().transform((value) => value),
+        tenantId: z.uuid(),
     }),
     z.object({
         kind: z.literal("record"),

package/dist/crypto/kms-wiring.d.ts

@@ -19,8 +19,7 @@ export type PgKmsRotationEnv = KmsWiringEnv & {
  *  plaintext fallback) so a short-lived process can `finally { await
  *  wiring.close() }` without narrowing first. Skipping it leaves the adapter's
  *  connection pool holding the event loop open and the process never exits —
- *  a long-running server is supposed to hold it, every ops script is not
- *  (fw#2551). */
+ *  a long-running server is supposed to hold it, every ops script is not. */
 export type KmsWiringRelease = {
     readonly close: () => Promise<void>;
 };

package/dist/crypto/kms-wiring.js

@@ -1,5 +1,5 @@
 // Boot-time env validation for the subject-keys KMS, shared by every app that
-// mounts crypto-shredding. Lived copy-pasted in four apps before fw#1617; the
+// mounts crypto-shredding. It lived copy-pasted in four apps; the
 // copies drifted apart in their parsers, which is the failure mode this module
 // exists to end.
 //
@@ -16,7 +16,7 @@ const DEFAULT_PLAINTEXT_REASON = "local dev without subject-keys KMS (fw#818)";
 // the integer kek_version column never hits that slot, silently leaving
 // rotation-window rows unreadable. Same class: "0x10" -> 16, " 2 " trimmed,
 // "-1"/"0" accepted as versions, values past MAX_SAFE_INTEGER rounded.
-// A digits-only regex closes all of these at once (phronexsis#323).
+// A digits-only regex closes all of these at once.
 function parseKekVersion(raw, fieldName) {
     if (!/^[0-9]+$/.test(raw)) {
         throw new Error(`${fieldName} must be a positive integer, got "${raw}".`);

package/dist/crypto/pg-kms-adapter.js

@@ -179,12 +179,8 @@ export async function rewrapSubjectKeys(options) {
     }
     const batchSize = options.batchSize ?? 200;
     const sql = postgres(options.databaseUrl, { max: 2, onnotice: () => { } });
-    const result = {
-        scanned: 0,
-        rewrapped: 0,
-        skippedErased: 0,
-        failures: [],
-    };
+    const failures = [];
+    const result = { scanned: 0, rewrapped: 0, skippedErased: 0, failures };
     try {
         let cursor = "";
         for (;;) {

package/dist/crypto/pii-field-encryption.js

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

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

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

package/dist/crypto/subject-resolver.js

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

package/dist/db/apply-entity-event.d.ts

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

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

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

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

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

package/dist/db/collect-table-metas.js

@@ -1,15 +1,14 @@
 // Canonical table source for both `kumiko schema generate` and setupTestStack
 // (entities, storeTables, projections, multiStreamProjections). One shared
-// source so the test-DB push and migrations cannot drift apart again (#255, #3102).
+// source so the test-DB push and migrations cannot drift apart again.
 import { compareByCodepoint } from "../utils/index.js";
 import { assertBackingTableSuperset, deriveEntityTableMeta, } from "./entity-table-meta.js";
 import { enumerateFeatureTableSources } from "./feature-table-sources.js";
 import { asEntityTableMeta } from "./query.js";
 function canonicalColumnsKey(meta) {
-    // Spalten-Identität unabhängig von Deklarations-Reihenfolge und
-    // Objekt-Key-Order. Indexes bleiben außen vor: eine Projection-Table
-    // (buildEntityTable ohne relations) trägt legitim weniger FK-Indexes
-    // als das Entity-Meta derselben Tabelle.
+    // Column identity independent of declaration order and object-key order.
+    // Indexes are excluded: a projection table (buildEntityTable without relations)
+    // legitimately has fewer FK indexes than the entity metadata for the same table.
     return [...meta.columns]
         .sort((a, b) => compareByCodepoint(a.name, b.name))
         .map((c) => `${c.name}|${c.pgType}|${c.notNull}|${c.defaultSql ?? ""}|${c.primaryKey ?? false}|${c.identity ?? false}|${c.bigintJsMode ?? ""}`)
@@ -27,8 +26,8 @@ function registerPass1Meta(metas, byName, meta, origin) {
 export function collectTableMetas(features) {
     const metas = [];
     const byName = new Map();
-    // Pass 1: kanonische Schema-Quellen, identisch zum bisherigen Template-
-    // Verhalten (gleiche Reihenfolge, gleiche deriveEntityTableMeta-Optionen).
+    // Pass 1: canonical schema sources, matching the previous template behavior
+    // (same order, same deriveEntityTableMeta options).
     for (const feature of features) {
         for (const [name, ent] of Object.entries(feature.entities ?? {})) {
             const fieldMeta = deriveEntityTableMeta(name, ent, { relations: feature.relations[name] });
@@ -52,10 +51,10 @@ export function collectTableMetas(features) {
             registerPass1Meta(metas, byName, entry.meta, `storeTable "${entry.name}" (${feature.name})`);
         }
     }
-    // Pass 2: table-tragende Registrierungen. Zwei Pässe, damit eine Entity-
-    // Tabelle aus Feature B gegen eine gleichnamige Projection-Table aus
-    // Feature A gewinnt — Entity-Metas sind die reichere Quelle (FK-Indexes
-    // aus relations).
+    // Pass 2: table-bearing registrations. Two passes ensure that an entity table
+    // from Feature B takes precedence over a same-named projection table from
+    // Feature A—entity metadata is the richer source because of FK indexes from
+    // relations.
     for (const feature of features) {
         for (const { table, origin } of enumerateFeatureTableSources(feature)) {
             const meta = asEntityTableMeta(table);

package/dist/db/compound-types.d.ts

@@ -4,6 +4,6 @@ import type { EntityDefinition } from "../engine/types/index.ts";
  */
 export declare function flattenCompoundTypes(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
 /**
- * DB-Form (flat) → API-Form (combined). Wird nach jedem Read aufgerufen.
+ * DB form (flat) → API form (combined). Called after every read.
  */
 export declare function rehydrateCompoundTypes(row: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;

package/dist/db/compound-types.js

@@ -1,20 +1,20 @@
-// Compound-Type Pipeline für den Executor.
+// Compound-type pipeline for the executor.
 //
-// Ein Compound-Type ist ein Field das aus EINEM API-Object und MEHREREN
-// DB-Spalten besteht. Beispiele:
+// A compound type is a field represented by ONE API object and MULTIPLE
+// DB columns. Examples:
 //   - locatedTimestamp: { at, tz, utc } ↔ <name>Utc + <name>Tz
 //   - money: { amount, currency } ↔ <name> + <name>Currency
-//   - (kommt) address: { street, zip, city } ↔ <name>Street + <name>Zip + <name>City
+//   - (upcoming) address: { street, zip, city } ↔ <name>Street + <name>Zip + <name>City
 //
-// Statt jeden Helper im Executor an 4 Stellen verschachtelt aufzurufen,
-// pipeline-iert diese Funktion alle Compound-Type-Konvertierungen in
-// einem Pass. Beim Hinzufügen eines neuen Compound-Types nur EINE Stelle
-// erweitern (das Array hier), nicht alle Executor-Aufrufe.
+// Instead of nesting every helper in the executor at four different points,
+// this function pipelines all compound-type conversions in one pass. Adding
+// a new compound type requires extending only ONE place (this array), rather
+// than every executor call.
 import { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp.js";
 import { flattenMoney, rehydrateMoney } from "./money.js";
-// Reihenfolge ist egal solange die Konverter sich nicht gegenseitig
-// überlappen (z.B. money darf nicht ein Feld berühren das locatedTimestamp
-// schon erzeugt hat). Aktuell überlappen sie nicht — types sind disjunkt.
+// Order is irrelevant as long as the converters do not overlap (for example,
+// money must not touch a field already produced by locatedTimestamp). They do
+// not currently overlap—types are disjoint.
 const FLATTENERS = [flattenLocatedTimestamp, flattenMoney];
 const REHYDRATORS = [rehydrateLocatedTimestamp, rehydrateMoney];
 /**
@@ -24,7 +24,7 @@ export function flattenCompoundTypes(payload, entity) {
     return FLATTENERS.reduce((acc, fn) => fn(acc, entity), payload);
 }
 /**
- * DB-Form (flat) → API-Form (combined). Wird nach jedem Read aufgerufen.
+ * DB form (flat) → API form (combined). Called after every read.
  */
 export function rehydrateCompoundTypes(row, entity) {
     return REHYDRATORS.reduce((acc, fn) => fn(acc, entity), row);

package/dist/db/cross-tenant-reads.d.ts

@@ -0,0 +1,8 @@
+import type { CrossTenantReads } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { EscapeHatchReporter } from "../engine/types/index.ts";
+import { type CreateTenantDbOptions, type TenantDb } from "./tenant-db.ts";
+export declare function createCrossTenantReads(systemModeDb: TenantDb, reason: string, report: EscapeHatchReporter): CrossTenantReads;
+export declare function createHandlerCrossTenantReads(options: Omit<CreateTenantDbOptions, "mode"> & {
+    readonly reason: string;
+    readonly report: EscapeHatchReporter;
+}): CrossTenantReads;

package/dist/db/cross-tenant-reads.js

@@ -0,0 +1,23 @@
+import { createTenantDb } from "./tenant-db.js";
+export function createCrossTenantReads(systemModeDb, reason, report) {
+    return {
+        selectMany(table, where, options) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.selectMany(table, where, options);
+        },
+        fetchOne(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.fetchOne(table, where);
+        },
+        count(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.count(table, where);
+        },
+    };
+}
+// Own system-mode TenantDb without unsafeRaw/globalWrites: the handler gets the read surface only.
+export function createHandlerCrossTenantReads(options) {
+    const { reason, report, ...dbOptions } = options;
+    const systemModeDb = createTenantDb({ ...dbOptions, mode: "system" });
+    return createCrossTenantReads(systemModeDb, reason, report);
+}

package/dist/db/cursor.js

@@ -1,8 +1,7 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-// String-basiert damit UUIDs (Default seit Sprint F) + Integer-Auto-Increment
-// durch denselben Cursor-Pfad laufen. UUIDv7 erfüllt die lex-Monotonie
-// (time-ordered Prefix); UUIDv4 nicht — wer den nutzt, kriegt inkorrekte
-// cursor-Reihenfolge (Default ist v7).
+// Uses strings so UUIDs and integer auto-increment IDs can share the same cursor path.
+// UUIDv7 preserves lexicographic monotonicity through its time-ordered prefix; UUIDv4 does not,
+// so UUIDv4 produces incorrect cursor ordering. The default is v7.
 export function encodeCursor(id) {
     return Buffer.from(String(id)).toString("base64url");
 }

package/dist/db/dialect.d.ts

@@ -3,8 +3,8 @@ import { type ColumnHandle, type SchemaTable } from "@cosmicdrift/kumiko-types/s
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { PgType } from "./entity-table-meta.ts";
 export type { ColumnHandle, SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
-export type TableColumns<_T = any> = SchemaTable;
-export type SelectQuery = any;
+export type TableColumns<_T = unknown> = SchemaTable;
+export type SelectQuery = unknown;
 export declare function pgTypeToSqlType(pgType: PgType): string;
 type ColumnFinal = {
     readonly sqlName: string;

package/dist/db/dialect.js

@@ -15,7 +15,7 @@
 //
 // Static import of the shared Temporal module, not the ambient global: the
 // global may be absent (Hermes/Safari) or torn down in tests, and instantToDriver
-// crashed on timestamptz writes without it (#1480).
+// crashed on timestamptz writes without it.
 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 { brandWritable, schemaTableName } from "./table-introspection.js";
@@ -190,7 +190,7 @@ export function instant(name, opts) {
 // PG `date` — no time-of-day, no timezone. Calendar-day fields (invoice
 // date, lease term) round-trip as Temporal.PlainDate, never through an
 // Instant — that detour is exactly what made `type:"date"` TZ-dependent on
-// both read and write (kumiko-framework#1924).
+// both read and write.
 export function plainDate(name) {
     return buildColumn(name, "date");
 }

package/dist/db/eagerload.d.ts

@@ -15,9 +15,9 @@ export type EagerLoadViewer = {
     readonly user: SessionUser;
     readonly parentVisibility: ParentVisibilityOption;
 };
-/** 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 declare function enrichWithReferences(rows: ReadonlyArray<Record<string, unknown>>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb, viewer: EagerLoadViewer): Promise<Array<Record<string, unknown>>>;
-/** Single-Row-Variante für detail-Calls. */
+/** Single-row variant for detail calls. */
 export declare function enrichRowWithReferences(row: Record<string, unknown>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb, viewer: EagerLoadViewer): Promise<Record<string, unknown>>;
 export {};