evidence-anchor/SCOPE.md

SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

---

One-liner

Selector creation, resolution, re-anchoring, and highlight/scroll contracts that keep citation-evidence annotations attached to their source passages.

---

Core Idea

An anchor is a resolvable reference to a passage in a document, represented by several complementary selectors (visual, text, structural, context). Given a stored selector set and a document representation, this repo answers: where is this passage now, and how confident are we? — returning a confidence-scored result (resolved / ambiguous / unresolved / stale) rather than a silent guess. It also owns the DocumentViewerAdapter contract every viewer implements.

---

In Scope

• selector creation from a captured viewer selection (createSelectors)
• selector resolution against a document representation (resolveSelectors)
• the exact-match confidence ladder and selector-redundancy rules
• PDF selector math (page number + normalized page rectangles, page-local text)
• the format-neutral DocumentViewerAdapter contract and the first PDF adapter
• scroll-to-target and highlight-render contracts + helpers
• anchor confidence scoring and ambiguous/unresolved/stale reporting

Selector behavior lives here; selector type interfaces live in citation-engine (see ADR-0006 and SharedContracts §8).

---

Out of Scope

• selector type definitions — owned by citation-engine (shared/selector)
• persistence policy, the canonical evidence domain model, citation-card rendering
• document ingestion, OCR, metadata extraction, external source lookup
• form-field binding semantics, guide-overlay UI, application shell / deployment
• becoming a viewer implementation itself (it defines the adapter, not the viewer)

During the umbrella-first MVP these belong to the appropriate citation-evidence subsystem. This repo may depend on citation-engine only (DependencyMap §4).

Not in this extraction slice (EANCH-WP-0001)

• full HTML/Markdown (DomSelectionCapture) selector implementation
• production-grade fuzzy / recovery-oriented re-anchoring
• stale and orphaned-annotation semantics beyond what upstream already ships

These are real INTENT.md goals but are registered as follow-on work, not built during the initial extract-and-verify pass.

---

Relevant When

• creating anchors from a user text selection in a document viewer
• resolving stored selectors back into a representation to reopen a citation
• implementing a new DocumentViewerAdapter (PDF today; HTML/Markdown later)
• scrolling to and highlighting a cited passage

---

Not Relevant When

• you need selector type shapes only — import from citation-engine
• you are working on ingestion, persistence, binding, or the app shell
• you need the integrated review workspace UX — that is citation-work / umbrella

---

Current State

• Status: experimental — extracting from the umbrella into a standalone package
• Implementation: partial — pure selector + PDF adapter slice exists upstream in ../citation-evidence/src/anchor/; extraction tracked by EANCH-WP-0001
• Stability: evolving — shared contracts stable, this repo's package API forming
• Usage: internal (consumed by citation-evidence during MVP)

---

How It Fits

• Upstream dependencies: citation-engine (shared selector/document/annotation types)
• Downstream consumers: citation-evidence (umbrella), later citation-work, evidence-source, evidence-binder
• Often used with: a concrete document viewer (PDF.js + react-pdf-highlighter-plus)

---

Terminology

• Preferred terms: anchor, selector, resolution, re-anchoring, highlight contract
• Also known as: "the anchoring layer"
• Potentially confusing terms: Selector (the type is engine-owned; the behavior is anchor-owned — see ADR-0006)

---

Related / Overlapping Repositories

• citation-engine — owns shared selector/document/annotation type interfaces
• citation-evidence — umbrella; current home of the code being extracted
• evidence-source — document ingestion / representations (consumer)
• citation-work — review workspace UX (consumer)
• evidence-binder — evidence-to-target binding (consumer)

---

Getting Oriented

• Start with: INTENT.md (intended responsibilities), then this file
• Key files / directories: upstream ../citation-evidence/src/anchor/ is the extraction source; post-extraction the package layout is in README.md
• Entry points: createSelectors, resolveSelectors, DocumentViewerAdapter

---

Provided Capabilities

type: library
title: Durable citation anchoring (selectors + resolution)
description: Create redundant selectors for a document passage and resolve them back into a representation with a confidence-scored result, so citations survive zoom, re-render, and light source edits.
keywords: [anchor, selector, resolution, citation, highlight, pdf]

type: interface
title: DocumentViewerAdapter contract
description: A format-neutral viewer adapter contract (selection capture, selector creation, resolution, scroll-to-target, highlight render) that any document viewer implements; PDF adapter provided first.
keywords: [viewer, adapter, highlight, scroll, pdf, contract]

---

Notes

Shared contracts are maintained in the umbrella and must not be contradicted here: citation-evidence/wiki/SharedContracts.md, wiki/DependencyMap.md, docs/decisions/ADR-0006-selector-ownership-split.md.