@cosmicdrift/kumiko-framework 0.1.0

package/src/db/index.ts

@@ -0,0 +1,55 @@
+export { assertExistsIn } from "./assert-exists-in";
+export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
+export type { DbConnection, DbConnectionOptions, DbRow, DbRunner, DbTx } from "./connection";
+export { createDbConnection, dbConnectionOptionsFromEnv } from "./connection";
+export type { CursorQueryOptions, CursorResult } from "./cursor";
+export { applyCursorQuery, decodeCursor, encodeCursor } from "./cursor";
+export type { SelectQuery, TableColumns } from "./dialect";
+export {
+  boolean,
+  instant,
+  integer,
+  jsonb,
+  primaryKey,
+  serial,
+  table,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "./dialect";
+export type { EagerLoadEntityResolver, EagerloadedRow } from "./eagerload";
+export {
+  collectReferenceFields,
+  enrichRowWithReferences,
+  enrichWithReferences,
+} from "./eagerload";
+export type { EncryptionProvider } from "./encryption";
+export { createEncryptionProvider } from "./encryption";
+export type {
+  EntityLifecycleVerb,
+  EventStoreExecutor,
+  EventStoreExecutorOptions,
+} from "./event-store-executor";
+export { createEventStoreExecutor, entityEventName } from "./event-store-executor";
+export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp";
+export { flattenMoney, rehydrateMoney } from "./money";
+export {
+  constraintOf,
+  extractPgError,
+  isTableAlreadyExists,
+  isUniqueViolation,
+  type PgErrorInfo,
+} from "./pg-error";
+export { seedReferenceData } from "./reference-data";
+export { fetchOne } from "./row-helpers";
+export { tableExists } from "./schema-inspection";
+export {
+  buildBaseColumns,
+  buildDrizzleTable,
+  type DrizzleTable,
+  toSnakeCase,
+  toTableName,
+} from "./table-builder";
+export type { TenantDb, TenantDbMode } from "./tenant-db";
+export { castTenantRows, createTenantDb } from "./tenant-db";

package/src/db/located-timestamp.ts

@@ -0,0 +1,114 @@
+// Auto-Convert für locatedTimestamp-Felder im DB-Layer.
+//
+// Vertrag (siehe auch db/money.ts — gleicher Compound-Type-Pattern):
+//   API-Form:    { at, tz } | { utc, tz }
+//   DB-Form:     <name>Utc TIMESTAMPTZ + <name>Tz TEXT
+//   Read-Form:   { at, tz, utc }
+//
+// `at`-Default-Sicht beim Read: Pickup-Ort-lokal (utc projiziert in
+// gespeicherter tz). Server kennt User-TZ nicht — User-spezifische
+// Anzeige passiert client-seitig aus utc.
+
+import type { EntityDefinition } from "../engine/types";
+
+// Sprint F: <name>Utc-Spalte ist jetzt instant() (siehe dialect.ts) —
+// Drizzle gibt direkt Temporal.Instant zurück. Vor Sprint F kam ein PG-
+// Wire-Format-String "2026-04-15 09:00:00+00" rein der via String-Massage
+// zu ISO-8601 gemacht werden musste. Heute übernimmt der customType die
+// Konversion DB↔Instant — diese Funktion ist nur noch defensive Glue für
+// Legacy-Code-Pfade die noch Strings durchreichen (z.B. raw SQL).
+function toInstant(value: unknown): Temporal.Instant | undefined {
+  if (value instanceof Temporal.Instant) return value;
+  if (typeof value !== "string") return undefined;
+  const iso = value.includes("T") ? value : value.replace(" ", "T").replace(/\+00$/, "Z");
+  return Temporal.Instant.from(iso);
+}
+
+/**
+ * API → DB: locatedTimestamp-Felder zu zwei flachen Spalten flatten.
+ *
+ * - `{ at, tz }` (UI-Form) → `{ <name>Utc, <name>Tz }` (utc via Temporal berechnet)
+ * - `{ utc, tz }` (Server-Form) → utc gewinnt direkt
+ * - `{ at, tz, utc }` → utc gewinnt; at wird ignoriert (Konsistenz-Check ist
+ *   Caller-Verantwortung)
+ *
+ * Pure — mutiert nicht.
+ */
+export function flattenLocatedTimestamp(
+  payload: Record<string, unknown>,
+  entity: EntityDefinition,
+): Record<string, unknown> {
+  const T = Temporal;
+  const result: Record<string, unknown> = { ...payload };
+
+  for (const [name, field] of Object.entries(entity.fields)) {
+    if (field.type !== "locatedTimestamp") continue;
+
+    const raw = result[name];
+    if (raw === undefined || raw === null) continue;
+    if (typeof raw !== "object") {
+      throw new Error(
+        `flattenLocatedTimestamp: field "${name}" expects { at, tz } or { utc, tz } object, got ${typeof raw}`,
+      );
+    }
+    const pair = raw as { at?: string; tz?: string; utc?: string };
+
+    delete result[name];
+
+    if (pair.tz === undefined) continue;
+    const tz = pair.tz;
+    // Sprint F: <name>Utc-Spalte ist instant() — Drizzle erwartet
+    // Temporal.Instant. Konvertierung pair.utc-string → Instant geht via
+    // toInstant() (kennt String + Instant); pair.at + tz → Instant via
+    // Temporal-Math.
+    const instant: Temporal.Instant | undefined =
+      pair.utc !== undefined
+        ? toInstant(pair.utc)
+        : pair.at !== undefined
+          ? T.PlainDateTime.from(pair.at).toZonedDateTime(tz).toInstant()
+          : undefined;
+    if (instant === undefined) continue;
+
+    result[`${name}Utc`] = instant;
+    result[`${name}Tz`] = tz;
+  }
+
+  return result;
+}
+
+/**
+ * DB → API: zwei flache Spalten zu combined { at, tz, utc } rehydraten.
+ *
+ * `at` ist immer Wall-Clock in der gespeicherten `tz` (Pickup-Ort-lokal).
+ * Wer User-Sicht braucht, leitet aus `utc` selbst ab — der Server kennt
+ * keine User-TZ.
+ *
+ * Pure — mutiert nicht.
+ */
+export function rehydrateLocatedTimestamp(
+  row: Record<string, unknown>,
+  entity: EntityDefinition,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...row };
+
+  for (const [name, field] of Object.entries(entity.fields)) {
+    if (field.type !== "locatedTimestamp") continue;
+
+    const utcRaw = result[`${name}Utc`];
+    const tzRaw = result[`${name}Tz`];
+
+    delete result[`${name}Utc`];
+    delete result[`${name}Tz`];
+
+    if (typeof tzRaw !== "string") continue;
+    const utcInstant = toInstant(utcRaw);
+    if (utcInstant === undefined) continue;
+
+    const localZdt = utcInstant.toZonedDateTimeISO(tzRaw);
+    const at = localZdt.toPlainDateTime().toString();
+
+    result[name] = { at, tz: tzRaw, utc: utcInstant.toString() };
+  }
+
+  return result;
+}

