@visual-z/xeno 0.8.4 → 0.9.1

package/src/core/handoff.ts

@@ -1,479 +0,0 @@
-/**
- * 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 type { WorkingSet } from "./working-set.ts";
-import { RECOVERY_SECTIONS, RECOVERY_KINDS } from "./recovery-sources.ts";
-import type { AcceptanceState } from "./acceptance.ts";
-import type { LoadedSkill } from "./skills.ts";
-import type { ProcessObservation } from "./process-state.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;
-  /** P.3: omitted on historical full-workspace observations. */
-  workspace_scope?: "source-v1";
-}
-
-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 = {
-  work_id?: string;
-  source?: { node: number; event_id: string };
-  chose: string;
-  because: string;
-  rejected?: readonly string[];
-}
-
-export type PitfallItem = {
-  work_id?: string;
-  source?: { node: number; event_id: string };
-  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;
-  background?: true;
-  /** 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;
-  receipt_ref?: string;
-  outcome?: ExecutionOutcome;
-};
-
-export type VerificationStatus = "pass" | "fail" | "not_run";
-
-export type VerificationItem = {
-  gate: string;
-  status: VerificationStatus;
-  at?: IsoTime;
-  exit?: number;
-  workspace_sha256?: string;
-  workspace_scope?: "source-v1";
-  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;
-  /**
-   * Working set v3 only: the original user event, present exactly when the turn
-   * carried images, so `history(event=ID)` can reattach them.
-   */
-  event?: EventId;
-  /**
-   * Working set v3 only: references to the turn's attached images (D8: digest
-   * and identity, never bytes). Absent from the full derived state, so legacy
-   * projections and frozen replay are unchanged.
-   */
-  images?: readonly UserTurnImage[];
-};
-
-/** Enough for the model to know an image exists and which one; bytes stay in the blob store. */
-export type UserTurnImage = { sha256: Sha256; name: string; width: number; height: number };
-
-export type Handoff = {
-  handoff_version: typeof HANDOFF_VERSION | 2;
-  working_set?: WorkingSet;
-  acceptance?: AcceptanceState;
-  loaded_skills?: readonly LoadedSkill[];
-  /** O.14: last observations only; live capabilities cannot survive a restart. */
-  processes?: readonly ProcessObservation[];
-  /** 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", "working_set", "user_turns", "user_turns_truncated",
-    "state", "acceptance", "loaded_skills", "processes", "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", "event", "images"],
-  "user_turns.images": ["sha256", "name", "width", "height"],
-  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", "receipt_ref", "background"],
-  processes: ["session", "node", "event", "observed", "command", "exit", "output"],
-  "processes.output": ["sha256", "path", "bytes"],
-  "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"
-    | "INVALID_WORKING_SET"
-    | "INVALID_USER_TURN"
-    | "INVALID_ACCEPTANCE"
-    | "INVALID_SKILL_SOURCE"
-    | "INVALID_PROCESS_STATE"
-    | "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 ?? []) {
-    if (item.depends_on && (new Set(item.depends_on).size !== item.depends_on.length || item.depends_on.includes(item.id) ||
-      item.depends_on.some(dep => !dep.trim())) || item.owner !== undefined && (!item.owner.trim() || !item.owner_event)) {
-      v.push({ code: "INVALID_WORK_STATE", detail: `invalid dependencies or ownership for work ${item.id}` });
-    }
-    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.working_set) {
-    const view = h.working_set;
-    if (![1, 2, 3].includes(view.version) || view.source.node !== h.predecessor?.node || view.source.sha256 !== h.predecessor?.sha256 ||
-        !Number.isSafeInteger(view.omitted.work) || view.omitted.work < 0 || !Number.isSafeInteger(view.omitted.references) || view.omitted.references < 0 ||
-        new Set(view.work.map(item => item.id)).size !== view.work.length || view.work.some(item => !["active", "blocked"].includes(item.status)) ||
-        view.references.some(reference => !reference.event) ||
-        view.version >= 2 && (!view.recovery_sections || RECOVERY_SECTIONS.some(section => {
-          const range = view.recovery_sections![section], references = view.references.filter(ref => ref.kind === RECOVERY_KINDS[section]);
-          return !range || !Number.isSafeInteger(range.total) || !Number.isSafeInteger(range.omitted) || range.omitted < 0 || range.omitted > range.total ||
-            range.total - range.omitted !== references.length || new Set(references.map(ref => ref.event)).size !== references.length ||
-            references.some(ref => !Number.isSafeInteger(ref.node) || Number(ref.node) < 0 || ref.provenance !==
-              (section === "users" ? "user_message" : section === "next_actions" ? "model_annotation" : "observation"));
-        }))) {
-      v.push({ code: "INVALID_WORKING_SET", detail: "working set must reference its source and explicit active state" });
-    }
-  }
-  // D8: an image reference must name its blob and the original event that reattaches it.
-  if (h.user_turns.some(turn => turn.event !== undefined && !turn.images?.length ||
-      turn.images !== undefined && (!turn.event || turn.images.length === 0 || turn.images.some(image => !/^[a-f0-9]{64}$/.test(image.sha256))))) {
-    v.push({ code: "INVALID_USER_TURN", detail: "user turn images need their original event and blob digests" });
-  }
-  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 === "acceptance.criteria" ? h.acceptance?.criteria : section === "acceptance.targets" ? h.acceptance?.targets : 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}` });
-      }
-    }
-  }
-
-  if (h.acceptance?.criteria.some(item => item.status === "pass" && (!item.evidence || item.evidence.exit !== 0) ||
-      item.status === "accepted" && (item.kind !== "human" || !item.accepted_event || item.target && !item.accepted_binding))) {
-    v.push({ code: "INVALID_ACCEPTANCE", detail: "criteria need actual command or user decision evidence" });
-  }
-  if (h.acceptance?.targets?.some(target => target.status === "ready" && (!target.observation || !target.binding || !target.session || !target.pid || !target.entry || !target.build_event))) {
-    v.push({ code: "INVALID_ACCEPTANCE", detail: "ready targets need original build and owned instance observations" });
-  }
-  if (h.loaded_skills?.some(item => !/^[a-f0-9]{64}$/.test(item.sha256) || item.sha256 !== item.artifact ||
-      !item.path || !item.event || !Number.isSafeInteger(item.node) || item.node < 0)) {
-    v.push({ code: "INVALID_SKILL_SOURCE", detail: "loaded skill must reference original instruction bytes and event" });
-  }
-  if (h.processes?.some(item => !Number.isSafeInteger(item.session) || item.session < 1 || !Number.isSafeInteger(item.node) || item.node < 0 ||
-    !item.event || !["running", "exited"].includes(item.observed) || item.observed === "exited" && !Number.isInteger(item.exit) ||
-    item.output && (!/^[a-f0-9]{64}$/.test(item.output.sha256) || !Number.isSafeInteger(item.output.bytes) || item.output.bytes < 0 || !item.output.path))) {
-    v.push({ code: "INVALID_PROCESS_STATE", detail: "process state requires original observation and actual exit evidence" });
-  }
-  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/history-query.ts

@@ -1,139 +0,0 @@
-/** 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";
-import type { EnvironmentValidity } from "./environment.ts";
-
-export interface HistoryEntry extends Pick<ToolResultEvent, "effect" | "outcome" | "data" | "data_ref" | "diagnostic" | "observation" | "warnings"> {
-  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;
-  /** Runtime consumption view only; never changes the original capability receipt. */
-  environment?: EnvironmentValidity;
-  invocation?: { event: string; input: string; schema: string | null; parent_call_id?: string; origin?: "extension" };
-}
-
-/** O.15: bump when historyEntries or freshness semantics change. */
-export const HISTORY_INDEX_VERSION = 6;
-export function historyKeyInput(nodes: readonly { node: number; events: readonly LogEvent[] }[], version = HISTORY_INDEX_VERSION): string {
-  const calls = new Map<string, string>();
-  const self = (name: string | undefined) => name === "history" || name === "note";
-  return canonicalValue({ version, nodes: nodes.map(part => ({ node: part.node, events: part.events.flatMap<LogEvent>(event => {
-    // The index deliberately excludes its own reads. Effects still affect
-    // freshness, and annotations have their own durable events (O.6).
-    if (event.t === "tool_invocation") { calls.set(event.call_id, event.name); return self(event.name) ? [] : [event]; }
-    if (event.t === "tool_result" && self(calls.get(event.call_id)) && event.effect === undefined) return [];
-    if (event.t !== "assistant") return [event];
-    for (const block of event.blocks) if (block.type === "tool_use") calls.set(block.call_id, block.name);
-    const blocks = event.blocks.filter(block => block.type === "text" || block.type === "tool_use" && !self(block.name));
-    return blocks.length ? [{ ...event, blocks }] : [];
-  }) })) });
-}
-
-export function historyEntries(nodes: readonly { node: number; events: readonly LogEvent[] }[]): HistoryEntry[] {
-  const entries: HistoryEntry[] = [];
-  const calls = new Map<string, { name: string; input: unknown }>();
-  const invocations = new Map<string, NonNullable<HistoryEntry["invocation"]>>();
-  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_invocation") {
-      calls.set(e.call_id, { name: e.name, input: e.input ?? calls.get(e.call_id)?.input ?? { artifact: e.input_ref.sha256 } });
-      invocations.set(e.call_id, { event: e.id, input: e.input_ref.sha256, schema: e.schema_ref?.sha256 ?? null,
-        ...(e.origin ? { origin: e.origin } : {}),
-        ...(e.parent_call_id ? { parent_call_id: e.parent_call_id } : {}) });
-    } 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 } : {}),
-        ...(invocations.has(e.call_id) ? { invocation: invocations.get(e.call_id)! } : {}),
-        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.data_ref ? { data_ref: e.data_ref } : {}),
-        ...(e.observation ? { observation: e.observation } : {}),
-        ...(e.warnings ? { warnings: e.warnings } : {}),
-        ...(e.content_ref ? { artifact: e.content_ref.sha256 } : {}) });
-    } else if (e.t === "target_observation") {
-      entries.push({ node, event: e.id, kind: e.t, text: canonicalValue(e.observation),
-        ...(e.observation.manifest ? { artifact: e.observation.manifest.sha256 } : {}) });
-    } else if (e.t === "process_exit") {
-      entries.push({ node, event: e.id, kind: e.t, text: canonicalValue(e), artifact: e.output.sha256 });
-    } else if (["work_owner", "work_dependencies", "approval", "skill_loaded", "acceptance_contract", "acceptance_decision", "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;
-}