Implement CE-WP-0002 T03-T09: ingest, anchor resolution, engine, UI, persistence, e2e

Completes the PDF review slice end-to-end. After this commit a user can
open a fixture, select text, save an evidence item with commentary, see
it in the sidebar, reload the page, click the item, and the viewer
scrolls to the passage.

- T03 src/source/pdf/{fingerprint,extract,ingest}.ts + 39 fixture tests
  - SHA-256 fingerprint over a fresh ArrayBuffer (TS BufferSource-safe)
  - PDF.js text extract; per-page normalize then join with "\n\n"
  - PageMap + OffsetMap (gap-free coverage); pageLength = end - start
  - Updated manifest's Betriebskosten quote to one PDF.js extracts cleanly
- T04 src/anchor/selectors/{create,resolve}.ts + 25 unit + 7 fixture tests
  - createSelectors emits the maximal redundant set (TextQuote +
    TextPosition + PdfRect + PdfPageText when available)
  - resolveSelectors implements the SharedContracts §7 ladder; confidence
    1.0 (pos+quote) → 0.7 (rect-only) → 0 (unresolved)
  - Cross-module integration test moved to tests/integration/ to honor
    the anchor↛source boundary lint rule
- T05 engine: sync event bus over the closed §4 vocabulary, Map-backed
  repos, services, createEngine() composition root, 12 tests
- T06 work + app: three-pane shell (CollectionList | ViewerShell |
  EvidenceSidebar) wired through EngineProvider; EngineContext lives in
  src/work/ to respect the work↛app boundary; SpikeApp deleted
- T07 AnnotationToolbar: pendingSelection in context; Save runs
  createSelectors → engine.annotations.create → engine.evidence.create
- T08 click-to-reopen + localStorage persistence
  - scrollToAnnotation state in context with a version counter so a
    second click on the same item re-fires the viewer scroll
  - captureSnapshot/restoreSnapshot/attachPersister/restoreFromStorage;
    restore bypasses services to avoid event-loops
  - active-document id persisted alongside the snapshot so reload lands
    on the same fixture; ADR-0005 written
  - 9 persistence tests
- T09 tests/integration/app-prd-scenario.dom.test.tsx
  - end-to-end happy-dom test of PRD scenario steps 1-8 through the real
    React tree; viewer + ingest mocked per ADR-0004's headless-Chromium
    limitation. Fixed memo-deps bug in EvidenceSidebar/ViewerShell where
    useEngineEventTick values were not included in the useMemo deps,
    leaving stale memoization across event-driven re-renders
- vitest.config.ts: happy-dom for *.dom.test.{ts,tsx} files
- noEmit added to tsconfig so tsc -b doesn't litter src/ with .js outputs

Gates: typecheck ✓ lint ✓ test 109/109 across 11 files ✓ build ✓

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/engine/engine.test.ts