package/src/db/money.ts

@@ -0,0 +1,120 @@
+// Auto-Convert für money-Felder im DB-Layer.
+//
+// Vertrag (siehe auch db/located-timestamp.ts — gleicher Compound-Type-Pattern):
+//   API-Form:    { amount, currency } | number (permissiv für Legacy)
+//   DB-Form:     <name> BIGINT + <name>Currency TEXT
+//   Read-Form:   { amount, currency }
+//
+// Permissiv-Insert: primitive number wird als amount akzeptiert (Legacy aus
+// pre-Stufe-3-Samples). Currency fällt dann auf entity.defaultCurrency
+// zurück (oder DEFAULT_CURRENCIES[0] = "EUR" als Framework-Fallback).
+//
+// Anders als locatedTimestamp behalten wir den Field-Namen `<name>` als
+// amount-Spalte (Legacy DB-Convention für Money — `SUM(buying_price)` bleibt
+// idiomatisch). `<name>Currency` ist die zusätzliche Spalte.
+
+import type { EntityDefinition } from "../engine/types";
+import { DEFAULT_CURRENCIES } from "../engine/types";
+
+const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
+
+/**
+ * API → DB: money-Felder zu zwei flachen Spalten flatten.
+ *
+ * - `{ amount, currency }` → `{ <name>: amount, <name>Currency: currency }`
+ * - `number` (legacy) → `{ <name>: number, <name>Currency: defaultCurrency }`
+ *
+ * Pure — mutiert nicht.
+ */
+export function flattenMoney(
+  payload: Record<string, unknown>,
+  entity: EntityDefinition,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...payload };
+  const fallbackCurrency = entity.defaultCurrency ?? FRAMEWORK_DEFAULT_CURRENCY;
+
+  for (const [name, field] of Object.entries(entity.fields)) {
+    if (field.type !== "money") continue;
+
+    const raw = result[name];
+    if (raw === undefined || raw === null) continue;
+
+    let amount: number;
+    let currency: string;
+
+    if (typeof raw === "object" && "amount" in raw) {
+      const pair = raw as { amount: number; currency?: string };
+      amount = pair.amount;
+      currency = pair.currency ?? fallbackCurrency;
+    } else if (typeof raw === "number") {
+      amount = raw;
+      // Expliziter currency-key im Payload überschreibt den Default-Fallback.
+      const explicitCurrency = result[`${name}Currency`];
+      currency = typeof explicitCurrency === "string" ? explicitCurrency : fallbackCurrency;
+    } else {
+      throw new Error(
+        `flattenMoney: field "${name}" expects { amount, currency } object or number, got ${typeof raw}`,
+      );
+    }
+
+    delete result[name];
+    result[name] = amount;
+    result[`${name}Currency`] = currency;
+  }
+
+  return result;
+}
+
+/**
+ * DB → API: zwei flache Spalten zu combined { amount, currency } rehydraten.
+ *
+ * Wirft loud bei korrupter DB-Form (string das nicht zur Zahl wird) — silent
+ * data-loss wäre Bug-Vektor. NULL/undefined amount → field aus Output entfernt.
+ *
+ * Pure — mutiert nicht.
+ */
+export function rehydrateMoney(
+  row: Record<string, unknown>,
+  entity: EntityDefinition,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...row };
+  const fallbackCurrency = entity.defaultCurrency ?? FRAMEWORK_DEFAULT_CURRENCY;
+
+  for (const [name, field] of Object.entries(entity.fields)) {
+    if (field.type !== "money") continue;
+
+    const amountRaw = result[name];
+    const currencyRaw = result[`${name}Currency`];
+
+    delete result[`${name}Currency`];
+
+    if (amountRaw === null || amountRaw === undefined) {
+      delete result[name];
+      continue;
+    }
+
+    let amount: number;
+    if (typeof amountRaw === "number") {
+      amount = amountRaw;
+    } else if (typeof amountRaw === "string" && amountRaw !== "") {
+      // PG-driver liefert BIGINT manchmal als String (>2^53 sicher).
+      amount = Number(amountRaw);
+      if (Number.isNaN(amount)) {
+        throw new Error(
+          `rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a number — DB corruption?`,
+        );
+      }
+    } else {
+      throw new Error(
+        `rehydrateMoney: field "${name}" amount has unexpected type ${typeof amountRaw}`,
+      );
+    }
+
+    const currency =
+      typeof currencyRaw === "string" && currencyRaw !== "" ? currencyRaw : fallbackCurrency;
+
+    result[name] = { amount, currency };
+  }
+
+  return result;
+}

