@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

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

@@ -0,0 +1,175 @@
+// applyEntityEvent — die EINZIGE Schreib-Logik für r.entity-Tabellen aus
+// Stored-Events. Beide Aufrufer benutzen sie:
+//
+//   - createEventStoreExecutor (live, im Write-TX) — übergibt das gerade
+//     appendete StoredEvent direkt; sensitive Felder liegen als Tabellen-
+//     Ciphertext im Payload (boot-validiert pii/encrypted, #967).
+//   - rebuildProjection via ImplicitProjection (replay, im Rebuild-TX) —
+//     übergibt dasselbe StoredEvent; apply kopiert Ciphertext byte-gleich
+//     zurück, bidx wird unten neu berechnet.
+//
+// Live==Rebuild-Equivalence ist damit by-construction für ALLE Felder —
+// eine geänderte Schreib-Logik muss nur an EINER Stelle gepflegt werden,
+// kein Sync-Contract mehr. Einzige legitime Divergenz: Crypto-Shredding
+// (DEK erased → Wert unlesbar, bidx NULL). Load-bearing Test:
+// db/__tests__/implicit-projection-equivalence.integration.test.ts.
+//
+// Tenant isolation: applyEntityEvent expects a raw DbRunner (tx or pool), NOT
+// a TenantDb wrapper. Two sources keep it safe:
+//   1. The live path reads the target row through the tenant-scoped TenantDb
+//      before writing — loadById() for update/delete/forget, db.fetchOne() for
+//      restore — so the aggregateId is already tenant-validated on arrival.
+//   2. create sets tenantId explicitly from event.tenantId, never derived from
+//      the TenantDb wrapper default.
+// The missing TenantDb wrapper in this function is therefore not a hole.
+//
+// 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)
+//   <entity>.forgotten → hard-DELETE immer (Art.17-Purge, auch bei softDelete);
+//                        via executor.forget(). Rebuild replayt created→forgotten
+//                        → Row weg, rebuild-safe (was ein direktes deleteMany nicht ist).
+//
+// Domain-Events (r.defineEvent) auf demselben Aggregate werden hier NICHT
+// behandelt — die liefen im Live-Pfad nie durch den Executor und müssen
+// von expliziten r.projection-apply-Handlern oder r.multiStreamProjection
+// behandelt werden. ImplicitProjection registriert die Auto-Verben.
+//
+// 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 { collectLookupableFields, computeBlindIndexValues } from "../crypto/blind-index.js";
+import { deleteMany, insertOne, updateMany } from "../db/query.js";
+import { InternalError } from "../errors/index.js";
+const AUTO_VERBS = ["created", "updated", "deleted", "restored", "forgotten"];
+/** Parsed event.type → AutoVerb wenn das Event eines der Auto-Verben
+ *  auf dem gegebenen Aggregate ist. null sonst (Domain-Event). */
+export function parseAutoVerb(event) {
+    const prefix = `${event.aggregateType}.`;
+    if (!event.type.startsWith(prefix))
+        return null;
+    const verb = event.type.slice(prefix.length);
+    // @cast-boundary: verb is validated against the AutoVerb list before the cast.
+    return AUTO_VERBS.includes(verb) ? verb : 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, table, entity, tx) {
+    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=tenantDbRunner(db) (kein TenantDb-Wrapper-Auto-Inject),
+            // beim Replay erst recht keiner. Default = event.tenantId; payload
+            // gewinnt NUR wenn gültig string mit length > 0 (seedTenantMembership-
+            // Pfad: Operator schreibt im Ziel-Tenant, Event im Operator-Tenant).
+            // Pinst durch db/__tests__/apply-entity-event-tenant.integration.ts.
+            //
+            // 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;
+            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 insertOne(tx, table, {
+                ...event.payload,
+                // Blind-Index-Spalten aus dem Payload-Wert (ciphertext → decrypt →
+                // HMAC, plaintext → HMAC, erased → NULL). Hier statt im Executor,
+                // damit Live-Write und Rebuild denselben Wert produzieren und der
+                // deterministische HMAC nie im Event-Log landet.
+                ...(await computeBlindIndexValues(event.payload, collectLookupableFields(entity))),
+                tenantId,
+                id: event.aggregateId,
+                version: event.version,
+                insertedAt: event.createdAt,
+                insertedById: event.createdBy,
+            });
+            return { kind: "applied", verb, row: row ?? null };
+        }
+        case "updated": {
+            // payload-Shape: { changes, previous } — siehe event-store-executor.ts.
+            const rawChanges = (event.payload["changes"] ?? {}); // @cast-boundary engine-payload
+            // Plural file fields (files/images) have no entity-table column — the
+            // array of UUIDs lives in the event payload only. Strip them from the
+            // UPDATE so Postgres doesn't error with "column X does not exist".
+            const changes = {};
+            for (const [key, value] of Object.entries(rawChanges)) {
+                const fieldType = entity.fields[key]?.type;
+                if (fieldType === "files" || fieldType === "images")
+                    continue;
+                changes[key] = value;
+            }
+            const rows = await updateMany(tx, table, {
+                ...changes,
+                // bidx nur für die geänderten lookupable-Felder (siehe created).
+                ...(await computeBlindIndexValues(changes, collectLookupableFields(entity))),
+                version: event.version,
+                modifiedAt: event.createdAt,
+                modifiedById: event.createdBy,
+            }, { id: event.aggregateId });
+            return { kind: "applied", verb, row: rows[0] ?? null };
+        }
+        case "deleted": {
+            if (softDelete) {
+                const rows = await updateMany(tx, table, {
+                    isDeleted: true,
+                    deletedAt: event.createdAt,
+                    deletedById: event.createdBy,
+                    version: event.version,
+                    modifiedAt: event.createdAt,
+                    modifiedById: event.createdBy,
+                }, { id: event.aggregateId });
+                return { kind: "applied", verb, row: rows[0] ?? null };
+            }
+            // Hard-Delete: DELETE-Statement gibt keine returning-Row her und
+            // der Live-Pfad nutzt eh `existing` (pre-delete-Snapshot) für die
+            // Response. Beim Replay ist das fine, der Caller braucht die Row
+            // nicht weiter.
+            await deleteMany(tx, table, { id: event.aggregateId });
+            return { kind: "applied", verb, row: null };
+        }
+        case "restored": {
+            // Restore ist nur bei softDelete sinnvoll. Hard-Delete-Entities sollten
+            // keine restored-Events erhalten — falls doch, defensive skip.
+            if (!softDelete)
+                return { kind: "skipped" };
+            const rows = await updateMany(tx, table, {
+                isDeleted: false,
+                deletedAt: null,
+                deletedById: null,
+                version: event.version,
+                modifiedAt: event.createdAt,
+                modifiedById: event.createdBy,
+            }, { id: event.aggregateId });
+            return { kind: "applied", verb, row: rows[0] ?? null };
+        }
+        case "forgotten": {
+            // Hard-delete regardless of softDelete: forget/purge (Art. 17) removes the
+            // row entirely. On rebuild the aggregate replays created → forgotten, so
+            // the row ends up gone — the rebuild-safe erasure the soft-delete verb
+            // (which only flips isDeleted) cannot provide.
+            await deleteMany(tx, table, { id: event.aggregateId });
+            return { kind: "applied", verb, row: null };
+        }
+    }
+}

