@cosmicdrift/kumiko-framework 0.1.0

package/src/event-store/__tests__/perf.integration.ts

@@ -0,0 +1,255 @@
+// Event-Store Performance — Gate A targets from the Sprint-B spike.
+// Asserts that today's framework API holds the same latency envelope as
+// the raw-SQL spike used as proof before the ES pivot.
+//
+// Targets (from docs/plans/architecture/event-sourcing-spike-1.md):
+//   - Write-Latency  p99 < 30ms  (append a single event)
+//   - Read-Latency   p99 < 10ms  (loadAggregate for a single aggregate)
+//   - Update-Latency p99 < 30ms  (append with predecessor-check WHERE EXISTS)
+//   - Snapshot-Load < 50ms       (1000-event aggregate, snapshot @ 900)
+//
+// Workload is sequential against local Docker Postgres — no network
+// latency, single-node PG. Production deploys are slower; these numbers
+// are the ceiling. Red test = framework regression, no slack tolerated.
+
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import type { TenantId } from "../../engine/types";
+import { createTestDb, type TestDb } from "../../stack";
+import { generateId as uuid } from "../../utils";
+import {
+  append,
+  createEventsTable,
+  loadAggregate,
+  loadAggregateWithSnapshot,
+  saveSnapshot,
+} from "../index";
+
+let testDb: TestDb;
+const tenantId = uuid() as TenantId;
+const userId = uuid();
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEventsTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(
+    sql`TRUNCATE kumiko_events, kumiko_snapshots, kumiko_archived_streams RESTART IDENTITY CASCADE`,
+  );
+});
+
+function percentile(sorted: readonly number[], p: number): number {
+  const idx = Math.ceil(sorted.length * p) - 1;
+  return sorted[Math.max(0, Math.min(idx, sorted.length - 1))] ?? 0;
+}
+
+async function measure<T>(op: () => Promise<T>): Promise<number> {
+  const start = performance.now();
+  await op();
+  return performance.now() - start;
+}
+
+describe("event-store performance — Gate A", () => {
+  test("write-latency p99 < 30ms over 200 sequential appends", async () => {
+    const samples: number[] = [];
+
+    // Warm-up — Connection-Pool + Drizzle-Prepare-Overhead
+    for (let i = 0; i < 10; i++) {
+      await append(testDb.db, {
+        aggregateId: uuid(),
+        aggregateType: "task",
+        tenantId,
+        expectedVersion: 0,
+        type: "task.created",
+        payload: { title: `warm ${i}` },
+        metadata: { userId },
+      });
+    }
+
+    for (let i = 0; i < 200; i++) {
+      const aggregateId = uuid();
+      samples.push(
+        await measure(() =>
+          append(testDb.db, {
+            aggregateId,
+            aggregateType: "task",
+            tenantId,
+            expectedVersion: 0,
+            type: "task.created",
+            payload: { title: `sample ${i}` },
+            metadata: { userId },
+          }),
+        ),
+      );
+    }
+
+    samples.sort((a, b) => a - b);
+    const p50 = percentile(samples, 0.5);
+    const p99 = percentile(samples, 0.99);
+    console.log(`  Write-latency: p50=${p50.toFixed(2)}ms, p99=${p99.toFixed(2)}ms (n=200)`);
+
+    expect(p99).toBeLessThan(30);
+  });
+
+  test("read-latency p99 < 10ms for loadAggregate detail reads", async () => {
+    // Seed 200 single-event aggregates
+    const ids: string[] = [];
+    for (let i = 0; i < 200; i++) {
+      const aggregateId = uuid();
+      await append(testDb.db, {
+        aggregateId,
+        aggregateType: "task",
+        tenantId,
+        expectedVersion: 0,
+        type: "task.created",
+        payload: { title: `read ${i}` },
+        metadata: { userId },
+      });
+      ids.push(aggregateId);
+    }
+
+    // Warm-up
+    for (const id of ids.slice(0, 10)) {
+      await loadAggregate(testDb.db, id, tenantId);
+    }
+
+    const samples: number[] = [];
+    for (const id of ids) {
+      samples.push(await measure(() => loadAggregate(testDb.db, id, tenantId)));
+    }
+
+    samples.sort((a, b) => a - b);
+    const p50 = percentile(samples, 0.5);
+    const p99 = percentile(samples, 0.99);
+    console.log(
+      `  Read-latency:  p50=${p50.toFixed(2)}ms, p99=${p99.toFixed(2)}ms (n=${ids.length})`,
+    );
+
+    expect(p99).toBeLessThan(10);
+  });
+
+  test("update-latency p99 < 30ms — exercises predecessor-check WHERE EXISTS path", async () => {
+    // Single aggregate, repeated updates — the INSERT … SELECT … WHERE EXISTS
+    // path is heavier than a simple create and adds an index lookup.
+    const aggregateId = uuid();
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "task",
+      tenantId,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "target" },
+      metadata: { userId },
+    });
+    let version = 1;
+
+    // Warm-up
+    for (let i = 0; i < 10; i++) {
+      await append(testDb.db, {
+        aggregateId,
+        aggregateType: "task",
+        tenantId,
+        expectedVersion: version,
+        type: "task.updated",
+        payload: { title: `warm ${i}` },
+        metadata: { userId },
+      });
+      version++;
+    }
+
+    const samples: number[] = [];
+    for (let i = 0; i < 200; i++) {
+      const current = version;
+      samples.push(
+        await measure(() =>
+          append(testDb.db, {
+            aggregateId,
+            aggregateType: "task",
+            tenantId,
+            expectedVersion: current,
+            type: "task.updated",
+            payload: { title: `sample ${i}` },
+            metadata: { userId },
+          }),
+        ),
+      );
+      version++;
+    }
+
+    samples.sort((a, b) => a - b);
+    const p50 = percentile(samples, 0.5);
+    const p99 = percentile(samples, 0.99);
+    console.log(`  Update-latency: p50=${p50.toFixed(2)}ms, p99=${p99.toFixed(2)}ms (n=200)`);
+
+    expect(p99).toBeLessThan(30);
+  });
+
+  test("snapshot-load < 50ms for 1000-event aggregate (Gate A)", async () => {
+    // Bulk-seed 1000 events via direct SQL insert — 1000 sequential
+    // append() calls would take minutes. We measure the
+    // loadAggregateWithSnapshot performance on a finished stream, not
+    // the seed phase.
+    const aggregateId = uuid();
+    await testDb.db.execute(sql`
+      INSERT INTO kumiko_events (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
+      SELECT ${aggregateId}::uuid, 'task', ${tenantId}::uuid, 1, 'task.created',
+             jsonb_build_object('title', 'v1'),
+             jsonb_build_object('userId', ${userId}::text),
+             ${userId}::text;
+    `);
+    await testDb.db.execute(sql`
+      INSERT INTO kumiko_events (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
+      SELECT ${aggregateId}::uuid, 'task', ${tenantId}::uuid, gs.v, 'task.updated',
+             jsonb_build_object('title', 'v' || gs.v),
+             jsonb_build_object('userId', ${userId}::text),
+             ${userId}::text
+        FROM generate_series(2, 1000) gs(v);
+    `);
+
+    // Snapshot @ version 900 — typische Policy: snapshot every N events
+    await saveSnapshot(testDb.db, {
+      aggregateId,
+      tenantId,
+      aggregateType: "task",
+      version: 900,
+      state: { title: "v900", version: 900 },
+    });
+
+    type TaskState = { title: string; version: number };
+    const reducer = (state: TaskState, evt: { payload: Record<string, unknown> }): TaskState => ({
+      ...state,
+      title: (evt.payload["title"] as string) ?? state.title,
+    });
+
+    // Warm-up
+    await loadAggregateWithSnapshot<TaskState>(testDb.db, aggregateId, tenantId, reducer, {
+      title: "",
+      version: 0,
+    });
+
+    const start = performance.now();
+    const result = await loadAggregateWithSnapshot<TaskState>(
+      testDb.db,
+      aggregateId,
+      tenantId,
+      reducer,
+      { title: "", version: 0 },
+    );
+    const durationMs = performance.now() - start;
+
+    expect(result.snapshotHit).toBe(true);
+    expect(result.version).toBe(1000);
+    expect(result.state.title).toBe("v1000");
+    console.log(
+      `  Snapshot-load (1000-event aggregate, 100 delta events): ${durationMs.toFixed(1)}ms`,
+    );
+
+    expect(durationMs).toBeLessThan(50);
+  });
+});

