EANCH-WP-0001 T01: codify repo boundary and package shape
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:
parent
41adf77c82
commit
08b3105454
4 changed files with 174 additions and 74 deletions
139
SCOPE.md
139
SCOPE.md
|
|
@ -8,130 +8,143 @@
|
|||
|
||||
## One-liner
|
||||
|
||||
<!-- Describe the purpose of this repository in one precise sentence. -->
|
||||
<!-- Example: "Provides a lightweight event router for Kubernetes-native systems." -->
|
||||
Selector creation, resolution, re-anchoring, and highlight/scroll contracts that
|
||||
keep citation-evidence annotations attached to their source passages.
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
|
||||
<!-- What is the main capability or idea behind this repository? -->
|
||||
<!-- What problem does it try to solve? -->
|
||||
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
|
||||
|
||||
<!-- What this repository is responsible for. -->
|
||||
<!-- Be explicit and concrete. -->
|
||||
- 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
|
||||
|
||||
<!-- What this repository deliberately does NOT do. -->
|
||||
<!-- This is often more important than "In 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
|
||||
|
||||
<!-- 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
|
||||
|
||||
<!-- 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
|
||||
|
||||
<!-- Rough indication of maturity. No strict format required. -->
|
||||
|
||||
- Status: <!-- e.g. concept / experimental / active / stable / deprecated -->
|
||||
- Implementation: <!-- e.g. idea / partial / substantial / complete -->
|
||||
- Stability: <!-- e.g. unstable / evolving / stable -->
|
||||
- Usage: <!-- e.g. none / personal / internal / production -->
|
||||
|
||||
<!-- Add any notes that help set expectations. -->
|
||||
- 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
|
||||
|
||||
<!-- Where does this repository sit in the bigger picture? -->
|
||||
|
||||
- Upstream dependencies:
|
||||
- Downstream consumers:
|
||||
- Often used with:
|
||||
- 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
|
||||
|
||||
<!-- Terms that are important to understand this repo. -->
|
||||
<!-- Especially useful if naming differs from other repos. -->
|
||||
|
||||
- Preferred terms:
|
||||
- Also known as:
|
||||
- Potentially confusing terms:
|
||||
- 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
|
||||
|
||||
<!-- List repositories that have similar or adjacent responsibilities. -->
|
||||
<!-- Helps detect duplication and navigate the ecosystem. -->
|
||||
|
||||
- <repo-name> — <!-- how it relates -->
|
||||
- `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
|
||||
|
||||
<!-- If someone decides to look deeper, where should they start? -->
|
||||
|
||||
- Start with:
|
||||
- Key files / directories:
|
||||
- Entry points:
|
||||
- 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
|
||||
|
||||
<!-- 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
|
||||
type: infrastructure
|
||||
title: Example capability title
|
||||
description: What this capability provides, in one or two sentences.
|
||||
keywords: [keyword1, keyword2, keyword3]
|
||||
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
|
||||
|
||||
<!-- 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`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue