feat: fact provenance, merkle roots, and statement history MCP

Add FactProvenance enrichment, SHA-256 Merkle tree, payer policy adapter, and get_statement_history MCP tool.

Author: zz-plant

docs/mcp.md

@@ -82,6 +82,20 @@ Re-observe pages — for scheduled monitoring.
 | `interval` | string | | Lookback window in hours |
 | `api` | string | | MediaWiki API base URL |
 
+### `get_statement_history`
+
+Track the history of a specific statement across revisions. Returns when the statement — or a semantic neighbor — appeared, disappeared, or changed, with revision IDs, timestamps, an overall status, and a short change summary.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `statement` | string | ✅ | Raw text statement to track |
+| `page` | string | ✅ | MediaWiki page title |
+| `context` | string | | Optional use-context slug |
+| `depth` | enum | | `brief`, `detailed` (default), or `forensic` |
+| `api` | string | | MediaWiki API base URL. Defaults to English Wikipedia |
+
+Response fields: `statement`, `page`, `context`, `revisions` (array of `revisionId` + `timestamp`), `status` (`present`, `absent`, `modified`, or `contested`), and `history_summary`.
+
 ## Protocol details
 
 - **Transport:** stdio (stdin for requests, stdout for responses)

packages/analyzers/src/__tests__/semantic-enrichment.test.ts

