feat(FN-4218): complete Steps 2-5 — schema, store, tests, and docs

Fusion-Task-Id: FN-4218
Fusion-Task-Lineage: 0b50d7f4-5001-4eb6-9633-7b24b00097fd

packages/core/src/__tests__/db.test.ts

@@ -290,7 +290,7 @@ describe("Database", () => {
     });
 
     it("seeds schema version", () => {
-      expect(db.getSchemaVersion()).toBe(74);
+      expect(db.getSchemaVersion()).toBe(75);
     });
 
     it("includes tokenUsageCacheWriteTokens on freshly initialized tasks table", () => {
@@ -318,7 +318,7 @@ describe("Database", () => {
 
     it("is idempotent - calling init() twice does not fail", () => {
       expect(() => db.init()).not.toThrow();
-      expect(db.getSchemaVersion()).toBe(74);
+      expect(db.getSchemaVersion()).toBe(75);
     });
     it("does not overwrite existing config on re-init", () => {
       // Update the config
@@ -1383,7 +1383,7 @@ describe("schema migrations", () => {
     db.init();
 
     // Verify version bumped to 29 (includes v1→v2 through v26→v29)
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     // Verify new columns exist and existing data is intact
     const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
@@ -1408,11 +1408,11 @@ describe("schema migrations", () => {
     const db = new Database(fusionDir);
     db.init();
 
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     // Re-init should not fail
     db.init();
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     db.close();
   });
@@ -1447,7 +1447,7 @@ describe("schema migrations", () => {
 
     db.init();
 
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
     expect(cols.map((col) => col.name)).toContain("priority");
@@ -1488,7 +1488,7 @@ describe("schema migrations", () => {
 
     db.init();
 
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
     const colNames = cols.map((col) => col.name);
@@ -1560,7 +1560,7 @@ describe("schema migrations", () => {
 
     db.init();
 
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
     const colNames = cols.map((col) => col.name);
@@ -1800,7 +1800,7 @@ describe("schema migrations", () => {
 
     db.init();
 
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     const cols = db.prepare("PRAGMA table_info(chat_messages)").all() as Array<{ name: string }>;
     expect(cols.map((col) => col.name)).toContain("attachments");
@@ -1874,7 +1874,7 @@ describe("schema migrations", () => {
 
     db.init();
 
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = 'agentRatings'").all() as Array<{ name: string }>;
     expect(tables).toEqual([{ name: "agentRatings" }]);
@@ -1898,7 +1898,7 @@ describe("schema migrations", () => {
 
     db.init();
 
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = 'mission_events'").all() as Array<{ name: string }>;
     expect(tables).toEqual([{ name: "mission_events" }]);
@@ -2002,7 +2002,7 @@ describe("schema migrations", () => {
     db.init();
 
     // Verify version bumped to 29
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     // Verify new columns exist and existing data is intact
     const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
@@ -2221,7 +2221,7 @@ describe("schema migrations", () => {
 
     localDb.init();
 
-    expect(localDb.getSchemaVersion()).toBe(74);
+    expect(localDb.getSchemaVersion()).toBe(75);
     const columns = localDb.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
     expect(columns.map((column) => column.name)).toContain("tokenUsageCacheWriteTokens");
 
@@ -2532,7 +2532,7 @@ describe("createDatabase factory", () => {
     const db = createDatabase(fusionDir);
     db.init();
 
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
     expect(db.getLastModified()).toBeGreaterThan(0);
 
     db.close();
@@ -2668,7 +2668,7 @@ describe("migration v67 drops orphan project auth tables", () => {
 
       migrated = new Database(fusion);
       migrated.init();
-      expect(migrated.getSchemaVersion()).toBe(74);
+      expect(migrated.getSchemaVersion()).toBe(75);
       const tables = migrated
         .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'project_auth_%'")
         .all() as Array<{ name: string }>;
@@ -2695,7 +2695,7 @@ describe("migration v67 drops orphan project auth tables", () => {
 
     try {
       fresh.init();
-      expect(fresh.getSchemaVersion()).toBe(74);
+      expect(fresh.getSchemaVersion()).toBe(75);
       const tables = fresh
         .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'project_auth_%'")
         .all() as Array<{ name: string }>;

packages/core/src/__tests__/experiment-session-store.test.ts

@@ -0,0 +1,171 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createDatabase, type Database } from "../db.js";
+import { ExperimentSessionStore } from "../experiment-session-store.js";
+
+describe("ExperimentSessionStore", () => {
+  let db: Database;
+  let store: ExperimentSessionStore;
+
+  beforeEach(() => {
+    const fusionDir = mkdtempSync(join(tmpdir(), "fn-experiment-test-"));
+    db = createDatabase(fusionDir, { inMemory: true });
+    db.init();
+    store = new ExperimentSessionStore(db);
+  });
+
+  it("creates schema tables and indexes and cascades session deletes", () => {
+    const tables = db
+      .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('experiment_sessions', 'experiment_session_records')")
+      .all() as Array<{ name: string }>;
+    expect(tables.map((row) => row.name).sort()).toEqual(["experiment_session_records", "experiment_sessions"]);
+
+    const sessionIndexes = db.prepare("PRAGMA index_list(experiment_sessions)").all() as Array<{ name: string }>;
+    expect(sessionIndexes.map((row) => row.name)).toEqual(
+      expect.arrayContaining([
+        "idxExperimentSessionsStatus",
+        "idxExperimentSessionsProject",
+        "idxExperimentSessionsCreatedAt",
+      ]),
+    );
+
+    const recordIndexes = db.prepare("PRAGMA index_list(experiment_session_records)").all() as Array<{ name: string }>;
+    expect(recordIndexes.map((row) => row.name)).toEqual(
+      expect.arrayContaining(["idxExperimentRecordsSessionSegment", "idxExperimentRecordsType"]),
+    );
+
+    const session = store.createSession({ name: "S1", metric: { name: "latency", direction: "minimize" } });
+    store.appendRecord(session.id, {
+      type: "run",
+      payload: { primaryMetric: 100, secondaryMetrics: [], status: "pending" },
+    });
+    expect(store.deleteSession(session.id)).toBe(true);
+    const count = db.prepare("SELECT COUNT(*) as c FROM experiment_session_records").get() as { c: number };
+    expect(count.c).toBe(0);
+  });
+
+  it("supports session CRUD, status/finalized events, and list filters", () => {
+    const onStatus = vi.fn();
+    const onFinalized = vi.fn();
+    store.on("session:status_changed", onStatus);
+    store.on("session:finalized", onFinalized);
+
+    const s1 = store.createSession({
+      name: "alpha bench",
+      projectId: "proj-a",
+      metric: { name: "throughput", direction: "maximize" },
+      tags: ["perf", "ci"],
+    });
+    const s2 = store.createSession({
+      name: "beta stability",
+      projectId: "proj-b",
+      status: "finalizing",
+      metric: { name: "latency", direction: "minimize" },
+      tags: ["stability"],
+      workingDir: "apps/api",
+    });
+
+    expect(store.getSession(s1.id)?.name).toBe("alpha bench");
+    expect(store.listSessions({ projectId: "proj-a" }).map((s) => s.id)).toEqual([s1.id]);
+    expect(store.listSessions({ status: "finalizing" }).map((s) => s.id)).toEqual([s2.id]);
+    expect(store.listSessions({ tag: "perf" }).map((s) => s.id)).toEqual([s1.id]);
+    expect(store.listSessions({ search: "api" }).map((s) => s.id)).toEqual([s2.id]);
+
+    const finalized = store.updateSession(s1.id, { status: "finalized" });
+    expect(finalized.finalizedAt).toBeTruthy();
+    expect(onStatus).toHaveBeenCalledTimes(1);
+    expect(onFinalized).toHaveBeenCalledTimes(1);
+
+    expect(store.deleteSession(s2.id)).toBe(true);
+    expect(store.getSession(s2.id)).toBeUndefined();
+  });
+
+  it("maintains contiguous seq per session under interleaved appends", () => {
+    const a = store.createSession({ name: "A", metric: { name: "m", direction: "maximize" } });
+    const b = store.createSession({ name: "B", metric: { name: "m", direction: "maximize" } });
+
+    store.appendRecord(a.id, { type: "run", payload: { primaryMetric: 1, secondaryMetrics: [], status: "pending" } });
+    store.appendRecord(b.id, { type: "run", payload: { primaryMetric: 2, secondaryMetrics: [], status: "pending" } });
+    store.appendRecord(a.id, { type: "run", payload: { primaryMetric: 3, secondaryMetrics: [], status: "keep" } });
+    store.appendRecord(b.id, { type: "run", payload: { primaryMetric: 4, secondaryMetrics: [], status: "discard" } });
+
+    expect(store.listRecords(a.id).map((r) => r.seq)).toEqual([1, 2]);
+    expect(store.listRecords(b.id).map((r) => r.seq)).toEqual([1, 2]);
+  });
+
+  it("starts new segments and appends config record in new segment", () => {
+    const session = store.createSession({ name: "seg", metric: { name: "x", direction: "maximize" } });
+    const { session: updated, record } = store.startNewSegment(session.id, {
+      metric: { name: "x", direction: "maximize" },
+      maxIterations: 20,
+    });
+    expect(updated.currentSegment).toBe(2);
+    expect(record.type).toBe("config");
+    expect(record.segment).toBe(2);
+
+    const run = store.appendRecord(session.id, {
+      type: "run",
+      payload: { primaryMetric: 5, secondaryMetrics: [], status: "pending" },
+    });
+    expect(run.segment).toBe(2);
+  });
+
+  it.each([
+    ["config", { metric: { name: "t", direction: "maximize" } }],
+    ["run", { primaryMetric: 1, secondaryMetrics: [{ name: "cpu", value: 2 }], status: "keep", durationMs: 12 }],
+    ["hook", { hook: "after", exitCode: 0, stdout: "ok" }],
+    ["finalize", { keptRunIds: ["r1"], discardedRunIds: ["r2"], summary: "done" }],
+  ] as const)("round-trips %s payloads", (type, payload) => {
+    const session = store.createSession({ name: "rt", metric: { name: "m", direction: "maximize" } });
+    const appended = store.appendRecord(session.id, { type, payload });
+    const listed = store.listRecords(session.id, { type });
+    expect(listed).toHaveLength(1);
+    expect(listed[0]).toEqual(appended);
+    expect(store.getRecord(appended.id)?.payload).toEqual(payload);
+  });
+
+  it("validates baseline/best run pointers and updates pointers", () => {
+    const a = store.createSession({ name: "A", metric: { name: "x", direction: "maximize" } });
+    const b = store.createSession({ name: "B", metric: { name: "x", direction: "maximize" } });
+    const runA = store.appendRecord(a.id, { type: "run", payload: { primaryMetric: 1, secondaryMetrics: [], status: "keep" } });
+    const configA = store.appendRecord(a.id, { type: "config", payload: { metric: { name: "x", direction: "maximize" } } });
+    const runB = store.appendRecord(b.id, { type: "run", payload: { primaryMetric: 2, secondaryMetrics: [], status: "keep" } });
+
+    expect(() => store.setBaselineRun(a.id, "missing")).toThrow(/not found/i);
+    expect(() => store.setBaselineRun(a.id, configA.id)).toThrow(/not a run/i);
+    expect(() => store.setBestRun(a.id, runB.id)).toThrow(/does not belong/i);
+
+    store.setBaselineRun(a.id, runA.id);
+    const updated = store.setBestRun(a.id, runA.id);
+    expect(updated.baselineRunId).toBe(runA.id);
+    expect(updated.bestRunId).toBe(runA.id);
+  });
+
+  it("rejects appends for finalized sessions", () => {
+    const session = store.createSession({ name: "done", metric: { name: "x", direction: "maximize" } });
+    store.updateSession(session.id, { status: "finalized" });
+
+    const onRecord = vi.fn();
+    store.on("record:appended", onRecord);
+    expect(() =>
+      store.appendRecord(session.id, {
+        type: "run",
+        payload: { primaryMetric: 1, secondaryMetrics: [], status: "pending" },
+      }),
+    ).toThrow(/Cannot append record/i);
+    expect(onRecord).not.toHaveBeenCalled();
+  });
+
+  it("recordKept is idempotent", () => {
+    const session = store.createSession({ name: "k", metric: { name: "x", direction: "maximize" } });
+    const run = store.appendRecord(session.id, {
+      type: "run",
+      payload: { primaryMetric: 9, secondaryMetrics: [], status: "keep" },
+    });
+    store.recordKept(session.id, run.id);
+    const updated = store.recordKept(session.id, run.id);
+    expect(updated.keptRunIds).toEqual([run.id]);
+  });
+});

packages/core/src/__tests__/insight-store.test.ts

@@ -886,7 +886,7 @@ describe("Migration: pre-33 DB upgrade", () => {
       // Step 1: Create a fresh database at v33 (runs all migrations up to 33)
       const db1 = createDatabase(legacyDir);
       db1.init();
-      expect(db1.getSchemaVersion()).toBe(74);
+      expect(db1.getSchemaVersion()).toBe(75);
       db1.close();
 
       // Step 2: Manually downgrade to version 32 and drop insight tables
@@ -921,7 +921,7 @@ describe("Migration: pre-33 DB upgrade", () => {
       expect(tableNamesBefore).not.toContain("project_insight_runs");
       // Now run init — this triggers the v32→v33 migration
       db3.init();
-      expect(db3.getSchemaVersion()).toBe(74);
+      expect(db3.getSchemaVersion()).toBe(75);
 
       // Step 4: Verify insight tables exist after migration
       const tablesAfter = db3.prepare(
@@ -952,12 +952,12 @@ describe("Migration: pre-33 DB upgrade", () => {
     try {
       const db1 = createDatabase(testDir);
       db1.init();
-      expect(db1.getSchemaVersion()).toBe(74);
+      expect(db1.getSchemaVersion()).toBe(75);
       db1.close();
 
       const db2 = createDatabase(testDir);
       expect(() => db2.init()).not.toThrow();
-      expect(db2.getSchemaVersion()).toBe(74);
+      expect(db2.getSchemaVersion()).toBe(75);
       db2.close();
     } finally {
       rmSync(testDir, { recursive: true, force: true });
@@ -971,7 +971,7 @@ describe("Migration: pre-33 DB upgrade", () => {
       // Step 1: Create a fresh DB and run migrations
       const db1 = createDatabase(compatDir);
       db1.init();
-      expect(db1.getSchemaVersion()).toBe(74);
+      expect(db1.getSchemaVersion()).toBe(75);
 
       // Step 2: Strip lifecycle and cancelledAt columns by recreating the
       // table without them. This simulates a DB that was created before the

packages/core/src/__tests__/mission-store.test.ts

@@ -2639,7 +2639,7 @@ describe("MissionStore", () => {
 
   describe("Loop State & Validator Run Schema (v31)", () => {
     it("schema version is 40 after migration", () => {
-      expect(db.getSchemaVersion()).toBe(74);
+      expect(db.getSchemaVersion()).toBe(75);
     });
 
     it("mission_features table has loop state columns", () => {

packages/core/src/__tests__/run-audit.test.ts

@@ -584,7 +584,7 @@ describe("Run Audit", () => {
     });
 
     it("schema version is bumped to 40", () => {
-      expect(db.getSchemaVersion()).toBe(74);
+      expect(db.getSchemaVersion()).toBe(75);
     });
   });
 });

packages/core/src/__tests__/task-documents.test.ts

@@ -51,7 +51,7 @@ describe("TaskStore task documents", () => {
 
     expect(tableNames.has("task_documents")).toBe(true);
     expect(tableNames.has("task_document_revisions")).toBe(true);
-    expect(db.getSchemaVersion()).toBe(74);
+    expect(db.getSchemaVersion()).toBe(75);
 
     const index = db
       .prepare(