amosblomqvist
b07c907ffd
The minimal implementation of the 2026-09-02 graph vision (docs/vision.md §1):
- contracts/graph.ts: every node is a TRUE proposition (statement is both
rendering label and identity key; required description; no kind, no name).
Edges are follows (derivable) / supports (grounds without entailing) with
message-granular provenance points {chatId, messageId}. Events reduce to
correct/miss/dont-know plus observation (understanding notes); no taught
events, no misconception kind.
- extraction.ts: extractor is TREE-BLIND (transcript only, no plan tree) and
free-form; auditor sees findings + the current graph, owns faithfulness and
identity (link-or-create verdict per proposition, recorded as linkTo);
transcriptView tags every line with its message id (provenance anchors).
- core/graph.ts merger: applies verdicts deterministically — linkTo appends
a link line (phrasings join aliases, provenance unions; reads merge by id),
absent creates; NO string matching anywhere. Quiz events rebuilt from tool
parts with attribution-only nodeId resolution; understanding notes become
observation events (obs:<sourceId>); mapping lines are the verdict audit
trail and make re-merges idempotent.
- deriveNodeStates: transitional — latest quiz event wins (known/missed/
dont-know, else candidate); taught unreachable until the state-model
ideation lands.
- graph-context.ts + 50-graph-context.md: follows chains, hotspot grouping,
state vocabulary updated for the new event kinds.
- graph-view.tsx: node label is the statement; detail shows statement +
description.
- tests: merger verdicts (link, no-string-match, cross-chat assertions),
tree-blind pipeline end-to-end, follows vocabulary in context tests.
276/276 green.
96 lines
3.7 KiB
TypeScript
96 lines
3.7 KiB
TypeScript
/**
|
|
* 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 / understanding observation. */
|
|
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<Omit<JobRecord, "id" | "kind" | "chatId" | "toolCallId" | "createdAt">>;
|
|
|
|
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;
|
|
}
|