@@ -0,0 +1,114 @@
+import type { EvidenceEvent } from "@refract-org/evidence-graph";
+import { describe, expect, it } from "vitest";
+import {
+  buildSemanticEnrichmentProvenance,
+  computeSourceSnapshotHash,
+  enrichEvidenceEvent,
+} from "../semantic-enrichment.js";
+
+function makeEvent(overrides?: Partial<EvidenceEvent>): EvidenceEvent {
+  return {
+    eventType: "sentence_first_seen",
+    fromRevisionId: 1,
+    toRevisionId: 2,
+    section: "body",
+    before: "",
+    after: "The study demonstrated significant results.",
+    deterministicFacts: [],
+    layer: "observed",
+    timestamp: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+describe("buildSemanticEnrichmentProvenance", () => {
+  it("produces identical Merkle roots for identical parameters and snapshots", () => {
+    const params = {
+      sourceSnapshotHash: computeSourceSnapshotHash(makeEvent()),
+      parameterFootprint: { depth: "brief", profileHedges: true },
+      effectiveAt: "2026-01-01T00:00:00Z",
+    };
+
+    const a = buildSemanticEnrichmentProvenance(params);
+    const b = buildSemanticEnrichmentProvenance(params);
+
+    expect(a.merkleRoot).toBe(b.merkleRoot);
+    expect(a.merkleRoot).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("produces different Merkle roots when the parameter footprint changes", () => {
+    const baseParams = {
+      sourceSnapshotHash: computeSourceSnapshotHash(makeEvent({ after: "Data showed a reduction." })),
+      parameterFootprint: { depth: "brief", profileHedges: true },
+      effectiveAt: "2026-01-01T00:00:00Z",
+    };
+
+    const unchanged = buildSemanticEnrichmentProvenance(baseParams);
+    const changed = buildSemanticEnrichmentProvenance({
+      ...baseParams,
+      parameterFootprint: { ...baseParams.parameterFootprint, depth: "full" },
+    });
+
+    expect(unchanged.merkleRoot).not.toBe(changed.merkleRoot);
+  });
+
+  it("produces different Merkle roots when the source snapshot changes", () => {
+    const eventA = makeEvent({ after: "The trial was conclusive." });
+    const eventB = makeEvent({ after: "The trial was inconclusive." });
+
+    const params = {
+      parameterFootprint: { depth: "brief" },
+      effectiveAt: "2026-01-01T00:00:00Z",
+    };
+
+    const a = buildSemanticEnrichmentProvenance({
+      sourceSnapshotHash: computeSourceSnapshotHash(eventA),
+      ...params,
+    });
+    const b = buildSemanticEnrichmentProvenance({
+      sourceSnapshotHash: computeSourceSnapshotHash(eventB),
+      ...params,
+    });
+
+    expect(a.merkleRoot).not.toBe(b.merkleRoot);
+  });
+
+  it("returns all required FactProvenance fields", () => {
+    const provenance = buildSemanticEnrichmentProvenance({
+      sourceSnapshotHash: computeSourceSnapshotHash(makeEvent()),
+      parameterFootprint: { depth: "brief" },
+      effectiveAt: "2026-01-01T00:00:00Z",
+    });
+
+    expect(provenance.merkleRoot).toMatch(/^[0-9a-f]{64}$/);
+    expect(provenance.sourceSnapshotHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(provenance.parameterFootprint).toEqual({ depth: "brief" });
+    expect(provenance.effectiveAt).toBe("2026-01-01T00:00:00Z");
+    expect(provenance.analyzer).toBe("@refract-org/analyzers/semantic-enrichment");
+    expect(provenance.inputHashes).toEqual([provenance.sourceSnapshotHash]);
+  });
+});
+
+describe("enrichEvidenceEvent", () => {
+  it("computes the six enrichment fields", () => {
+    const event = makeEvent({ after: "The study demonstrated robust effects (p < 0.05)." });
+    const result = enrichEvidenceEvent(event);
+
+    expect(result.editMagnitude).toBe("minor");
+    expect(result.contentChange).toBe("introduction");
+    expect(result.keyTerms).toContain("robust");
+    expect(result.certaintyProfile.high).toBeGreaterThan(0);
+    expect(result.quantitativeFindings.length).toBeGreaterThan(0);
+  });
+
+  it("attaches a FactProvenance block keyed to source snapshot and parameters", () => {
+    const event = makeEvent({ after: "The study demonstrated robust effects." });
+    const parameters = { depth: "brief" };
+    const result = enrichEvidenceEvent(event, { parameters });
+
+    expect(result.provenance.merkleRoot).toMatch(/^[0-9a-f]{64}$/);
+    expect(result.provenance.sourceSnapshotHash).toBe(computeSourceSnapshotHash(event));
+    expect(result.provenance.parameterFootprint).toEqual(parameters);
+    expect(result.provenance.effectiveAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+});

packages/analyzers/src/index.ts

@@ -71,11 +71,15 @@ export { protectionTracker } from "./protection-tracker.js";
 export { revertDetector } from "./revert-detector.js";
 export type { SectionEvent, SectionLineage } from "./section-differ.js";
 export { buildSectionLineage, sectionDiffer } from "./section-differ.js";
+export type { SemanticEnrichmentResult } from "./semantic-enrichment.js";
 export {
+  buildSemanticEnrichmentProvenance,
   computeCertaintyProfile,
   computeContentChange,
   computeDirectionSignal,
   computeEditMagnitude,
+  computeSourceSnapshotHash,
+  enrichEvidenceEvent,
   extractKeyTerms,
   extractQuantitativeFindings,
 } from "./semantic-enrichment.js";

packages/analyzers/src/merkle-tree.ts

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+
+/** Compute a SHA-256 leaf hash for a UTF-8 string. */
+export function hashLeaf(input: string): string {
+  return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+/** Compute a deterministic pair hash (commutative ordering). */
+function hashPair(a: string, b: string): string {
+  // Sort pair so hashPair(a,b) === hashPair(b,a).
+  const combined = a < b ? `${a}${b}` : `${b}${a}`;
+  return createHash("sha256").update(combined, "utf8").digest("hex");
+}
+
+/**
+ * Build a SHA-256 Merkle root from an array of leaf hashes.
+ * An empty array yields the hash of an empty leaf.
+ * Odd-length levels promote the last hash unchanged.
+ */
+export function buildMerkleRoot(leaves: string[]): string {
+  if (leaves.length === 0) return hashLeaf("");
+
+  let current = [...leaves];
+  while (current.length > 1) {
+    const next: string[] = [];
+    for (let i = 0; i < current.length; i += 2) {
+      if (i + 1 < current.length) {
+        next.push(hashPair(current[i], current[i + 1]));
+      } else {
+        next.push(current[i]);
+      }
+    }
+    current = next;
+  }
+
+  return current[0] ?? "";
+}

packages/analyzers/src/semantic-enrichment.ts

@@ -1,7 +1,17 @@
 // Semantic enrichment — deterministic text analysis for evidence events
 // No model. No API. Byte-reproducible on every run.
 
-import type { CertaintyProfile, DirectionSignal, QuantitativeFinding } from "@refract-org/evidence-graph";
+import {
+  type CertaintyProfile,
+  type ContentChange,
+  type DirectionSignal,
+  type EditMagnitude,
+  EVENT_SCHEMA_VERSION,
+  type EvidenceEvent,
+  type FactProvenance,
+  type QuantitativeFinding,
+} from "@refract-org/evidence-graph";
+import { buildMerkleRoot, hashLeaf } from "./merkle-tree.js";
 
 const CERTAINTY_PATTERNS = {
   high: [/demonstrat\w*/i, /prove\w*/i, /confirm\w*/i, /establish\w*/i, /significantly/i, /robust/i, /definitive/i],
@@ -106,3 +116,133 @@ export function extractKeyTerms(text: string): string[] {
   }
   return [...terms].slice(0, 15); // Limit to top 15
 }
+
+/**
+ * Deterministic JSON serialization for hash inputs.
+ * Sorts object keys recursively so equivalent values always serialize
+ * to the same byte string.
+ */
+function stableStringify(value: unknown): string {
+  if (value === undefined) return "undefined";
+  if (value === null) return "null";
+
+  switch (typeof value) {
+    case "boolean":
+    case "number":
+      return String(value);
+    case "string":
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+      }
+      const record = value as Record<string, unknown>;
+      const keys = Object.keys(record).sort();
+      const pairs = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(record[k])}`);
+      return `{${pairs.join(",")}}`;
+    }
+    default:
+      return "null";
+  }
+}
+
+function parameterFootprintToLegacyParameters(
+  footprint: Record<string, unknown>,
+): Record<string, string | number | boolean> | undefined {
+  const out: Record<string, string | number | boolean> = {};
+  let hasAny = false;
+  for (const [key, value] of Object.entries(footprint)) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      out[key] = value;
+      hasAny = true;
+    }
+  }
+  return hasAny ? out : undefined;
+}
+
+/** The result of applying semantic enrichment to a single evidence event. */
+export interface SemanticEnrichmentResult {
+  editMagnitude: EditMagnitude;
+  contentChange: ContentChange;
+  keyTerms: string[];
+  certaintyProfile: CertaintyProfile;
+  directionSignal: DirectionSignal;
+  quantitativeFindings: QuantitativeFinding[];
+  /** Strictly typed provenance block carrying the Merkle root of source + parameters. */
+  provenance: FactProvenance;
+}
+
+/** Build a deterministic source snapshot hash from the raw event state. */
+export function computeSourceSnapshotHash(event: EvidenceEvent): string {
+  const snapshot = `${event.fromRevisionId}|${event.toRevisionId}|${event.section}|${event.before}|${event.after}`;
+  return hashLeaf(snapshot);
+}
+
+/** Build a FactProvenance block for semantic enrichment output. */
+export function buildSemanticEnrichmentProvenance(params: {
+  sourceSnapshotHash: string;
+  parameterFootprint: Record<string, unknown>;
+  analyzer?: string;
+  version?: string;
+  inputHashes?: string[];
+  effectiveAt?: string;
+}): FactProvenance {
+  const parameterHash = hashLeaf(stableStringify(params.parameterFootprint));
+  const merkleRoot = buildMerkleRoot([params.sourceSnapshotHash, parameterHash]);
+  return {
+    analyzer: params.analyzer ?? "@refract-org/analyzers/semantic-enrichment",
+    version: params.version ?? EVENT_SCHEMA_VERSION,
+    inputHashes: params.inputHashes ?? [params.sourceSnapshotHash],
+    parameters: parameterFootprintToLegacyParameters(params.parameterFootprint),
+    parameterFootprint: params.parameterFootprint,
+    sourceSnapshotHash: params.sourceSnapshotHash,
+    effectiveAt: params.effectiveAt ?? new Date().toISOString(),
+    merkleRoot,
+  };
+}
+
+/**
+ * Run the full deterministic semantic enrichment pipeline for an evidence event
+ * and emit a strictly typed FactProvenance block alongside the enrichment fields.
+ */
+export function enrichEvidenceEvent(
+  event: EvidenceEvent,
+  options?: {
+    analyzer?: string;
+    version?: string;
+    parameters?: Record<string, unknown>;
+    effectiveAt?: string;
+  },
+): SemanticEnrichmentResult {
+  const before = event.before || "";
+  const after = event.after || "";
+  const text = after || before;
+
+  const editMagnitude = computeEditMagnitude(before.length, after.length);
+  const contentChange = computeContentChange(event.eventType, before, after);
+  const keyTerms = extractKeyTerms(text);
+  const certaintyProfile = computeCertaintyProfile(text);
+  const directionSignal = computeDirectionSignal(computeCertaintyProfile(before), computeCertaintyProfile(after));
+  const quantitativeFindings = extractQuantitativeFindings(text);
+
+  const sourceSnapshotHash = computeSourceSnapshotHash(event);
+  const parameterFootprint = options?.parameters ?? {};
+
+  const provenance = buildSemanticEnrichmentProvenance({
+    sourceSnapshotHash,
+    parameterFootprint,
+    analyzer: options?.analyzer,
+    version: options?.version,
+    effectiveAt: options?.effectiveAt,
+  });
+
+  return {
+    editMagnitude,
+    contentChange,
+    keyTerms,
+    certaintyProfile,
+    directionSignal,
+    quantitativeFindings,
+    provenance,
+  };
+}