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: maintained
• 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

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]

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.