sentinelayer-cli 0.40.0 → 0.42.0

package/src/session/recall/needle-eval.js

@@ -0,0 +1,279 @@
+/**
+ * ENGRAM §1 — the 8-Needle eval harness (ENGRAM §11) + recall QA (§6 step 9).
+ *
+ * Two complementary axes, both as hard gates:
+ *   - Needle-Chain (DEPTH): plant chains of N memories linked ONLY through
+ *     shared entities; query the head with a paraphrase; success = the TAIL
+ *     memory in the top-20. This tests depth through the graph — the tail is
+ *     lexically disjoint from the head, so it is reachable only by spreading
+ *     activation over the entity graph. Gate: >= 95% chain completion.
+ *   - Needle-Scatter (BREADTH): 8 relevant memories dispersed across the
+ *     corpus; success = the pre-rerank candidate pool contains them. Gate:
+ *     >= 95% present in the pool.
+ * Plus recall@10 >= 0.95 vs exact brute-force ground truth.
+ *
+ * Everything is generated from a seeded PRNG so the harness is byte-
+ * reproducible in CI with the deterministic hash-projection embedder — no
+ * model download, no network.
+ */
+
+import { buildRecallIndex } from "./index-core.js";
+import { createEmbedder } from "./embedder.js";
+import { buildEventObservations } from "./observation-core.js";
+import { recall } from "./retrieve.js";
+
+/** mulberry32 — tiny deterministic PRNG. */
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function next() {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const BASE_TS_MS = Date.UTC(2026, 0, 1, 0, 0, 0);
+const STEP_MS = 60_000; // one minute between events
+
+function tsAt(seq) {
+  return new Date(BASE_TS_MS + seq * STEP_MS).toISOString();
+}
+
+// Opaque, non-stem-sharing random token. Distinct tokens share char n-grams
+// only by rare chance, so the corpus's ONLY intra-chain linkage is the entity
+// graph (never lexical stems) — the faithful Needle-Chain construction.
+const TOKEN_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+function randToken(rand, len = 8) {
+  let out = "";
+  for (let i = 0; i < len; i += 1) out += TOKEN_ALPHABET[Math.floor(rand() * TOKEN_ALPHABET.length)];
+  return out;
+}
+
+function message(seq, agentId, text, topics, eventId) {
+  return {
+    stream: "sl_event",
+    event: "session_message",
+    eventId,
+    agent: { id: agentId },
+    payload: { message: text, topics },
+    ts: tsAt(seq),
+    sequenceId: seq,
+  };
+}
+
+/**
+ * Needle-Chain corpus. Each chain's N memories are linked ONLY through
+ * per-link topic entities (never through shared text). The head carries a
+ * distinctive salted subject; the query paraphrases it. The tail is
+ * lexically disjoint from the head.
+ */
+export function buildChainCorpus({ chains = 150, chainLen = 8, seed = 1 } = {}) {
+  const rand = mulberry32(seed);
+  const events = [];
+  const chainQueries = [];
+  let seq = 1;
+  const agents = ["codex", "claude", "relay", "warden", "atlas"];
+
+  for (let i = 0; i < chains; i += 1) {
+    const headTokenA = randToken(rand);
+    const headTokenB = randToken(rand);
+    // Per-link opaque topic entities — the ONLY thing linking consecutive
+    // memories (never shared text).
+    const linkTokens = [];
+    for (let j = 0; j < chainLen - 1; j += 1) linkTokens.push(`link${randToken(rand)}`);
+    const memberIds = [];
+    for (let j = 0; j < chainLen; j += 1) {
+      const agentId = agents[Math.floor(rand() * agents.length)];
+      const eventId = `c${i}-m${j}`;
+      const topics = [];
+      if (j > 0) topics.push(linkTokens[j - 1]);
+      if (j < chainLen - 1) topics.push(linkTokens[j]);
+      let text;
+      if (j === 0) {
+        text = `${headTokenA} ${headTokenB} ${randToken(rand)}`;
+      } else if (j === chainLen - 1) {
+        text = `${randToken(rand)} ${randToken(rand)} ${randToken(rand)}`;
+      } else {
+        text = `${randToken(rand)} ${randToken(rand)}`;
+      }
+      events.push(message(seq, agentId, text, topics, eventId));
+      memberIds.push(eventId);
+      seq += 1;
+      // Intersperse a distractor so chains are dispersed, not contiguous.
+      if (rand() < 0.5) {
+        events.push(message(seq, agents[Math.floor(rand() * agents.length)], `${randToken(rand)} ${randToken(rand)}`, [], `c${i}-n${j}`));
+        seq += 1;
+      }
+    }
+    // Paraphrase of the head: reordered head tokens + generic verbs that never
+    // appear in the corpus (and are stripped as stopwords anyway).
+    chainQueries.push({
+      chainId: i,
+      query: `recall the ${headTokenB} about ${headTokenA}`,
+      headId: memberIds[0],
+      tailId: memberIds[chainLen - 1],
+      memberIds,
+    });
+  }
+  return { events, chainQueries, lastSeq: seq };
+}
+
+/**
+ * Needle-Scatter corpus. Each query has `relevants` memories that share a
+ * distinctive salted token, dispersed among distractors.
+ */
+export function buildScatterCorpus({ queries = 60, relevants = 8, distractorsPerQuery = 12, seed = 7 } = {}) {
+  const rand = mulberry32(seed);
+  const events = [];
+  const scatterQueries = [];
+  const agents = ["codex", "claude", "relay", "warden", "atlas"];
+  let seq = 1;
+
+  // Build a flat pool of (queryIndex, kind) slots then shuffle for dispersion.
+  const slots = [];
+  for (let q = 0; q < queries; q += 1) {
+    for (let r = 0; r < relevants; r += 1) slots.push({ q, r, relevant: true });
+    for (let d = 0; d < distractorsPerQuery; d += 1) slots.push({ q, d, relevant: false });
+  }
+  // Deterministic Fisher-Yates shuffle.
+  for (let i = slots.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(rand() * (i + 1));
+    [slots[i], slots[j]] = [slots[j], slots[i]];
+  }
+
+  // Opaque per-query subject token (shared by that query's relevants) and a
+  // per-query topic entity; distinct across queries (no stem sharing).
+  const subjectTokens = [];
+  const topicTokens = [];
+  for (let q = 0; q < queries; q += 1) {
+    subjectTokens.push(randToken(rand));
+    topicTokens.push(`topic${randToken(rand)}`);
+  }
+
+  const relevantIdsByQuery = new Map();
+  for (const slot of slots) {
+    const agentId = agents[Math.floor(rand() * agents.length)];
+    if (slot.relevant) {
+      const eventId = `s${slot.q}-r${slot.r}`;
+      events.push(message(seq, agentId, `${subjectTokens[slot.q]} ${randToken(rand)} ${randToken(rand)}`, [topicTokens[slot.q]], eventId));
+      if (!relevantIdsByQuery.has(slot.q)) relevantIdsByQuery.set(slot.q, new Set());
+      relevantIdsByQuery.get(slot.q).add(eventId);
+    } else {
+      events.push(message(seq, agentId, `${randToken(rand)} ${randToken(rand)}`, [], `s${slot.q}-d${slot.d}`));
+    }
+    seq += 1;
+  }
+  for (let q = 0; q < queries; q += 1) {
+    scatterQueries.push({
+      queryIndex: q,
+      query: `what do we know about ${subjectTokens[q]}`,
+      relevantIds: relevantIdsByQuery.get(q) || new Set(),
+    });
+  }
+  return { events, scatterQueries, lastSeq: seq };
+}
+
+export function evaluateChain(index, chainQueries, { k = 20, now } = {}) {
+  let completed = 0;
+  const misses = [];
+  for (const cq of chainQueries) {
+    const result = recall(index, { query: cq.query, k, now });
+    const ids = new Set(result.results.map((r) => r.observationId));
+    if (ids.has(cq.tailId)) completed += 1;
+    else misses.push(cq.chainId);
+  }
+  const total = chainQueries.length;
+  return { total, completed, rate: total > 0 ? completed / total : 1, misses };
+}
+
+export function evaluateScatter(index, scatterQueries, { now } = {}) {
+  let fractionSum = 0;
+  const misses = [];
+  for (const sq of scatterQueries) {
+    const result = recall(index, { query: sq.query, k: 20, now });
+    const pool = new Set(result.candidatePoolIds);
+    let present = 0;
+    for (const id of sq.relevantIds) if (pool.has(id)) present += 1;
+    const denom = sq.relevantIds.size || 1;
+    fractionSum += present / denom;
+    if (present / denom < 1) misses.push({ q: sq.queryIndex, present, of: denom });
+  }
+  const total = scatterQueries.length;
+  return { total, rate: total > 0 ? fractionSum / total : 1, misses };
+}
+
+export function evaluateRecallAt10(index, scatterQueries, { now } = {}) {
+  let recallSum = 0;
+  for (const sq of scatterQueries) {
+    const result = recall(index, { query: sq.query, k: 10, now });
+    const top10 = result.results.slice(0, 10).map((r) => r.observationId);
+    let hit = 0;
+    for (const id of top10) if (sq.relevantIds.has(id)) hit += 1;
+    const denom = Math.min(10, sq.relevantIds.size || 1);
+    recallSum += hit / denom;
+  }
+  const total = scatterQueries.length;
+  return { total, rate: total > 0 ? recallSum / total : 1 };
+}
+
+/**
+ * Run the full 8-Needle evaluation. Returns metrics + a pass/fail per gate.
+ *
+ * @param {object} [options]
+ * @param {number} [options.chains=150]
+ * @param {number} [options.chainLen=8]
+ * @param {number} [options.scatterQueries=60]
+ * @param {number} [options.relevants=8]
+ * @param {number} [options.seed=1]
+ * @param {object} [options.embedder]
+ * @returns {object}
+ */
+export function runEightNeedle({
+  chains = 150,
+  chainLen = 8,
+  scatterQueries = 60,
+  relevants = 8,
+  distractorsPerQuery = 12,
+  seed = 1,
+  embedder = createEmbedder(),
+  gates = { chain: 0.95, scatter: 0.95, recallAt10: 0.95 },
+} = {}) {
+  const chain = buildChainCorpus({ chains, chainLen, seed });
+  const scatter = buildScatterCorpus({ queries: scatterQueries, relevants, distractorsPerQuery, seed: seed + 100 });
+
+  const chainObservations = buildEventObservations(chain.events, { sessionId: "needle-chain" });
+  const scatterObservations = buildEventObservations(scatter.events, { sessionId: "needle-scatter" });
+  const chainIndex = buildRecallIndex({
+    observations: chainObservations.observations,
+    embedder,
+    sessionId: "needle-chain",
+  });
+  const scatterIndex = buildRecallIndex({
+    observations: scatterObservations.observations,
+    embedder,
+    sessionId: "needle-scatter",
+  });
+
+  // Fixed "now" strictly after every corpus timestamp -> deterministic B(m).
+  const nowMs = BASE_TS_MS + (Math.max(chain.lastSeq, scatter.lastSeq) + 10) * STEP_MS;
+
+  const chainResult = evaluateChain(chainIndex, chain.chainQueries, { k: 20, now: nowMs });
+  const scatterResult = evaluateScatter(scatterIndex, scatter.scatterQueries, { now: nowMs });
+  const recallAt10Result = evaluateRecallAt10(scatterIndex, scatter.scatterQueries, { now: nowMs });
+
+  const pass =
+    chainResult.rate >= gates.chain &&
+    scatterResult.rate >= gates.scatter &&
+    recallAt10Result.rate >= gates.recallAt10;
+
+  return {
+    config: { chains, chainLen, scatterQueries, relevants, distractorsPerQuery, seed, embedder: embedder.name },
+    corpusSizes: { chainEvents: chain.events.length, scatterEvents: scatter.events.length },
+    needleChain: { rate: chainResult.rate, completed: chainResult.completed, total: chainResult.total, gate: gates.chain, pass: chainResult.rate >= gates.chain },
+    needleScatter: { rate: scatterResult.rate, total: scatterResult.total, gate: gates.scatter, pass: scatterResult.rate >= gates.scatter },
+    recallAt10: { rate: recallAt10Result.rate, total: recallAt10Result.total, gate: gates.recallAt10, pass: recallAt10Result.rate >= gates.recallAt10 },
+    pass,
+  };
+}

package/src/session/recall/observation-core.js

@@ -0,0 +1,183 @@
+/**
+ * Pure observation normalization shared by session and detachable ENGRAM
+ * adapters. It deliberately knows nothing about which event types a host
+ * considers control-plane noise.
+ */
+
+import {
+  clipSnippet,
+  contentHash,
+  normalizeString,
+  tokenize,
+} from "./text.js";
+
+const FILE_EXTENSIONS = new Set([
+  "js", "mjs", "cjs", "ts", "tsx", "jsx", "py", "md", "json", "sql", "yml",
+  "yaml", "tf", "go", "rs", "java", "rb", "sh", "toml", "ini", "html", "css",
+  "txt", "lock", "cfg", "env",
+]);
+
+function eventType(event) {
+  return normalizeString(event?.event || event?.type).toLowerCase();
+}
+
+function eventAgentId(event) {
+  return (
+    normalizeString(event?.agent?.id) ||
+    normalizeString(event?.agentId) ||
+    normalizeString(event?.agent_id) ||
+    "unknown"
+  );
+}
+
+function eventTimestamp(event) {
+  return normalizeString(event?.ts || event?.timestamp || event?.time || event?.at);
+}
+
+function toEpochMs(iso) {
+  const ms = Date.parse(normalizeString(iso));
+  return Number.isFinite(ms) ? ms : 0;
+}
+
+function asStringArray(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeString(entry)).filter(Boolean);
+  }
+  const single = normalizeString(value);
+  return single ? [single] : [];
+}
+
+function extractText(event) {
+  const payload =
+    event?.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+      ? event.payload
+      : {};
+  const parts = [];
+  for (const key of [
+    "message", "response", "text", "summary", "note", "title", "alert",
+    "reason", "details", "reasoning", "decision", "content", "body",
+  ]) {
+    const value = normalizeString(payload[key]);
+    if (value) parts.push(value);
+  }
+  for (const key of ["decisions", "highlights", "actionItems", "action_items"]) {
+    if (Array.isArray(payload[key])) {
+      for (const entry of payload[key]) {
+        const value = typeof entry === "string" ? entry : normalizeString(entry?.text || entry?.title);
+        if (value) parts.push(value);
+      }
+    }
+  }
+  for (const key of ["file", "path", "ruleId", "rule_id", "layer", "tool", "name", "code"]) {
+    const value = normalizeString(payload[key]);
+    if (value) parts.push(value);
+  }
+  if (Array.isArray(payload.files)) {
+    for (const file of payload.files) {
+      const value = normalizeString(file);
+      if (value) parts.push(value);
+    }
+  }
+  return parts.join(" · ");
+}
+
+function extractFiles(event, text) {
+  const payload = event?.payload && typeof event.payload === "object" ? event.payload : {};
+  const files = new Set();
+  for (const value of asStringArray(payload.file)) files.add(value);
+  for (const value of asStringArray(payload.files)) files.add(value);
+  for (const value of asStringArray(payload.path)) files.add(value);
+  for (const token of tokenize(text)) {
+    const dot = token.lastIndexOf(".");
+    if (dot > 0 && dot < token.length - 1) {
+      const extension = token.slice(dot + 1);
+      if (FILE_EXTENSIONS.has(extension)) files.add(token);
+    }
+  }
+  return Array.from(files);
+}
+
+function extractPrRefs(text) {
+  const refs = new Set();
+  const pattern = /#(\d{1,6})\b/g;
+  let match;
+  while ((match = pattern.exec(text)) !== null) refs.add(`#${match[1]}`);
+  return Array.from(refs);
+}
+
+function extractMentions(event, text) {
+  const payload = event?.payload && typeof event.payload === "object" ? event.payload : {};
+  const mentions = new Set();
+  for (const value of asStringArray(payload.to)) mentions.add(value.toLowerCase());
+  for (const value of asStringArray(payload.recipient)) mentions.add(value.toLowerCase());
+  for (const value of asStringArray(payload.mentions)) mentions.add(value.toLowerCase());
+  const pattern = /@([a-z0-9][a-z0-9_-]{1,})/gi;
+  let match;
+  while ((match = pattern.exec(text)) !== null) mentions.add(match[1].toLowerCase());
+  return Array.from(mentions);
+}
+
+function replyTargetSequence(event) {
+  const payload = event?.payload && typeof event.payload === "object" ? event.payload : {};
+  const sequence = Number(
+    payload.targetSequenceId ?? payload.target_sequence_id ?? payload.replyTo ?? payload.reply_to ?? 0,
+  );
+  return Number.isFinite(sequence) && sequence > 0 ? Math.floor(sequence) : 0;
+}
+
+function resolveObservationId(event, sessionId, index, kind, agentId, ts, text) {
+  const token = normalizeString(event?.idempotencyToken || event?.idempotency_token);
+  if (token) return token;
+  const eventId = normalizeString(event?.eventId || event?.id);
+  if (eventId) return eventId;
+  const sequence = Number(event?.sequenceId ?? event?.sequence_id);
+  if (Number.isFinite(sequence) && sequence > 0) {
+    return `${sessionId || "s"}:${Math.floor(sequence)}`;
+  }
+  return `h:${contentHash(`${kind}|${agentId}|${ts}|${index}|${text}`)}`;
+}
+
+/** Normalize an already-selected set of events into immutable observations. */
+export function buildEventObservations(events = [], { sessionId = "" } = {}) {
+  const source = Array.isArray(events) ? events : [];
+  const byId = new Map();
+  const observations = [];
+
+  source.forEach((event, index) => {
+    const kind = eventType(event) || "event";
+    const agentId = eventAgentId(event);
+    const ts = eventTimestamp(event);
+    const text = extractText(event);
+    const id = resolveObservationId(event, sessionId, index, kind, agentId, ts, text);
+    if (byId.has(id)) return;
+
+    const sequence = Number(event?.sequenceId ?? event?.sequence_id);
+    const observation = {
+      id,
+      sessionId: normalizeString(event?.sessionId) || sessionId,
+      sequenceId: Number.isFinite(sequence) && sequence > 0 ? Math.floor(sequence) : 0,
+      index,
+      ts,
+      tsMs: toEpochMs(ts),
+      kind,
+      agentId,
+      agentModel: normalizeString(event?.agent?.model || event?.agentModel),
+      text,
+      tokens: tokenize(text),
+      mentions: extractMentions(event, text),
+      files: extractFiles(event, text),
+      prRefs: extractPrRefs(text),
+      replyToSequence: replyTargetSequence(event),
+      snippet: clipSnippet(text),
+      raw: event,
+    };
+    byId.set(id, observation);
+    observations.push(observation);
+  });
+
+  return {
+    observations,
+    droppedControlEvents: 0,
+    materialCount: observations.length,
+  };
+}

