@visual-z/xeno 0.1.0

package/src/core/handoff.ts

@@ -0,0 +1,397 @@
+/**
+ * Handoff: the structured projection that carries a segment's durable state into
+ * the next one. Generated deterministically from the log with zero LLM calls
+ * (decisions D2, D3).
+ *
+ * The field set borrows names from the closed MCP SEP #2683 proposal
+ * (handoff_version, completed, decisions, pitfalls) for future interop. That
+ * proposal states no types, no required fields and no invariants, so everything
+ * below is this project's own -- in particular the invariants in
+ * validateHandoff(), which are the part that actually does work.
+ *
+ * The contract is enforced here rather than in the prompt because the harness is
+ * the only layer that sees prompt assembly, tool mediation and lifecycle events
+ * at once -- the placement argument from ClawVM (arXiv:2604.10352).
+ */
+
+import type { LineRange, Sha256, NodeRef, IsoTime, EvidenceQuery, EventId } from "./events.ts";
+import type { ProgressEvidence } from "./progress.ts";
+import { isExecutionOutcome, type ExecutionOutcome } from "./outcome.ts";
+import type { WorkItem } from "./work-state.ts";
+import type { EvidenceLink } from "./evidence-links.ts";
+import { emitYaml } from "./yaml.ts";
+
+export const HANDOFF_VERSION = 1 as const;
+
+/** Resolved proof that a completion claim is real: a log event that exited zero. */
+export type Evidence = {
+  /** Configured gate name, when the backing command had one. */
+  gate?: string;
+  command: string;
+  exit: number;
+  at: IsoTime;
+  /** Id of the backing tool_result event, so the claim is traceable to the log. */
+  event_id: string;
+  /** Exact observed workspace after the command; absence means legacy/unknown. */
+  workspace_sha256?: string;
+}
+
+export type CompletedItem = {
+  what: string;
+  work_id?: string;
+  /** The proof as it stood when the claim was made. */
+  evidence: Evidence;
+  evidence_stale?: true;
+  /**
+   * Set when the gate this item cited is failing as of the latest run.
+   *
+   * The item stays in `completed` because it really did pass when claimed, and
+   * deleting that record would throw away something true. But a reader scanning
+   * `completed` would otherwise have to cross-reference `verification` to notice
+   * the suite is now red, so the signal is repeated inline where it is read.
+   */
+  evidence_superseded?: { gate: string; status: "fail"; exit?: number; at?: IsoTime };
+}
+
+/**
+ * A claim whose evidence did not resolve. Kept visible on purpose: a skipped or
+ * failed check must never read as a pass, and silently dropping the claim would
+ * hide exactly the information a reviewer needs.
+ */
+export type UnverifiedClaim = {
+  what: string;
+  claimed: EvidenceQuery;
+  reason: "no_matching_event" | "nonzero_exit" | "stale_workspace";
+  /** Present when a matching event existed but failed. */
+  exit?: number;
+}
+
+export type InFlightItem = {
+  work_id?: string;
+  what: string;
+  next_action: string;
+}
+
+export type BlockedItem = {
+  work_id?: string;
+  what: string;
+  reason: string;
+}
+
+export type DecisionItem = {
+  chose: string;
+  because: string;
+  rejected?: readonly string[];
+}
+
+export type PitfallItem = {
+  tried: string;
+  failed_because: string;
+}
+
+export type FileAnchor = {
+  path: string;
+  /** Checked against subsequent workspace snapshots; true marks a mismatch. */
+  sha256: Sha256;
+  stale?: true;
+  read_ranges?: readonly LineRange[];
+  touched: readonly ("read" | "edit")[];
+}
+
+/**
+ * A branch this node opened, and what became of it.
+ *
+ * Recorded in the handoff rather than only in the log because the handoff is
+ * the only thing that crosses a boundary: a branch absent from it is a branch
+ * the next context does not know exists.
+ */
+export type BranchRecord = {
+  node: number;
+  /** Event id in this node where the branch was spawned. */
+  spawned_at: EventId;
+  purpose: string;
+  /** null means unresolved, which D16 requires be visible rather than quiet. */
+  resolution: "merged" | "discarded" | null;
+  /** Present once the branch joined; a path, never the handoff's contents. */
+  handoff_ref?: string;
+  summary?: string;
+  outcome?: ExecutionOutcome;
+};
+
+export type VerificationStatus = "pass" | "fail" | "not_run";
+
+export type VerificationItem = {
+  gate: string;
+  status: VerificationStatus;
+  at?: IsoTime;
+  exit?: number;
+  workspace_sha256?: string;
+  stale?: true;
+}
+
+export type UserTurnRecord = {
+  at: IsoTime;
+  text: string;
+  /**
+   * Set when a later interrupt event cancelled this turn. Omitted rather
+   * than false: absence means the turn was not abandoned, which is the
+   * common case, and deleting the turn would rewrite history.
+   */
+  abandoned?: true;
+};
+
+export type Handoff = {
+  handoff_version: typeof HANDOFF_VERSION | 2;
+  /** V2 arrays are carried suffixes; the immutable source rebuilds every page. */
+  history?: {
+    source: NodeRef;
+    sections: Record<string, { total: number; offset: number }>;
+  };
+  /**
+   * The node this state was derived FROM.
+   *
+   * There is deliberately no field naming the node it is FOR: a fork makes one
+   * handoff the basis for several children at once, so that question has no
+   * single answer. Identity lives here and nowhere else.
+   */
+  predecessor: NodeRef | null;
+
+  /**
+   * Verbatim from the first user turn of segment 0 that was not later
+   * cancelled. Never rewritten. If every user turn in that segment was
+   * abandoned, this is the last of them (EMPTY_OBJECTIVE forbids blanking it);
+   * the abandoned mark lives on `user_turns`.
+   */
+  objective: string;
+  /**
+   * Every user turn, verbatim, accumulated across segments. Which sentence is a
+   * hard constraint is not derivable, and user turns are both the smallest and
+   * highest-value content in a session -- so all of them are kept rather than
+   * asking the model to label some of them.
+   */
+  user_turns: readonly UserTurnRecord[];
+  /** Set only when the cap dropped turns; names the log refs that still hold them. */
+  user_turns_truncated?: { dropped: number; recover_from: readonly string[] };
+
+  state: {
+    /** O.2: canonical identified work; legacy lists below are compatible projections. */
+    work_items?: readonly WorkItem[];
+    completed: readonly CompletedItem[];
+    unverified_claims: readonly UnverifiedClaim[];
+    in_flight: readonly InFlightItem[];
+    blocked: readonly BlockedItem[];
+    /** Derived from the log, so always present even when the model annotated nothing. */
+    last_activity: string | null;
+  };
+
+  decisions: readonly DecisionItem[];
+  pitfalls: readonly PitfallItem[];
+  file_anchors: readonly FileAnchor[];
+  verification: readonly VerificationItem[];
+  /** Branches opened from this node, resolved or not. */
+  branches: readonly BranchRecord[];
+  open_questions: readonly string[];
+  /** D9 exact novelty ledger. Absence is legacy; rebuild it from original events. */
+  progress_evidence?: readonly ProgressEvidence[];
+  /** O.6: original evidence references and replacement relationships, never inline history. */
+  evidence_links?: readonly EvidenceLink[];
+
+  /**
+   * True only when work remains AND some in-flight item has a concrete next
+   * action. Blocked-with-no-next-action is therefore invalid by construction,
+   * which is the correct reading: a human has to look at it.
+   */
+  continuation_valid: boolean;
+
+  budget: {
+    /** Length of the path from the root to this node, inclusive. */
+    nodes_on_path: number;
+    /** Consecutive nodes along this path with no verifiable progress (D9). */
+    nodes_without_progress: number;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// YAML field order: schema-defined, not alphabetical, so the file reads top-down
+// the way a person would want to read it (decision D10).
+// ---------------------------------------------------------------------------
+
+const ORDER: Record<string, readonly string[]> = {
+  "": [
+    "handoff_version", "predecessor", "history",
+    "objective", "user_turns", "user_turns_truncated",
+    "state", "decisions", "pitfalls", "file_anchors",
+    "verification", "branches", "open_questions", "progress_evidence", "evidence_links",
+    "continuation_valid", "budget",
+  ],
+  predecessor: ["node", "log_ref", "sha256"],
+  user_turns: ["at", "text", "abandoned"],
+  user_turns_truncated: ["dropped", "recover_from"],
+  state: ["completed", "unverified_claims", "in_flight", "blocked", "last_activity", "work_items"],
+  "state.completed": ["work_id", "what", "evidence", "evidence_superseded"],
+  "state.completed.evidence_superseded": ["gate", "status", "exit", "at"],
+  "state.completed.evidence": ["gate", "command", "exit", "at", "event_id"],
+  "state.unverified_claims": ["what", "claimed", "reason", "exit"],
+  "state.in_flight": ["work_id", "what", "next_action"],
+  "state.blocked": ["work_id", "what", "reason"],
+  "state.work_items": ["id", "what", "status", "verification", "opened_at", "updated_at", "next_action", "reason", "evidence", "previous_evidence"],
+  decisions: ["chose", "because", "rejected"],
+  pitfalls: ["tried", "failed_because"],
+  file_anchors: ["path", "sha256", "read_ranges", "touched"],
+  verification: ["gate", "status", "at", "exit"],
+  branches: ["node", "spawned_at", "purpose", "resolution", "handoff_ref", "summary", "outcome"],
+  "branches.outcome": ["status", "reason"],
+  evidence_links: ["id", "work", "what", "event", "resource", "version", "freshness", "superseded_by"],
+  budget: ["nodes_on_path", "nodes_without_progress"],
+};
+
+/** Key-order resolver for emitYaml(). Array indices are transparent to the path. */
+export function handoffKeyOrder(path: readonly string[]): readonly string[] | undefined {
+  return ORDER[path.join(".")];
+}
+
+/**
+ * The one way to serialize a handoff.
+ *
+ * Callers cannot forget the key order and silently get alphabetical output. The
+ * types above are declared as type aliases rather than interfaces so they carry
+ * an implicit index signature and satisfy YamlValue directly -- no cast.
+ */
+export function emitHandoff(h: Handoff): string {
+  return emitYaml(h, { keyOrder: handoffKeyOrder });
+}
+
+// ---------------------------------------------------------------------------
+// Invariants
+// ---------------------------------------------------------------------------
+
+export type Violation = {
+  code:
+    | "COMPLETED_WITHOUT_PASSING_EVIDENCE"
+    | "PASS_WITHOUT_ZERO_EXIT"
+    | "ANCHOR_WITHOUT_SHA"
+    | "EMPTY_OBJECTIVE"
+    | "PREDECESSOR_MISSING"
+    | "PREDECESSOR_WITHOUT_SHA"
+    | "EMPTY_PATH"
+    | "CONTINUATION_WITHOUT_NEXT_ACTION"
+    | "INVALID_HISTORY"
+    | "INVALID_EXECUTION_OUTCOME"
+    | "INVALID_WORK_STATE"
+    | "INVALID_EVIDENCE_LINK"
+    | "BAD_VERSION";
+  detail: string;
+}
+
+/**
+ * The enforceable contract. Every rule here exists because some real harness got
+ * it wrong: "migration applied successfully" with a nonzero exit code nobody
+ * read; a skipped check reported as a pass; a stale file snapshot presented as
+ * current state.
+ */
+export function validateHandoff(h: Handoff): Violation[] {
+  const v: Violation[] = [];
+  for (const link of h.evidence_links ?? []) if (!link.id || !link.work || !link.event ||
+      !["current", "stale", "unknown"].includes(link.freshness) || (link.freshness !== "unknown" && !link.version)) {
+    v.push({ code: "INVALID_EVIDENCE_LINK", detail: `invalid evidence reference ${link.id}` });
+  }
+  const workIds = new Set<string>();
+  for (const item of h.state.work_items ?? []) {
+    const proven = item.verification === "verified" || item.verification === "stale";
+    if (!item.id.trim() || workIds.has(item.id) || !item.what.trim() || !item.opened_at || !item.updated_at ||
+        !["active", "blocked", "completed", "cancelled"].includes(item.status) ||
+        !["not_run", "verified", "unverified", "stale"].includes(item.verification) ||
+        (item.status === "active" && !item.next_action?.trim()) ||
+        (item.status === "completed" && !proven) ||
+        (proven && (!item.evidence || item.evidence.exit !== 0)) ||
+        (!proven && item.evidence !== undefined)) {
+      v.push({ code: "INVALID_WORK_STATE", detail: `invalid identity, lifecycle or evidence for work ${item.id}` });
+    }
+    workIds.add(item.id);
+  }
+  for (const branch of h.branches) {
+    if (branch.outcome !== undefined && !isExecutionOutcome(branch.outcome)) {
+      v.push({ code: "INVALID_EXECUTION_OUTCOME", detail: `branch ${branch.node} has an invalid execution outcome` });
+    }
+  }
+
+  if (h.handoff_version !== HANDOFF_VERSION && h.handoff_version !== 2) {
+    v.push({ code: "BAD_VERSION", detail: `expected ${HANDOFF_VERSION}, got ${h.handoff_version}` });
+  }
+  if (h.handoff_version === 2) {
+    const history = h.history;
+    if (!history || !h.predecessor || history.source.node !== h.predecessor.node ||
+        history.source.sha256 !== h.predecessor.sha256) {
+      v.push({ code: "INVALID_HISTORY", detail: "paged handoff must identify its immutable predecessor" });
+    } else for (const [section, range] of Object.entries(history.sections)) {
+      const values = section.startsWith("state.") ? h.state[section.slice(6) as keyof Handoff["state"]]
+        : h[section as keyof Handoff];
+      if (!Array.isArray(values) || !Number.isSafeInteger(range.total) || !Number.isSafeInteger(range.offset) ||
+          range.offset < 0 || range.total < range.offset || range.total - range.offset !== values.length) {
+        v.push({ code: "INVALID_HISTORY", detail: `invalid carried range for ${section}` });
+      }
+    }
+  }
+
+  for (const c of h.state.completed) {
+    if (c.evidence.exit !== 0) {
+      v.push({
+        code: "COMPLETED_WITHOUT_PASSING_EVIDENCE",
+        detail: `"${c.what}" cites ${c.evidence.command} which exited ${c.evidence.exit}`,
+      });
+    }
+  }
+
+  for (const item of h.verification) {
+    if (item.status === "pass" && item.exit !== 0) {
+      v.push({
+        code: "PASS_WITHOUT_ZERO_EXIT",
+        detail: `gate "${item.gate}" is pass but exit is ${item.exit ?? "absent"}`,
+      });
+    }
+  }
+
+  for (const a of h.file_anchors) {
+    if (!a.sha256) {
+      v.push({ code: "ANCHOR_WITHOUT_SHA", detail: `anchor for ${a.path} has no sha256` });
+    }
+  }
+
+  if (h.objective.trim().length === 0) {
+    v.push({ code: "EMPTY_OBJECTIVE", detail: "objective is empty" });
+  }
+
+  // Every handoff is derived from some node, so a null predecessor means the
+  // state has no provenance -- there is nothing to grep back to.
+  if (h.predecessor === null) {
+    v.push({ code: "PREDECESSOR_MISSING", detail: "handoff has no source node" });
+  } else if (!h.predecessor.sha256) {
+    // Same rule as ANCHOR_WITHOUT_SHA: a reference you cannot check is a
+    // promise, not a pointer (D8). predecessor is the chain's most important
+    // anchor; filling it without a digest is how the empty-string default
+    // survived every call site. node 0 with predecessor === null is a
+    // different case and is already covered above.
+    v.push({
+      code: "PREDECESSOR_WITHOUT_SHA",
+      detail: `predecessor node ${h.predecessor.node} has no sha256`,
+    });
+  }
+
+  // A path always contains at least the node itself.
+  if (h.budget.nodes_on_path < 1) {
+    v.push({
+      code: "EMPTY_PATH",
+      detail: `nodes_on_path is ${h.budget.nodes_on_path}, but a path includes its own node`,
+    });
+  }
+
+  if (h.continuation_valid && !h.state.in_flight.some((i) => i.next_action.trim().length > 0) &&
+      !(h.handoff_version === 2 && (h.history?.sections["state.in_flight"]?.offset ?? 0) > 0)) {
+    v.push({
+      code: "CONTINUATION_WITHOUT_NEXT_ACTION",
+      detail: "continuation_valid is true but no in_flight item has a next_action",
+    });
+  }
+
+  return v;
+}

package/src/core/harness-comparison.ts

@@ -0,0 +1,90 @@
+/** Shared evaluation protocol, not a production context policy (research N.10). */
+import { shuffled } from "./experiment.ts";
+import { canReserve, type BenchmarkUsage } from "./benchmark.ts";
+
+export const COMPARISON_ARMS = ["xeno-windowed", "xeno-continuous", "pi"] as const;
+export type ComparisonArm = typeof COMPARISON_ARMS[number];
+export interface ComparisonJob { id: string; arm: ComparisonArm }
+
+/** Null means an explicit provider-balance authorization, never zero allowance. */
+export function comparisonCanReserve(charged: number, reservation: number, budget: number | null): boolean {
+  if (![charged, reservation, charged + reservation].every(Number.isFinite) || charged < 0 || reservation <= 0) return false;
+  return budget === null || canReserve(charged, reservation, budget);
+}
+
+/** DeepSeek documents 402 as insufficient balance; other errors need their own diagnosis. */
+export function comparisonFailureKind(status: number | null): "balance" | "provider" {
+  return status === 402 ? "balance" : "provider";
+}
+
+export function comparisonSchedule(ids: readonly string[], seed: number): ComparisonJob[] {
+  if (ids.length === 0 || new Set(ids).size !== ids.length) throw new Error("empty or duplicate comparison tasks");
+  const arms = shuffled(COMPARISON_ARMS, seed);
+  return [...ids].sort().flatMap((id, i) => arms.map((_, position) => ({ id, arm: arms[(i + position) % arms.length]! })));
+}
+
+export function jsonObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected JSON object");
+  return value as Record<string, unknown>;
+}
+
+/** Missing cache usage is unknown, never a fabricated zero or a discounted bill. */
+export function comparisonUsage(body: unknown): BenchmarkUsage | null {
+  try {
+    const usage = jsonObject(jsonObject(body)["usage"]);
+    const prompt = usage["prompt_tokens"], output = usage["completion_tokens"];
+    const details = usage["prompt_tokens_details"];
+    const vendorCached = usage["prompt_cache_hit_tokens"];
+    const standardCached = details ? jsonObject(details)["cached_tokens"] : undefined;
+    if (vendorCached !== undefined && standardCached !== undefined && vendorCached !== standardCached) return null;
+    const cached = vendorCached ?? standardCached;
+    if (![prompt, output, cached].every((n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0)) return null;
+    const p = prompt as number, o = output as number, c = cached as number;
+    if (p === 0 || o === 0 || c > p) return null;
+    if (usage["prompt_cache_miss_tokens"] !== undefined && usage["prompt_cache_miss_tokens"] !== p - c) return null;
+    return { input_tokens: p - c, output_tokens: o, cache_read_input_tokens: c, cache_creation_input_tokens: 0 };
+  } catch { return null; }
+}
+
+/** Buffer upstream responses for one billing boundary; do not report this as TTFT. */
+export function completionSse(value: unknown): string {
+  const body = jsonObject(value);
+  const choices = body["choices"];
+  if (!Array.isArray(choices) || choices.length !== 1) throw new Error("expected one completion");
+  const choice = jsonObject(choices[0]), message = jsonObject(choice["message"]);
+  const calls = message["tool_calls"];
+  const finish = choice["finish_reason"];
+  if (typeof finish !== "string" || !["stop", "tool_calls", "length", "content_filter"].includes(finish)) throw new Error("incomplete completion");
+  if (calls !== undefined && !Array.isArray(calls)) throw new Error("invalid tool calls");
+  const delta = { ...message, ...(Array.isArray(calls) ? { tool_calls: calls.map((call: unknown, index: number) => ({ ...jsonObject(call), index })) } : {}) };
+  const common = { id: body["id"], object: "chat.completion.chunk", created: body["created"], model: body["model"] };
+  return [
+    { ...common, choices: [{ index: 0, delta, finish_reason: null }] },
+    { ...common, choices: [{ index: 0, delta: {}, finish_reason: finish }] },
+    { ...common, choices: [], usage: body["usage"] },
+  ].map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`).join("") + "data: [DONE]\n\n";
+}
+
+/** JSONL permits U+2028 in strings. Only LF frames an event, including Pi's output. */
+export function comparisonLines(buffer: string, chunk: string): { buffer: string; values: unknown[] } {
+  const lines = (buffer + chunk).split("\n");
+  const remainder = lines.pop()!;
+  return { buffer: remainder, values: lines.filter((line) => line.trim() !== "").map((line) => JSON.parse(line) as unknown) };
+}
+
+export function comparisonSummary(plan: readonly ComparisonJob[], results: readonly (ComparisonJob & { status: string; correct: boolean })[]) {
+  const keys = new Set(plan.map((job) => `${job.id}/${job.arm}`)), seen = new Set<string>();
+  if (keys.size !== plan.length) throw new Error("duplicate planned comparison job");
+  for (const result of results) {
+    const key = `${result.id}/${result.arm}`;
+    if (!keys.has(key) || seen.has(key) || (result.correct && result.status !== "answered")) throw new Error("invalid comparison outcome");
+    seen.add(key);
+  }
+  return COMPARISON_ARMS.map((arm) => {
+    const planned = plan.filter((job) => job.arm === arm).length, rows = results.filter((row) => row.arm === arm);
+    const correct = rows.filter((row) => row.correct).length;
+    return { arm, planned, attempted: rows.length, answered: rows.filter((row) => row.status === "answered").length,
+      correct, missing: planned - rows.length, accuracy: rows.length ? correct / rows.length : null,
+      complete: rows.length === planned };
+  }).filter((row) => row.planned > 0);
+}

package/src/core/history-query.ts

@@ -0,0 +1,103 @@
+/** N.2: searchable views retain provenance; they can always be rebuilt from the log. */
+import type { LogEvent, ToolResultEvent } from "./events.ts";
+import { canonicalValue } from "./continuation.ts";
+import { deriveEvidenceLinks, observationResources, resourceKey, type EvidenceLink } from "./evidence-links.ts";
+
+export interface HistoryEntry extends Pick<ToolResultEvent, "effect" | "outcome" | "data" | "diagnostic"> {
+  node: number;
+  event: string;
+  kind: string;
+  text: string;
+  tool?: string;
+  input?: unknown;
+  ok?: boolean;
+  artifact?: string;
+  resources?: readonly string[];
+  work_ids?: readonly string[];
+  evidence?: readonly EvidenceLink[];
+  source_available?: boolean;
+}
+
+export function historyEntries(nodes: readonly { node: number; events: readonly LogEvent[] }[]): HistoryEntry[] {
+  const entries: HistoryEntry[] = [];
+  const calls = new Map<string, { name: string; input: unknown }>();
+  for (const { node, events } of nodes) for (const e of events) {
+    if (e.t === "assistant") {
+      for (const block of e.blocks) if (block.type === "tool_use") calls.set(block.call_id, { name: block.name, input: block.input });
+      const text = e.blocks.filter((b) => b.type === "text").map((b) => b.text).join("\n");
+      if (text) entries.push({ node, event: e.id, kind: e.t, text });
+    } else if (e.t === "tool_result") {
+      const call = calls.get(e.call_id);
+      // Indexing query results recursively would make the index amplify itself.
+      if (call?.name === "history" || call?.name === "note") continue;
+      entries.push({ node, event: e.id, kind: e.t, text: e.content, ok: e.ok,
+        ...(call ? { tool: call.name, input: call.input } : {}),
+        resources: observationResources(e, call?.input),
+        ...(e.effect ? { effect: e.effect } : {}), ...(e.outcome ? { outcome: e.outcome } : {}),
+        ...(e.data !== undefined ? { data: e.data } : {}), ...(e.diagnostic ? { diagnostic: e.diagnostic } : {}),
+        ...(e.content_ref ? { artifact: e.content_ref.sha256 } : {}) });
+    } else if (["user", "next_action", "decision", "pitfall", "blocked", "question", "claim", "work_status", "evidence_link"].includes(e.t)) {
+      entries.push({ node, event: e.id, kind: e.t, text: e.t === "user" ? e.text : canonicalValue(e),
+        ...("work_id" in e && e.work_id ? { work_ids: [e.work_id] } : {}),
+        ...(e.t === "evidence_link" ? { work_ids: [e.work], ...(e.resource ? { resources: [resourceKey(e.resource)] } : {}) } : {}) });
+    }
+  }
+  const lookup = new Map(entries.map(entry => [entry.event, entry]));
+  for (const link of deriveEvidenceLinks([], nodes.flatMap(node => [...node.events]))) {
+    const source = lookup.get(link.event);
+    const annotation = lookup.get(link.id);
+    if (annotation) { annotation.source_available = source !== undefined; annotation.evidence = [link]; }
+    if (source) {
+      source.work_ids = [...new Set([...(source.work_ids ?? []), link.work])];
+      source.evidence = [...(source.evidence ?? []), link];
+    }
+  }
+  return entries;
+}
+
+export function historyIndex(entries: readonly HistoryEntry[]): {
+  byEvent: ReadonlyMap<string, HistoryEntry>; byResource: ReadonlyMap<string, readonly HistoryEntry[]>; byWork: ReadonlyMap<string, readonly HistoryEntry[]>;
+} {
+  const byResource = new Map<string, HistoryEntry[]>(), byWork = new Map<string, HistoryEntry[]>();
+  const add = (index: Map<string, HistoryEntry[]>, key: string, entry: HistoryEntry): void => {
+    const items = index.get(key);
+    if (items) items.push(entry); else index.set(key, [entry]);
+  };
+  for (const entry of entries) {
+    for (const resource of entry.resources ?? []) add(byResource, resource, entry);
+    for (const work of entry.work_ids ?? []) add(byWork, work, entry);
+  }
+  return { byEvent: new Map(entries.map(entry => [entry.event, entry])), byResource, byWork };
+}
+
+/** Literal AND search, newest first. No regex execution, hidden ranking, or LLM. */
+export function queryHistory(entries: readonly HistoryEntry[], query: string, tool?: string): HistoryEntry[] {
+  const terms = query.toLowerCase().trim().split(/\s+/).filter(Boolean);
+  return entries.filter((entry) => {
+    if (tool !== undefined && entry.tool !== tool) return false;
+    const text = `${entry.text}\n${canonicalValue(entry.input)}`.toLowerCase();
+    return terms.every((term) => text.includes(term));
+  }).toReversed();
+}
+
+/**
+ * Lines of an entry that contain a query term, so a caller can see the match
+ * without reading back the whole observation. Literal and case-insensitive,
+ * like queryHistory; an index view, never replacement evidence.
+ */
+export function historyHits(text: string, terms: readonly string[], limit = 5, width = 300): { line: number; text: string }[] {
+  const needles = terms.map((term) => term.toLowerCase()).filter(Boolean);
+  if (needles.length === 0 || limit < 1) return [];
+  const hits: { line: number; text: string }[] = [];
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length && hits.length < limit; i++) {
+    const lower = lines[i]!.toLowerCase();
+    if (!needles.some((needle) => lower.includes(needle))) continue;
+    const line = lines[i]!;
+    // Center a long line on its first match so the term survives the cut.
+    const at = Math.min(...needles.map((needle) => lower.indexOf(needle)).filter((index) => index >= 0));
+    const start = line.length <= width ? 0 : Math.max(0, Math.min(at - Math.floor(width / 3), line.length - width));
+    hits.push({ line: i + 1, text: line.slice(start, start + width) });
+  }
+  return hits;
+}