@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/es-ops/operations-schema.js

@@ -0,0 +1,40 @@
+// Tracking-Table für ES-Operations (Phase 1: seed-migrations; Phase 2+:
+// projection-rebuild, event-replay, stream-migration, ... — siehe
+// kumiko-platform/docs/plans/features/es-ops.md).
+//
+// File-ID-Tracking analog drizzle-kit: filename ist die ID, applied-set
+// liegt in dieser Tabelle. Pending = files-on-disk MINUS applied-set.
+//
+// operation_type-Discriminator lässt Phase 2+ dieselbe Tabelle nutzen,
+// kein Schema-Sprawl. CLI-Status filtert per type:
+//   bunx kumiko ops seed:status      → operation_type = "seed-migration"
+//   bunx kumiko ops projection:status → operation_type = "projection-rebuild"
+import { index, integer, table as pgTable, sql, text, timestamp } from "../db/dialect.js";
+// sql now comes from native dialect
+import { tableExists } from "../db/index.js";
+import { unsafePushTables } from "../stack/index.js";
+export const esOperationsTable = pgTable("kumiko_es_operations", {
+    // Filename without extension serves as ID. Chronologically sortable
+    // (date-prefix convention), human-meaningful, no separate hash needed.
+    // Renaming a file = different ID = re-run; intentional (drizzle parity).
+    id: text("id").primaryKey(),
+    operationType: text("operation_type").notNull().$type(),
+    appliedAt: timestamp("applied_at", { withTimezone: true, mode: "string" })
+        .notNull()
+        .default(sql `now()`),
+    durationMs: integer("duration_ms").notNull(),
+    // Trace: came from boot-time auto-apply, explicit CLI, or CI step.
+    // Helps when forensics ask "wer hat das wann angestoßen".
+    appliedBy: text("applied_by").notNull().$type(),
+    // Optional human-readable annotation — surfaced in `ops <op>:status`.
+    notes: text("notes"),
+}, (t) => ({
+    typeIdx: index("kumiko_es_operations_type_idx").on(t.operationType),
+}));
+// Convenience for tests + boot-time setup (idempotent). Mirrors the
+// createEventsTable pattern in event-store/events-schema.ts.
+export async function createEsOperationsTable(db) {
+    if (!(await tableExists(db, "public.kumiko_es_operations"))) {
+        await unsafePushTables(db, { kumikoEsOperations: esOperationsTable });
+    }
+}

package/dist/es-ops/runner.d.ts

@@ -0,0 +1,29 @@
+import type { DbConnection, DbRunner } from "../db/index.js";
+import type { Registry } from "../engine/index.js";
+import type { EsOperationAppliedBy, SeedMigrationContext } from "./types.js";
+export type RunPendingSeedMigrationsArgs = {
+    readonly db: DbConnection;
+    /** Absoluter Pfad zum seeds-Directory (typically <appRoot>/seeds). */
+    readonly seedsDir: string;
+    /** Factory die den Context für jede einzelne seed-Migration erzeugt.
+     *  Caller bekommt einen DbRunner (Connection ODER aktive Tx) — Runner
+     *  ruft das pro-migration im tx-Scope auf. */
+    readonly createContext: (dbRunner: DbRunner) => SeedMigrationContext;
+    /** Trace-marker: boot | cli | ci-pipeline. Landet in applied_by. */
+    readonly appliedBy: EsOperationAppliedBy;
+    /** Optional registry für Dry-Run-Validation: parsed jeden seed-file und
+     *  checkt dass alle referenzierten handler-QNs in der Registry existieren
+     *  BEVOR die Migration läuft. Catched camelCase-typos + andere QN-Drift
+     *  zur Boot-Zeit statt mitten im write-cycle (Phase 1.5 / A2).
+     *
+     *  Wenn weggelassen → kein Dry-Run (backward-compat für tests die ohne
+     *  Registry arbeiten). runProdApp reicht den richtigen Registry rein. */
+    readonly registry?: Registry;
+    /** Optional log-prefix override, default "[es-ops/seed-migration]". */
+    readonly logger?: (line: string) => void;
+};
+export type RunPendingSeedMigrationsResult = {
+    readonly appliedIds: readonly string[];
+    readonly skippedIds: readonly string[];
+};
+export declare function runPendingSeedMigrations(args: RunPendingSeedMigrationsArgs): Promise<RunPendingSeedMigrationsResult>;

