@cosmicdrift/kumiko-framework 0.1.0

package/src/db/__tests__/unique-violation-mapping.integration.ts

@@ -0,0 +1,166 @@
+// F8 — pg-unique-violation auf entity-level-Indices wird sauber zu
+// einer 409 UniqueViolationError gemapped, NICHT zu einer 500
+// InternalError.
+//
+// Der event-store-Layer hatte das schon (Sprint 4d Patch:
+// EventStoreVersionConflict-catch im executor.create/update). Aber
+// app-level unique-Indices auf der Projection-Tabelle (z.B. (tenantId,
+// email) auf User-Entity) liefen ohne mapping durch — krachten als
+// pg-23505 InternalError. F8 schließt diese Lücke.
+//
+// **Test-Setup:** ein User-style entity mit composite-unique-Index
+// (tenantId, email). Aggregate-id ist auto-generated UUID, kollidiert
+// also nicht. Erst die projection-INSERT verletzt den Index. Ohne F8:
+// 500. Mit F8: writeFailure(UniqueViolationError) → 409.
+
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createEntity, createTextField } from "../../engine";
+import { createEventsTable } from "../../event-store";
+import { createEntityTable, createTestDb, type TestDb, TestUsers } from "../../stack";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { buildDrizzleTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const userEntity = createEntity({
+  table: "read_unique_users",
+  fields: {
+    email: createTextField({ required: true }),
+    displayName: createTextField({ required: true }),
+  },
+  // softDelete=true damit wir den restore-Pfad pinnen können (siehe
+  // restore-Test unten — "kein 23505 möglich" claim).
+  softDelete: true,
+  // Composite-unique auf (tenantId, email) — typisches User-Pattern.
+  // Der unique-Index lebt auf der Projection, NICHT auf der events-
+  // Tabelle. Daher fängt der existing event-store-23505-catch (Sprint
+  // 4d) das nicht; das ist der Pfad den F8 abdeckt.
+  indexes: [
+    { columns: ["tenantId", "email"], unique: true, name: "read_unique_users_tenant_email_uniq" },
+  ],
+});
+const table = buildDrizzleTable("unique-user", userEntity);
+const exec = createEventStoreExecutor(table, userEntity, { entityName: "unique-user" });
+
+let testDb: TestDb;
+let tdb: TenantDb;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEntityTable(testDb.db, userEntity, "unique-user");
+  await createEventsTable(testDb.db);
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(sql`TRUNCATE kumiko_events, read_unique_users RESTART IDENTITY CASCADE`);
+});
+
+// =============================================================================
+// create — duplicate email → 409 unique_violation
+// =============================================================================
+
+describe("F8 — entity-level unique-violation auf create", () => {
+  test("zweiter create mit selber email → unique_violation 409 (nicht internal_error 500)", async () => {
+    const first = await exec.create(
+      { email: "alice@example.com", displayName: "Alice 1" },
+      admin,
+      tdb,
+    );
+    expect(first.isSuccess).toBe(true);
+
+    const second = await exec.create(
+      { email: "alice@example.com", displayName: "Alice 2" },
+      admin,
+      tdb,
+    );
+    expect(second.isSuccess).toBe(false);
+    if (second.isSuccess) return;
+    expect(second.error.code).toBe("unique_violation");
+    expect(second.error.httpStatus).toBe(409);
+    // constraintName aus dem PG-error durchgereicht — App-Code kann
+    // damit auf den richtigen field-name mappen.
+    const details = second.error.details as { constraintName?: string; entityName?: string };
+    expect(details.entityName).toBe("unique-user");
+    expect(details.constraintName).toBe("read_unique_users_tenant_email_uniq");
+  });
+
+  test("DB-Beweis: nach 23505-conflict ist nur die erste Row in der Projection", async () => {
+    await exec.create({ email: "bob@example.com", displayName: "Bob 1" }, admin, tdb);
+    const second = await exec.create(
+      { email: "bob@example.com", displayName: "Bob 2" },
+      admin,
+      tdb,
+    );
+    expect(second.isSuccess).toBe(false);
+    const rows = await testDb.db.select().from(table);
+    expect(rows).toHaveLength(1);
+    expect((rows[0] as { displayName: string }).displayName).toBe("Bob 1");
+  });
+});
+
+// =============================================================================
+// update — change email to existing value → 409 unique_violation
+// =============================================================================
+
+describe("F8 — entity-level unique-violation auf update", () => {
+  test("update auf existing email-value → unique_violation 409", async () => {
+    const alice = await exec.create(
+      { email: "alice@example.com", displayName: "Alice" },
+      admin,
+      tdb,
+    );
+    const bob = await exec.create({ email: "bob@example.com", displayName: "Bob" }, admin, tdb);
+    if (!alice.isSuccess || !bob.isSuccess) throw new Error("create failed in setup");
+
+    // Bob versucht Alice's email zu nehmen → kollidiert mit dem
+    // existing alice-row. Vor F8 wäre das ein internal_error 500
+    // gewesen.
+    const conflict = await exec.update(
+      { id: bob.data.id, version: 1, changes: { email: "alice@example.com" } },
+      admin,
+      tdb,
+    );
+    expect(conflict.isSuccess).toBe(false);
+    if (conflict.isSuccess) return;
+    expect(conflict.error.code).toBe("unique_violation");
+    expect(conflict.error.httpStatus).toBe(409);
+  });
+});
+
+// =============================================================================
+// restore — kein try-catch nötig (drift-pin: dokumentiert die Annahme)
+// =============================================================================
+
+describe("F8 — restore touch'd nur isDeleted, kein 23505-Pfad", () => {
+  test("restore einer soft-gedeleteten row mit unique-field läuft konfliktfrei durch", async () => {
+    // Audit-Annahme (advisor-Punkt verifiziert): restore mutiert nur
+    // isDeleted=false, kein unique-field-Touch. Der unique-Index ist
+    // global (kein partial-WHERE-NOT-isDeleted in framework's table-
+    // builder), also würde EIN paralleler create mit derselben email
+    // schon am unique-Index scheitern (F8-create-Pfad), bevor er den
+    // soft-deleted restore-Pfad konfliktfrei machen könnte.
+    //
+    // Dieser Test pinnt: restore allein wirft kein 23505. Wenn jemand
+    // morgen einen Pfad einbaut der restore mit field-changes
+    // kombiniert, fällt's hier auf — der Test war "soll konfliktfrei
+    // sein", die Annahme wird laut.
+    const alice = await exec.create(
+      { email: "carol@example.com", displayName: "Carol" },
+      admin,
+      tdb,
+    );
+    if (!alice.isSuccess) throw new Error("create failed in setup");
+
+    const deleted = await exec.delete({ id: alice.data.id }, admin, tdb);
+    expect(deleted.isSuccess).toBe(true);
+
+    const restored = await exec.restore({ id: alice.data.id }, admin, tdb);
+    expect(restored.isSuccess).toBe(true);
+  });
+});

