evidence-binder/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

Binds evidence items to structured targets and owns the rect-registry contract
that drives the citation-evidence visual guide.

---

## Core Idea

Turn collected evidence into structured, target-bound relationships — "what does
this evidence support, explain, contradict, or source?" — and coordinate the
active `(target, evidence, annotation)` triple so the workspace can draw a visual
guide from a form field to its evidence card to the source highlight.

---

## In Scope

- `EvidenceLink` storage + binding service (link/unlink/update, two query
  directions, canonical bus events)
- active-target / active-evidence / active-annotation state machine + provider
- the SharedContracts §7 rect-registry contract: registry, change pumps, React
  hooks, and the SVG overlay
- a target-neutral reference `FormRenderer` (+ `FieldDefinitionForm`)

---

## Out of Scope

- document ingestion, selector creation/resolution, or viewer internals (that is
  `evidence-anchor` / the engine)
- evidence capture / source panels (`evidence-source`)
- the review workspace and app composition (`citation-work`, umbrella `app/`)
- changing canonical enum vocabularies (owned by the umbrella shared contracts)
- publish/distribution beyond sibling-checkout linking

---

## Relevant When

- linking evidence to form fields, claims, requirements, decisions, or sections
- coordinating which target/evidence/annotation is active
- drawing or consuming the visual guide between panes

---

## Not Relevant When

- you need to import, render, or re-anchor documents (use `evidence-anchor`)
- you need to capture or ingest evidence sources (use `evidence-source`)
- you are wiring the whole app together (that is the umbrella `citation-evidence`)

---

## Current State

- Status: active
- Implementation: substantial (headless core + rect-registry + reference UI extracted, tests green)
- Stability: evolving
- Usage: internal (consumed by the citation-evidence umbrella)

---

## How It Fits

- Upstream dependencies: `citation-engine` (shared types + event bus); `evidence-anchor` (allowed, currently unused)
- Downstream consumers: `citation-evidence` umbrella app
- Often used with: `evidence-anchor`, `citation-engine`

---

## Terminology

- Preferred terms: evidence link, evidence target, rect registry, active triple, visual guide
- Also known as: "binder"
- Potentially confusing terms: dropped legacy relations `derived-from` / `needs-check` are NOT part of the canonical `EvidenceRelation` enum

---

## Related / Overlapping Repositories

- citation-engine — owns shared domain types + the event bus this package emits on
- evidence-anchor — selector/resolution + highlight/scroll contracts (allowed dependency)
- citation-evidence — umbrella app that composes the binder with the rest of the workspace

---

## Getting Oriented

- Start with: `README.md`, then `docs/extraction-inventory.md`
- Key files / directories: `src/services/bindings.ts`, `src/state/active.ts`, `src/visual-guide/rect-registry.ts`, `src/BinderProvider.tsx`
- Entry points: `src/index.ts`

---

## Provided Capabilities

```capability
type: library
title: Evidence-to-target binding
description: Links evidence items to structured targets (form fields, claims, requirements) with relation/status/confidence and two query directions, emitting canonical engine bus events.
keywords: [evidence, binding, evidence-link, form-field, citation-evidence]
```

```capability
type: library
title: Visual-guide rect registry
description: The SharedContracts §7 rect-registry contract — independent renderers publish field/evidence-card/highlight rects into one registry; an SVG overlay draws the active-triple guide without polling.
keywords: [rect-registry, visual-guide, overlay, active-state, citation-evidence]
```

---

## Notes

Extracted from `citation-evidence/src/binder/` under EBIND-WP-0001. Shared-contract
authority remains in the umbrella wiki.