diff --git a/README.md b/README.md
index 2cac04d..306bf90 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@ graph TB
VIS["visual-maker
write → render → look"]
end
- subgraph STORE["File stores (data/, never in git)"]
+ subgraph STORE["File stores (src/store adapters → data/, never in git)"]
CHATS[("data/chats/*.json
UIMessages + plan tree")]
JOBS[("data/jobs/*.json")]
LEDG[("data/graph/*.jsonl
nodes/edges/events/mappings/sessions")]
@@ -126,10 +126,15 @@ src/
subagents/ researcher · demo-builder · visual-maker,
runner (async protocol), headless Chrome helper
server/chat-handler.ts one chat turn: stream, persist, spawn, emit
+ server/stores.ts THE composition root — the one place adapters wire in
core/contracts.ts THE contracts file — types + protocol docs
+ core/ports.ts storage ports — ChatStore · GraphStore · JobStore
+ (core code depends on these types only)
core/ question-core, plan-tree, phases, pending,
graph (emission/derivation), graph-context, math delims
- store/ chats · graph ledgers · jobs (plain fs, no framework)
+ — all pure: storage arrives as parameters
+ store/ fs adapters implementing the ports: chats ·
+ graph ledgers · jobs (plain fs, no framework)
scripts/bench-graph.ts sigma/forceAtlas2 layout benchmark
data/ chats/ · graph/ · jobs/ — runtime state, git-ignored
```
diff --git a/eslint.config.mjs b/eslint.config.mjs
index ecd1844..1e5d7d0 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -10,7 +10,8 @@ import importPlugin from "eslint-plugin-import";
*
* components/** → "@/src/core" (the pure core barrel) — ONLY
* app/** → "@/src/core" + "@/src/server" (the server barrel) — ONLY
- * pure core → never imports src/agent, src/server, src/store
+ * src/core/** → never imports src/agent, src/server, src/store (pure
+ * core: adapters implement core/ports.ts, never the reverse)
*
* tests/ and scripts/ are internal — unrestricted.
*/
@@ -49,10 +50,10 @@ export default defineConfig([
"app/ (transport + server components) imports ONLY the barrels: `@/src/core` and `@/src/server` (architecture: docs/architecture.md).",
},
{
- target: "./src/core/{index,contracts,question-core,plan-tree,phases,pending,math-delims,ui-message}.ts",
+ target: "./src/core",
from: ["./src/agent", "./src/server", "./src/store"],
message:
- "Pure core modules never import IO layers (agent/server/store). IO-bound core (graph.ts, graph-context.ts) is exempt until the storage-port stage inverts it.",
+ "Pure core never imports IO layers (agent/server/store): adapters implement core/ports.ts, and the composition root (src/server/stores.ts) passes them in (architecture: docs/architecture.md).",
},
],
},
diff --git a/src/agent/subagents/runner.ts b/src/agent/subagents/runner.ts
index c8e9802..c640641 100644
--- a/src/agent/subagents/runner.ts
+++ b/src/agent/subagents/runner.ts
@@ -1,8 +1,8 @@
import { isToolUIPart, type LanguageModel, type UIMessage } from "ai";
import type { DemoResult, DemoToolInput, JobKind, ResearchResult, ResearchToolInput, VisualResult, VisualToolInput } from "../../core/contracts.ts";
import { JOB_TOOLS } from "../../core/pending.ts";
-import { getChat, saveMessages } from "../../store/chats.ts";
-import { createJob, findJobByToolCallId, getJob, updateJob } from "../../store/jobs.ts";
+import { chatStore } from "../../store/chats.ts";
+import { jobStore } from "../../store/jobs.ts";
import { runDemoBuilder } from "./demo-builder.ts";
import { createResearcherAgent } from "./researcher.ts";
import { runVisualMaker } from "./visual-maker.ts";
@@ -60,22 +60,22 @@ export function spawnPendingJobs(chatId: string, messages: UIMessage[]): void {
if (!(JOB_TOOLS as readonly string[]).includes(tool)) continue;
const runner = KIND_RUNNERS[tool as JobKind];
if (!runner) continue;
- if (findJobByToolCallId(chatId, part.toolCallId)) continue; // already has a job
- const job = createJob({ kind: tool as JobKind, chatId, toolCallId: part.toolCallId });
+ if (jobStore.findJobByToolCallId(chatId, part.toolCallId)) continue; // already has a job
+ const job = jobStore.createJob({ kind: tool as JobKind, chatId, toolCallId: part.toolCallId });
void runner(job.id).catch((err) => {
console.error(`[job ${job.id}] ${tool} runner crashed:`, err);
- updateJob(job.id, { status: "error", error: String(err), activity: "failed" });
+ jobStore.updateJob(job.id, { status: "error", error: String(err), activity: "failed" });
});
}
}
export async function runResearchJob(jobId: string, opts: RunResearchJobOptions = {}): Promise {
- const job = getJob(jobId);
+ const job = jobStore.getJob(jobId);
if (!job || job.status !== "running") return;
- const chat = getChat(job.chatId);
+ const chat = chatStore.getChat(job.chatId);
if (!chat) {
- updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
+ jobStore.updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
return;
}
const input = findToolPart(chat.messages, job.toolCallId)?.input as ResearchToolInput | undefined;
@@ -94,7 +94,7 @@ export async function runResearchJob(jobId: string, opts: RunResearchJobOptions
const agent = createResearcherAgent(opts.model);
try {
- updateJob(jobId, { activity: "researching" });
+ jobStore.updateJob(jobId, { activity: "researching" });
const result = await agent.generate({
prompt,
onToolExecutionStart: ({ toolCall }) => {
@@ -102,7 +102,7 @@ export async function runResearchJob(jobId: string, opts: RunResearchJobOptions
if (toolCall.toolName === "web_fetch" && typeof input?.url === "string") {
fetchedUrls.push(input.url);
}
- updateJob(jobId, { activity: activityLine(toolCall.toolName, input) });
+ jobStore.updateJob(jobId, { activity: activityLine(toolCall.toolName, input) });
},
});
@@ -111,11 +111,11 @@ export async function runResearchJob(jobId: string, opts: RunResearchJobOptions
const research: ResearchResult = { brief, sources: parseSources(brief, fetchedUrls) };
fulfillPart(job.chatId, job.toolCallId, research);
- updateJob(jobId, { status: "done", result: research }); // activity line kept: the last tool call is the record
+ jobStore.updateJob(jobId, { status: "done", result: research }); // activity line kept: the last tool call is the record
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
fulfillPart(job.chatId, job.toolCallId, { brief: `Research failed: ${reason}`, sources: [] });
- updateJob(jobId, { status: "error", activity: "failed", error: reason });
+ jobStore.updateJob(jobId, { status: "error", activity: "failed", error: reason });
}
}
@@ -135,12 +135,12 @@ function isVisualFailure(result: VisualResult): boolean {
}
export async function runDemoJob(jobId: string, opts: RunDemoJobOptions = {}): Promise {
- const job = getJob(jobId);
+ const job = jobStore.getJob(jobId);
if (!job || job.status !== "running") return;
- const chat = getChat(job.chatId);
+ const chat = chatStore.getChat(job.chatId);
if (!chat) {
- updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
+ jobStore.updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
return;
}
const input = findToolPart(chat.messages, job.toolCallId)?.input as DemoToolInput | undefined;
@@ -148,25 +148,25 @@ export async function runDemoJob(jobId: string, opts: RunDemoJobOptions = {}): P
const brief = typeof input?.brief === "string" ? input.brief : "";
try {
- updateJob(jobId, { activity: "building demo" });
+ jobStore.updateJob(jobId, { activity: "building demo" });
const result = await runDemoBuilder(
{ title, brief },
{
model: opts.model,
- onActivity: (line) => updateJob(jobId, { activity: line }),
+ onActivity: (line) => jobStore.updateJob(jobId, { activity: line }),
},
);
fulfillPart(job.chatId, job.toolCallId, result);
if (isDemoFailure(result)) {
- updateJob(jobId, { status: "error", error: result.notes ?? "demo build failed", activity: "failed" });
+ jobStore.updateJob(jobId, { status: "error", error: result.notes ?? "demo build failed", activity: "failed" });
} else {
- updateJob(jobId, { status: "done", result });
+ jobStore.updateJob(jobId, { status: "done", result });
}
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
const failure: DemoResult = { title, html: "", tested: true, notes: `FAILED: ${reason}` };
fulfillPart(job.chatId, job.toolCallId, failure);
- updateJob(jobId, { status: "error", error: reason, activity: "failed" });
+ jobStore.updateJob(jobId, { status: "error", error: reason, activity: "failed" });
}
}
@@ -175,37 +175,37 @@ export interface RunVisualJobOptions {
}
export async function runVisualJob(jobId: string, opts: RunVisualJobOptions = {}): Promise {
- const job = getJob(jobId);
+ const job = jobStore.getJob(jobId);
if (!job || job.status !== "running") return;
- const chat = getChat(job.chatId);
+ const chat = chatStore.getChat(job.chatId);
if (!chat) {
- updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
+ jobStore.updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
return;
}
const input = findToolPart(chat.messages, job.toolCallId)?.input as VisualToolInput | undefined;
const brief = typeof input?.brief === "string" ? input.brief : "";
try {
- updateJob(jobId, { activity: "drawing figure" });
+ jobStore.updateJob(jobId, { activity: "drawing figure" });
const result = await runVisualMaker(
{ brief },
{
model: opts.model,
- onActivity: (line) => updateJob(jobId, { activity: line }),
+ onActivity: (line) => jobStore.updateJob(jobId, { activity: line }),
},
);
fulfillPart(job.chatId, job.toolCallId, result);
if (isVisualFailure(result)) {
- updateJob(jobId, { status: "error", error: result.notes ?? "visual build failed", activity: "failed" });
+ jobStore.updateJob(jobId, { status: "error", error: result.notes ?? "visual build failed", activity: "failed" });
} else {
- updateJob(jobId, { status: "done", result });
+ jobStore.updateJob(jobId, { status: "done", result });
}
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
const failure: VisualResult = { svg: "", notes: `FAILED: ${reason}` };
fulfillPart(job.chatId, job.toolCallId, failure);
- updateJob(jobId, { status: "error", error: reason, activity: "failed" });
+ jobStore.updateJob(jobId, { status: "error", error: reason, activity: "failed" });
}
}
@@ -241,7 +241,7 @@ function hostOf(url: string | undefined): string {
* Synchronous read-modify-write (no awaits) — atomic within the event loop.
*/
function fulfillPart(chatId: string, toolCallId: string, output: ResearchResult | DemoResult | VisualResult): void {
- const chat = getChat(chatId);
+ const chat = chatStore.getChat(chatId);
if (!chat) return;
let found = false;
const messages = chat.messages.map((m) =>
@@ -260,7 +260,7 @@ function fulfillPart(chatId: string, toolCallId: string, output: ResearchResult
);
if (!found) return;
try {
- saveMessages(chatId, messages);
+ chatStore.saveMessages(chatId, messages);
} catch (err) {
console.error(`[chat ${chatId}] fulfilling job part ${toolCallId} failed:`, err);
}
diff --git a/src/agent/tools/plan.ts b/src/agent/tools/plan.ts
index d18cac9..2efd281 100644
--- a/src/agent/tools/plan.ts
+++ b/src/agent/tools/plan.ts
@@ -13,7 +13,7 @@ import {
setCurrent,
updateNode,
} from "../../core/plan-tree.ts";
-import { getChat, saveTree } from "../../store/chats.ts";
+import { chatStore } from "../../store/chats.ts";
import type { TeacherToolContext } from "../tools.ts";
/**
@@ -52,12 +52,12 @@ async function runPlanOp(
chatId: string,
op: (tree: PlanTree) => PlanTree,
): Promise {
- const record = getChat(chatId);
+ const record = chatStore.getChat(chatId);
if (!record) return { ok: false, error: `Chat not found: ${chatId}`, tree: emptyTree() };
const current = record.tree ?? emptyTree();
try {
const next = op(current);
- saveTree(chatId, next);
+ chatStore.saveTree(chatId, next);
return { ok: true, tree: next };
} catch (err) {
if (err instanceof PlanTreeError) return { ok: false, error: err.message, tree: current };
@@ -81,7 +81,7 @@ export function planTools(ctx: TeacherToolContext): ToolSet {
.describe("Initial `requires` edges between the nodes. Edge direction: from = prerequisite, to = dependent."),
}),
execute: async ({ nodes, edges }): Promise => {
- const record = getChat(ctx.chatId);
+ const record = chatStore.getChat(ctx.chatId);
if (!record) return { ok: false, error: `Chat not found: ${ctx.chatId}`, tree: emptyTree() };
const existing = record.tree;
if (existing && existing.nodes.length > 0) {
diff --git a/src/core/contracts.ts b/src/core/contracts.ts
index 8da5d02..e60cece 100644
--- a/src/core/contracts.ts
+++ b/src/core/contracts.ts
@@ -1,7 +1,7 @@
/**
* Shared contracts — the single source of truth every component codes against.
- * Pure types + protocol docs; no runtime code, type-only imports (safe
- * everywhere: server, client, tests). See docs/vision.md (§ refs).
+ * Pure types + protocol docs + tiny pure helpers; type-only imports of "ai"
+ * (safe everywhere: server, client, tests). See docs/vision.md (§ refs).
*/
import type { UIMessage } from "ai";
@@ -83,6 +83,23 @@ export interface GraphEdge {
provenance: string[];
}
+/** mappings.jsonl line — the naive-union identity map: a chat's tree node →
+ * the graph node it folded into (the merge audit trail; v1 never merges two
+ * sessions' tree nodes — W8 exact-title match aside). */
+export interface NodeMapping {
+ chatId: string;
+ treeNodeId: string;
+ graphNodeId: string;
+}
+
+/** sessions.jsonl line — the emission checkpoint for one chat (which chats
+ * have been folded, and through which updatedAt — never fold twice). */
+export interface SessionCheckpoint {
+ chatId: string;
+ /** The chat record's `updatedAt` at the time of the fold. */
+ foldedAt: string;
+}
+
export type LedgerEventKind =
| "probe-correct"
| "probe-miss"
@@ -136,6 +153,13 @@ export interface GraphSnapshot {
nodeSessions: Record;
}
+/** Derive a short chat title from the learner's first message (pure).
+ * Used on chat creation; deterministic so tests can pin it. */
+export function titleFromPrompt(prompt: string): string {
+ const oneLine = prompt.replace(/\s+/g, " ").trim();
+ return oneLine.length > 72 ? `${oneLine.slice(0, 72)}…` : oneLine;
+}
+
// ─── Chat records (the session store's on-disk format) ───────────────────────
/** One persisted session: data/chats/.json. The stored messages are full
diff --git a/src/core/graph-context.ts b/src/core/graph-context.ts
index 031c595..2bf6c68 100644
--- a/src/core/graph-context.ts
+++ b/src/core/graph-context.ts
@@ -22,7 +22,7 @@
*/
import type { GraphEdge, GraphNode } from "./contracts.ts";
-import { deriveNodeStates, getGraph, type DerivedGraph } from "./graph.ts";
+import { deriveNodeStates, type DerivedGraph } from "./graph.ts";
import type { NodeStateClass } from "./contracts.ts";
/** The section header the teacher is taught to recognize (50-graph-context.md). */
@@ -59,7 +59,7 @@ function isHotspot(node: GraphNode, state: NodeStateClass): boolean {
* Render the context block, or null when there is nothing worth injecting
* (no nodes; or a truncated graph whose selection came out empty).
*
- * Pure: callers hand in exactly what getGraph() + deriveNodeStates() produce.
+ * Pure: callers hand in exactly what getGraph(graphStore) + deriveNodeStates() produce.
*/
export function renderGraphContext(
nodes: GraphNode[],
@@ -162,11 +162,11 @@ function edgeChains(edges: GraphEdge[]): string[][] {
// ─── the per-request entry point ─────────────────────────────────────────────
/**
- * Build the graph context block for one request. Stateless — re-reads the
- * ledgers every call, so it self-updates as the graph grows mid-session.
- * Accepts an injected derived graph (tests); defaults to the live one.
+ * Build the graph context block for one request. Pure: the caller hands in
+ * the derived graph (production: getGraph(graphStore) per request in the
+ * chat-handler, so it self-updates as the graph grows mid-session).
*/
-export function buildGraphContext(graph: DerivedGraph = getGraph()): string | null {
+export function buildGraphContext(graph: DerivedGraph): string | null {
const states = deriveNodeStates(graph.nodes, graph.events);
return renderGraphContext(graph.nodes, graph.edges, states);
}
diff --git a/src/core/graph.ts b/src/core/graph.ts
index 0501837..709d8a5 100644
--- a/src/core/graph.ts
+++ b/src/core/graph.ts
@@ -16,10 +16,12 @@
* Idempotent + incremental: mappings dedupe nodes, (from,to,type) dedupes
* edge assertions, chat-scoped refs dedupe events, and sessions.jsonl
* checkpoints which chats have been folded. Re-emitting a chat appends
- * nothing. The store (src/store/graph.ts) holds the append-only ledgers;
- * everything here derives from them.
+ * nothing. Every function takes the storage ports (core/ports.ts) as
+ * explicit parameters — pure core, no adapter imports; the composition
+ * root (src/server/stores.ts) wires the fs adapters in.
*/
+import { randomBytes } from "node:crypto";
import { isToolUIPart, type UIMessage } from "ai";
import type {
GraphEdge,
@@ -32,13 +34,18 @@ import type {
PlanToolResult,
} from "./contracts.ts";
import type { QuestionAnswerData } from "./question-core.ts";
-import { getChat, listChats } from "../store/chats.ts";
-import { graphLedgers, newGraphNodeId } from "../store/graph.ts";
+import type { ChatStore, GraphStore } from "./ports.ts";
-/** The ledger surface emitChat needs (the real one is src/store/graph.ts).
- * Injectable so tests can fold fixtures into an in-memory ledger instead of
- * the live data/graph files. */
-export type GraphLedgers = typeof graphLedgers;
+/** The storage ports every graph operation needs, passed explicitly. */
+export interface GraphDeps {
+ chatStore: ChatStore;
+ graphStore: GraphStore;
+}
+
+/** "n_" + 12 hex chars (contracts.ts GraphNode.id — store-assigned). */
+function newGraphNodeId(): string {
+ return `n_${randomBytes(6).toString("hex")}`;
+}
// ─── transcript scanning ─────────────────────────────────────────────────────
@@ -109,11 +116,12 @@ export interface EmissionStats {
* turn (chat-handler onFinish) and again on catch-up (GET /api/graph). Sync
* and fast: a handful of small-file reads plus one append per new record.
*
- * `ledgers` is injectable for tests (in-memory ledger); production always
- * uses the live store.
+ * The storage ports are explicit (tests pass in-memory ledgers; production
+ * passes the fs adapters from src/server/stores.ts).
*/
-export function emitChat(chatId: string, ledgers: GraphLedgers = graphLedgers): EmissionStats {
- const record = getChat(chatId);
+export function emitChat(chatId: string, deps: GraphDeps): EmissionStats {
+ const { graphStore: ledgers } = deps;
+ const record = deps.chatStore.getChat(chatId);
if (!record) return { nodes: 0, edges: 0, events: 0 };
const stats: EmissionStats = { nodes: 0, edges: 0, events: 0 };
@@ -297,11 +305,11 @@ export interface DerivedGraph {
* edges are merged by (from,to,type) with unioned provenance, first-seen
* order. `store events, derive state` — this is the only reader that matters.
*/
-export function getGraph(): DerivedGraph {
- const nodes = graphLedgers.readNodes();
+export function getGraph(graphStore: GraphStore): DerivedGraph {
+ const nodes = graphStore.readNodes();
const merged: GraphEdge[] = [];
const byKey = new Map();
- for (const line of graphLedgers.readEdges()) {
+ for (const line of graphStore.readEdges()) {
const key = `${line.from}\u0000${line.to}\u0000${line.type}`;
const existing = byKey.get(key);
if (existing) {
@@ -314,7 +322,7 @@ export function getGraph(): DerivedGraph {
merged.push(edge);
}
}
- return { nodes, edges: merged, events: graphLedgers.readEvents() };
+ return { nodes, edges: merged, events: graphStore.readEvents() };
}
const QUIZ_EVENT_KINDS: ReadonlySet = new Set([
@@ -366,8 +374,8 @@ export function deriveNodeStates(nodes: GraphNode[], events: LedgerEvent[]): Rec
// ─── the /api/graph payload ──────────────────────────────────────────────────
/** Everything the home graph view needs, in one fetch (shape: contracts). */
-export function graphSnapshot(): GraphSnapshot {
- const { nodes, edges, events } = getGraph();
+export function graphSnapshot(deps: GraphDeps): GraphSnapshot {
+ const { nodes, edges, events } = getGraph(deps.graphStore);
const nodeStates = deriveNodeStates(nodes, events);
const nodeChats = new Map>();
@@ -379,7 +387,7 @@ export function graphSnapshot(): GraphSnapshot {
}
chats.add(chatId);
};
- for (const m of graphLedgers.readMappings()) touch(m.graphNodeId, m.chatId);
+ for (const m of deps.graphStore.readMappings()) touch(m.graphNodeId, m.chatId);
for (const edge of edges) {
for (const chatId of edge.provenance) {
touch(edge.from, chatId);
@@ -397,7 +405,7 @@ export function graphSnapshot(): GraphSnapshot {
}
const sessions: Record = {};
for (const id of chatIds) {
- const chat = getChat(id);
+ const chat = deps.chatStore.getChat(id);
if (chat) sessions[id] = chat.title;
}
@@ -417,9 +425,9 @@ export function graphSnapshot(): GraphSnapshot {
* sessions deposit value — vision §1 "frequent updates"). Called at the top
* of GET /api/graph; the chat-handler onFinish hook covers the live path.
*/
-export function foldStaleChats(): number {
+export function foldStaleChats(deps: GraphDeps): number {
const checkpoints = new Map();
- for (const checkpoint of graphLedgers.readCheckpoints()) {
+ for (const checkpoint of deps.graphStore.readCheckpoints()) {
const previous = checkpoints.get(checkpoint.chatId);
if (previous === undefined || checkpoint.foldedAt > previous) {
checkpoints.set(checkpoint.chatId, checkpoint.foldedAt);
@@ -427,11 +435,11 @@ export function foldStaleChats(): number {
}
let folded = 0;
- for (const chat of listChats()) {
+ for (const chat of deps.chatStore.listChats()) {
const foldedAt = checkpoints.get(chat.id);
if (foldedAt !== undefined && chat.updatedAt <= foldedAt) continue;
try {
- emitChat(chat.id);
+ emitChat(chat.id, deps);
folded++;
} catch (err) {
console.error(`[graph] fold failed for chat ${chat.id}:`, err);
diff --git a/src/core/index.ts b/src/core/index.ts
index a20bfa9..fa9a5a5 100644
--- a/src/core/index.ts
+++ b/src/core/index.ts
@@ -9,13 +9,16 @@
* components/** → "@/src/core" (this barrel, ONLY)
* app/** → "@/src/core" + "@/src/server"
*
- * IO-bound modules (core/graph.ts, core/graph-context.ts read the ledgers
- * via the store) stay internal to the server side until the storage-port
- * stage inverts their dependency; they are deliberately NOT re-exported
- * here.
+ * Server-only core modules (core/graph.ts emission/derivation,
+ * core/graph-context.ts) are pure but need storage ports passed in by a
+ * server caller, so they are deliberately NOT re-exported here — the
+ * server imports them directly. The storage PORT TYPES are types-only and
+ * browser-safe, hence re-exported.
*/
export * from "./contracts.ts";
+export * from "./ports.ts";
+
export * from "./question-core.ts";
export * from "./plan-tree.ts";
export * from "./phases.ts";
diff --git a/src/core/ports.ts b/src/core/ports.ts
new file mode 100644
index 0000000..bed10f2
--- /dev/null
+++ b/src/core/ports.ts
@@ -0,0 +1,95 @@
+/**
+ * Storage ports (the hexagonal seams — vision §1 "storage stays swappable").
+ *
+ * One port per ENTITY, with domain operations — never one generic
+ * key/value interface. Core and the service layer that orbits it code
+ * against these types only; concrete adapters live in src/store/ (fs
+ * JSON/JSONL today, SQLite drop-in later) and are wired exactly once, in
+ * the composition root (src/server/stores.ts). Dependencies point one way:
+ * adapters may import core; core NEVER imports an adapter.
+ */
+
+import type { UIMessage } from "ai";
+import type {
+ ChatRecord,
+ ChatSummary,
+ GraphEdge,
+ GraphNode,
+ JobKind,
+ JobRecord,
+ LedgerEvent,
+ NodeMapping,
+ PlanTree,
+ SessionCheckpoint,
+} from "./contracts.ts";
+
+// ─── ChatStore — the session record's home (data/chats) ─────────────────────
+
+export interface ChatStore {
+ /** Create a session record (persisted immediately). */
+ createChat(title: string): ChatRecord;
+ /** The full record, or null if unknown id / corrupt file. */
+ getChat(id: string): ChatRecord | null;
+ /** All sessions, newest activity first (the sidebar's list view). */
+ listChats(): ChatSummary[];
+ /** Persist the full message list (client state + new response) after a turn. */
+ saveMessages(id: string, messages: UIMessage[]): void;
+ /** Persist the session plan tree (plan tools call this in execute). */
+ saveTree(id: string, tree: PlanTree): void;
+}
+
+// ─── GraphStore — the append-only evidence ledgers (data/graph) ──────────────
+// v1 surface = the five JSONL ledgers (nodes / edges / events / mappings /
+// sessions). Reads return the raw append-order lines; merging edge assertions
+// by (from, to, type) is DERIVED in core/graph.ts — the store never decides.
+// The extraction pipeline (next stage) becomes the sole writer; this read
+// surface stays.
+
+export interface GraphStore {
+ /** Append one GraphNode (ids are unique — no merging needed). */
+ appendNode(node: GraphNode): void;
+ /** Raw node lines in append order. */
+ readNodes(): GraphNode[];
+
+ /** Append one edge ASSERTION (a second session asserting the same
+ * (from, to, type) appends another line; readers merge). */
+ appendEdge(assertion: GraphEdge): void;
+ readEdges(): GraphEdge[];
+
+ /** Append one quiz outcome / taught event. */
+ appendEvent(event: LedgerEvent): void;
+ readEvents(): LedgerEvent[];
+
+ /** Append one identity-map line (chat's tree node → graph node). */
+ appendMapping(mapping: NodeMapping): void;
+ readMappings(): NodeMapping[];
+
+ /** Append one emission checkpoint. */
+ appendCheckpoint(checkpoint: SessionCheckpoint): void;
+ readCheckpoints(): SessionCheckpoint[];
+}
+
+// ─── JobStore — background sub-agent jobs (data/jobs) ─────────────────────────
+
+export interface CreateJobInit {
+ kind: JobKind;
+ chatId: string;
+ toolCallId: string;
+ /** First activity line (defaults to "starting"). */
+ activity?: string;
+}
+
+/** Mergeable fields — identity (id, kind, chatId, toolCallId, createdAt) is immutable. */
+export type JobPatch = Partial>;
+
+export interface JobStore {
+ /** Create a running job (keyed by toolCallId for spawn dedup). */
+ createJob(init: CreateJobInit): JobRecord;
+ getJob(id: string): JobRecord | null;
+ /** Merge a patch into the record; null if unknown id. */
+ updateJob(id: string, patch: JobPatch): JobRecord | null;
+ /** All jobs for a chat, newest activity first. */
+ listJobs(chatId: string): JobRecord[];
+ /** The job fulfilling a given tool part, if any (spawn-hook dedup). */
+ findJobByToolCallId(chatId: string, toolCallId: string): JobRecord | null;
+}
diff --git a/src/server/chat-handler.ts b/src/server/chat-handler.ts
index d171224..9937e8b 100644
--- a/src/server/chat-handler.ts
+++ b/src/server/chat-handler.ts
@@ -2,9 +2,9 @@ import { createAgentUIStreamResponse, type UIMessage } from "ai";
import { createTeacherAgent, type TeacherAgent } from "../agent/teacher-agent.ts";
import { createTeacherTools } from "../agent/tools.ts";
import { spawnPendingJobs } from "../agent/subagents/runner.ts";
-import { emitChat } from "../core/graph.ts";
+import { emitChat, getGraph } from "../core/graph.ts";
import { buildGraphContext } from "../core/graph-context.ts";
-import { getChat, saveMessages } from "../store/chats.ts";
+import { stores } from "./stores.ts";
/**
* One chat turn: run the teacher agent over the client's message list and
@@ -23,7 +23,7 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
return Response.json({ error: "Invalid JSON body" }, { status: 400 });
}
const chatId = typeof body.chatId === "string" ? body.chatId : "";
- if (!chatId || !getChat(chatId)) {
+ if (!chatId || !stores.chatStore.getChat(chatId)) {
return Response.json({ error: "Unknown chat" }, { status: 404 });
}
if (!Array.isArray(body.messages)) {
@@ -37,7 +37,7 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
// take the lesson down: the block is context, not a dependency.
let graphContext: string | null = null;
try {
- graphContext = buildGraphContext();
+ graphContext = buildGraphContext(getGraph(stores.graphStore));
} catch (err) {
console.error(`[chat ${chatId}] graph context build failed:`, err);
}
@@ -49,7 +49,7 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
// Persist even when aborted: the partial transcript (including any
// pending question part) is what makes resume work.
try {
- saveMessages(chatId, messages as UIMessage[]);
+ stores.chatStore.saveMessages(chatId, messages as UIMessage[]);
} catch (err) {
console.error(`[chat ${chatId}] persist failed:`, err, { isAborted });
}
@@ -67,7 +67,7 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
// Skipped under tests: scripted chats are fixtures, not knowledge.
if (process.env.NODE_ENV !== "test") {
try {
- emitChat(chatId);
+ emitChat(chatId, stores);
} catch (err) {
console.error(`[chat ${chatId}] graph emission failed:`, err);
}
diff --git a/src/server/chats.ts b/src/server/chats.ts
index 5bb7f7f..d654a47 100644
--- a/src/server/chats.ts
+++ b/src/server/chats.ts
@@ -1,9 +1,11 @@
-import { createChat, getChat, listChats, titleFromPrompt } from "../store/chats.ts";
+import { stores } from "./stores.ts";
+import { titleFromPrompt } from "../core/contracts.ts";
/**
* Server-side chat entries for the transport layer (app/api/chats*,
- * app/chat/[id]). Today these delegate straight to the fs store; the
+ * app/chat/[id]). Today these delegate straight to the ChatStore port; the
* services stage carves the real orchestration behind this same surface.
*/
-export { createChat, getChat, listChats, titleFromPrompt };
+export const { createChat, getChat, listChats } = stores.chatStore;
+export { titleFromPrompt };
diff --git a/src/server/graph.ts b/src/server/graph.ts
index e7e1740..b22056e 100644
--- a/src/server/graph.ts
+++ b/src/server/graph.ts
@@ -1,5 +1,6 @@
import type { GraphSnapshot } from "../core/contracts.ts";
import { foldStaleChats, graphSnapshot } from "../core/graph.ts";
+import { stores } from "./stores.ts";
/**
* Server-side graph entry for the home view (GET /api/graph): fold any chat
@@ -9,6 +10,6 @@ import { foldStaleChats, graphSnapshot } from "../core/graph.ts";
* same read surface.
*/
export function graphView(): GraphSnapshot {
- foldStaleChats();
- return graphSnapshot();
+ foldStaleChats(stores);
+ return graphSnapshot(stores);
}
diff --git a/src/server/index.ts b/src/server/index.ts
index d36cc03..2f27036 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -8,3 +8,4 @@ export * from "./chat-handler.ts";
export * from "./chats.ts";
export * from "./graph.ts";
export * from "./jobs.ts";
+export * from "./stores.ts";
diff --git a/src/server/jobs.ts b/src/server/jobs.ts
index a7b7a96..5202c4f 100644
--- a/src/server/jobs.ts
+++ b/src/server/jobs.ts
@@ -1,4 +1,4 @@
-import { listJobs } from "../store/jobs.ts";
+import { stores } from "./stores.ts";
/**
* Server-side job-status entry (GET /api/jobs?chatId=…, contracts.ts
@@ -7,4 +7,4 @@ import { listJobs } from "../store/jobs.ts";
* re-syncs the chat when the job flips to done/error.
*/
-export { listJobs };
+export const { listJobs } = stores.jobStore;
diff --git a/src/server/stores.ts b/src/server/stores.ts
new file mode 100644
index 0000000..3a8ba69
--- /dev/null
+++ b/src/server/stores.ts
@@ -0,0 +1,19 @@
+/**
+ * THE COMPOSITION ROOT for storage — the single place concrete store
+ * adapters are wired. Everything else (core, services, agents) codes against
+ * the port types in core/ports.ts and receives instances through this
+ * module. Swapping the fs adapter for SQLite later changes exactly this
+ * file (and the adapter implementations in src/store/).
+ */
+
+import { chatStore } from "../store/chats.ts";
+import { graphStore } from "../store/graph.ts";
+import { jobStore } from "../store/jobs.ts";
+/** The wired adapters. Satisfies core/graph.ts's GraphDeps structurally. */
+export const stores = {
+ chatStore,
+ graphStore,
+ jobStore,
+};
+
+export type Stores = typeof stores;
diff --git a/src/store/chats.ts b/src/store/chats.ts
index 92058c2..007a5da 100644
--- a/src/store/chats.ts
+++ b/src/store/chats.ts
@@ -1,21 +1,25 @@
+/**
+ * ChatStore — the fs JSON adapter (one file per chat in data/chats/).
+ *
+ * Implements core/ports.ts ChatStore; the record shapes live in
+ * core/contracts.ts (ChatRecord/ChatSummary). Idioms: sync fs, tiny
+ * records, id-guarded filenames, JSON with tab indentation. Wired in the
+ * composition root (src/server/stores.ts); nothing else constructs it.
+ */
+
import * as fs from "node:fs";
import * as path from "node:path";
-import type { UIMessage } from "ai";
import { PATHS } from "../../config.ts";
+import type { ChatStore } from "../core/ports.ts";
import type { ChatRecord, ChatSummary, PlanTree } from "../core/contracts.ts";
-
-/**
- * Chat store — one JSON file per chat in data/chats/. The record shape lives
- * in core/contracts (ChatRecord/ChatSummary); this module is the fs adapter's
- * implementation (the storage port formalizes this in a later stage).
- */
+import type { UIMessage } from "ai";
function chatFile(id: string): string {
if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error(`Invalid chat id: ${id}`);
return path.join(PATHS.chats, `${id}.json`);
}
-export function createChat(title: string): ChatRecord {
+function createChat(title: string): ChatRecord {
const now = new Date().toISOString();
const record: ChatRecord = {
id: `chat_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`,
@@ -29,7 +33,7 @@ export function createChat(title: string): ChatRecord {
return record;
}
-export function getChat(id: string): ChatRecord | null {
+function getChat(id: string): ChatRecord | null {
try {
return JSON.parse(fs.readFileSync(chatFile(id), "utf-8")) as ChatRecord;
} catch {
@@ -37,7 +41,7 @@ export function getChat(id: string): ChatRecord | null {
}
}
-export function listChats(): ChatSummary[] {
+function listChats(): ChatSummary[] {
try {
fs.mkdirSync(PATHS.chats, { recursive: true });
return fs
@@ -53,7 +57,7 @@ export function listChats(): ChatSummary[] {
}
/** Persist the full message list (client state + new response) after a turn. */
-export function saveMessages(id: string, messages: UIMessage[]): void {
+function saveMessages(id: string, messages: UIMessage[]): void {
const record = getChat(id);
if (!record) throw new Error(`Chat not found: ${id}`);
record.messages = messages;
@@ -62,7 +66,7 @@ export function saveMessages(id: string, messages: UIMessage[]): void {
}
/** Persist the session plan tree (plan tools call this in execute). */
-export function saveTree(id: string, tree: PlanTree): void {
+function saveTree(id: string, tree: PlanTree): void {
const record = getChat(id);
if (!record) throw new Error(`Chat not found: ${id}`);
record.tree = tree;
@@ -71,8 +75,10 @@ export function saveTree(id: string, tree: PlanTree): void {
fs.writeFileSync(chatFile(id), JSON.stringify(record, null, "\t"), "utf-8");
}
-/** Derive a short title from the first user message. */
-export function titleFromPrompt(prompt: string): string {
- const oneLine = prompt.replace(/\s+/g, " ").trim();
- return oneLine.length > 72 ? `${oneLine.slice(0, 72)}…` : oneLine;
-}
+export const chatStore: ChatStore = {
+ createChat,
+ getChat,
+ listChats,
+ saveMessages,
+ saveTree,
+};
diff --git a/src/store/graph.ts b/src/store/graph.ts
index 35cc936..6666f83 100644
--- a/src/store/graph.ts
+++ b/src/store/graph.ts
@@ -1,9 +1,8 @@
/**
- * Graph ledger store (W4; vision §1, contracts.ts "v1 emission").
- *
- * Five append-only JSONL ledgers at config.LEDGER_FILES:
+ * GraphStore — the fs JSONL adapter: five append-only ledgers at
+ * config.LEDGER_FILES (contracts.ts "v1 emission").
* nodes.jsonl GraphNode — one line per graph node
- * edges.jsonl GraphEdge — one line per edge ASSERTION (a second
+ * edges.jsonl GraphEdge — one line per edge ASSERTION (a second
* session asserting the same (from,to,type)
* appends another line; reads merge)
* events.jsonl LedgerEvent — quiz outcomes + taught events
@@ -11,38 +10,25 @@
* (chatId, treeNodeId) → graphNodeId
* sessions.jsonl SessionCheckpoint— emission checkpoints (foldedAt)
*
- * data/graph/* is exclusively this store's (the legacy V0 scaffold lives in
- * data/legacy-graph). Reads are strict against the contracts.ts shapes:
- * corrupt lines are skipped, never guessed at — the ledgers are the source of
- * truth and everything else is derived (src/core/graph.ts).
- *
- * Same idioms as src/store/chats.ts: sync fs, tiny records, no framework.
+ * Implements core/ports.ts GraphStore. data/graph/* is exclusively this
+ * adapter's. Reads are strict against the contracts.ts shapes: corrupt lines
+ * are skipped, never guessed at — the ledgers are the source of truth and
+ * everything else is derived (core/graph.ts, which takes this port as a
+ * parameter). Same idioms as src/store/chats.ts: sync fs, no framework.
*/
import * as fs from "node:fs";
import * as path from "node:path";
-import { randomBytes } from "node:crypto";
import { LEDGER_FILES } from "../../config.ts";
-import type { GraphEdge, GraphNode, LedgerEvent, LedgerEventKind } from "../core/contracts.ts";
-
-/** The naive-union identity map line: a chat's tree node → graph node. */
-export interface NodeMapping {
- chatId: string;
- treeNodeId: string;
- graphNodeId: string;
-}
-
-/** sessions.jsonl line — the emission checkpoint for one chat. */
-export interface SessionCheckpoint {
- chatId: string;
- /** The chat record's `updatedAt` at the time of the fold. */
- foldedAt: string;
-}
-
-/** "n_" + nanoid-like (contracts.ts GraphNode.id). */
-export function newGraphNodeId(): string {
- return `n_${randomBytes(6).toString("hex")}`;
-}
+import type {
+ GraphEdge,
+ GraphNode,
+ LedgerEvent,
+ LedgerEventKind,
+ NodeMapping,
+ SessionCheckpoint,
+} from "../core/contracts.ts";
+import type { GraphStore } from "../core/ports.ts";
// ─── JSONL primitives ────────────────────────────────────────────────────────
@@ -124,9 +110,9 @@ const isNodeMapping = (v: unknown): v is NodeMapping =>
const isCheckpoint = (v: unknown): v is SessionCheckpoint =>
isRecord(v) && isString(v.chatId) && isString(v.foldedAt);
-// ─── typed ledger access ─────────────────────────────────────────────────────
+// ─── the port implementation ────────────────────────────────────────────────
-export const graphLedgers = {
+export const graphStore: GraphStore = {
appendNode(node: GraphNode): void {
appendLine(LEDGER_FILES.nodes, node);
},
@@ -136,8 +122,8 @@ export const graphLedgers = {
},
/** Append one edge ASSERTION; readers merge lines by (from,to,type). */
- appendEdge(edge: GraphEdge): void {
- appendLine(LEDGER_FILES.edges, edge);
+ appendEdge(assertion: GraphEdge): void {
+ appendLine(LEDGER_FILES.edges, assertion);
},
readEdges(): GraphEdge[] {
return readValid(LEDGER_FILES.edges, isGraphEdge);
diff --git a/src/store/jobs.ts b/src/store/jobs.ts
index d230202..b1d3d8e 100644
--- a/src/store/jobs.ts
+++ b/src/store/jobs.ts
@@ -1,18 +1,19 @@
+/**
+ * JobStore — the fs JSON adapter: one file per background sub-agent job in
+ * data/jobs/ (contracts.ts "THE ASYNC PROTOCOL"). Keyed by toolCallId for
+ * dedup: the chat-handler spawn hook never creates two jobs for the same
+ * tool part. Implements core/ports.ts JobStore. Idioms: sync fs, id-guarded
+ * filenames, JSON with tab indentation. Writes are small and rare (activity
+ * line updates); the read-modify-write sections in the runner contain no
+ * awaits, so they are atomic within the single-threaded event loop.
+ */
+
import * as fs from "node:fs";
import * as path from "node:path";
import { PATHS } from "../../config.ts";
-import type { JobKind, JobRecord } from "../core/contracts.ts";
-
-/**
- * Job store — one JSON file per background sub-agent job in data/jobs/
- * (contracts.ts "THE ASYNC PROTOCOL"). Keyed by toolCallId for dedup: the
- * chat-handler spawn hook never creates two jobs for the same tool part.
- *
- * Follows src/store/chats.ts idioms: sync fs, id-guarded filenames, JSON
- * with tab indentation. Writes are small and rare (activity line updates);
- * the read-modify-write sections in the runner contain no awaits, so they
- * are atomic within the single-threaded event loop.
- */
+import type { JobStore } from "../core/ports.ts";
+import type { CreateJobInit, JobPatch } from "../core/ports.ts";
+import type { JobRecord } from "../core/contracts.ts";
/** Background jobs (data/jobs). Not in config.ts PATHS (orchestrator-owned). */
const JOBS_DIR = path.join(PATHS.data, "jobs");
@@ -22,15 +23,7 @@ function jobFile(id: string): string {
return path.join(JOBS_DIR, `${id}.json`);
}
-export interface CreateJobInit {
- kind: JobKind;
- chatId: string;
- toolCallId: string;
- /** First activity line (defaults to "starting"). */
- activity?: string;
-}
-
-export function createJob(init: CreateJobInit): JobRecord {
+function createJob(init: CreateJobInit): JobRecord {
const now = new Date().toISOString();
const record: JobRecord = {
id: `job_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`,
@@ -47,7 +40,7 @@ export function createJob(init: CreateJobInit): JobRecord {
return record;
}
-export function getJob(id: string): JobRecord | null {
+function getJob(id: string): JobRecord | null {
try {
return JSON.parse(fs.readFileSync(jobFile(id), "utf-8")) as JobRecord;
} catch {
@@ -56,10 +49,7 @@ export function getJob(id: string): JobRecord | null {
}
/** Merge a partial patch into the record (identity fields are immutable). */
-export function updateJob(
- id: string,
- patch: Partial>,
-): JobRecord | null {
+function updateJob(id: string, patch: JobPatch): JobRecord | null {
const record = getJob(id);
if (!record) return null;
const next: JobRecord = { ...record, ...patch, updatedAt: new Date().toISOString() };
@@ -68,7 +58,7 @@ export function updateJob(
}
/** All jobs for a chat, newest activity first. */
-export function listJobs(chatId: string): JobRecord[] {
+function listJobs(chatId: string): JobRecord[] {
try {
fs.mkdirSync(JOBS_DIR, { recursive: true });
return fs
@@ -83,6 +73,14 @@ export function listJobs(chatId: string): JobRecord[] {
}
/** The job fulfilling a given tool part, if any (spawn-hook dedup). */
-export function findJobByToolCallId(chatId: string, toolCallId: string): JobRecord | null {
+function findJobByToolCallId(chatId: string, toolCallId: string): JobRecord | null {
return listJobs(chatId).find((j) => j.toolCallId === toolCallId) ?? null;
}
+
+export const jobStore: JobStore = {
+ createJob,
+ getJob,
+ updateJob,
+ listJobs,
+ findJobByToolCallId,
+};
diff --git a/tests/chat-flow.test.ts b/tests/chat-flow.test.ts
index 0588064..b1d4eef 100644
--- a/tests/chat-flow.test.ts
+++ b/tests/chat-flow.test.ts
@@ -19,7 +19,7 @@ import { MockLanguageModelV4, simulateReadableStream } from "ai/test";
import type { LanguageModelV4StreamPart } from "@ai-sdk/provider";
import { createTeacherAgent } from "../src/agent/teacher-agent.ts";
import { handleChatRequest } from "../src/server/chat-handler.ts";
-import { createChat, getChat, saveMessages } from "../src/store/chats.ts";
+import { chatStore } from "../src/store/chats.ts";
import { buildAnswer, coerceCorrectAnswer, normalizeOptions, resolveCorrect, type QuestionData } from "../src/core/question-core.ts";
import { findPendingToolCall } from "../src/core/pending.ts";
import { PATHS } from "../config.ts";
@@ -113,14 +113,14 @@ describe("teacher chat flow (scripted model)", () => {
it("quiz tool call persists as a pending part; the answer continues the lesson", async () => {
const calls: string[][] = [];
const agent = createTeacherAgent(scriptedModel(calls));
- const chat = createChat("Test: solar system");
+ const chat = chatStore.createChat("Test: solar system");
createdChats.push(chat.id);
// ── Turn 1: learner opens with a topic; teacher probes with a quiz ──
const firstUser = { id: "u1", role: "user", parts: [{ type: "text", text: "teach me the solar system" }] };
await drain(await handleChatRequest(post(chat.id, [firstUser]), agent));
- const saved1 = getChat(chat.id)!;
+ const saved1 = chatStore.getChat(chat.id)!;
assert.equal(saved1.messages.length, 2, "user message + assistant response persisted");
const assistantMsg = saved1.messages[1]!;
assert.equal(assistantMsg.role, "assistant");
@@ -170,7 +170,7 @@ describe("teacher chat flow (scripted model)", () => {
// ── The teacher reacts — as a CONTINUATION of the same assistant message
// (the last client message is the assistant message carrying the tool
// output, so the new text appends to that message's parts). ──
- const saved2 = getChat(chat.id)!;
+ const saved2 = chatStore.getChat(chat.id)!;
assert.equal(saved2.messages.length, 2, "the reaction continues the same assistant message");
const finalParts = saved2.messages[1]!.parts;
const textPart = finalParts.find((p) => p.type === "text");
@@ -200,7 +200,7 @@ describe("teacher chat flow (scripted model)", () => {
// tool-input-start chunk. If a transport change ever stopped emitting
// it, the indicator would silently die — pin the protocol.
const agent = createTeacherAgent(scriptedModel([]));
- const chat = createChat("Test: protocol pin");
+ const chat = chatStore.createChat("Test: protocol pin");
createdChats.push(chat.id);
const firstUser = { id: "u1", role: "user", parts: [{ type: "text", text: "quiz me" }] };
const body = await drain(await handleChatRequest(post(chat.id, [firstUser]), agent));
@@ -214,7 +214,7 @@ describe("teacher chat flow (scripted model)", () => {
it("persists even when the stream is aborted (resume keeps partial state)", async () => {
const calls: string[][] = [];
const agent = createTeacherAgent(scriptedModel(calls));
- const chat = createChat("Test: abort");
+ const chat = chatStore.createChat("Test: abort");
createdChats.push(chat.id);
const req = post(chat.id, [{ id: "u1", role: "user", parts: [{ type: "text", text: "quiz me" }] }]);
@@ -226,17 +226,17 @@ describe("teacher chat flow (scripted model)", () => {
await reader.cancel();
// Give onFinish a tick to fire.
await new Promise((r) => setTimeout(r, 50));
- const saved = getChat(chat.id)!;
+ const saved = chatStore.getChat(chat.id)!;
assert.ok(saved.messages.length >= 1, "partial transcript persisted");
});
});
describe("chat store", () => {
it("round-trips and lists chats", async () => {
- const chat = createChat("Store test");
+ const chat = chatStore.createChat("Store test");
createdChats.push(chat.id);
- saveMessages(chat.id, [{ id: "m1", role: "user", parts: [{ type: "text", text: "hi" }] }]);
- const loaded = getChat(chat.id)!;
+ chatStore.saveMessages(chat.id, [{ id: "m1", role: "user", parts: [{ type: "text", text: "hi" }] }]);
+ const loaded = chatStore.getChat(chat.id)!;
assert.equal(loaded.messages.length, 1);
assert.equal(loaded.title, "Store test");
});
diff --git a/tests/demos.test.tsx b/tests/demos.test.tsx
index 0f1b1be..984e6bc 100644
--- a/tests/demos.test.tsx
+++ b/tests/demos.test.tsx
@@ -43,8 +43,8 @@ import { runDemoBuilder } from "../src/agent/subagents/demo-builder.ts";
import { headlessOverride, type DemoRunResult, type HeadlessApi } from "../src/agent/subagents/headless.ts";
import { demoModelOverride, runDemoJob, runVisualJob, spawnPendingJobs, visualModelOverride } from "../src/agent/subagents/runner.ts";
import { runVisualMaker } from "../src/agent/subagents/visual-maker.ts";
-import { createChat, getChat, saveMessages } from "../src/store/chats.ts";
-import { createJob, findJobByToolCallId, getJob, listJobs } from "../src/store/jobs.ts";
+import { chatStore } from "../src/store/chats.ts";
+import { jobStore } from "../src/store/jobs.ts";
import { handleChatRequest } from "../src/server/chat-handler.ts";
import { createTeacherAgent } from "../src/agent/teacher-agent.ts";
import { artifactRenderers } from "../components/artifacts/index.ts";
@@ -447,9 +447,9 @@ async function drain(res: Response): Promise {
describe("demo/visual job runners", () => {
it("runDemoJob fulfills the part with a tested DemoResult and marks the job done", async () => {
- const chat = createChat("Test: demo runner");
+ const chat = chatStore.createChat("Test: demo runner");
createdChats.push(chat.id);
- saveMessages(chat.id, [
+ chatStore.saveMessages(chat.id, [
{ id: "u1", role: "user", parts: [{ type: "text", text: "show me compounding" }] },
{
id: "a1",
@@ -458,7 +458,7 @@ describe("demo/visual job runners", () => {
},
] as never);
- const job = createJob({ kind: "demo", chatId: chat.id, toolCallId: "call-d1" });
+ const job = jobStore.createJob({ kind: "demo", chatId: chat.id, toolCallId: "call-d1" });
createdJobs.push(job.id);
// runDemoJob has no headless injection point — the module override is the seam.
@@ -475,14 +475,14 @@ describe("demo/visual job runners", () => {
headlessOverride.current = undefined;
}
- const done = getJob(job.id)!;
+ const done = jobStore.getJob(job.id)!;
assert.equal(done.status, "done");
assert.equal(done.activity, "run_demo: clean", "final activity line recorded");
const result = done.result as { title: string; html: string; tested: boolean };
assert.equal(result.title, "Compound interest");
assert.equal(result.tested, true);
- const saved = getChat(chat.id)!;
+ const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-demo");
assert.ok(part && part.type === "tool-demo", "demo tool part persisted");
assert.equal(part.state, "output-available", "part fulfilled");
@@ -490,9 +490,9 @@ describe("demo/visual job runners", () => {
});
it("runVisualJob fulfills the part even on failure and marks the job error", async () => {
- const chat = createChat("Test: visual runner failure");
+ const chat = chatStore.createChat("Test: visual runner failure");
createdChats.push(chat.id);
- saveMessages(chat.id, [
+ chatStore.saveMessages(chat.id, [
{ id: "u1", role: "user", parts: [{ type: "text", text: "draw it" }] },
{
id: "a1",
@@ -501,16 +501,16 @@ describe("demo/visual job runners", () => {
},
] as never);
- const job = createJob({ kind: "visual", chatId: chat.id, toolCallId: "call-v1" });
+ const job = jobStore.createJob({ kind: "visual", chatId: chat.id, toolCallId: "call-v1" });
createdJobs.push(job.id);
await runVisualJob(job.id, { model: scriptedModel([{ text: "cannot" }]) });
- const errored = getJob(job.id)!;
+ const errored = jobStore.getJob(job.id)!;
assert.equal(errored.status, "error");
assert.match(errored.error ?? "", /never wrote an SVG/);
- const saved = getChat(chat.id)!;
+ const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-visual");
assert.ok(part && part.type === "tool-visual", "visual tool part persisted");
assert.equal(part.state, "output-available", "failure still fulfills the part");
@@ -520,7 +520,7 @@ describe("demo/visual job runners", () => {
});
it("the spawn hook dispatches a demo part to the demo runner (kind→runner map)", async () => {
- const chat = createChat("Test: demo spawn dispatch");
+ const chat = chatStore.createChat("Test: demo spawn dispatch");
createdChats.push(chat.id);
// A teacher that calls demo on turn 1 (scripted stream, like jobs.test.ts).
@@ -571,25 +571,25 @@ describe("demo/visual job runners", () => {
),
);
- const job = findJobByToolCallId(chat.id, "call-d2");
+ const job = jobStore.findJobByToolCallId(chat.id, "call-d2");
assert.ok(job, "spawn hook created a job for the demo part");
assert.equal(job!.kind, "demo");
createdJobs.push(job!.id);
// The background runner (fire-and-forget) completes with the overrides.
- await waitFor(() => getJob(job!.id)!.status !== "running", 5000, "demo job completion");
- const done = getJob(job!.id)!;
+ await waitFor(() => jobStore.getJob(job!.id)!.status !== "running", 5000, "demo job completion");
+ const done = jobStore.getJob(job!.id)!;
assert.equal(done.status, "done");
assert.equal(done.activity, "run_demo: clean");
- const saved = getChat(chat.id)!;
+ const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-demo");
assert.ok(part && part.type === "tool-demo", "demo tool part persisted");
assert.equal(part.state, "output-available", "demo part fulfilled by the background runner");
// Idempotency: re-running the spawn hook creates no second job.
spawnPendingJobs(chat.id, saved.messages);
- assert.equal(listJobs(chat.id).length, 1, "no duplicate job for the same tool part");
+ assert.equal(jobStore.listJobs(chat.id).length, 1, "no duplicate job for the same tool part");
} finally {
demoModelOverride.current = undefined;
headlessOverride.current = undefined;
diff --git a/tests/graph-context.test.ts b/tests/graph-context.test.ts
index 2949a87..b15eb85 100644
--- a/tests/graph-context.test.ts
+++ b/tests/graph-context.test.ts
@@ -23,7 +23,8 @@ import { MockLanguageModelV4, simulateReadableStream } from "ai/test";
import type { LanguageModelV4StreamPart } from "@ai-sdk/provider";
import type { GraphEdge, GraphNode, LedgerEvent } from "../src/core/contracts.ts";
import type { NodeStateClass } from "../src/core/contracts.ts";
-import { emitChat, type GraphLedgers } from "../src/core/graph.ts";
+import { emitChat, getGraph } from "../src/core/graph.ts";
+import type { GraphStore } from "../src/core/ports.ts";
import {
buildGraphContext,
GRAPH_CONTEXT_HEADER,
@@ -32,8 +33,9 @@ import {
} from "../src/core/graph-context.ts";
import { createTeacherAgent } from "../src/agent/teacher-agent.ts";
import { handleChatRequest } from "../src/server/chat-handler.ts";
-import { createChat, getChat, saveMessages, saveTree } from "../src/store/chats.ts";
-import { type NodeMapping, type SessionCheckpoint } from "../src/store/graph.ts";
+import { chatStore } from "../src/store/chats.ts";
+import type { NodeMapping, SessionCheckpoint } from "../src/core/contracts.ts";
+import { graphStore } from "../src/store/graph.ts";
import { createTree } from "../src/core/plan-tree.ts";
import { PATHS } from "../config.ts";
@@ -176,9 +178,9 @@ describe("buildGraphContext", () => {
it("reads the live ledgers without throwing (read-only integration)", () => {
// Other suites (graph.test.ts) mutate data/graph concurrently, so only
- // assert the shape of the result, never its content. Read-only is
- // structural: buildGraphContext only ever calls getGraph().
- const out = buildGraphContext();
+ // assert the shape of the result, never its content. Structural note:
+ // the caller now hands in getGraph(graphStore) — the entry point is pure.
+ const out = buildGraphContext(getGraph(graphStore));
assert.ok(out === null || out.includes(GRAPH_CONTEXT_HEADER));
});
});
@@ -248,10 +250,10 @@ describe("graph-context injection (chat-flow style)", () => {
assert.ok(context, "fixture graph renders a block");
// Exactly what chat-handler does per request when no agent is passed:
- // createTeacherAgent(model, tools, buildGraphContext()).
+ // createTeacherAgent(model, tools, buildGraphContext(getGraph(graphStore))).
const prompts: string[] = [];
const agent = createTeacherAgent(capturingModel(prompts), undefined, context);
- const chat = createChat("Test: graph context injection");
+ const chat = chatStore.createChat("Test: graph context injection");
createdChats.push(chat.id);
await drain(
@@ -279,7 +281,7 @@ describe("graph-context injection (chat-flow style)", () => {
it("no block is injected when the context is null (new learner)", async () => {
const prompts: string[] = [];
const agent = createTeacherAgent(capturingModel(prompts));
- const chat = createChat("Test: no graph context");
+ const chat = chatStore.createChat("Test: no graph context");
createdChats.push(chat.id);
await drain(
await handleChatRequest(
@@ -295,7 +297,7 @@ describe("graph-context injection (chat-flow style)", () => {
// ─── exact-match merge (emitChat dedup) ─────────────────────────────────────
-/** An in-memory stand-in for the five ledgers (see GraphLedgers in graph.ts). */
+/** An in-memory stand-in for the five ledgers (the GraphStore port, core/ports.ts). */
function memoryLedgers() {
const nodes: GraphNode[] = [];
const edges: GraphEdge[] = [];
@@ -313,31 +315,31 @@ function memoryLedgers() {
readMappings: () => mappings.map((m) => ({ ...m })),
appendCheckpoint: (c: SessionCheckpoint) => void checkpoints.push(c),
readCheckpoints: () => checkpoints.map((c) => ({ ...c })),
- // Test accessors (not part of the GraphLedgers surface).
+ // Test accessors (not part of the GraphStore surface).
counts: { get nodes() { return nodes.length; }, get mappings() { return mappings.length; } },
- } satisfies GraphLedgers & { counts: { nodes: number; mappings: number } };
+ } satisfies GraphStore & { counts: { nodes: number; mappings: number } };
}
/** A real chat record with a stored tree (emitChat reads the real chat store). */
function fixtureChat(title: string, tree: ReturnType) {
- const chat = createChat(title);
+ const chat = chatStore.createChat(title);
createdChats.push(chat.id);
- saveTree(chat.id, tree);
- saveMessages(chat.id, [{ id: "u1", role: "user", parts: [{ type: "text", text: "go" }] }]);
- return getChat(chat.id)!;
+ chatStore.saveTree(chat.id, tree);
+ chatStore.saveMessages(chat.id, [{ id: "u1", role: "user", parts: [{ type: "text", text: "go" }] }]);
+ return chatStore.getChat(chat.id)!;
}
describe("exact-match merge (emitChat)", () => {
it("maps a case/whitespace-identical title onto the existing node instead of duplicating", () => {
const ledgers = memoryLedgers();
const chat1 = fixtureChat("Merge A", createTree([{ id: "cr", title: "Chain rule intuition" }], []));
- let stats = emitChat(chat1.id, ledgers);
+ let stats = emitChat(chat1.id, { chatStore, graphStore: ledgers });
assert.deepEqual(stats, { nodes: 1, edges: 0, events: 0 });
const firstId = ledgers.readNodes()[0]!.id;
// Second session, same proposition: different casing + padding.
const chat2 = fixtureChat("Merge B", createTree([{ id: "cr2", title: " chain Rule INTUITION " }], []));
- stats = emitChat(chat2.id, ledgers);
+ stats = emitChat(chat2.id, { chatStore, graphStore: ledgers });
assert.deepEqual(stats, { nodes: 0, edges: 0, events: 0 }, "no duplicate node appended");
assert.equal(ledgers.counts.nodes, 1, "still exactly one graph node");
@@ -357,7 +359,7 @@ describe("exact-match merge (emitChat)", () => {
createdAt: "2026-08-22T00:00:00.000Z",
});
const chat = fixtureChat("Merge alias", createTree([{ id: "d", title: "The Derivative" }], []));
- const stats = emitChat(chat.id, ledgers);
+ const stats = emitChat(chat.id, { chatStore, graphStore: ledgers });
assert.deepEqual(stats, { nodes: 0, edges: 0, events: 0 }, "alias match → no new node");
assert.deepEqual(ledgers.readMappings(), [{ chatId: chat.id, treeNodeId: "d", graphNodeId: "n_alias" }]);
});
@@ -365,12 +367,12 @@ describe("exact-match merge (emitChat)", () => {
it("does NOT fuzzy-match near-identical titles (that stays deferred)", () => {
const ledgers = memoryLedgers();
const chat1 = fixtureChat("Fuzzy A", createTree([{ id: "cr", title: "Chain rule intuition" }], []));
- emitChat(chat1.id, ledgers);
+ emitChat(chat1.id, { chatStore, graphStore: ledgers });
const chat2 = fixtureChat(
"Fuzzy B",
createTree([{ id: "cr2", title: "Chain rules intuition" }], []),
);
- const stats = emitChat(chat2.id, ledgers);
+ const stats = emitChat(chat2.id, { chatStore, graphStore: ledgers });
assert.equal(stats.nodes, 1, "near-miss titles stay separate nodes");
assert.equal(ledgers.counts.nodes, 2);
});
@@ -387,7 +389,7 @@ describe("exact-match merge (emitChat)", () => {
[{ from: "base", to: "chain" }],
),
);
- emitChat(chat1.id, ledgers);
+ emitChat(chat1.id, { chatStore, graphStore: ledgers });
// Second session re-teaches the same two propositions (exact titles)
// and asserts the same edge — it must dedupe onto the existing nodes.
@@ -401,7 +403,7 @@ describe("exact-match merge (emitChat)", () => {
[{ from: "base", to: "chain" }],
),
);
- const stats = emitChat(chat2.id, ledgers);
+ const stats = emitChat(chat2.id, { chatStore, graphStore: ledgers });
// A new ASSERTION line is appended (provenance is honest) — reads merge
// by (from,to,type), so the derived graph still has one edge with both
// sessions in its provenance.
diff --git a/tests/graph.test.ts b/tests/graph.test.ts
index aa0788b..1c55bde 100644
--- a/tests/graph.test.ts
+++ b/tests/graph.test.ts
@@ -15,11 +15,14 @@ import type { UIMessage } from "ai";
import type { PlanTree, PlanToolResult } from "../src/core/contracts.ts";
import type { QuestionAnswerData } from "../src/core/question-core.ts";
import { createTree, markDone, removeNode } from "../src/core/plan-tree.ts";
-import { emitChat, foldStaleChats, getGraph, graphSnapshot } from "../src/core/graph.ts";
-import { graphLedgers } from "../src/store/graph.ts";
-import { createChat, getChat, saveMessages, saveTree } from "../src/store/chats.ts";
+import { emitChat, foldStaleChats, getGraph, graphSnapshot, type GraphDeps } from "../src/core/graph.ts";
+import { graphStore } from "../src/store/graph.ts";
+import { chatStore } from "../src/store/chats.ts";
import { LEDGER_FILES, PATHS } from "../config.ts";
+/** The wired fs adapters, exactly what src/server/stores.ts passes in production. */
+const graphDeps = { chatStore, graphStore } as const satisfies GraphDeps;
+
// ─── ledger isolation (backup-and-clear of data/graph/*.jsonl) ──────────────
const LEDGER_PATHS = Object.values(LEDGER_FILES);
@@ -95,11 +98,11 @@ function answer(over: Partial): QuestionAnswerData {
/** Create a chat in the real store with a tree and messages; returns the record. */
function fixtureChat(title: string, tree: PlanTree | null, messages: UIMessage[]) {
- const chat = createChat(title);
+ const chat = chatStore.createChat(title);
createdChats.push(chat.id);
- if (tree) saveTree(chat.id, tree);
- saveMessages(chat.id, messages);
- return getChat(chat.id)!;
+ if (tree) chatStore.saveTree(chat.id, tree);
+ chatStore.saveMessages(chat.id, messages);
+ return chatStore.getChat(chat.id)!;
}
/** The fixture tree: alpha → beta, gamma free-floating, alpha done. */
@@ -188,9 +191,9 @@ let chat2Id = "";
/** Everything the graph holds for a set of chats (other processes' test
* emissions run concurrently against the same files — scope, never assume). */
function scopedGraph(chatIds: string[]) {
- const graph = getGraph();
+ const graph = getGraph(graphStore);
const nodeIds = new Set(
- graphLedgers
+ graphStore
.readMappings()
.filter((m) => chatIds.includes(m.chatId))
.map((m) => m.graphNodeId),
@@ -204,7 +207,7 @@ function scopedGraph(chatIds: string[]) {
describe("graph emission (emitChat)", () => {
it("folds tree nodes/edges and quiz/mark_done events with the probe/check boundary", () => {
- const stats = emitChat(chat1.id);
+ const stats = emitChat(chat1.id, graphDeps);
assert.deepEqual(stats, { nodes: 3, edges: 1, events: 6 });
const graph = scopedGraph([chat1.id]);
@@ -262,14 +265,14 @@ describe("graph emission (emitChat)", () => {
});
it("is idempotent — re-emission appends nothing", () => {
- const stats = emitChat(chat1.id);
+ const stats = emitChat(chat1.id, graphDeps);
assert.deepEqual(stats, { nodes: 0, edges: 0, events: 0 });
const graph = scopedGraph([chat1.id]);
assert.equal(graph.nodes.length, 3);
assert.equal(graph.edges.length, 1);
assert.equal(graph.events.length, 6);
// exactly one checkpoint line per fold, though — checkpoints are a log
- assert.equal(graphLedgers.readCheckpoints().filter((c) => c.chatId === chat1.id).length, 2);
+ assert.equal(graphStore.readCheckpoints().filter((c) => c.chatId === chat1.id).length, 2);
});
it("accumulates edge provenance when another chat maps onto the same nodes", () => {
@@ -288,13 +291,13 @@ describe("graph emission (emitChat)", () => {
assistant("a1", [planPart("p1", "plan_init", { nodes: [], edges: [] }, tree2)]),
]);
- const before = getGraph();
+ const before = getGraph(graphStore);
const gAlpha = before.nodes.find((n) => n.statement === "Alpha intuition")!.id;
const gBeta = before.nodes.find((n) => n.statement === "Beta rule")!.id;
- graphLedgers.appendMapping({ chatId: chat2.id, treeNodeId: "alpha", graphNodeId: gAlpha });
- graphLedgers.appendMapping({ chatId: chat2.id, treeNodeId: "beta", graphNodeId: gBeta });
+ graphStore.appendMapping({ chatId: chat2.id, treeNodeId: "alpha", graphNodeId: gAlpha });
+ graphStore.appendMapping({ chatId: chat2.id, treeNodeId: "beta", graphNodeId: gBeta });
- const stats = emitChat(chat2.id);
+ const stats = emitChat(chat2.id, graphDeps);
assert.deepEqual(stats, { nodes: 0, edges: 1, events: 0 });
chat2Id = chat2.id;
@@ -305,7 +308,7 @@ describe("graph emission (emitChat)", () => {
});
it("derives node states, sessions, and node provenance in graphSnapshot", () => {
- const snap = graphSnapshot();
+ const snap = graphSnapshot(graphDeps);
const idByStatement = new Map(snap.nodes.map((n) => [n.statement, n.id]));
assert.equal(snap.nodeStates[idByStatement.get("Alpha intuition")!], "taught");
assert.equal(snap.nodeStates[idByStatement.get("Beta rule")!], "missed");
@@ -336,7 +339,7 @@ describe("graph emission (emitChat)", () => {
assistant("a2", [planPart("p2", "plan_remove_node", { id: "y" }, prunedTree)]),
]);
- const stats = emitChat(chat.id);
+ const stats = emitChat(chat.id, graphDeps);
assert.deepEqual(stats, { nodes: 1, edges: 0, events: 0 }); // y pruned, edge cascaded away
const graph = scopedGraph([chat.id]);
@@ -345,7 +348,7 @@ describe("graph emission (emitChat)", () => {
});
it("returns zeros for unknown chats", () => {
- assert.deepEqual(emitChat("chat_does_not_exist"), { nodes: 0, edges: 0, events: 0 });
+ assert.deepEqual(emitChat("chat_does_not_exist", graphDeps), { nodes: 0, edges: 0, events: 0 });
});
});
@@ -366,11 +369,11 @@ describe("catch-up (foldStaleChats)", () => {
]),
]);
- const folded = foldStaleChats();
+ const folded = foldStaleChats(graphDeps);
assert.ok(folded >= 1, "the catch-up fixture was folded");
- assert.equal(graphLedgers.readCheckpoints().filter((c) => c.chatId === chat.id).length, 1);
+ assert.equal(graphStore.readCheckpoints().filter((c) => c.chatId === chat.id).length, 1);
- const snap = graphSnapshot();
+ const snap = graphSnapshot(graphDeps);
const solo = snap.nodes.find((n) => n.statement === "Solo node");
assert.ok(solo, "solo node was emitted by the catch-up fold");
assert.equal(snap.nodeStates[solo.id], "known"); // correct check, no taught event
@@ -378,8 +381,8 @@ describe("catch-up (foldStaleChats)", () => {
// Already checkpointed → not folded again (other test files' chats may
// legitimately fold here, so assert on THIS chat only).
- foldStaleChats();
- assert.equal(graphLedgers.readCheckpoints().filter((c) => c.chatId === chat.id).length, 1);
+ foldStaleChats(graphDeps);
+ assert.equal(graphStore.readCheckpoints().filter((c) => c.chatId === chat.id).length, 1);
});
});
@@ -388,14 +391,14 @@ describe("catch-up (foldStaleChats)", () => {
describe("graph ledger store", () => {
it("round-trips lines and skips corrupt / foreign-shaped lines (strict reads)", () => {
const node = { id: "n_storetest", statement: "Store test", aliases: [], kind: "truth" as const, createdAt: "2026-08-22T00:00:00.000Z" };
- graphLedgers.appendNode(node);
+ graphStore.appendNode(node);
// A torn append and a legacy V0-shaped node (different schema) — both skipped.
fs.appendFileSync(
LEDGER_FILES.nodes,
`{not json}\n${JSON.stringify({ id: "legacy", statement: "Legacy shape", domain: "x", state: "known" })}\n`,
"utf-8",
);
- const nodes = graphLedgers.readNodes().filter((n) => n.id === "n_storetest" || n.id === "legacy");
+ const nodes = graphStore.readNodes().filter((n) => n.id === "n_storetest" || n.id === "legacy");
assert.equal(nodes.length, 1);
assert.equal(nodes[0]!.statement, "Store test");
});
diff --git a/tests/jobs.test.ts b/tests/jobs.test.ts
index 992b4ab..7a6ba3e 100644
--- a/tests/jobs.test.ts
+++ b/tests/jobs.test.ts
@@ -24,8 +24,8 @@ import { MockLanguageModelV4, simulateReadableStream } from "ai/test";
import type { LanguageModelV4StreamPart } from "@ai-sdk/provider";
import { createTeacherAgent } from "../src/agent/teacher-agent.ts";
import { handleChatRequest } from "../src/server/chat-handler.ts";
-import { createChat, getChat } from "../src/store/chats.ts";
-import { createJob, findJobByToolCallId, getJob, listJobs, updateJob } from "../src/store/jobs.ts";
+import { chatStore } from "../src/store/chats.ts";
+import { jobStore } from "../src/store/jobs.ts";
import { researchModelOverride, runResearchJob, spawnPendingJobs } from "../src/agent/subagents/runner.ts";
import { createResearcherAgent } from "../src/agent/subagents/researcher.ts";
import { PATHS } from "../config.ts";
@@ -86,32 +86,32 @@ function post(chatId: string, messages: unknown[]): Request {
describe("job store", () => {
it("create → get → update → list round-trips", () => {
- const job = createJob({ kind: "research", chatId: "chat_storetest", toolCallId: "call-store" });
+ const job = jobStore.createJob({ kind: "research", chatId: "chat_storetest", toolCallId: "call-store" });
trackJob(job.id);
assert.match(job.id, /^job_/);
assert.equal(job.status, "running");
assert.equal(job.activity, "starting");
- const loaded = getJob(job.id)!;
+ const loaded = jobStore.getJob(job.id)!;
assert.equal(loaded.toolCallId, "call-store");
assert.equal(loaded.kind, "research");
- const updated = updateJob(job.id, { activity: 'web_search: "test"', status: "done", result: { brief: "b" } })!;
+ const updated = jobStore.updateJob(job.id, { activity: 'web_search: "test"', status: "done", result: { brief: "b" } })!;
assert.equal(updated.activity, 'web_search: "test"');
assert.equal(updated.status, "done");
assert.ok(updated.updatedAt >= job.updatedAt);
// immutable identity fields survive a patch
assert.equal(updated.toolCallId, "call-store");
- assert.equal(getJob(updated.id)!.toolCallId, "call-store");
+ assert.equal(jobStore.getJob(updated.id)!.toolCallId, "call-store");
- const listed = listJobs("chat_storetest");
+ const listed = jobStore.listJobs("chat_storetest");
assert.ok(listed.some((j) => j.id === job.id));
- assert.equal(listJobs("chat_other").some((j) => j.id === job.id), false, "jobs are scoped to their chat");
+ assert.equal(jobStore.listJobs("chat_other").some((j) => j.id === job.id), false, "jobs are scoped to their chat");
- const byTool = findJobByToolCallId("chat_storetest", "call-store");
+ const byTool = jobStore.findJobByToolCallId("chat_storetest", "call-store");
assert.equal(byTool?.id, job.id);
- assert.equal(findJobByToolCallId("chat_storetest", "call-missing"), null);
+ assert.equal(jobStore.findJobByToolCallId("chat_storetest", "call-missing"), null);
});
});
@@ -155,7 +155,7 @@ function researchCallingTeacher(): MockLanguageModelV4 {
describe("spawn hook (async protocol §2)", () => {
it("a pending research part in the final assistant message spawns exactly one job", async () => {
- const chat = createChat("Test: research spawn");
+ const chat = chatStore.createChat("Test: research spawn");
trackChat(chat.id);
const agent = createTeacherAgent(researchCallingTeacher());
@@ -163,13 +163,13 @@ describe("spawn hook (async protocol §2)", () => {
await drain(await handleChatRequest(post(chat.id, [firstUser]), agent));
// The research part is pending (input-available) in the stored chat.
- const saved = getChat(chat.id)!;
+ const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-research");
assert.ok(part && part.type === "tool-research", "research tool part persisted");
assert.equal(part.state, "input-available", "job tool part stays pending until the runner fulfills it");
// A job record exists for it.
- const job = findJobByToolCallId(chat.id, "call-r1");
+ const job = jobStore.findJobByToolCallId(chat.id, "call-r1");
assert.ok(job, "spawn hook created a job record");
assert.equal(job!.kind, "research");
assert.equal(job!.status, "running");
@@ -177,7 +177,7 @@ describe("spawn hook (async protocol §2)", () => {
// Re-running the spawn hook (idempotency) does not create a second job.
spawnPendingJobs(chat.id, saved.messages);
- assert.equal(listJobs(chat.id).length, 1, "no duplicate job for the same tool part");
+ assert.equal(jobStore.listJobs(chat.id).length, 1, "no duplicate job for the same tool part");
});
});
@@ -249,7 +249,7 @@ describe("research runner (async protocol §3)", () => {
it("fulfills the part with a ResearchResult and marks the job done with activity recorded", async () => {
const restoreFetch = stubFetch();
try {
- const chat = createChat("Test: runner completion");
+ const chat = chatStore.createChat("Test: runner completion");
trackChat(chat.id);
// A pending research part, as the spawn hook would find it.
@@ -265,23 +265,22 @@ describe("research runner (async protocol §3)", () => {
},
] as never;
// saveMessages requires the chat to exist; use the store directly.
- const { saveMessages } = await import("../src/store/chats.ts");
- saveMessages(chat.id, messages);
+ chatStore.saveMessages(chat.id, messages);
- const job = createJob({ kind: "research", chatId: chat.id, toolCallId: "call-run1" });
+ const job = jobStore.createJob({ kind: "research", chatId: chat.id, toolCallId: "call-run1" });
trackJob(job.id);
await runResearchJob(job.id, { model: researcherModel() });
// The job is done, with the activity line from the tool call.
- const done = getJob(job.id)!;
+ const done = jobStore.getJob(job.id)!;
assert.equal(done.status, "done");
assert.equal(done.activity, 'web_search: "sigma.js latest version"', "activity line recorded");
assert.ok(done.result, "result stored on the job");
// The stored chat's part flipped to output-available with a
// ResearchResult-shaped output.
- const saved = getChat(chat.id)!;
+ const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-research");
assert.ok(part && part.type === "tool-research");
assert.equal(part.state, "output-available");
@@ -300,10 +299,9 @@ describe("research runner (async protocol §3)", () => {
throw new Error("model exploded");
},
});
- const chat = createChat("Test: runner failure");
+ const chat = chatStore.createChat("Test: runner failure");
trackChat(chat.id);
- const { saveMessages } = await import("../src/store/chats.ts");
- saveMessages(chat.id, [
+ chatStore.saveMessages(chat.id, [
{ id: "u1", role: "user", parts: [{ type: "text", text: "hi" }] },
{
id: "a1",
@@ -312,16 +310,16 @@ describe("research runner (async protocol §3)", () => {
},
] as never);
- const job = createJob({ kind: "research", chatId: chat.id, toolCallId: "call-err1" });
+ const job = jobStore.createJob({ kind: "research", chatId: chat.id, toolCallId: "call-err1" });
trackJob(job.id);
await runResearchJob(job.id, { model: failing });
- const errored = getJob(job.id)!;
+ const errored = jobStore.getJob(job.id)!;
assert.equal(errored.status, "error");
assert.match(errored.error ?? "", /model exploded/);
- const saved = getChat(chat.id)!;
+ const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-research");
assert.ok(part && part.type === "tool-research");
assert.equal(part.state, "output-available", "failure still fulfills the part");
diff --git a/tests/plan-tree.test.ts b/tests/plan-tree.test.ts
index d19a43d..bbdad7b 100644
--- a/tests/plan-tree.test.ts
+++ b/tests/plan-tree.test.ts
@@ -26,7 +26,7 @@ import {
updateNode,
} from "../src/core/plan-tree.ts";
import { planTools } from "../src/agent/tools/plan.ts";
-import { createChat, getChat } from "../src/store/chats.ts";
+import { chatStore } from "../src/store/chats.ts";
import { PATHS } from "../config.ts";
const N = (id: string, title = id, summary?: string) => ({ id, title, ...(summary ? { summary } : {}) });
@@ -228,7 +228,7 @@ async function exec(tools: ReturnType, name: string, input: un
}
function newChat(title: string): string {
- const chat = createChat(title);
+ const chat = chatStore.createChat(title);
createdChats.push(chat.id);
return chat.id;
}
@@ -251,7 +251,7 @@ describe("plan tools (execute against the real store)", () => {
assert.equal(res.tree.nodes.length, 2);
assert.deepEqual(res.tree.edges, [{ from: "truth", to: "goal" }]);
- const saved = getChat(chatId)!.tree;
+ const saved = chatStore.getChat(chatId)!.tree;
assert.ok(saved, "tree persisted to the chat record");
assert.deepEqual(saved, res.tree);
});
@@ -268,7 +268,7 @@ describe("plan tools (execute against the real store)", () => {
assert.equal(res.error, "Tree already initialized — use the mutation tools");
assert.deepEqual(res.tree.nodes.map((n: { id: string }) => n.id), ["a"], "existing tree returned, not wiped");
- const saved = getChat(chatId)!.tree!;
+ const saved = chatStore.getChat(chatId)!.tree!;
assert.deepEqual(saved.nodes.map((n) => n.id), ["a"]);
});
@@ -288,7 +288,7 @@ describe("plan tools (execute against the real store)", () => {
assert.equal(res.ok, false);
assert.match(res.error!, /cycle/);
assert.deepEqual(res.tree, emptyTree());
- assert.equal(getChat(chatId)!.tree, undefined, "nothing persisted on failure");
+ assert.equal(chatStore.getChat(chatId)!.tree, undefined, "nothing persisted on failure");
});
it("mutation round-trip: add node with parents, set current, mark done — each persists", async () => {
@@ -315,17 +315,17 @@ describe("plan tools (execute against the real store)", () => {
["ratelimit→burst", "ratelimit→detour"],
);
assert.equal(added.tree.version, 2);
- assert.deepEqual(getChat(chatId)!.tree!, added.tree, "add_node persisted");
+ assert.deepEqual(chatStore.getChat(chatId)!.tree!, added.tree, "add_node persisted");
const current = await exec(tools, "plan_set_current", { id: "detour" });
assert.equal(current.ok, true);
assert.equal(current.tree.currentNodeId, "detour");
- assert.equal(getChat(chatId)!.tree!.currentNodeId, "detour", "set_current persisted");
+ assert.equal(chatStore.getChat(chatId)!.tree!.currentNodeId, "detour", "set_current persisted");
const done = await exec(tools, "plan_mark_done", { id: "ratelimit" });
assert.equal(done.ok, true);
assert.deepEqual(done.tree.doneNodeIds, ["ratelimit"]);
- assert.deepEqual(getChat(chatId)!.tree!.doneNodeIds, ["ratelimit"], "mark_done persisted");
+ assert.deepEqual(chatStore.getChat(chatId)!.tree!.doneNodeIds, ["ratelimit"], "mark_done persisted");
assert.equal(done.tree.version, 4);
});
@@ -333,7 +333,7 @@ describe("plan tools (execute against the real store)", () => {
const chatId = newChat("Plan tools: invalid ops");
const tools = planTools({ chatId });
await exec(tools, "plan_init", { nodes: [{ id: "a", title: "A" }] });
- const before = getChat(chatId)!.tree!;
+ const before = chatStore.getChat(chatId)!.tree!;
const dup = await exec(tools, "plan_add_node", { id: "a", title: "Impostor" });
assert.equal(dup.ok, false);
@@ -348,7 +348,7 @@ describe("plan tools (execute against the real store)", () => {
assert.equal(badEdge.ok, false);
assert.match(badEdge.error!, /self-loop/);
- assert.deepEqual(getChat(chatId)!.tree!, before, "record untouched by failed ops");
+ assert.deepEqual(chatStore.getChat(chatId)!.tree!, before, "record untouched by failed ops");
});
it("mutation tools work on a fresh (uninitialized) chat: the tree seeds from empty", async () => {
@@ -357,7 +357,7 @@ describe("plan tools (execute against the real store)", () => {
const res = await exec(tools, "plan_add_node", { id: "a", title: "A" });
assert.equal(res.ok, true);
assert.equal(res.tree.nodes.length, 1);
- assert.ok(getChat(chatId)!.tree, "tree seeded without plan_init");
+ assert.ok(chatStore.getChat(chatId)!.tree, "tree seeded without plan_init");
});
it("unknown chat returns ok:false with the empty tree", async () => {