@@ -0,0 +1,168 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import type { Document, DocumentRepresentation } from "@shared/document";
+import type { DocumentId, RepresentationId } from "@shared/ids";
+import type { Selector } from "@shared/selector";
+import { createEngine, type Engine, type EngineEvent } from "./index";
+
+function fakeDocAndRep(): { document: Document; representation: DocumentRepresentation } {
+  const docId = "doc_fake" as DocumentId;
+  const repId = "rep_fake" as RepresentationId;
+  return {
+    document: {
+      id: docId,
+      mediaType: "application/pdf",
+      createdAt: "2026-05-25T00:00:00.000Z",
+      updatedAt: "2026-05-25T00:00:00.000Z",
+    },
+    representation: {
+      id: repId,
+      documentId: docId,
+      representationType: "pdf-text",
+      contentHash: "h",
+      canonicalText: "The quick brown fox.",
+      pageMap: [{ page: 1, width: 100, height: 100 }],
+      offsetMap: [{ page: 1, globalStart: 0, globalEnd: 20, pageLength: 20 }],
+      generatedAt: "2026-05-25T00:00:00.000Z",
+    },
+  };
+}
+
+describe("Engine integration", () => {
+  let engine: Engine;
+  let events: EngineEvent[];
+
+  beforeEach(() => {
+    engine = createEngine();
+    events = [];
+    engine.bus.onAny((e) => events.push(e));
+  });
+
+  it("documentService.register stores both and emits DocumentImported + DocumentRepresentationGenerated", () => {
+    const { document, representation } = fakeDocAndRep();
+    const result = engine.documents.register({ document, representation });
+    expect(result.document).toBe(document);
+    expect(result.representation).toBe(representation);
+    expect(engine.documents.get(document.id)).toBe(document);
+    expect(engine.documents.getRepresentation(representation.id)).toBe(representation);
+    expect(events.map((e) => e.type)).toEqual(["DocumentImported", "DocumentRepresentationGenerated"]);
+  });
+
+  it("annotationService.create stamps an ID + normalize version + timestamps, then emits AnnotationCreated", () => {
+    const { document, representation } = fakeDocAndRep();
+    engine.documents.register({ document, representation });
+    const selectors: Selector[] = [{ type: "TextQuoteSelector", exact: "brown fox" }];
+    const ann = engine.annotations.create({
+      documentId: document.id,
+      representationId: representation.id,
+      selectors,
+      quote: "brown fox",
+      note: "a quick mark",
+    });
+    expect(ann.id).toMatch(/^ann_/);
+    expect(ann.normalizeVersion).toBeGreaterThan(0);
+    expect(ann.createdAt).toBe(ann.updatedAt);
+    expect(engine.annotations.get(ann.id)).toBe(ann);
+    const created = events.find((e) => e.type === "AnnotationCreated");
+    expect(created?.type).toBe("AnnotationCreated");
+  });
+
+  it("setResolutionStatus emits AnnotationResolved for resolved/ambiguous and AnnotationResolutionFailed for unresolved/stale", () => {
+    const { document, representation } = fakeDocAndRep();
+    engine.documents.register({ document, representation });
+    const ann = engine.annotations.create({
+      documentId: document.id,
+      representationId: representation.id,
+      selectors: [{ type: "TextQuoteSelector", exact: "x" }],
+    });
+    events.length = 0;
+    engine.annotations.setResolutionStatus(ann.id, "resolved", { confidence: 0.95 });
+    expect(events.map((e) => e.type)).toEqual(["AnnotationResolved"]);
+    engine.annotations.setResolutionStatus(ann.id, "unresolved", { confidence: 0, reason: "no quote match" });
+    expect(events.map((e) => e.type)).toEqual(["AnnotationResolved", "AnnotationResolutionFailed"]);
+  });
+
+  it("evidenceService.create requires at least one annotation and emits EvidenceItemCreated", () => {
+    const { document, representation } = fakeDocAndRep();
+    engine.documents.register({ document, representation });
+    const ann = engine.annotations.create({
+      documentId: document.id,
+      representationId: representation.id,
+      selectors: [{ type: "TextQuoteSelector", exact: "brown fox" }],
+    });
+    expect(() => engine.evidence.create({ annotationIds: [] })).toThrow();
+    const item = engine.evidence.create({
+      annotationIds: [ann.id],
+      commentary: "good quote",
+    });
+    expect(item.status).toBe("candidate");
+    expect(item.annotationIds).toEqual([ann.id]);
+    expect(events.find((e) => e.type === "EvidenceItemCreated")).toBeDefined();
+  });
+
+  it("setStatus emits EvidenceItemUpdated only on real change and carries previousStatus", () => {
+    const { document, representation } = fakeDocAndRep();
+    engine.documents.register({ document, representation });
+    const ann = engine.annotations.create({
+      documentId: document.id,
+      representationId: representation.id,
+      selectors: [{ type: "TextQuoteSelector", exact: "brown fox" }],
+    });
+    const item = engine.evidence.create({ annotationIds: [ann.id] });
+    events.length = 0;
+    const same = engine.evidence.setStatus(item.id, "candidate");
+    expect(same).toBe(item);
+    expect(events).toEqual([]);
+    engine.evidence.setStatus(item.id, "confirmed");
+    const updated = events.find((e) => e.type === "EvidenceItemUpdated");
+    expect(updated).toBeDefined();
+    if (updated?.type === "EvidenceItemUpdated") {
+      expect(updated.previousStatus).toBe("candidate");
+    }
+  });
+
+  it("listByDocument scopes evidence items to a single document via annotation lookup", () => {
+    const a = fakeDocAndRep();
+    engine.documents.register(a);
+    const annA = engine.annotations.create({
+      documentId: a.document.id,
+      representationId: a.representation.id,
+      selectors: [{ type: "TextQuoteSelector", exact: "brown fox" }],
+    });
+    engine.evidence.create({ annotationIds: [annA.id], commentary: "a" });
+
+    // Second, distinct document.
+    const otherDocId = "doc_other" as DocumentId;
+    const otherRepId = "rep_other" as RepresentationId;
+    engine.documents.register({
+      document: { ...a.document, id: otherDocId },
+      representation: { ...a.representation, id: otherRepId, documentId: otherDocId },
+    });
+    const annB = engine.annotations.create({
+      documentId: otherDocId,
+      representationId: otherRepId,
+      selectors: [{ type: "TextQuoteSelector", exact: "z" }],
+    });
+    engine.evidence.create({ annotationIds: [annB.id], commentary: "b" });
+
+    expect(engine.evidence.listByDocument(a.document.id)).toHaveLength(1);
+    expect(engine.evidence.listByDocument(otherDocId)).toHaveLength(1);
+  });
+
+  it("activate emits EvidenceItemActivated without mutating the item", () => {
+    const { document, representation } = fakeDocAndRep();
+    engine.documents.register({ document, representation });
+    const ann = engine.annotations.create({
+      documentId: document.id,
+      representationId: representation.id,
+      selectors: [{ type: "TextQuoteSelector", exact: "x" }],
+    });
+    const item = engine.evidence.create({ annotationIds: [ann.id] });
+    events.length = 0;
+    engine.evidence.activate(item.id, "sidebar");
+    const activated = events.find((e) => e.type === "EvidenceItemActivated");
+    expect(activated).toBeDefined();
+    if (activated?.type === "EvidenceItemActivated") {
+      expect(activated.source).toBe("sidebar");
+    }
+  });
+});