package/src/db/apply-entity-event.ts

@@ -0,0 +1,188 @@
+// applyEntityEvent — die EINZIGE Schreib-Logik für r.entity-Tabellen aus
+// Stored-Events. Beide Aufrufer benutzen sie:
+//
+//   - createEventStoreExecutor (live, im Write-TX) — übergibt ein
+//     "live event" mit unstripped flatData/flatChanges als payload damit
+//     sensitive Felder in der Read-Tabelle landen, das Event-Log selbst
+//     bleibt aber stripped (siehe append-Site im Executor).
+//   - rebuildProjection via ImplicitProjection (replay, im Rebuild-TX) —
+//     übergibt das StoredEvent direkt; payload ist dort ohne sensitive,
+//     was bei Rebuild akzeptiert wird (sensitive-Drift durch GDPR-Strip
+//     ist als load-bearing Backlog-Item gepinnt — siehe
+//     docs/plans/architecture/migrations.md Sektion "Backlog (Welle 3+)"
+//     → "Sensitive-Field-Persistenz im Rebuild" für Optionen a/b/c).
+//
+// Live==Rebuild-Equivalence ist damit by-construction für alle Felder
+// die NICHT als sensitive markiert sind — eine geänderte Schreib-Logik
+// muss nur an EINER Stelle gepflegt werden, kein Sync-Contract mehr.
+// Der load-bearing Test bleibt für non-sensitive-Drift in
+// db/__tests__/implicit-projection-equivalence.integration.ts.
+//
+// Tenant-Isolation: applyEntityEvent erwartet einen rohen DbRunner (TX
+// oder pool), KEINEN TenantDb-Wrapper. Schutz kommt aus zwei Quellen:
+//   1. Live-Pfad ruft VOR der Schreibung loadById (tenant-scoped) für
+//      update/delete/restore — die aggregateId ist also schon tenant-
+//      validiert bevor wir hier ankommen.
+//   2. Bei create wird tenantId explizit aus event.tenantId gesetzt, also
+//      nie über den TenantDb-Wrapper-Default abgeleitet.
+// Damit ist der TenantDb-Wrapper-Loss in dieser Funktion funktional ohne
+// Sicherheitslücke.
+//
+// Auto-Verben:
+//   <entity>.created   → INSERT
+//   <entity>.updated   → UPDATE WHERE id=aggregateId
+//   <entity>.deleted   → soft-delete-UPDATE wenn entity.softDelete, sonst hard-DELETE
+//   <entity>.restored  → undelete-UPDATE (nur bei softDelete sinnvoll)
+//
+// Domain-Events (r.defineEvent) auf demselben Aggregate werden hier NICHT
+// behandelt — die liefen im Live-Pfad nie durch den Executor und müssen
+// von expliziten r.projection-apply-Handlern oder r.multiStreamProjection
+// behandelt werden. ImplicitProjection registriert daher nur die 4
+// Auto-Verben.
+//
+// Return-Shape: ApplyResult mit `kind` + optionaler `row`.
+//   - "applied" → Schreibung lief durch. `row` enthält die geschriebene
+//     Row für create/update/soft-delete/restore. Bei hard-delete ist
+//     `row` null (DELETE-Statements geben keine returning-Row her).
+//   - "skipped" → Event ist kein Auto-Verb (Domain-Event auf demselben
+//     Aggregate). Caller no-op.
+
+import { eq } from "drizzle-orm";
+import type { EntityDefinition } from "../engine/types";
+import { InternalError } from "../errors";
+import type { StoredEvent } from "../event-store";
+import type { DbRow, DbRunner } from "./connection";
+import type { TableColumns } from "./dialect";
+
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle-Tabellen sind generisch typed; framework code erasiert die Spalten-Union absichtlich.
+type Table = TableColumns<any>;
+
+export type AutoVerb = "created" | "updated" | "deleted" | "restored";
+
+export type ApplyResult =
+  | { readonly kind: "applied"; readonly verb: AutoVerb; readonly row: DbRow | null }
+  | { readonly kind: "skipped" };
+
+/** Parsed event.type → AutoVerb wenn das Event eines der 4 Auto-Verben
+ *  auf dem gegebenen Aggregate ist. null sonst (Domain-Event). */
+export function parseAutoVerb(event: StoredEvent): AutoVerb | null {
+  const prefix = `${event.aggregateType}.`;
+  if (!event.type.startsWith(prefix)) return null;
+  const verb = event.type.slice(prefix.length);
+  if (verb === "created" || verb === "updated" || verb === "deleted" || verb === "restored") {
+    return verb;
+  }
+  return null;
+}
+
+/** Idempotente Anwendung eines Auto-Events auf die Entity-Tabelle.
+ *  Wird sowohl beim Live-Append (innerhalb der Write-TX) als auch beim
+ *  Rebuild (innerhalb der Rebuild-TX) gerufen — identische Logik. */
+export async function applyEntityEvent(
+  event: StoredEvent,
+  table: Table,
+  entity: EntityDefinition,
+  tx: DbRunner,
+): Promise<ApplyResult> {
+  const verb = parseAutoVerb(event);
+  if (verb === null) return { kind: "skipped" };
+  const softDelete = entity.softDelete ?? false;
+
+  switch (verb) {
+    case "created": {
+      // tenantId-Resolution explizit, nicht via Spread-Reihenfolge:
+      // Live-Pfad nutzt tx=db.raw (kein TenantDb-Wrapper-Auto-Inject),
+      // beim Replay erst recht keiner. Default = event.tenantId; payload
+      // gewinnt NUR wenn gültig string mit length > 0 (seedTenantMembership-
+      // Pfad: Operator schreibt im Ziel-Tenant, Event im Operator-Tenant).
+      // Pinst durch db/__tests__/apply-entity-event-tenant.integration.ts.
+      //
+      // Fail-loud wenn payload.tenantId gesetzt aber invalid (leer/null/
+      // non-string): das ist tenant-isolation-kritisch — silent fallback
+      // auf event.tenantId würde eine Bug-payload in den Operator-Tenant
+      // schreiben statt zu failen, was Cross-Tenant-Datendrift erzeugt.
+      const payloadTenantId = event.payload["tenantId"];
+      let tenantId: string;
+      if (payloadTenantId === undefined) {
+        tenantId = event.tenantId;
+      } else if (typeof payloadTenantId === "string" && payloadTenantId.length > 0) {
+        tenantId = payloadTenantId;
+      } else {
+        throw new InternalError({
+          message: `applyEntityEvent: payload.tenantId set but invalid (${JSON.stringify(payloadTenantId)}). Tenant-isolation-kritisch: silent fallback auf event.tenantId würde Cross-Tenant-Drift erzeugen.`,
+        });
+      }
+      const [row] = await tx
+        .insert(table)
+        .values({
+          ...event.payload,
+          tenantId,
+          id: event.aggregateId,
+          version: event.version,
+          insertedAt: event.createdAt,
+          insertedById: event.createdBy,
+        })
+        .returning();
+      return { kind: "applied", verb, row: (row as DbRow | undefined) ?? null };
+    }
+
+    case "updated": {
+      // payload-Shape: { changes, previous } — siehe event-store-executor.ts.
+      const changes = (event.payload["changes"] ?? {}) as Record<string, unknown>; // @cast-boundary engine-payload
+      const [row] = await tx
+        .update(table)
+        .set({
+          ...changes,
+          version: event.version,
+          modifiedAt: event.createdAt,
+          modifiedById: event.createdBy,
+        })
+        .where(eq(table["id"], event.aggregateId))
+        .returning();
+      return { kind: "applied", verb, row: (row as DbRow | undefined) ?? null };
+    }
+
+    case "deleted": {
+      if (softDelete) {
+        const [row] = await tx
+          .update(table)
+          .set({
+            isDeleted: true,
+            deletedAt: event.createdAt,
+            deletedById: event.createdBy,
+            version: event.version,
+            modifiedAt: event.createdAt,
+            modifiedById: event.createdBy,
+          })
+          .where(eq(table["id"], event.aggregateId))
+          .returning();
+        return { kind: "applied", verb, row: (row as DbRow | undefined) ?? null };
+      }
+      // Hard-Delete: DELETE-Statement gibt keine returning-Row her und
+      // der Live-Pfad nutzt eh `existing` (pre-delete-Snapshot) für die
+      // Response. Beim Replay ist das fine, der Caller braucht die Row
+      // nicht weiter.
+      await tx.delete(table).where(eq(table["id"], event.aggregateId));
+      return { kind: "applied", verb, row: null };
+    }
+
+    case "restored": {
+      // Restore ist nur bei softDelete sinnvoll. Hard-Delete-Entities sollten
+      // keine restored-Events erhalten — falls doch, defensive skip.
+      if (!softDelete) return { kind: "skipped" };
+      const [row] = await tx
+        .update(table)
+        .set({
+          isDeleted: false,
+          deletedAt: null,
+          deletedById: null,
+          version: event.version,
+          modifiedAt: event.createdAt,
+          modifiedById: event.createdBy,
+        })
+        .where(eq(table["id"], event.aggregateId))
+        .returning();
+      return { kind: "applied", verb, row: (row as DbRow | undefined) ?? null };
+    }
+  }
+}

