@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

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/reference-data.js

@@ -37,7 +37,12 @@ export async function seedReferenceData(defs, registry, db) {
             const keyValue = row[upsertKey];
             if (keyValue === undefined)
                 continue;
-            const existing = await fetchOne(db, table, { [upsertKey]: keyValue });
+            // Soft-deleted rows are invisible to executor.update, so treat them as missing and re-create.
+            const existing = await fetchOne(db, table, {
+                [upsertKey]: keyValue,
+                tenantId: SYSTEM_TENANT_ID,
+                ...(entity.softDelete && { isDeleted: false }),
+            });
             if (existing) {
                 const changes = {};
                 for (const [field, value] of Object.entries(row)) {

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

@@ -1,6 +1,5 @@
 import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { toSnakeCase } from "../utils/case.js";
-import { assertUnreachable } from "../utils/index.js";
 import { markExecutorManagedTable } from "./executor-managed-tables.js";
 import { columnHandleName } from "./table-introspection.js";
 export { toSnakeCase } from "../utils/case.js";
@@ -13,173 +12,120 @@ export const SOFT_DELETE_LIVE_ROW_PREDICATE = `"is_deleted" = false`;
 export function physicalColumnName(table, field) {
     return columnHandleName(table, field) ?? toSnakeCase(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.
-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.
-            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
-            // fieldToColumnMeta in entity-table-meta.ts).
-            if (field.type === "text" && field.lookupable === true) {
-                return { ...mainCol, [`${name}Bidx`]: text(`${snakeName}_bidx`) };
-            }
-            return mainCol;
-        }
-        case "boolean":
-            return {
-                [name]: field.default !== undefined
-                    ? boolean(snakeName).default(field.default).notNull()
-                    : field.required
-                        ? boolean(snakeName).notNull()
-                        : 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).
-            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.
-            //
-            // 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
-            // multi-select.
-            return { [name]: jsonb(snakeName).default([]).notNull() };
-        case "number": {
-            const base = field.integer === true ? integer(snakeName) : doublePrecision(snakeName);
-            const col = field.default !== undefined ? base.default(field.default) : base;
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "decimal": {
-            const base = decimalColumn(snakeName, field.precision, field.scale);
-            const col = field.default !== undefined ? base.default(field.default) : base;
-            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.
-            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).
-            if (field.multiple === true) {
-                return { [name]: jsonb(snakeName).default([]).notNull() };
-            }
-            return {
-                [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().
-            return {
-                [name]: field.required ? moneyAmount(snakeName).notNull() : moneyAmount(snakeName),
-                [`${name}Currency`]: text(`${snakeName}_currency`)
-                    .default(entity.defaultCurrency ?? "EUR")
-                    .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.
-            // 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).
-            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).
-            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.
-            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`.
-            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.
-            const utc = instant(`${snakeName}_utc`);
-            const tz = text(`${snakeName}_tz`);
-            return {
-                [`${name}Utc`]: field.required ? utc.notNull() : utc,
-                [`${name}Tz`]: field.required ? tz.notNull() : tz,
-            };
-        }
-        case "file":
-        case "image": {
-            // Single file: stores fileRefId as UUID — must match fileRefsTable.id
-            // (uuid column). Anything narrower (integer, text length-limited) would
-            // silently truncate or type-coerce at INSERT time and the FK reference
-            // would be unusable.
-            const col = uuid(snakeName);
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "files":
-        case "images":
-            // Ordered fileRef UUID array, same shape as multiSelect: never null.
-            return { [name]: jsonb(snakeName).default([]).notNull() };
-        default:
-            assertUnreachable(field, "field type");
+// `required: true` maps to NOT NULL for every field type, so r.entity stays the
+// single source of truth and hand-written tables never add .notNull() on top.
+function notNullWhenRequired(column, required) {
+    return required ? column.notNull() : column;
+}
+// Without a DEFAULT clause ALTER TABLE ADD COLUMN breaks on existing rows, and
+// entity-table-meta renders declared defaults too, so both builders stay in lockstep.
+function withDeclaredDefault(column, value) {
+    return value !== undefined ? column.default(value) : column;
+}
+// longText differs from text only in the type layer (no sortable/searchable/filterable).
+function textColumns(name, snakeName, field) {
+    const declaredDefault = "default" in field ? field.default : undefined;
+    const mainCol = {
+        [name]: notNullWhenRequired(withDeclaredDefault(text(snakeName), declaredDefault), field.required),
+    };
+    // Nullable HMAC blind-index column, in lockstep with fieldToColumnMeta in entity-table-meta.ts.
+    if (field.type === "text" && field.lookupable === true) {
+        return { ...mainCol, [`${name}Bidx`]: text(`${snakeName}_bidx`) };
     }
+    return mainCol;
+}
+function booleanColumns(name, snakeName, field) {
+    if (field.default !== undefined) {
+        return { [name]: boolean(snakeName).default(field.default).notNull() };
+    }
+    return { [name]: notNullWhenRequired(boolean(snakeName), field.required) };
+}
+function numberColumns(name, snakeName, field) {
+    const base = field.integer === true ? integer(snakeName) : doublePrecision(snakeName);
+    return { [name]: notNullWhenRequired(withDeclaredDefault(base, field.default), field.required) };
+}
+function referenceColumns(name, snakeName, field) {
+    if (field.multiple === true)
+        return { [name]: emptyJsonbArray(snakeName) };
+    return { [name]: notNullWhenRequired(uuid(snakeName), field.required) };
+}
+// BIGINT minor units: INTEGER would cap at about 21 M EUR. The currency column
+// always has a default, so it is structurally NOT NULL.
+function moneyColumns(name, snakeName, field, entity) {
+    return {
+        [name]: notNullWhenRequired(moneyAmount(snakeName), field.required),
+        [`${name}Currency`]: text(`${snakeName}_currency`)
+            .default(entity.defaultCurrency ?? "EUR")
+            .notNull(),
+    };
+}
+// <name>_utc + <name>_tz form an atomic pair the executor converts on write and
+// read, so `required` propagates to both columns.
+function locatedTimestampColumns(name, snakeName, field) {
+    return {
+        [`${name}Utc`]: notNullWhenRequired(instant(`${snakeName}_utc`), field.required),
+        [`${name}Tz`]: notNullWhenRequired(text(`${snakeName}_tz`), field.required),
+    };
+}
+// The `[]` default makes the column structurally never null, so `required` is
+// intentionally ignored and read-side code needs no null check.
+function emptyJsonbArray(snakeName) {
+    return jsonb(snakeName).default([]).notNull();
+}
+// Same reasoning as emptyJsonbArray; optional embedded data needs a wrapper field.
+function emptyJsonbObject(snakeName) {
+    return jsonb(snakeName).default({}).notNull();
+}
+function singleColumnNotNullWhenRequired(column) {
+    return (name, snakeName, field) => ({
+        [name]: notNullWhenRequired(column(snakeName), field.required),
+    });
+}
+// Each entry has a type-level twin in ColumnsForField and a meta-level twin in
+// fieldToColumnMeta (entity-table-meta.ts).
+const COLUMN_EMITTERS = {
+    text: textColumns,
+    longText: textColumns,
+    boolean: booleanColumns,
+    select: (name, snakeName, field) => ({
+        [name]: notNullWhenRequired(withDeclaredDefault(text(snakeName), field.default), field.required),
+    }),
+    multiSelect: (name, snakeName) => ({ [name]: emptyJsonbArray(snakeName) }),
+    number: numberColumns,
+    decimal: (name, snakeName, field) => ({
+        [name]: notNullWhenRequired(withDeclaredDefault(decimalColumn(snakeName, field.precision, field.scale), field.default), field.required),
+    }),
+    // mode "number" keeps the value JSON-serializable (safe up to 2^53).
+    bigInt: (name, snakeName, field) => ({
+        [name]: notNullWhenRequired(withDeclaredDefault(bigint(snakeName, { mode: "number" }), field.default), field.required),
+    }),
+    reference: referenceColumns,
+    money: moneyColumns,
+    embedded: (name, snakeName, field) => ({
+        [name]: field.multiple === true ? emptyJsonbArray(snakeName) : emptyJsonbObject(snakeName),
+    }),
+    jsonb: (name, snakeName) => ({ [name]: emptyJsonbObject(snakeName) }),
+    date: singleColumnNotNullWhenRequired(plainDate),
+    timestamp: singleColumnNotNullWhenRequired(instant),
+    tz: singleColumnNotNullWhenRequired(text),
+    locatedTimestamp: locatedTimestampColumns,
+    // Must match fileRefsTable.id (uuid); anything narrower breaks the reference.
+    file: singleColumnNotNullWhenRequired(uuid),
+    image: singleColumnNotNullWhenRequired(uuid),
+    files: (name, snakeName) => ({ [name]: emptyJsonbArray(snakeName) }),
+    images: (name, snakeName) => ({ [name]: emptyJsonbArray(snakeName) }),
+};
+function emitFieldColumns(type, name, field, entity) {
+    // A type from untyped input must not reach an Object.prototype member.
+    if (!Object.hasOwn(COLUMN_EMITTERS, type)) {
+        throw new Error(`[Kumiko] unhandled field type: ${String(field)}`);
+    }
+    const emit = COLUMN_EMITTERS[type];
+    return emit(name, toSnakeCase(name), field, entity);
+}
+// Most fields return one column; money and locatedTimestamp return two.
+function fieldToColumns(name, field, entity) {
+    return emitFieldColumns(field.type, name, field, entity);
 }
 // Accepts both camelCase (`tenantMembership`) and kebab-case (`tenant-membership`)
 // entity / field names. Implementation lives in utils/case — re-exported here
@@ -188,12 +134,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 +165,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 +242,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 +296,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 +309,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 +335,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 +353,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 ");

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

@@ -0,0 +1,10 @@
+import type { TableLike } from "./query.ts";
+export type TableInfo = {
+    readonly name: string;
+    readonly columnOf: (field: string) => string;
+    readonly pgTypeOf: (column: string) => string | undefined;
+    readonly bigintJsModeOf: (column: string) => "number" | "bigint" | undefined;
+    readonly fieldOf: (column: string) => string;
+    readonly hasColumn: (fieldOrColumn: string) => boolean;
+};
+export declare function extractTableInfo(table: TableLike): TableInfo;

package/dist/db/table-info.js

@@ -0,0 +1,45 @@
+import { camelCase as envCamelCase } from "../env/index.js";
+import { toSnakeCase } from "./table-builder.js";
+import { asEntityTableMeta } from "./table-introspection.js";
+// Idempotent snake_case → camelCase. `env.camelCase` always lowercases first
+// (designed for SHOUT_CASE input) — for already-camelCase keys (mock rows
+// in tests, projection-aliased columns) it would silently produce "tenantid"
+// instead of leaving "tenantId" alone. Guard with an underscore check so
+// the conversion only fires when the key is actually snake-shaped.
+function snakeToCamel(key) {
+    if (!key.includes("_"))
+        return key;
+    return envCamelCase(key);
+}
+export function extractTableInfo(table) {
+    const meta = asEntityTableMeta(table);
+    if (!meta) {
+        throw new Error("extractTableInfo: table is not a kumiko EntityTableMeta — " +
+            "build it via buildEntityTable / deriveEntityTableMeta / table().");
+    }
+    const colByField = new Map();
+    const fieldByCol = new Map();
+    const typeByCol = new Map();
+    const bigintModeByCol = new Map();
+    for (const c of meta.columns) {
+        typeByCol.set(c.name, c.pgType);
+        if (c.bigintJsMode !== undefined)
+            bigintModeByCol.set(c.name, c.bigintJsMode);
+        // EntityTableMeta column names are snake_case. Map snake → snake AND
+        // derive a camelCase JS field-name so result rows can be renamed back
+        // to the API shape (`aggregate_id` → `aggregateId`).
+        colByField.set(c.name, c.name);
+        const camel = snakeToCamel(c.name);
+        if (camel !== c.name)
+            colByField.set(camel, c.name);
+        fieldByCol.set(c.name, camel === c.name ? c.name : camel);
+    }
+    return {
+        name: meta.tableName,
+        columnOf: (field) => colByField.get(field) ?? toSnakeCase(field),
+        pgTypeOf: (col) => typeByCol.get(col),
+        bigintJsModeOf: (col) => bigintModeByCol.get(col),
+        fieldOf: (col) => fieldByCol.get(col) ?? snakeToCamel(col),
+        hasColumn: (fieldOrColumn) => colByField.has(fieldOrColumn) || fieldByCol.has(fieldOrColumn),
+    };
+}

package/dist/db/temporal-value-guards.d.ts

@@ -0,0 +1,6 @@
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+export declare function isTemporalInstant(v: unknown): v is Temporal.Instant;
+export declare function isTemporalPlainDate(v: unknown): v is Temporal.PlainDate;
+export declare function isTemporalPlainDateTimeLike(v: unknown): v is {
+    toPlainDate(): Temporal.PlainDate;
+};

package/dist/db/temporal-value-guards.js

@@ -0,0 +1,15 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+export function isTemporalInstant(v) {
+    return propertyOf(v, Symbol.toStringTag) === "Temporal.Instant";
+}
+export function isTemporalPlainDate(v) {
+    return propertyOf(v, Symbol.toStringTag) === "Temporal.PlainDate";
+}
+export function isTemporalPlainDateTimeLike(v) {
+    const tag = propertyOf(v, Symbol.toStringTag);
+    return ((tag === "Temporal.PlainDateTime" || tag === "Temporal.ZonedDateTime") &&
+        typeof v === "object" &&
+        v !== null &&
+        "toPlainDate" in v &&
+        typeof v.toPlainDate === "function");
+}

package/dist/db/tenant-db-runner.d.ts

@@ -6,5 +6,6 @@ export declare function isDbRunner(value: unknown): value is DbRunner;
 export declare function bindTenantDbRunner(tenantDb: TenantDb, runner: DbRunner): void;
 export declare function tenantDbRunner(tenantDb: TenantDb): DbRunner;
 export declare function denyTenantDbWrites(tenantDb: TenantDb, reason: string): void;
+export declare function tenantDbWritesDeniedReason(tenantDb: TenantDb): string | undefined;
 export declare function tenantDbWritesDeniedError(operation: string, reason: string): InternalError;
 export declare function tenantDbWriteRunner(tenantDb: TenantDb, operation: string): DbRunner;