package/dist/db/assert-exists-in.d.ts

@@ -0,0 +1,23 @@
+import type { TenantId } from "../engine/types/identifiers.js";
+import { NotFoundError } from "../errors/index.js";
+import type { DbConnection } from "./connection.js";
+import type { TenantDb } from "./tenant-db.js";
+/**
+ * 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 declare function assertExistsIn(db: DbConnection | TenantDb, entity: any, options: {
+    field: string;
+    value: unknown;
+    tenantId?: TenantId;
+    where?: Record<string, unknown>;
+    entityName?: string;
+}): Promise<NotFoundError | null>;

package/dist/db/assert-exists-in.js

@@ -0,0 +1,34 @@
+import { fetchOne } from "../db/query.js";
+import { NotFoundError } from "../errors/index.js";
+function isTenantDb(db) {
+    return "tenantId" in db && "fetchOne" in db && typeof db.fetchOne === "function";
+}
+/**
+ * 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, 
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle table types are dynamic
+entity, options) {
+    const where = { [options.field]: options.value };
+    if (options.tenantId !== undefined)
+        where["tenantId"] = options.tenantId;
+    if (options.where)
+        Object.assign(where, options.where);
+    const row = isTenantDb(db) ? await db.fetchOne(entity, where) : await fetchOne(db, entity, where);
+    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/dist/db/blind-index-cleanup.d.ts

@@ -0,0 +1,5 @@
+import type { FeatureDefinition } from "../engine/types/index.js";
+import type { DbRunner } from "./connection.js";
+export declare function nullBlindIndexesForSubject(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, subjectKey: string): Promise<void>;
+export declare function subjectRowExistsInTenant(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, subjectId: string, tenantId: string): Promise<boolean>;
+export declare function recordRowExistsInTenant(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, entityName: string, recordId: string, tenantId: string): Promise<boolean>;

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

@@ -0,0 +1,112 @@
+// Immediate blind-index nulling after a subject erase (#818).
+//
+// After kms.eraseKey the ciphertext is unreadable, but the deterministic
+// bidx column would stay matchable until the next write/rebuild — a
+// linkage window ("does any row hold value X"). This sweep closes it right
+// away: the ciphertext names its subject inline
+// (kumiko-pii:v1:<subjectKey>:...), so a LIKE-prefix match finds exactly
+// the erased subject's rows — one UPDATE per lookupable field.
+//
+// Rows the forget run deletes/anonymizes via the executor anyway get their
+// bidx recomputed automatically there; this sweep covers the rows left
+// behind (foreign entities with userOwned fields).
+import { collectLookupableFields } from "../crypto/blind-index.js";
+import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern.js";
+import { isSelfPiiField } from "../crypto/is-self-pii-field.js";
+import { toSnakeCase } from "../utils/case.js";
+import { resolveTableName } from "./entity-table-meta.js";
+import { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
+import { tableExists } from "./schema-inspection.js";
+export async function nullBlindIndexesForSubject(db, features, subjectKey) {
+    const likePattern = subjectCiphertextLikePattern(subjectKey);
+    for (const feature of features.values()) {
+        for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+            const lookupable = collectLookupableFields(entity);
+            if (lookupable.length === 0)
+                continue;
+            // No featureName prefix — the dispatcher builds entity tables without
+            // one (buildEntityTable with no featureName option), the sweep has to
+            // hit the same names.
+            const tableName = resolveTableName(entityName, entity, undefined);
+            // Skip entities whose projection was never migrated — same class as
+            // subjectRowExistsInTenant (fw#2348). A throw here runs AFTER eraseKey
+            // in forget-subject and would leave deterministic bidx columns still
+            // linkable (fw#2550).
+            if (!(await tableExists(db, tableName)))
+                continue;
+            for (const fieldName of lookupable) {
+                const snake = toSnakeCase(fieldName);
+                await executeRawQuery(db, `UPDATE ${quoteIdent(tableName)} SET ${quoteIdent(`${snake}_bidx`)} = NULL WHERE ${quoteIdent(snake)} LIKE $1`, [likePattern]);
+            }
+        }
+    }
+}
+// Tenant-scope oracle for crypto-shredding's forget-subject (mh#349): a
+// "user"-kind subject id is often not a real user (share-token recipient,
+// email subscriber, ...) — those entities self-own their PII (`pii: true`,
+// i.e. their own row id IS the subject) and carry a real tenant_id,
+// unlike read_users (systemStream, tenant_id always SYSTEM_TENANT_ID). This
+// checks whether the subject row lives in the given tenant, so a tenant-
+// scoped DPO can still forget subjects it truly owns without needing a
+// tenant-membership row (which only exists for real users).
+//
+// Invariant: `id` must never be client-settable on self-PII entities — the
+// framework create path strips client ids; app write paths MUST do the same
+// or a DPO could plant a foreign subject id in their tenant and pass this
+// oracle (#2348). Upgrade path: require an event-store provenance check
+// (`aggregate_id = subjectId` under the actor tenant) when apps need
+// client-supplied ids.
+export async function subjectRowExistsInTenant(db, features, subjectId, tenantId) {
+    // Prefetch which self-PII projection tables actually exist — probing a
+    // missing relation used to throw (and get swallowed), which both hid
+    // real schema bugs and risked poisoning the Bun.SQL connection for the
+    // rest of the forget TX (fw#2348 / framework#356).
+    const candidateTables = [];
+    for (const feature of features.values()) {
+        for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+            const hasSelfPiiField = Object.values(entity.fields).some(isSelfPiiField);
+            if (!hasSelfPiiField)
+                continue;
+            candidateTables.push(resolveTableName(entityName, entity, undefined));
+        }
+    }
+    const existing = new Set();
+    for (const tableName of candidateTables) {
+        const rows = await executeRawQueryRead(db, `SELECT to_regclass(quote_ident($1)) IS NOT NULL AS exists`, [tableName]);
+        if (rows[0]?.exists === true)
+            existing.add(tableName);
+    }
+    for (const tableName of candidateTables) {
+        if (!existing.has(tableName))
+            continue;
+        const rows = await executeRawQueryRead(db, `SELECT 1 FROM ${quoteIdent(tableName)} WHERE id = $1 AND tenant_id = $2 LIMIT 1`, [subjectId, tenantId]);
+        if (rows.length > 0)
+            return true;
+    }
+    return false;
+}
+function findEntityByExactName(features, entityName) {
+    for (const feature of features.values()) {
+        const entity = feature.entities?.[entityName];
+        if (entity)
+            return entity;
+    }
+    return undefined;
+}
+// Tighter than subjectRowExistsInTenant: the record subject names its own
+// entity, so this is a single-table lookup instead of a self-PII scan
+// across the whole registry.
+//
+// Invariant: sound only because `id` is a single-column PK per entity
+// table (globally unique, unspoofable via a client-supplied explicitId
+// at create) — a composite PK or shared table would break this (#2348).
+export async function recordRowExistsInTenant(db, features, entityName, recordId, tenantId) {
+    const entity = findEntityByExactName(features, entityName);
+    if (!entity)
+        return false;
+    const tableName = resolveTableName(entityName, entity, undefined);
+    if (!(await tableExists(db, tableName)))
+        return false;
+    const rows = await executeRawQueryRead(db, `SELECT 1 FROM ${quoteIdent(tableName)} WHERE id = $1 AND tenant_id = $2 LIMIT 1`, [recordId, tenantId]);
+    return rows.length > 0;
+}

package/dist/db/bun-provider.d.ts

@@ -0,0 +1,2 @@
+import { type DbConnectionOptions, type DbPoolHandle } from "./api.js";
+export declare function createBunConnection(url: string, options?: DbConnectionOptions): DbPoolHandle;

package/dist/db/bun-provider.js

@@ -0,0 +1,37 @@
+// Bun.SQL Provider — experimentell.
+// Default: postgres-js. Dieser Provider nur aktiv wenn DB_PROVIDER=bun.
+// Bekannter Bug: Extended-Query-Protocol Caching verursacht
+// PostgresError "bind message has 11 result formats but query has 1 columns"
+// bei sequentiellen Queries mit unterschiedlicher Spaltenzahl innerhalb
+// derselben Connection.
+//
+// Bun.SQL hat kein LISTEN — postgres-js-Peer für event-dispatcher.
+import postgres from "postgres";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS, } from "./api.js";
+export function createBunConnection(url, options = {}) {
+    const bunOpts = {};
+    if (options.maxConnections !== undefined)
+        bunOpts.max = options.maxConnections;
+    if (options.idleTimeoutSeconds !== undefined)
+        bunOpts.idleTimeout = options.idleTimeoutSeconds;
+    if (options.connectTimeoutSeconds !== undefined)
+        bunOpts.connectionTimeout = options.connectTimeoutSeconds;
+    const db = new Bun.SQL(url, bunOpts);
+    // LISTEN peer — 1 connection reicht für NOTIFY-Wakeups
+    const pgOpts = { max: 1 };
+    if (options.idleTimeoutSeconds !== undefined)
+        pgOpts.idle_timeout = options.idleTimeoutSeconds;
+    if (options.connectTimeoutSeconds !== undefined)
+        pgOpts.connect_timeout = options.connectTimeoutSeconds;
+    const listenClient = postgres(url, pgOpts);
+    const closeTimeout = options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS;
+    return {
+        db,
+        client: listenClient,
+        listenClient,
+        close: async () => {
+            await db.end({ timeout: closeTimeout });
+            await listenClient.end({ timeout: closeTimeout });
+        },
+    };
+}

package/dist/db/collect-table-metas.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureDefinition } from "../engine/types/index.js";
+import { type EntityTableMeta } from "./entity-table-meta.js";
+export declare function collectTableMetas(features: readonly FeatureDefinition[]): readonly EntityTableMeta[];

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

@@ -0,0 +1,76 @@
+// Canonical table source for both `kumiko schema generate` and setupTestStack
+// (entities, storeTables, projections, multiStreamProjections). One shared
+// source so the test-DB push and migrations cannot drift apart again (#255, #3102).
+import { compareByCodepoint } from "../utils/index.js";
+import { assertBackingTableSuperset, deriveEntityTableMeta, } from "./entity-table-meta.js";
+import { enumerateFeatureTableSources } from "./feature-table-sources.js";
+import { asEntityTableMeta } from "./query.js";
+function canonicalColumnsKey(meta) {
+    // Spalten-Identität unabhängig von Deklarations-Reihenfolge und
+    // Objekt-Key-Order. Indexes bleiben außen vor: eine Projection-Table
+    // (buildEntityTable ohne relations) trägt legitim weniger FK-Indexes
+    // als das Entity-Meta derselben Tabelle.
+    return [...meta.columns]
+        .sort((a, b) => compareByCodepoint(a.name, b.name))
+        .map((c) => `${c.name}|${c.pgType}|${c.notNull}|${c.defaultSql ?? ""}|${c.primaryKey ?? false}|${c.identity ?? false}|${c.bigintJsMode ?? ""}`)
+        .join("\n");
+}
+export function collectTableMetas(features) {
+    const metas = [];
+    const byName = new Map();
+    // Pass 1: kanonische Schema-Quellen, identisch zum bisherigen Template-
+    // Verhalten (gleiche Reihenfolge, gleiche deriveEntityTableMeta-Optionen).
+    for (const feature of features) {
+        for (const [name, ent] of Object.entries(feature.entities ?? {})) {
+            const fieldMeta = deriveEntityTableMeta(name, ent, { relations: feature.relations[name] });
+            // Backing table wins: it's the physical DDL truth for ride-along columns/
+            // indexes the field-DSL can't express (secrets' envelope). Validated as a
+            // superset of the field-derived meta so a field/table disagreement throws.
+            const backing = feature.entityTables?.[name];
+            let meta = fieldMeta;
+            if (backing !== undefined) {
+                const tableMeta = asEntityTableMeta(backing);
+                if (!tableMeta) {
+                    throw new Error(`collectTableMetas: entity "${name}" (${feature.name}) declares a backing ` +
+                        "table that carries no EntityTableMeta — build it via table() / buildEntityTable.");
+                }
+                assertBackingTableSuperset(name, fieldMeta, tableMeta);
+                meta = tableMeta;
+            }
+            metas.push(meta);
+            byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });
+        }
+        for (const entry of Object.values(feature.storeTables)) {
+            metas.push(entry.meta);
+            byName.set(entry.meta.tableName, {
+                meta: entry.meta,
+                origin: `storeTable "${entry.name}" (${feature.name})`,
+            });
+        }
+    }
+    // Pass 2: table-tragende Registrierungen. Zwei Pässe, damit eine Entity-
+    // Tabelle aus Feature B gegen eine gleichnamige Projection-Table aus
+    // Feature A gewinnt — Entity-Metas sind die reichere Quelle (FK-Indexes
+    // aus relations).
+    for (const feature of features) {
+        for (const { table, origin } of enumerateFeatureTableSources(feature)) {
+            const meta = asEntityTableMeta(table);
+            if (!meta) {
+                throw new Error(`collectTableMetas: ${origin} carries no EntityTableMeta — ` +
+                    "build the table via table() / buildEntityTable / defineUnmanagedTable.");
+            }
+            const existing = byName.get(meta.tableName);
+            if (existing) {
+                if (canonicalColumnsKey(existing.meta) !== canonicalColumnsKey(meta)) {
+                    throw new Error(`collectTableMetas: table "${meta.tableName}" is declared with diverging ` +
+                        `columns by ${origin} and ${existing.origin}. Align the column ` +
+                        "definitions or rename one of the tables.");
+                }
+                continue;
+            }
+            metas.push(meta);
+            byName.set(meta.tableName, { meta, origin });
+        }
+    }
+    return metas;
+}

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

@@ -0,0 +1,9 @@
+import type { EntityDefinition } from "../engine/types/index.js";
+/**
+ * API-Form (combined) → DB-Form (flat). Wird vor jedem Insert/Update aufgerufen.
+ */
+export declare function flattenCompoundTypes(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
+/**
+ * DB-Form (flat) → API-Form (combined). Wird nach jedem Read aufgerufen.
+ */
+export declare function rehydrateCompoundTypes(row: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;

package/dist/db/compound-types.js

@@ -0,0 +1,31 @@
+// 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 { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp.js";
+import { flattenMoney, rehydrateMoney } from "./money.js";
+// Reihenfolge ist egal solange die Konverter sich nicht gegenseitig
+// überlappen (z.B. money darf nicht ein Feld berühren das locatedTimestamp
+// schon erzeugt hat). Aktuell überlappen sie nicht — types sind disjunkt.
+const FLATTENERS = [flattenLocatedTimestamp, flattenMoney];
+const REHYDRATORS = [rehydrateLocatedTimestamp, rehydrateMoney];
+/**
+ * API-Form (combined) → DB-Form (flat). Wird vor jedem Insert/Update aufgerufen.
+ */
+export function flattenCompoundTypes(payload, entity) {
+    return FLATTENERS.reduce((acc, fn) => fn(acc, entity), payload);
+}
+/**
+ * DB-Form (flat) → API-Form (combined). Wird nach jedem Read aufgerufen.
+ */
+export function rehydrateCompoundTypes(row, entity) {
+    return REHYDRATORS.reduce((acc, fn) => fn(acc, entity), row);
+}

package/dist/db/config-seed.d.ts

@@ -0,0 +1,19 @@
+import type { EntityDefinition } from "../engine/index.js";
+import type { ConfigSeedDef, Registry } from "../engine/types/index.js";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher.js";
+import type { DbConnection } from "./connection.js";
+import type { EntityTable } from "./table-builder.js";
+/**
+ * Seed config values at boot time via the event-store executor.
+ *
+ * For each ConfigSeedDef: calls executor.create(payload, SYSTEM_USER, db).
+ * When the aggregate stream already exists (e.g. re-boot, admin-override),
+ * the executor returns a WriteFailure(version_conflict) which we skip.
+ *
+ * Idempotent, race-safe via DB-level unique constraints, and visible to
+ * multi-stream-projection subscribers as normal configValue.created events.
+ */
+export declare function seedConfigValues<E extends EntityDefinition>(seeds: readonly ConfigSeedDef[], table: EntityTable<E>, entity: E, registry: Registry, db: DbConnection, cipher?: EnvelopeCipher): Promise<{
+    created: number;
+    skipped: number;
+}>;

package/dist/db/config-seed.js

@@ -0,0 +1,75 @@
+import { v5 as uuidv5 } from "uuid";
+import { createSystemUser, SYSTEM_TENANT_ID } from "../engine/index.js";
+import { createEventStoreExecutor } from "./event-store-executor.js";
+import { createTenantDb } from "./tenant-db.js";
+// Namespace UUID for deterministic seed aggregate IDs. Same namespace +
+// (key, tenantId, userId) triple always produces the same UUIDv5, which
+// makes executor.create(…, expectedVersion: 0) hit version_conflict on
+// re-boot — no new stream created, idempotent without DB-level checks.
+const CONFIG_SEED_NS = "6f1e9d8c-2a5b-4c7d-9e3f-1a2b3c4d5e6f";
+/**
+ * Seed config values at boot time via the event-store executor.
+ *
+ * For each ConfigSeedDef: calls executor.create(payload, SYSTEM_USER, db).
+ * When the aggregate stream already exists (e.g. re-boot, admin-override),
+ * the executor returns a WriteFailure(version_conflict) which we skip.
+ *
+ * Idempotent, race-safe via DB-level unique constraints, and visible to
+ * multi-stream-projection subscribers as normal configValue.created events.
+ */
+export async function seedConfigValues(seeds, table, entity, registry, db, cipher) {
+    let created = 0;
+    let skipped = 0;
+    if (seeds.length === 0)
+        return { created, skipped };
+    const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+    const executor = createEventStoreExecutor(table, entity, { entityName: "config-value" });
+    const tdb = createTenantDb(db, SYSTEM_TENANT_ID, "system");
+    for (const seed of seeds) {
+        const keyDef = registry.getConfigKey(seed.key);
+        if (!keyDef) {
+            skipped++;
+            continue;
+        }
+        // Encrypted keys without a cipher would silently write plaintext to a
+        // column the resolver later tries to decrypt — fail loud at boot, not
+        // on first read in prod.
+        if (keyDef.encrypted && !cipher) {
+            throw new Error(`seedConfigValues: key "${seed.key}" is encrypted but no EnvelopeCipher was supplied.`);
+        }
+        const scope = seed.scope ?? keyDef.scope;
+        // User-scope seeds need a concrete tenantId because the resolver
+        // user-cascade matches the user's actual tenantId, not the SYSTEM
+        // sentinel — a SYSTEM-rooted user row would be unreachable.
+        if (scope === "user" && (!seed.tenantId || !seed.userId)) {
+            throw new Error(`seedConfigValues: user-scope seed "${seed.key}" requires both tenantId and userId — use createUserSeed({value}, {tenantId, userId}).`);
+        }
+        const tenantId = seed.tenantId ?? SYSTEM_TENANT_ID;
+        const userId = scope === "user" ? (seed.userId ?? null) : null;
+        // Deterministic aggregate id (key+tenant+user triple) so re-boot hits
+        // the existing stream → version_conflict → counted as skipped.
+        const idSource = `${seed.key}:${tenantId}:${userId ?? ""}`;
+        const aggregateId = uuidv5(idSource, CONFIG_SEED_NS);
+        let value = JSON.stringify(seed.value);
+        if (keyDef.encrypted && cipher) {
+            value = await cipher.encrypt(value, { tenantId });
+        }
+        const payload = {
+            id: aggregateId,
+            key: seed.key,
+            value,
+            tenantId,
+            userId,
+        };
+        const result = await executor.create(payload, systemUser, tdb);
+        if (result.isSuccess) {
+            created++;
+        }
+        else {
+            // version_conflict (stream exists) and unique_violation (projection
+            // race) both mean "already seeded" — count as skipped, not error.
+            skipped++;
+        }
+    }
+    return { created, skipped };
+}

package/dist/db/connection.d.ts

@@ -0,0 +1,10 @@
+import type { DbConnection, PgClient } from "@cosmicdrift/kumiko-types/db-connection";
+export type * from "@cosmicdrift/kumiko-types/db-connection";
+export type { DbConnectionOptions, DbPoolHandle } from "./api.js";
+export { createConnection } from "./api.js";
+export declare function createDbConnection(url: string, options?: import("./api.js").DbConnectionOptions): {
+    db: DbConnection;
+    client: PgClient;
+    close: () => Promise<void>;
+};
+export declare function dbConnectionOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): import("./api.js").DbConnectionOptions;