pi-mega-compact 0.9.2 → 0.11.0

package/src/store/turns/connection.ts

@@ -0,0 +1,137 @@
+/**
+ * connection.ts — S49 reconciled turns.db connection manager.
+ *
+ * RECONCILIATION (s49-turn-db ∪ master): exposes master's contract-facing
+ * `openTurnDb` / `closeTurnDb` / `closeAllTurnDbs` (consumed by SqliteTurnStore)
+ * AND this branch's value-adds: closed-handle eviction, the MEGACOMPACT_TURNS_DB_PATH
+ * env override, and the one-time main-db → turns.db migration (S49B) run after
+ * schema init. The unified `initTurnSchema` (schema.ts) creates both the
+ * contract tables and the S51/S52 additive shells.
+ *
+ * Separate cache from the main memory store (src/store/sqlite/utils.ts) so a
+ * turn-DB failure can never touch the authoritative memory DB (program §2).
+ * Pi-agnostic (PREVENT-PI-004: node:sqlite in-process, no network).
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { TurnsConfig } from "../../config/turns.js";
+import { initTurnSchema } from "./schema.js";
+import { migrateTurnTablesIfNeeded } from "./migrations.js";
+
+/** Default turns.db filename within a state dir. */
+export const TURNS_DB_FILE = "turns.db";
+
+// Module-level cache, SEPARATE from the memory store's cache. Keyed by the
+// resolved db path (or `:memory:<stateDir>` for in-memory).
+const cache = new Map<string, DatabaseSync>();
+
+/** Resolve the turns.db path (env override wins — tests/DR). */
+export function turnDbPath(stateDir: string): string {
+	const override = process.env.MEGACOMPACT_TURNS_DB_PATH;
+	if (override && override.trim() !== "") return override;
+	return join(stateDir, TURNS_DB_FILE);
+}
+
+/**
+ * Open (or reuse) the isolated turn database connection. Contract-facing
+ * shape consumed by `SqliteTurnStore`. Accepts `dbPath` / `inMemory` overrides
+ * for tests. Runs the unified schema init + the one-time main-db migration.
+ */
+export function openTurnDb(
+	stateDir: string,
+	options?: { dbPath?: string; inMemory?: boolean },
+): DatabaseSync {
+	const resolvedPath =
+		options?.inMemory === true
+			? ":memory:"
+			: (options?.dbPath ?? turnDbPath(stateDir));
+	const cacheKey = options?.inMemory ? `:memory:${stateDir}` : resolvedPath;
+
+	const cached = cache.get(cacheKey);
+	if (cached) {
+		// A closed handle in the cache (test called db.close() directly) would
+		// surface as "database is not open" on reuse. Detect + evict.
+		try {
+			cached.exec("SELECT 1");
+			return cached;
+		} catch {
+			cache.delete(cacheKey);
+		}
+	}
+
+	if (options?.inMemory !== true && !existsSync(stateDir)) {
+		mkdirSync(stateDir, { recursive: true });
+	}
+	const db = new DatabaseSync(resolvedPath);
+	db.exec("PRAGMA journal_mode = WAL");
+	db.exec("PRAGMA foreign_keys = ON");
+	db.exec("PRAGMA busy_timeout = 5000");
+	initTurnSchema(db);
+	// S49B: one-time move of legacy main-db turn tables into turns.db (idempotent,
+	// non-fatal). File-backed only; never runs for the in-memory test backend.
+	if (options?.inMemory !== true && TurnsConfig.TURNS_DB_ENABLED) {
+		migrateTurnTablesIfNeeded(db, stateDir);
+	}
+	cache.set(cacheKey, db);
+	return db;
+}
+
+/**
+ * Back-compat alias for callers (S51 topics store, dashboard routes) that open
+ * a raw DatabaseSync against turns.db to run their own read queries. Equivalent
+ * to `openTurnDb(stateDir)` (file-backed, default path).
+ */
+export function openTurnStore(stateDir: string): DatabaseSync {
+	return openTurnDb(stateDir);
+}
+
+/** Back-compat alias: close the cached file-backed connection for a state dir. */
+export function closeTurnStore(stateDir: string): void {
+	closeTurnDb(stateDir);
+}
+
+/** Close and evict a cached connection. Idempotent. */
+export function closeTurnDb(
+	stateDir: string,
+	options?: { dbPath?: string; inMemory?: boolean },
+): void {
+	const resolvedPath =
+		options?.inMemory === true
+			? ":memory:"
+			: (options?.dbPath ?? turnDbPath(stateDir));
+	const cacheKey = options?.inMemory ? `:memory:${stateDir}` : resolvedPath;
+	const db = cache.get(cacheKey);
+	if (!db) return;
+	db.close();
+	cache.delete(cacheKey);
+}
+
+/** Close all cached connections (test teardown / graceful shutdown). */
+export function closeAllTurnDbs(): void {
+	for (const db of cache.values()) {
+		try {
+			db.close();
+		} catch {
+			// best-effort
+		}
+	}
+	cache.clear();
+}
+
+/**
+ * Run `fn` atomically. SAVEPOINT (not BEGIN) so it nests safely under an outer
+ * transaction. Self-contained (not imported from memory utils) to keep the
+ * reuse seam clean.
+ */
+export function withTx(db: DatabaseSync, fn: () => void): void {
+	db.exec("SAVEPOINT turns_tx");
+	try {
+		fn();
+		db.exec("RELEASE turns_tx");
+	} catch (e) {
+		db.exec("ROLLBACK TO turns_tx");
+		db.exec("RELEASE turns_tx");
+		throw e;
+	}
+}

