coulomb/evidence-anchor
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

EANCH-WP-0001 T01: codify repo boundary and package shape

Browse source 
Finish SCOPE.md (boundary, maturity, deps, non-goals + capability blocks),
rewrite README.md as an extraction-oriented package doc with the initial
src/ module layout (selectors/pdf/highlight) and public API surface.
Selector types stay in citation-engine; selector behavior + viewer
contract owned here (ADR-0006 / SharedContracts §8).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-07-08 20:34:41 +02:00
parent 41adf77c82
commit 08b3105454
4 changed files with 174 additions and 74 deletions
Download patch file Download diff file Expand all files Collapse all files

21
.claude/ralph-loop.local.md Normal file
View file

@ -0,0 +1,21 @@
---
active: true
iteration: 1
session_id: b236681f-560d-497b-aa7d-07eab42bba2b
max_iterations: 12
completion_promise: "HEUREKA"
workplan_id: EANCH-WP-0001
workplan_file: workplans/EANCH-WP-0001-intent-placeholder.md
started_at: "2026-07-08T18:31:44Z"
---
Read the workplan at `workplans/EANCH-WP-0001-intent-placeholder.md`.
If every task has `status: done` AND frontmatter `status: done`:
run `rm -f .claude/ralph-loop.local.md` first (deactivates the loop so the stop hook exits cleanly),
then output <promise>HEUREKA</promise>.
Otherwise implement the next `todo` task as described in the workplan.
Set task `in_progress` when starting, `done` when complete.
When all tasks are done set frontmatter `status: done`.

86
README.md
View file

@ -1,16 +1,82 @@
# evidence-anchor # evidence-anchor
Selector creation, resolution, and the `DocumentViewerAdapter` contract that Selector creation, resolution, and the `DocumentViewerAdapter` contract that
every document viewer in the workspace implements. every document viewer in the citation-evidence workspace implements. This repo
turns annotations from static marks into durable, reopenable source references.
## MVP status: INTENT only - **Owns:** selector *behavior* — `createSelectors`, `resolveSelectors`, PDF
selector math, the viewer-adapter contract, and highlight/scroll helpers.
- **Does not own:** selector *type interfaces* — those live in `citation-engine`
(`shared/selector`). See `ADR-0006` and `SharedContracts.md` §8.
- **May depend on:** `citation-engine` only (DependencyMap §4). Nothing from
`binder/`, `source/`, or `work/` may flow back into it.
During the citation-evidence MVP, code lives upstream in See `SCOPE.md` for the boundary and `INTENT.md` for the long-range intent.
[`citation-evidence`](../citation-evidence/) under `src/anchor/`. This repo
currently holds `INTENT.md` describing what will move here. Contract
changes belong in
[`citation-evidence/wiki/SharedContracts.md`](../citation-evidence/wiki/SharedContracts.md),
not here.
Per the dependency map, anchor depends on `shared/` and `engine/` only; ## Status: extracting from the umbrella
nothing in `binder/`, `source/`, or `work/` may flow back into it.
The concrete anchor slice currently lives upstream in
[`../citation-evidence/src/anchor/`](../citation-evidence/src/anchor/). Workplan
`EANCH-WP-0001` moves it here as a standalone TypeScript package, wires the
umbrella to consume this package, and verifies the round-trip. Shared-contract
changes still happen in the umbrella (`citation-evidence/wiki/`), not here.
## Install model
Sibling-checkout, linked-package model — this repo is checked out next to its
consumers and consumed via a local link (e.g. `link:../evidence-anchor`), not
published to a registry during MVP. Its only shared-type dependency is
`citation-engine`, imported through the engine's public `shared` entrypoint
(`@citation-evidence/engine/shared`) rather than umbrella-only `@shared/*`
aliases.
## Package layout (initial extracted version)
```text
src/
index.ts public entrypoint (re-exports the surfaces below)
types.ts adapter-side types: SelectionCapture,
ResolvedAnchorTarget, AnchorResolution,
HighlightRenderOptions, DocumentViewerAdapter
selectors/
index.ts createSelectors, resolveSelectors, DEFAULT_CONTEXT_CHARS
create.ts selector creation from a captured selection
resolve.ts resolution + the exact-match confidence ladder
create.test.ts
resolve.test.ts
pdf/
pdf-selector-math.ts page number + normalized page-rectangle math
pdf-selector-math.test.ts
pdf-viewer-adapter.tsx concrete PDF DocumentViewerAdapter (from the spike)
highlight/
scroll-job.ts scroll-to-target helper
scroll-job.test.ts
highlight-styles.css highlight rendering styles
debug-textlayer.css optional text-layer debugging styles
```
Boundary rules for the layout:
- viewer-library imports (`pdfjs`, `react-pdf-highlighter-plus`) are confined to
`src/pdf/` — they never appear on `types.ts` or on the public surface;
- `src/selectors/` is pure (no viewer/UI deps) and depends only on
`citation-engine` shared types;
- the public entrypoint re-exports the stable surface consumers rely on:
`createSelectors`, `resolveSelectors`, the selector/resolution types, the
`DocumentViewerAdapter` contract, and the PDF adapter.
## Public API (target surface)
```ts
import {
createSelectors,
resolveSelectors,
type DocumentViewerAdapter,
type AnchorResolution,
} from "evidence-anchor";
```
Resolution is explicit about uncertainty — `AnchorResolution.status` is one of
`resolved` / `ambiguous` / `unresolved` / `stale` with a `0..1` confidence, so a
caller can highlight, ask the user to confirm, or mark a citation stale rather
than silently highlight the wrong passage.