package/src/db/assert-exists-in.ts

@@ -0,0 +1,59 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { and, eq, type SQL } from "drizzle-orm";
+import { NotFoundError } from "../errors";
+import type { DbConnection } from "./connection";
+import type { TenantDb } from "./tenant-db";
+
+/**
+ * Generic constraint helper: asserts a value exists in a table.
+ * Returns a ready-to-return NotFoundError when the row is missing, or null
+ * when it exists. Callers typically use it with writeFailure:
+ *
+ *   const missing = await assertExistsIn(db, orderTable, { field: "id", value: id });
+ *   if (missing) return writeFailure(missing);
+ *
+ * Accepts both DbConnection and TenantDb. When using TenantDb, the automatic
+ * tenant filter is applied. Use tenantId option for explicit tenant filtering
+ * on raw DbConnection.
+ */
+export async function assertExistsIn(
+  db: DbConnection | TenantDb,
+  // biome-ignore lint/suspicious/noExplicitAny: Drizzle table types are dynamic
+  entity: any,
+  options: {
+    field: string;
+    value: unknown;
+    tenantId?: TenantId;
+    where?: Record<string, unknown>;
+    entityName?: string;
+  },
+): Promise<NotFoundError | null> {
+  const conditions = [eq(entity[options.field], options.value)];
+
+  if (options.tenantId !== undefined) {
+    conditions.push(eq(entity["tenantId"], options.tenantId));
+  }
+
+  if (options.where) {
+    for (const [key, val] of Object.entries(options.where)) {
+      conditions.push(eq(entity[key], val));
+    }
+  }
+
+  const [row] = await db
+    .select()
+    .from(entity)
+    .where(and(...conditions) as SQL);
+
+  if (!row) {
+    const entityName = options.entityName ?? String(options.field).replace(/Id$/, "");
+    return new NotFoundError(
+      entityName,
+      typeof options.value === "number" || typeof options.value === "string"
+        ? options.value
+        : undefined,
+    );
+  }
+
+  return null;
+}