package/dist/es-ops/runner.js

@@ -0,0 +1,195 @@
+// Runner für pending seed-migrations beim Boot.
+//
+// Flow:
+//   1. List seeds/<*.ts> sorted ascending (filename = chronologische ID)
+//   2. SELECT id FROM kumiko_es_operations WHERE operation_type='seed-migration'
+//   3. pending = files \ applied
+//   4. Für jeden pending in Order:
+//      a. dynamic import → default-export (SeedMigration)
+//      b. wenn migration.skippable && env[KUMIKO_SKIP_ES_OPS_<sanitized>]='1':
+//         → console.log + continue (kein Marker geschrieben)
+//      c. Tx start
+//      d. await migration.run(ctx)
+//      e. INSERT marker mit duration_ms + appliedBy
+//      f. Tx commit
+//   5. On any failure: Tx rollback + console.error + throw
+//      → App-Boot bricht ab. Operator muss Failure fixen + retry.
+//
+// Skippable-Pattern: seed.skippable=true erlaubt im Notfall ein
+// `KUMIKO_SKIP_ES_OPS_<id>=1` env-flag um eine kaputte Migration zu
+// überspringen ohne ihr Code touchen zu müssen. NICHT als
+// Standard-Workflow — wirklich Notfall.
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { acquireEsOpsAdvisoryLock, esOperationExists } from "../db/queries/es-ops.js";
+import { insertOne, selectMany } from "../db/query.js";
+import { esOperationsTable } from "./operations-schema.js";
+const DEFAULT_LOGGER = (line) => {
+    // biome-ignore lint/suspicious/noConsole: boot-time-output, kein Logger-Inject hier
+    console.log(line);
+};
+const LOG_PREFIX = "[es-ops/seed-migration]";
+export async function runPendingSeedMigrations(args) {
+    const log = args.logger ?? DEFAULT_LOGGER;
+    const onDisk = await listSeedFiles(args.seedsDir);
+    if (onDisk.length === 0) {
+        log(`${LOG_PREFIX} no seed files in ${args.seedsDir} — skipping`);
+        return { appliedIds: [], skippedIds: [] };
+    }
+    const applied = await loadAppliedIds(args.db);
+    const pending = onDisk.filter((entry) => !applied.has(entry.id));
+    if (pending.length === 0) {
+        log(`${LOG_PREFIX} ${onDisk.length} on disk, all applied — nothing to do`);
+        return { appliedIds: [], skippedIds: [] };
+    }
+    log(`${LOG_PREFIX} ${pending.length}/${onDisk.length} pending`);
+    const appliedIds = [];
+    const skippedIds = [];
+    // Dry-Run-Pass (Phase 1.5 / A2): vor JEDER migration alle handler-QNs aus
+    // den seed-files parsen + gegen registry checken. Fail-fast vor erstem
+    // write — gibt klare error-message mit Datei + qn statt zur runtime
+    // "handler not found" mitten im migration-flow.
+    if (args.registry !== undefined) {
+        const unknownQns = [];
+        for (const entry of pending) {
+            const source = await readFile(entry.filePath, "utf-8");
+            for (const qn of extractWriteHandlerQns(source)) {
+                if (!args.registry.getWriteHandler(qn)) {
+                    unknownQns.push({ id: entry.id, qn });
+                }
+            }
+        }
+        if (unknownQns.length > 0) {
+            const lines = unknownQns.map((u) => `  - ${u.id}: "${u.qn}" not registered`);
+            throw new Error(`[es-ops/seed-migration] dry-run found ${unknownQns.length} unknown handler-QN(s):\n${lines.join("\n")}\n  Check spelling against your TenantHandlers/AuthHandlers constants (kebab-case after the colon).`);
+        }
+        log(`${LOG_PREFIX} dry-run ok — all referenced handler-QNs registered`);
+    }
+    for (const entry of pending) {
+        const migration = await loadSeedModule(entry.filePath);
+        const envFlag = `KUMIKO_SKIP_ES_OPS_${sanitizeForEnv(entry.id)}`;
+        if (migration.skippable === true && process.env[envFlag] === "1") {
+            log(`${LOG_PREFIX} skip "${entry.id}" — ${envFlag}=1`);
+            skippedIds.push(entry.id);
+            continue;
+        }
+        const start = Date.now();
+        try {
+            await args.db.begin(async (tx) => {
+                // Advisory-Lock: sequentialisiert Multi-Replica-Boots. Zweiter
+                // Pod blockt bis erster fertig ist, dann re-checked sein
+                // applied-set (außerhalb dieser Funktion in nächster Iteration)
+                // und findet den Marker → skip. Lock wird beim Tx-Commit
+                // automatisch released (xact-scope).
+                await acquireEsOpsAdvisoryLock(tx);
+                if (await esOperationExists(tx, entry.id)) {
+                    log(`${LOG_PREFIX} race-skip "${entry.id}" — applied by parallel boot`);
+                    // skip: parallel boot won the advisory-lock and already applied
+                    // this migration. Nothing more to do in this tx.
+                    return;
+                }
+                const ctx = args.createContext(tx);
+                await migration.run(ctx);
+                await insertOne(tx, esOperationsTable, {
+                    id: entry.id,
+                    operationType: "seed-migration",
+                    durationMs: Date.now() - start,
+                    appliedBy: args.appliedBy,
+                    notes: migration.description,
+                });
+            });
+            const elapsed = Date.now() - start;
+            log(`${LOG_PREFIX} ✓ ${entry.id} (${elapsed}ms) — ${migration.description}`);
+            appliedIds.push(entry.id);
+        }
+        catch (err) {
+            const elapsed = Date.now() - start;
+            log(`${LOG_PREFIX} ✗ ${entry.id} (${elapsed}ms) — ${stringifyError(err)}`);
+            log(`${LOG_PREFIX} ABORT — ${pending.length - appliedIds.length - skippedIds.length - 1} pending migrations were NOT attempted`);
+            throw err;
+        }
+    }
+    return { appliedIds, skippedIds };
+}
+async function listSeedFiles(seedsDir) {
+    let entries;
+    try {
+        entries = await readdir(seedsDir);
+    }
+    catch {
+        // Directory doesn't exist → treat as empty. App ohne seeds-Dir ist
+        // ein valider Zustand (no-op).
+        return [];
+    }
+    return entries
+        .filter((name) => name.endsWith(".ts") || name.endsWith(".mts") || name.endsWith(".js"))
+        .filter((name) => !name.startsWith("_") && !name.startsWith("."))
+        .sort() // filename = chronologische ID (date-prefix-convention)
+        .map((name) => ({
+        id: name.replace(/\.(ts|mts|js)$/, ""),
+        // resolve, nicht join: Bun's await import() braucht absolute Pfade.
+        // Wenn seedsDir relativ ist (z.B. "./seeds" aus runProdApp-Option),
+        // wäre der join-Pfad auch relativ → Bun's import-resolver such
+        // relativ zum runner.ts-Modul, nicht zu process.cwd() → fail mit
+        // "Cannot find module 'seeds/...' from '<runner-path>'".
+        filePath: path.resolve(seedsDir, name),
+    }));
+}
+async function loadAppliedIds(db) {
+    const rows = await selectMany(db, esOperationsTable, {
+        operationType: "seed-migration",
+    });
+    return new Set(rows.map((r) => r.id));
+}
+async function loadSeedModule(filePath) {
+    // Bun + Node both honor dynamic import on absolute paths. The seed-files
+    // must export their SeedMigration as default.
+    const mod = await import(filePath);
+    const migration = mod.default;
+    if (!isSeedMigration(migration)) {
+        throw new Error(`[es-ops] seed file ${filePath} must export a SeedMigration as default ` +
+            `(object with { description: string, run: (ctx) => Promise<void> })`);
+    }
+    return migration;
+}
+function isSeedMigration(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    // @cast-boundary generic-record — narrowing unknown to property-bag for shape-check
+    const v = value;
+    return typeof v.description === "string" && typeof v.run === "function";
+}
+// "2026-05-20-fix-admin-roles" → "2026_05_20_FIX_ADMIN_ROLES"
+function sanitizeForEnv(id) {
+    return id.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+}
+// Parse seed-file source + extract handler-QNs aus `systemWriteAs(...)`-
+// Calls. Reine regex (kein AST) — fängt die häufigen Inline-String-Cases:
+//   ctx.systemWriteAs("foo:write:bar", payload)
+//   systemWriteAs("foo:write:bar", ...)  (destructured)
+//
+// Edge-Cases die NICHT geguckt werden:
+//   - QN aus Variable: `const qn = "..."; ctx.systemWriteAs(qn, ...)`
+//   - String-Concat / Template-Literals mit dynamic vars
+// Diese Pattern sind selten in real seed-migrations + bleibt als known-
+// limitation dokumentiert. Wer dynamic-QN braucht, weiß was er tut.
+function extractWriteHandlerQns(source) {
+    const pattern = /systemWriteAs\s*\(\s*["']([^"']+)["']/g;
+    const out = new Set();
+    for (const match of source.matchAll(pattern)) {
+        const qn = match[1];
+        if (qn)
+            out.add(qn);
+    }
+    return [...out];
+}
+function stringifyError(err) {
+    if (err instanceof Error)
+        return `${err.name}: ${err.message}`;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}

package/dist/es-ops/types.d.ts

@@ -0,0 +1,92 @@
+import type { DbRunner } from "../db/index.js";
+import type { TenantId, WriteResult } from "../engine/index.js";
+export type EsOperationAppliedBy = "boot" | "cli" | "ci-pipeline";
+/** Default-Export einer seed-Migration-File. */
+export type SeedMigration = {
+    /** Kurze Beschreibung was die Migration tut. Wird in kumiko_es_operations.notes
+     *  und im `ops seed:status`-Output gezeigt. */
+    readonly description: string;
+    /** Optional: skippe diesen Seed wenn die env-var
+     *  `KUMIKO_SKIP_ES_OPS_<sanitized-filename>=1` gesetzt ist (für Recovery /
+     *  Debug-Boots). Default false = always-run-pending. */
+    readonly skippable?: boolean;
+    /** Hauptarbeit. ctx liefert systemWriteAs (Event-Store-konformer Pfad,
+     *  bypassed Access-Checks via system-user) plus Read-Helpers.
+     *
+     *  Throws → Marker NICHT geschrieben, App-Boot bricht ab, Retry bei
+     *  nächstem Boot. Pro-Migration eigene Transaction; ein Failure stoppt
+     *  alle nachfolgenden pending-Migrations (Order-Erhalt). */
+    readonly run: (ctx: SeedMigrationContext) => Promise<void>;
+};
+/** Read-shape eines User-Eintrags wie an Seed-Helpers exposed.
+ *  Schmaler Subset von AuthUserRow — Seeds brauchen typischerweise nur
+ *  diese Felder zur Identifikation. */
+export type SeedUserRow = {
+    readonly id: string;
+    readonly email: string;
+    readonly tenantId: string;
+};
+/** Read-shape eines Membership-Eintrags wie an Seed-Helpers exposed.
+ *  Unterscheidet zwei tenantIds: die "logische" aus dem Read-Projektion
+ *  (`tenantId`) und die "physische" aus dem Aggregate-Stream
+ *  (`streamTenantId`). Die beiden weichen voneinander ab wenn das
+ *  Aggregate von einem Executor mit anderer tenantId angelegt wurde
+ *  (z.B. seedTenantMembership-by=systemAdmin) — typischer
+ *  publicstatus-Driver-Use-Case. */
+export type SeedMembershipRow = {
+    readonly userId: string;
+    /** Payload-tenant aus `read_tenant_memberships.tenant_id`. Geht ins
+     *  write-payload als `tenantId`. */
+    readonly tenantId: string;
+    /** Stream-tenant aus `kumiko_events.tenant_id` der v1-Row. MUSS als
+     *  `tenantIdOverride` an `systemWriteAs` durchgereicht werden, sonst
+     *  sucht der Event-Store-Executor den Stream im falschen Tenant und
+     *  liefert `version_conflict`. */
+    readonly streamTenantId: string;
+    readonly roles: readonly string[];
+};
+/** Read-shape eines Tenant-Eintrags wie an Seed-Helpers exposed. */
+export type SeedTenantRow = {
+    readonly id: string;
+    readonly name: string;
+    readonly tenantKey: string;
+};
+export type SeedMigrationContext = {
+    /** Event-Store-konformer Write via existing write-handler. System-User
+     *  als Executor bypassed Access-Check (Standard-Seed-Pattern). Events
+     *  haben inserted_by_id = SYSTEM_TENANT_ID-User → audit-fähig.
+     *
+     *  Typ-Signatur folgt existing ctx.writeAs (payload als unknown) — Type-
+     *  Safety kommt über handler-spezifische Wrapper im Aufrufer ("ich weiß
+     *  was updateMemberRoles braucht"). Versucht NICHT Generic-Magic.
+     *
+     *  **tenantIdOverride (Phase 1.5):** wenn das Ziel-Aggregate in einem
+     *  spezifischen Tenant-Stream lebt (nicht SYSTEM_TENANT_ID, was Default
+     *  ist), MUSS der Caller die Stream-tenantId mitgeben — sonst sucht der
+     *  Event-Store-Executor den Aggregate-Stream gegen `SYSTEM_TENANT_ID`
+     *  und liefert `version_conflict` (siehe Memory
+     *  `feedback_event_store_tenant_consistency.md` + Driver-Use-Case
+     *  publicstatus-admin-roles in `project_es_ops_phase1_retro.md`).
+     *
+     *  Typische Pattern:
+     *    - System-scope-Aggregate (config-values, system text-content) →
+     *      tenantIdOverride weglassen (Default SYSTEM_TENANT_ID).
+     *    - Tenant-scope-Aggregate (memberships, tenant-config, app-data) →
+     *      `tenantIdOverride: m.tenantId` (oder den Stream-Tenant aus
+     *      einem find*-Helper).
+     *
+     *  **extraRoles:** hasAccess has no system-bypass — a handler with an
+     *  explicit role gate (e.g. `access: { roles: ["SystemAdmin"] }` or
+     *  `["anonymous"]`) otherwise rejects the bare `system` actor with
+     *  `access_denied`. Pass the required role(s) here — see
+     *  `createSystemUser`'s `extraRoles` doc. */
+    readonly systemWriteAs: (handlerQualifiedName: string, payload: unknown, tenantIdOverride?: TenantId, extraRoles?: readonly string[]) => Promise<WriteResult>;
+    readonly findUserByEmail: (email: string) => Promise<SeedUserRow | null>;
+    readonly findMembershipsOfUser: (userId: string) => Promise<readonly SeedMembershipRow[]>;
+    readonly findTenants: () => Promise<readonly SeedTenantRow[]>;
+    /** Escape-Hatch — direkter DB-Zugang. Nur für READ-only Lookups die der
+     *  Context nicht standard-mäßig anbietet. WRITES via systemWriteAs!
+     *  Type ist DbRunner (Connection oder aktive Tx) weil der Runner den
+     *  Context pro-Migration im Tx-Scope erzeugt. */
+    readonly db: DbRunner;
+};

package/dist/es-ops/types.js

@@ -0,0 +1,14 @@
+// Public API für seed-migrations. Files in /seeds/<date>-<slug>.ts
+// exportieren ein default-Object dieses Typs. Runner ruft `run(ctx)` in
+// chronologischer Reihenfolge auf, einmal pro App-Boot (track in
+// kumiko_es_operations).
+//
+// API-Stabilität: Phase 1 ist "minimal-viable". Helper am Context
+// (findUserByEmail, etc.) wachsen on-demand — wenn eine real-Migration
+// einen Lookup braucht den der Context nicht anbietet, fügen wir ihn
+// dort hinzu. Das vermeidet "wir-bauen-alle-möglichen-Helper-spekulativ".
+//
+// ctx.db als Escape-Hatch ist erlaubt für READ-only lookups. WRITES
+// IMMER via ctx.systemWriteAs damit Event-Store-Invariants bleiben
+// (Source-of-Truth + Projection läuft automatisch).
+export {};

package/dist/event-store/admin-api.d.ts

@@ -0,0 +1,17 @@
+import type { DbRunner } from "../db/index.js";
+import type { TenantId } from "../engine/types/index.js";
+import type { EventMetadata } from "./event-store.js";
+export type RawEventToAppend = {
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly tenantId: TenantId;
+    readonly expectedVersion: number;
+    readonly type: string;
+    readonly eventVersion?: number;
+    readonly payload: Record<string, unknown>;
+    readonly metadata: EventMetadata;
+    readonly createdAt: Temporal.Instant;
+    readonly createdBy: string;
+};
+export declare function appendRaw(runner: DbRunner, event: RawEventToAppend): Promise<void>;
+export declare function appendRawBatch(runner: DbRunner, events: readonly RawEventToAppend[]): Promise<void>;

package/dist/event-store/admin-api.js

@@ -0,0 +1,173 @@
+// Event-Store Admin-API — Marten-Bypass für Legacy-Daten-Importe.
+// Spec + Verhalten: docs/plans/features/event-store-admin-api.md
+//
+// Guard-Rail: dieses Modul ist NICHT aus event-store/index.ts re-exportiert.
+// Import nur via deep-path `@cosmicdrift/kumiko-framework/event-store/admin-api`. Das
+// Guard-Script `scripts/guard-admin-api.ts` blockt Aufrufe aus App-Code —
+// Allowlist: samples/*/migration/, scripts/migrations/, die Definition
+// selbst, das Guard-Script selbst.
+import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
+import { claimXactId } from "../db/queries/event-store.js";
+import { eventPredecessorExists, findExistingEventVersion, insertRawEventBatch, insertRawFirstEvent, insertRawSubsequentEvent, } from "../db/queries/event-store-admin.js";
+import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
+function mapEventUniqueViolation(e, event) {
+    if (constraintOf(e) === "events_idempotency_uq" && event.metadata.idempotencyKey) {
+        return new IdempotentAppendConflictError(event.tenantId, event.metadata.idempotencyKey);
+    }
+    return new VersionConflictError(event.aggregateId, event.expectedVersion);
+}
+// Mirrors append()'s two-path structure: typed builder equivalent for v=0,
+// INSERT … SELECT … WHERE EXISTS gate for v>0. Caller-supplied createdAt +
+// createdBy skip the usual userResolver/now() paths.
+export async function appendRaw(runner, event) {
+    const newVersion = event.expectedVersion + 1;
+    const eventVersion = event.eventVersion ?? 1;
+    try {
+        // See db/queries/event-store.ts's claimXactId — gap-finality needs a
+        // real xact id assigned before this holder's insert.
+        await claimXactId(runner);
+        if (event.expectedVersion === 0) {
+            await insertRawFirst(runner, event, newVersion, eventVersion);
+        }
+        else {
+            await insertRawSubsequent(runner, event, newVersion, eventVersion);
+        }
+    }
+    catch (e) {
+        if (isUniqueViolation(e)) {
+            throw mapEventUniqueViolation(e, event);
+        }
+        throw e;
+    }
+}
+function rawEventParams(event, newVersion, eventVersion) {
+    return {
+        aggregateId: event.aggregateId,
+        aggregateType: event.aggregateType,
+        tenantId: event.tenantId,
+        newVersion,
+        type: event.type,
+        eventVersion,
+        payload: event.payload,
+        metadata: event.metadata,
+        createdAt: event.createdAt.toString(),
+        createdBy: event.createdBy,
+    };
+}
+async function insertRawFirst(runner, event, newVersion, eventVersion) {
+    await insertRawFirstEvent(runner, rawEventParams(event, newVersion, eventVersion));
+}
+async function insertRawSubsequent(runner, event, newVersion, eventVersion) {
+    const inserted = await insertRawSubsequentEvent(runner, {
+        ...rawEventParams(event, newVersion, eventVersion),
+        expectedVersion: event.expectedVersion,
+    });
+    if (!inserted) {
+        throw new VersionConflictError(event.aggregateId, event.expectedVersion);
+    }
+}
+// Batch append. One multi-VALUES INSERT — atomic by PG statement semantics.
+// Three pre-flight checks identify the specific conflicting aggregate, so the
+// thrown VersionConflictError points at a real event (not at a batch-first
+// placeholder). The INSERT's UNIQUE constraint is still the authoritative
+// gate — pre-flight is for diagnostic precision, not correctness.
+export async function appendRawBatch(runner, events) {
+    const firstEvent = events[0];
+    // skip: empty batch is a no-op by contract — callers that chunk a stream
+    // into size-N batches shouldn't need to guard the tail-case themselves.
+    if (!firstEvent)
+        return;
+    verifyContiguousWithinBatch(events);
+    await verifyPredecessors(runner, events);
+    await verifyNoDuplicates(runner, events);
+    const params = [];
+    const valuesClauses = events.map((e) => {
+        const newVersion = e.expectedVersion + 1;
+        const eventVersion = e.eventVersion ?? 1;
+        const baseIdx = params.length;
+        params.push(e.aggregateId, e.aggregateType, e.tenantId, newVersion, e.type, eventVersion, e.payload, e.metadata, e.createdAt.toString(), e.createdBy);
+        return `($${baseIdx + 1}::uuid, $${baseIdx + 2}, $${baseIdx + 3}::uuid, $${baseIdx + 4}, $${baseIdx + 5}, $${baseIdx + 6}, $${baseIdx + 7}::jsonb, $${baseIdx + 8}::jsonb, $${baseIdx + 9}::timestamptz, $${baseIdx + 10})`;
+    });
+    try {
+        await claimXactId(runner);
+        await insertRawEventBatch(runner, valuesClauses.join(", "), params);
+    }
+    catch (e) {
+        if (isUniqueViolation(e)) {
+            // Pre-flight ran but lost a race against a concurrent writer. Rare for
+            // migration (single-runner) but possible; we can't name the exact row.
+            throw mapEventUniqueViolation(e, firstEvent);
+        }
+        throw e;
+    }
+}
+// Defense-in-depth against a buggy event-mapper: within one batch, for each
+// aggregate the expectedVersion sequence must be contiguous (no gaps). Without
+// this, [expectedVersion=0, expectedVersion=2] for the same aggregate would
+// write v=1 and v=3 with v=2 missing — UNIQUE won't catch it (no collision),
+// predecessor-EXISTS won't catch it (min is 0, check skipped), and the
+// orphan only surfaces at projection-rebuild time. Fail-loud here instead.
+function verifyContiguousWithinBatch(events) {
+    const byAggregate = new Map();
+    for (const e of events) {
+        const key = `${e.tenantId}:${e.aggregateId}`;
+        const list = byAggregate.get(key) ?? [];
+        list.push(e);
+        byAggregate.set(key, list);
+    }
+    for (const list of byAggregate.values()) {
+        if (list.length < 2)
+            continue;
+        const sorted = [...list].sort((a, b) => a.expectedVersion - b.expectedVersion);
+        const [first, ...rest] = sorted;
+        if (!first)
+            continue;
+        let prev = first;
+        for (const curr of rest) {
+            if (curr.expectedVersion !== prev.expectedVersion + 1) {
+                throw new VersionConflictError(curr.aggregateId, curr.expectedVersion);
+            }
+            prev = curr;
+        }
+    }
+}
+// Per aggregate-group, check the predecessor (min(expectedVersion) > 0)
+// exists in the DB. For migration batches that are usually single-aggregate
+// or fresh-stream, this loops zero or one times.
+async function verifyPredecessors(runner, events) {
+    const groups = new Map();
+    for (const e of events) {
+        const key = `${e.tenantId}:${e.aggregateId}`;
+        const existing = groups.get(key);
+        if (!existing || e.expectedVersion < existing.minExpected) {
+            groups.set(key, {
+                tenantId: e.tenantId,
+                aggregateId: e.aggregateId,
+                minExpected: e.expectedVersion,
+            });
+        }
+    }
+    for (const g of groups.values()) {
+        if (g.minExpected === 0)
+            continue;
+        const present = await eventPredecessorExists(runner, g.aggregateId, g.tenantId, g.minExpected);
+        if (!present) {
+            throw new VersionConflictError(g.aggregateId, g.minExpected);
+        }
+    }
+}
+// Single IN-query checks whether any (tenant, aggregate, newVersion) tuple
+// already exists. Returns the first collision, so the thrown error names
+// the real conflicting aggregate instead of the batch's first event.
+async function verifyNoDuplicates(runner, events) {
+    const params = [];
+    const tripleClauses = events.map((e) => {
+        const baseIdx = params.length;
+        params.push(e.tenantId, e.aggregateId, e.expectedVersion + 1);
+        return `($${baseIdx + 1}::uuid, $${baseIdx + 2}::uuid, $${baseIdx + 3})`;
+    });
+    const conflict = await findExistingEventVersion(runner, tripleClauses.join(", "), params);
+    if (conflict) {
+        throw new VersionConflictError(conflict.aggregateId, conflict.version - 1);
+    }
+}

package/dist/event-store/archive.d.ts

@@ -0,0 +1,14 @@
+import type { DbConnection, DbRunner } from "../db/connection.js";
+import type { TenantId } from "../engine/types/index.js";
+export declare const archivedStreamsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare function createArchivedStreamsTable(db: DbConnection): Promise<void>;
+export type ArchiveStreamArgs = {
+    readonly tenantId: TenantId;
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly archivedBy: string;
+    readonly reason?: string;
+};
+export declare function archiveStream(db: DbRunner, args: ArchiveStreamArgs): Promise<void>;
+export declare function isStreamArchived(db: DbRunner, tenantId: TenantId, aggregateId: string): Promise<boolean>;
+export declare function restoreStream(db: DbRunner, tenantId: TenantId, aggregateId: string): Promise<void>;

package/dist/event-store/archive.js

@@ -0,0 +1,55 @@
+// sql now comes from native dialect
+import { instant, table as pgTable, sql, text, uniqueIndex, uuid } from "../db/dialect.js";
+import { upsertArchivedStream } from "../db/queries/event-store.js";
+import { deleteMany, fetchOne } from "../db/query.js";
+import { tableExists } from "../db/schema-inspection.js";
+import { unsafePushTables } from "../stack/index.js";
+// Marten-aligned stream archival. Archived streams become read-only: fresh
+// appendEvent on an archived aggregate throws, and loadAggregate returns
+// an empty slice unless the caller passes { includeArchived: true }.
+//
+// Storage: sparse table — only ARCHIVED streams have a row. Active streams
+// stay out of this table to keep the hot path free of extra writes. A
+// tenant-scoped PK guards against cross-tenant reuse of aggregate IDs.
+export const archivedStreamsTable = pgTable("kumiko_archived_streams", {
+    tenantId: uuid("tenant_id").notNull(),
+    aggregateId: uuid("aggregate_id").notNull(),
+    aggregateType: text("aggregate_type").notNull(),
+    archivedAt: instant("archived_at", { precision: 3 }).notNull().default(sql `now()`),
+    archivedBy: text("archived_by").notNull(),
+    reason: text("reason"),
+}, (t) => ({
+    pk: uniqueIndex("kumiko_archived_streams_pk").on(t.tenantId, t.aggregateId),
+}));
+// guard:dup-ok — intentionale Parallele zu createSnapshotsTable; verschiedene Tabellen-Schemas by design
+export async function createArchivedStreamsTable(db) {
+    // skip: table already exists — idempotent boot + test-setup call
+    if (await tableExists(db, "public.kumiko_archived_streams"))
+        return;
+    await unsafePushTables(db, { kumikoArchivedStreams: archivedStreamsTable });
+}
+// Mark a stream as archived. Idempotent — re-archiving (same tenant +
+// aggregate) updates archivedAt/archivedBy to the latest call instead of
+// failing. That matches Marten's "archive is a state, not an event" model.
+export async function archiveStream(db, args) {
+    await upsertArchivedStream(db, {
+        tenantId: args.tenantId,
+        aggregateId: args.aggregateId,
+        aggregateType: args.aggregateType,
+        archivedBy: args.archivedBy,
+        reason: args.reason ?? null,
+    });
+}
+// Cheap existence probe — issued in the hot read path, so keep the query to
+// a single indexed lookup on the composite PK.
+export async function isStreamArchived(db, tenantId, aggregateId) {
+    const row = await fetchOne(db, archivedStreamsTable, { tenantId, aggregateId });
+    return row !== undefined;
+}
+// Undo an archive — restores the stream to writable state. Ops tool. The
+// historical archivedAt is lost; if auditing needs the archive-history,
+// use domain events on the aggregate (e.g. "stream.archived" / "stream.
+// restored") instead of relying on this row.
+export async function restoreStream(db, tenantId, aggregateId) {
+    await deleteMany(db, archivedStreamsTable, { tenantId, aggregateId });
+}

package/dist/event-store/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class VersionConflictError extends Error {
+    readonly aggregateId: string;
+    readonly expectedVersion: number;
+    constructor(aggregateId: string, expectedVersion: number);
+}
+export declare class IdempotentAppendConflictError extends Error {
+    readonly tenantId: string;
+    readonly idempotencyKey: string;
+    constructor(tenantId: string, idempotencyKey: string);
+}
+export declare class ArchivedStreamError extends Error {
+    readonly tenantId: string;
+    readonly aggregateId: string;
+    constructor(tenantId: string, aggregateId: string);
+}