@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/db/queries/raw-sql.js

@@ -1,11 +1,11 @@
 import { asRawClient, unsafeReadRetrying } from "../query.js";
 /** Escape hatch for caller-built SQL that may write (or lock). No closed-connection retry —
- *  retrying an ambiguous write risks double-apply (#1358). Prefer {@link executeRawQueryRead}
+ *  retrying an ambiguous write risks double-apply. Prefer {@link executeRawQueryRead}
  *  for SELECT-only paths. */
 export async function executeRawQuery(db, sqlText, params = []) {
     return await asRawClient(db).unsafe(sqlText, params);
 }
-/** SELECT-only escape hatch with the #1163 closed-connection retry. Do not pass
+/** SELECT-only escape hatch with the closed-connection retry. Do not pass
  *  INSERT/UPDATE/DELETE — retry re-executes the statement. */
 // @wrapper-known semantic-alias
 export async function executeRawQueryRead(db, sqlText, params = []) {

package/dist/db/queries/shadow-swap.js

@@ -64,10 +64,10 @@ export function rebuildMetaOrThrow(table, projectionName) {
     return meta;
 }
 // Fence against a rebuild running with a registry that does not match the
-// migrated live schema (#835): during a rolling deploy, a pod still running
+// migrated live schema: during a rolling deploy, a pod still running
 // the previous build can pick up an async rebuild job; its shadow — built from
 // the stale EntityTableMeta — would swap away a freshly-migrated column
-// (recurrence class of #494). Compares COLUMN NAMES only; a type-/nullability-
+// (a recurring failure). Compares COLUMN NAMES only; a type-/nullability-
 // only drift passes (schema regression, not data loss — the boot gate of the
 // next deploy catches it). A missing live table is fine: nothing to wipe.
 // Must run BEFORE buildShadowTable; columnNamesOf pins table_schema='public',
@@ -93,7 +93,7 @@ export async function assertLiveColumnsMatchMeta(db, meta, projectionName) {
         "Rebuilding would swap away the difference. Likely cause: this pod runs a build whose registry is behind (or ahead of) the applied migrations — rolling deploy in progress? — or DDL was applied by hand. " +
         "Rebuild aborted; retry from a pod whose code matches the migrated schema.");
 }