package/src/session/recall/observations.js

@@ -0,0 +1,21 @@
+/** SentinelLayer session-event adapter for the pure observation core. */
+
+import { filterSessionMaterialEvents } from "../control-events.js";
+import { buildEventObservations } from "./observation-core.js";
+
+/**
+ * Build immutable observations from raw session events, excluding operational
+ * control rows unless the caller explicitly requests forensic inclusion.
+ */
+export function buildObservations(
+  events = [],
+  { sessionId = "", includeControlEvents = false } = {},
+) {
+  const source = Array.isArray(events) ? events : [];
+  const material = includeControlEvents ? source : filterSessionMaterialEvents(source);
+  const built = buildEventObservations(material, { sessionId });
+  return {
+    ...built,
+    droppedControlEvents: source.length - material.length,
+  };
+}

package/src/session/recall/provenance.js

@@ -0,0 +1,153 @@
+/**
+ * ENGRAM §1 — path evidence (explainability-as-delight, ENGRAM §7).
+ *
+ * For any surfaced memory, reconstruct WHY it surfaced as a one-line path
+ * from a query seed to the memory: "msg #12 (codex) -> topic:gate-policy ->
+ * decision:#47 -> pr:#60 -> msg #88". Uses the same bounded bidirectional
+ * BFS (meet-in-the-middle, <=4 hops each side) that §7 specifies for path
+ * evidence. Deterministic tie-breaking so the explanation is reproducible.
+ *
+ * This is a product feature, not debug output (stack doc §2): every recall
+ * hit carries its provenance.
+ */
+
+import { normalizeString } from "./text.js";
+
+function entityLabel(index, entityId) {
+  const entity = index.graph.entities.get(entityId);
+  if (!entity) return entityId;
+  return `${entity.kind}:${entity.label || "?"}`;
+}
+
+function obsLabel(index, obsId) {
+  const obs = index.byId.get(obsId);
+  if (!obs) return obsId;
+  const seq = obs.sequenceId ? `#${obs.sequenceId}` : obs.kind;
+  return `${obs.kind} ${seq} (${obs.agentId})`.trim();
+}
+
+/**
+ * Neighbors of an observation in the recall graph: observations reachable
+ * via one shared entity (bipartite obs->entity->obs) plus direct reply
+ * thread links. Returns entries carrying the connecting entity (for labeling).
+ *
+ * `hubDegreeCap` skips generic hub entities during traversal — a prolific
+ * author (agent entity bound to hundreds of observations) does not make two
+ * messages *relevant* to each other, so it must not carry spreading
+ * activation. This is the deterministic stand-in for §7's `type_prior x
+ * edge weight`: specific entities (files, PRs, topics, decisions, mentions,
+ * reply threads) carry relevance; hubs do not.
+ */
+function observationNeighbors(index, obsId, { hubDegreeCap = Infinity } = {}) {
+  const neighbors = new Map(); // neighborObsId -> via (entityId | "reply")
+  const entityIds = index.graph.obsToEntities.get(obsId);
+  if (entityIds) {
+    for (const entityId of entityIds) {
+      const peers = index.graph.entityToObs.get(entityId);
+      if (!peers) continue;
+      if (peers.size > hubDegreeCap) continue; // skip hub entities
+      for (const peer of peers) {
+        if (peer === obsId) continue;
+        if (!neighbors.has(peer)) neighbors.set(peer, entityId);
+      }
+    }
+  }
+  const replyPeers = index.graph.replyEdges.get(obsId);
+  if (replyPeers) {
+    for (const peer of replyPeers) {
+      if (peer !== obsId && !neighbors.has(peer)) neighbors.set(peer, "reply");
+    }
+  }
+  return neighbors;
+}
+
+/**
+ * Shortest path (BFS) from any seed observation to the target, over the
+ * observation graph, bounded to maxHops. Returns an array of steps or null.
+ * Deterministic: neighbors visited in sorted order.
+ */
+function shortestPath(index, seedObsIds, targetObsId, maxHops, hubDegreeCap) {
+  if (seedObsIds.has(targetObsId)) return [{ obsId: targetObsId, via: null }];
+  const visited = new Set(seedObsIds);
+  let frontier = Array.from(seedObsIds).sort();
+  const prev = new Map(); // obsId -> {from, via}
+
+  for (let hop = 0; hop < maxHops; hop += 1) {
+    const next = [];
+    for (const obsId of frontier) {
+      const neighbors = observationNeighbors(index, obsId, { hubDegreeCap });
+      const sortedNeighbors = Array.from(neighbors.keys()).sort();
+      for (const neighbor of sortedNeighbors) {
+        if (visited.has(neighbor)) continue;
+        visited.add(neighbor);
+        prev.set(neighbor, { from: obsId, via: neighbors.get(neighbor) });
+        if (neighbor === targetObsId) {
+          // Reconstruct.
+          const steps = [];
+          let cursor = targetObsId;
+          while (cursor && !seedObsIds.has(cursor)) {
+            const edge = prev.get(cursor);
+            steps.unshift({ obsId: cursor, via: edge.via });
+            cursor = edge.from;
+          }
+          steps.unshift({ obsId: cursor, via: null });
+          return steps;
+        }
+        next.push(neighbor);
+      }
+    }
+    if (next.length === 0) break;
+    frontier = next.sort();
+  }
+  return null;
+}
+
+/**
+ * Build a one-line provenance string for a result.
+ *
+ * @param {object} index
+ * @param {string} targetObsId
+ * @param {object} seeds  { obsIds: Set<string>, entityIds: string[], channels: string[] }
+ * @param {object} [options]
+ * @param {number} [options.maxHops=4]
+ * @returns {string}
+ */
+export function buildProvenance(index, targetObsId, seeds = {}, { maxHops = 4, hubDegreeCap = Infinity } = {}) {
+  const seedObsIds = seeds.obsIds instanceof Set ? seeds.obsIds : new Set(seeds.obsIds || []);
+
+  // Direct hit: the memory matched the query itself (dense/bm25/entity).
+  if (seedObsIds.has(targetObsId) || seedObsIds.size === 0) {
+    const channels = Array.isArray(seeds.channels) && seeds.channels.length > 0
+      ? seeds.channels.join("+")
+      : "direct";
+    return `direct match (${channels}): ${obsLabel(index, targetObsId)}`;
+  }
+
+  const path = shortestPath(index, seedObsIds, targetObsId, maxHops, hubDegreeCap);
+  if (!path || path.length === 0) {
+    // Reachable only via the query-entity seed labels (no obs path) — still
+    // explain via the shared entity if there is one.
+    const targetEntities = index.graph.obsToEntities.get(targetObsId);
+    if (targetEntities) {
+      for (const entityId of Array.from(targetEntities).sort()) {
+        if ((seeds.entityIds || []).includes(entityId)) {
+          return `${entityLabel(index, entityId)} -> ${obsLabel(index, targetObsId)}`;
+        }
+      }
+    }
+    return `related: ${obsLabel(index, targetObsId)}`;
+  }
+
+  const parts = [];
+  path.forEach((step, i) => {
+    if (i > 0 && step.via && step.via !== "reply") {
+      parts.push(entityLabel(index, step.via));
+    } else if (i > 0 && step.via === "reply") {
+      parts.push("reply");
+    }
+    parts.push(obsLabel(index, step.obsId));
+  });
+  return parts.join(" -> ") || `related: ${obsLabel(index, targetObsId)}`;
+}
+
+export { observationNeighbors };