package/src/event-store/__tests__/snapshot.integration.ts

@@ -0,0 +1,267 @@
+// Sprint E.3 — Snapshot store.
+//
+// Pins three invariants for the framework-internal snapshot surface:
+//   1. saveSnapshot + loadLatestSnapshot round-trip a state.
+//   2. loadAggregateWithSnapshot(snapshot + deltas) yields the same final
+//      state as loadAggregate + full-replay — snapshots stay truthful to
+//      the event log they compress.
+//   3. Performance — a 1000-event aggregate with a snapshot at v900 loads
+//      in < 50ms (typical asOf/reducer rehydrate budget). Same gate the
+//      spike proved on raw SQL, now enforced on the framework path.
+
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import type { TenantId } from "../../engine/types";
+import { createTestDb, type TestDb } from "../../stack";
+import { generateId as uuid } from "../../utils";
+import {
+  append,
+  archiveStream,
+  createEventsTable,
+  loadAggregate,
+  loadAggregateWithSnapshot,
+  loadLatestSnapshot,
+  type SnapshotReducer,
+  saveSnapshot,
+} from "../index";
+
+let testDb: TestDb;
+const tenant = uuid() as TenantId;
+const userId = uuid();
+
+type CounterState = Record<string, unknown> & {
+  readonly count: number;
+  readonly label: string;
+};
+
+const initial: CounterState = { count: 0, label: "init" };
+
+// Tiny reducer: count.incremented → count++, label.set → overwrite label.
+const reducer: SnapshotReducer<CounterState> = (state, event) => {
+  if (event.type === "counter.incremented") {
+    const by = (event.payload["by"] as number | undefined) ?? 1;
+    return { ...state, count: state.count + by };
+  }
+  if (event.type === "counter.label-set") {
+    return { ...state, label: event.payload["label"] as string };
+  }
+  return state;
+};
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEventsTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(
+    sql`TRUNCATE kumiko_events, kumiko_snapshots, kumiko_archived_streams RESTART IDENTITY`,
+  );
+});
+
+// Append N increment events to a fresh aggregate. Returns the aggregate id.
+async function seedAggregate(eventCount: number): Promise<string> {
+  const aggId = uuid();
+  for (let i = 0; i < eventCount; i++) {
+    await append(testDb.db, {
+      aggregateId: aggId,
+      aggregateType: "counter",
+      tenantId: tenant,
+      expectedVersion: i,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+  }
+  return aggId;
+}
+
+// Reduce by loading every event through the framework's loadAggregate —
+// the ground truth the snapshot path must match. Using the real API (not
+// raw SQL) keeps the invariant honest: if loadAggregate semantics drift,
+// this helper shifts with them.
+async function loadFullState(aggregateId: string): Promise<CounterState> {
+  const events = await loadAggregate(testDb.db, aggregateId, tenant);
+  let state: CounterState = initial;
+  for (const event of events) {
+    state = reducer(state, event);
+  }
+  return state;
+}
+
+describe("snapshot-store — round-trip", () => {
+  test("saveSnapshot + loadLatestSnapshot roundtrip the state", async () => {
+    const aggId = uuid();
+    await saveSnapshot(testDb.db, {
+      aggregateId: aggId,
+      tenantId: tenant,
+      aggregateType: "counter",
+      version: 42,
+      state: { count: 100, label: "checkpoint" },
+    });
+
+    const loaded = await loadLatestSnapshot<CounterState>(testDb.db, aggId, tenant);
+    expect(loaded).not.toBeNull();
+    expect(loaded?.version).toBe(42);
+    expect(loaded?.state).toEqual({ count: 100, label: "checkpoint" });
+    expect(loaded?.aggregateType).toBe("counter");
+  });
+
+  test("saveSnapshot is idempotent — re-snapshotting the same version upserts", async () => {
+    const aggId = uuid();
+    await saveSnapshot(testDb.db, {
+      aggregateId: aggId,
+      tenantId: tenant,
+      aggregateType: "counter",
+      version: 10,
+      state: { count: 10, label: "v1" },
+    });
+    await saveSnapshot(testDb.db, {
+      aggregateId: aggId,
+      tenantId: tenant,
+      aggregateType: "counter",
+      version: 10,
+      state: { count: 10, label: "v2-updated" },
+    });
+    const loaded = await loadLatestSnapshot<CounterState>(testDb.db, aggId, tenant);
+    expect(loaded?.state.label).toBe("v2-updated");
+  });
+
+  test("loadLatestSnapshot picks the highest version when multiple exist", async () => {
+    const aggId = uuid();
+    for (const v of [5, 50, 20, 100, 75]) {
+      await saveSnapshot(testDb.db, {
+        aggregateId: aggId,
+        tenantId: tenant,
+        aggregateType: "counter",
+        version: v,
+        state: { count: v * 2, label: `at-${v}` },
+      });
+    }
+    const loaded = await loadLatestSnapshot<CounterState>(testDb.db, aggId, tenant);
+    expect(loaded?.version).toBe(100);
+    expect(loaded?.state.label).toBe("at-100");
+  });
+});
+
+describe("snapshot-store — loadAggregateWithSnapshot", () => {
+  test("snapshot + delta replay equals full replay", async () => {
+    const aggId = await seedAggregate(50);
+    // Seeded aggregate has 50 increment events — state at v40 is count=40.
+    // Snapshot MUST reflect that truth; otherwise the "snapshot + deltas =
+    // full replay" invariant is meaningless.
+    const partial = { count: 40, label: "snap-at-40" };
+    await saveSnapshot(testDb.db, {
+      aggregateId: aggId,
+      tenantId: tenant,
+      aggregateType: "counter",
+      version: 40,
+      state: partial,
+    });
+
+    const full = await loadFullState(aggId);
+    const snapBased = await loadAggregateWithSnapshot<CounterState>(
+      testDb.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+    );
+    expect(snapBased.snapshotHit).toBe(true);
+    expect(snapBased.version).toBe(50);
+    expect(snapBased.state.count).toBe(full.count);
+    expect(snapBased.state.count).toBe(50);
+  });
+
+  test("no snapshot → falls back to full replay (snapshotHit=false)", async () => {
+    const aggId = await seedAggregate(20);
+    const full = await loadFullState(aggId);
+    const snapBased = await loadAggregateWithSnapshot<CounterState>(
+      testDb.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+    );
+    expect(snapBased.snapshotHit).toBe(false);
+    expect(snapBased.version).toBe(20);
+    expect(snapBased.state.count).toBe(full.count);
+  });
+
+  test("archived stream returns initial + snapshotHit=false (matches loadAggregate)", async () => {
+    // Archive semantics must be symmetric with loadAggregate — an archived
+    // stream is "gone" from the default read path, regardless of snapshot
+    // presence. Otherwise a snapshot would silently survive a GDPR-style
+    // archival and leak state that the event log hid.
+    const aggId = await seedAggregate(10);
+    await saveSnapshot(testDb.db, {
+      aggregateId: aggId,
+      tenantId: tenant,
+      aggregateType: "counter",
+      version: 10,
+      state: { count: 10, label: "pre-archive" },
+    });
+    await archiveStream(testDb.db, {
+      tenantId: tenant,
+      aggregateId: aggId,
+      aggregateType: "counter",
+      archivedBy: userId,
+    });
+
+    const snapBased = await loadAggregateWithSnapshot<CounterState>(
+      testDb.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+    );
+    expect(snapBased.state).toEqual(initial);
+    expect(snapBased.version).toBe(0);
+    expect(snapBased.snapshotHit).toBe(false);
+
+    // includeArchived opt-in surfaces the snapshot + deltas for ops tooling.
+    const archived = await loadAggregateWithSnapshot<CounterState>(
+      testDb.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+      { includeArchived: true },
+    );
+    expect(archived.snapshotHit).toBe(true);
+    expect(archived.state.count).toBe(10);
+  });
+
+  test("1000-event aggregate with snapshot at v900 loads in under 50ms", async () => {
+    const aggId = await seedAggregate(1000);
+    await saveSnapshot(testDb.db, {
+      aggregateId: aggId,
+      tenantId: tenant,
+      aggregateType: "counter",
+      version: 900,
+      state: { count: 900, label: "snap-at-900" },
+    });
+
+    // Warm cache
+    await loadAggregateWithSnapshot<CounterState>(testDb.db, aggId, tenant, reducer, initial);
+
+    const start = performance.now();
+    const snapBased = await loadAggregateWithSnapshot<CounterState>(
+      testDb.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+    );
+    const elapsedMs = performance.now() - start;
+
+    expect(snapBased.snapshotHit).toBe(true);
+    expect(snapBased.version).toBe(1000);
+    expect(snapBased.state.count).toBe(1000);
+    expect(elapsedMs).toBeLessThan(50);
+  });
+});