139
SCOPE.md
View file

@ -8,130 +8,143 @@
## One-liner ## One-liner
<!-- Describe the purpose of this repository in one precise sentence. --> Selector creation, resolution, re-anchoring, and highlight/scroll contracts that
<!-- Example: "Provides a lightweight event router for Kubernetes-native systems." --> keep citation-evidence annotations attached to their source passages.
--- ---
## Core Idea ## Core Idea
<!-- What is the main capability or idea behind this repository? --> An **anchor** is a resolvable reference to a passage in a document, represented
<!-- What problem does it try to solve? --> 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 ## In Scope
<!-- What this repository is responsible for. --> - selector **creation** from a captured viewer selection (`createSelectors`)
<!-- Be explicit and concrete. --> - 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 ## Out of Scope
<!-- What this repository deliberately does NOT do. --> - selector *type definitions* — owned by `citation-engine` (`shared/selector`)
<!-- This is often more important than "In Scope". --> - 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 ## Relevant When
<!-- When should someone consider using or exploring this repository? --> - 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 ## Not Relevant When
<!-- When should someone ignore this repository? --> - 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 ## Current State
<!-- Rough indication of maturity. No strict format required. --> - Status: experimental — extracting from the umbrella into a standalone package
- Implementation: partial — pure selector + PDF adapter slice exists upstream in
- Status: <!-- e.g. concept / experimental / active / stable / deprecated --> `../citation-evidence/src/anchor/`; extraction tracked by EANCH-WP-0001
- Implementation: <!-- e.g. idea / partial / substantial / complete --> - Stability: evolving — shared contracts stable, this repo's package API forming
- Stability: <!-- e.g. unstable / evolving / stable --> - Usage: internal (consumed by `citation-evidence` during MVP)
- Usage: <!-- e.g. none / personal / internal / production -->
<!-- Add any notes that help set expectations. -->
--- ---
## How It Fits ## How It Fits
<!-- Where does this repository sit in the bigger picture? --> - Upstream dependencies: `citation-engine` (shared selector/document/annotation types)
- Downstream consumers: `citation-evidence` (umbrella), later `citation-work`,
- Upstream dependencies: `evidence-source`, `evidence-binder`
- Downstream consumers: - Often used with: a concrete document viewer (PDF.js + react-pdf-highlighter-plus)
- Often used with:
--- ---
## Terminology ## Terminology
<!-- Terms that are important to understand this repo. --> - Preferred terms: anchor, selector, resolution, re-anchoring, highlight contract
<!-- Especially useful if naming differs from other repos. --> - Also known as: "the anchoring layer"
- Potentially confusing terms: `Selector` (the *type* is engine-owned; the
- Preferred terms: *behavior* is anchor-owned — see ADR-0006)
- Also known as:
- Potentially confusing terms:
--- ---
## Related / Overlapping Repositories ## Related / Overlapping Repositories
<!-- List repositories that have similar or adjacent responsibilities. --> - `citation-engine` — owns shared selector/document/annotation type interfaces
<!-- Helps detect duplication and navigate the ecosystem. --> - `citation-evidence` — umbrella; current home of the code being extracted
- `evidence-source` — document ingestion / representations (consumer)
- <repo-name> — <!-- how it relates --> - `citation-work` — review workspace UX (consumer)
- `evidence-binder` — evidence-to-target binding (consumer)
--- ---
## Getting Oriented ## Getting Oriented
<!-- If someone decides to look deeper, where should they start? --> - Start with: `INTENT.md` (intended responsibilities), then this file
- Key files / directories: upstream `../citation-evidence/src/anchor/` is the
- Start with: extraction source; post-extraction the package layout is in `README.md`
- Key files / directories: - Entry points: `createSelectors`, `resolveSelectors`, `DocumentViewerAdapter`
- Entry points:
--- ---
## Provided Capabilities ## Provided Capabilities
<!-- What can this repo's domain provide to other domains on request? -->
<!-- Each capability block is parsed by the state-hub capability catalog ingest. -->
<!-- Remove the examples and add your own, or leave empty if none. -->
<!--
```capability ```capability
type: infrastructure type: library
title: Example capability title title: Durable citation anchoring (selectors + resolution)
description: What this capability provides, in one or two sentences. 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: [keyword1, keyword2, keyword3] 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 ## Notes
<!-- Anything else worth knowing. Keep it short. --> 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`.

2
workplans/EANCH-WP-0001-intent-placeholder.md
View file

@ -104,7 +104,7 @@ T01 boundary + package shape
```task ```task
id: EANCH-WP-0001-T01 id: EANCH-WP-0001-T01
priority: high priority: high
status: todo status: done
state_hub_task_id: "ef88ff6a-590f-4858-a674-33f84c1d6116" state_hub_task_id: "ef88ff6a-590f-4858-a674-33f84c1d6116"
``` ```