diff --git a/src/functions/cascade.ts b/src/functions/cascade.ts index fb979e65fc..2678da42d0 100644 --- a/src/functions/cascade.ts +++ b/src/functions/cascade.ts @@ -1,8 +1,15 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV } from "../state/schema.js"; -import type { Memory, GraphNode, GraphEdge } from "../types.js"; +import type { Memory, GraphEdge } from "../types.js"; +import { + GraphIndexReader, + graphIndexReadiness, + removeGraphNodeFromIndexOrInvalidate, + withFailClosedGraphMutation, +} from "../state/graph-indexes.js"; import { recordAudit } from "./audit.js"; +import { rebuildGraphSnapshotOrInvalidateInMutation } from "./graph.js"; export function registerCascadeFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::cascade-update", @@ -23,15 +30,39 @@ export function registerCascadeFunction(sdk: ISdk, kv: StateKV): void { const obsIds = new Set(superseded.sourceObservationIds || []); if (obsIds.size > 0) { - const now = new Date().toISOString(); - const nodes = await kv.list(KV.graphNodes); - for (const node of nodes) { - if (node.stale) continue; - const overlap = (node.sourceObservationIds ?? []).some((id) => obsIds.has(id)); - if (overlap) { + await withFailClosedGraphMutation(kv, "graph cascade update", async () => { + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) return; + const reader = await GraphIndexReader.open(kv, readiness.generation); + if (!reader) return; + const nodes = []; + const edges = new Map(); + for (const nodeId of await reader.getNodeIdsForObservations([ + ...obsIds, + ])) { + const node = await reader.getNode(nodeId); + if (!node) continue; + nodes.push(node); + for (const edge of await reader.getIncidentEdges(node.id)) { + edges.set(edge.id, edge); + } + } + + const now = new Date().toISOString(); + for (const node of nodes) { + if ( + !(node.sourceObservationIds ?? []).some((id) => obsIds.has(id)) + ) { + continue; + } node.stale = true; node.updatedAt = now; await kv.set(KV.graphNodes, node.id, node); + await removeGraphNodeFromIndexOrInvalidate( + kv, + node.id, + readiness.generation, + ); await recordAudit(kv, "consolidate", "mem::cascade-update", [node.id], { resourceType: "GraphNode", change: "marked stale from superseded memory", @@ -39,13 +70,13 @@ export function registerCascadeFunction(sdk: ISdk, kv: StateKV): void { }); flaggedNodes++; } - } - const edges = await kv.list(KV.graphEdges); - for (const edge of edges) { - if (edge.stale) continue; - const overlap = (edge.sourceObservationIds ?? []).some((id) => obsIds.has(id)); - if (overlap) { + for (const edge of edges.values()) { + if ( + !(edge.sourceObservationIds ?? []).some((id) => obsIds.has(id)) + ) { + continue; + } edge.stale = true; await kv.set(KV.graphEdges, edge.id, edge); await recordAudit(kv, "consolidate", "mem::cascade-update", [edge.id], { @@ -55,7 +86,14 @@ export function registerCascadeFunction(sdk: ISdk, kv: StateKV): void { }); flaggedEdges++; } - } + + if (flaggedNodes > 0 || flaggedEdges > 0) { + await rebuildGraphSnapshotOrInvalidateInMutation( + kv, + readiness.generation, + ); + } + }); } const supersededConcepts = new Set( diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 7bdabf6125..106ae9d2d9 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -27,12 +27,22 @@ import type { import { importOrigin } from "../types.js"; import { normalizeAccessLog } from "./access-tracker.js"; import { KV } from "../state/schema.js"; +import { + GraphIndexReader, + indexGraphEdgeOrInvalidate, + indexGraphNodeOrInvalidate, + initializeGraphIndexes, + readIndexedGraph, + resetGraphIndexes, + withFailClosedGraphMutation, +} from "../state/graph-indexes.js"; import { checkPayloadFrameSize } from "../state/frame-guard.js"; import { StateKV } from "../state/kv.js"; import { VERSION } from "../version.js"; import { recordAudit } from "./audit.js"; import { indexRecords } from "./search.js"; import { resetLessonIndex } from "./lessons.js"; +import { rebuildGraphSnapshotOrInvalidateInMutation } from "./graph.js"; import { logger } from "../logger.js"; // Bounded-concurrency chunk size for the import delete/write loops. A @@ -99,9 +109,28 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { if (profile) profiles.push(profile); } + let indexedGraph: { nodes: GraphNode[]; edges: GraphEdge[] } | null = null; + let graphWarning: string | undefined; + try { + const graphReadiness = await initializeGraphIndexes(kv); + if (graphReadiness.ready) { + indexedGraph = await readIndexedGraph(kv); + if (!indexedGraph) { + graphWarning = "Graph data was omitted because its index generation changed during export."; + } + } else { + graphWarning = + "Graph data was omitted because generation-matched read indexes are unavailable."; + } + } catch (error) { + graphWarning = `Graph data was omitted because index readiness could not be read: ${ + error instanceof Error ? error.message : String(error) + }`; + } + const graphNodes = indexedGraph?.nodes ?? []; + const graphEdges = indexedGraph?.edges ?? []; + const [ - graphNodes, - graphEdges, semanticMemories, proceduralMemories, actions, @@ -117,8 +146,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { checkpoints, accessLogs, ] = await Promise.all([ - kv.list(KV.graphNodes).catch(() => []), - kv.list(KV.graphEdges).catch(() => []), kv.list(KV.semantic).catch(() => []), kv.list(KV.procedural).catch(() => []), kv.list(KV.actions).catch(() => []), @@ -161,6 +188,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { signals: signals.length > 0 ? signals : undefined, checkpoints: checkpoints.length > 0 ? checkpoints : undefined, accessLogs: accessLogs.length > 0 ? accessLogs : undefined, + warnings: graphWarning ? [graphWarning] : undefined, }; if (maxSessions !== undefined) { @@ -295,6 +323,10 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { }; } + const hasGraphData = + (Array.isArray(importData.graphNodes) && importData.graphNodes.length > 0) || + (Array.isArray(importData.graphEdges) && importData.graphEdges.length > 0); + const stats = { sessions: 0, observations: 0, @@ -372,14 +404,10 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { await kv.list(KV.insights).catch(() => []), (i) => kv.delete(KV.insights, i.id), ); - await runChunked( - await kv.list<{ id: string }>(KV.graphNodes).catch(() => []), - (n) => kv.delete(KV.graphNodes, n.id), - ); - await runChunked( - await kv.list<{ id: string }>(KV.graphEdges).catch(() => []), - (e) => kv.delete(KV.graphEdges, e.id), - ); + // Graph replacement is generation-based. Whole-scope list/delete can + // exceed iii's invocation frame on large corpora, so rotate to a fresh + // generation and leave old rows as unreachable orphans. + await resetGraphIndexes(kv); await runChunked( await kv.list<{ id: string }>(KV.semantic).catch(() => []), (s) => kv.delete(KV.semantic, s.id), @@ -398,6 +426,18 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { ); } + if (hasGraphData) { + const readiness = await initializeGraphIndexes(kv); + if (!readiness.ready) { + return { + success: false, + error: + "Graph import requires generation-matched read indexes. Run " + + "graph reset before importing graph data into a legacy corpus.", + }; + } + } + // Records actually written this run, accumulated for search // indexing after the KV writes settle. Skipped (already-present) // and merge-overwritten rows are already in the index or will be @@ -472,22 +512,75 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { stats.summaries++; }); - if (importData.graphNodes) { - await runChunked(importData.graphNodes, async (node) => { - if (strategy === "skip") { - const existing = await kv.get(KV.graphNodes, node.id).catch(() => null); - if (existing) { stats.skipped++; return; } + if (hasGraphData) { + await withFailClosedGraphMutation(kv, "graph import", async () => { + const readiness = await initializeGraphIndexes(kv); + if (!readiness.ready || !readiness.generation) { + throw new Error( + "Graph import requires generation-matched read indexes.", + ); } - await kv.set(KV.graphNodes, node.id, node); - }); - } - if (importData.graphEdges) { - await runChunked(importData.graphEdges, async (edge) => { - if (strategy === "skip") { - const existing = await kv.get(KV.graphEdges, edge.id).catch(() => null); - if (existing) { stats.skipped++; return; } + const reader = await GraphIndexReader.open(kv, readiness.generation); + if (!reader) throw new Error("Graph read indexes unavailable"); + const activeNodeIds = new Set( + (await reader.getNameCatalog()).map((entry) => entry.id), + ); + const activeEdgeIds = new Set(); + if (strategy === "skip" && importData.graphEdges?.length) { + const endpoints = new Set(); + for (const edge of importData.graphEdges) { + endpoints.add(edge.sourceNodeId); + endpoints.add(edge.targetNodeId); + const existing = await kv.get( + KV.graphEdges, + edge.id, + ); + if (existing) { + endpoints.add(existing.sourceNodeId); + endpoints.add(existing.targetNodeId); + } + } + for (const nodeId of endpoints) { + for (const edge of await reader.getIncidentEdges(nodeId)) { + activeEdgeIds.add(edge.id); + } + } + } + + if (importData.graphNodes) { + await runChunked(importData.graphNodes, async (node) => { + if (strategy === "skip" && activeNodeIds.has(node.id)) { + stats.skipped++; + return; + } + await kv.set(KV.graphNodes, node.id, node); + await indexGraphNodeOrInvalidate( + kv, + node, + readiness.generation, + ); + activeNodeIds.add(node.id); + }); + } + if (importData.graphEdges) { + await runChunked(importData.graphEdges, async (edge) => { + if (strategy === "skip" && activeEdgeIds.has(edge.id)) { + stats.skipped++; + return; + } + await kv.set(KV.graphEdges, edge.id, edge); + await indexGraphEdgeOrInvalidate( + kv, + edge, + readiness.generation, + ); + activeEdgeIds.add(edge.id); + }); } - await kv.set(KV.graphEdges, edge.id, edge); + await rebuildGraphSnapshotOrInvalidateInMutation( + kv, + readiness.generation, + ); }); } if (importData.semanticMemories) { diff --git a/src/functions/graph-retrieval.ts b/src/functions/graph-retrieval.ts index 10fd51a762..8955b2fc42 100644 --- a/src/functions/graph-retrieval.ts +++ b/src/functions/graph-retrieval.ts @@ -2,8 +2,8 @@ import type { GraphNode, GraphEdge, } from "../types.js"; -import { KV } from "../state/schema.js"; import type { StateKV } from "../state/kv.js"; +import { GraphIndexReader } from "../state/graph-indexes.js"; export interface GraphRetrievalResult { obsId: string; @@ -13,6 +13,10 @@ export interface GraphRetrievalResult { pathLength: number; } +type NeighborProvider = ( + nodeId: string, +) => Promise>; + function buildGraphContext( path: Array<{ node: GraphNode; edge?: GraphEdge }>, ): string { @@ -46,28 +50,51 @@ export class GraphRetrieval { maxDepth = 2, maxResults = 20, ): Promise { - const allNodes = (await this.kv.list(KV.graphNodes)).filter((n) => !n.stale); - const allEdges = (await this.kv.list(KV.graphEdges)).filter((e) => !e.stale); - - const matchingNodes = allNodes.filter((n) => { - const nameLower = n.name.toLowerCase(); - return entityNames.some( - (e) => - nameLower.includes(e.toLowerCase()) || - e.toLowerCase().includes(nameLower), + const reader = await GraphIndexReader.open(this.kv); + if (!reader) return []; + const catalog = await reader.getNameCatalog(); + const lowered = entityNames.map((e) => e.toLowerCase()); + const matchingNodes: GraphNode[] = []; + for (const entry of catalog) { + const nameLower = entry.name.toLowerCase(); + const matched = lowered.some( + (e) => nameLower.includes(e) || e.includes(nameLower), ); - }); + if (!matched) continue; + const node = await reader.getNode(entry.id); + if (node) matchingNodes.push(node); + } + + const results = await this.scoreEntityMatches( + matchingNodes, + (id) => reader.getNeighbors(id), + maxDepth, + maxResults, + ); + return (await reader.isCurrent()) ? results : []; + } + private async scoreEntityMatches( + matchingNodes: GraphNode[], + getNeighbors: NeighborProvider, + maxDepth: number, + maxResults: number, + ): Promise { if (matchingNodes.length === 0) return []; + // Which start node first claims an observation decides its score, + // so iterate catalog matches in a deterministic order. + const orderedMatches = [...matchingNodes].sort((a, b) => + a.id.localeCompare(b.id), + ); + const results: GraphRetrievalResult[] = []; const visitedObs = new Set(); - for (const startNode of matchingNodes) { - const paths = this.dijkstraTraversal( + for (const startNode of orderedMatches) { + const paths = await this.dijkstraTraversal( startNode, - allNodes, - allEdges, + getNeighbors, maxDepth, ); @@ -119,18 +146,46 @@ export class GraphRetrieval { maxDepth = 1, maxResults = 10, ): Promise { - const allNodes = (await this.kv.list(KV.graphNodes)).filter((n) => !n.stale); - const allEdges = (await this.kv.list(KV.graphEdges)).filter((e) => !e.stale); + const reader = await GraphIndexReader.open(this.kv); + if (!reader) return []; + const candidateIds = await reader.getNodeIdsForObservations(obsIds); + const linkedNodes: GraphNode[] = []; + for (const nodeId of candidateIds) { + const node = await reader.getNode(nodeId); + if ( + node && + (node.sourceObservationIds ?? []).some((id) => obsIds.includes(id)) + ) { + linkedNodes.push(node); + } + } - const linkedNodes = allNodes.filter((n) => - n.sourceObservationIds.some((id) => obsIds.includes(id)), + const results = await this.scoreExpansion( + linkedNodes, + (id) => reader.getNeighbors(id), + obsIds, + maxDepth, + maxResults, + ); + return (await reader.isCurrent()) ? results : []; + } + + private async scoreExpansion( + linkedNodes: GraphNode[], + getNeighbors: NeighborProvider, + obsIds: string[], + maxDepth: number, + maxResults: number, + ): Promise { + const orderedLinked = [...linkedNodes].sort((a, b) => + a.id.localeCompare(b.id), ); const results: GraphRetrievalResult[] = []; const visitedObs = new Set(obsIds); - for (const node of linkedNodes) { - const paths = this.dijkstraTraversal(node, allNodes, allEdges, maxDepth); + for (const node of orderedLinked) { + const paths = await this.dijkstraTraversal(node, getNeighbors, maxDepth); for (const path of paths) { const lastNode = path[path.length - 1].node; for (const obsId of lastNode.sourceObservationIds) { @@ -163,18 +218,38 @@ export class GraphRetrieval { currentState: GraphEdge[]; history: GraphEdge[]; }> { - const allNodes = (await this.kv.list(KV.graphNodes)).filter((n) => !n.stale); - const allEdges = (await this.kv.list(KV.graphEdges)).filter((e) => !e.stale); - - const entity = allNodes.find( - (n) => n.name.toLowerCase() === entityName.toLowerCase(), - ); + const reader = await GraphIndexReader.open(this.kv); + if (!reader) return { entity: null, currentState: [], history: [] }; + const catalog = await reader.getNameCatalog(); + const lower = entityName.toLowerCase(); + let entity: GraphNode | null = null; + for (const entry of catalog) { + if (entry.name.toLowerCase() !== lower) continue; + const node = await reader.getNode(entry.id); + if (node) { + entity = node; + break; + } + } if (!entity) return { entity: null, currentState: [], history: [] }; - const relatedEdges = allEdges.filter( - (e) => e.sourceNodeId === entity.id || e.targetNodeId === entity.id, - ); + const relatedEdges = await reader.getIncidentEdges(entity.id); + + if (!(await reader.isCurrent())) { + return { entity: null, currentState: [], history: [] }; + } + return this.partitionTemporalEdges(entity, relatedEdges, asOf); + } + private partitionTemporalEdges( + entity: GraphNode, + relatedEdges: GraphEdge[], + asOf?: string, + ): { + entity: GraphNode | null; + currentState: GraphEdge[]; + history: GraphEdge[]; + } { if (!asOf) { const latestEdges = this.getLatestEdges(relatedEdges); const historicalEdges = relatedEdges.filter( @@ -231,32 +306,14 @@ export class GraphRetrieval { // which fell back to edge-count order and ignored the 0.1-1.0 weight // attached to every graph edge. Dijkstra over `cost = 1/weight` // (cheaper edges = stronger relationships) returns the - // highest-weighted path to each reachable node within maxDepth. Also - // tightens the perf profile: - // - Adjacency built once in O(V+E) (previous BFS re-filtered - // allEdges per visited node, O(V·E) overall). - // - Min-heap dequeue is O(log V) per pop (previous queue.shift() - // was O(n) — the dominant cost on graphs above ~200 nodes per - // the contributor's benchmark in #328). - private dijkstraTraversal( + // highest-weighted path to each reachable node within maxDepth. + // Neighbor expansion is delegated to targeted adjacency reads bounded by + // degree x maxDepth. + private async dijkstraTraversal( startNode: GraphNode, - allNodes: GraphNode[], - allEdges: GraphEdge[], + getNeighbors: NeighborProvider, maxDepth: number, - ): Array> { - const nodeIndex = new Map(); - for (const n of allNodes) nodeIndex.set(n.id, n); - - const adjacency = new Map>(); - for (const edge of allEdges) { - const a = edge.sourceNodeId; - const b = edge.targetNodeId; - if (!adjacency.has(a)) adjacency.set(a, []); - if (!adjacency.has(b)) adjacency.set(b, []); - adjacency.get(a)!.push({ neighborId: b, edge }); - adjacency.get(b)!.push({ neighborId: a, edge }); - } - + ): Promise>> { const dist = new Map(); const pathTo = new Map>(); dist.set(startNode.id, 0); @@ -273,10 +330,9 @@ export class GraphRetrieval { if (cost > (dist.get(nodeId) ?? Infinity)) continue; if (depth >= maxDepth) continue; - const neighbors = adjacency.get(nodeId) ?? []; - for (const { neighborId, edge } of neighbors) { - const nextNode = nodeIndex.get(neighborId); - if (!nextNode) continue; + const neighbors = await getNeighbors(nodeId); + for (const { node: nextNode, edge } of neighbors) { + const neighborId = nextNode.id; // Clamp weight to avoid division-by-zero on malformed edges; // 0.01 is below the documented 0.1 floor. const edgeCost = 1 / Math.max(edge.weight, 0.01); diff --git a/src/functions/graph.ts b/src/functions/graph.ts index 76340d60fc..c1d50e3632 100644 --- a/src/functions/graph.ts +++ b/src/functions/graph.ts @@ -9,6 +9,18 @@ import type { } from "../types.js"; import { KV, generateId } from "../state/schema.js"; import type { StateKV } from "../state/kv.js"; +import { + GraphIndexReader, + graphIndexReadiness, + initializeGraphIndexes, + indexGraphEdgeOrInvalidate, + indexGraphNodeOrInvalidate, + markGraphIndexesUnavailable, + readIndexedGraph, + resetGraphIndexes, + withFailClosedGraphMutation, + withGraphIndexMutation, +} from "../state/graph-indexes.js"; import { GRAPH_EXTRACTION_SYSTEM, buildGraphExtractionPrompt, @@ -34,49 +46,6 @@ const MAX_GRAPH_QUERY_LIMIT = 5000; const SNAPSHOT_TOP_NODES = DEFAULT_GRAPH_QUERY_LIMIT; const SNAPSHOT_KEY = "current"; -// `state::list` over a 75K-node scope can exceed the iii invocation -// timeout. The query handler races the enumeration against this budget -// and falls back to the snapshot (or a warning envelope) when the live -// path is too slow. 6000ms leaves headroom under the default 8s engine -// invocation deadline. -const LIVE_ENUMERATION_BUDGET_MS = 6000; - -function withTimeout(p: Promise, ms: number, label: string): Promise { - return new Promise((resolve, reject) => { - const t = setTimeout( - () => reject(new Error(`${label}: exceeded ${ms}ms budget`)), - ms, - ); - p.then( - (v) => { - clearTimeout(t); - resolve(v); - }, - (err) => { - clearTimeout(t); - reject(err); - }, - ); - }); -} - -function emptySnapshot(): GraphSnapshot { - return { - version: 1, - topNodes: [], - topEdges: [], - topDegrees: {}, - stats: { - totalNodes: 0, - totalEdges: 0, - nodesByType: {}, - edgesByType: {}, - }, - updatedAt: new Date(0).toISOString(), - dirty: true, - }; -} - async function readSnapshot(kv: StateKV): Promise { try { const snap = await kv.get(KV.graphSnapshot, SNAPSHOT_KEY); @@ -95,6 +64,8 @@ async function readSnapshot(kv: StateKV): Promise { function buildSnapshotFromArrays( nodes: GraphNode[], edges: GraphEdge[], + indexGeneration: string, + resetAt?: string, ): GraphSnapshot { const liveNodes = nodes.filter((n) => !n.stale); const liveEdges = edges.filter((e) => !e.stale); @@ -138,6 +109,8 @@ function buildSnapshotFromArrays( }, updatedAt: new Date().toISOString(), dirty: false, + indexGeneration, + ...(resetAt ? { resetAt } : {}), }; } @@ -171,16 +144,186 @@ function paginateFromSnapshot( }; } -// #814 v2: the rebuild path won't terminate on corpora large enough -// that kv.list returns a payload too big to JSON.parse without -// starving the iii heartbeat. We don't actually know the corpus size -// without enumerating, but we can refuse to start a rebuild if the -// snapshot's recorded `totalNodes` already exceeds this threshold — -// the rebuild path is unreliable above it, and an incremental -// extract-driven snapshot is the right approach for those corpora. -// Operators above the threshold should use mem::graph-reset and let -// future extracts rebuild incrementally. -const REBUILD_SAFE_NODE_CEILING = 25000; +// Bounds the index-served BFS in mem::graph-query so a dense corpus +// can't expand into an unbounded number of targeted gets. Hitting the +// cap returns a truncated page with an explanatory warning. +const TRAVERSAL_VISIT_CAP = 5000; +const GRAPH_QUERY_EDGE_CAP = 5000; + +async function queryViaIndexes( + reader: GraphIndexReader, + snapshot: GraphSnapshot | null, + query: string, + limit: number, + offset: number, +): Promise { + const lower = query.toLowerCase(); + const catalog = await reader.getNameCatalog(); + const candidateIds: string[] = []; + const seenIds = new Set(); + for (const entry of catalog) { + if (!entry.name.toLowerCase().includes(lower)) continue; + seenIds.add(entry.id); + candidateIds.push(entry.id); + } + + for (const node of snapshot?.topNodes ?? []) { + if (node.stale || seenIds.has(node.id)) continue; + const propertyMatch = Object.values(node.properties).some( + (value) => + typeof value === "string" && value.toLowerCase().includes(lower), + ); + if (propertyMatch) { + seenIds.add(node.id); + candidateIds.push(node.id); + } + } + + const pageIds = candidateIds.slice(offset, offset + limit); + const nodes: GraphNode[] = []; + for (const nodeId of pageIds) { + const node = await reader.getNode(nodeId); + if (node) nodes.push(node); + } + + const nodeIds = new Set(nodes.map((node) => node.id)); + const edgeIds = new Set(); + const edges: GraphEdge[] = []; + let edgeCapped = false; + for (const node of nodes) { + const remaining = GRAPH_QUERY_EDGE_CAP - edgeIds.size; + if (remaining <= 0) { + edgeCapped = true; + break; + } + const incident = await reader.getIncidentEdges(node.id, remaining); + if (incident.length === remaining) edgeCapped = true; + for (const edge of incident) { + if (edgeIds.has(edge.id)) continue; + edgeIds.add(edge.id); + if ( + nodeIds.has(edge.sourceNodeId) && + nodeIds.has(edge.targetNodeId) + ) { + edges.push(edge); + } + } + } + + const warnings: string[] = []; + if (!snapshot || snapshot.stats.totalNodes > snapshot.topNodes.length) { + warnings.push( + "Property-value matches are limited to the top-degree snapshot; " + + "all nodes are still matched by name.", + ); + } + if (edgeCapped) { + warnings.push( + `Incident-edge reads were capped at ${GRAPH_QUERY_EDGE_CAP} records.`, + ); + } + if (nodes.length < pageIds.length) { + warnings.push( + "One or more catalog candidates were stale or missing; totals are " + + "candidate-count estimates.", + ); + } + if ( + offset > 0 || + pageIds.length < candidateIds.length || + nodes.length < pageIds.length || + edgeCapped + ) { + warnings.push( + "totalEdges is bounded to edges whose endpoints are both in the " + + "returned page.", + ); + } + return { + nodes, + edges, + depth: 0, + totalNodes: candidateIds.length, + totalEdges: edges.length, + truncated: candidateIds.length > offset + nodes.length || edgeCapped, + limit, + offset, + ...(warnings.length ? { warning: warnings.join(" ") } : {}), + }; +} + +async function traverseViaIndexes( + reader: GraphIndexReader, + startNodeId: string, + nodeType: string | undefined, + maxDepth: number, + limit: number, + offset: number, +): Promise { + const visited = new Set(); + const visitedEdges = new Set(); + const resultNodes: GraphNode[] = []; + const resultEdges: GraphEdge[] = []; + const queue: Array<{ nodeId: string; depth: number }> = [ + { nodeId: startNodeId, depth: 0 }, + ]; + const enqueued = new Set([startNodeId]); + let capped = false; + + traversal: + while (queue.length > 0) { + const { nodeId, depth } = queue.shift()!; + if (visited.has(nodeId) || depth > maxDepth) continue; + if (visited.size >= TRAVERSAL_VISIT_CAP) { + capped = true; + break; + } + visited.add(nodeId); + + const node = await reader.getNode(nodeId); + if (node && (!nodeType || node.type === nodeType)) { + resultNodes.push(node); + } + + const remainingEdges = GRAPH_QUERY_EDGE_CAP - visitedEdges.size; + if (remainingEdges <= 0) { + capped = true; + break; + } + const incident = await reader.getIncidentEdges(nodeId, remainingEdges); + if (incident.length === remainingEdges) capped = true; + for (const edge of incident) { + if (!visitedEdges.has(edge.id)) { + visitedEdges.add(edge.id); + resultEdges.push(edge); + } + const nextId = + edge.sourceNodeId === nodeId ? edge.targetNodeId : edge.sourceNodeId; + if (!enqueued.has(nextId)) { + if (enqueued.size >= TRAVERSAL_VISIT_CAP) { + capped = true; + break traversal; + } + enqueued.add(nextId); + queue.push({ nodeId: nextId, depth: depth + 1 }); + } + } + if (capped && visitedEdges.size >= GRAPH_QUERY_EDGE_CAP) break; + } + + const result = paginate(resultNodes, resultEdges, maxDepth, limit, offset); + if (capped) { + return { + ...result, + truncated: true, + warning: + `Traversal stopped at the ${TRAVERSAL_VISIT_CAP}-node or ` + + `${GRAPH_QUERY_EDGE_CAP}-edge safety cap. Lower maxDepth or start ` + + `from a lower-degree node for a complete walk.`, + }; + } + return result; +} function nameIndexKey(type: string, name: string): string { return `${type}|${name}`; @@ -470,7 +613,7 @@ export function extractGraphHeuristics( ): GraphNode | null => { const trimmed = name.trim(); if (!trimmed) return null; - const key = `${type}${trimmed.toLowerCase()}`; + const key = `${type}\0${trimmed.toLowerCase()}`; let node = nodeByKey.get(key); if (!node) { node = { @@ -548,13 +691,30 @@ export function extractGraphHeuristics( // `kv.list(KV.graphNodes)`. At 75K nodes the list payload // exceeds the iii heartbeat budget and the worker dies before merge can // complete. Each name-index entry is a single small kv.get/set pair. -export async function persistGraphDelta( +async function persistGraphDeltaUnlocked( kv: StateKV, nodes: GraphNode[], edges: GraphEdge[], obsIds: string[], ): Promise<{ newNodeCount: number; newEdgeCount: number }> { - const snap = (await readSnapshot(kv)) ?? emptySnapshot(); + const readiness = await initializeGraphIndexes(kv); + if (!readiness.ready || !readiness.generation) { + throw new Error( + readiness.reason ?? + "Graph writes require generation-matched read indexes. Run graph reset before extracting or importing new graph data.", + ); + } + const snap = await readSnapshot(kv); + if (!snap || snap.indexGeneration !== readiness.generation) { + throw new Error( + "Graph writes require a snapshot matched to the active index generation.", + ); + } + const reader = await GraphIndexReader.open(kv, readiness.generation); + if (!reader) throw new Error("Graph read indexes became unavailable."); + const indexedNodeIds = new Set( + (await reader.getNameCatalog()).map((entry) => entry.id), + ); const capturedAt = new Date().toISOString(); let newNodeCount = 0; let newEdgeCount = 0; @@ -567,6 +727,7 @@ export async function persistGraphDelta( // endpoints to the persisted ids so edges never dangle and re-runs hit the // same edge-index key instead of duplicating. const idRemap = new Map(); + const activeEdgeIds = new Set(); for (const node of nodes) { const indexKey = nameIndexKey(node.type, node.name); @@ -582,18 +743,21 @@ export async function persistGraphDelta( // 0 forever after a reset). if ( existing && - snap.resetAt && - typeof existing.createdAt === "string" && - existing.createdAt < snap.resetAt + (existing.type !== node.type || existing.name !== node.name) ) { existing = null; } + if (existing && !indexedNodeIds.has(existing.id)) { + existing = null; + } } if (existing) { idRemap.set(node.id, existing.id); const merged = mergeNode(existing, node, obsIds, capturedAt); await kv.set(KV.graphNodes, existing.id, merged); + await indexGraphNodeOrInvalidate(kv, merged, readiness.generation); + indexedNodeIds.add(existing.id); // Update topNodes entry if present so a stale clone isn't // returned from the snapshot fast path. const topIdx = snap.topNodes.findIndex((n) => n.id === existing!.id); @@ -605,6 +769,8 @@ export async function persistGraphDelta( await kv.set(KV.graphNodes, node.id, node); await kv.set(KV.graphNameIndex, indexKey, node.id); await kv.set(KV.graphNodeDegree, node.id, 0); + await indexGraphNodeOrInvalidate(kv, node, readiness.generation); + indexedNodeIds.add(node.id); snap.stats.totalNodes += 1; snap.stats.nodesByType[node.type] = (snap.stats.nodesByType[node.type] ?? 0) + 1; @@ -633,17 +799,27 @@ export async function persistGraphDelta( // Same #825 orphan check as the node path above. if ( existing && - snap.resetAt && - typeof existing.createdAt === "string" && - existing.createdAt < snap.resetAt + (existing.sourceNodeId !== edge.sourceNodeId || + existing.targetNodeId !== edge.targetNodeId || + existing.type !== edge.type) ) { existing = null; } + if (existing && !activeEdgeIds.has(existing.id)) { + const indexedEdges = await reader.getIncidentEdges( + existing.sourceNodeId, + ); + if (!indexedEdges.some((candidate) => candidate.id === existing!.id)) { + existing = null; + } + } } if (existing) { const merged = mergeEdge(existing, obsIds); await kv.set(KV.graphEdges, existing.id, merged); + await indexGraphEdgeOrInvalidate(kv, merged, readiness.generation); + activeEdgeIds.add(existing.id); // Replace cached topEdges entry too if present. const topIdx = snap.topEdges.findIndex((e) => e.id === existing!.id); if (topIdx !== -1) { @@ -653,6 +829,8 @@ export async function persistGraphDelta( } else { await kv.set(KV.graphEdges, edge.id, edge); await kv.set(KV.graphEdgeKey, eKey, edge.id); + await indexGraphEdgeOrInvalidate(kv, edge, readiness.generation); + activeEdgeIds.add(edge.id); snap.stats.totalEdges += 1; snap.stats.edgesByType[edge.type] = (snap.stats.edgesByType[edge.type] ?? 0) + 1; @@ -671,6 +849,10 @@ export async function persistGraphDelta( } if (newNodeCount > 0 || newEdgeCount > 0 || snapMutated) { + const current = await graphIndexReadiness(kv); + if (!current.ready || current.generation !== readiness.generation) { + throw new Error("Graph index generation changed during persistence."); + } snap.updatedAt = capturedAt; snap.dirty = false; await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, snap); @@ -679,6 +861,120 @@ export async function persistGraphDelta( return { newNodeCount, newEdgeCount }; } +export async function persistGraphDelta( + kv: StateKV, + nodes: GraphNode[], + edges: GraphEdge[], + obsIds: string[], +): Promise<{ newNodeCount: number; newEdgeCount: number }> { + return withFailClosedGraphMutation(kv, "graph persistence", () => + persistGraphDeltaUnlocked(kv, nodes, edges, obsIds), + ); +} + +async function rebuildGraphSnapshotFromIndexesInMutation( + kv: StateKV, + expectedGeneration: string, +): Promise { + const readiness = await graphIndexReadiness(kv); + if ( + !readiness.ready || + !readiness.generation || + readiness.generation !== expectedGeneration + ) { + throw new Error( + "Graph snapshot rebuild requires generation-matched read indexes.", + ); + } + const indexed = await readIndexedGraph(kv); + if (!indexed) { + throw new Error("Graph read indexes became unavailable during rebuild."); + } + const current = await graphIndexReadiness(kv); + if (!current.ready || current.generation !== expectedGeneration) { + throw new Error("Graph index generation changed during snapshot rebuild."); + } + + const degrees = new Map(indexed.nodes.map((node) => [node.id, 0])); + const latestEdges = new Map(); + for (const edge of indexed.edges) { + degrees.set(edge.sourceNodeId, (degrees.get(edge.sourceNodeId) ?? 0) + 1); + degrees.set(edge.targetNodeId, (degrees.get(edge.targetNodeId) ?? 0) + 1); + const key = edgeIndexKey(edge.sourceNodeId, edge.targetNodeId, edge.type); + const previous = latestEdges.get(key); + const edgeTime = new Date(edge.tcommit ?? edge.createdAt).getTime(); + const previousTime = previous + ? new Date(previous.tcommit ?? previous.createdAt).getTime() + : -Infinity; + const edgeIsLatest = edge.isLatest !== false; + const previousIsLatest = previous?.isLatest !== false; + if ( + !previous || + (edgeIsLatest && !previousIsLatest) || + (edgeIsLatest === previousIsLatest && edgeTime > previousTime) + ) { + latestEdges.set(key, edge); + } + } + for (const node of indexed.nodes) { + await kv.set(KV.graphNameIndex, nameIndexKey(node.type, node.name), node.id); + await kv.set(KV.graphNodeDegree, node.id, degrees.get(node.id) ?? 0); + } + for (const [key, edge] of latestEdges) { + await kv.set(KV.graphEdgeKey, key, edge.id); + } + + const snapshot = buildSnapshotFromArrays( + indexed.nodes, + indexed.edges, + expectedGeneration, + readiness.resetAt, + ); + const beforeWrite = await graphIndexReadiness(kv); + if (!beforeWrite.ready || beforeWrite.generation !== expectedGeneration) { + throw new Error("Graph index generation changed during snapshot rebuild."); + } + await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, snapshot); + return snapshot; +} + +export async function rebuildGraphSnapshotOrInvalidateInMutation( + kv: StateKV, + expectedGeneration: string, +): Promise { + try { + return await rebuildGraphSnapshotFromIndexesInMutation( + kv, + expectedGeneration, + ); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + await markGraphIndexesUnavailable( + kv, + `graph snapshot rebuild failed after a graph mutation: ${message}`, + expectedGeneration, + ).catch(() => {}); + throw error; + } +} + +export async function rebuildGraphSnapshotFromIndexes( + kv: StateKV, +): Promise { + return withGraphIndexMutation(async () => { + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) { + throw new Error( + "Graph snapshot rebuild requires generation-matched read indexes.", + ); + } + return rebuildGraphSnapshotOrInvalidateInMutation( + kv, + readiness.generation, + ); + }); +} + export function registerGraphFunction( sdk: ISdk, kv: StateKV, @@ -744,7 +1040,6 @@ export function registerGraphFunction( edges, obsIds, ); - await recordAudit(kv, "observe", "mem::graph-extract", obsIds, { nodesExtracted: nodes.length, edgesExtracted: edges.length, @@ -787,69 +1082,33 @@ export function registerGraphFunction( }): Promise => { const maxDepth = Math.min(data.maxDepth || 3, 5); const { limit, offset } = resolvePagination(data.limit, data.offset); + const readiness = await graphIndexReadiness(kv); + const snapshot = await readSnapshot(kv); + const viewReadiness = await graphIndexReadiness(kv); - // #814 v2: the empty-body / nodeType-only path NEVER enumerates. - // It reads the snapshot exclusively. The snapshot is updated - // inline by graph-extract, so for newly-built corpora it's - // always current. For legacy corpora missing a snapshot the - // operator must run mem::graph-snapshot-rebuild (safe under - // REBUILD_SAFE_NODE_CEILING) or mem::graph-reset to wipe and - // rebuild incrementally from new observations. + // The empty-body / nodeType-only path reads the snapshot only. + // Legacy snapshots can still be returned, but are explicitly + // marked unavailable until a reset starts a new indexed generation. const noWalk = !data.query && !data.startNodeId; if (noWalk) { - const snap = await readSnapshot(kv); - if (snap && snap.stats.totalNodes > 0) { - return paginateFromSnapshot(snap, data.nodeType, limit, offset); - } - return { - nodes: [], - edges: [], - depth: 0, - totalNodes: 0, - totalEdges: 0, - truncated: false, - limit, - offset, - warning: - "No graph snapshot available. Either no graph has been " + - "extracted yet, or you are on a legacy corpus from a pre-#814 " + - "agentmemory build. Run POST /agentmemory/graph/snapshot-rebuild " + - "(safe up to ~25K nodes) or POST /agentmemory/graph/reset to " + - "wipe and let future extracts repopulate.", - }; - } - - // Query / startNodeId paths still need broader access. Race the - // live enumeration against a wall-clock budget so a long - // kv.list doesn't block the worker indefinitely. On timeout the - // caller gets a snapshot-backed approximation instead of a 500. - let allNodes: GraphNode[]; - let allEdges: GraphEdge[]; - try { - const [rawNodes, rawEdges] = await withTimeout( - Promise.all([ - kv.list(KV.graphNodes), - kv.list(KV.graphEdges), - ]), - LIVE_ENUMERATION_BUDGET_MS, - "graph-query enumeration", - ); - allNodes = rawNodes.filter((n) => !n.stale); - allEdges = rawEdges.filter((e) => !e.stale); - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logger.warn("Graph query enumeration timed out, using snapshot", { - error: msg, - }); - const snap = await readSnapshot(kv); - if (snap) { + if (snapshot) { + const snapshotReady = + readiness.ready && + viewReadiness.ready && + readiness.generation === viewReadiness.generation && + snapshot.indexGeneration === viewReadiness.generation; return { - ...paginateFromSnapshot(snap, data.nodeType, limit, offset), - warning: - "Live graph enumeration exceeded budget. Query / " + - "startNodeId paths degrade on >25K-node corpora until a " + - "per-node edge index lands. Result reflects top-degree " + - "snapshot, not the requested walk.", + ...paginateFromSnapshot(snapshot, data.nodeType, limit, offset), + indexStatus: snapshotReady ? "ready" : "unavailable", + ...(!snapshotReady + ? { + warning: + "Graph read indexes are unavailable for this legacy corpus. " + + "The response is limited to the stored snapshot. Run graph reset " + + "to start a new indexed generation; complete legacy recovery " + + "requires paginated state scanning.", + } + : {}), }; } return { @@ -861,84 +1120,106 @@ export function registerGraphFunction( truncated: false, limit, offset, + indexStatus: "unavailable", warning: - "Graph enumeration exceeded budget and no snapshot is available.", + "No graph snapshot or generation-matched read index is available. " + + "Run graph reset to start a new indexed generation; complete legacy " + + "recovery requires paginated state scanning.", }; } - if (data.query) { - const lower = data.query.toLowerCase(); - const matchingNodes = allNodes.filter( - (n) => - n.name.toLowerCase().includes(lower) || - Object.values(n.properties).some( - (v) => typeof v === "string" && v.toLowerCase().includes(lower), - ), - ); - return paginate(matchingNodes, allEdges, 0, limit, offset); - } - - if (data.startNodeId) { - const visited = new Set(); - const visitedEdges = new Set(); - const resultNodes: GraphNode[] = []; - const resultEdges: GraphEdge[] = []; - const queue: Array<{ nodeId: string; depth: number }> = [ - { nodeId: data.startNodeId, depth: 0 }, - ]; - - while (queue.length > 0) { - const { nodeId, depth } = queue.shift()!; - if (visited.has(nodeId) || depth > maxDepth) continue; - visited.add(nodeId); - - const node = allNodes.find((n) => n.id === nodeId); - if (node) { - if (!data.nodeType || node.type === data.nodeType) { - resultNodes.push(node); - } - } - - const neighborEdges = allEdges.filter( - (e) => e.sourceNodeId === nodeId || e.targetNodeId === nodeId, - ); - for (const edge of neighborEdges) { - if (!visitedEdges.has(edge.id)) { - visitedEdges.add(edge.id); - resultEdges.push(edge); - } - const nextId = - edge.sourceNodeId === nodeId - ? edge.targetNodeId - : edge.sourceNodeId; - if (!visited.has(nextId)) { - queue.push({ nodeId: nextId, depth: depth + 1 }); - } - } + const expectedGeneration = + readiness.ready && + viewReadiness.ready && + readiness.generation === viewReadiness.generation + ? readiness.generation + : undefined; + const reader = expectedGeneration + ? await GraphIndexReader.open(kv, expectedGeneration) + : null; + if (reader) { + const matchedSnapshot = + snapshot?.indexGeneration === expectedGeneration + ? snapshot + : null; + const result = data.query + ? await queryViaIndexes( + reader, + matchedSnapshot, + data.query, + limit, + offset, + ) + : await traverseViaIndexes( + reader, + data.startNodeId!, + data.nodeType, + maxDepth, + limit, + offset, + ); + if (await reader.isCurrent()) { + return { ...result, indexStatus: "ready" }; } - - return paginate(resultNodes, resultEdges, maxDepth, limit, offset); } - // Unreachable — noWalk branch handles the rest. - return paginate([], [], 0, limit, offset); + const fallbackReadiness = await graphIndexReadiness(kv).catch(() => null); + const stableSnapshot = + snapshot && + expectedGeneration && + fallbackReadiness?.ready && + fallbackReadiness.generation === expectedGeneration && + snapshot.indexGeneration === expectedGeneration + ? snapshot + : null; + return { + ...(stableSnapshot + ? paginateFromSnapshot(stableSnapshot, data.nodeType, limit, offset) + : { + nodes: [], + edges: [], + depth: 0, + totalNodes: 0, + totalEdges: 0, + truncated: false, + limit, + offset, + }), + indexStatus: "unavailable", + warning: + "Graph read indexes are unavailable or changed during the requested " + + "search or traversal. Any snapshot response is generation-matched. " + + "Run graph reset " + + "to start a new indexed generation; complete legacy recovery requires " + + "paginated state scanning.", + }; }, ); - // #814 v2: graph-stats reads the snapshot exclusively. The snapshot - // is maintained inline by mem::graph-extract, so for any corpus built - // on a post-#814 agentmemory the stats are always current without an - // enumeration. Legacy corpora without a snapshot get an empty - // envelope + a warning pointing at the snapshot-rebuild or graph-reset - // endpoints — never a 500. + // graph-stats reads the snapshot exclusively and never enumerates graph + // scopes. Missing legacy snapshots remain unavailable until graph reset. sdk.registerFunction("mem::graph-stats", async () => { + const readiness = await graphIndexReadiness(kv); const snap = await readSnapshot(kv); + const current = await graphIndexReadiness(kv); if (snap) { + const trusted = + readiness.ready && + current.ready && + readiness.generation === current.generation && + snap.indexGeneration === current.generation; return { ...snap.stats, fromSnapshot: true, + indexStatus: trusted ? "ready" : "unavailable", updatedAt: snap.updatedAt, - ...(snap.dirty + ...(!trusted + ? { + warning: + "Graph snapshot counts are not matched to a ready index " + + "generation and may be incomplete.", + } + : snap.dirty ? { warning: "Snapshot is marked dirty (write was in-flight when read). " + @@ -953,188 +1234,59 @@ export function registerGraphFunction( nodesByType: {}, edgesByType: {}, fromSnapshot: false, + indexStatus: "unavailable", warning: - "No graph snapshot available. Run POST /agentmemory/graph/snapshot-rebuild " + - "(safe up to ~25K nodes) or POST /agentmemory/graph/reset to wipe " + - "and let future extracts repopulate.", + "No graph snapshot available. Run POST /agentmemory/graph/reset to " + + "start a new indexed generation. Legacy recovery requires paginated " + + "state scanning.", }; }); - // #814 v2: explicit rebuild backfills the snapshot AND the name / - // edge-key / degree indexes from existing graphNodes/graphEdges - // scopes. This is the path operators run once after upgrading to a - // post-#814 build to bring legacy corpora online. It enumerates via - // kv.list — the same pair that breaks at 75K+ — so we refuse to - // run on corpora large enough that the response payload would - // block the worker heartbeat. Above the ceiling the only safe path - // is mem::graph-reset followed by incremental re-extraction. sdk.registerFunction( "mem::graph-snapshot-rebuild", - async (data?: { force?: boolean }) => { + async () => { const started = Date.now(); - // #825: pre-flight refusal for legacy corpora. The old guard - // checked node count AFTER kv.list, but the heartbeat dies at - // ~0.35s on a 75K-node response — long before the wall-clock - // budget can fire. We can't safely enumerate to discover size. - // - // Heuristic: if no snapshot exists, the corpus is either empty - // or legacy. The empty case has nothing to rebuild; the legacy - // case will crash. Refuse both unless `force: true` is passed - // (operator opt-in to attempt rebuild on a corpus they know is - // small enough — typically under 10K nodes on the default iii - // state adapter). - // Strict boolean check on force — accept only literal `true`, - // never truthy strings/numbers, so a hand-crafted JSON payload - // can't accidentally bypass the legacy-corpus safeguard. - const forceRebuild = data?.force === true; try { - const existing = await readSnapshot(kv); - if (!existing && !forceRebuild) { - logger.warn("Graph snapshot rebuild refused: no prior snapshot", { - hint: "legacy corpus or empty store", - }); + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) { return { success: false, - legacyCorpus: true, + indexUnavailable: true, + status: readiness.status, error: - "No prior snapshot found. Rebuild would call kv.list on " + - "KV.graphNodes/Edges, which heartbeat-crashes the worker " + - "on corpora past the iii state response budget (~25K nodes). " + - "Either (a) call POST /agentmemory/graph/reset to drop into " + - "incremental-only mode and rebuild from new extracts, or " + - "(b) re-send with `force: true` if you're certain the " + - "corpus is small.", + "Graph snapshot rebuild requires generation-matched read indexes. " + + "Legacy graph scopes cannot be recovered safely until iii exposes " + + "paginated state scanning. Run graph reset to start a new generation.", }; } - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logger.warn("Graph snapshot pre-flight read failed", { error: msg }); - // Fall through; the user passed force=true or the snapshot - // read itself failed (separate problem). - } - - try { - const [nodes, edges] = await withTimeout( - Promise.all([ - kv.list(KV.graphNodes), - kv.list(KV.graphEdges), - ]), - LIVE_ENUMERATION_BUDGET_MS, - "graph-snapshot-rebuild enumeration", - ); - - if (nodes.length > REBUILD_SAFE_NODE_CEILING) { - logger.warn("Graph snapshot rebuild aborted: corpus too large", { - totalNodes: nodes.length, - ceiling: REBUILD_SAFE_NODE_CEILING, + const snap = await rebuildGraphSnapshotFromIndexes(kv); + const tookMs = Date.now() - started; + logger.info("Graph snapshot rebuilt", { + totalNodes: snap.stats.totalNodes, + totalEdges: snap.stats.totalEdges, + topNodes: snap.topNodes.length, + topEdges: snap.topEdges.length, + tookMs, }); return { - success: false, - tooLarge: true, - totalNodes: nodes.length, - ceiling: REBUILD_SAFE_NODE_CEILING, - error: - `Corpus has ${nodes.length} graph nodes; safe-rebuild ceiling ` + - `is ${REBUILD_SAFE_NODE_CEILING}. Run POST /agentmemory/graph/reset ` + - `to wipe and let future extracts rebuild incrementally.`, + success: true, + ...snap.stats, + topNodes: snap.topNodes.length, + topEdges: snap.topEdges.length, + updatedAt: snap.updatedAt, + tookMs, }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logger.error("Graph snapshot rebuild failed", { error: msg }); + return { success: false, error: msg }; } + }, + ); - // Backfill the targeted-lookup indexes so post-rebuild - // graph-extract calls hit the O(1) path instead of falling - // through to the (already-removed) full-scope scan. Batch - // writes via Promise.all to avoid N sequential round-trips — - // BATCH_SIZE bounds in-flight writes so we don't open thousands - // of concurrent state channels on huge corpora. - const liveNodes = nodes.filter((n) => !n.stale); - const liveEdges = edges.filter((e) => !e.stale); - const degree = new Map(); - for (const e of liveEdges) { - degree.set(e.sourceNodeId, (degree.get(e.sourceNodeId) ?? 0) + 1); - degree.set(e.targetNodeId, (degree.get(e.targetNodeId) ?? 0) + 1); - } - const BATCH_SIZE = 100; - for (let i = 0; i < liveNodes.length; i += BATCH_SIZE) { - const batch = liveNodes.slice(i, i + BATCH_SIZE); - await Promise.all( - batch.flatMap((n) => [ - kv.set(KV.graphNameIndex, nameIndexKey(n.type, n.name), n.id), - kv.set(KV.graphNodeDegree, n.id, degree.get(n.id) ?? 0), - ]), - ); - } - for (let i = 0; i < liveEdges.length; i += BATCH_SIZE) { - const batch = liveEdges.slice(i, i + BATCH_SIZE); - await Promise.all( - batch.map((e) => - kv.set( - KV.graphEdgeKey, - edgeIndexKey(e.sourceNodeId, e.targetNodeId, e.type), - e.id, - ), - ), - ); - } - - const snap = buildSnapshotFromArrays(nodes, edges); - await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, snap); - const tookMs = Date.now() - started; - logger.info("Graph snapshot rebuilt", { - totalNodes: snap.stats.totalNodes, - totalEdges: snap.stats.totalEdges, - topNodes: snap.topNodes.length, - topEdges: snap.topEdges.length, - tookMs, - }); - return { - success: true, - ...snap.stats, - topNodes: snap.topNodes.length, - topEdges: snap.topEdges.length, - updatedAt: snap.updatedAt, - tookMs, - }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logger.error("Graph snapshot rebuild failed", { error: msg }); - return { success: false, error: msg }; - } - }); - - // #814 v2 + #825: clean-restart escape hatch for corpora of any - // size, including the legacy 75K+ case that crashes kv.list. - // - // Previous reset walked kv.list(...) which is the - // exact primitive that heartbeat-crashes the worker on the corpus - // this reset was meant to recover (Allan's repro, 0.35s death). - // - // The new design is enumeration-free: write an empty snapshot and - // return. The hot path (mem::graph-query empty-body, mem::graph-stats) - // reads ONLY the snapshot post-#816, so a fresh empty snapshot - // makes the graph behave as if it were empty for every read. - // - // Future extracts repopulate the snapshot + side-indexes - // incrementally (graph-extract is O(1) per node post-#816 — it does - // not consult the legacy rows). - // - // Trade-off: legacy rows in KV.graphNodes / KV.graphEdges remain on - // disk as unreferenced orphans. They consume disk but are never - // read by any post-#816 code path. Cleanup is deferred to a future - // chunked-vacuum job; #816's broken vacuum-via-list strategy is - // what we are leaving behind here. sdk.registerFunction("mem::graph-reset", async () => { const started = Date.now(); - // Stamp resetAt=now on the empty snapshot. Future - // mem::graph-extract calls compare each name-index lookup's - // existing node `createdAt` against this timestamp; anything - // older counts as an orphan and is dropped from the merge path, - // forcing extract to write a fresh row instead of reconnecting - // to a pre-reset entry. - const resetSnapshot: GraphSnapshot = { - ...emptySnapshot(), - resetAt: new Date().toISOString(), - }; - await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, resetSnapshot); + await resetGraphIndexes(kv); const counts: Record = { [KV.graphSnapshot]: 1, }; diff --git a/src/functions/mesh.ts b/src/functions/mesh.ts index ad52e5ea73..0488ee6fa4 100644 --- a/src/functions/mesh.ts +++ b/src/functions/mesh.ts @@ -2,7 +2,17 @@ import type { ISdk } from "iii-sdk"; import type { StateKV } from "../state/kv.js"; import { KV, generateId } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; +import { + GraphIndexReader, + graphIndexReadiness, + indexGraphEdgeOrInvalidate, + indexGraphNodeOrInvalidate, + initializeGraphIndexes, + readIndexedGraph, + withFailClosedGraphMutation, +} from "../state/graph-indexes.js"; import { recordAudit } from "./audit.js"; +import { rebuildGraphSnapshotOrInvalidateInMutation } from "./graph.js"; import type { MeshPeer, Memory, @@ -74,12 +84,30 @@ interface MeshSyncPayload { graphEdges?: GraphEdge[]; } +function hasGraphRecords(data: MeshSyncPayload): boolean { + return Boolean(data.graphNodes?.length || data.graphEdges?.length); +} + +async function requireGraphWriteIndexes( + kv: StateKV, + data: MeshSyncPayload, +): Promise { + if (!hasGraphRecords(data)) return; + const readiness = await initializeGraphIndexes(kv); + if (!readiness.ready) { + throw new Error( + "Graph mesh writes require generation-matched read indexes. Run graph reset before syncing graph data.", + ); + } +} + async function lwwMergeList( kv: StateKV, scope: string, items: T[] | undefined, lockPrefix: string, tsField: "updatedAt" | "createdAt", + onWrite?: (item: T) => Promise, ): Promise { if (!items || !Array.isArray(items)) return 0; let count = 0; @@ -100,7 +128,10 @@ async function lwwMergeList( } return false; }); - if (wrote) count++; + if (wrote) { + count++; + if (onWrite) await onWrite(item); + } } return count; } @@ -112,6 +143,8 @@ function graphNodeTs(node: GraphNode): string { async function lwwMergeGraphNodes( kv: StateKV, items: GraphNode[] | undefined, + activeNodeIds: Set, + generation: string, ): Promise { if (!items || !Array.isArray(items)) return 0; let count = 0; @@ -121,7 +154,7 @@ async function lwwMergeGraphNodes( if (!ts || Number.isNaN(new Date(ts).getTime())) continue; const wrote = await withKeyedLock(`mem:gnode:${item.id}`, async () => { const existing = await kv.get(KV.graphNodes, item.id); - if (!existing) { + if (!existing || !activeNodeIds.has(item.id)) { await kv.set(KV.graphNodes, item.id, item); return true; } @@ -131,11 +164,75 @@ async function lwwMergeGraphNodes( } return false; }); - if (wrote) count++; + if (wrote) { + count++; + await indexGraphNodeOrInvalidate(kv, item, generation); + activeNodeIds.add(item.id); + } } return count; } +async function lwwMergeGraphEdges( + kv: StateKV, + items: GraphEdge[] | undefined, + activeEdgeIds: Set, + generation: string, +): Promise { + if (!items || !Array.isArray(items)) return 0; + let count = 0; + for (const item of items) { + if (!item.id || typeof item.id !== "string") continue; + if (Number.isNaN(new Date(item.createdAt).getTime())) continue; + const wrote = await withKeyedLock(`mem:gedge:${item.id}`, async () => { + const existing = await kv.get(KV.graphEdges, item.id); + if (!existing || !activeEdgeIds.has(item.id)) { + await kv.set(KV.graphEdges, item.id, item); + return true; + } + if (new Date(item.createdAt) > new Date(existing.createdAt)) { + await kv.set(KV.graphEdges, item.id, item); + return true; + } + return false; + }); + if (wrote) { + count++; + await indexGraphEdgeOrInvalidate(kv, item, generation); + activeEdgeIds.add(item.id); + } + } + return count; +} + +async function activeGraphIds( + kv: StateKV, + incomingEdges: GraphEdge[], +): Promise<{ nodeIds: Set; edgeIds: Set }> { + const reader = await GraphIndexReader.open(kv); + if (!reader) throw new Error("Graph read indexes unavailable"); + const nodeIds = new Set( + (await reader.getNameCatalog()).map((entry) => entry.id), + ); + const edgeIds = new Set(); + const edgeEndpoints = new Set(); + for (const edge of incomingEdges) { + edgeEndpoints.add(edge.sourceNodeId); + edgeEndpoints.add(edge.targetNodeId); + const existing = await kv.get(KV.graphEdges, edge.id); + if (existing) { + edgeEndpoints.add(existing.sourceNodeId); + edgeEndpoints.add(existing.targetNodeId); + } + } + for (const nodeId of edgeEndpoints) { + for (const edge of await reader.getIncidentEdges(nodeId)) { + edgeIds.add(edge.id); + } + } + return { nodeIds, edgeIds }; +} + export function registerMeshFunction( sdk: ISdk, kv: StateKV, @@ -337,6 +434,14 @@ export function registerMeshFunction( if (!data || typeof data !== "object") { return { success: false, error: "payload required" }; } + try { + await requireGraphWriteIndexes(kv, data); + } catch (err) { + return { + success: false, + error: err instanceof Error ? err.message : String(err), + }; + } let accepted = 0; accepted += await lwwMergeList(kv, KV.memories, data.memories, "mem:memory", "updatedAt"); @@ -360,8 +465,36 @@ export function registerMeshFunction( }); } } - accepted += await lwwMergeGraphNodes(kv, data.graphNodes); - accepted += await lwwMergeList(kv, KV.graphEdges, data.graphEdges, "mem:gedge", "createdAt"); + if (hasGraphRecords(data)) { + accepted += await withFailClosedGraphMutation(kv, "mesh graph receive", async () => { + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) { + throw new Error("Graph read indexes unavailable"); + } + const { nodeIds, edgeIds } = await activeGraphIds( + kv, + data.graphEdges ?? [], + ); + const graphAccepted = + (await lwwMergeGraphNodes( + kv, + data.graphNodes, + nodeIds, + readiness.generation, + )) + + (await lwwMergeGraphEdges( + kv, + data.graphEdges, + edgeIds, + readiness.generation, + )); + await rebuildGraphSnapshotOrInvalidateInMutation( + kv, + readiness.generation, + ); + return graphAccepted; + }); + } await recordAudit(kv, "mesh_sync", "mem::mesh-receive", [], { action: "mesh.receive", accepted, @@ -435,16 +568,25 @@ async function collectSyncData( result.relations = deltaFilter(all, sinceTime, "createdAt"); } - if (scopes.includes("graph:nodes") && !projectScoped) { - const all = await kv.list(KV.graphNodes); - result.graphNodes = all.filter( - (n) => new Date(graphNodeTs(n)).getTime() > sinceTime, - ); - } - - if (scopes.includes("graph:edges") && !projectScoped) { - const all = await kv.list(KV.graphEdges); - result.graphEdges = deltaFilter(all, sinceTime, "createdAt"); + if ( + !projectScoped && + (scopes.includes("graph:nodes") || scopes.includes("graph:edges")) + ) { + const graph = await readIndexedGraph(kv); + if (graph) { + if (scopes.includes("graph:nodes")) { + result.graphNodes = graph.nodes.filter( + (node) => new Date(graphNodeTs(node)).getTime() > sinceTime, + ); + } + if (scopes.includes("graph:edges")) { + result.graphEdges = deltaFilter( + graph.edges, + sinceTime, + "createdAt", + ); + } + } } return result; @@ -455,6 +597,11 @@ async function applySyncData( data: MeshSyncPayload, scopes: string[], ): Promise { + const graphPayload: MeshSyncPayload = { + graphNodes: scopes.includes("graph:nodes") ? data.graphNodes : undefined, + graphEdges: scopes.includes("graph:edges") ? data.graphEdges : undefined, + }; + await requireGraphWriteIndexes(kv, graphPayload); let applied = 0; if (scopes.includes("memories")) { @@ -484,11 +631,35 @@ async function applySyncData( if (wrote) applied++; } } - if (scopes.includes("graph:nodes")) { - applied += await lwwMergeGraphNodes(kv, data.graphNodes); - } - if (scopes.includes("graph:edges")) { - applied += await lwwMergeList(kv, KV.graphEdges, data.graphEdges, "mem:gedge", "createdAt"); + if (hasGraphRecords(graphPayload)) { + applied += await withFailClosedGraphMutation(kv, "mesh graph sync", async () => { + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) { + throw new Error("Graph read indexes unavailable"); + } + const { nodeIds, edgeIds } = await activeGraphIds( + kv, + graphPayload.graphEdges ?? [], + ); + const graphApplied = + (await lwwMergeGraphNodes( + kv, + graphPayload.graphNodes, + nodeIds, + readiness.generation, + )) + + (await lwwMergeGraphEdges( + kv, + graphPayload.graphEdges, + edgeIds, + readiness.generation, + )); + await rebuildGraphSnapshotOrInvalidateInMutation( + kv, + readiness.generation, + ); + return graphApplied; + }); } return applied; diff --git a/src/functions/reflect.ts b/src/functions/reflect.ts index 3a2af82934..70a82fd974 100644 --- a/src/functions/reflect.ts +++ b/src/functions/reflect.ts @@ -12,6 +12,7 @@ import type { } from "../types.js"; import { recordAudit } from "./audit.js"; import { REFLECT_SYSTEM, buildReflectPrompt } from "../prompts/reflect.js"; +import { readIndexedGraph } from "../state/graph-indexes.js"; interface ConceptCluster { concepts: string[]; @@ -171,14 +172,14 @@ export function registerReflectFunctions( const maxInsightsPerCluster = 5; const maxTotal = 50; - const [graphNodes, graphEdges, semanticMemories, lessons, crystals] = - await Promise.all([ - kv.list(KV.graphNodes).catch(() => []), - kv.list(KV.graphEdges).catch(() => []), - kv.list(KV.semantic).catch(() => []), - kv.list(KV.lessons).catch(() => []), - kv.list(KV.crystals).catch(() => []), - ]); + const [graph, semanticMemories, lessons, crystals] = await Promise.all([ + readIndexedGraph(kv).catch(() => null), + kv.list(KV.semantic).catch(() => []), + kv.list(KV.lessons).catch(() => []), + kv.list(KV.crystals).catch(() => []), + ]); + const graphNodes = graph?.nodes ?? []; + const graphEdges = graph?.edges ?? []; let activeLessons = lessons.filter((l) => !l.deleted); if (data?.project) { diff --git a/src/functions/snapshot.ts b/src/functions/snapshot.ts index 99c45c061f..413d227aed 100644 --- a/src/functions/snapshot.ts +++ b/src/functions/snapshot.ts @@ -12,6 +12,14 @@ import type { } from "../types.js"; import { KV, generateId } from "../state/schema.js"; import type { StateKV } from "../state/kv.js"; +import { + graphIndexReadiness, + indexGraphNodeOrInvalidate, + initializeGraphIndexes, + readIndexedGraph, + withFailClosedGraphMutation, +} from "../state/graph-indexes.js"; +import { rebuildGraphSnapshotOrInvalidateInMutation } from "./graph.js"; import { recordAudit } from "./audit.js"; import { VERSION } from "../version.js"; import { logger } from "../logger.js"; @@ -60,7 +68,22 @@ export function registerSnapshotFunction( const sessions = await kv.list(KV.sessions); const memories = await kv.list(KV.memories); - const graphNodes = await kv.list(KV.graphNodes); + let graphNodes: GraphNode[] = []; + let graphWarning: string | undefined; + try { + const readiness = await initializeGraphIndexes(kv); + if (readiness.ready) { + const graph = await readIndexedGraph(kv); + if (graph) graphNodes = graph.nodes; + else graphWarning = "Graph read indexes unavailable"; + } else { + graphWarning = + readiness.reason ?? "Graph read indexes unavailable"; + } + } catch (error) { + graphWarning = + error instanceof Error ? error.message : String(error); + } const accessLogs = await kv .list(KV.accessLog) .catch(() => [] as AccessLogExport[]); @@ -81,6 +104,7 @@ export function registerSnapshotFunction( sessions, memories, graphNodes, + ...(graphWarning ? { graphWarning } : {}), observations, accessLogs, }; @@ -129,7 +153,11 @@ export function registerSnapshotFunction( }); logger.info("Snapshot created", { commitHash }); - return { success: true, snapshot: meta }; + return { + success: true, + snapshot: meta, + ...(graphWarning ? { warning: graphWarning } : {}), + }; } catch (err) { const msg = err instanceof Error ? err.message : String(err); logger.error("Snapshot failed", { error: msg }); @@ -193,6 +221,18 @@ export function registerSnapshotFunction( accessLogs?: AccessLogExport[]; }; + if (state.graphNodes?.length) { + const readiness = await initializeGraphIndexes(kv); + if (!readiness.ready) { + return { + success: false, + error: + "Graph restore requires generation-matched read indexes. " + + "Run graph reset before restoring graph data into a legacy corpus.", + }; + } + } + if (state.sessions) { for (const session of state.sessions) { await kv.set(KV.sessions, session.id, session); @@ -204,9 +244,26 @@ export function registerSnapshotFunction( } } if (state.graphNodes) { - for (const node of state.graphNodes) { - await kv.set(KV.graphNodes, node.id, node); - } + await withFailClosedGraphMutation(kv, "graph snapshot restore", async () => { + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) { + throw new Error("Graph read indexes unavailable"); + } + for (const node of state.graphNodes!) { + await kv.set(KV.graphNodes, node.id, node); + await indexGraphNodeOrInvalidate( + kv, + node as unknown as GraphNode, + readiness.generation, + ); + } + if (state.graphNodes!.length > 0) { + await rebuildGraphSnapshotOrInvalidateInMutation( + kv, + readiness.generation, + ); + } + }); } if (state.observations) { for (const [sessionId, obs] of Object.entries(state.observations)) { diff --git a/src/functions/temporal-graph.ts b/src/functions/temporal-graph.ts index 1e8d1df100..33b6f49fe9 100644 --- a/src/functions/temporal-graph.ts +++ b/src/functions/temporal-graph.ts @@ -9,6 +9,14 @@ import type { } from "../types.js"; import { KV, generateId } from "../state/schema.js"; import type { StateKV } from "../state/kv.js"; +import { + GraphIndexReader, + graphIndexReadiness, + indexGraphEdgeOrInvalidate, + indexGraphNodeOrInvalidate, + withFailClosedGraphMutation, +} from "../state/graph-indexes.js"; +import { rebuildGraphSnapshotOrInvalidateInMutation } from "./graph.js"; import { logger } from "../logger.js"; const TEMPORAL_EXTRACTION_SYSTEM = `You are a temporal knowledge extraction engine. Given observations, extract entities AND their temporal relationships with full context metadata. @@ -149,6 +157,19 @@ function parseTemporalGraphXml( return { nodes, edges }; } +async function findIndexedEntity( + reader: GraphIndexReader, + entityName: string, +): Promise { + const lower = entityName.toLowerCase(); + const entry = (await reader.getNameCatalog()).find( + (candidate) => + candidate.name.toLowerCase() === lower || + candidate.aliases?.some((alias) => alias.toLowerCase() === lower), + ); + return entry ? reader.getNode(entry.id) : null; +} + export function registerTemporalGraphFunctions( sdk: ISdk, kv: StateKV, @@ -170,6 +191,16 @@ export function registerTemporalGraphFunctions( return { success: false, error: "No observations provided" }; } + const reader = await GraphIndexReader.open(kv); + if (!reader) { + return { + success: false, + error: + "Temporal graph extraction requires generation-matched read " + + "indexes. Run graph reset before adding temporal graph data.", + }; + } + const items = data.observations .map( (o, i) => @@ -186,76 +217,111 @@ export function registerTemporalGraphFunctions( const obsIds = data.observations.map((o) => o.id); const { nodes, edges } = parseTemporalGraphXml(response, obsIds); - const existingNodes = await kv.list(KV.graphNodes); - const existingEdges = await kv.list(KV.graphEdges); - - const idRemap = new Map(); - for (const node of nodes) { - const existing = existingNodes.find( - (n) => - n.name === node.name && n.type === node.type, - ); - if (existing) { - const oldId = node.id; - const merged = { - ...existing, - sourceObservationIds: [ - ...new Set([ - ...existing.sourceObservationIds, - ...obsIds, - ]), - ], - properties: { ...existing.properties, ...node.properties }, - updatedAt: new Date().toISOString(), - aliases: [ - ...new Set([ - ...(existing.aliases || []), - ...(node.aliases || []), - ]), - ], - }; - if (merged.aliases.length === 0) delete (merged as any).aliases; - await kv.set(KV.graphNodes, existing.id, merged); - node.id = existing.id; - idRemap.set(oldId, existing.id); - } else { - await kv.set(KV.graphNodes, node.id, node); - existingNodes.push(node); + await withFailClosedGraphMutation(kv, "temporal graph extraction", async () => { + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) { + throw new Error("Graph read indexes became unavailable"); } - } - - for (const edge of edges) { - if (idRemap.has(edge.sourceNodeId)) { - edge.sourceNodeId = idRemap.get(edge.sourceNodeId)!; + const currentReader = await GraphIndexReader.open( + kv, + readiness.generation, + ); + if (!currentReader) { + throw new Error("Graph read indexes became unavailable"); } - if (idRemap.has(edge.targetNodeId)) { - edge.targetNodeId = idRemap.get(edge.targetNodeId)!; + const existingNodes: GraphNode[] = []; + for (const entry of await currentReader.getNameCatalog()) { + const existing = await currentReader.getNode(entry.id); + if (existing) existingNodes.push(existing); } - const existingKey = `${edge.sourceNodeId}|${edge.targetNodeId}|${edge.type}`; - const existingEdge = existingEdges.find( - (e) => - `${e.sourceNodeId}|${e.targetNodeId}|${e.type}` === - existingKey, - ); - if (existingEdge) { - const updatedOld = { - ...existingEdge, - isLatest: false, - tvalidEnd: - existingEdge.tvalidEnd || new Date().toISOString(), - supersededBy: edge.id, - }; - await kv.set(KV.graphEdges, existingEdge.id, updatedOld); - - await kv.set(KV.graphEdgeHistory, existingEdge.id, updatedOld); + const idRemap = new Map(); + for (const node of nodes) { + const existing = existingNodes.find( + (candidate) => + candidate.name === node.name && candidate.type === node.type, + ); + if (existing) { + const oldId = node.id; + const merged = { + ...existing, + sourceObservationIds: [ + ...new Set([ + ...existing.sourceObservationIds, + ...obsIds, + ]), + ], + properties: { ...existing.properties, ...node.properties }, + updatedAt: new Date().toISOString(), + aliases: [ + ...new Set([ + ...(existing.aliases || []), + ...(node.aliases || []), + ]), + ], + }; + if (merged.aliases.length === 0) delete (merged as any).aliases; + await kv.set(KV.graphNodes, existing.id, merged); + await indexGraphNodeOrInvalidate( + kv, + merged, + readiness.generation, + ); + node.id = existing.id; + idRemap.set(oldId, existing.id); + } else { + await kv.set(KV.graphNodes, node.id, node); + await indexGraphNodeOrInvalidate( + kv, + node, + readiness.generation, + ); + existingNodes.push(node); + } + } - edge.version = (existingEdge.version || 1) + 1; + for (const edge of edges) { + if (idRemap.has(edge.sourceNodeId)) { + edge.sourceNodeId = idRemap.get(edge.sourceNodeId)!; + } + if (idRemap.has(edge.targetNodeId)) { + edge.targetNodeId = idRemap.get(edge.targetNodeId)!; + } + const existingKey = `${edge.sourceNodeId}|${edge.targetNodeId}|${edge.type}`; + const existingEdge = ( + await currentReader.getIncidentEdges(edge.sourceNodeId) + ).find( + (candidate) => + `${candidate.sourceNodeId}|${candidate.targetNodeId}|${candidate.type}` === + existingKey, + ); + + if (existingEdge) { + const updatedOld: GraphEdge = { + ...existingEdge, + isLatest: false, + tvalidEnd: + existingEdge.tvalidEnd || new Date().toISOString(), + supersededBy: edge.id, + }; + await kv.set(KV.graphEdges, existingEdge.id, updatedOld); + await kv.set(KV.graphEdgeHistory, existingEdge.id, updatedOld); + edge.version = (existingEdge.version || 1) + 1; + } + + await kv.set(KV.graphEdges, edge.id, edge); + await indexGraphEdgeOrInvalidate( + kv, + edge, + readiness.generation, + ); } - await kv.set(KV.graphEdges, edge.id, edge); - existingEdges.push(edge); - } + await rebuildGraphSnapshotOrInvalidateInMutation( + kv, + readiness.generation, + ); + }); logger.info("Temporal graph extraction complete", { nodes: nodes.length, @@ -280,35 +346,24 @@ export function registerTemporalGraphFunctions( asOf?: string; includeHistory?: boolean; }): Promise => { - const allNodes = await kv.list(KV.graphNodes); - const allEdges = await kv.list(KV.graphEdges); - - const entity = allNodes.find( - (n) => - n.name.toLowerCase() === data.entityName.toLowerCase() || - (n.aliases && - n.aliases.some( - (a) => - a.toLowerCase() === data.entityName.toLowerCase(), - )), - ); + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) { + return { error: "Graph read indexes unavailable" }; + } + const reader = await GraphIndexReader.open(kv); + if (!reader) return { error: "Graph read indexes unavailable" }; + const entity = await findIndexedEntity(reader, data.entityName); if (!entity) { return { error: `Entity "${data.entityName}" not found` } as any; } - const relatedEdges = allEdges.filter( - (e) => e.sourceNodeId === entity.id || e.targetNodeId === entity.id, - ); + const relatedEdges = await reader.getIncidentEdges(entity.id); - const historicalEdges = await kv - .list(KV.graphEdgeHistory) - .catch(() => [] as GraphEdge[]); - const entityHistory = historicalEdges.filter( - (e) => e.sourceNodeId === entity.id || e.targetNodeId === entity.id, + const entityHistory = relatedEdges.filter( + (edge) => edge.isLatest === false, ); - - const allEntityEdges = [...relatedEdges, ...entityHistory]; + const allEntityEdges = relatedEdges; if (data.asOf) { const asOfTime = new Date(data.asOf).getTime(); @@ -331,24 +386,30 @@ export function registerTemporalGraphFunctions( const currentEdges = getLatestByKey(validEdges); const historical = data.includeHistory ? validEdges : []; - return { + const result = { entity, currentEdges, historicalEdges: historical, timeline: buildTimeline(allEntityEdges), }; + return (await reader.isCurrent()) + ? result + : { error: "Graph read index generation changed during query" }; } const currentEdges = relatedEdges.filter( (e) => e.isLatest !== false, ); - return { + const result = { entity, currentEdges, historicalEdges: data.includeHistory ? entityHistory : [], timeline: buildTimeline(allEntityEdges), }; + return (await reader.isCurrent()) + ? result + : { error: "Graph read index generation changed during query" }; }, ); @@ -358,27 +419,16 @@ export function registerTemporalGraphFunctions( from?: string; to?: string; }) => { - const allNodes = await kv.list(KV.graphNodes); - const allEdges = await kv.list(KV.graphEdges); - const historicalEdges = await kv - .list(KV.graphEdgeHistory) - .catch(() => [] as GraphEdge[]); - - const entity = allNodes.find( - (n) => n.name.toLowerCase() === data.entityName.toLowerCase(), - ); + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) { + return { error: "Graph read indexes unavailable" }; + } + const reader = await GraphIndexReader.open(kv); + if (!reader) return { error: "Graph read indexes unavailable" }; + const entity = await findIndexedEntity(reader, data.entityName); if (!entity) return { error: "Entity not found" }; - const allEntityEdges = [ - ...allEdges.filter( - (e) => - e.sourceNodeId === entity.id || e.targetNodeId === entity.id, - ), - ...historicalEdges.filter( - (e) => - e.sourceNodeId === entity.id || e.targetNodeId === entity.id, - ), - ]; + const allEntityEdges = await reader.getIncidentEdges(entity.id); allEntityEdges.sort( (a, b) => @@ -412,11 +462,14 @@ export function registerTemporalGraphFunctions( isLatest: e.isLatest !== false, })); - return { + const result = { entity: entity.name, totalChanges: changes.length, changes, }; + return (await reader.isCurrent()) + ? result + : { error: "Graph read index generation changed during query" }; }, ); } diff --git a/src/index.ts b/src/index.ts index 717419f7df..c788a48b51 100644 --- a/src/index.ts +++ b/src/index.ts @@ -22,6 +22,7 @@ import { } from "./providers/index.js"; import { StateKV } from "./state/kv.js"; import { KV } from "./state/schema.js"; +import { initializeGraphIndexes } from "./state/graph-indexes.js"; import { VectorIndex } from "./state/vector-index.js"; import { HybridSearch } from "./state/hybrid-search.js"; import { IndexPersistence } from "./state/index-persistence.js"; @@ -256,6 +257,16 @@ async function main() { registerTimelineFunction(sdk, kv); registerProfileFunction(sdk, kv); registerAutoForgetFunction(sdk, kv); + try { + const graphIndexes = await initializeGraphIndexes(kv); + if (!graphIndexes.ready) { + console.warn( + `[agentmemory] Graph read indexes unavailable: ${graphIndexes.reason}`, + ); + } + } catch (err) { + console.warn(`[agentmemory] Failed to initialize graph indexes:`, err); + } registerExportImportFunction(sdk, kv); registerEnrichFunction(sdk, kv); diff --git a/src/mcp/server.ts b/src/mcp/server.ts index ef26427aaf..f64b77f11e 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -5,8 +5,6 @@ import type { SessionSummary, Memory, Session, - GraphNode, - GraphEdge, } from "../types.js"; import { getVisibleTools } from "./tools-registry.js"; import { timingSafeCompare } from "../auth.js"; @@ -1479,14 +1477,10 @@ export function registerMcpEndpoints( if (uri === "agentmemory://graph/stats") { try { - const nodes = await kv.list(KV.graphNodes); - const edges = await kv.list(KV.graphEdges); - const nodesByType: Record = {}; - for (const n of nodes) - nodesByType[n.type] = (nodesByType[n.type] || 0) + 1; - const edgesByType: Record = {}; - for (const e of edges) - edgesByType[e.type] = (edgesByType[e.type] || 0) + 1; + const stats = await sdk.trigger({ + function_id: "mem::graph-stats", + payload: {}, + }); return { status_code: 200, body: { @@ -1494,12 +1488,7 @@ export function registerMcpEndpoints( { uri, mimeType: "application/json", - text: JSON.stringify({ - totalNodes: nodes.length, - totalEdges: edges.length, - nodesByType, - edgesByType, - }), + text: JSON.stringify(stats), }, ], }, diff --git a/src/state/graph-indexes.ts b/src/state/graph-indexes.ts new file mode 100644 index 0000000000..ca07b0d5ec --- /dev/null +++ b/src/state/graph-indexes.ts @@ -0,0 +1,662 @@ +import type { GraphNode, GraphEdge, GraphSnapshot } from "../types.js"; +import { KV } from "./schema.js"; +import type { StateKV } from "./kv.js"; +import { withKeyedLock } from "./keyed-mutex.js"; + +export const NAME_SHARD_COUNT = 64; +export const GRAPH_INDEX_VERSION = 2; +const META_KEY = "current"; +const SNAPSHOT_KEY = "current"; + +export interface NameCatalogEntry { + id: string; + name: string; + aliases?: string[]; +} + +interface GraphIndexMeta { + version: typeof GRAPH_INDEX_VERSION; + status: "initializing" | "ready" | "unavailable"; + generation: string; + updatedAt: string; + reason?: string; +} + +export interface GraphIndexReadiness { + ready: boolean; + status: GraphIndexMeta["status"] | "missing"; + generation?: string; + resetAt?: string; + reason?: string; +} + +function newGeneration(): string { + return `gidx_${crypto.randomUUID()}`; +} + +function nameShardStorageKey(generation: string, shard: string): string { + return `${generation}:${shard}`; +} + +function adjacencyStorageKey(generation: string, nodeId: string): string { + return `${generation}:${nodeId}`; +} + +function observationStorageKey(generation: string, obsId: string): string { + return `${generation}:${obsId}`; +} + +function freshSnapshot( + generation: string, + resetAt?: string, +): GraphSnapshot { + return { + version: 1, + topNodes: [], + topEdges: [], + topDegrees: {}, + stats: { + totalNodes: 0, + totalEdges: 0, + nodesByType: {}, + edgesByType: {}, + }, + updatedAt: new Date().toISOString(), + dirty: false, + indexGeneration: generation, + ...(resetAt ? { resetAt } : {}), + }; +} + +async function readMeta(kv: StateKV): Promise { + return kv.get(KV.graphIndexMeta, META_KEY); +} + +async function readSnapshot(kv: StateKV): Promise { + return kv.get(KV.graphSnapshot, SNAPSHOT_KEY); +} + +async function writeMeta( + kv: StateKV, + status: GraphIndexMeta["status"], + generation: string, + reason?: string, +): Promise { + await kv.set(KV.graphIndexMeta, META_KEY, { + version: GRAPH_INDEX_VERSION, + status, + generation, + updatedAt: new Date().toISOString(), + ...(reason ? { reason } : {}), + } satisfies GraphIndexMeta); +} + +export async function markGraphIndexesUnavailable( + kv: StateKV, + reason: string, + expectedGeneration?: string, +): Promise { + let meta: GraphIndexMeta | null; + try { + meta = await readMeta(kv); + } catch (error) { + if (!expectedGeneration) throw error; + await writeMeta(kv, "unavailable", expectedGeneration, reason); + return; + } + if (expectedGeneration && meta?.generation !== expectedGeneration) return; + await writeMeta( + kv, + "unavailable", + meta?.generation ?? expectedGeneration ?? newGeneration(), + reason, + ); +} + +export function nameShardKey(nodeId: string): string { + let hash = 5381; + for (let i = 0; i < nodeId.length; i++) { + hash = ((hash * 33) ^ nodeId.charCodeAt(i)) >>> 0; + } + return String(hash % NAME_SHARD_COUNT); +} + +export async function graphIndexReadiness( + kv: StateKV, +): Promise { + const [meta, snapshot] = await Promise.all([readMeta(kv), readSnapshot(kv)]); + if ( + meta?.version === GRAPH_INDEX_VERSION && + meta.status === "ready" && + typeof meta.generation === "string" && + meta.generation.length > 0 && + snapshot?.indexGeneration === meta.generation + ) { + return { + ready: true, + status: "ready", + generation: meta.generation, + resetAt: snapshot.resetAt, + }; + } + return { + ready: false, + status: meta?.status ?? "missing", + generation: meta?.generation, + resetAt: snapshot?.resetAt, + reason: + meta?.reason ?? + (meta?.status === "ready" + ? "graph index generation does not match the active snapshot" + : "graph read indexes are not initialized"), + }; +} + +export async function graphIndexesReady(kv: StateKV): Promise { + return (await graphIndexReadiness(kv)).ready; +} + +export async function initializeGraphIndexes( + kv: StateKV, +): Promise { + return withKeyedLock("gidx:init", async () => { + const current = await graphIndexReadiness(kv); + if (current.ready || current.status === "unavailable") return current; + + const groups = await kv.listGroups(); + const graphScopesPresent = + groups.includes(KV.graphNodes) || groups.includes(KV.graphEdges); + if (graphScopesPresent) { + const generation = current.generation ?? newGeneration(); + const reason = + "legacy graph scopes contain data but cannot be scanned safely; reset the graph or wait for paginated state scanning support"; + await writeMeta(kv, "unavailable", generation, reason); + return { + ready: false, + status: "unavailable", + generation, + resetAt: current.resetAt, + reason, + }; + } + + const generation = newGeneration(); + await writeMeta(kv, "initializing", generation); + await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, freshSnapshot(generation)); + await writeMeta(kv, "ready", generation); + return { + ready: true, + status: "ready", + generation, + }; + }); +} + +export async function resetGraphIndexes(kv: StateKV): Promise { + return withGraphIndexMutation(() => + withKeyedLock("gidx:init", async () => { + const generation = newGeneration(); + const resetAt = new Date().toISOString(); + const snapshot = freshSnapshot(generation, resetAt); + await writeMeta(kv, "initializing", generation); + await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, snapshot); + await writeMeta(kv, "ready", generation); + return snapshot; + }), + ); +} + +export function withGraphIndexMutation(fn: () => Promise): Promise { + return withKeyedLock("gidx:mutation", fn); +} + +async function failClosedGraphMutation( + kv: StateKV, + operation: string, + fn: () => Promise, +): Promise { + const before = await graphIndexReadiness(kv).catch(() => null); + let expectedGeneration = before?.ready ? before.generation : undefined; + try { + return await fn(); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + if (!expectedGeneration) { + const current = await graphIndexReadiness(kv).catch(() => null); + expectedGeneration = current?.ready ? current.generation : undefined; + } + if (expectedGeneration) { + await markGraphIndexesUnavailable( + kv, + `${operation} failed after graph mutation started: ${message}`, + expectedGeneration, + ).catch(() => {}); + } + throw error instanceof Error ? error : new Error(message); + } +} + +export function withFailClosedGraphMutation( + kv: StateKV, + operation: string, + fn: () => Promise, +): Promise { + return withGraphIndexMutation(() => + failClosedGraphMutation(kv, operation, fn), + ); +} + +async function readyGeneration( + kv: StateKV, + expectedGeneration?: string, +): Promise { + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) return null; + if ( + expectedGeneration && + readiness.generation !== expectedGeneration + ) { + return null; + } + return readiness.generation; +} + +export async function indexGraphNode( + kv: StateKV, + node: GraphNode, + expectedGeneration?: string, +): Promise { + if (!node?.id || typeof node.name !== "string") return false; + const generation = await readyGeneration(kv, expectedGeneration); + if (!generation) return false; + const shard = nameShardKey(node.id); + const storageKey = nameShardStorageKey(generation, shard); + await withKeyedLock(`gidx:shard:${storageKey}`, async () => { + const entries = + (await kv.get(KV.graphNameShards, storageKey)) ?? []; + const next = entries.filter((entry) => entry.id !== node.id); + next.push({ + id: node.id, + name: node.name, + ...(node.aliases?.length ? { aliases: node.aliases } : {}), + }); + await kv.set(KV.graphNameShards, storageKey, next); + }); + await linkObservationsForGeneration( + kv, + generation, + node.id, + node.sourceObservationIds, + ); + return true; +} + +async function linkObservationsForGeneration( + kv: StateKV, + generation: string, + nodeId: string, + obsIds: string[] | undefined, +): Promise { + for (const obsId of obsIds ?? []) { + const storageKey = observationStorageKey(generation, obsId); + await withKeyedLock(`gidx:obs:${storageKey}`, async () => { + const nodeIds = + (await kv.get(KV.graphObsNodes, storageKey)) ?? []; + if (!nodeIds.includes(nodeId)) { + nodeIds.push(nodeId); + await kv.set(KV.graphObsNodes, storageKey, nodeIds); + } + }); + } +} + +export async function indexGraphEdge( + kv: StateKV, + edge: GraphEdge, + expectedGeneration?: string, +): Promise { + if (!edge?.id || !edge.sourceNodeId || !edge.targetNodeId) return false; + const generation = await readyGeneration(kv, expectedGeneration); + if (!generation) return false; + const endpoints = + edge.sourceNodeId === edge.targetNodeId + ? [edge.sourceNodeId] + : [edge.sourceNodeId, edge.targetNodeId]; + for (const nodeId of endpoints) { + const storageKey = adjacencyStorageKey(generation, nodeId); + await withKeyedLock(`gidx:adj:${storageKey}`, async () => { + const edgeIds = + (await kv.get(KV.graphAdjacency, storageKey)) ?? []; + if (!edgeIds.includes(edge.id)) { + edgeIds.push(edge.id); + await kv.set(KV.graphAdjacency, storageKey, edgeIds); + } + }); + } + return true; +} + +async function invalidateFailedIndexWrite( + kv: StateKV, + kind: "node" | "edge", + id: string, + expectedGeneration: string | undefined, + error: unknown, +): Promise { + const message = error instanceof Error ? error.message : String(error); + await markGraphIndexesUnavailable( + kv, + `graph ${kind} ${id} could not be indexed: ${message}`, + expectedGeneration, + ).catch(() => {}); + throw error instanceof Error ? error : new Error(message); +} + +export async function indexGraphNodeOrInvalidate( + kv: StateKV, + node: GraphNode, + expectedGeneration?: string, +): Promise { + let generation = expectedGeneration; + try { + const readiness = await graphIndexReadiness(kv); + generation ??= readiness.generation; + if ( + !readiness.ready || + !generation || + readiness.generation !== generation || + !(await indexGraphNode(kv, node, generation)) + ) { + throw new Error(`graph node ${node.id} could not be indexed`); + } + } catch (error) { + await invalidateFailedIndexWrite( + kv, + "node", + node.id, + generation, + error, + ); + } +} + +export async function removeGraphNodeFromIndexOrInvalidate( + kv: StateKV, + nodeId: string, + expectedGeneration: string, +): Promise { + try { + const generation = await readyGeneration(kv, expectedGeneration); + if (!generation) throw new Error(`graph node ${nodeId} could not be removed`); + const storageKey = nameShardStorageKey( + generation, + nameShardKey(nodeId), + ); + await withKeyedLock(`gidx:shard:${storageKey}`, async () => { + const entries = + (await kv.get(KV.graphNameShards, storageKey)) ?? []; + await kv.set( + KV.graphNameShards, + storageKey, + entries.filter((entry) => entry.id !== nodeId), + ); + }); + } catch (error) { + await invalidateFailedIndexWrite( + kv, + "node", + nodeId, + expectedGeneration, + error, + ); + } +} + +export async function indexGraphEdgeOrInvalidate( + kv: StateKV, + edge: GraphEdge, + expectedGeneration?: string, +): Promise { + let generation = expectedGeneration; + try { + const readiness = await graphIndexReadiness(kv); + generation ??= readiness.generation; + if ( + !readiness.ready || + !generation || + readiness.generation !== generation || + !(await indexGraphEdge(kv, edge, generation)) + ) { + throw new Error(`graph edge ${edge.id} could not be indexed`); + } + } catch (error) { + await invalidateFailedIndexWrite( + kv, + "edge", + edge.id, + generation, + error, + ); + } +} + +async function loadCatalogForGeneration( + kv: StateKV, + generation: string, +): Promise { + const shards = await Promise.all( + Array.from({ length: NAME_SHARD_COUNT }, (_, shard) => + kv.get( + KV.graphNameShards, + nameShardStorageKey(generation, String(shard)), + ), + ), + ); + const catalog: NameCatalogEntry[] = []; + for (const entries of shards) { + if (Array.isArray(entries)) catalog.push(...entries); + } + return catalog; +} + +export async function loadNameCatalog( + kv: StateKV, +): Promise { + const generation = await readyGeneration(kv); + return generation ? loadCatalogForGeneration(kv, generation) : []; +} + +async function loadAdjacentEdgeIdsForGeneration( + kv: StateKV, + generation: string, + nodeId: string, +): Promise { + const edgeIds = await kv.get( + KV.graphAdjacency, + adjacencyStorageKey(generation, nodeId), + ); + return Array.isArray(edgeIds) ? edgeIds : []; +} + +async function loadNodeIdsForObservationsForGeneration( + kv: StateKV, + generation: string, + obsIds: string[], +): Promise { + const ids = new Set(); + for (const obsId of obsIds) { + const nodeIds = await kv.get( + KV.graphObsNodes, + observationStorageKey(generation, obsId), + ); + if (Array.isArray(nodeIds)) { + for (const id of nodeIds) ids.add(id); + } + } + return [...ids]; +} + +export class GraphIndexReader { + private nodeCache = new Map(); + private edgeCache = new Map(); + private catalog: NameCatalogEntry[] | null = null; + private indexedNodeIds: Set | null = null; + private indexedEdgeIds = new Set(); + + private constructor( + private kv: StateKV, + private generation: string, + ) {} + + static async open( + kv: StateKV, + expectedGeneration?: string, + ): Promise { + const readiness = await graphIndexReadiness(kv); + if ( + !readiness.ready || + !readiness.generation || + (expectedGeneration && readiness.generation !== expectedGeneration) + ) { + return null; + } + return new GraphIndexReader(kv, readiness.generation); + } + + async isCurrent(): Promise { + try { + const readiness = await graphIndexReadiness(this.kv); + return readiness.ready && readiness.generation === this.generation; + } catch { + return false; + } + } + + async getNode(nodeId: string): Promise { + const cached = this.nodeCache.get(nodeId); + if (cached !== undefined) return cached; + if (!this.indexedNodeIds) await this.getNameCatalog(); + if (!this.indexedNodeIds!.has(nodeId)) { + this.nodeCache.set(nodeId, null); + return null; + } + const raw = await this.kv.get(KV.graphNodes, nodeId); + const node = raw && !raw.stale ? raw : null; + this.nodeCache.set(nodeId, node); + return node; + } + + async getEdge(edgeId: string): Promise { + const cached = this.edgeCache.get(edgeId); + if (cached !== undefined) return cached; + if (!this.indexedEdgeIds.has(edgeId)) return null; + const raw = await this.kv.get(KV.graphEdges, edgeId); + const edge = raw && !raw.stale ? raw : null; + this.edgeCache.set(edgeId, edge); + return edge; + } + + async getNameCatalog(): Promise { + if (!this.catalog) { + this.catalog = await loadCatalogForGeneration(this.kv, this.generation); + this.indexedNodeIds = new Set(this.catalog.map((entry) => entry.id)); + } + return this.catalog; + } + + async getNodeIdsForObservations(obsIds: string[]): Promise { + return loadNodeIdsForObservationsForGeneration( + this.kv, + this.generation, + obsIds, + ); + } + + async getIncidentEdges( + nodeId: string, + maxEdges = Number.POSITIVE_INFINITY, + ): Promise { + if (!this.indexedNodeIds) await this.getNameCatalog(); + if (!this.indexedNodeIds!.has(nodeId)) return []; + if (!(await this.getNode(nodeId))) return []; + const edgeIds = await loadAdjacentEdgeIdsForGeneration( + this.kv, + this.generation, + nodeId, + ); + const edges: GraphEdge[] = []; + for (const edgeId of edgeIds) { + if (edges.length >= maxEdges) break; + this.indexedEdgeIds.add(edgeId); + const edge = await this.getEdge(edgeId); + if ( + edge && + (await this.getNode(edge.sourceNodeId)) && + (await this.getNode(edge.targetNodeId)) && + (edge.sourceNodeId === nodeId || edge.targetNodeId === nodeId) + ) { + edges.push(edge); + } + } + return edges; + } + + async getNeighbors( + nodeId: string, + ): Promise> { + const neighbors: Array<{ node: GraphNode; edge: GraphEdge }> = []; + for (const edge of await this.getIncidentEdges(nodeId)) { + const neighborId = + edge.sourceNodeId === nodeId ? edge.targetNodeId : edge.sourceNodeId; + const node = await this.getNode(neighborId); + if (node) neighbors.push({ node, edge }); + } + return neighbors; + } +} + +export async function backfillGraphIndexes( + kv: StateKV, + nodes: GraphNode[], + edges: GraphEdge[], +): Promise { + await withGraphIndexMutation(async () => { + const readiness = await graphIndexReadiness(kv); + if (!readiness.ready || !readiness.generation) { + throw new Error("graph read indexes are unavailable"); + } + for (const node of nodes) { + await indexGraphNodeOrInvalidate(kv, node, readiness.generation); + } + for (const edge of edges) { + await indexGraphEdgeOrInvalidate(kv, edge, readiness.generation); + } + }); +} + +export async function readIndexedGraph( + kv: StateKV, +): Promise<{ nodes: GraphNode[]; edges: GraphEdge[] } | null> { + const reader = await GraphIndexReader.open(kv); + if (!reader) return null; + const nodeIds = new Set( + (await reader.getNameCatalog()).map((entry) => entry.id), + ); + const nodes: GraphNode[] = []; + for (const nodeId of nodeIds) { + const node = await reader.getNode(nodeId); + if (node) nodes.push(node); + } + const edgeIds = new Set(); + for (const node of nodes) { + for (const edge of await reader.getIncidentEdges(node.id)) { + edgeIds.add(edge.id); + } + } + const edges: GraphEdge[] = []; + for (const edgeId of edgeIds) { + const edge = await reader.getEdge(edgeId); + if (edge) edges.push(edge); + } + return (await reader.isCurrent()) ? { nodes, edges } : null; +} diff --git a/src/state/kv.ts b/src/state/kv.ts index 0c0e6ccc12..446e4d1030 100644 --- a/src/state/kv.ts +++ b/src/state/kv.ts @@ -44,4 +44,19 @@ export class StateKV { payload: { scope }, }) } + + async listGroups(): Promise { + const result = await this.sdk.trigger< + Record, + string[] | { groups: string[] } + >({ + function_id: 'state::list_groups', + payload: {}, + }) + const groups = Array.isArray(result) ? result : result?.groups + if (!Array.isArray(groups) || !groups.every((group) => typeof group === 'string')) { + throw new Error('state::list_groups returned an invalid response') + } + return groups + } } diff --git a/src/state/schema.ts b/src/state/schema.ts index 773f147ce6..45dfec3d68 100644 --- a/src/state/schema.ts +++ b/src/state/schema.ts @@ -38,6 +38,23 @@ export const KV = { graphNameIndex: "mem:graph:name-index", graphEdgeKey: "mem:graph:edge-key", graphNodeDegree: "mem:graph:node-degree", + // Read-path side-indexes so graph retrieval never enumerates the full + // nodes/edges scopes. Maintained as hints on every write site; + // readers verify each hit against the live record (stale flag + + // snapshot resetAt) so deletes/wipes need no index cleanup. + // - graphNameShards: key `hash(nodeId) % 64` -> Array<{id, name}>. + // The full name catalog is readable as 64 bounded gets, preserving + // substring-match semantics without a kv.list. + // - graphAdjacency: key nodeId -> incident edgeId[]. Bounds traversal + // cost by degree x depth instead of total edge count. + // - graphObsNodes: key obsId -> nodeId[] linking observations to the + // graph nodes extracted from them. + // - graphIndexMeta: versioned readiness + generation marker. Readers + // fail closed unless it matches the active graph snapshot. + graphNameShards: "mem:graph:name-shards", + graphAdjacency: "mem:graph:adjacency", + graphObsNodes: "mem:graph:obs-nodes", + graphIndexMeta: "mem:graph:index-meta", semantic: "mem:semantic", procedural: "mem:procedural", teamShared: (teamId: string) => `mem:team:${teamId}:shared`, diff --git a/src/types.ts b/src/types.ts index d2c63efa61..c287d6d2fd 100644 --- a/src/types.ts +++ b/src/types.ts @@ -352,6 +352,7 @@ export interface ExportData { insights?: Insight[]; accessLogs?: AccessLogExport[]; pagination?: ExportPagination; + warnings?: string[]; } export interface AccessLogExport { @@ -480,6 +481,7 @@ export interface GraphQueryResult { // also failed, expose an explanatory note so the viewer can surface // an actionable banner instead of a blank graph. warning?: string; + indexStatus?: "ready" | "unavailable"; } // #814: persisted top-degree subgraph + aggregate counts. Stored under @@ -504,6 +506,7 @@ export interface GraphSnapshot { }; updatedAt: string; dirty: boolean; + indexGeneration?: string; // #825 follow-up: ISO timestamp set by mem::graph-reset. After // reset, mem::graph-extract treats any pre-resetAt node as an // orphan (skip merge, write fresh) so future extracts don't diff --git a/test/cascade.test.ts b/test/cascade.test.ts index 8462abc7f0..8c0cb06e37 100644 --- a/test/cascade.test.ts +++ b/test/cascade.test.ts @@ -7,14 +7,19 @@ vi.mock("../src/logger.js", () => ({ import { registerCascadeFunction } from "../src/functions/cascade.js"; import type { Memory, GraphNode, GraphEdge } from "../src/types.js"; import { mockKV, mockSdk } from "./helpers/mocks.js"; +import { + backfillGraphIndexes, + initializeGraphIndexes, +} from "../src/state/graph-indexes.js"; describe("Cascade Update Function", () => { let sdk: ReturnType; let kv: ReturnType; - beforeEach(() => { + beforeEach(async () => { sdk = mockSdk(); kv = mockKV(); + await initializeGraphIndexes(kv as never); vi.clearAllMocks(); registerCascadeFunction(sdk as never, kv as never); }); @@ -73,6 +78,11 @@ describe("Cascade Update Function", () => { createdAt: "2026-03-01T00:00:00Z", }; await kv.set("mem:graph:nodes", "node_2", unrelatedNode); + await backfillGraphIndexes( + kv as never, + [node, unrelatedNode], + [], + ); const result = (await sdk.trigger("mem::cascade-update", { supersededMemoryId: "mem_old", @@ -115,7 +125,29 @@ describe("Cascade Update Function", () => { sourceObservationIds: ["obs_x", "obs_y"], createdAt: "2026-03-01T00:00:00Z", }; + const endpoints: GraphNode[] = [ + { + id: "node_a", + type: "concept", + name: "Node A", + properties: {}, + sourceObservationIds: ["obs_x"], + createdAt: "2026-03-01T00:00:00Z", + }, + { + id: "node_b", + type: "concept", + name: "Node B", + properties: {}, + sourceObservationIds: ["obs_y"], + createdAt: "2026-03-01T00:00:00Z", + }, + ]; + for (const node of endpoints) { + await kv.set("mem:graph:nodes", node.id, node); + } await kv.set("mem:graph:edges", "edge_1", edge); + await backfillGraphIndexes(kv as never, endpoints, [edge]); const result = (await sdk.trigger("mem::cascade-update", { supersededMemoryId: "mem_old2", @@ -214,6 +246,7 @@ describe("Cascade Update Function", () => { stale: true, }; await kv.set("mem:graph:nodes", "node_stale", node); + await backfillGraphIndexes(kv as never, [node], []); const result = (await sdk.trigger("mem::cascade-update", { supersededMemoryId: "mem_skip", diff --git a/test/export-import.test.ts b/test/export-import.test.ts index d33aacb1e6..930f185845 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -5,14 +5,21 @@ vi.mock("../src/logger.js", () => ({ })); import { registerExportImportFunction } from "../src/functions/export-import.js"; +import { persistGraphDelta } from "../src/functions/graph.js"; +import { GraphRetrieval } from "../src/functions/graph-retrieval.js"; import { VERSION } from "../src/version.js"; import { getSearchIndex } from "../src/functions/search.js"; +import { GraphIndexReader } from "../src/state/graph-indexes.js"; +import { KV } from "../src/state/schema.js"; import type { Session, CompressedObservation, Memory, SessionSummary, ExportData, + GraphEdge, + GraphNode, + GraphSnapshot, } from "../src/types.js"; function mockKV() { @@ -33,6 +40,10 @@ function mockKV() { const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + listGroups: async (): Promise => + [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope), }; } @@ -134,6 +145,22 @@ describe("Export/Import Functions", () => { expect(result.summaries.length).toBe(1); }); + it("warns when a legacy graph cannot be included safely", async () => { + await kv.set(KV.graphNodes, "legacy", { + id: "legacy", + type: "concept", + name: "Legacy graph", + properties: {}, + sourceObservationIds: [], + createdAt: "2020-01-01T00:00:00.000Z", + } satisfies GraphNode); + + const result = (await sdk.trigger("mem::export", {})) as ExportData; + + expect(result.graphNodes).toBeUndefined(); + expect(result.warnings?.join(" ")).toMatch(/graph data was omitted/i); + }); + it("import with merge strategy adds data", async () => { const exportData: ExportData = { version: "0.3.0", @@ -260,6 +287,120 @@ describe("Export/Import Functions", () => { expect(oldSession).toBeNull(); }); + it("imports historical graph rows into indexes and refreshes snapshot counts", async () => { + const nodes: GraphNode[] = [ + { + id: "gn_old_1", + type: "project", + name: "historical-project", + properties: {}, + sourceObservationIds: [], + createdAt: "2020-01-01T00:00:00.000Z", + }, + { + id: "gn_old_2", + type: "concept", + name: "historical-concept", + properties: {}, + sourceObservationIds: [], + createdAt: "2020-01-01T00:00:00.000Z", + }, + ]; + const edges: GraphEdge[] = [ + { + id: "ge_old_1", + type: "related_to", + sourceNodeId: nodes[0].id, + targetNodeId: nodes[1].id, + weight: 0.8, + sourceObservationIds: [], + createdAt: "2020-01-01T00:00:00.000Z", + }, + ]; + const exportData: ExportData = { + version: "0.9.29", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + graphNodes: nodes, + graphEdges: edges, + }; + + const result = (await sdk.trigger("mem::import", { + exportData, + strategy: "merge", + })) as { success: boolean }; + const snapshot = await kv.get(KV.graphSnapshot, "current"); + const reader = await GraphIndexReader.open(kv as never); + + expect(result.success).toBe(true); + expect(snapshot?.stats).toMatchObject({ totalNodes: 2, totalEdges: 1 }); + expect(await reader!.getNode(nodes[0].id)).toMatchObject({ + name: "historical-project", + }); + expect(await reader!.getIncidentEdges(nodes[0].id)).toHaveLength(1); + + const persistence = await persistGraphDelta( + kv as never, + nodes.map((node, index) => ({ + ...node, + id: `gn_duplicate_${index}`, + })), + [{ + ...edges[0], + id: "ge_duplicate", + sourceNodeId: "gn_duplicate_0", + targetNodeId: "gn_duplicate_1", + }], + [], + ); + expect(persistence).toEqual({ newNodeCount: 0, newEdgeCount: 0 }); + expect(await kv.list(KV.graphNodes)).toHaveLength(2); + expect(await kv.list(KV.graphEdges)).toHaveLength(1); + }); + + it("replace import without graph data resets the visible graph snapshot", async () => { + const graphExport: ExportData = { + version: "0.9.29", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + graphNodes: [ + { + id: "gn_1", + type: "concept", + name: "old graph", + properties: {}, + sourceObservationIds: [], + createdAt: "2026-01-01T00:00:00.000Z", + }, + ], + }; + await sdk.trigger("mem::import", { exportData: graphExport, strategy: "merge" }); + + const emptyExport: ExportData = { + version: "0.9.29", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + }; + const result = (await sdk.trigger("mem::import", { + exportData: emptyExport, + strategy: "replace", + })) as { success: boolean }; + const snapshot = await kv.get(KV.graphSnapshot, "current"); + + expect(result.success).toBe(true); + expect(snapshot?.stats).toMatchObject({ totalNodes: 0, totalEdges: 0 }); + expect(await new GraphRetrieval(kv as never).searchByEntities(["old graph"])).toEqual([]); + }); + it("export then import round-trip preserves data", async () => { const exported = (await sdk.trigger("mem::export", {})) as ExportData; diff --git a/test/graph-import.test.ts b/test/graph-import.test.ts index e342cc8ab5..a76b089419 100644 --- a/test/graph-import.test.ts +++ b/test/graph-import.test.ts @@ -9,6 +9,7 @@ vi.mock("../src/logger.js", () => ({ })); import { parseGraphifyGraph, registerGraphImportFunction } from "../src/functions/graph-import.js"; +import { GraphIndexReader } from "../src/state/graph-indexes.js"; import { KV } from "../src/state/schema.js"; import type { GraphNode, GraphEdge } from "../src/types.js"; @@ -45,6 +46,10 @@ function mockKV() { }, list: async (scope: string): Promise => Array.from(store.get(scope)?.values() ?? []) as T[], + listGroups: async (): Promise => + [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope), _store: store, }; } @@ -158,6 +163,10 @@ describe("mem::graph::import-graphify", () => { const edges = await kv.list(KV.graphEdges); expect(nodes).toHaveLength(4); expect(edges).toHaveLength(2); + const reader = await GraphIndexReader.open(kv as never); + expect(reader).not.toBeNull(); + expect(await reader!.getNameCatalog()).toHaveLength(4); + expect(await reader!.getIncidentEdges(edges[0].sourceNodeId)).not.toHaveLength(0); }); it("re-import is idempotent: second run merges instead of duplicating", async () => { diff --git a/test/graph-index-parity.test.ts b/test/graph-index-parity.test.ts new file mode 100644 index 0000000000..b71c16ce4f --- /dev/null +++ b/test/graph-index-parity.test.ts @@ -0,0 +1,636 @@ +import { describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { GraphRetrieval } from "../src/functions/graph-retrieval.js"; +import { + persistGraphDelta, + rebuildGraphSnapshotFromIndexes, + registerGraphFunction, +} from "../src/functions/graph.js"; +import { registerTemporalGraphFunctions } from "../src/functions/temporal-graph.js"; +import { + backfillGraphIndexes, + graphIndexReadiness, + graphIndexesReady, + GraphIndexReader, + indexGraphNode, + initializeGraphIndexes, + loadNameCatalog, + nameShardKey, +} from "../src/state/graph-indexes.js"; +import { KV } from "../src/state/schema.js"; +import { StateKV } from "../src/state/kv.js"; +import type { + CompressedObservation, + GraphEdge, + GraphNode, + GraphQueryResult, + GraphSnapshot, +} from "../src/types.js"; + +function mockKV(nodes: GraphNode[] = [], edges: GraphEdge[] = []) { + const store = new Map>(); + const calls: Array<{ operation: "get" | "list" | "listGroups"; scope?: string; key?: string }> = []; + let failNextGetScope: string | undefined; + let failNextSetScope: string | undefined; + let getHook: + | { scope: string; remaining: number; fn: () => Promise } + | undefined; + store.set(KV.graphNodes, new Map(nodes.map((node) => [node.id, node]))); + store.set(KV.graphEdges, new Map(edges.map((edge) => [edge.id, edge]))); + + return { + get: async (scope: string, key: string): Promise => { + calls.push({ operation: "get", scope, key }); + if (getHook?.scope === scope && --getHook.remaining === 0) { + const hook = getHook.fn; + getHook = undefined; + await hook(); + } + if (failNextGetScope === scope) { + failNextGetScope = undefined; + throw new Error(`injected ${scope} read failure`); + } + return (store.get(scope)?.get(key) as T) ?? null; + }, + set: async (scope: string, key: string, data: T): Promise => { + if (failNextSetScope === scope) { + failNextSetScope = undefined; + throw new Error(`injected ${scope} write failure`); + } + if (!store.has(scope)) store.set(scope, new Map()); + store.get(scope)!.set(key, data); + return data; + }, + delete: async (scope: string, key: string): Promise => { + store.get(scope)?.delete(key); + }, + list: async (scope: string): Promise => { + calls.push({ operation: "list", scope }); + return Array.from(store.get(scope)?.values() ?? []) as T[]; + }, + listGroups: async (): Promise => { + calls.push({ operation: "listGroups" }); + return [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope); + }, + clearCalls: () => calls.splice(0), + failNextGet: (scope: string) => { + failNextGetScope = scope; + }, + failNextSet: (scope: string) => { + failNextSetScope = scope; + }, + onGet: (scope: string, occurrence: number, fn: () => Promise) => { + getHook = { scope, remaining: occurrence, fn }; + }, + graphListCallCount: () => + calls.filter( + (call) => + call.operation === "list" && + (call.scope === KV.graphNodes || call.scope === KV.graphEdges), + ).length, + getKeys: (scope: string) => + calls + .filter((call) => call.operation === "get" && call.scope === scope) + .map((call) => call.key!), + }; +} + +function mockSdk() { + const functions = new Map(); + return { + registerFunction: ( + idOrOpts: string | { id: string }, + handler: Function, + ) => { + const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id; + functions.set(id, handler); + }, + registerTrigger: () => {}, + trigger: async ( + idOrInput: string | { function_id: string; payload: unknown }, + data?: unknown, + ) => { + const id = + typeof idOrInput === "string" ? idOrInput : idOrInput.function_id; + const payload = typeof idOrInput === "string" ? data : idOrInput.payload; + const fn = functions.get(id); + if (!fn) throw new Error(`No function: ${id}`); + return fn(payload); + }, + }; +} + +const noopProvider = { + name: "noop", + compress: vi.fn().mockResolvedValue(""), + summarize: vi.fn(), +}; + +function makeNode( + id: string, + name: string, + type: GraphNode["type"] = "concept", + obsIds: string[] = ["obs_1"], + properties: Record = {}, +): GraphNode { + return { + id, + type, + name, + properties, + sourceObservationIds: obsIds, + createdAt: "2026-01-01T00:00:00.000Z", + }; +} + +function makeEdge( + id: string, + sourceNodeId: string, + targetNodeId: string, + type: GraphEdge["type"] = "related_to", + weight = 0.8, +): GraphEdge { + return { + id, + type, + sourceNodeId, + targetNodeId, + weight, + sourceObservationIds: ["obs_1"], + createdAt: "2026-01-01T00:00:00.000Z", + tcommit: "2026-01-01T00:00:00.000Z", + isLatest: true, + }; +} + +function fixtureGraph(): { nodes: GraphNode[]; edges: GraphEdge[] } { + const nodes = [ + makeNode("n1", "React", "library", ["obs_react"]), + makeNode("n2", "Hook", "concept", ["obs_hook"]), + makeNode("n3", "State", "concept", ["obs_state"]), + makeNode("n4", "auth-middleware", "function", ["obs_auth"]), + makeNode("n5", "Lonely", "concept", ["obs_lonely"]), + ]; + const edges = [ + makeEdge("e1", "n1", "n2", "uses", 0.9), + makeEdge("e2", "n2", "n3", "related_to", 0.8), + makeEdge("e3", "n1", "n3", "related_to", 0.15), + makeEdge("e4", "n4", "n1", "uses", 0.7), + ]; + return { nodes, edges }; +} + +async function indexedKV(nodes: GraphNode[], edges: GraphEdge[]) { + const kv = mockKV(); + await initializeGraphIndexes(kv as never); + for (const node of nodes) await kv.set(KV.graphNodes, node.id, node); + for (const edge of edges) await kv.set(KV.graphEdges, edge.id, edge); + await backfillGraphIndexes(kv as never, nodes, edges); + await rebuildGraphSnapshotFromIndexes(kv as never); + kv.clearCalls(); + return kv; +} + +function resultIds(results: Array<{ obsId: string }>): string[] { + return results.map((result) => result.obsId).sort(); +} + +describe("graph index parity and readiness", () => { + it("preserves entity, chunk, and traversal semantics through indexes", async () => { + const { nodes, edges } = fixtureGraph(); + const kv = await indexedKV(nodes, edges); + const retrieval = new GraphRetrieval(kv as never); + + expect(resultIds(await retrieval.searchByEntities(["React"], 3, 20))).toEqual([ + "obs_auth", + "obs_hook", + "obs_react", + "obs_state", + ]); + expect(resultIds(await retrieval.expandFromChunks(["obs_react"], 2, 20))).toEqual([ + "obs_auth", + "obs_hook", + "obs_state", + ]); + expect(await retrieval.searchByEntities(["missing"])).toEqual([]); + + const sdk = mockSdk(); + registerGraphFunction(sdk as never, kv as never, noopProvider as never); + const traversal = (await sdk.trigger("mem::graph-query", { + startNodeId: "n1", + maxDepth: 2, + })) as GraphQueryResult; + expect(traversal.nodes.map((node) => node.id).sort()).toEqual([ + "n1", + "n2", + "n3", + "n4", + ]); + expect(traversal.edges.map((edge) => edge.id).sort()).toEqual([ + "e1", + "e2", + "e3", + "e4", + ]); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("produces the same retrieval from backfill and incremental indexing", async () => { + const { nodes, edges } = fixtureGraph(); + const incremental = await indexedKV(nodes, edges); + const backfilled = mockKV(); + await initializeGraphIndexes(backfilled as never); + for (const node of nodes) await backfilled.set(KV.graphNodes, node.id, node); + for (const edge of edges) await backfilled.set(KV.graphEdges, edge.id, edge); + await backfillGraphIndexes(backfilled as never, nodes, edges); + + const viaIncremental = await new GraphRetrieval(incremental as never) + .searchByEntities(["React"], 2, 20); + const viaBackfill = await new GraphRetrieval(backfilled as never) + .searchByEntities(["React"], 2, 20); + expect(viaBackfill).toEqual(viaIncremental); + }); + + it("preserves temporal partitioning through indexed reads", async () => { + const nodes = [makeNode("n1", "Alice", "person")]; + const edges = [ + makeEdge("e1", "n1", "n1", "located_in" as never, 0.9), + { + ...makeEdge("e2", "n1", "n1", "located_in" as never, 0.9), + tcommit: "2026-02-01T00:00:00.000Z", + tvalid: "2026-02-01", + }, + ]; + const retrieval = new GraphRetrieval((await indexedKV(nodes, edges)) as never); + + const current = await retrieval.temporalQuery("Alice"); + expect(current.currentState.map((edge) => edge.id)).toEqual(["e2"]); + expect(current.history.map((edge) => edge.id)).toEqual(["e1"]); + const historical = await retrieval.temporalQuery( + "Alice", + "2026-01-15T00:00:00.000Z", + ); + expect(historical.currentState.map((edge) => edge.id)).toEqual(["e1"]); + }); + + it("filters catalog names before fetching nodes and bounds properties to the snapshot", async () => { + const nodes = [ + makeNode("n1", "payments-service", "project", ["obs_1"], { lang: "rust" }), + makeNode("n2", "billing", "concept", ["obs_2"], { note: "uses payments" }), + makeNode("n3", "frontend", "project", ["obs_3"]), + ]; + const kv = await indexedKV(nodes, [makeEdge("e1", "n1", "n2")]); + const sdk = mockSdk(); + registerGraphFunction(sdk as never, kv as never, noopProvider as never); + + const result = (await sdk.trigger("mem::graph-query", { + query: "payments", + })) as GraphQueryResult; + + expect(result.nodes.map((node) => node.id).sort()).toEqual(["n1", "n2"]); + expect(result.warning).toBeUndefined(); + expect(kv.getKeys(KV.graphNodes)).toEqual(["n1", "n2"]); + }); + + it("keeps a missing legacy snapshot unavailable without listing graph scopes", async () => { + const kv = mockKV([makeNode("legacy", "Legacy")]); + const readiness = await initializeGraphIndexes(kv as never); + + expect(readiness.status).toBe("unavailable"); + expect(readiness.ready).toBe(false); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("does not trust an under-counted legacy snapshot or list graph scopes", async () => { + const kv = mockKV([makeNode("legacy", "Legacy")]); + await kv.set(KV.graphSnapshot, "current", { + version: 1, + topNodes: [], + topEdges: [], + topDegrees: {}, + stats: { totalNodes: 0, totalEdges: 0, nodesByType: {}, edgesByType: {} }, + updatedAt: "2026-01-01T00:00:00.000Z", + dirty: false, + }); + + expect((await initializeGraphIndexes(kv as never)).status).toBe("unavailable"); + expect(await graphIndexesReady(kv as never)).toBe(false); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("proves an empty store ready through list_groups without graph enumeration", async () => { + const kv = mockKV(); + const readiness = await initializeGraphIndexes(kv as never); + + expect(readiness.ready).toBe(true); + expect(readiness.generation).toBeTruthy(); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("propagates transient readiness reads without replacing healthy metadata", async () => { + const kv = mockKV(); + const original = await initializeGraphIndexes(kv as never); + kv.failNextGet(KV.graphIndexMeta); + + await expect(initializeGraphIndexes(kv as never)).rejects.toThrow( + /injected/, + ); + const current = await graphIndexReadiness(kv as never); + expect(current).toMatchObject({ + ready: true, + generation: original.generation, + }); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("fails closed when list_groups returns a malformed response", async () => { + const sdk = { trigger: vi.fn().mockResolvedValue(null) }; + const kv = new StateKV(sdk as never); + + await expect(kv.listGroups()).rejects.toThrow(/invalid response/); + }); + + it("fails every unavailable read path closed without graph enumeration", async () => { + const kv = mockKV([makeNode("legacy", "Legacy")]); + await initializeGraphIndexes(kv as never); + kv.clearCalls(); + const retrieval = new GraphRetrieval(kv as never); + + expect(await retrieval.searchByEntities(["Legacy"])).toEqual([]); + expect(await retrieval.expandFromChunks(["obs_1"])).toEqual([]); + expect((await retrieval.temporalQuery("Legacy")).entity).toBeNull(); + + const sdk = mockSdk(); + registerGraphFunction(sdk as never, kv as never, noopProvider as never); + registerTemporalGraphFunctions(sdk as never, kv as never, noopProvider as never); + const byName = (await sdk.trigger("mem::graph-query", { + query: "Legacy", + })) as GraphQueryResult; + const byStart = (await sdk.trigger("mem::graph-query", { + startNodeId: "legacy", + })) as GraphQueryResult; + const rebuild = (await sdk.trigger("mem::graph-snapshot-rebuild", { + force: true, + })) as { success: boolean; indexUnavailable?: boolean }; + const temporal = (await sdk.trigger("mem::temporal-query", { + entityName: "Legacy", + })) as { error?: string }; + const differential = (await sdk.trigger("mem::differential-state", { + entityName: "Legacy", + })) as { error?: string }; + + expect(byName.indexStatus).toBe("unavailable"); + expect(byStart.indexStatus).toBe("unavailable"); + expect(rebuild).toMatchObject({ success: false, indexUnavailable: true }); + expect(temporal.error).toMatch(/unavailable/i); + expect(differential.error).toMatch(/unavailable/i); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("refuses graph writes before touching an unavailable legacy corpus", async () => { + const kv = mockKV([makeNode("legacy", "Legacy")]); + const incoming = makeNode("new", "New"); + + await expect( + persistGraphDelta(kv as never, [incoming], [], []), + ).rejects.toThrow(/legacy graph scopes|generation-matched/i); + expect(await kv.get(KV.graphNodes, incoming.id)).toBeNull(); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("invalidates a partially indexed generation and recovers after reset", async () => { + const kv = mockKV(); + await initializeGraphIndexes(kv as never); + const incoming = makeNode("partial", "Partial write"); + kv.failNextSet(KV.graphNameShards); + + await expect( + persistGraphDelta(kv as never, [incoming], [], []), + ).rejects.toThrow(/injected/); + expect(await kv.get(KV.graphNodes, incoming.id)).toEqual(incoming); + expect((await graphIndexReadiness(kv as never)).status).toBe( + "unavailable", + ); + + const sdk = mockSdk(); + registerGraphFunction(sdk as never, kv as never, noopProvider as never); + const unavailable = (await sdk.trigger("mem::graph-query", { + query: incoming.name, + })) as GraphQueryResult; + expect(unavailable.indexStatus).toBe("unavailable"); + expect(kv.graphListCallCount()).toBe(0); + + await sdk.trigger("mem::graph-reset", {}); + await persistGraphDelta(kv as never, [incoming], [], []); + expect((await graphIndexReadiness(kv as never)).ready).toBe(true); + expect( + await new GraphRetrieval(kv as never).searchByEntities([incoming.name]), + ).toHaveLength(1); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("invalidates readiness when a post-primary write fails", async () => { + const kv = mockKV(); + await initializeGraphIndexes(kv as never); + const incoming = makeNode("partial-secondary", "Partial secondary"); + kv.failNextSet(KV.graphNameIndex); + + await expect( + persistGraphDelta(kv as never, [incoming], [], []), + ).rejects.toThrow(/injected/); + expect(await kv.get(KV.graphNodes, incoming.id)).toEqual(incoming); + expect((await graphIndexReadiness(kv as never)).status).toBe( + "unavailable", + ); + }); + + it("invalidates readiness when the final snapshot write fails", async () => { + const kv = mockKV(); + await initializeGraphIndexes(kv as never); + const incoming = makeNode("partial-snapshot", "Partial snapshot"); + kv.failNextSet(KV.graphSnapshot); + + await expect( + persistGraphDelta(kv as never, [incoming], [], []), + ).rejects.toThrow(/injected/); + expect((await graphIndexReadiness(kv as never)).status).toBe( + "unavailable", + ); + }); + + it("graph reset starts a fresh ready generation and hides old hints", async () => { + const legacy = makeNode("legacy", "Legacy"); + const kv = mockKV([legacy]); + const unavailable = await initializeGraphIndexes(kv as never); + await kv.set( + KV.graphNameShards, + `${unavailable.generation}:${nameShardKey(legacy.id)}`, + [{ id: legacy.id, name: legacy.name }], + ); + const sdk = mockSdk(); + registerGraphFunction(sdk as never, kv as never, noopProvider as never); + + await sdk.trigger("mem::graph-reset", {}); + const ready = await graphIndexReadiness(kv as never); + expect(ready.ready).toBe(true); + expect(ready.generation).not.toBe(unavailable.generation); + expect(await loadNameCatalog(kv as never)).toEqual([]); + + const fresh = makeNode("fresh", "Fresh"); + await persistGraphDelta(kv as never, [fresh], [], []); + expect((await loadNameCatalog(kv as never)).map((entry) => entry.name)).toEqual([ + "Fresh", + ]); + expect((await new GraphRetrieval(kv as never).searchByEntities(["Fresh"]))).toHaveLength(1); + const oldWalk = (await sdk.trigger("mem::graph-query", { + startNodeId: legacy.id, + })) as GraphQueryResult; + expect(oldWalk.nodes).toEqual([]); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("updates the name catalog when an existing node is renamed", async () => { + const kv = mockKV(); + await initializeGraphIndexes(kv as never); + const original = makeNode("n1", "Old name"); + await kv.set(KV.graphNodes, original.id, original); + await indexGraphNode(kv as never, original); + const renamed = { ...original, name: "New name" }; + await kv.set(KV.graphNodes, renamed.id, renamed); + await indexGraphNode(kv as never, renamed); + + expect(await loadNameCatalog(kv as never)).toEqual([ + { id: "n1", name: "New name" }, + ]); + }); + + it("does not mix a captured snapshot with a replacement generation", async () => { + const kv = mockKV(); + const oldNode = makeNode( + "same-id", + "stable-name", + "concept", + ["obs_old"], + { tag: "old-only-token" }, + ); + await persistGraphDelta(kv as never, [oldNode], [], []); + const sdk = mockSdk(); + registerGraphFunction(sdk as never, kv as never, noopProvider as never); + kv.clearCalls(); + kv.onGet(KV.graphIndexMeta, 3, async () => { + await sdk.trigger("mem::graph-reset", {}); + await persistGraphDelta( + kv as never, + [{ ...oldNode, properties: { tag: "replacement" } }], + [], + [], + ); + }); + + const result = (await sdk.trigger("mem::graph-query", { + query: "old-only-token", + })) as GraphQueryResult; + + expect(result).toMatchObject({ nodes: [], indexStatus: "unavailable" }); + expect(result.warning).toMatch(/changed|generation/i); + }); + + it("applies incident-edge caps after discarding stale adjacency hints", async () => { + const left = makeNode("left", "Left"); + const middle = makeNode("middle", "Middle"); + const right = makeNode("right", "Right"); + const stale = makeEdge("edge-stale", left.id, middle.id); + const live = makeEdge("edge-live", left.id, right.id); + const kv = await indexedKV([left, middle, right], [stale, live]); + await kv.set(KV.graphEdges, stale.id, { ...stale, stale: true }); + + const reader = await GraphIndexReader.open(kv as never); + expect((await reader!.getIncidentEdges(left.id, 1)).map((edge) => edge.id)) + .toEqual([live.id]); + }); + + it("indexes current heuristic persistence without enumerating graph scopes", async () => { + const kv = mockKV(); + const sdk = mockSdk(); + registerGraphFunction(sdk as never, kv as never, noopProvider as never); + const observation: CompressedObservation = { + id: "obs_heuristic", + sessionId: "ses_1", + timestamp: "2026-08-01T00:00:00.000Z", + type: "file_edit", + title: "Update graph code", + facts: [], + narrative: "Updated graph indexing", + concepts: ["graph indexing"], + files: ["src/functions/graph.ts"], + importance: 8, + }; + + const result = (await sdk.trigger("mem::graph-extract", { + observations: [observation], + })) as { success: boolean }; + const reader = await GraphIndexReader.open(kv as never); + const catalog = await reader!.getNameCatalog(); + const concept = catalog.find((entry) => entry.name === "graph indexing")!; + + expect(result.success).toBe(true); + expect(catalog.map((entry) => entry.name).sort()).toEqual([ + "graph indexing", + "src/functions/graph.ts", + ]); + expect(await reader!.getIncidentEdges(concept.id)).toHaveLength(1); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("remaps Graphify-style edges to merged node IDs and indexes both endpoints", async () => { + const kv = mockKV(); + const existing = makeNode("existing", "React", "library"); + await persistGraphDelta(kv as never, [existing], [], []); + + const duplicate = makeNode("incoming-react", "React", "library"); + const other = makeNode("incoming-hook", "Hook", "concept"); + const edge = makeEdge("incoming-edge", duplicate.id, other.id, "uses"); + await persistGraphDelta(kv as never, [duplicate, other], [edge], []); + + const reader = await GraphIndexReader.open(kv as never); + const incident = await reader!.getIncidentEdges(existing.id); + expect(incident).toHaveLength(1); + expect(incident[0]).toMatchObject({ + sourceNodeId: existing.id, + targetNodeId: other.id, + }); + expect((await loadNameCatalog(kv as never)).map((entry) => entry.id).sort()).toEqual([ + existing.id, + other.id, + ]); + expect(kv.graphListCallCount()).toBe(0); + }); + + it("deduplicates same-key edges created within one fresh batch", async () => { + const kv = mockKV(); + const left = makeNode("left", "Left"); + const right = makeNode("right", "Right"); + const first = makeEdge("edge-first", left.id, right.id); + const second = makeEdge("edge-second", left.id, right.id); + + const result = await persistGraphDelta( + kv as never, + [left, right], + [first, second], + [], + ); + const snapshot = await kv.get(KV.graphSnapshot, "current"); + + expect(result).toEqual({ newNodeCount: 2, newEdgeCount: 1 }); + expect(await kv.get(KV.graphEdges, first.id)).not.toBeNull(); + expect(await kv.get(KV.graphEdges, second.id)).toBeNull(); + expect(snapshot?.stats.totalEdges).toBe(1); + expect(kv.graphListCallCount()).toBe(0); + }); +}); diff --git a/test/graph-retrieval.test.ts b/test/graph-retrieval.test.ts index 2eb3f923be..1165e36a55 100644 --- a/test/graph-retrieval.test.ts +++ b/test/graph-retrieval.test.ts @@ -1,21 +1,25 @@ import { describe, it, expect, beforeEach } from "vitest"; import { GraphRetrieval } from "../src/functions/graph-retrieval.js"; +import { + indexGraphEdge, + indexGraphNode, + initializeGraphIndexes, +} from "../src/state/graph-indexes.js"; +import { KV } from "../src/state/schema.js"; import type { GraphNode, GraphEdge } from "../src/types.js"; -function mockKV( +async function mockKV( nodes: GraphNode[] = [], edges: GraphEdge[] = [], -) { +): Promise<{ + get: (scope: string, key: string) => Promise; + set: (scope: string, key: string, data: T) => Promise; + delete: (scope: string, key: string) => Promise; + list: (scope: string) => Promise; + listGroups: () => Promise; +}> { const store = new Map>(); - const nodesMap = new Map(); - for (const n of nodes) nodesMap.set(n.id, n); - store.set("mem:graph:nodes", nodesMap); - - const edgesMap = new Map(); - for (const e of edges) edgesMap.set(e.id, e); - store.set("mem:graph:edges", edgesMap); - - return { + const kv = { get: async (scope: string, key: string): Promise => { return (store.get(scope)?.get(key) as T) ?? null; }, @@ -31,7 +35,23 @@ function mockKV( const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + listGroups: async (): Promise => { + return Array.from(store.entries()) + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope); + }, }; + + await initializeGraphIndexes(kv as never); + for (const node of nodes) { + await kv.set(KV.graphNodes, node.id, node); + await indexGraphNode(kv as never, node); + } + for (const edge of edges) { + await kv.set(KV.graphEdges, edge.id, edge); + await indexGraphEdge(kv as never, edge); + } + return kv; } function makeNode( @@ -76,7 +96,7 @@ describe("GraphRetrieval", () => { makeNode("n1", "React", "library", ["obs_1"]), makeNode("n2", "Vue", "library", ["obs_2"]), ]; - const kv = mockKV(nodes, []); + const kv = await mockKV(nodes, []); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["React"]); @@ -86,7 +106,7 @@ describe("GraphRetrieval", () => { it("finds entities by partial name match", async () => { const nodes = [makeNode("n1", "auth-middleware", "function", ["obs_1"])]; - const kv = mockKV(nodes, []); + const kv = await mockKV(nodes, []); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["auth"]); @@ -99,7 +119,7 @@ describe("GraphRetrieval", () => { makeNode("n2", "Component", "concept", ["obs_2"]), ]; const edges = [makeEdge("e1", "n1", "n2", "uses")]; - const kv = mockKV(nodes, edges); + const kv = await mockKV(nodes, edges); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["React"], 2); @@ -109,7 +129,7 @@ describe("GraphRetrieval", () => { }); it("returns empty for no matches", async () => { - const kv = mockKV([], []); + const kv = await mockKV([], []); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["nonexistent"]); expect(results).toEqual([]); @@ -121,7 +141,7 @@ describe("GraphRetrieval", () => { makeNode("n2", "jwt", "concept", ["obs_2"]), ]; const edges = [makeEdge("e1", "n1", "n2", "uses")]; - const kv = mockKV(nodes, edges); + const kv = await mockKV(nodes, edges); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.expandFromChunks(["obs_1"]); @@ -131,7 +151,7 @@ describe("GraphRetrieval", () => { it("does not duplicate already-seen observations in expansion", async () => { const nodes = [makeNode("n1", "file.ts", "file", ["obs_1", "obs_2"])]; - const kv = mockKV(nodes, []); + const kv = await mockKV(nodes, []); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.expandFromChunks(["obs_1"]); @@ -149,7 +169,7 @@ describe("GraphRetrieval", () => { isLatest: true, }, ]; - const kv = mockKV(nodes, edges); + const kv = await mockKV(nodes, edges); const retrieval = new GraphRetrieval(kv as never); const result = await retrieval.temporalQuery("Alice"); @@ -159,7 +179,7 @@ describe("GraphRetrieval", () => { }); it("returns null entity for unknown name", async () => { - const kv = mockKV([], []); + const kv = await mockKV([], []); const retrieval = new GraphRetrieval(kv as never); const result = await retrieval.temporalQuery("Unknown"); expect(result.entity).toBeNull(); @@ -175,7 +195,7 @@ describe("GraphRetrieval", () => { makeEdge("e1", "n1", "n2", "uses", 0.9), makeEdge("e2", "n2", "n3", "related_to", 0.8), ]; - const kv = mockKV(nodes, edges); + const kv = await mockKV(nodes, edges); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["React"], 3); @@ -204,7 +224,7 @@ describe("GraphRetrieval", () => { makeEdge("e_strong_a", "n1", "n2", "related_to", 0.9), makeEdge("e_strong_b", "n2", "n3", "related_to", 0.9), ]; - const kv = mockKV(nodes, edges); + const kv = await mockKV(nodes, edges); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["Start"], 3); @@ -224,7 +244,7 @@ describe("GraphRetrieval", () => { makeNode("n3", "Lonely", "concept", ["obs_lonely"]), ]; const edges = [makeEdge("e1", "n1", "n2", "related_to", 0.7)]; - const kv = mockKV(nodes, edges); + const kv = await mockKV(nodes, edges); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["A"], 5); @@ -242,7 +262,7 @@ describe("GraphRetrieval", () => { // floor at 0.01 means traversal completes with a very high cost // rather than throwing or producing Infinity. const edges = [makeEdge("e1", "n1", "n2", "related_to", 0)]; - const kv = mockKV(nodes, edges); + const kv = await mockKV(nodes, edges); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["Anchor"], 2); @@ -264,7 +284,7 @@ describe("GraphRetrieval", () => { makeNode("n2", "Hook", "concept", ["obs_neighbor"]), ]; const edges = [makeEdge("e1", "n1", "n2", "uses", 0.8)]; - const kv = mockKV(nodes, edges); + const kv = await mockKV(nodes, edges); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["React"], 2); @@ -288,7 +308,7 @@ describe("GraphRetrieval", () => { makeEdge("e2", "n2", "n3", "related_to", 0.8), makeEdge("e3", "n3", "n4", "related_to", 0.8), ]; - const kv = mockKV(nodes, edges); + const kv = await mockKV(nodes, edges); const retrieval = new GraphRetrieval(kv as never); const results = await retrieval.searchByEntities(["Start"], 2); diff --git a/test/graph.test.ts b/test/graph.test.ts index aae56da6c0..04cd85b329 100644 --- a/test/graph.test.ts +++ b/test/graph.test.ts @@ -5,6 +5,11 @@ vi.mock("../src/logger.js", () => ({ })); import { registerGraphFunction } from "../src/functions/graph.js"; +import { + backfillGraphIndexes, + initializeGraphIndexes, +} from "../src/state/graph-indexes.js"; +import { KV } from "../src/state/schema.js"; import type { CompressedObservation, GraphNode, @@ -14,6 +19,7 @@ import type { function mockKV() { const store = new Map>(); + const listCalls: string[] = []; return { get: async (scope: string, key: string): Promise => { return (store.get(scope)?.get(key) as T) ?? null; @@ -27,12 +33,34 @@ function mockKV() { store.get(scope)?.delete(key); }, list: async (scope: string): Promise => { + listCalls.push(scope); const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + listGroups: async (): Promise => { + return [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope); + }, + clearListCalls: () => { + listCalls.length = 0; + }, + graphListCallCount: () => { + return listCalls.filter( + (scope) => scope === KV.graphNodes || scope === KV.graphEdges, + ).length; + }, }; } +async function seedGraphIndexes(kv: ReturnType): Promise { + const [nodes, edges] = await Promise.all([ + kv.list(KV.graphNodes), + kv.list(KV.graphEdges), + ]); + await backfillGraphIndexes(kv as never, nodes, edges); +} + function mockSdk() { const functions = new Map(); return { @@ -84,11 +112,12 @@ describe("Graph Functions", () => { let kv: ReturnType; const ORIG_GRAPH_FLAG = process.env["GRAPH_EXTRACTION_ENABLED"]; - beforeEach(() => { + beforeEach(async () => { sdk = mockSdk(); kv = mockKV(); vi.clearAllMocks(); process.env["GRAPH_EXTRACTION_ENABLED"] = "true"; + await initializeGraphIndexes(kv as never); registerGraphFunction(sdk as never, kv as never, mockProvider as never); }); @@ -262,8 +291,7 @@ describe("Graph Functions", () => { await kv.set("mem:graph:edges", edge.id, edge); } - // Post-#814 the empty-body path reads the snapshot exclusively. - // Backfill the snapshot from the seeded data first. + await seedGraphIndexes(kv); await sdk.trigger("mem::graph-snapshot-rebuild", { force: true }); const unbounded = (await sdk.trigger( @@ -296,6 +324,7 @@ describe("Graph Functions", () => { await kv.set("mem:graph:nodes", node.id, node); } + await seedGraphIndexes(kv); await sdk.trigger("mem::graph-snapshot-rebuild", { force: true }); const page1 = (await sdk.trigger("mem::graph-query", { @@ -332,6 +361,7 @@ describe("Graph Functions", () => { }); } + await seedGraphIndexes(kv); await sdk.trigger("mem::graph-snapshot-rebuild", { force: true }); const huge = (await sdk.trigger("mem::graph-query", { @@ -383,6 +413,7 @@ describe("Graph Functions", () => { lastSeen: "2026-01-01T00:00:00Z", }); + await seedGraphIndexes(kv); await sdk.trigger("mem::graph-snapshot-rebuild", { force: true }); const page = (await sdk.trigger("mem::graph-query", { @@ -433,6 +464,7 @@ describe("Graph Functions", () => { stale: false, }); } + await seedGraphIndexes(kv); } it("snapshot-rebuild persists top-degree subgraph + aggregate stats", async () => { @@ -540,19 +572,35 @@ describe("Graph Functions", () => { }); it("graph-stats returns empty envelope + warning when no snapshot exists", async () => { - // Seed nodes but never rebuild the snapshot — simulates a legacy - // corpus on a post-#814 upgrade. - await seed(5, 5); + const legacyKv = mockKV(); + await legacyKv.set(KV.graphNodes, "legacy-node", { + id: "legacy-node", + type: "concept", + name: "legacy", + properties: {}, + sourceObservationIds: [], + createdAt: "2026-01-01T00:00:00Z", + }); + const readiness = await initializeGraphIndexes(legacyKv as never); + const localSdk = mockSdk(); + registerGraphFunction( + localSdk as never, + legacyKv as never, + mockProvider as never, + ); + legacyKv.clearListCalls(); - const stats = (await sdk.trigger("mem::graph-stats", {})) as { + const stats = (await localSdk.trigger("mem::graph-stats", {})) as { totalNodes: number; totalEdges: number; fromSnapshot: boolean; warning?: string; }; + expect(readiness.status).toBe("unavailable"); expect(stats.fromSnapshot).toBe(false); expect(stats.totalNodes).toBe(0); expect(stats.warning).toMatch(/snapshot-rebuild|graph\/reset/); + expect(legacyKv.graphListCallCount()).toBe(0); }); it("graph-reset clears state and writes empty snapshot", async () => { @@ -593,150 +641,77 @@ describe("Graph Functions", () => { }); }); - // CodeRabbit feedback: cover the timeout-budget fallback path and - // the oversized-corpus rebuild refusal. The hot path never enumerates - // any more, but the rebuild endpoint AND the BFS / query branches - // still call kv.list — both need explicit failure-mode tests. - describe("budget + tooLarge guards (#814 v2)", () => { - function slowKV(delayMs: number) { - const base = mockKV(); - return { - ...base, - list: async (scope: string): Promise => { - await new Promise((r) => setTimeout(r, delayMs)); - return base.list(scope); - }, - }; - } - - it("graph-query startNodeId returns warning envelope when enumeration exceeds budget", async () => { - const slow = slowKV(7000); // > LIVE_ENUMERATION_BUDGET_MS (6000ms) - const localSdk = mockSdk(); - registerGraphFunction(localSdk as never, slow as never, mockProvider as never); - - const result = (await localSdk.trigger("mem::graph-query", { - startNodeId: "n_missing", - })) as GraphQueryResult; - - expect(result.warning).toBeTruthy(); - expect(result.warning).toMatch(/budget|enumeration/i); - }, 10000); - - // CodeRabbit raised that slowKV(setTimeout) doesn't simulate a - // blocked event loop. The real production failure is iii rejecting - // the trigger with "Invocation stopped" after the worker dies - // (heartbeat starvation). A rejecting kv.list mock covers that - // catch-path directly without introducing a busy-wait that would - // also starve the budget timer and produce a flaky test. - function rejectingKV() { - const base = mockKV(); - return { - ...base, - list: async (_scope: string): Promise => { - throw new Error("Invocation stopped"); - }, - }; - } - - it("graph-query rejects-from-engine path returns warning envelope (worker-death simulation)", async () => { - const rejector = rejectingKV(); + describe("unavailable index guards", () => { + async function unavailableGraph() { + const localKv = mockKV(); + await localKv.set(KV.graphNodes, "legacy_n", { + id: "legacy_n", + type: "concept", + name: "legacy", + properties: {}, + sourceObservationIds: [], + createdAt: "2026-01-01T00:00:00Z", + stale: false, + }); + const readiness = await initializeGraphIndexes(localKv as never); const localSdk = mockSdk(); registerGraphFunction( localSdk as never, - rejector as never, + localKv as never, mockProvider as never, ); + localKv.clearListCalls(); + return { localKv, localSdk, readiness }; + } - const result = (await localSdk.trigger("mem::graph-query", { - startNodeId: "n_missing", + it("graph-query fails closed without enumerating primary graph scopes", async () => { + const { localKv, localSdk, readiness } = await unavailableGraph(); + + const byName = (await localSdk.trigger("mem::graph-query", { + query: "legacy", + })) as GraphQueryResult; + const byStart = (await localSdk.trigger("mem::graph-query", { + startNodeId: "legacy_n", })) as GraphQueryResult; - expect(result.warning).toBeTruthy(); - expect(result.nodes).toEqual([]); + expect(readiness.status).toBe("unavailable"); + expect(byName).toMatchObject({ nodes: [], indexStatus: "unavailable" }); + expect(byStart).toMatchObject({ nodes: [], indexStatus: "unavailable" }); + expect(byName.warning).toMatch(/unavailable/i); + expect(byStart.warning).toMatch(/unavailable/i); + expect(localKv.graphListCallCount()).toBe(0); }); - it("graph-snapshot-rebuild refuses corpora past REBUILD_SAFE_NODE_CEILING", async () => { - // Direct-poke the mock store with > 25K node values so kv.list - // returns them without paying the per-set cost. Each node only - // needs id/type/name/stale=false for the rebuild path. - const localKv = mockKV(); - // Walk the implementation detail: mockKV stores entries in a - // Map under the scope key. Push directly to that map via the - // public `set` API in a tight loop. - const COUNT = 25001; - const sets: Array> = []; - for (let i = 0; i < COUNT; i++) { - sets.push( - localKv.set("mem:graph:nodes", `bn_${i}`, { - id: `bn_${i}`, - type: "concept", - name: `bulk-${i}`, - properties: {}, - sourceObservationIds: [], - createdAt: "2026-01-01T00:00:00Z", - stale: false, - }), - ); - } - await Promise.all(sets); - - const localSdk = mockSdk(); - registerGraphFunction(localSdk as never, localKv as never, mockProvider as never); + it("graph-snapshot-rebuild refuses unavailable indexes without graph enumeration", async () => { + const { localKv, localSdk } = await unavailableGraph(); const result = (await localSdk.trigger( "mem::graph-snapshot-rebuild", { force: true }, - )) as { success: boolean; tooLarge?: boolean; totalNodes?: number }; - expect(result.success).toBe(false); - expect(result.tooLarge).toBe(true); - expect(result.totalNodes).toBeGreaterThanOrEqual(25001); - }); + )) as { + success: boolean; + indexUnavailable?: boolean; + status?: string; + error?: string; + }; - // #825: new pre-flight refusal when no snapshot exists (signals - // legacy corpus that would crash on kv.list). force=true bypasses. - it("graph-snapshot-rebuild refuses on legacy corpus (no snapshot) without force", async () => { - const localKv = mockKV(); - // Seed nodes but never persist a snapshot → simulates a corpus - // built on a pre-#814 agentmemory. - await localKv.set("mem:graph:nodes", "legacy_n", { - id: "legacy_n", - type: "concept", - name: "legacy", - properties: {}, - sourceObservationIds: [], - createdAt: "2026-01-01T00:00:00Z", - stale: false, + expect(result).toMatchObject({ + success: false, + indexUnavailable: true, + status: "unavailable", }); - const localSdk = mockSdk(); - registerGraphFunction(localSdk as never, localKv as never, mockProvider as never); - - const result = (await localSdk.trigger( - "mem::graph-snapshot-rebuild", - {}, - )) as { success: boolean; legacyCorpus?: boolean; error?: string }; - expect(result.success).toBe(false); - expect(result.legacyCorpus).toBe(true); - expect(result.error).toMatch(/graph\/reset|force/); + expect(result.error).toMatch(/paginated state scanning|graph reset/i); + expect(localKv.graphListCallCount()).toBe(0); }); it("graph-reset is enumeration-free (does not call kv.list)", async () => { - // Wrap the mock kv.list with a counter; assert it stays at 0 - // across a full reset cycle. - const localKv = mockKV(); - let listCalls = 0; - const baseList = localKv.list; - localKv.list = async (scope: string): Promise => { - listCalls += 1; - return baseList.call(localKv, scope) as Promise; - }; - const localSdk = mockSdk(); - registerGraphFunction(localSdk as never, localKv as never, mockProvider as never); + const { localKv, localSdk } = await unavailableGraph(); const result = (await localSdk.trigger("mem::graph-reset", {})) as { success: boolean; }; expect(result.success).toBe(true); - expect(listCalls).toBe(0); + expect(localKv.graphListCallCount()).toBe(0); }); }); }); diff --git a/test/helpers/mocks.ts b/test/helpers/mocks.ts index bc829ed5f6..8e273fac65 100644 --- a/test/helpers/mocks.ts +++ b/test/helpers/mocks.ts @@ -32,6 +32,10 @@ export function mockKV() { const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + listGroups: async (): Promise => + [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope), }; } diff --git a/test/mesh.test.ts b/test/mesh.test.ts index e08db07840..229e5d6ae0 100644 --- a/test/mesh.test.ts +++ b/test/mesh.test.ts @@ -5,6 +5,7 @@ vi.mock("../src/logger.js", () => ({ })); import { registerMeshFunction } from "../src/functions/mesh.js"; +import { initializeGraphIndexes } from "../src/state/graph-indexes.js"; import type { MeshPeer, Memory, @@ -34,6 +35,10 @@ function mockKV() { const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + listGroups: async (): Promise => + [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope), }; } @@ -59,10 +64,11 @@ describe("Mesh Functions", () => { let sdk: ReturnType; let kv: ReturnType; - beforeEach(() => { + beforeEach(async () => { sdk = mockSdk(); kv = mockKV(); vi.clearAllMocks(); + await initializeGraphIndexes(kv as never); registerMeshFunction(sdk as never, kv as never); }); diff --git a/test/reflect.test.ts b/test/reflect.test.ts index 7ea163d593..fcef3fd549 100644 --- a/test/reflect.test.ts +++ b/test/reflect.test.ts @@ -6,6 +6,10 @@ vi.mock("../src/logger.js", () => ({ import { registerReflectFunctions } from "../src/functions/reflect.js"; import type { Insight, GraphNode, GraphEdge, SemanticMemory, Lesson, Crystal } from "../src/types.js"; +import { + backfillGraphIndexes, + initializeGraphIndexes, +} from "../src/state/graph-indexes.js"; function mockKV() { const store = new Map>(); @@ -25,6 +29,10 @@ function mockKV() { const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + listGroups: async (): Promise => + [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope), }; } @@ -126,9 +134,10 @@ describe("Reflect", () => { let kv: ReturnType; let provider: { name: string; compress: ReturnType; summarize: ReturnType }; - beforeEach(() => { + beforeEach(async () => { sdk = mockSdk(); kv = mockKV(); + await initializeGraphIndexes(kv as never); provider = { name: "test", compress: vi.fn(), @@ -154,8 +163,17 @@ describe("Reflect", () => { await kv.set("mem:graph:nodes", "node_security", makeConceptNode("security")); await kv.set("mem:graph:nodes", "node_validation", makeConceptNode("validation")); await kv.set("mem:graph:nodes", "node_testing", makeConceptNode("testing")); - await kv.set("mem:graph:edges", "edge_1", makeEdge("security", "validation")); - await kv.set("mem:graph:edges", "edge_2", makeEdge("security", "testing")); + await kv.set("mem:graph:edges", "edge_security_validation", makeEdge("security", "validation")); + await kv.set("mem:graph:edges", "edge_security_testing", makeEdge("security", "testing")); + await backfillGraphIndexes( + kv as never, + [ + makeConceptNode("security"), + makeConceptNode("validation"), + makeConceptNode("testing"), + ], + [makeEdge("security", "validation"), makeEdge("security", "testing")], + ); await kv.set("mem:semantic", "sem_1", makeSemantic("Always validate security inputs")); await kv.set("mem:semantic", "sem_2", makeSemantic("Testing improves security coverage")); @@ -180,7 +198,12 @@ describe("Reflect", () => { it("skips clusters with fewer than 3 supporting items", async () => { await kv.set("mem:graph:nodes", "node_sparse", makeConceptNode("sparse")); await kv.set("mem:graph:nodes", "node_topic", makeConceptNode("topic")); - await kv.set("mem:graph:edges", "edge_1", makeEdge("sparse", "topic")); + await kv.set("mem:graph:edges", "edge_sparse_topic", makeEdge("sparse", "topic")); + await backfillGraphIndexes( + kv as never, + [makeConceptNode("sparse"), makeConceptNode("topic")], + [makeEdge("sparse", "topic")], + ); await kv.set("mem:semantic", "sem_1", makeSemantic("One sparse fact")); const result = (await sdk.trigger("mem::reflect", {})) as { @@ -196,7 +219,12 @@ describe("Reflect", () => { it("deduplicates insights by fingerprint", async () => { await kv.set("mem:graph:nodes", "node_security", makeConceptNode("security")); await kv.set("mem:graph:nodes", "node_validation", makeConceptNode("validation")); - await kv.set("mem:graph:edges", "edge_1", makeEdge("security", "validation")); + await kv.set("mem:graph:edges", "edge_security_validation", makeEdge("security", "validation")); + await backfillGraphIndexes( + kv as never, + [makeConceptNode("security"), makeConceptNode("validation")], + [makeEdge("security", "validation")], + ); await kv.set("mem:semantic", "sem_1", makeSemantic("Always validate security inputs")); await kv.set("mem:semantic", "sem_2", makeSemantic("Testing improves security coverage")); await kv.set("mem:semantic", "sem_3", makeSemantic("Validation prevents injection")); @@ -238,7 +266,12 @@ describe("Reflect", () => { await kv.set("mem:graph:nodes", "node_a", makeConceptNode("concept_a")); await kv.set("mem:graph:nodes", "node_b", makeConceptNode("concept_b")); - await kv.set("mem:graph:edges", "edge_1", makeEdge("concept_a", "concept_b")); + await kv.set("mem:graph:edges", "edge_concept_a_concept_b", makeEdge("concept_a", "concept_b")); + await backfillGraphIndexes( + kv as never, + [makeConceptNode("concept_a"), makeConceptNode("concept_b")], + [makeEdge("concept_a", "concept_b")], + ); await kv.set("mem:semantic", "sem_1", makeSemantic("fact about concept_a")); await kv.set("mem:semantic", "sem_2", makeSemantic("fact about concept_b")); await kv.set("mem:semantic", "sem_3", makeSemantic("concept_a and concept_b together")); diff --git a/test/snapshot.test.ts b/test/snapshot.test.ts index 6a052cd54c..7cd7e34980 100644 --- a/test/snapshot.test.ts +++ b/test/snapshot.test.ts @@ -53,6 +53,10 @@ function mockKV() { const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + listGroups: async (): Promise => + [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope), }; } @@ -178,7 +182,8 @@ describe("snapshot-create reentrancy guard", () => { let listCalls = 0; const store = new Map>(); const gatedKv = { - get: async () => null, + get: async (scope: string, key: string): Promise => + (store.get(scope)?.get(key) as T) ?? null, set: async (scope: string, key: string, data: T): Promise => { if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); @@ -192,6 +197,10 @@ describe("snapshot-create reentrancy guard", () => { if (listCalls === 1) await firstListGate; return (Array.from(store.get(scope)?.values() ?? []) as T[]) ?? []; }, + listGroups: async (): Promise => + [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope), }; const localSdk = mockSdk(); registerSnapshotFunction(localSdk as never, gatedKv as never, "/tmp/reentrant"); diff --git a/test/temporal-graph.test.ts b/test/temporal-graph.test.ts index 55ef301d17..7d18cd0e50 100644 --- a/test/temporal-graph.test.ts +++ b/test/temporal-graph.test.ts @@ -1,5 +1,11 @@ import { describe, it, expect, vi } from "vitest"; import type { GraphNode, GraphEdge, MemoryProvider } from "../src/types.js"; +import { + backfillGraphIndexes, + initializeGraphIndexes, + resetGraphIndexes, +} from "../src/state/graph-indexes.js"; +import { KV } from "../src/state/schema.js"; vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, @@ -36,9 +42,25 @@ function mockKV( const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; }, + listGroups: async (): Promise => + [...store.entries()] + .filter(([, entries]) => entries.size > 0) + .map(([scope]) => scope), }; } +async function readyKV( + nodes: GraphNode[] = [], + edges: GraphEdge[] = [], +) { + const kv = mockKV(); + await initializeGraphIndexes(kv as never); + for (const node of nodes) await kv.set(KV.graphNodes, node.id, node); + for (const edge of edges) await kv.set(KV.graphEdges, edge.id, edge); + await backfillGraphIndexes(kv as never, nodes, edges); + return kv; +} + function mockSdk() { const functions = new Map(); return { @@ -67,7 +89,7 @@ describe("TemporalGraph", () => { "../src/functions/temporal-graph.js" ); const sdk = mockSdk(); - const kv = mockKV(); + const kv = await readyKV(); const provider: MemoryProvider = { name: "test", compress: vi.fn().mockResolvedValue(""), @@ -109,7 +131,7 @@ describe("TemporalGraph", () => { }; const sdk = mockSdk(); - const kv = mockKV(); + const kv = await readyKV(); registerTemporalGraphFunctions(sdk as never, kv as never, provider); const result = (await sdk.trigger("mem::temporal-graph-extract", { @@ -200,7 +222,7 @@ describe("TemporalGraph", () => { }; const sdk = mockSdk(); - const kv = mockKV([existingNode, existingNode2], [existingEdge]); + const kv = await readyKV([existingNode, existingNode2], [existingEdge]); registerTemporalGraphFunctions(sdk as never, kv as never, provider); const result = (await sdk.trigger("mem::temporal-graph-extract", { @@ -274,7 +296,25 @@ describe("TemporalGraph", () => { }; const sdk = mockSdk(); - const kv = mockKV([node], [edge1, edge2]); + const destinations: GraphNode[] = [ + { + id: "gn_2", + type: "location", + name: "Old city", + properties: {}, + sourceObservationIds: [], + createdAt: "2023-01-01T00:00:00Z", + }, + { + id: "gn_3", + type: "location", + name: "New city", + properties: {}, + sourceObservationIds: [], + createdAt: "2024-06-01T00:00:00Z", + }, + ]; + const kv = await readyKV([node, ...destinations], [edge1, edge2]); const provider: MemoryProvider = { name: "test", compress: vi.fn(), @@ -334,7 +374,25 @@ describe("TemporalGraph", () => { }; const sdk = mockSdk(); - const kv = mockKV([node], [edge1, edge2]); + const destinations: GraphNode[] = [ + { + id: "gn_nyc", + type: "location", + name: "New York", + properties: {}, + sourceObservationIds: [], + createdAt: "2023-01-01T00:00:00Z", + }, + { + id: "gn_london", + type: "location", + name: "London", + properties: {}, + sourceObservationIds: [], + createdAt: "2024-06-01T00:00:00Z", + }, + ]; + const kv = await readyKV([node, ...destinations], [edge1, edge2]); const provider: MemoryProvider = { name: "test", compress: vi.fn(), @@ -352,6 +410,62 @@ describe("TemporalGraph", () => { expect(result.currentEdges[0].targetNodeId).toBe("gn_nyc"); }); + it("does not leak pre-reset history through a re-imported same-id node", async () => { + const { registerTemporalGraphFunctions } = await import( + "../src/functions/temporal-graph.js" + ); + const entity: GraphNode = { + id: "gn_same", + type: "person", + name: "Historical Alice", + properties: {}, + sourceObservationIds: ["obs_old"], + createdAt: "2020-01-01T00:00:00Z", + }; + const target: GraphNode = { + id: "gn_target", + type: "organization", + name: "Old Employer", + properties: {}, + sourceObservationIds: ["obs_old"], + createdAt: "2020-01-01T00:00:00Z", + }; + const kv = await readyKV([entity, target]); + await kv.set(KV.graphEdgeHistory, "ge_old_history", { + id: "ge_old_history", + type: "works_at", + sourceNodeId: entity.id, + targetNodeId: target.id, + weight: 0.9, + sourceObservationIds: ["obs_old"], + createdAt: "2020-01-01T00:00:00Z", + tcommit: "2020-01-01T00:00:00Z", + isLatest: false, + } satisfies GraphEdge); + + await resetGraphIndexes(kv as never); + await backfillGraphIndexes(kv as never, [entity, target], []); + + const sdk = mockSdk(); + const provider: MemoryProvider = { + name: "test", + compress: vi.fn(), + summarize: vi.fn(), + }; + registerTemporalGraphFunctions(sdk as never, kv as never, provider); + const temporal = (await sdk.trigger("mem::temporal-query", { + entityName: entity.name, + includeHistory: true, + })) as any; + const differential = (await sdk.trigger("mem::differential-state", { + entityName: entity.name, + })) as any; + + expect(temporal.historicalEdges).toEqual([]); + expect(temporal.timeline).toEqual([]); + expect(differential.totalChanges).toBe(0); + }); + it("handles empty observations gracefully", async () => { const { registerTemporalGraphFunctions } = await import( "../src/functions/temporal-graph.js"