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, fuzzy recovery floor, and selector-redundancy rules
- PDF selector math (page number + normalized page rectangles, page-local text)
- DOM/structural selector creation and resolution for HTML/Markdown
- the format-neutral `DocumentViewerAdapter` contract, the PDF adapter, and the HTML viewer
- 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).

### Still deferred (beyond EANCH-WP-0004)

- `FragmentSelector` (export-only deep links)
- human-confirmation UI for ambiguous/fuzzy matches

---

## 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: active — standalone package consumed by `citation-evidence`
- Implementation: PDF + HTML/Markdown selector paths, stale/orphan/fuzzy resolution,
  `PdfViewerAdapter`, and `HtmlViewerAdapter` (`evidence-anchor/dom`)
- Stability: evolving — shared contracts stable; HTML/MD wired in `citation-work` ViewerShell
- 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

```capability
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]
```

```capability
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`.