@refract-org/evidence-graph 0.2.1

package/src/__tests__/hash-identity.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import { createClaimIdentity, createEventIdentity } from "../hash-identity.js";
+import type { EvidenceEvent } from "../schemas/evidence.js";
+
+describe("Claim identity hash", () => {
+  it("produces deterministic hash from same inputs", () => {
+    const a = createClaimIdentity({
+      text: "The sky is blue",
+      section: "Introduction",
+      pageTitle: "Color",
+      pageId: 12345,
+    });
+    const b = createClaimIdentity({
+      text: "The sky is blue",
+      section: "Introduction",
+      pageTitle: "Color",
+      pageId: 12345,
+    });
+    expect(a.claimId).toBe(b.claimId);
+    expect(a.identityKey).toBe(b.identityKey);
+  });
+
+  it("produces different hash for different text", () => {
+    const a = createClaimIdentity({
+      text: "The sky is blue",
+      section: "Introduction",
+      pageTitle: "Color",
+      pageId: 12345,
+    });
+    const b = createClaimIdentity({
+      text: "The sky is green",
+      section: "Introduction",
+      pageTitle: "Color",
+      pageId: 12345,
+    });
+    expect(a.claimId).not.toBe(b.claimId);
+  });
+
+  it("produces different hash for different sections", () => {
+    const a = createClaimIdentity({
+      text: "The sky is blue",
+      section: "Introduction",
+      pageTitle: "Color",
+      pageId: 12345,
+    });
+    const b = createClaimIdentity({
+      text: "The sky is blue",
+      section: "Discussion",
+      pageTitle: "Color",
+      pageId: 12345,
+    });
+    expect(a.claimId).not.toBe(b.claimId);
+  });
+
+  it("normalizes whitespace and case", () => {
+    const a = createClaimIdentity({
+      text: "  The Sky Is Blue  ",
+      section: "Introduction",
+      pageTitle: "Color",
+      pageId: 12345,
+    });
+    const b = createClaimIdentity({
+      text: "the sky is blue",
+      section: "Introduction",
+      pageTitle: "Color",
+      pageId: 12345,
+    });
+    expect(a.claimId).toBe(b.claimId);
+  });
+
+  it("claimId is 16 hex characters", () => {
+    const id = createClaimIdentity({
+      text: "test",
+      section: "test",
+      pageTitle: "Test",
+      pageId: 1,
+    });
+    expect(id.claimId).toMatch(/^[0-9a-f]{16}$/);
+  });
+});
+
+describe("createEventIdentity", () => {
+  const base: Omit<EvidenceEvent, "eventId" | "modelInterpretation"> = {
+    eventType: "revert_detected",
+    fromRevisionId: 1,
+    toRevisionId: 2,
+    section: "body",
+    before: "",
+    after: "reverted",
+    deterministicFacts: [{ fact: "test" }],
+    layer: "observed",
+    timestamp: "2026-01-01T00:00:00Z",
+  };
+
+  it("produces a deterministic 16-char hex hash", () => {
+    const id = createEventIdentity(base);
+    expect(id).toMatch(/^[0-9a-f]{16}$/);
+  });
+
+  it("is deterministic for same input", () => {
+    const a = createEventIdentity(base);
+    const b = createEventIdentity(base);
+    expect(a).toBe(b);
+  });
+
+  it("differs for different event types", () => {
+    const a = createEventIdentity({ ...base, eventType: "sentence_removed" });
+    const b = createEventIdentity(base);
+    expect(a).not.toBe(b);
+  });
+});