-// EntityTableMeta carries no RLS/policies, so the swap would silently drop them (#2907).
+// EntityTableMeta carries no RLS/policies, so the swap would silently drop them.
 export async function assertLiveTableHasNoRowLevelSecurity(tx, tableName, projectionName) {
     const rows = await asRawClient(tx).unsafe(`SELECT c.relrowsecurity AS rls_enabled, c.relforcerowsecurity AS rls_forced,
        (SELECT count(*)::int FROM pg_policy p WHERE p.polrelid = c.oid) AS policy_count
@@ -158,7 +158,7 @@ const UNREACHABLE_SAMPLE_LIMIT = 20;
 // Runs INSIDE the rebuild tx, under the fence, before swapShadowIntoLive. A live
 // row whose aggregate id has NO event in the projection's source streams is
 // UNREACHABLE: no replay can ever reconstruct it, so the swap would silently
-// drop it. That is the #498 ghost — a row direct-inserted without ever emitting
+// drop it. That is a ghost row direct-inserted without ever emitting
 // a .created event. The static CI guard cannot see it in data that already
 // exists in production, or on table identifiers it couldn't resolve; this
 // catches it at cutover and aborts (tx rolls back, live untouched).
@@ -169,14 +169,14 @@ const UNREACHABLE_SAMPLE_LIMIT = 20;
 //   - a blind-index column recomputed to NULL after the subject's key is
 //     shredded (GDPR erase) — the NULL is the intended end state;
 //   - a `sensitive` column stripped from the event log by design;
-//   - an archived stream that stops replaying (fw#832) — the row's wipe is the
+//   - an archived stream that stops replaying — the row's wipe is the
 //     intended tombstone behavior, reported via backfill's `failed` list;
 //   - a legacy column direct-written before its handler emitted events, healed
-//     by the #494 backfill-then-rebuild flow.
+//     by the backfill-then-rebuild flow.
 // Checking event existence INCLUDING archived streams leaves every one of them
 // alone: those rows all have a real event, so they are not ghosts. Column-level
-// drift is a SEPARATE, non-blocking check — see countColumnDrift below (#916,
-// resolves the #722 open question: observe, don't block).
+// drift is a SEPARATE, non-blocking check — see countColumnDrift below,
+// which resolves the open question: observe, don't block.
 //
 // Implicit projections only (caller-gated). aggregate_id and the entity id are
 // both uuid, so the anti-join probes the events index without a cast.
@@ -298,8 +298,8 @@ async function assertBlindIndexKeyMatchesLive(raw, tableName, quotedTable, bidxC
         `untouched.`);
 }
 // The bidx column is schema-driven, not key-driven: it exists NULL in a
-// plaintext install and in the fw#1610 case (KMS configured, no index key),
-// both of which are correct as-is. Only a POPULATED column with no key
+// plaintext install and in the case where KMS is configured but no index key
+// is present, both of which are correct as-is. Only a POPULATED column with no key
 // configured in THIS process means the rebuild is about to overwrite proof
 // of a real index with NULL — that's the one provable data-loss case.
 export async function assertNoBlindIndexLoss(tx, tableName, meta, projectionName) {
@@ -331,29 +331,29 @@ export async function assertNoBlindIndexLoss(tx, tableName, meta, projectionName
 // live-vs-shadow divergence. A blind-index column (`<field>_bidx`) is
 // recomputed to NULL on GDPR key-shredding; the NULL is the intended end
 // state, not drift. Everything else that legitimately diverges (archived
-// streams, #494 backfill) either never reaches this comparison (archived rows
+// streams, backfill) either never reaches this comparison (archived rows
 // are absent from the shadow entirely, see swapShadowIntoLive) or IS real
-// column drift that the #494 backfill-then-rebuild flow relies on replay to
+// column drift that the backfill-then-rebuild flow relies on replay to
 // heal — reporting it (without blocking) is correct, not a false positive.
 const COLUMN_DRIFT_SAMPLE_LIMIT = 20;
 // Runs INSIDE the rebuild tx, in the same slot as assertNoUnreachableLiveRows
 // (after replay settles, before swapShadowIntoLive). Non-blocking counterpart
 // to the ghost-row guard: reports live rows whose column values differ from
-// the freshly-replayed shadow, WITHOUT aborting the swap (#916, resolves the
-// #722 open question in favor of observe-not-block).
+// the freshly-replayed shadow, WITHOUT aborting the swap (it resolves the
+// open question in favor of observe-not-block).
 //
 // Why non-blocking: a legacy column direct-written before its handler emitted
-// events (#494) diverges from replay by design — that divergence is exactly
+// events diverges from replay by design — that divergence is exactly
 // what the backfill-then-rebuild flow relies on replay to heal. Failing hard
 // here would make rebuild mutually exclusive with that shipped healing path.
-// There is no reliable metadata to distinguish "#494 healing in progress" from
+// There is no reliable metadata to distinguish "healing in progress" from
 // "someone else corrupted this row" short of an open-ended per-column policy
 // blocklist — wrong-by-default whenever a class is missed. So: surface it,
 // don't police it. The caller logs the result; ops decides.
 //
-// Caveat: sensitive CUSTOM fields still diverge until #972 (Subject-DEK
-// design) — regular sensitive fields carry event-payload ciphertext parity
-// post-#973 and don't drift. Both are reported the same as any other column
+// Caveat: sensitive CUSTOM fields still diverge until the Subject-DEK
+// design — regular sensitive fields carry event-payload ciphertext parity
+// post-design and don't drift. Both are reported the same as any other column
 // drift; this is deliberate (see module comment above), not an oversight.
 //
 // Relies on assertLiveColumnsMatchMeta having already run: live/shadow/meta

package/dist/db/query.d.ts

@@ -24,7 +24,7 @@ export declare function hasBegin(client: RawClient): client is RawClientWithBegi
 export declare function asRawClient(db: unknown): RawClient;
 export declare function runnerCanBeginTransaction(db: unknown): boolean;
 export declare function runInSavepoint<T>(tx: ExecutorManagedRunner, fn: (sp: ExecutorManagedRunner) => Promise<T>): Promise<T>;
-export declare function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T>;
+export declare function runInSavepoint<T>(tx: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
 export declare function runInSavepointIfSupported<T>(db: ExecutorManagedRunner, fn: (sp: ExecutorManagedRunner) => Promise<T>): Promise<T>;
 export declare function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
 export type AnyDb = DbRunner | unknown;

package/dist/db/query.js

@@ -13,7 +13,7 @@
 //
 // `table` is an EntityTableMeta; the legacy table objects carrying it under a Symbol are accepted too.
 // Static import (not getTemporal()): coercion works without an installed
-// global and returns the same Temporal classes as the rest of the repo (#1480).
+// global and returns the same Temporal classes as the rest of the repo.
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isOneOf, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { requestContext } from "../api/request-context.js";
@@ -279,7 +279,7 @@ function isTemporalPlainDateTimeLike(v) {
         "toPlainDate" in v &&
         typeof v.toPlainDate === "function");
 }
-// Verified empirically (kumiko-framework#1924): a `date`
+// Verified empirically: a `date`
 // column comes back as a native JS Date, but ALWAYS anchored at UTC
 // midnight regardless of process TZ — epochMilliseconds is stable across
 // zones, only the local wall-clock read of that Date would drift the day
@@ -339,7 +339,7 @@ function coerceDriverRow(row, info) {
     const out = {};
     let changed = false;
     for (const key of Object.keys(row)) {
-        // Blind-index columns (#818) are pure lookup artifacts — the
+        // Blind-index columns are pure lookup artifacts — the
         // deterministic HMAC must never leak into caller/API responses.
         if ((key.endsWith("_bidx") || key.endsWith("Bidx")) && info.hasColumn(key)) {
             changed = true;
@@ -420,7 +420,7 @@ function isSqlExpression(v) {
 // as-is — no Instant detour. Postgres parses a DATE literal without ever
 // consulting the session timezone, so this is TZ-independent by construction
 // (verified empirically — see plainDateFromDriver above for the read side).
-// Compat cushion: pre-#1924 code (this field used to be an Instant) may still
+// Compat cushion: code (this field used to be an Instant) may still
 // hand a Temporal.Instant into a where-filter or write on a `date` column —
 // same UTC anchor as plainDateFromDriver's read side, so a filter built with
 // `Temporal.Now.instant()` keeps working instead of binding a raw Instant the
@@ -515,7 +515,7 @@ function buildWhereClause(info, where, startIndex, qualifier) {
     // multiSelect (and any other jsonb-array-of-scalars column) stores an
     // 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, which Postgres rejects outright (fw#2490).
+    // against the jsonb column, which Postgres rejects outright.
     // Mirrors event-store-executor-read.ts's applyFilter — keep in lock-step.
     function jsonbContainsAny(col, candidates) {
         if (candidates.length === 0)
@@ -703,7 +703,7 @@ function buildWhereClause(info, where, startIndex, qualifier) {
                 conditions.push(`${ref(col)} = ${p.literal}`);
             }
             else {
-                // Blind-index OR rewrite (#818): if the column has a bidx
+                // Blind-index OR rewrite: if the column has a bidx
                 // counterpart (suffix convention `<col>_bidx`, framework-reserved)
                 // and a key is configured, equality matches both arms —
                 // plaintext legacy rows via the plaintext arm, encrypted rows

package/dist/db/rebuild-marker.js

@@ -1,20 +1,18 @@
-// Rebuild-Marker für den drizzle-freien Migrations-Pfad.
+// Rebuild marker for the drizzle-free migration path.
 //
-// `kumiko schema generate` schreibt neben jedes `NNNN_<name>.sql` einen
-// Sibling-Marker `NNNN_<name>.rebuild.json`, der die in dieser Migration
-// geänderten/neu angelegten Tabellen listet. `kumiko schema apply` liest den
-// Marker für jede frisch applizierte Migration und rebuildet die betroffenen
-// Projektionen.
+// `kumiko schema generate` writes a sibling marker
+// `NNNN_<name>.rebuild.json` next to each `NNNN_<name>.sql`, listing the tables
+// changed or created by that migration. `kumiko schema apply` reads the marker
+// for each newly applied migration and rebuilds the affected projections.
 //
-// Bewusst nur **Tabellennamen** (kein Projection-Name): der Generator ist
-// registry-frei (kennt die App-Projektionen nicht). Die Auflösung
-// Tabelle→Projection passiert app-seitig beim Apply via
-// `buildProjectionTableIndex(registry)`. Tabellen ohne zugehörige Projektion
-// werden dort einfach übersprungen.
+// Deliberately stores only **table names** (not projection names): the generator
+// is registry-free and does not know the app's projections. The table-to-
+// projection resolution happens in the app during apply via
+// `buildProjectionTableIndex(registry)`. Tables without a corresponding
+// projection are simply skipped there.
 //
-// Marker werden zum generate-Zeitpunkt aus dem strukturierten `SchemaDiff`
-// geschrieben — nicht beim Apply aus dem (ggf. hand-editierten) SQL
-// re-derived.
+// Markers are written at generate time from the structured `SchemaDiff`, rather
+// than being re-derived during apply from the possibly hand-edited SQL.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { managedChangeRequiresRecreate } from "./migrate-generator.js";
@@ -29,12 +27,12 @@ function markerPathFor(migrationsDir, migrationId) {
 // (managedChangeRequiresRecreate: drop/NOT-NULL-w/o-default/unique-index/type-
 // or nullability-change) — then the table is emptied and must be re-derived from
 // events. A pure additive nullable column is an in-place `ADD COLUMN` ALTER that
-// already brings the table to the target state (same logic #181 applied to
+// already brings the table to the target state (same logic applied to
 // index-/default-only changes). Rebuilding it anyway is wasted replay AND — the
 // bug this closes — a co-triggered rebuild can drop the fresh column (rebuild
 // runs from the rebuilding process's registry meta; on a rolling deploy an older
 // pod's meta lacks the column → shadow-swap wipes it → phantom migration + boot-
-// drift crash; see 0008_add_pending_deletion_request_id / #494 / #835).
+// drift crash).
 //
 // If a NEW additive column genuinely needs value-backfill from historical events
 // (a column DERIVED from existing event fields), opt in explicitly by hand-adding
@@ -60,18 +58,19 @@ export function rebuildTablesFromDiff(diff) {
     }
     return [...names].sort();
 }
-// Schreibt `<sqlFilename ohne .sql>.rebuild.json`. Leere Tabellen-Liste →
-// kein Marker (z.B. reine Drop-Migration).
+// Writes `<sqlFilename without .sql>.rebuild.json`. An empty table list writes no
+// marker (for example, a drop-only migration).
 export function writeRebuildMarker(migrationsDir, sqlFilename, tables) {
-    // skip: leere Tabellen-Liste → kein Marker (z.B. reine Drop-Migration).
+    // skip: empty table list means no marker is written (for example, for a
+    // migration that only drops tables).
     if (tables.length === 0)
         return;
     const migrationId = sqlFilename.replace(/\.sql$/, "");
     const marker = { version: MARKER_VERSION, tables };
     writeFileSync(markerPathFor(migrationsDir, migrationId), `${JSON.stringify(marker, null, 2)}\n`);
 }
-// Liest die Tabellen-Liste für eine applizierte Migration. Kein Marker /
-// kaputtes File → leere Liste (Migration ohne Projection-Impact).
+// Reads the table list for an applied migration. A missing or malformed file
+// yields an empty list (the migration has no projection impact).
 export function readRebuildMarker(migrationsDir, migrationId) {
     const path = markerPathFor(migrationsDir, migrationId);
     if (!existsSync(path))

package/dist/db/replay-migration-sql.js

@@ -70,7 +70,7 @@ function parseColumnNames(body) {
 // through to the fail-loud check as "unparsed". RENAME TO / RENAME COLUMN
 // are not listed here: they change identity and are applied explicitly.
 const SHAPE_NEUTRAL_ALTER_CLAUSE_RE = new RegExp([
-    `ALTER COLUMN\\s+${IDENT}\\s+TYPE\\b`, // #1085 int/bigint-catchup fixes
+    `ALTER COLUMN\\s+${IDENT}\\s+TYPE\\b`, // int/bigint-catchup fixes
     `ALTER COLUMN\\s+${IDENT}\\s+(SET|DROP)\\s+NOT NULL\\b`,
     `ALTER COLUMN\\s+${IDENT}\\s+(SET DEFAULT\\b|DROP DEFAULT\\b)`,
     `(ADD|DROP)\\s+CONSTRAINT\\s+${IDENT}`,
@@ -269,7 +269,7 @@ function applyStatement(schema, statement, context) {
 // Reuses the real runner's file-discovery + statement-splitting
 // (loadMigrationsFromDir) instead of a second copy, so any future change to
 // sub-directory handling, numeric sort order, or the .sql filter can't
-// silently drift between the runner and this replay (#1522/9).
+// silently drift between the runner and this replay.
 export function replayMigrationsDir(migrationsDir) {
     const schema = new Map();
     const migrations = loadMigrationsFromDir(migrationsDir, expandDestructiveMarkers);

package/dist/db/schema-inspection.js

@@ -26,11 +26,10 @@ function resolveUnsafeClient(db) {
 //   await unsafePushTables(db, { events: eventsTable });
 export async function tableExists(db, fullyQualifiedName) {
     const unsafe = resolveUnsafeClient(db);
-    // quote_ident-Round-trip auf SQL-Seite: ohne Quotes folded postgres
-    // unquoted identifier case-insensitiv (myWidget → mywidget), während die
-    // generierte DDL den Namen via quoteIdent("myWidget") → "myWidget" case-
-    // preserved schreibt. quote_ident sorgt für identische Quotierung beidseits.
-    // Schema-qualifizierte Namen (`public.events`) werden per Split einzeln quotet.
+    // SQL-side quote_ident round-trip: unquoted PostgreSQL identifiers are folded case-insensitively
+    // (`myWidget` → `mywidget`), while generated DDL preserves the case via
+    // `quoteIdent("myWidget")` → `"myWidget"`. quote_ident keeps both sides quoted identically.
+    // Schema-qualified names (`public.events`) are quoted one component at a time after splitting.
     const dotIdx = fullyQualifiedName.indexOf(".");
     const [sql, params] = dotIdx >= 0
         ? [

package/dist/db/table-builder.d.ts

@@ -196,8 +196,7 @@ export type EntityRow<E extends EntityDefinition = EntityDefinition> = string ex
 export type { ExecutorManagedRunner, ExecutorManagedWriteCapability, Writable, WritableSchemaTable, WritableTable, } from "@cosmicdrift/kumiko-types/executor-brand";
 export type { EntityTenancy, TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 type EntityTableTenancy<E extends EntityDefinition> = [NonNullable<E["tenancy"]>] extends [never] ? "tenant" : [NonNullable<E["tenancy"]>] extends ["global"] ? "global" : "tenant";
-export type EntityTable<E extends EntityDefinition = EntityDefinition> = TableColumns<// biome-ignore lint/suspicious/noExplicitAny: drizzle's internal table-config stays generic; we layer typed columns on top via the intersection below.
-any> & BaseColumnsType<E> & SoftDeleteColumnsType & ColumnsForEntity<E["fields"]> & TenancyBrand<EntityTableTenancy<E>>;
+export type EntityTable<E extends EntityDefinition = EntityDefinition> = TableColumns & BaseColumnsType<E> & SoftDeleteColumnsType & ColumnsForEntity<E["fields"]> & TenancyBrand<EntityTableTenancy<E>>;
 export declare function buildBaseColumns(softDelete: boolean, idType?: "serial" | "uuid"): {
     id: ColumnBuilder<string> | ColumnBuilder<number>;
     tenantId: ColumnBuilder<string>;

package/dist/db/table-builder.js

@@ -16,29 +16,28 @@ export function physicalColumnName(table, field) {
 // Returns column(s) for a field. Most fields return a single entry,
 // money returns two (amount + currency).
 //
-// `required: true` auf einem FieldDefinition mappt **immer** auf .notNull()
-// in der DB-Spalte. Die alte Implementation hat das nur für reference-
-// fields gemacht — text/select/number/etc. waren stillschweigend nullable
-// in der DB, auch wenn der API-Validator required erzwungen hat. Folge:
-// hand-written PgTable-Definitionen mussten daneben mit .notNull() pflegen,
-// was zu Doppel-Definitionen + Schema-Drift führte. Jetzt ist r.entity
-// die einzige Wahrheit.
+// `required: true` on a FieldDefinition always maps to .notNull() in the
+// database column. Previously this applied only to reference fields, while
+// text/select/number/etc. remained silently nullable even when the API
+// validator enforced required. That forced hand-written PgTable definitions
+// to add .notNull(), causing duplicate definitions and schema drift. Now
+// r.entity is the single source of truth.
 function fieldToColumns(name, field, entity) {
     const snakeName = toSnakeCase(name);
     switch (field.type) {
         case "text":
         case "longText": {
-            // Beide mappen auf PG `text` (unbounded). Unterschied lebt nur
-            // im Type-Layer: longText hat kein sortable/searchable/filterable
-            // (Sprint 5b vorab). Reihenfolge default() VOR notNull(): drizzle's
-            // column-builder chained beides; ohne default() hat die generierte
-            // SQL keinen DEFAULT-clause (bricht ALTER TABLE ADD COLUMN auf
-            // existing rows). longText hat heute kein default-feld im type,
-            // aber der check `field.default !== undefined` ist defensive.
+            // Both map to PG `text` (unbounded). The difference exists only in the
+            // type layer: longText has no sortable/searchable/filterable support.
+            // The order default() before notNull() matters: the column builder
+            // chains both; without default(), the generated SQL has no DEFAULT
+            // clause, which breaks ALTER TABLE ADD COLUMN on existing rows.
+            // longText currently has no default field in its type, but checking
+            // `field.default !== undefined` is defensive.
             const base = text(snakeName);
             const withDefault = "default" in field && field.default !== undefined ? base.default(field.default) : base;
             const mainCol = { [name]: field.required ? withDefault.notNull() : withDefault };
-            // lookupable → nullable HMAC-Blind-Index-Spalte (lock-step mit
+            // lookupable → nullable HMAC blind-index column (kept in lockstep with
             // fieldToColumnMeta in entity-table-meta.ts).
             if (field.type === "text" && field.lookupable === true) {
                 return { ...mainCol, [`${name}Bidx`]: text(`${snakeName}_bidx`) };
@@ -54,23 +53,23 @@ function fieldToColumns(name, field, entity) {
                         : boolean(snakeName),
             };
         case "select": {
-            // default() durchreichen — entity-table-meta rendert deklarierte
-            // defaults, dieser Builder MUSS lock-step bleiben (sonst trägt das
-            // Meta am buildEntityTable-Objekt eine andere Spalte als die
-            // Migration, #255-Follow-up-Befund).
+            // Pass default() through because entity-table-meta renders declared
+            // defaults. This builder must stay in lockstep; otherwise the metadata
+            // on the buildEntityTable object describes a different column than the
+            // migration.
             const base = text(snakeName);
             const col = field.default !== undefined ? base.default(field.default) : base;
             return { [name]: field.required ? col.notNull() : col };
         }
         case "multiSelect":
-            // jsonb-Array<string> mit Default `[]` und immer NOT NULL.
+            // jsonb string array with default `[]`, always NOT NULL.
             //
-            // Der `required`-Flag auf MultiSelectFieldDef wird hier bewusst
-            // ignoriert: Mit Default `[]` ist das Feld strukturell never-null
-            // (Insert ohne Wert → leeres Array, nicht NULL). Read-Side-Code
-            // braucht keinen null-check, das ist API-Garantie. Wer "wirklich
-            // null" will (= "Feld noch nie gesetzt") nutzt einen separaten
-            // Status-Field oder ein optional-typed reference statt eines
+            // The `required` flag on MultiSelectFieldDef is intentionally ignored:
+            // with default `[]`, the field is structurally never null (an insert
+            // without a value produces an empty array, not NULL). Read-side code
+            // therefore needs no null check; this is an API guarantee. Code that
+            // needs actual null (meaning the field has never been set) should use
+            // a separate status field or an optional-typed reference instead of a
             // multi-select.
             return { [name]: jsonb(snakeName).default([]).notNull() };
         case "number": {
@@ -84,19 +83,18 @@ function fieldToColumns(name, field, entity) {
             return { [name]: field.required ? col.notNull() : col };
         }
         case "bigInt": {
-            // 64-bit-Integer fuer Audit-Counter, Byte-Sizes, Cumulative-Sums.
-            // mode:"number" liefert JS-`number` (sicher bis 2^53 ≈ 9 PB) statt
-            // JS-`bigint` — JSON-serialisierbar, Frontend-tauglich. Wer >2^53
-            // braucht (Astronomie-Astronomie), nutzt einen Text-Field mit
-            // eigenem Codec.
+            // 64-bit integer for audit counters, byte sizes, and cumulative sums.
+            // mode:"number" produces a JS `number` (safe up to 2^53 ≈ 9 PB) rather
+            // than JS `bigint`, making it JSON-serializable and frontend-friendly.
+            // Values above 2^53 should use a text field with a custom codec.
             const base = bigint(snakeName, { mode: "number" });
             const col = field.default !== undefined ? base.default(field.default) : base;
             return { [name]: field.required ? col.notNull() : col };
         }
         case "reference":
-            // Tier 2.7e-3: FK-Style UUID-Spalte. Multi-Mode (Tier 2.7e-Multi)
-            // speichert UUIDs als jsonb-Array<string>. Single-Mode bleibt
-            // klassische UUID-Spalte (NOT NULL nur bei required).
+            // FK-style UUID column. Multi-mode stores UUIDs as a jsonb string array;
+            // single-mode remains a conventional UUID column (NOT NULL only when
+            // required).
             if (field.multiple === true) {
                 return { [name]: jsonb(snakeName).default([]).notNull() };
             }
@@ -104,11 +102,12 @@ function fieldToColumns(name, field, entity) {
                 [name]: field.required ? uuid(snakeName).notNull() : uuid(snakeName),
             };
         case "money":
-            // BIGINT storing the integer minor unit (cents for EUR, yen for JPY —
-            // the currency column tells you which). INTEGER would cap at ~21 M EUR
-            // which is too tight for B2B invoices, property values or balance
-            // aggregates. BIGINT handles up to ~90 trillion EUR safely in JS.
-            // Currency hat immer einen Default, ist also strukturell .notNull().
+            // BIGINT stores the integer minor unit (cents for EUR, yen for JPY —
+            // the currency column identifies which). INTEGER would cap at about
+            // 21 M EUR, which is too low for B2B invoices, property values, or
+            // balance aggregates. BIGINT safely handles up to about 90 trillion
+            // EUR in JS.
+            // Currency always has a default, so it is structurally .notNull().
             return {
                 [name]: field.required ? moneyAmount(snakeName).notNull() : moneyAmount(snakeName),
                 [`${name}Currency`]: text(`${snakeName}_currency`)
@@ -116,47 +115,47 @@ function fieldToColumns(name, field, entity) {
                     .notNull(),
             };
         case "embedded":
-            // jsonb mit default `{}` und immer NOT NULL — analog zu multiSelect.
-            // `required` wird bewusst ignoriert weil der Default das Feld
-            // strukturell never-null macht. Wer optional-embedded möchte (=
-            // "Feld komplett weglassen können") modelliert das über ein
-            // wrapper-feld mit boolean-flag oder discriminierte-union.
+            // jsonb with default `{}`, always NOT NULL, analogous to multiSelect.
+            // `required` is intentionally ignored because the default makes the
+            // field structurally never null. To make embedded data optional (so
+            // the field can be omitted entirely), model it with a wrapper field
+            // and boolean flag or a discriminated union.
             // multiple → the value is a list of rows, so the empty default is `[]`.
             return field.multiple === true
                 ? { [name]: jsonb(snakeName).default([]).notNull() }
                 : { [name]: jsonb(snakeName).default({}).notNull() };
         case "jsonb":
-            // Free-form jsonb — keys nicht schema-validated. Default `{}`, NOT NULL
-            // (analog zu embedded). Use-case: custom-fields-Bundle's host-entity-
-            // `customFields`-Spalte (tenant-definierte dynamische keys).
+            // Free-form jsonb — keys are not schema-validated. Default `{}`, NOT NULL
+            // (analogous to embedded). Use case: the host entity's custom-fields
+            // bundle in the `customFields` column, whose keys are tenant-defined.
             return { [name]: jsonb(snakeName).default({}).notNull() };
         case "date": {
             // Real PG `date` — no time-of-day, no timezone. Temporal.PlainDate
             // end-to-end (see plainDate() in dialect.ts). Was aliased on instant()
-            // = TIMESTAMPTZ until kumiko-framework#1924 (TZ-dependent round-trip).
+            // = TIMESTAMPTZ (TZ-dependent round-trip).
             const col = plainDate(snakeName);
             return { [name]: field.required ? col.notNull() : col };
         }
         case "timestamp": {
-            // UTC-Instant — gespeichert als TIMESTAMPTZ in PG, gelesen/geschrieben
-            // als Temporal.Instant via instant() customType (siehe dialect.ts).
-            // Sprint F: Single-Mode-Welt — Caller-Code kennt nur Temporal.Instant,
-            // nie JS-Date. Auch Vergleiche (lte/gt/orderBy) akzeptieren Instants
-            // direkt, kein .toString()-Cast nötig.
+            // UTC instant — stored as TIMESTAMPTZ in PG and read/written as
+            // Temporal.Instant through the instant() customType (see dialect.ts).
+            // Callers use only Temporal.Instant, never JS Date. Comparisons
+            // (lte/gt/orderBy) also accept Instants directly, so no .toString()
+            // cast is needed.
             const col = instant(snakeName);
             return { [name]: field.required ? col.notNull() : col };
         }
         case "tz": {
-            // IANA-Zonenname als TEXT — Validierung über Zod-Schema (kommt im
-            // Validator-Schritt). Snake-Convention: `pickup_tz`.
+            // IANA time-zone name as TEXT — validated through the Zod schema in the
+            // validator step. Snake-case convention: `pickup_tz`.
             const col = text(snakeName);
             return { [name]: field.required ? col.notNull() : col };
         }
         case "locatedTimestamp": {
-            // ZWEI Spalten als atomares Pair: <name>_utc TIMESTAMPTZ + <name>_tz TEXT.
-            // _utc ist instant() (Temporal.Instant), _tz ist text (IANA-Name).
-            // Auto-Convert (at+tz → utc beim Insert; utc+tz → at beim Read) wird
-            // im Executor verdrahtet (Phase C). required propagiert auf beide.
+            // Two columns form an atomic pair: <name>_utc TIMESTAMPTZ + <name>_tz TEXT.
+            // _utc is instant() (Temporal.Instant), and _tz is text (IANA name).
+            // The executor wires automatic conversion (at+tz → utc on insert;
+            // utc+tz → at on read). required propagates to both columns.
             const utc = instant(`${snakeName}_utc`);
             const tz = text(`${snakeName}_tz`);
             return {
@@ -188,12 +187,12 @@ function fieldToColumns(name, field, entity) {
  * Derives a table name from an entity name:
  * 1. camelCase → snake_case (e.g. "memberTask" → "member_task")
  * 2. Simple English pluralization (category→categories, status→statuses, task→tasks)
- * 3. `read_` prefix — markiert die Tabelle als Event-Sourced-Read-Model,
- *    damit im DB-Tool sofort erkennbar ist dass App-Code nicht direkt
- *    reinschreibt. Event-Store (kumiko_events) + Framework-State
- *    (kumiko_*) haben ihren eigenen Prefix, normale App-Side-Tables
- *    (ohne ES-Anbindung) haben keinen — die drei Kategorien sind damit
- *    im Tabellenbrowser unterscheidbar.
+ * 3. `read_` prefix — marks the table as an event-sourced read model so
+ *    it is immediately distinguishable in database tools and application
+ *    code is not expected to write to it directly. The event store
+ *    (`kumiko_events`) and framework state (`kumiko_*`) use their own
+ *    prefixes; ordinary app-side tables without event-sourcing have none.
+ *    The three categories are therefore distinguishable in the table browser.
  */
 const ES_PLURAL_SUFFIXES = ["s", "sh", "ch", "x"];
 export const READ_MODEL_PREFIX = "read_";
@@ -219,12 +218,13 @@ export function buildBaseColumns(softDelete, idType = "uuid") {
         id: idColumn,
         tenantId: uuid("tenant_id").notNull(),
         version: integer("version").default(1).notNull(),
-        // Sprint F: Temporal.Instant durchgängig (siehe instant() in dialect.ts).
-        // Vorher mode default "date" → Inkonsistenz mit user-defined timestamp
-        // Felder (mode "string"). Jetzt: ein Mode für alle Timestamps.
+        // Temporal.Instant is used throughout (see instant() in dialect.ts).
+        // Previously the default mode was "date", which was inconsistent with
+        // user-defined timestamp fields (mode "string"). A single mode is now
+        // used for all timestamps.
         // customType doesn't expose Drizzle's `defaultNow()` shortcut — use raw
-        // SQL so PG sets the value on insert and we don't need to pass an
-        // Instant from JS for every row create.
+        // SQL so PG sets the value on insert and callers need not pass an
+        // Instant for every row creation.
         insertedAt: instant("inserted_at").default(sql `now()`).notNull(),
         modifiedAt: instant("modified_at"),
         // User-IDs are stringified UUIDs post-ES migration. Text (not uuid) so the
@@ -295,9 +295,9 @@ export function buildEntityTable(entityName, entity, options) {
     }
     // Default table name derived from entityName (e.g. "memberTask" → "read_member_tasks")
     const baseTableName = entity.table ?? toTableName(entityName);
-    // featureName-prefix wird zwischen read_ und den base-Namen geschoben,
-    // damit alle read-models einheitlich mit `read_` starten — egal ob
-    // featureName gesetzt ist oder nicht. Beispiel:
+    // The featureName prefix is inserted between read_ and the base name so
+    // all read models consistently start with `read_`, whether or not
+    // featureName is set. Examples:
     //   featureName="shop", base="read_orders"  →  "read_shop_orders"
     //   featureName=undef,  base="read_orders"  →  "read_orders"
     //   featureName="shop", base="orders" (no read_)  →  "shop_orders"
@@ -349,7 +349,7 @@ export function buildEntityTable(entityName, entity, options) {
                 indexes[`${tableName}_${toSnakeCase(fieldName)}_idx`] = index(`${tableName}_${toSnakeCase(fieldName)}_idx`).on(column);
             }
         }
-        // lookupable-Felder: Index auf der bidx-Spalte (lock-step mit
+        // lookupable fields: index the bidx column (kept in lockstep with
         // deriveEntityTableMeta).
         const bidxFieldByField = new Map();
         for (const [name, field] of Object.entries(entity.fields)) {
@@ -362,10 +362,10 @@ export function buildEntityTable(entityName, entity, options) {
                 indexes[idxName] = index(idxName).on(column);
             }
         }
-        // entity.indexes = composite/unique-Indices die der Author explizit
-        // deklariert hat. Spalten werden via field-name (camelCase) angesprochen,
-        // der Index-Name folgt der Convention <table>_<col1>_<col2>_<unique|idx>
-        // — Override via index.name möglich.
+        // entity.indexes contains composite/unique indexes explicitly declared by
+        // the author. Columns are addressed by field name (camelCase), and the
+        // index name follows <table>_<col1>_<col2>_<unique|idx>; index.name can
+        // override the convention.
         for (const def of entity.indexes ?? []) {
             const cols = def.columns
                 .map((fieldName) => tHandle[fieldName])
@@ -388,12 +388,12 @@ export function buildEntityTable(entityName, entity, options) {
             }
             else if (def.unique === true && entity.softDelete === true) {
                 // Soft-deleted rows keep their value, so a full unique index would
-                // permanently block reuse; kept in lock-step with entity-table-meta.ts (framework#2593).
+                // permanently block reuse; kept in lock-step with entity-table-meta.ts.
                 chain = chain.where(sql.raw(SOFT_DELETE_LIVE_ROW_PREDICATE));
             }
             indexes[indexName] = chain;
-            // Partielles bidx-Pendant für unique-Indices über lookupable-Spalten
-            // (lock-step mit deriveEntityTableMeta).
+            // Partial bidx counterpart for unique indexes over lookupable fields
+            // (kept in lockstep with deriveEntityTableMeta).
             if (def.unique === true && def.where === undefined) {
                 const bidxFieldNames = def.columns.map((c) => bidxFieldByField.get(c) ?? c);
                 if (bidxFieldNames.some((c, i) => c !== def.columns[i])) {
@@ -406,7 +406,7 @@ export function buildEntityTable(entityName, entity, options) {
                             .map((c) => `"${toSnakeCase(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).
+                        // holds.
                         const whereText = (entity.softDelete === true
                             ? [...notNullParts, SOFT_DELETE_LIVE_ROW_PREDICATE]
                             : notNullParts).join(" AND ");