package/src/db/pg-error.ts

@@ -0,0 +1,46 @@
+// Drizzle wraps postgres-js errors in `DrizzleQueryError`; the original PG
+// error (with SQLSTATE `code` and `constraint_name`) lives in `.cause`. We
+// unwrap both layers so callers don't have to know which layer produced the
+// error. Used by the event-store to distinguish a unique-violation on the
+// aggregate-version index (optimistic-concurrency conflict) from the one on
+// the request-id idempotency index (replay signal).
+
+export type PgErrorInfo = {
+  readonly code: string | undefined;
+  readonly constraint_name: string | undefined;
+};
+
+export function extractPgError(e: unknown): PgErrorInfo | null {
+  if (typeof e !== "object" || e === null) return null;
+  const layers: unknown[] = [e];
+  // @cast-boundary error-details — DrizzleQueryError wraps PG-error in .cause
+  const cause = (e as { cause?: unknown }).cause;
+  if (typeof cause === "object" && cause !== null) layers.push(cause);
+
+  for (const layer of layers) {
+    // @cast-boundary error-details — postgres-js error shape (code, constraint_name)
+    const code = (layer as { code?: string }).code;
+    const constraintName = (layer as { constraint_name?: string }).constraint_name;
+    if (code !== undefined || constraintName !== undefined) {
+      return { code, constraint_name: constraintName };
+    }
+  }
+  return null;
+}
+
+export function isUniqueViolation(e: unknown): boolean {
+  return extractPgError(e)?.code === "23505";
+}
+
+// PG SQLSTATE 42P07 — "relation already exists". Raised when CREATE
+// TABLE (or drizzle-kit's generated equivalent) runs against a table
+// that's already been created. Useful for idempotent boot-paths like
+// the dev-server, where a persistent DB carries the table over from
+// the previous restart.
+export function isTableAlreadyExists(e: unknown): boolean {
+  return extractPgError(e)?.code === "42P07";
+}
+
+export function constraintOf(e: unknown): string | undefined {
+  return extractPgError(e)?.constraint_name;
+}