src/engine/events/bus.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from "vitest";
+import type { DocumentId } from "@shared/ids";
+import { createEventBus } from "./bus";
+
+const docId = "doc_test" as DocumentId;
+const minimalDoc = {
+  id: docId,
+  mediaType: "application/pdf",
+  createdAt: "2026-05-25T00:00:00.000Z",
+  updatedAt: "2026-05-25T00:00:00.000Z",
+};
+
+describe("EventBus", () => {
+  it("delivers typed events to the registered listener", () => {
+    const bus = createEventBus();
+    const spy = vi.fn();
+    bus.on("DocumentImported", spy);
+    const result = bus.emit({ type: "DocumentImported", documentId: docId, document: minimalDoc });
+    expect(spy).toHaveBeenCalledOnce();
+    expect(spy.mock.calls[0]![0]).toMatchObject({ type: "DocumentImported", documentId: docId });
+    expect(result.listenerCount).toBe(1);
+    expect(result.errors).toEqual([]);
+  });
+
+  it("does not deliver an event to listeners of a different type", () => {
+    const bus = createEventBus();
+    const spy = vi.fn();
+    bus.on("AnnotationCreated", spy);
+    bus.emit({ type: "DocumentImported", documentId: docId, document: minimalDoc });
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("delivers every event to onAny listeners", () => {
+    const bus = createEventBus();
+    const spy = vi.fn();
+    bus.onAny(spy);
+    bus.emit({ type: "DocumentImported", documentId: docId, document: minimalDoc });
+    bus.emit({ type: "EvidenceItemActivated", evidenceItemId: "ev_x" as never });
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  it("returns an unsubscribe function from on()", () => {
+    const bus = createEventBus();
+    const spy = vi.fn();
+    const off = bus.on("DocumentImported", spy);
+    off();
+    bus.emit({ type: "DocumentImported", documentId: docId, document: minimalDoc });
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("captures listener errors and still calls subsequent listeners", () => {
+    const bus = createEventBus();
+    const boom = new Error("listener exploded");
+    const a = vi.fn(() => { throw boom; });
+    const b = vi.fn();
+    bus.on("DocumentImported", a);
+    bus.on("DocumentImported", b);
+    const result = bus.emit({ type: "DocumentImported", documentId: docId, document: minimalDoc });
+    expect(a).toHaveBeenCalledOnce();
+    expect(b).toHaveBeenCalledOnce();
+    expect(result.errors).toEqual([boom]);
+    expect(result.listenerCount).toBe(2);
+  });
+});

src/engine/events/bus.ts

@@ -0,0 +1,79 @@
+/**
+ * Synchronous in-process event bus.
+ *
+ * Listeners fire in registration order on the calling stack; `emit` returns
+ * after every listener has run. A listener throwing does not stop later
+ * listeners — its error surfaces through the returned `errors` array so
+ * callers can decide whether to log, rethrow, or ignore.
+ *
+ * MVP-sufficient. ADR-0005 (persistence) will decide whether to upgrade to
+ * an async/queued bus when storage becomes durable.
+ */
+
+import type { EngineEvent, EngineEventOf, EngineEventType } from "./types";
+
+export type EngineEventListener<T extends EngineEventType = EngineEventType> = (
+  event: EngineEventOf<T>,
+) => void;
+
+export type AnyEngineEventListener = (event: EngineEvent) => void;
+
+export interface EmitResult {
+  readonly listenerCount: number;
+  readonly errors: readonly unknown[];
+}
+
+export interface EventBus {
+  on<T extends EngineEventType>(type: T, listener: EngineEventListener<T>): () => void;
+  onAny(listener: AnyEngineEventListener): () => void;
+  emit<T extends EngineEventType>(event: EngineEventOf<T>): EmitResult;
+}
+
+export function createEventBus(): EventBus {
+  const typedListeners = new Map<EngineEventType, Set<EngineEventListener>>();
+  const anyListeners = new Set<AnyEngineEventListener>();
+
+  return {
+    on(type, listener) {
+      let set = typedListeners.get(type);
+      if (!set) {
+        set = new Set();
+        typedListeners.set(type, set);
+      }
+      set.add(listener as unknown as EngineEventListener);
+      return () => {
+        set!.delete(listener as unknown as EngineEventListener);
+      };
+    },
+    onAny(listener) {
+      anyListeners.add(listener);
+      return () => {
+        anyListeners.delete(listener);
+      };
+    },
+    emit(event) {
+      const errors: unknown[] = [];
+      let count = 0;
+      const typedSet = typedListeners.get(event.type);
+      if (typedSet) {
+        for (const l of typedSet) {
+          count++;
+          try {
+            (l as AnyEngineEventListener)(event);
+          } catch (err) {
+            errors.push(err);
+          }
+        }
+      }
+      for (const l of anyListeners) {
+        count++;
+        try {
+          l(event);
+        } catch (err) {
+          errors.push(err);
+        }
+      }
+      return { listenerCount: count, errors };
+    },
+  };
+}

src/engine/events/index.ts

@@ -0,0 +1,8 @@
+export * from "./types";
+export {
+  createEventBus,
+  type EventBus,
+  type EngineEventListener,
+  type AnyEngineEventListener,
+  type EmitResult,
+} from "./bus";

src/engine/events/types.ts

@@ -0,0 +1,84 @@
+/**
+ * Engine event vocabulary.
+ *
+ * Implements `wiki/SharedContracts.md` §4 (closed event list). Each event
+ * carries the *minimum* identifying payload needed by downstream listeners;
+ * services hand back the full domain object to the caller separately.
+ *
+ * Adding an event requires updating SharedContracts.md first.
+ */
+
+import type { Annotation, AnnotationResolutionStatus } from "@shared/annotation";
+import type { Document, DocumentRepresentation } from "@shared/document";
+import type { EvidenceItem, EvidenceItemStatus } from "@shared/evidence";
+import type {
+  AnnotationId,
+  DocumentId,
+  EvidenceItemId,
+  RepresentationId,
+} from "@shared/ids";
+
+export interface DocumentImportedEvent {
+  readonly type: "DocumentImported";
+  readonly documentId: DocumentId;
+  readonly document: Document;
+}
+
+export interface DocumentRepresentationGeneratedEvent {
+  readonly type: "DocumentRepresentationGenerated";
+  readonly documentId: DocumentId;
+  readonly representationId: RepresentationId;
+  readonly representation: DocumentRepresentation;
+}
+
+export interface AnnotationCreatedEvent {
+  readonly type: "AnnotationCreated";
+  readonly annotationId: AnnotationId;
+  readonly annotation: Annotation;
+}
+
+export interface AnnotationResolvedEvent {
+  readonly type: "AnnotationResolved";
+  readonly annotationId: AnnotationId;
+  readonly status: AnnotationResolutionStatus;
+  readonly confidence: number;
+}
+
+export interface AnnotationResolutionFailedEvent {
+  readonly type: "AnnotationResolutionFailed";
+  readonly annotationId: AnnotationId;
+  readonly reason: string;
+}
+
+export interface EvidenceItemCreatedEvent {
+  readonly type: "EvidenceItemCreated";
+  readonly evidenceItemId: EvidenceItemId;
+  readonly evidenceItem: EvidenceItem;
+}
+
+export interface EvidenceItemUpdatedEvent {
+  readonly type: "EvidenceItemUpdated";
+  readonly evidenceItemId: EvidenceItemId;
+  readonly evidenceItem: EvidenceItem;
+  readonly previousStatus: EvidenceItemStatus;
+}
+
+export interface EvidenceItemActivatedEvent {
+  readonly type: "EvidenceItemActivated";
+  readonly evidenceItemId: EvidenceItemId;
+  readonly source?: "sidebar" | "form-field" | "citation-card";
+}
+
+export type EngineEvent =
+  | DocumentImportedEvent
+  | DocumentRepresentationGeneratedEvent
+  | AnnotationCreatedEvent
+  | AnnotationResolvedEvent
+  | AnnotationResolutionFailedEvent
+  | EvidenceItemCreatedEvent
+  | EvidenceItemUpdatedEvent
+  | EvidenceItemActivatedEvent;
+
+export type EngineEventType = EngineEvent["type"];
+
+export type EngineEventOf<T extends EngineEventType> = Extract<EngineEvent, { type: T }>;

src/engine/index.ts

@@ -1 +1,60 @@
-export {};
+/**
+ * Engine composition root.
+ *
+ * `createEngine()` wires in-memory repos to the services and shares a single
+ * event bus. The app layer holds the returned `Engine` instance and passes
+ * its services into the UI.
+ *
+ * Swapping the repository implementation later (ADR-0005) is a matter of
+ * replacing `createInMemoryRepos()` here. The service signatures don't
+ * change.
+ */
+
+import { createEventBus, type EventBus } from "./events";
+import {
+  createInMemoryRepos,
+  type InMemoryRepos,
+} from "./repos";
+import {
+  createAnnotationService,
+  createDocumentService,
+  createEvidenceService,
+  type AnnotationService,
+  type DocumentService,
+  type EvidenceService,
+} from "./services";
+
+export * from "./events";
+export * from "./repos";
+export * from "./services";
+export {
+  SNAPSHOT_VERSION,
+  attachPersister,
+  captureSnapshot,
+  documentIdsIn,
+  restoreFromStorage,
+  restoreSnapshot,
+  type EngineSnapshot,
+  type PersisterOptions,
+} from "./persistence";
+
+export interface Engine {
+  readonly bus: EventBus;
+  readonly repos: InMemoryRepos;
+  readonly documents: DocumentService;
+  readonly annotations: AnnotationService;
+  readonly evidence: EvidenceService;
+}
+
+export function createEngine(): Engine {
+  const bus = createEventBus();
+  const repos = createInMemoryRepos();
+  const documents = createDocumentService(repos.documents, repos.representations, bus);
+  const annotations = createAnnotationService(repos.annotations, bus);
+  const evidence = createEvidenceService(
+    repos.evidenceItems,
+    (id) => repos.annotations.get(id),
+    bus,
+  );
+  return { bus, repos, documents, annotations, evidence };
+}

src/engine/persistence.test.ts

@@ -0,0 +1,183 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { Document, DocumentRepresentation } from "@shared/document";
+import type { DocumentId, RepresentationId } from "@shared/ids";
+import {
+  attachPersister,
+  captureSnapshot,
+  createEngine,
+  restoreFromStorage,
+  restoreSnapshot,
+  type Engine,
+  type EngineEvent,
+  type EngineSnapshot,
+} from "./index";
+
+function fakeDocAndRep(suffix: string): {
+  document: Document;
+  representation: DocumentRepresentation;
+} {
+  const docId = `doc_${suffix}` as DocumentId;
+  const repId = `rep_${suffix}` as RepresentationId;
+  return {
+    document: {
+      id: docId,
+      mediaType: "application/pdf",
+      title: `Doc ${suffix}`,
+      createdAt: "2026-05-25T00:00:00.000Z",
+      updatedAt: "2026-05-25T00:00:00.000Z",
+    },
+    representation: {
+      id: repId,
+      documentId: docId,
+      representationType: "pdf-text",
+      contentHash: `hash-${suffix}`,
+      canonicalText: "The quick brown fox.",
+      pageMap: [{ page: 1, width: 100, height: 100 }],
+      offsetMap: [{ page: 1, globalStart: 0, globalEnd: 20, pageLength: 20 }],
+      generatedAt: "2026-05-25T00:00:00.000Z",
+    },
+  };
+}
+
+function memoryStorage(): Pick<Storage, "getItem" | "setItem" | "removeItem"> {
+  const map = new Map<string, string>();
+  return {
+    getItem: (k) => map.get(k) ?? null,
+    setItem: (k, v) => void map.set(k, v),
+    removeItem: (k) => void map.delete(k),
+  };
+}
+
+function seed(engine: Engine, suffix: string) {
+  const { document, representation } = fakeDocAndRep(suffix);
+  engine.documents.register({ document, representation });
+  const ann = engine.annotations.create({
+    documentId: document.id,
+    representationId: representation.id,
+    selectors: [{ type: "TextQuoteSelector", exact: "brown fox" }],
+    quote: "brown fox",
+  });
+  const item = engine.evidence.create({
+    annotationIds: [ann.id],
+    commentary: `commentary-${suffix}`,
+  });
+  return { document, representation, ann, item };
+}
+
+describe("captureSnapshot + restoreSnapshot", () => {
+  it("round-trips documents, representations, annotations and evidence items", () => {
+    const src = createEngine();
+    const a = seed(src, "a");
+    const b = seed(src, "b");
+    const snap = captureSnapshot(src);
+    expect(snap.documents).toHaveLength(2);
+    expect(snap.representations).toHaveLength(2);
+    expect(snap.annotations).toHaveLength(2);
+    expect(snap.evidenceItems).toHaveLength(2);
+
+    const dst = createEngine();
+    restoreSnapshot(dst, snap);
+    expect(dst.documents.get(a.document.id)?.title).toBe("Doc a");
+    expect(dst.documents.get(b.document.id)?.title).toBe("Doc b");
+    expect(dst.annotations.get(a.ann.id)?.quote).toBe("brown fox");
+    expect(dst.evidence.get(a.item.id)?.commentary).toBe("commentary-a");
+  });
+
+  it("restoreSnapshot does NOT emit *Created events (events would loop the persister)", () => {
+    const src = createEngine();
+    seed(src, "x");
+    const snap = captureSnapshot(src);
+
+    const dst = createEngine();
+    const seen: EngineEvent["type"][] = [];
+    dst.bus.onAny((e) => seen.push(e.type));
+    restoreSnapshot(dst, snap);
+    expect(seen).toEqual([]);
+  });
+
+  it("rejects a snapshot with a mismatching version", () => {
+    const dst = createEngine();
+    expect(() =>
+      restoreSnapshot(dst, {
+        version: 999,
+        documents: [],
+        representations: [],
+        annotations: [],
+        evidenceItems: [],
+      } as EngineSnapshot),
+    ).toThrow(/version/);
+  });
+});
+
+describe("attachPersister", () => {
+  let storage: ReturnType<typeof memoryStorage>;
+  let engine: Engine;
+  const KEY = "ce-test-snap";
+
+  beforeEach(() => {
+    storage = memoryStorage();
+    engine = createEngine();
+  });
+
+  it("writes a snapshot to storage on every mutating event", () => {
+    const off = attachPersister(engine, { key: KEY, storage });
+    expect(storage.getItem(KEY)).toBeNull();
+    seed(engine, "z");
+    const raw = storage.getItem(KEY);
+    expect(raw).not.toBeNull();
+    const snap = JSON.parse(raw!) as EngineSnapshot;
+    expect(snap.documents).toHaveLength(1);
+    expect(snap.evidenceItems).toHaveLength(1);
+    off();
+  });
+
+  it("stops writing after the unsubscribe is called", () => {
+    const off = attachPersister(engine, { key: KEY, storage });
+    seed(engine, "q");
+    const after = storage.getItem(KEY);
+    off();
+    seed(engine, "r");
+    expect(storage.getItem(KEY)).toBe(after);
+  });
+
+  it("survives a JSON.stringify failure without throwing into the caller", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const failing = { ...memoryStorage(), setItem: () => { throw new Error("boom"); } };
+    attachPersister(engine, { key: KEY, storage: failing });
+    expect(() => seed(engine, "k")).not.toThrow();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+describe("restoreFromStorage", () => {
+  it("returns {restored: false} when the key is empty", () => {
+    const storage = memoryStorage();
+    const engine = createEngine();
+    const result = restoreFromStorage(engine, { key: "missing", storage });
+    expect(result.restored).toBe(false);
+  });
+
+  it("hydrates the engine when storage holds a valid snapshot", () => {
+    const src = createEngine();
+    seed(src, "rs");
+    const storage = memoryStorage();
+    storage.setItem("snap", JSON.stringify(captureSnapshot(src)));
+
+    const dst = createEngine();
+    const result = restoreFromStorage(dst, { key: "snap", storage });
+    expect(result.restored).toBe(true);
+    expect(dst.documents.list()).toHaveLength(1);
+  });
+
+  it("ignores malformed JSON without throwing", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const storage = memoryStorage();
+    storage.setItem("snap", "not-json");
+    const engine = createEngine();
+    const result = restoreFromStorage(engine, { key: "snap", storage });
+    expect(result.restored).toBe(false);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});

src/engine/persistence.ts

@@ -0,0 +1,138 @@
+/**
+ * Engine snapshot + restore.
+ *
+ * MVP "persistence" — capture the engine's in-memory state into a JSON blob
+ * and restore it later. Used by the SPA to survive page reloads via
+ * `localStorage` until ADR-0005 lands a real store.
+ *
+ * Restore deliberately bypasses the service layer: it writes directly to
+ * the repos so no `*Created` events fire. Without that, restoring would
+ * trigger the persister to re-write the same snapshot — and if the user
+ * has another tab open, it would also broadcast spurious "this annotation
+ * just appeared" events to UI listeners.
+ */
+
+import type { Annotation } from "@shared/annotation";
+import type { Document, DocumentRepresentation } from "@shared/document";
+import type { EvidenceItem } from "@shared/evidence";
+import type { DocumentId } from "@shared/ids";
+
+import type { Engine } from "./index";
+
+export const SNAPSHOT_VERSION = 1;
+
+export interface EngineSnapshot {
+  readonly version: number;
+  readonly documents: readonly Document[];
+  readonly representations: readonly DocumentRepresentation[];
+  readonly annotations: readonly Annotation[];
+  readonly evidenceItems: readonly EvidenceItem[];
+}
+
+export function captureSnapshot(engine: Engine): EngineSnapshot {
+  const documents = engine.documents.list();
+  // Gather representations per known document.
+  const representations: DocumentRepresentation[] = [];
+  const annotations: Annotation[] = [];
+  const evidenceItems: EvidenceItem[] = [];
+  const seenItemIds = new Set<string>();
+  for (const doc of documents) {
+    representations.push(...engine.documents.listRepresentations(doc.id));
+    annotations.push(...engine.annotations.listByDocument(doc.id));
+    for (const item of engine.evidence.listByDocument(doc.id)) {
+      // listByDocument keys off annotation lookup; an item that shares
+      // annotations across two documents would surface twice. De-dupe.
+      if (!seenItemIds.has(item.id)) {
+        seenItemIds.add(item.id);
+        evidenceItems.push(item);
+      }
+    }
+  }
+  return {
+    version: SNAPSHOT_VERSION,
+    documents: [...documents],
+    representations,
+    annotations,
+    evidenceItems,
+  };
+}
+
+export function restoreSnapshot(engine: Engine, snapshot: EngineSnapshot): void {
+  if (snapshot.version !== SNAPSHOT_VERSION) {
+    throw new Error(
+      `restoreSnapshot: snapshot version ${snapshot.version} does not match current ${SNAPSHOT_VERSION}`,
+    );
+  }
+  for (const d of snapshot.documents) engine.repos.documents.create(d);
+  for (const r of snapshot.representations) engine.repos.representations.create(r);
+  for (const a of snapshot.annotations) engine.repos.annotations.create(a);
+  for (const i of snapshot.evidenceItems) engine.repos.evidenceItems.create(i);
+}
+
+export interface PersisterOptions {
+  /** Storage key. */
+  readonly key: string;
+  /** Storage shim — defaults to globalThis.localStorage. */
+  readonly storage?: Pick<Storage, "getItem" | "setItem" | "removeItem">;
+}
+
+/**
+ * Subscribe to engine events and write a fresh snapshot on every mutation.
+ * Returns the unsubscribe function.
+ *
+ * Initial snapshot is NOT written — call `captureSnapshot` + `storage.setItem`
+ * yourself if you want a baseline.
+ */
+export function attachPersister(engine: Engine, options: PersisterOptions): () => void {
+  const storage = options.storage ?? globalThis.localStorage;
+  const write = () => {
+    const snap = captureSnapshot(engine);
+    try {
+      storage.setItem(options.key, JSON.stringify(snap));
+    } catch (err) {
+      // localStorage quota / serialization errors shouldn't crash the app.
+      // Surface to the console; ADR-0005 owns the durable fix.
+      console.warn("attachPersister: write failed", err);
+    }
+  };
+  const offs = [
+    engine.bus.on("DocumentImported", write),
+    engine.bus.on("DocumentRepresentationGenerated", write),
+    engine.bus.on("AnnotationCreated", write),
+    engine.bus.on("AnnotationResolved", write),
+    engine.bus.on("AnnotationResolutionFailed", write),
+    engine.bus.on("EvidenceItemCreated", write),
+    engine.bus.on("EvidenceItemUpdated", write),
+  ];
+  return () => {
+    for (const off of offs) off();
+  };
+}
+
+export type RestoreFromStorageOptions = PersisterOptions;
+
+export function restoreFromStorage(
+  engine: Engine,
+  options: RestoreFromStorageOptions,
+): { readonly restored: boolean; readonly snapshot?: EngineSnapshot } {
+  const storage = options.storage ?? globalThis.localStorage;
+  const raw = storage.getItem(options.key);
+  if (!raw) return { restored: false };
+  try {
+    const parsed = JSON.parse(raw) as EngineSnapshot;
+    if (typeof parsed !== "object" || parsed === null) return { restored: false };
+    restoreSnapshot(engine, parsed);
+    return { restored: true, snapshot: parsed };
+  } catch (err) {
+    console.warn("restoreFromStorage: parse failed, ignoring stored snapshot", err);
+    return { restored: false };
+  }
+}
+
+/**
+ * Narrow helper: get the set of document ids restored from a snapshot.
+ * Useful for the SPA's "show me what was open last time" logic.
+ */
+export function documentIdsIn(snapshot: EngineSnapshot): readonly DocumentId[] {
+  return snapshot.documents.map((d) => d.id);
+}

src/engine/repos/in-memory.ts

@@ -0,0 +1,151 @@
+/**
+ * In-memory `Map`-backed repositories.
+ *
+ * Implements the MVP storage layer. The repository interfaces match the
+ * shape that ADR-0005's eventual persistence implementation will satisfy,
+ * so swapping `createInMemoryRepos()` for a SQLite/Postgres factory later
+ * is a localised change.
+ *
+ * All mutating methods return the *stored* object so callers can pick up
+ * server-assigned fields (none in MVP, but the contract anticipates it).
+ */
+
+import type { Annotation } from "@shared/annotation";
+import type { Document, DocumentRepresentation } from "@shared/document";
+import type { EvidenceItem } from "@shared/evidence";
+import type {
+  AnnotationId,
+  DocumentId,
+  EvidenceItemId,
+  RepresentationId,
+} from "@shared/ids";
+
+export interface DocumentRepository {
+  create(document: Document): Document;
+  get(id: DocumentId): Document | null;
+  list(): readonly Document[];
+  update(document: Document): Document;
+}
+
+export interface RepresentationRepository {
+  create(representation: DocumentRepresentation): DocumentRepresentation;
+  get(id: RepresentationId): DocumentRepresentation | null;
+  listByDocument(documentId: DocumentId): readonly DocumentRepresentation[];
+}
+
+export interface AnnotationRepository {
+  create(annotation: Annotation): Annotation;
+  get(id: AnnotationId): Annotation | null;
+  listByDocument(documentId: DocumentId): readonly Annotation[];
+  update(annotation: Annotation): Annotation;
+}
+
+export interface EvidenceItemRepository {
+  create(item: EvidenceItem): EvidenceItem;
+  get(id: EvidenceItemId): EvidenceItem | null;
+  listByDocument(
+    documentId: DocumentId,
+    annotationLookup: (id: AnnotationId) => Annotation | null,
+  ): readonly EvidenceItem[];
+  update(item: EvidenceItem): EvidenceItem;
+}
+
+export interface InMemoryRepos {
+  readonly documents: DocumentRepository;
+  readonly representations: RepresentationRepository;
+  readonly annotations: AnnotationRepository;
+  readonly evidenceItems: EvidenceItemRepository;
+}
+
+export function createInMemoryRepos(): InMemoryRepos {
+  const documents = new Map<DocumentId, Document>();
+  const representations = new Map<RepresentationId, DocumentRepresentation>();
+  const annotations = new Map<AnnotationId, Annotation>();
+  const evidenceItems = new Map<EvidenceItemId, EvidenceItem>();
+
+  return {
+    documents: {
+      create(document) {
+        documents.set(document.id, document);
+        return document;
+      },
+      get(id) {
+        return documents.get(id) ?? null;
+      },
+      list() {
+        return [...documents.values()];
+      },
+      update(document) {
+        if (!documents.has(document.id)) {
+          throw new Error(`DocumentRepository.update: unknown id ${document.id}`);
+        }
+        documents.set(document.id, document);
+        return document;
+      },
+    },
+    representations: {
+      create(representation) {
+        representations.set(representation.id, representation);
+        return representation;
+      },
+      get(id) {
+        return representations.get(id) ?? null;
+      },
+      listByDocument(documentId) {
+        const out: DocumentRepresentation[] = [];
+        for (const rep of representations.values()) {
+          if (rep.documentId === documentId) out.push(rep);
+        }
+        return out;
+      },
+    },
+    annotations: {
+      create(annotation) {
+        annotations.set(annotation.id, annotation);
+        return annotation;
+      },
+      get(id) {
+        return annotations.get(id) ?? null;
+      },
+      listByDocument(documentId) {
+        const out: Annotation[] = [];
+        for (const ann of annotations.values()) {
+          if (ann.documentId === documentId) out.push(ann);
+        }
+        return out;
+      },
+      update(annotation) {
+        if (!annotations.has(annotation.id)) {
+          throw new Error(`AnnotationRepository.update: unknown id ${annotation.id}`);
+        }
+        annotations.set(annotation.id, annotation);
+        return annotation;
+      },
+    },
+    evidenceItems: {
+      create(item) {
+        evidenceItems.set(item.id, item);
+        return item;
+      },
+      get(id) {
+        return evidenceItems.get(id) ?? null;
+      },
+      listByDocument(documentId, annotationLookup) {
+        const out: EvidenceItem[] = [];
+        for (const item of evidenceItems.values()) {
+          if (item.annotationIds.some((aid) => annotationLookup(aid)?.documentId === documentId)) {
+            out.push(item);
+          }
+        }
+        return out;
+      },
+      update(item) {
+        if (!evidenceItems.has(item.id)) {
+          throw new Error(`EvidenceItemRepository.update: unknown id ${item.id}`);
+        }
+        evidenceItems.set(item.id, item);
+        return item;
+      },
+    },
+  };
+}

src/engine/repos/index.ts

@@ -0,0 +1,8 @@
+export {
+  createInMemoryRepos,
+  type InMemoryRepos,
+  type DocumentRepository,
+  type RepresentationRepository,
+  type AnnotationRepository,
+  type EvidenceItemRepository,
+} from "./in-memory";

src/engine/services/annotations.ts

@@ -0,0 +1,102 @@
+/**
+ * Annotation service — creates technical marks on document ranges and
+ * emits `AnnotationCreated`. Resolution-status updates emit
+ * `AnnotationResolved` / `AnnotationResolutionFailed`.
+ *
+ * Annotation creation is the engine's response to a user action in the
+ * viewer (T07). The viewer adapter has already turned the selection into
+ * `Selector[]`; this service stamps an ID, normalize-version, timestamps,
+ * persists, and broadcasts.
+ */
+
+import type {
+  Annotation,
+  AnnotationResolutionStatus,
+} from "@shared/annotation";
+import type { DocumentId, RepresentationId, AnnotationId } from "@shared/ids";
+import type { Selector } from "@shared/selector";
+import { newId } from "@shared/ids";
+import { NORMALIZE_VERSION } from "@shared/text/normalize";
+
+import type { EventBus } from "../events";
+import type { AnnotationRepository } from "../repos";
+
+export interface CreateAnnotationInput {
+  readonly documentId: DocumentId;
+  readonly representationId?: RepresentationId;
+  readonly selectors: readonly Selector[];
+  readonly quote?: string;
+  readonly note?: string;
+  readonly createdBy?: string;
+}
+
+export interface AnnotationService {
+  create(input: CreateAnnotationInput): Annotation;
+  get(id: AnnotationId): Annotation | null;
+  listByDocument(documentId: DocumentId): readonly Annotation[];
+  setResolutionStatus(
+    id: AnnotationId,
+    status: AnnotationResolutionStatus,
+    opts: { readonly confidence: number; readonly reason?: string },
+  ): Annotation;
+}
+
+export function createAnnotationService(
+  annotations: AnnotationRepository,
+  bus: EventBus,
+  now: () => string = () => new Date().toISOString(),
+): AnnotationService {
+  return {
+    create(input) {
+      const ts = now();
+      const annotation: Annotation = {
+        id: newId("annotation"),
+        documentId: input.documentId,
+        ...(input.representationId !== undefined ? { representationId: input.representationId } : {}),
+        selectors: input.selectors,
+        ...(input.quote !== undefined ? { quote: input.quote } : {}),
+        ...(input.note !== undefined ? { note: input.note } : {}),
+        normalizeVersion: NORMALIZE_VERSION,
+        ...(input.createdBy !== undefined ? { createdBy: input.createdBy } : {}),
+        createdAt: ts,
+        updatedAt: ts,
+      };
+      const stored = annotations.create(annotation);
+      bus.emit({ type: "AnnotationCreated", annotationId: stored.id, annotation: stored });
+      return stored;
+    },
+    get(id) {
+      return annotations.get(id);
+    },
+    listByDocument(documentId) {
+      return annotations.listByDocument(documentId);
+    },
+    setResolutionStatus(id, status, opts) {
+      const existing = annotations.get(id);
+      if (!existing) {
+        throw new Error(`AnnotationService.setResolutionStatus: unknown id ${id}`);
+      }
+      const updated: Annotation = {
+        ...existing,
+        resolutionStatus: status,
+        updatedAt: now(),
+      };
+      const stored = annotations.update(updated);
+      if (status === "unresolved" || status === "stale") {
+        bus.emit({
+          type: "AnnotationResolutionFailed",
+          annotationId: stored.id,
+          reason: opts.reason ?? status,
+        });
+      } else {
+        bus.emit({
+          type: "AnnotationResolved",
+          annotationId: stored.id,
+          status,
+          confidence: opts.confidence,
+        });
+      }
+      return stored;
+    },
+  };
+}

src/engine/services/documents.ts

@@ -0,0 +1,63 @@
+/**
+ * Document service — registers ingested documents and emits the §4 events.
+ *
+ * The ingest pipeline (`src/source/pdf/ingest.ts`) is a pure function over
+ * bytes — it does not touch the engine. The app composition root calls
+ * `ingestPdf` then hands the result to `documentService.register()`, which
+ * is where the engine takes over: persist into the repos, emit
+ * `DocumentImported` + `DocumentRepresentationGenerated`.
+ */
+
+import type { Document, DocumentRepresentation } from "@shared/document";
+import type { DocumentId, RepresentationId } from "@shared/ids";
+
+import type { EventBus } from "../events";
+import type { DocumentRepository, RepresentationRepository } from "../repos";
+
+export interface DocumentService {
+  register(input: {
+    readonly document: Document;
+    readonly representation: DocumentRepresentation;
+  }): { readonly document: Document; readonly representation: DocumentRepresentation };
+  get(id: DocumentId): Document | null;
+  list(): readonly Document[];
+  getRepresentation(id: RepresentationId): DocumentRepresentation | null;
+  listRepresentations(documentId: DocumentId): readonly DocumentRepresentation[];
+}
+
+export function createDocumentService(
+  documents: DocumentRepository,
+  representations: RepresentationRepository,
+  bus: EventBus,
+): DocumentService {
+  return {
+    register({ document, representation }) {
+      const storedDocument = documents.create(document);
+      const storedRepresentation = representations.create(representation);
+      bus.emit({
+        type: "DocumentImported",
+        documentId: storedDocument.id,
+        document: storedDocument,
+      });
+      bus.emit({
+        type: "DocumentRepresentationGenerated",
+        documentId: storedDocument.id,
+        representationId: storedRepresentation.id,
+        representation: storedRepresentation,
+      });
+      return { document: storedDocument, representation: storedRepresentation };
+    },
+    get(id) {
+      return documents.get(id);
+    },
+    list() {
+      return documents.list();
+    },
+    getRepresentation(id) {
+      return representations.get(id);
+    },
+    listRepresentations(documentId) {
+      return representations.listByDocument(documentId);
+    },
+  };
+}

src/engine/services/evidence.ts

@@ -0,0 +1,127 @@
+/**
+ * Evidence service — creates EvidenceItems on top of annotations and
+ * tracks their lifecycle. Emits §4 events: `EvidenceItemCreated`,
+ * `EvidenceItemUpdated`, `EvidenceItemActivated`.
+ *
+ * MVP item shape per `wiki/SharedContracts.md` §2.2: status starts at
+ * `candidate`, may transition to `confirmed | rejected | needs-check`.
+ * Item-level relation/strength (supports/contradicts/...) lives on the
+ * link, not the item — that's CE-WP-0003.
+ */
+
+import type { Annotation } from "@shared/annotation";
+import type {
+  EvidenceItem,
+  EvidenceItemStatus,
+} from "@shared/evidence";
+import type {
+  AnnotationId,
+  DocumentId,
+  EvidenceItemId,
+} from "@shared/ids";
+import { newId } from "@shared/ids";
+
+import type { EventBus, EvidenceItemActivatedEvent } from "../events";
+import type { EvidenceItemRepository } from "../repos";
+
+export interface CreateEvidenceItemInput {
+  readonly annotationIds: readonly AnnotationId[];
+  readonly title?: string;
+  readonly commentary?: string;
+  readonly status?: EvidenceItemStatus;
+  readonly confidence?: number;
+  readonly tags?: readonly string[];
+  readonly createdBy?: string;
+}
+
+export interface EvidenceService {
+  create(input: CreateEvidenceItemInput): EvidenceItem;
+  get(id: EvidenceItemId): EvidenceItem | null;
+  listByDocument(documentId: DocumentId): readonly EvidenceItem[];
+  setStatus(id: EvidenceItemId, status: EvidenceItemStatus): EvidenceItem;
+  updateCommentary(id: EvidenceItemId, commentary: string): EvidenceItem;
+  activate(
+    id: EvidenceItemId,
+    source?: EvidenceItemActivatedEvent["source"],
+  ): EvidenceItem;
+}
+
+export function createEvidenceService(
+  items: EvidenceItemRepository,
+  annotationLookup: (id: AnnotationId) => Annotation | null,
+  bus: EventBus,
+  now: () => string = () => new Date().toISOString(),
+): EvidenceService {
+  return {
+    create(input) {
+      if (input.annotationIds.length === 0) {
+        throw new Error("EvidenceService.create: at least one annotationId is required");
+      }
+      const ts = now();
+      const item: EvidenceItem = {
+        id: newId("evidence"),
+        annotationIds: input.annotationIds,
+        ...(input.title !== undefined ? { title: input.title } : {}),
+        ...(input.commentary !== undefined ? { commentary: input.commentary } : {}),
+        status: input.status ?? "candidate",
+        ...(input.confidence !== undefined ? { confidence: input.confidence } : {}),
+        ...(input.tags !== undefined ? { tags: input.tags } : {}),
+        ...(input.createdBy !== undefined ? { createdBy: input.createdBy } : {}),
+        createdAt: ts,
+        updatedAt: ts,
+      };
+      const stored = items.create(item);
+      bus.emit({ type: "EvidenceItemCreated", evidenceItemId: stored.id, evidenceItem: stored });
+      return stored;
+    },
+    get(id) {
+      return items.get(id);
+    },
+    listByDocument(documentId) {
+      return items.listByDocument(documentId, annotationLookup);
+    },
+    setStatus(id, status) {
+      const existing = items.get(id);
+      if (!existing) {
+        throw new Error(`EvidenceService.setStatus: unknown id ${id}`);
+      }
+      if (existing.status === status) return existing;
+      const updated: EvidenceItem = { ...existing, status, updatedAt: now() };
+      const stored = items.update(updated);
+      bus.emit({
+        type: "EvidenceItemUpdated",
+        evidenceItemId: stored.id,
+        evidenceItem: stored,
+        previousStatus: existing.status,
+      });
+      return stored;
+    },
+    updateCommentary(id, commentary) {
+      const existing = items.get(id);
+      if (!existing) {
+        throw new Error(`EvidenceService.updateCommentary: unknown id ${id}`);
+      }
+      const updated: EvidenceItem = { ...existing, commentary, updatedAt: now() };
+      const stored = items.update(updated);
+      bus.emit({
+        type: "EvidenceItemUpdated",
+        evidenceItemId: stored.id,
+        evidenceItem: stored,
+        previousStatus: existing.status,
+      });
+      return stored;
+    },
+    activate(id, source) {
+      const existing = items.get(id);
+      if (!existing) {
+        throw new Error(`EvidenceService.activate: unknown id ${id}`);
+      }
+      bus.emit({
+        type: "EvidenceItemActivated",
+        evidenceItemId: existing.id,
+        ...(source !== undefined ? { source } : {}),
+      });
+      return existing;
+    },
+  };
+}

src/engine/services/index.ts

@@ -0,0 +1,14 @@
+export {
+  createDocumentService,
+  type DocumentService,
+} from "./documents";
+export {
+  createAnnotationService,
+  type AnnotationService,
+  type CreateAnnotationInput,
+} from "./annotations";
+export {
+  createEvidenceService,
+  type EvidenceService,
+  type CreateEvidenceItemInput,
+} from "./evidence";