package/src/db/compound-types.ts

@@ -0,0 +1,47 @@
+// Compound-Type Pipeline für den Executor.
+//
+// Ein Compound-Type ist ein Field das aus EINEM API-Object und MEHREREN
+// DB-Spalten besteht. Beispiele:
+//   - locatedTimestamp: { at, tz, utc } ↔ <name>Utc + <name>Tz
+//   - money: { amount, currency } ↔ <name> + <name>Currency
+//   - (kommt) address: { street, zip, city } ↔ <name>Street + <name>Zip + <name>City
+//
+// Statt jeden Helper im Executor an 4 Stellen verschachtelt aufzurufen,
+// pipeline-iert diese Funktion alle Compound-Type-Konvertierungen in
+// einem Pass. Beim Hinzufügen eines neuen Compound-Types nur EINE Stelle
+// erweitern (das Array hier), nicht alle Executor-Aufrufe.
+
+import type { EntityDefinition } from "../engine/types";
+import { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp";
+import { flattenMoney, rehydrateMoney } from "./money";
+
+type Converter = (
+  payload: Record<string, unknown>,
+  entity: EntityDefinition,
+) => Record<string, unknown>;
+
+// Reihenfolge ist egal solange die Konverter sich nicht gegenseitig
+// überlappen (z.B. money darf nicht ein Feld berühren das locatedTimestamp
+// schon erzeugt hat). Aktuell überlappen sie nicht — types sind disjunkt.
+const FLATTENERS: readonly Converter[] = [flattenLocatedTimestamp, flattenMoney];
+const REHYDRATORS: readonly Converter[] = [rehydrateLocatedTimestamp, rehydrateMoney];
+
+/**
+ * API-Form (combined) → DB-Form (flat). Wird vor jedem Insert/Update aufgerufen.
+ */
+export function flattenCompoundTypes(
+  payload: Record<string, unknown>,
+  entity: EntityDefinition,
+): Record<string, unknown> {
+  return FLATTENERS.reduce((acc, fn) => fn(acc, entity), payload);
+}
+
+/**
+ * DB-Form (flat) → API-Form (combined). Wird nach jedem Read aufgerufen.
+ */
+export function rehydrateCompoundTypes(
+  row: Record<string, unknown>,
+  entity: EntityDefinition,
+): Record<string, unknown> {
+  return REHYDRATORS.reduce((acc, fn) => fn(acc, entity), row);
+}

package/src/db/connection.ts

@@ -0,0 +1,104 @@
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import { readPositiveIntEnv } from "../utils/env-parse";
+
+export type DbConnection = ReturnType<typeof drizzle>;
+
+// Drizzle's transaction callback receives a tx handle with the same query API
+// as the top-level DbConnection. Extracted via Parameters so we stay in sync
+// with whatever Drizzle defines without hard-coding the internal type name.
+export type DbTx = Parameters<Parameters<DbConnection["transaction"]>[0]>[0];
+
+// Code paths that operate on either a connection or an active transaction
+// (e.g. TenantDb, dispatcher pipeline) accept both.
+export type DbRunner = DbConnection | DbTx;
+
+// Dynamic Drizzle tables (buildDrizzleTable with `any` column schema) lose
+// their per-column types at the Drizzle boundary. Query results come back as
+// arbitrary records. `DbRow` marks those typing-loss sites so readers see the
+// limitation without re-spelling `Record<string, unknown>` at every callsite.
+// Use `DbRow` for rows read via dynamic tables; a concrete entity-row type
+// is preferred whenever the table is statically typed.
+export type DbRow = Record<string, unknown>;
+
+// The raw postgres.js client. Exposed alongside the Drizzle wrapper so the
+// event-dispatcher (or other components that need LISTEN / pg-specific
+// features Drizzle doesn't surface) can subscribe without re-opening a
+// connection from the URL.
+export type PgClient = ReturnType<typeof postgres>;
+
+// Connection-pool options — thin wrapper around the postgres.js fields the
+// framework explicitly supports. Omitted keys fall back to postgres.js
+// defaults (max=10, idle_timeout=PGIDLE_TIMEOUT env, connect_timeout=
+// PGCONNECT_TIMEOUT env). See `docs/plans/architecture/scaling.md` for
+// sizing guidance per deployment shape.
+export type DbConnectionOptions = {
+  // Max concurrent connections in the pool. postgres.js defaults to 10 —
+  // fine for a single app process against a small DB. Multi-worker or
+  // high-concurrency API deploys should scale this with `num_workers *
+  // per-request-concurrency` and stay below the DB's own max_connections
+  // (typical managed postgres: 100–400).
+  readonly maxConnections?: number;
+  // Seconds before an idle connection is closed. Null/undefined → keep
+  // connections warm forever (postgres.js default when the env var is
+  // unset). Managed pgBouncer tiers usually want this explicitly set to
+  // something like 30–60 so a single burst doesn't hold connections
+  // indefinitely.
+  readonly idleTimeoutSeconds?: number;
+  // Seconds to wait while establishing a new connection. Fails the query
+  // with a timeout error rather than hanging indefinitely when the DB is
+  // unreachable — critical for `/health/ready` to actually flip to 503
+  // within its 2s probe budget.
+  readonly connectTimeoutSeconds?: number;
+};
+
+export function createDbConnection(
+  url: string,
+  options: DbConnectionOptions = {},
+): {
+  db: DbConnection;
+  client: PgClient;
+  close: () => Promise<void>;
+} {
+  // Only forward fields the caller set — empty object otherwise preserves
+  // postgres.js's env-var-driven defaults (PGIDLE_TIMEOUT / PGCONNECT_TIMEOUT).
+  const pgOptions: Parameters<typeof postgres>[1] = {};
+  if (options.maxConnections !== undefined) pgOptions.max = options.maxConnections;
+  if (options.idleTimeoutSeconds !== undefined) pgOptions.idle_timeout = options.idleTimeoutSeconds;
+  if (options.connectTimeoutSeconds !== undefined) {
+    pgOptions.connect_timeout = options.connectTimeoutSeconds;
+  }
+
+  const client = postgres(url, pgOptions);
+  const db = drizzle(client);
+
+  return {
+    db,
+    client,
+    close: async () => {
+      await client.end();
+    },
+  };
+}
+
+// Parse the supported env vars into a DbConnectionOptions object. Useful
+// for a main.ts that wants to read DATABASE_POOL_MAX / DATABASE_POOL_
+// IDLE_TIMEOUT / DATABASE_POOL_CONNECT_TIMEOUT without re-implementing
+// the number-coercion + validation. Unrecognised / non-numeric values
+// throw — misconfig surfaces at boot, not mid-request.
+export function dbConnectionOptionsFromEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): DbConnectionOptions {
+  const opts: DbConnectionOptions & {
+    maxConnections?: number;
+    idleTimeoutSeconds?: number;
+    connectTimeoutSeconds?: number;
+  } = {};
+  const max = readPositiveIntEnv(env, "DATABASE_POOL_MAX");
+  const idle = readPositiveIntEnv(env, "DATABASE_POOL_IDLE_TIMEOUT");
+  const connect = readPositiveIntEnv(env, "DATABASE_POOL_CONNECT_TIMEOUT");
+  if (max !== undefined) opts.maxConnections = max;
+  if (idle !== undefined) opts.idleTimeoutSeconds = idle;
+  if (connect !== undefined) opts.connectTimeoutSeconds = connect;
+  return opts;
+}