package/src/db/reference-data.ts

@@ -0,0 +1,77 @@
+import { eq } from "drizzle-orm";
+import type { ReferenceDataDef } from "../engine/types";
+import { SYSTEM_TENANT_ID } from "../engine/types";
+import type { DbConnection, DbRow } from "./connection";
+import type { TableColumns } from "./dialect";
+import { toSnakeCase } from "./table-builder";
+
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic tables
+type Table = TableColumns<any>;
+
+/**
+ * Seed reference data at boot time.
+ * For each ReferenceDataDef: upsert rows (insert missing, update changed, never delete).
+ * Upsert key defaults to the first field in the data object.
+ */
+export async function seedReferenceData(
+  defs: readonly ReferenceDataDef[],
+  tables: ReadonlyMap<string, Table>,
+  db: DbConnection,
+): Promise<{ inserted: number; updated: number }> {
+  let inserted = 0;
+  let updated = 0;
+
+  for (const def of defs) {
+    const table = tables.get(def.entityName);
+    if (!table) continue;
+    if (def.data.length === 0) continue;
+
+    const firstRow = def.data[0];
+    if (!firstRow) continue;
+    const firstKey = Object.keys(firstRow)[0];
+    if (!firstKey) continue;
+    const upsertKey = def.upsertKey ?? firstKey;
+    const snakeKey = toSnakeCase(upsertKey);
+
+    for (const row of def.data) {
+      const keyValue = row[upsertKey];
+      if (keyValue === undefined) continue;
+
+      // Check if row exists
+      const [existing] = await db
+        .select()
+        .from(table)
+        .where(eq(table[upsertKey] ?? table[snakeKey], keyValue))
+        .limit(1);
+
+      if (existing) {
+        // Update if any field changed
+        const existingData = existing as DbRow;
+        const changes: Record<string, unknown> = {};
+        for (const [field, value] of Object.entries(row)) {
+          if (field === upsertKey) continue;
+          if (existingData[field] !== value) {
+            changes[field] = value;
+          }
+        }
+        if (Object.keys(changes).length > 0) {
+          await db
+            .update(table)
+            .set(changes)
+            .where(eq(table[upsertKey] ?? table[snakeKey], keyValue));
+          updated++;
+        }
+      } else {
+        await db.insert(table).values({
+          ...row,
+          tenantId: SYSTEM_TENANT_ID,
+          version: 1,
+          insertedAt: Temporal.Now.instant(),
+        });
+        inserted++;
+      }
+    }
+  }
+
+  return { inserted, updated };
+}

