diff --git a/src/triggers/events.ts b/src/triggers/events.ts index 4c887f5f9c..806684e2b5 100644 --- a/src/triggers/events.ts +++ b/src/triggers/events.ts @@ -1,6 +1,6 @@ import { TriggerAction, type IIIClient } from "iii-sdk"; import type { CompressedObservation, Memory, Session } from "../types.js"; -import { KV } from "../state/schema.js"; +import { KV, fingerprintId } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { emitLiveEvent } from "../viewer/live-events.js"; import { isReflectEnabled } from "../functions/slots.js"; @@ -10,7 +10,9 @@ import { getConsolidationCooldownMs, isAgentScopeIsolated, isConsolidationEnabled, + isGraphExtractionEnabled, } from "../config.js"; +import { getGraphGeneration } from "../state/graph-generation.js"; import { logger } from "../logger.js"; import { noteMemoryChange, noteSessionChange } from "../state/viewer-counts.js"; @@ -18,6 +20,14 @@ import { noteMemoryChange, noteSessionChange } from "../state/viewer-counts.js"; // the per-turn session-stop fan-out. const CONSOLIDATION_MARKER_KEY = "consolidation:lastRun"; +const observationFingerprint = (obs: CompressedObservation[], context: string): string => + fingerprintId("gx", `${context}|${obs.map((o) => o.id).sort().join(",")}`); + +async function graphExtractContext(kv: StateKV): Promise { + const generation = await getGraphGeneration(kv).catch(() => null); + return `${generation ?? "legacy"}|${isGraphExtractionEnabled() ? "llm" : "heuristic"}`; +} + async function consolidationDueUnserialized(kv: StateKV): Promise { const cooldownMs = getConsolidationCooldownMs(); if (cooldownMs <= 0) return true; // debounce disabled @@ -70,7 +80,44 @@ export function registerEventTriggers(sdk: IIIClient, kv: StateKV): void { ); const compressed = observations.filter((o) => o.title); if (compressed.length > 0) { - fireVoid("mem::graph-extract", { observations: compressed }); + const session = await kv + .get(KV.sessions, data.sessionId) + .catch(() => null); + const at = session?.graphExtractedAt; + const mark = session?.graphExtractedDigest; + const context = await graphExtractContext(kv); + let batch = compressed; + if (typeof at === "string") { + const seen = compressed.filter((o) => o.timestamp <= at); + if (observationFingerprint(seen, context) === mark) { + batch = compressed.filter((o) => o.timestamp > at); + } else { + logger.info("graph-extract watermark stale, re-extracting session", { + sessionId: data.sessionId, + atOrBelow: seen.length, + total: compressed.length, + }); + } + } + if (batch.length > 0) { + const newest = batch.reduce( + (max, o) => (o.timestamp > max ? o.timestamp : max), + "", + ); + await sdk.trigger({ + function_id: "mem::graph-extract", + payload: { observations: batch }, + action: TriggerAction.Void(), + }); + if (session) await kv.update(KV.sessions, data.sessionId, [ + { type: "set", path: "graphExtractedAt", value: newest }, + { + type: "set", + path: "graphExtractedDigest", + value: observationFingerprint(compressed, context), + }, + ]); + } } } catch (err) { logger.warn("graph-extract trigger failed", { diff --git a/src/types.ts b/src/types.ts index c6d6a37026..ff9413ee29 100644 --- a/src/types.ts +++ b/src/types.ts @@ -13,6 +13,8 @@ export interface Session { summary?: string; commitShas?: string[]; agentId?: string; + graphExtractedAt?: string; + graphExtractedDigest?: string; } export interface ProjectSessionIndexEntry { diff --git a/test/graph-extract-incremental.test.ts b/test/graph-extract-incremental.test.ts new file mode 100644 index 0000000000..918e464c26 --- /dev/null +++ b/test/graph-extract-incremental.test.ts @@ -0,0 +1,362 @@ +import { describe, it, expect, beforeEach, vi } from "vitest"; +import type { CompressedObservation } from "../src/types.js"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +vi.mock("../src/config.js", () => ({ + getAgentId: vi.fn(() => undefined), + isConsolidationEnabled: vi.fn(() => false), + getConsolidationCooldownMs: vi.fn(() => 300000), + isGraphExtractionEnabled: vi.fn(() => false), +})); + +vi.mock("../src/functions/slots.js", () => ({ + isReflectEnabled: vi.fn(() => false), +})); + +import { registerEventTriggers } from "../src/triggers/events.js"; +import { logger } from "../src/logger.js"; +import { isGraphExtractionEnabled } from "../src/config.js"; +import { KV } from "../src/state/schema.js"; + +const STALE = "graph-extract watermark stale, re-extracting session"; + +// These tests pin the extract to the observations captured since the last +// successful one. Why that matters is in src/triggers/events.ts. + +const SID = "ses_1"; + +function obs(id: string, timestamp: string): CompressedObservation { + return { + id, + sessionId: SID, + timestamp, + type: "conversation", + title: id, + facts: [], + narrative: id, + concepts: [], + files: [], + importance: 0.5, + }; +} + +// A KV that persists writes, so the watermark survives between simulated +// per-turn stops the way the real session record does. +function persistentKV() { + const store = new Map>(); + const scope = (s: string) => { + if (!store.has(s)) store.set(s, new Map()); + return store.get(s)!; + }; + return { + store, + scope, + get: vi.fn(async (s: string, k: string) => scope(s).get(k) ?? null), + update: vi.fn( + async ( + s: string, + k: string, + ops: Array<{ type: string; path: string; value?: unknown }>, + ) => { + const cur = (scope(s).get(k) ?? {}) as Record; + for (const op of ops) if (op.type === "set") cur[op.path] = op.value; + scope(s).set(k, cur); + return cur; + }, + ), + list: vi.fn(async (s: string) => [...scope(s).values()]), + }; +} + +type StoppedHandler = (data: { + sessionId: string; + skipConsolidation?: boolean; +}) => Promise; + +function mockSdk(opts?: { rejectGraphExtract?: () => boolean }) { + const handlers = new Map(); + const trigger = vi.fn( + async (input: { function_id: string; payload?: unknown }) => { + if ( + input.function_id === "mem::graph-extract" && + opts?.rejectGraphExtract?.() + ) { + throw new Error("dispatch refused"); + } + if (input.function_id === "mem::summarize") { + return { summary: "s", sessionId: SID }; + } + return { ok: true }; + }, + ); + return { + sdk: { + registerFunction: (id: string, h: StoppedHandler) => handlers.set(id, h), + registerTrigger: () => {}, + trigger, + }, + handlers, + trigger, + }; +} + +// Every batch handed to mem::graph-extract, as arrays of observation ids. +function batches(trigger: ReturnType): string[][] { + return trigger.mock.calls + .filter((c) => (c[0] as { function_id: string }).function_id === "mem::graph-extract") + .map((c) => + ( + (c[0] as { payload: { observations: CompressedObservation[] } }).payload + .observations ?? [] + ).map((o) => o.id), + ); +} + +function harness(opts?: { rejectGraphExtract?: () => boolean }) { + const kv = persistentKV(); + const { sdk, handlers, trigger } = mockSdk(opts); + registerEventTriggers(sdk as never, kv as never); + const stopped = handlers.get("event::session::stopped")!; + kv.scope("mem:sessions").set(SID, { + id: SID, + project: "p", + cwd: "/p", + startedAt: "2026-01-01T00:00:00.000Z", + status: "active", + observationCount: 0, + }); + const land = (...os: CompressedObservation[]) => { + for (const o of os) kv.scope(`mem:obs:${SID}`).set(o.id, o); + }; + const drop = (id: string) => kv.scope(`mem:obs:${SID}`).delete(id); + const stop = () => stopped({ sessionId: SID }); + const session = () => + kv.scope("mem:sessions").get(SID) as Record; + return { kv, trigger, stop, land, drop, session }; +} + +describe("event::session::stopped graph-extract is incremental", () => { + beforeEach(() => vi.clearAllMocks()); + + it("hands each turn only the observations captured since the last extract", async () => { + const h = harness(); + + h.land(obs("a", "2026-01-01T00:00:01.000Z"), obs("b", "2026-01-01T00:00:02.000Z")); + await h.stop(); + h.land(obs("c", "2026-01-01T00:00:03.000Z")); + await h.stop(); + h.land(obs("d", "2026-01-01T00:00:04.000Z")); + await h.stop(); + + expect(batches(h.trigger)).toEqual([["a", "b"], ["c"], ["d"]]); + }); + + it("does not dispatch graph-extract at all when no new observations landed", async () => { + const h = harness(); + h.land(obs("a", "2026-01-01T00:00:01.000Z")); + await h.stop(); + await h.stop(); + await h.stop(); + + expect(batches(h.trigger)).toEqual([["a"]]); + }); + + it("stays incremental when kv.list returns the same set in a different order", async () => { + // Listing order is the store's, not ours. The same observation set coming + // back rearranged is not a change and must not force a full re-extract. + const h = harness(); + h.land(obs("a", "2026-01-01T00:00:01.000Z"), obs("b", "2026-01-01T00:00:02.000Z")); + await h.stop(); + + h.drop("a"); + h.land(obs("a", "2026-01-01T00:00:01.000Z")); // same observation, now last + h.land(obs("c", "2026-01-01T00:00:03.000Z")); + await h.stop(); + + expect(batches(h.trigger)[1]).toEqual(["c"]); + }); + + it("extracts without creating a session row when the session record is missing", async () => { + const h = harness(); + h.kv.scope("mem:sessions").delete(SID); + h.land(obs("a", "2026-01-01T00:00:01.000Z")); + await h.stop(); + + expect(batches(h.trigger)).toEqual([["a"]]); + expect(h.kv.scope("mem:sessions").has(SID)).toBe(false); + }); + + it("re-extracts the whole session after a graph reset starts a new generation", async () => { + const h = harness(); + h.land(obs("a", "2026-01-01T00:00:01.000Z")); + await h.stop(); + h.kv.scope(KV.graphControl).set("generation", "11111111-2222-3333-4444-555555555555"); + h.land(obs("b", "2026-01-01T00:00:02.000Z")); + await h.stop(); + + expect(batches(h.trigger)).toEqual([["a"], ["a", "b"]]); + }); + + it("re-extracts the whole session when LLM graph extraction is turned on", async () => { + const h = harness(); + h.land(obs("a", "2026-01-01T00:00:01.000Z")); + await h.stop(); + vi.mocked(isGraphExtractionEnabled).mockReturnValue(true); + try { + await h.stop(); + } finally { + vi.mocked(isGraphExtractionEnabled).mockReturnValue(false); + } + + expect(batches(h.trigger)).toEqual([["a"], ["a"]]); + }); +}); + +// The fallback branch. Most of these assert the PRE-FIX behaviour (extract +// everything) on purpose, so they pass against unmodified source by +// construction — their job is to kill mutations that would make the watermark +// silently skip an observation. +describe("graph-extract watermark never skips an observation", () => { + beforeEach(() => vi.clearAllMocks()); + + it("extracts the whole session on the first stop, when no watermark exists", async () => { + const h = harness(); + h.land( + obs("a", "2026-01-01T00:00:01.000Z"), + obs("b", "2026-01-01T00:00:02.000Z"), + obs("c", "2026-01-01T00:00:03.000Z"), + ); + await h.stop(); + expect(batches(h.trigger)).toEqual([["a", "b", "c"]]); + // A session that has never been extracted is not a stale watermark. + expect(logger.info).not.toHaveBeenCalled(); + }); + + it("re-extracts the whole session when the record predates the digest", async () => { + // The path every deployed session takes exactly once, on the first stop + // after this ships: a session record carrying graphExtractedAt and no + // digest at all. An untrustworthy watermark costs one re-extract; + // trusting it costs every observation at or below it. + const h = harness(); + h.kv.scope("mem:sessions").set(SID, { + id: SID, + project: "p", + cwd: "/p", + startedAt: "2026-01-01T00:00:00.000Z", + status: "active", + observationCount: 0, + graphExtractedAt: "2026-01-01T00:00:02.000Z", + // graphExtractedDigest absent — written by a build that had none + }); + h.land( + obs("a", "2026-01-01T00:00:01.000Z"), + obs("b", "2026-01-01T00:00:03.000Z"), + ); + await h.stop(); + + expect(batches(h.trigger)).toEqual([["a", "b"]]); + }); + + it("re-extracts everything when an observation lands out of order below the watermark", async () => { + // mem::compress is fire-and-forget, so a slow compression writes an older + // timestamp after a newer one was already extracted. Without the count + // tripwire that observation would never reach the graph. + const h = harness(); + h.land(obs("a", "2026-01-01T00:00:01.000Z"), obs("c", "2026-01-01T00:00:03.000Z")); + await h.stop(); + + h.land(obs("b", "2026-01-01T00:00:02.000Z"), obs("d", "2026-01-01T00:00:04.000Z")); + await h.stop(); + + expect(batches(h.trigger)[1]).toEqual(["a", "c", "b", "d"]); + }); + + it("re-extracts everything when two observations share the watermark timestamp", async () => { + const h = harness(); + h.land(obs("a", "2026-01-01T00:00:01.000Z")); + await h.stop(); + h.land(obs("b", "2026-01-01T00:00:01.000Z")); + await h.stop(); + + expect(batches(h.trigger)[1]).toEqual(["a", "b"]); + }); + + it("re-extracts everything when a deletion and a late arrival share a millisecond", async () => { + // evict's per-project cap (evict.ts) is age- and status-independent, so it + // can delete an observation from the session that is still being appended + // to. When a late compression lands in the same window AND carries the + // same timestamp, size and any timestamp-derived checksum both net to + // zero — only the observation ids tell the two sets apart. + const h = harness(); + h.land( + obs("a", "2026-01-01T00:00:01.000Z"), + obs("c", "2026-01-01T00:00:03.000Z"), + obs("e", "2026-01-01T00:00:05.000Z"), + ); + await h.stop(); + + h.drop("c"); // evicted + h.land(obs("b", "2026-01-01T00:00:03.000Z")); // compressed late, same ms + + await h.stop(); + + expect(batches(h.trigger)[1]).toEqual(["a", "e", "b"]); + expect(logger.info).toHaveBeenCalledWith(STALE, { + sessionId: SID, + atOrBelow: 3, + total: 3, + }); + }); + + it("leaves the watermark unset when the extract dispatch fails, so the next stop retries", async () => { + let refuse = true; + const h = harness({ rejectGraphExtract: () => refuse }); + + h.land(obs("a", "2026-01-01T00:00:01.000Z"), obs("b", "2026-01-01T00:00:02.000Z")); + await h.stop(); + expect(h.session().graphExtractedAt).toBeUndefined(); + + refuse = false; + await h.stop(); + + expect(batches(h.trigger)[1]).toEqual(["a", "b"]); + expect(h.session()).toMatchObject({ + graphExtractedDigest: expect.any(String), + }); + }); + it("extracts a row that gets its title below the watermark", async () => { + // A legacy untitled row (hookType, no title) is skipped until + // mem::compression-retry titles it, and the title keeps the capture time. + const h = harness(); + const untitled = { id: "b", sessionId: SID, timestamp: "2026-01-01T00:00:01.000Z", hookType: "post_tool_use" }; + h.land(untitled as unknown as CompressedObservation, obs("a", "2026-01-01T00:00:02.000Z")); + await h.stop(); + h.land(obs("b", "2026-01-01T00:00:01.000Z")); + await h.stop(); + + expect(batches(h.trigger)).toEqual([["a"], ["b", "a"]]); + }); +}); + +// Pins current behaviour, not desired behaviour. The digest is over ids, and +// the timestamp marker sees only timestamps, so neither notices a row whose +// content changed in place. +describe("graph-extract watermark known limitations", () => { + beforeEach(() => vi.clearAllMocks()); + + it("does not re-extract a row upgraded in place by compression (known limitation, shared with the timestamp marker)", async () => { + // observe.ts writes a titled synthetic row with no concepts; mem::compress + // later rewrites it with the same id and timestamp. A stop that ran in + // between already extracted the synthetic version. + const h = harness(); + h.land(obs("b", "2026-01-01T00:00:01.000Z"), obs("a", "2026-01-01T00:00:02.000Z")); + await h.stop(); + h.land({ ...obs("b", "2026-01-01T00:00:01.000Z"), concepts: ["auth"] }); + await h.stop(); + + expect(batches(h.trigger)).toEqual([["b", "a"]]); + }); +}); diff --git a/test/graph-heuristic-extract.test.ts b/test/graph-heuristic-extract.test.ts index f3bfec805b..0d0593858b 100644 --- a/test/graph-heuristic-extract.test.ts +++ b/test/graph-heuristic-extract.test.ts @@ -73,6 +73,47 @@ describe("extractGraphHeuristics", () => { expect(edges.length).toBeLessThanOrEqual(12); }); + // event::session::stopped now sends one batch per turn instead of the whole + // session. persistGraphDelta merges batches by (type, name) and by edge key, + // so splitting a batch must change neither set. Node ids are random, so + // compare by name. + function shape(results: Array>) { + const prov = new Map>(); + const edges = new Set(); + for (const r of results) { + const named = new Map(r.nodes.map((n) => [n.id, `${n.type}:${n.name}`])); + for (const n of r.nodes) { + const key = `${n.type}:${n.name}`; + const ids = prov.get(key) ?? new Set(); + for (const id of n.sourceObservationIds) ids.add(id); + prov.set(key, ids); + } + for (const e of r.edges) { + const pair = [named.get(e.sourceNodeId)!, named.get(e.targetNodeId)!]; + edges.add(pair.sort().join("|")); + } + } + return { + nodes: [...prov] + .map(([key, ids]) => `${key}=${[...ids].sort().join(",")}`) + .sort(), + edges: [...edges].sort(), + }; + } + + it("builds the same graph whether observations arrive together or one batch at a time", () => { + // One shared entity so the merge and provenance union are exercised, and + // disjoint ones on either side so any link drawn ACROSS observations + // (the only way splitting could change the set) shows up as an edge the + // split calls cannot produce. + const o1 = obs("o1", ["src/auth.ts", "src/db.ts"], ["authentication"]); + const o2 = obs("o2", ["src/db.ts", "src/cache.ts"], ["caching"]); + + expect( + shape([extractGraphHeuristics([o1]), extractGraphHeuristics([o2])]), + ).toEqual(shape([extractGraphHeuristics([o1, o2])])); + }); + it("never emits self edges or duplicate pairs", () => { const { edges } = extractGraphHeuristics([ obs("o1", ["a.ts"], ["a"]), @@ -96,7 +137,7 @@ describe("keyless graph extraction wiring", () => { const events = readFileSync("src/triggers/events.ts", "utf-8"); const stopped = events.slice(events.indexOf("event::session::stopped")); const gate = stopped.indexOf("isGraphExtractionEnabled()"); - const fire = stopped.indexOf('fireVoid("mem::graph-extract"'); + const fire = stopped.indexOf('"mem::graph-extract"'); expect(fire).toBeGreaterThan(-1); expect(gate === -1 || gate > fire).toBe(true); });