package/src/store/turns/contract-compliance.test.ts

@@ -0,0 +1,562 @@
+/**
+ * contract-compliance.test.ts — Shared compliance suite for TurnStore.
+ *
+ * Parameterized: takes a factory function and runs every contract assertion
+ * against the produced store. Imported by backend-specific test files to prove
+ * both SqliteTurnStore and InMemoryTurnStore satisfy the same contract.
+ *
+ * Contract guarantees tested:
+ *   1. appendTurn returns a TurnId; getTurn round-trips
+ *   2. appendRecall + listRecall round-trips
+ *   3. query filters compose (AND)
+ *   4. conversationStats aggregates correctly
+ *   5. forkConversation creates fork lineage
+ *   6. asReader cannot append (type-level — verified by compilation)
+ *   7. asWriter cannot prune (type-level — verified by compilation)
+ *   8. asAdmin can prune + checkpoint + restore
+ *   9. checkpoint/restore round-trip is lossless
+ *  10. close() is idempotent
+ *  11. clear() wipes all data
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import type {
+	TurnStore,
+	TurnEntry,
+	TurnRecallEntry,
+	TurnStoreOptions,
+} from "./types.js";
+
+/** Factory function — backend test files provide the concrete constructor. */
+export type StoreFactory = (options: TurnStoreOptions) => TurnStore;
+
+/** Helper: create a valid TurnEntry. */
+function makeTurn(overrides: Partial<TurnEntry> = {}): TurnEntry {
+	return {
+		conversationId: "conv_test1234",
+		sessionId: "sess_abc",
+		turnIndex: 0,
+		role: "assistant",
+		endedAt: Date.now(),
+		...overrides,
+	};
+}
+
+/** Helper: create a valid TurnRecallEntry. */
+function makeRecall(
+	turnId: string,
+	overrides: Partial<TurnRecallEntry> = {},
+): TurnRecallEntry {
+	return {
+		turnId,
+		checkpointId: "ckpt_001",
+		score: 0.85,
+		source: "checkpoint",
+		...overrides,
+	};
+}
+
+/**
+ * Run the full compliance suite against a TurnStore factory.
+ * Backend test files call this with their constructor.
+ */
+export function runComplianceSuite(
+	name: string,
+	factory: StoreFactory,
+	options: TurnStoreOptions,
+): void {
+	describe(`${name} — TurnStore compliance`, () => {
+		let store: TurnStore;
+
+		beforeEach(() => {
+			store = factory(options);
+		});
+
+		afterEach(() => {
+			try {
+				store.asAdmin().clear();
+			} catch {
+				// best-effort
+			}
+			try {
+				store.close();
+			} catch {
+				// best-effort
+			}
+		});
+
+		// ── 1. appendTurn + getTurn round-trip ──────────────────
+
+		it("appendTurn returns a TurnId; getTurn retrieves the entry", () => {
+			const entry = makeTurn({ turnIndex: 0 });
+			const id = store.asWriter().appendTurn(entry);
+			assert.ok(
+				typeof id === "string" && id.length > 0,
+				"TurnId is a non-empty string",
+			);
+
+			const retrieved = store.asReader().getTurn(id);
+			assert.ok(retrieved, "getTurn should return the entry");
+			assert.equal(retrieved!.conversationId, entry.conversationId);
+			assert.equal(retrieved!.turnIndex, entry.turnIndex);
+			assert.equal(retrieved!.role, entry.role);
+		});
+
+		it("appendTurn preserves optional fields", () => {
+			const entry = makeTurn({
+				turnIndex: 1,
+				ctxTokens: 5000,
+				ctxPercent: 0.65,
+				pressureBand: "yellow",
+				model: "claude-sonnet-4",
+			});
+			const id = store.asWriter().appendTurn(entry);
+			const retrieved = store.asReader().getTurn(id);
+			assert.ok(retrieved);
+			assert.equal(retrieved!.ctxTokens, 5000);
+			assert.equal(retrieved!.ctxPercent, 0.65);
+			assert.equal(retrieved!.pressureBand, "yellow");
+			assert.equal(retrieved!.model, "claude-sonnet-4");
+		});
+
+		// ── 2. appendRecall + listRecall round-trip ──────────────
+
+		it("appendRecall + listRecall round-trips", () => {
+			const tid = store.asWriter().appendTurn(makeTurn({ turnIndex: 0 }));
+			const recall = makeRecall(tid, {
+				checkpointId: "ckpt_r1",
+				score: 0.9,
+				source: "cluster_summary",
+			});
+			store.asWriter().appendRecall(recall);
+
+			const results = store.asReader().listRecall(tid);
+			assert.equal(results.length, 1);
+			assert.equal(results[0].checkpointId, "ckpt_r1");
+			assert.equal(results[0].score, 0.9);
+			assert.equal(results[0].source, "cluster_summary");
+		});
+
+		it("appendRecall deduplicates on (turnId, checkpointId)", () => {
+			const tid = store.asWriter().appendTurn(makeTurn({ turnIndex: 0 }));
+			const r1 = makeRecall(tid, { checkpointId: "ckpt_dedup", score: 0.7 });
+			const r2 = makeRecall(tid, { checkpointId: "ckpt_dedup", score: 0.8 });
+
+			store.asWriter().appendRecall(r1);
+			store.asWriter().appendRecall(r2);
+
+			const results = store.asReader().listRecall(tid);
+			// Either 1 (deduped) or 2 (last-write-wins) — both valid contract behaviors
+			assert.ok(results.length >= 1 && results.length <= 2);
+		});
+
+		// ── 3. query filters compose (AND) ──────────────────────
+
+		it("query with no filter returns all turns", () => {
+			store.asWriter().appendTurn(makeTurn({ turnIndex: 0 }));
+			store.asWriter().appendTurn(makeTurn({ turnIndex: 1 }));
+
+			const results = store.asReader().query({});
+			assert.ok(results.length >= 2);
+		});
+
+		it("query filters by conversationId", () => {
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ conversationId: "conv_a", turnIndex: 0 }));
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ conversationId: "conv_b", turnIndex: 0 }));
+
+			const results = store.asReader().query({ conversationId: "conv_a" });
+			assert.equal(results.length, 1);
+			assert.equal(results[0].conversationId, "conv_a");
+		});
+
+		it("query filters by time range (sinceMs + untilMs)", () => {
+			const now = Date.now();
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ turnIndex: 0, endedAt: now - 2000 }));
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ turnIndex: 1, endedAt: now - 1000 }));
+			store.asWriter().appendTurn(makeTurn({ turnIndex: 2, endedAt: now }));
+
+			const results = store.asReader().query({
+				sinceMs: now - 1500,
+				untilMs: now - 500,
+			});
+			assert.equal(results.length, 1);
+			assert.equal(results[0].turnIndex, 1);
+		});
+
+		it("query filters by pressureBand", () => {
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ turnIndex: 0, pressureBand: "red" }));
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ turnIndex: 1, pressureBand: "green" }));
+
+			const results = store.asReader().query({ pressureBand: "red" });
+			assert.equal(results.length, 1);
+			assert.equal(results[0].pressureBand, "red");
+		});
+
+		it("query respects limit and offset", () => {
+			for (let i = 0; i < 5; i++) {
+				store.asWriter().appendTurn(makeTurn({ turnIndex: i }));
+			}
+
+			const page1 = store.asReader().query({ limit: 2, offset: 0 });
+			const page2 = store.asReader().query({ limit: 2, offset: 2 });
+			assert.equal(page1.length, 2);
+			assert.equal(page2.length, 2);
+			assert.notEqual(page1[0].turnIndex, page2[0].turnIndex);
+		});
+
+		// ── 4. conversationStats ────────────────────────────────
+
+		it("conversationStats aggregates correctly", () => {
+			const now = Date.now();
+			const convId = "conv_stats";
+			store.asWriter().appendTurn(
+				makeTurn({
+					conversationId: convId,
+					turnIndex: 0,
+					endedAt: now - 2000,
+					ctxPercent: 0.3,
+					pressureBand: "green",
+				}),
+			);
+			store.asWriter().appendTurn(
+				makeTurn({
+					conversationId: convId,
+					turnIndex: 1,
+					endedAt: now - 1000,
+					ctxPercent: 0.7,
+					pressureBand: "yellow",
+				}),
+			);
+			store.asWriter().appendTurn(
+				makeTurn({
+					conversationId: convId,
+					turnIndex: 2,
+					endedAt: now,
+					pressureBand: "green",
+				}),
+			);
+
+			const stats = store.asReader().conversationStats(convId);
+			assert.equal(stats.turnCount, 3);
+			assert.equal(stats.firstTurnAt, now - 2000);
+			assert.equal(stats.lastTurnAt, now);
+			assert.ok(Math.abs(stats.avgCtxPercent - 0.5) < 0.01);
+			assert.equal(stats.pressureBands.green, 2);
+			assert.equal(stats.pressureBands.yellow, 1);
+		});
+
+		it("conversationStats returns zeros for empty conversation", () => {
+			const stats = store.asReader().conversationStats("conv_nonexistent");
+			assert.equal(stats.turnCount, 0);
+			assert.equal(stats.avgCtxPercent, 0);
+		});
+
+		// ── 5. forkConversation ─────────────────────────────────
+
+		it("forkConversation creates a child conversation with fork lineage", () => {
+			const parentId = "conv_parent";
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ conversationId: parentId, turnIndex: 0 }));
+			const tid = store
+				.asWriter()
+				.appendTurn(makeTurn({ conversationId: parentId, turnIndex: 1 }));
+			store
+				.asWriter()
+				.appendRecall(makeRecall(tid, { checkpointId: "ckpt_fork" }));
+
+			const childId = store.asWriter().forkConversation(parentId, 1);
+			assert.ok(childId.startsWith("conv_"), "child is a conversation id");
+			assert.notEqual(childId, parentId, "child is a different conversation");
+
+			const forks = store.asReader().listForks(parentId);
+			assert.equal(forks.length, 1);
+			assert.equal(forks[0].childConversationId, childId);
+			assert.equal(forks[0].forkTurnIndex, 1);
+		});
+
+		it("forkConversation seeds child with parent recall", () => {
+			const parentId = "conv_seed_parent";
+			store.asWriter().appendTurn(
+				makeTurn({ conversationId: parentId, turnIndex: 0 }),
+			);
+			const tid1 = store.asWriter().appendTurn(
+				makeTurn({ conversationId: parentId, turnIndex: 1 }),
+			);
+			// Attach recall to the parent's turn at index 1
+			store.asWriter().appendRecall(
+				makeRecall(tid1, { checkpointId: "ckpt_seed1", score: 0.9, source: "checkpoint" }),
+			);
+			store.asWriter().appendRecall(
+				makeRecall(tid1, { checkpointId: "ckpt_seed2", score: 0.7, source: "memory" }),
+			);
+
+			const childId = store.asWriter().forkConversation(parentId, 1);
+
+			// The child should have a seed turn (turnIndex 0, role system)
+			const childTurns = store.asReader().query({ conversationId: childId });
+			assert.ok(childTurns.length >= 1, "child has at least one turn");
+
+			const seedTurn = childTurns.find(
+				(t) => t.turnIndex === 0 && t.role === "system",
+			);
+			assert.ok(seedTurn, "child has a seed turn");
+
+			// The seed turn should have the parent's recall entries.
+			// Use snapshot-based verification (position-stable IDs).
+			const snapshot = store.asAdmin().checkpoint();
+			const childRecallInSnapshot = snapshot.recall.filter((r) => {
+				// The recall's turnId should point to a turn in the child conversation
+				const turnIdx = Number(r.turnId) - 1;
+				const turn = snapshot.turns[turnIdx];
+				return turn && turn.conversationId === childId;
+			});
+			assert.equal(
+				childRecallInSnapshot.length,
+				2,
+				"child seed turn inherits both recall entries from parent",
+			);
+			assert.ok(
+				childRecallInSnapshot.some((r) => r.checkpointId === "ckpt_seed1"),
+				"child has ckpt_seed1",
+			);
+			assert.ok(
+				childRecallInSnapshot.some((r) => r.checkpointId === "ckpt_seed2"),
+				"child has ckpt_seed2",
+			);
+		});
+
+		// ── 6. countTurns ──────────────────────────────────────
+
+		it("countTurns returns the number of turns in a conversation", () => {
+			const convId = "conv_count";
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ conversationId: convId, turnIndex: 0 }));
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ conversationId: convId, turnIndex: 1 }));
+
+			assert.equal(store.asReader().countTurns(convId), 2);
+			assert.equal(store.asReader().countTurns("conv_nonexistent"), 0);
+		});
+
+		// ── 7. ensureConversationId ─────────────────────────────
+
+		it("ensureConversationId returns same id for same session", () => {
+			const id1 = store.asWriter().ensureConversationId("sess_test1");
+			const id2 = store.asWriter().ensureConversationId("sess_test1");
+			assert.equal(id1, id2, "same session should always get the same conversationId");
+			assert.ok(id1.startsWith("conv_"), "conversationId has conv_ prefix");
+
+			// After writing a turn with this session, ensureConversationId
+			// should still return the same conversationId
+			store.asWriter().appendTurn(
+				makeTurn({ conversationId: id1, sessionId: "sess_test1", turnIndex: 0 }),
+			);
+			const id3 = store.asWriter().ensureConversationId("sess_test1");
+			assert.equal(id3, id1, "conversationId stable after turn is written");
+		});
+
+		// ── 8. prune ────────────────────────────────────────────
+
+		it("prune removes old turns, respects keepMinPerConversation", () => {
+			const convId = "conv_prune";
+			const now = Date.now();
+
+			// 5 turns, 3 are old
+			for (let i = 0; i < 5; i++) {
+				store.asWriter().appendTurn(
+					makeTurn({
+						conversationId: convId,
+						turnIndex: i,
+						endedAt: now - (5 - i) * 1000,
+					}),
+				);
+			}
+
+			const report = store.asAdmin().prune({
+				maxTurnAgeMs: 3500, // turns older than 3.5s
+				keepMinPerConversation: 3, // keep at least 3
+				vacuumAfterPrune: false,
+			});
+
+			// Should delete 2 (5 total - 3 minimum = 2 eligible, but only those older than cutoff)
+			assert.ok(report.turnsRemoved >= 0, "prune report has turnsRemoved");
+			assert.equal(
+				store.asReader().countTurns(convId),
+				5 - report.turnsRemoved,
+			);
+		});
+
+		it("prune cascades recall for deleted turns", () => {
+			const convId = "conv_prune_recall";
+			const now = Date.now();
+
+			const tid0 = store.asWriter().appendTurn(
+				makeTurn({
+					conversationId: convId,
+					turnIndex: 0,
+					endedAt: now - 10000,
+				}),
+			);
+			store.asWriter().appendRecall(makeRecall(tid0));
+			store.asWriter().appendTurn(
+				makeTurn({
+					conversationId: convId,
+					turnIndex: 1,
+					endedAt: now,
+				}),
+			);
+
+			const report = store.asAdmin().prune({
+				maxTurnAgeMs: 5000,
+				keepMinPerConversation: 1,
+				vacuumAfterPrune: false,
+			});
+
+			if (report.turnsRemoved > 0) {
+				assert.ok(report.recallRemoved >= 0, "recall cascaded");
+			}
+		});
+
+		// ── 9. checkpoint / restore round-trip ──────────────────
+
+		it("checkpoint + restore is lossless", () => {
+			const convId = "conv_snapshot";
+			store
+				.asWriter()
+				.appendTurn(makeTurn({ conversationId: convId, turnIndex: 0 }));
+			const tid = store.asWriter().appendTurn(
+				makeTurn({
+					conversationId: convId,
+					turnIndex: 1,
+					ctxTokens: 8000,
+					ctxPercent: 0.8,
+					pressureBand: "red",
+					model: "test-model",
+				}),
+			);
+			store.asWriter().appendRecall(
+				makeRecall(tid, {
+					checkpointId: "ckpt_snap",
+					score: 0.95,
+					source: "memory",
+				}),
+			);
+			store.asWriter().forkConversation(convId, 1);
+
+			const snapshot = store.asAdmin().checkpoint();
+			assert.equal(snapshot.version, 1);
+			// Fork creates a seed turn in the child, so total turns = 3
+			assert.equal(snapshot.turns.length, 3, "2 parent + 1 child seed turn");
+			assert.equal(snapshot.recall.length, 2, "1 parent recall + 1 child seed recall (copied from parent)");
+			assert.equal(snapshot.forks.length, 1);
+
+			// Clear and restore
+			store.asAdmin().clear();
+			assert.equal(store.asReader().countTurns(convId), 0);
+
+			store.asAdmin().restore(snapshot);
+
+			// Verify turns restored
+			assert.equal(store.asReader().countTurns(convId), 2);
+
+			// Verify turn content
+			const turns = store.asReader().query({ conversationId: convId });
+			assert.equal(turns.length, 2);
+			assert.equal(turns[1].ctxTokens, 8000);
+			assert.equal(turns[1].pressureBand, "red");
+			assert.equal(turns[1].model, "test-model");
+
+			// Verify recall restored: find the restored turn at turnIndex 1
+			// and check its recall entries
+			const turn1 = turns.find((t) => t.turnIndex === 1);
+			assert.ok(turn1, "turn at index 1 should exist after restore");
+			// We need the TurnId to query listRecall. Since restore may
+			// remap IDs, we query by (conversationId, turnIndex) to find
+			// the new TurnId via getTurn.
+			//
+			// Strategy: snapshot recall uses position-based IDs.
+			// After restore, the turn at position 2 (index 1) should have
+			// its recall. We can verify by taking a second checkpoint
+			// and checking it matches the first.
+			const snapshot2 = store.asAdmin().checkpoint();
+			assert.equal(snapshot2.turns.length, 3, "second checkpoint has 3 turns (2 parent + 1 child seed)");
+			assert.equal(snapshot2.recall.length, 2, "second checkpoint has 2 recall (1 parent + 1 child seed)");
+			assert.equal(snapshot2.recall[0].checkpointId, "ckpt_snap", "recall checkpointId preserved");
+			assert.equal(snapshot2.recall[0].score, 0.95, "recall score preserved");
+			assert.equal(snapshot2.recall[0].source, "memory", "recall source preserved");
+
+			// Verify forks restored
+			const forks = store.asReader().listForks(convId);
+			assert.equal(forks.length, 1);
+		});
+
+		// ── 10. close is idempotent ──────────────────────────────
+
+		it("close is idempotent", () => {
+			// Should not throw
+			store.close();
+			// Second close should also not throw
+			// (create a new store for this since the old one is closed)
+			const store2 = factory(options);
+			store2.close();
+			store2.close();
+		});
+
+		// ── 11. clear wipes all data ─────────────────────────────
+
+		it("clear wipes all data", () => {
+			store.asWriter().appendTurn(makeTurn({ turnIndex: 0 }));
+			store.asAdmin().clear();
+			assert.equal(
+				store.asReader().query({}).length,
+				0,
+				"no turns after clear",
+			);
+		});
+
+		// ── 12. Capability gating ────────────────────────────────
+
+		it("asReader returns a TurnReader (type check)", () => {
+			const reader = store.asReader();
+			assert.equal(typeof reader.query, "function");
+			assert.equal(typeof reader.getTurn, "function");
+			assert.equal(typeof reader.listRecall, "function");
+			assert.equal(typeof reader.listForks, "function");
+			assert.equal(typeof reader.countTurns, "function");
+			assert.equal(typeof reader.conversationStats, "function");
+		});
+
+		it("asWriter returns a TurnWriter (type check)", () => {
+			const writer = store.asWriter();
+			assert.equal(typeof writer.appendTurn, "function");
+			assert.equal(typeof writer.appendRecall, "function");
+			assert.equal(typeof writer.ensureConversationId, "function");
+			assert.equal(typeof writer.forkConversation, "function");
+		});
+
+		it("asAdmin returns a TurnAdmin (type check)", () => {
+			const admin = store.asAdmin();
+			assert.equal(typeof admin.prune, "function");
+			assert.equal(typeof admin.vacuum, "function");
+			assert.equal(typeof admin.checkpoint, "function");
+			assert.equal(typeof admin.restore, "function");
+			assert.equal(typeof admin.clear, "function");
+		});
+	});
+}