package/src/db/row-helpers.ts

@@ -0,0 +1,53 @@
+import { and, type SQL } from "drizzle-orm";
+import type { DbRow } from "./connection";
+import type { TableColumns } from "./dialect";
+
+// biome-ignore lint/suspicious/noExplicitAny: Mirrors the erased ProjectionTable / event-store-executor pattern — the framework doesn't know user column shapes.
+type AnyTable = TableColumns<any>;
+
+// Minimal DB surface fetchOne uses — structurally satisfied by raw DbRunner
+// (connection / tx) AND TenantDb (tenant-scoped wrapper). Both expose the
+// same `select().from().where().limit()` chain with compatible rows, so the
+// helper types against the shared shape instead of a union that TS can't
+// narrow cleanly.
+type SelectChainDb = {
+  select: () => {
+    from: (table: AnyTable) => {
+      where: (cond: SQL | undefined) => {
+        limit: (n: number) => PromiseLike<readonly Record<string, unknown>[]>;
+      };
+    };
+  };
+};
+
+// SELECT * FROM <table> WHERE <...conditions> LIMIT 1 → first row or undefined.
+// Collapses the "const [row] = await db.select()...limit(1)" destructure
+// that repeats in every detail-query-style handler and existence-check.
+//
+// Conditions are variadic and non-empty — the tuple `[SQL, ...SQL[]]` rejects
+// `fetchOne(db, table)` (would silently pick any row) and `fetchOne(db, table,
+// undefined)` (would do the same) at compile time. Multiple conditions are
+// combined with AND.
+//
+//   const existing = await fetchOne<{ id: number }>(db, userTable,
+//     eq(userTable.email, payload.email));
+//   if (existing) return writeFailure(new ConflictError({ ... }));
+//
+//   const row = await fetchOne(db, membershipTable,
+//     eq(membershipTable.userId, userId),
+//     eq(membershipTable.tenantId, tenantId),
+//   );
+//
+// For dynamic condition arrays (length known only at runtime), spread
+// explicitly: `fetchOne(db, table, first, ...rest)`. Raw `...arr` with
+// `arr: SQL[]` won't type-check because TS can't prove the array is non-
+// empty — a feature, not a bug.
+export async function fetchOne<TRow = DbRow>(
+  db: SelectChainDb,
+  table: AnyTable,
+  ...conditions: readonly [SQL, ...SQL[]]
+): Promise<TRow | undefined> {
+  const where = conditions.length === 1 ? conditions[0] : and(...conditions);
+  const rows = await db.select().from(table).where(where).limit(1);
+  return rows[0] as TRow | undefined;
+}

package/src/db/schema-inspection.ts

@@ -0,0 +1,25 @@
+import { sql } from "drizzle-orm";
+import type { DbConnection, DbTx } from "./connection";
+
+// True when `<fullyQualifiedName>` refers to an existing relation in the
+// current database. Thin wrapper over `to_regclass`, which returns NULL
+// when the name doesn't resolve — the only postgres query that cheaply
+// reports existence without raising an error on a missing relation.
+//
+// Used by framework-managed tables (events, archived_streams, snapshots,
+// projections, event-consumers) whose createX() is called from multiple
+// boot paths (setupTestStack, production boot, manual test setups). The
+// guard keeps those calls idempotent without having to interpret the
+// "already exists" error code.
+//
+//   if (await tableExists(db, "public.events")) return;
+//   await pushTables(db, { events: eventsTable });
+export async function tableExists(
+  db: DbConnection | DbTx,
+  fullyQualifiedName: string,
+): Promise<boolean> {
+  const rows = await db.execute<{ exists: boolean }>(
+    sql`SELECT to_regclass(${fullyQualifiedName}) IS NOT NULL AS exists`,
+  );
+  return rows[0]?.exists ?? false;
+}