package/src/db/cursor.ts

@@ -0,0 +1,83 @@
+import type { EntityId, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { and, asc, desc, eq, gt, inArray, type SQL, sql } from "drizzle-orm";
+import type { SelectQuery as PgSelect } from "./dialect";
+
+export type CursorQueryOptions = {
+  tenantId: TenantId;
+  cursor?: string;
+  limit?: number;
+  filterIds?: readonly EntityId[];
+  sort?: string;
+  sortDirection?: "asc" | "desc";
+  extraWhere?: SQL;
+};
+
+export type CursorResult<T> = {
+  rows: T[];
+  nextCursor: string | null;
+  /** Optional total row count — nur present wenn der Caller `totalCount: true`
+   *  in der Query setzt. Pager-UI braucht's für "Page X of Y"; Infinite-
+   *  Scroll und Default-Lists lassen den extra COUNT(*) weg. */
+  total?: number;
+};
+
+// String-basiert damit sowohl UUIDs (Default seit Sprint F) als auch
+// Integer-Auto-Increment-IDs (Legacy/Spezialfälle) durch denselben
+// Cursor-Pfad laufen. Stable-Sort-Voraussetzung: die id-Spalte muss
+// lexikografisch monoton zur Insertion-Order sein. UUIDv7 erfüllt das
+// (time-ordered Prefix); UUIDv4 nicht — wer den nutzt, kriegt
+// inkorrekte cursor-Reihenfolge, das ist erwartet (Default ist v7).
+export function encodeCursor(id: string | number): string {
+  return Buffer.from(String(id)).toString("base64url");
+}
+
+export function decodeCursor(cursor: string): string {
+  const decoded = Buffer.from(cursor, "base64url").toString();
+  if (decoded === "") throw new Error(`Invalid cursor: ${cursor}`);
+  return decoded;
+}
+
+export function applyCursorQuery<T extends PgSelect>(
+  query: T,
+  // biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic tables lose column types
+  table: any,
+  options: CursorQueryOptions,
+): T {
+  const conditions: SQL[] = [eq(table.tenantId, options.tenantId)];
+
+  if (table.isDeleted) {
+    conditions.push(eq(table.isDeleted, false));
+  }
+
+  if (options.cursor) {
+    conditions.push(gt(table.id, decodeCursor(options.cursor)));
+  }
+
+  if (options.filterIds !== undefined) {
+    if (options.filterIds.length === 0) {
+      // No matching IDs — return empty result via raw `false`. Statisch
+      // false ist type-agnostisch (int-PK / uuid-PK egal); ein eq(id, "")
+      // oder eq(id, -1) würde je nach Spalten-Type einen Cast-Error
+      // werfen.
+      conditions.push(sql`false`);
+    } else {
+      conditions.push(inArray(table.id, options.filterIds as readonly string[]));
+    }
+  }
+
+  if (options.extraWhere) {
+    conditions.push(options.extraWhere);
+  }
+
+  const limit = options.limit ?? 50;
+
+  let result = query.where(and(...conditions)).limit(limit);
+
+  if (options.sort && table[options.sort]) {
+    const column = table[options.sort];
+    result =
+      options.sortDirection === "desc" ? result.orderBy(desc(column)) : result.orderBy(asc(column));
+  }
+
+  return result as T;
+}