evidence-anchor/workplans/EANCH-WP-0002-anchor-resolution-hardening.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	spec_refs	state_hub_workstream_id
EANCH-WP-0002	workplan	Anchor resolution hardening: stale/orphan semantics, fuzzy re-anchoring, production PDF adapter	infotech	evidence-anchor	proposed	codex	citation_evidence_mvp	2026-07-08	2026-07-08	INTENT.md SCOPE.md ../citation-evidence/wiki/SharedContracts.md ../citation-evidence/wiki/ArchitectureOverview.md	2e1ad557-11d9-4e5c-8743-973002482a0c

EANCH-WP-0002 — Anchor Resolution Hardening

Goal

Close the resolution-quality gaps left open by the MVP extraction (EANCH-WP-0001) on the existing PDF/text path. The extracted slice resolves exact position/quote/PDF selectors with a fixed confidence ladder and returns resolved | ambiguous | unresolved. INTENT.md promises more: stale detection, orphaned-annotation handling, fuzzy/recovery re-anchoring, and human-confirmation workflows for ambiguity. This workplan makes those real without changing the shared selector types (those stay in citation-engine).

Non-goals: HTML/Markdown selectors (see EANCH-WP-0003); new persistence or UI shell behavior.

Background

Current extracted behavior (src/selectors/resolve.ts):

• confidence ladder 1.00 → 0.70 across TextPosition/TextQuote/PdfPageText/PdfRect
• multiple undisambiguated quote matches → ambiguous at 0.5
• nothing matches → unresolved at 0.0
• there is no stale path (the AnnotationResolutionStatus enum includes stale, but resolve.ts never returns it) and no fuzzy matching

Task Breakdown

T01 — Stale vs. unresolved: distinguish "representation changed" from "never found"

id: EANCH-WP-0002-T01
status: todo
priority: high
state_hub_task_id: "940b03ba-4b2f-4d1a-b7bc-72813817549d"

Return stale (not unresolved) when a previously-resolvable anchor no longer matches because the representation's canonical text changed, while the stored quote is still meaningful. Define the signal (e.g. position selector points in-range but slice ≠ quote AND quote no longer found) and preserve the original quote/context on the result. Add unit tests covering stale vs. unresolved.

T02 — Orphaned-annotation detection surface

id: EANCH-WP-0002-T02
status: todo
priority: medium
depends_on: [T01]
state_hub_task_id: "f75b94cd-bfb8-47f9-bd89-0d605f925290"

Give callers a way to identify annotations whose selectors can no longer be placed at all (orphaned) versus stale-but-recoverable. Decide whether this is a distinct status, a flag on AnchorResolution, or a helper. Keep the shared enum unchanged unless a contract change is agreed in the umbrella wiki first.

T03 — Fuzzy / recovery re-anchoring

id: EANCH-WP-0002-T03
status: todo
priority: high
depends_on: [T01]
state_hub_task_id: "8548fa44-5bb3-40cf-b8f8-e745deae7dda"

Add a fuzzy quote-matching fallback (bounded edit-distance / token overlap) below the exact ladder, returning candidates at appropriately low confidence with ambiguous/stale status. Must never silently emit a confident wrong match (INTENT: "No Silent Misleading Match"). Add tests with lightly-edited source text. Confirm the ladder's exact tiers are untouched above the fuzzy floor.

T04 — Promote the PDF spike to a production adapter

id: EANCH-WP-0002-T04
status: todo
priority: medium
depends_on: [T03]
state_hub_task_id: "6a7163f5-39ca-48fa-8941-8459c563198f"

Turn PdfSpikeViewer into a supported PDFViewerAdapter that implements the DocumentViewerAdapter contract cleanly (remove spike-only debug flags from the public surface, or gate them), keep viewer libs behind src/pdf/, and keep the umbrella green through the change. Update evidence-anchor/pdf exports and docs.

T05 — Verification + close-out

id: EANCH-WP-0002-T05
status: todo
priority: high
depends_on: [T02, T04]
state_hub_task_id: "1ea0885a-c541-438f-a4fd-b8be0773b373"

pnpm test/typecheck/lint green here; umbrella typecheck/test/build green after any contract-visible change; fix-consistency clean; progress note.