package/src/__tests__/replay-manifest.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import type { EvidenceEvent, Revision } from "../index.js";
+import { createReplayManifest } from "../replay-manifest.js";
+
+const rev: Revision = {
+  revId: 1,
+  pageId: 100,
+  pageTitle: "Test",
+  timestamp: "2026-01-01T00:00:00Z",
+  comment: "first edit",
+  content: "Hello world",
+  size: 11,
+  minor: false,
+};
+
+const event: EvidenceEvent = {
+  eventType: "revert_detected",
+  fromRevisionId: 1,
+  toRevisionId: 2,
+  section: "",
+  before: "",
+  after: "reverted",
+  deterministicFacts: [{ fact: "revert" }],
+  layer: "observed",
+  timestamp: "2026-01-01T00:00:00Z",
+};
+
+describe("createReplayManifest", () => {
+  it("produces a manifest with expected format", () => {
+    const manifest = createReplayManifest({
+      pageTitle: "Test",
+      analyzerVersions: { "revert-detector": "0.1.0" },
+      revisions: [rev],
+      events: [event],
+      generatedAt: "2026-01-01T00:00:00.000Z",
+    });
+
+    expect(manifest.format).toBe("refract-replay-manifest/v1");
+    expect(manifest.pageTitle).toBe("Test");
+    expect(manifest.analyzerVersions["revert-detector"]).toBe("0.1.0");
+  });
+
+  it("generates a manifest hash", () => {
+    const manifest = createReplayManifest({
+      pageTitle: "Test",
+      analyzerVersions: { "revert-detector": "0.1.0" },
+      revisions: [rev],
+      events: [event],
+      generatedAt: "2026-01-01T00:00:00.000Z",
+    });
+
+    expect(manifest.manifestHash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("includes input and output hashes", () => {
+    const manifest = createReplayManifest({
+      pageTitle: "Test",
+      analyzerVersions: { "revert-detector": "0.1.0" },
+      revisions: [rev],
+      events: [event],
+      generatedAt: "2026-01-01T00:00:00.000Z",
+    });
+
+    expect(manifest.inputRevisionHashes).toHaveLength(1);
+    expect(manifest.outputEventHashes).toHaveLength(1);
+  });
+
+  it("is deterministic for same inputs", () => {
+    const a = createReplayManifest({
+      pageTitle: "Test",
+      analyzerVersions: { "revert-detector": "0.1.0" },
+      revisions: [rev],
+      events: [event],
+      generatedAt: "2026-01-01T00:00:00.000Z",
+    });
+
+    const b = createReplayManifest({
+      pageTitle: "Test",
+      analyzerVersions: { "revert-detector": "0.1.0" },
+      revisions: [rev],
+      events: [event],
+      generatedAt: "2026-01-01T00:00:00.000Z",
+    });
+
+    expect(a.manifestHash).toBe(b.manifestHash);
+  });
+});

package/src/hash-identity.ts

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+import type { ClaimIdentity } from "./schemas/claim.js";
+import type { EvidenceEvent } from "./schemas/evidence.js";
+
+export function createClaimIdentity(params: {
+  text: string;
+  section: string;
+  pageTitle: string;
+  pageId: number;
+}): ClaimIdentity {
+  const identityKey = `${params.pageTitle}|${params.pageId}|${params.section}|${params.text.toLowerCase().trim()}`;
+  const claimId = createHash("sha256").update(identityKey).digest("hex").slice(0, 16);
+  return {
+    claimId,
+    identityKey,
+    pageTitle: params.pageTitle,
+    pageId: params.pageId,
+  };
+}
+
+export function createEventIdentity(event: Omit<EvidenceEvent, "eventId" | "modelInterpretation">): string {
+  const factsStr = event.deterministicFacts.map((f) => `${f.fact}:${f.detail ?? ""}`).join("|");
+  const identityKey = `${event.eventType}|${event.fromRevisionId}|${event.toRevisionId}|${event.section}|${event.before}|${event.after}|${event.timestamp}|${factsStr}`;
+  return createHash("sha256").update(identityKey).digest("hex").slice(0, 16);
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+export { createClaimIdentity, createEventIdentity } from "./hash-identity.js";
+export {
+  buildInterpretationPrompt,
+  ModelInterpretationSchema,
+  parseInterpretationResponse,
+} from "./interpretation-prompt.js";
+export type { MerkleProof, ReplayManifest } from "./replay-manifest.js";
+export {
+  buildMerkleTree,
+  createReplayManifest,
+  getMerkleProof,
+  singleEventProof,
+  verifyMerkleProof,
+} from "./replay-manifest.js";
+export type {
+  ClaimIdentity,
+  ClaimLineage,
+  ClaimObject,
+  ClaimState,
+  ClaimVariant,
+  PropositionType,
+} from "./schemas/claim.js";
+export type {
+  DeterministicFact,
+  EventType,
+  EvidenceEvent,
+  EvidenceLayer,
+  FactProvenance,
+  ModelInterpretation,
+  PolicyDimension,
+} from "./schemas/evidence.js";
+export type {
+  Depth,
+  ExportFormat,
+  PageTimeline,
+  PolicySignal,
+  Report,
+  ReportLayer,
+  ReportLayerLabel,
+  TimelineEvent,
+} from "./schemas/report.js";
+export type { DiffLine, DiffResult, Revision, Section, SectionChange } from "./schemas/revision.js";
+export type { SourceAuthority, SourceLineage, SourceRecord, SourceReplacement, SourceType } from "./schemas/source.js";

package/src/interpretation-prompt.ts

@@ -0,0 +1,209 @@
+import type { EventType, EvidenceEvent, ModelInterpretation } from "./schemas/evidence.js";
+
+const _ALLOWED_EVENT_TYPES: EventType[] = [
+  "sentence_first_seen",
+  "sentence_removed",
+  "sentence_reintroduced",
+  "citation_added",
+  "citation_removed",
+  "citation_replaced",
+  "template_added",
+  "template_removed",
+  "revert_detected",
+  "section_reorganized",
+  "lead_promotion",
+  "lead_demotion",
+  "page_moved",
+  "wikilink_added",
+  "wikilink_removed",
+  "category_added",
+  "category_removed",
+  "protection_changed",
+  "talk_page_correlated",
+  "talk_thread_opened",
+  "talk_thread_archived",
+  "talk_reply_added",
+  "template_parameter_changed",
+  "edit_cluster_detected",
+  "talk_activity_spike",
+];
+
+export const ModelInterpretationSchema = {
+  type: "object" as const,
+  properties: {
+    semanticChange: { type: "string" as const, description: "Description of what changed and why" },
+    confidence: {
+      type: "number" as const,
+      minimum: 0,
+      maximum: 1,
+      description: "Confidence in this interpretation (0.0–1.0)",
+    },
+    policyDimension: {
+      type: "string" as const,
+      enum: [
+        "verifiability",
+        "npov",
+        "blp",
+        "due_weight",
+        "protection",
+        "edit_warring",
+        "notability",
+        "copyright",
+        "civility",
+      ],
+      description: "Wikipedia policy dimension this event relates to",
+    },
+    discussionType: {
+      type: "string" as const,
+      enum: [
+        "notability_challenge",
+        "sourcing_dispute",
+        "neutrality_concern",
+        "content_deletion",
+        "content_addition",
+        "naming_dispute",
+        "procedural",
+        "other",
+      ],
+      description: "Type of talk page discussion this event correlates with",
+    },
+  },
+  required: ["semanticChange", "confidence"],
+} as const;
+
+const EVENT_DESCRIPTIONS: Partial<Record<EventType, string>> = {
+  sentence_first_seen: "a sentence appeared for the first time",
+  sentence_removed: "a sentence was deleted entirely",
+  sentence_reintroduced: "a previously removed sentence was restored",
+  citation_added: "a new reference or citation was added",
+  citation_removed: "an existing reference was removed",
+  citation_replaced: "one citation was replaced by another",
+  template_added: "a maintenance or policy template was added",
+  template_removed: "a template was removed",
+  revert_detected: "an edit summary indicates a revert",
+  section_reorganized: "sections were added, removed, or reordered",
+  lead_promotion: "content moved from the body into the lead section",
+  lead_demotion: "content moved from the lead into the body",
+  page_moved: "the page was renamed",
+  wikilink_added: "a new internal link was added",
+  wikilink_removed: "an internal link was removed",
+  category_added: "a category was added",
+  category_removed: "a category was removed",
+  protection_changed: "page protection level changed",
+  talk_page_correlated: "a talk page discussion exists near this revision",
+  talk_thread_opened: "a new talk page thread was created",
+  talk_thread_archived: "a talk page thread was archived",
+  talk_reply_added: "a reply was posted in an existing talk thread",
+  template_parameter_changed: "a template parameter was modified",
+  edit_cluster_detected: "multiple edits within a short time window",
+  talk_activity_spike: "talk page activity exceeds normal levels",
+};
+
+const POLICY_DIMENSION_DESCRIPTIONS: Record<string, string> = {
+  verifiability: "claims and sourcing — citations added/removed, citation needed tags",
+  npov: "neutral point of view — bias, balancing claims, fair representation",
+  blp: "biographies of living persons — potentially defamatory or unsourced claims about living people",
+  due_weight: "proportionate coverage — undue emphasis on fringe views",
+  protection: "page protection — edit restrictions, dispute mitigation",
+  edit_warring: "revert cycles and content disputes",
+  notability: "whether the topic meets inclusion criteria",
+  copyright: "potential copyright violations",
+  civility: "editor conduct and dispute tone",
+};
+
+export function buildInterpretationPrompt(events: EvidenceEvent[], pageTitle: string): string {
+  const summary = summarizeEvents(events);
+
+  const lines: string[] = [
+    `You are analyzing edit history events from the Wikipedia page "${pageTitle}".`,
+    "For each event below, provide a structured interpretation: what changed semantically,",
+    "your confidence level, which (if any) Wikipedia policy dimension applies, and whether",
+    "this event correlates with a talk page discussion type.",
+    "",
+    "These are mechanically observed events — factual descriptions of what appeared or disappeared",
+    "at revision boundaries. Your job is not to repeat the mechanical description but to",
+    "interpret what the change means in editorial context.",
+    "",
+    "Return a JSON array with one object per event, using this schema:",
+    JSON.stringify(ModelInterpretationSchema, null, 2),
+    "",
+    `Total events: ${events.length}`,
+    `Page: ${pageTitle}`,
+    `Event type breakdown:`,
+    ...Object.entries(summary.byType)
+      .sort(([, a], [, b]) => b - a)
+      .map(([type, count]) => `  ${type}: ${count} — ${EVENT_DESCRIPTIONS[type as EventType] ?? ""}`),
+    "",
+    "Policy dimensions:",
+    ...Object.entries(POLICY_DIMENSION_DESCRIPTIONS).map(([dim, desc]) => `  ${dim}: ${desc}`),
+    "",
+    "Discussion types:",
+    ...[
+      "notability_challenge",
+      "sourcing_dispute",
+      "neutrality_concern",
+      "content_deletion",
+      "content_addition",
+      "naming_dispute",
+      "procedural",
+      "other",
+    ].map((t) => `  ${t}`),
+    "",
+    "Events:",
+    ...events.map((e, i) => {
+      const section = e.section ? ` [${e.section}]` : "";
+      const facts = e.deterministicFacts.map((f) => `${f.fact}${f.detail ? `: ${f.detail}` : ""}`).join("; ");
+      return `  ${i + 1}. ${e.eventType}${section} (rev ${e.fromRevisionId}→${e.toRevisionId})${facts ? ` — ${facts}` : ""}`;
+    }),
+  ];
+
+  return lines.join("\n");
+}
+
+export function parseInterpretationResponse(text: string): ModelInterpretation[] {
+  const cleaned = text.trim();
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch {
+    const jsonMatch = cleaned.match(/\[[\s\S]*\]/);
+    if (jsonMatch) {
+      try {
+        parsed = JSON.parse(jsonMatch[0]);
+      } catch {
+        return [];
+      }
+    } else {
+      return [];
+    }
+  }
+
+  if (!Array.isArray(parsed)) return [];
+
+  return parsed
+    .map((item: unknown) => {
+      if (typeof item !== "object" || item === null) return null;
+      const obj = item as Record<string, unknown>;
+      if (typeof obj.semanticChange !== "string" || typeof obj.confidence !== "number") return null;
+      return {
+        semanticChange: obj.semanticChange,
+        confidence: Math.max(0, Math.min(1, obj.confidence)),
+        ...(typeof obj.policyDimension === "string"
+          ? { policyDimension: obj.policyDimension as ModelInterpretation["policyDimension"] }
+          : {}),
+        ...(typeof obj.discussionType === "string"
+          ? { discussionType: obj.discussionType as ModelInterpretation["discussionType"] }
+          : {}),
+      } satisfies ModelInterpretation;
+    })
+    .filter((item): item is ModelInterpretation => item !== null);
+}
+
+function summarizeEvents(events: EvidenceEvent[]): { byType: Record<string, number> } {
+  const byType: Record<string, number> = {};
+  for (const e of events) {
+    byType[e.eventType] = (byType[e.eventType] ?? 0) + 1;
+  }
+  return { byType };
+}

package/src/replay-manifest.ts

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { createEventIdentity } from "./hash-identity.js";
+import type { EvidenceEvent } from "./schemas/evidence.js";
+import type { Revision } from "./schemas/revision.js";
+
+export interface MerkleProof {
+  leafHash: string;
+  leafIndex: number;
+  siblings: string[];
+  rootHash: string;
+}
+
+export interface ReplayManifest {
+  format: "refract-replay-manifest/v1";
+  generatedAt: string;
+  pageTitle: string;
+  analyzerVersions: Record<string, string>;
+  inputRevisionHashes: string[];
+  outputEventHashes: string[];
+  merkleRoot: string;
+  manifestHash: string;
+}
+
+function hashPair(a: string, b: string): string {
+  return createHash("sha256")
+    .update(a < b ? a + b : b + a)
+    .digest("hex");
+}
+
+export function buildMerkleTree(hashes: string[]): string[][] {
+  if (hashes.length === 0) return [[""]];
+  const levels: string[][] = [hashes];
+  let current = hashes;
+  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]);
+      }
+    }
+    levels.push(next);
+    current = next;
+  }
+  return levels;
+}
+
+export function getMerkleProof(levels: string[][], leafIndex: number): MerkleProof {
+  const leafHash = levels[0][leafIndex];
+  if (!leafHash) throw new Error(`Leaf index ${leafIndex} out of range`);
+  const siblings: string[] = [];
+  let idx = leafIndex;
+  for (let level = 0; level < levels.length - 1; level++) {
+    const isLeft = idx % 2 === 0;
+    const siblingIdx = isLeft ? idx + 1 : idx - 1;
+    if (siblingIdx < levels[level].length) {
+      siblings.push(levels[level][siblingIdx]);
+    }
+    idx = Math.floor(idx / 2);
+  }
+  const root = levels[levels.length - 1];
+  return {
+    leafHash,
+    leafIndex,
+    siblings,
+    rootHash: root[0] ?? "",
+  };
+}
+
+export function verifyMerkleProof(proof: MerkleProof): boolean {
+  let hash = proof.leafHash;
+  for (const sibling of proof.siblings) {
+    hash = hashPair(hash, sibling);
+  }
+  return hash === proof.rootHash;
+}
+
+export function createReplayManifest(params: {
+  pageTitle: string;
+  analyzerVersions: Record<string, string>;
+  revisions: Revision[];
+  events: EvidenceEvent[];
+  generatedAt?: string;
+}): ReplayManifest {
+  const inputHashes = params.revisions.map((r) => createHash("sha256").update(r.content).digest("hex"));
+
+  const outputHashes = params.events.map((e) => e.eventId ?? createEventIdentity(e));
+
+  const merkleRoot = buildMerkleTree(outputHashes).at(-1)?.[0] ?? "";
+
+  const partial = {
+    format: "refract-replay-manifest/v1" as const,
+    generatedAt: params.generatedAt ?? new Date().toISOString(),
+    pageTitle: params.pageTitle,
+    analyzerVersions: params.analyzerVersions,
+    inputRevisionHashes: inputHashes,
+    outputEventHashes: outputHashes,
+    merkleRoot,
+  };
+
+  const manifestHash = createHash("sha256").update(JSON.stringify(partial)).digest("hex");
+
+  return { ...partial, manifestHash };
+}
+
+export function singleEventProof(manifest: ReplayManifest, eventIndex: number): MerkleProof {
+  const levels = buildMerkleTree(manifest.outputEventHashes);
+  return getMerkleProof(levels, eventIndex);
+}

package/src/schemas/claim.ts

@@ -0,0 +1,58 @@
+// Claim object — the core provenance unit
+
+export type PropositionType =
+  | "factual_claim"
+  | "attributed_claim"
+  | "institutional_finding"
+  | "allegation"
+  | "counterclaim"
+  | "policy_statement"
+  | "editorial_note"
+  | "unknown";
+
+export type ClaimState =
+  | "absent"
+  | "emerging"
+  | "contested"
+  | "softened"
+  | "strengthened"
+  | "stabilizing"
+  | "hardened"
+  | "receding"
+  | "deleted"
+  | "reintroduced";
+
+export interface ClaimIdentity {
+  claimId: string; // Deterministic hash from identity key
+  identityKey: string; // Canonical claim text + section + page
+  pageTitle: string;
+  pageId: number;
+}
+
+export interface ClaimVariant {
+  revisionId: number;
+  text: string;
+  section: string;
+  observedAt: string; // ISO 8601
+}
+
+export interface ClaimLineage {
+  firstSeenRevisionId: number;
+  firstSeenAt: string; // ISO 8601
+  lastSeenRevisionId?: number;
+  lastSeenAt?: string;
+  variants: ClaimVariant[];
+  mergeSourceIds?: string[];
+  splitTargetIds?: string[];
+  deprecatedAt?: string;
+  deprecatedByClaimId?: string;
+}
+
+export interface ClaimObject {
+  identity: ClaimIdentity;
+  lineage: ClaimLineage;
+  currentState: ClaimState;
+  propositionType: PropositionType;
+  sourceLineage: string[]; // SourceRecord IDs
+  phase: string; // Phase tag: Phase 0 | Phase 1b | Phase 2a | Phase 2b
+}