Provenance graph: no builder or query surface for labeled multi-edge relations (KnowledgeRelation)

[drewstone]

Consumer story

discovery-lab built a queryable provenance graph over its run stores (tools/provenance.mjs): nodes are runs, workers, claims, profiles, models, tasks, register results; edges are labeled relations such as branched-from, executed-with, graded-as, cites-evidence, supersedes, authored-by. The lab wanted to adopt agent-knowledge's graph surface and could not. It aligned its edge shape with KnowledgeRelation ({sourceId, targetId, predicate, metadata}) but had to hand-roll the builder and every query.

What was read (7.2.4, published package + origin/main source)

• src/graph.ts: the entire public surface is buildKnowledgeGraph(pages: KnowledgePage[]): KnowledgeGraph. It is hardcoded to wikilink + shared-source page linking. It cannot express caller-defined predicates.
• KnowledgeGraphEdge has no label, no metadata, no id; edges are keyed ${source}->${target}, so one edge per ordered node pair — run-2 --branched-from--> run-1 and run-2 --supersedes--> run-1 collapse into one edge with merged reasons.
• KnowledgeGraphNode has no kind field and no metadata bag; KnowledgeGraphNodeSchema/KnowledgeGraphEdgeSchema are non-passthrough Zod objects, so custom fields are stripped on persistence.
• The shared-source pass is implicit and O(n^2): any two pages sharing a sourceId gain an edge. On provenance data, where many nodes legitimately share a model or source id, this manufactures a dense edge set the caller did not ask for.
• KnowledgeRelation ({sourceId, targetId, predicate: string, weight?, metadata?}) is the one shape in the package with an arbitrary predicate, but nothing builds a graph from KnowledgeRelation[] and nothing queries one (no exported neighbors, paths, or reachability; viz/ BFS helpers are private).

Required change

1. A builder from KnowledgeRelation[] (plus caller-supplied nodes with a kind and metadata) into a graph that preserves one edge per (source, target, predicate).
2. A minimal query surface over that graph: neighbors by predicate, ancestor/descendant walk over a predicate, reachability.
3. Schemas that preserve caller metadata (passthrough or explicit metadata fields) so a persisted graph round-trips.

What this deletes downstream

discovery-lab's local edge/builder/query code in tools/provenance.mjs (~150 lines) becomes an adapter over the upstream builder; the lab keeps only its store loaders. Recorded in discovery docs/15-adoption-decisions.md.