evidence-binder/INTENT.md

# INTENT

## Purpose

This repository exists to provide the evidence binding layer for the **citation-evidence** ecosystem.

**evidence-binder** connects evidence items to structured targets such as form fields, claims, requirements, decisions, document sections, tasks, or other information objects.

It is responsible for answering the binding question:

> What does this evidence support, explain, contradict, or source?

---

## Primary Utility

The repository provides the model and interaction logic for turning collected evidence into structured support for information work.

It should make it possible to:

- link evidence items to form fields,
- link evidence items to claims, requirements, decisions, or document sections,
- group evidence items into evidence sets,
- express relation types such as supports, contradicts, explains, qualifies, or source-for,
- track evidence status and confidence per target,
- switch between multiple evidence items connected to the same target,
- coordinate active target, active evidence item, and active source annotation,
- support visual guidance from structured target to evidence to source context.

This repository turns collected citations into actionable evidence relationships.

---

## Intended Users

Primary users of this repository are developers and agents implementing evidence-backed workflows.

They include:

- developers building evidence-backed forms,
- developers building claim or requirement review tools,
- developers implementing source-backed decision workflows,
- developers connecting document evidence to structured data,
- coding agents helping users identify, bind, inspect, or validate evidence,
- application developers integrating citation-evidence into domain-specific systems.

End users should experience this repository whenever they see which source passage supports a field, claim, requirement, or decision.

---

## Strategic Role

The strategic role of **evidence-binder** is to make citation-evidence more than a document annotation system.

Annotations and evidence items become much more valuable when they are connected to the things they justify.

This repository provides that connection.

It enables the flow:

```text
Evidence Item
  → Evidence Link
  → Evidence Target
  → Evidence Set
  → Supported Field / Claim / Requirement / Decision
````

The repository should make it possible to inspect not only where evidence came from, but also what it is being used for.

---

## Core Concept

The core concept of this repository is the **evidence link**.

An evidence link connects an evidence item to a structured target with a meaningful relation.

Examples:

```text
Evidence Item A supports Form Field X
Evidence Item B contradicts Claim Y
Evidence Item C explains Requirement Z
Evidence Item D is the source for Decision Q
Evidence Item E qualifies Document Section S
```

The evidence link is not just a technical pointer. It expresses an interpretive relationship between source material and structured work.

---

## Scope

This repository should own:

* evidence-to-target binding model,
* evidence link lifecycle,
* evidence sets,
* target adapters,
* relation types,
* target evidence status,
* field evidence state,
* active target and active evidence state,
* evidence switching behavior,
* evidence completeness indicators,
* support for multiple evidence items per target,
* support for evidence that supports or contradicts a target,
* visual guide model connecting target, evidence card, and source highlight,
* interaction contracts for evidence-backed forms and structured review workflows.

It should provide the binding capabilities consumed by:

* **citation-evidence** for the integrated workspace,
* **citation-work** when collected evidence is prepared for later use,
* **citation-engine** through shared domain contracts,
* **evidence-anchor** when linked evidence must reopen source context,
* **evidence-source** when evidence requires source context metadata.

---

## Out of Scope

This repository should not own the broader system internals.

Specifically, it should not own:

* the canonical document and annotation model,
* document ingestion,
* text extraction,
* citation recovery,
* low-level selector resolution,
* viewer-specific highlighting,
* review workspace UI,
* citation card rendering internals,
* persistence implementation details,
* application shell and deployment,
* domain-specific form schemas beyond generic target adapters.

Those responsibilities belong to the appropriate citation-evidence subsystem repositories.

---

## Architectural Position

```text
citation-evidence
  integrated product shell and reference workspace

citation-engine
  core domain model, services, persistence contracts

evidence-binder
  evidence links, evidence sets, target binding, active evidence state

citation-work
  document review and evidence capture workflow

evidence-anchor
  selector resolution and source-context highlighting

evidence-source
  document ingestion, representations, and source context
```

**evidence-binder** sits between evidence objects and the structured targets that use them.

It should not define what documents are or how annotations resolve. It should define how evidence is attached to meaningful targets.

---

## Primary Workflows

### 1. Link Evidence to a Form Field

A user selects an evidence item and attaches it to a form field.

```text
Active Form Field
  → Select Evidence Item
  → Create Evidence Link
  → Mark Relation as supports / explains / source-for
  → Update Field Evidence State
```

### 2. Focus Field and Show Evidence

A user activates a field that has linked evidence.

```text
Focus Form Field
  → Load Evidence Set
  → Select Active Evidence Item
  → Request Source Context
  → Highlight Evidence Card
  → Highlight Source Annotation
```

### 3. Switch Between Evidence Items

A target has several evidence items. The user switches between them.

```text
Evidence Set
  → Next / Previous Evidence Item
  → Update Active Evidence
  → Resolve Annotation
  → Scroll Source Viewer
  → Update Visual Guide
```

### 4. Bind Evidence to a Claim or Requirement

Evidence is linked to a structured non-form target.

```text
Claim / Requirement / Decision
  → Attach Evidence Item
  → Set Relation
  → Set Status / Confidence
  → Make Evidence Traceable
```

### 5. Inspect Evidence Completeness

A user or agent checks whether a target has sufficient evidence.

```text
Target
  → Load Evidence Links
  → Evaluate Required Evidence Policy
  → Show none / candidate / confirmed / conflicting / insufficient
```

---

## Target Model

The repository should support generic evidence targets.

Initial target types may include:

```text
form-field
claim
requirement
decision
document-section
task
record-field
```

The model should not assume that all targets are form fields.

A target should be addressable through a generic structure such as:

```ts
type EvidenceTarget = {
  type: string;
  id: string;
  label?: string;
  context?: Record<string, unknown>;
};
```

This allows domain-specific systems to add their own target types without changing the core binding model.

---

## Relation Types

Initial evidence relations may include:

```text
supports
contradicts
explains
source-for
qualifies
context-for
derived-from
needs-check
```

The first version should keep relation types simple but explicit.

The relation should describe how the evidence item is being used with respect to the target.

---

## Evidence State

The repository should support target-specific evidence state.

Examples:

```text
no-evidence
candidate-evidence
confirmed-evidence
conflicting-evidence
insufficient-evidence
needs-review
verified
```

An evidence item may be generally confirmed, but its relationship to a specific target may still need review.

Therefore, evidence item status and evidence link status should be distinguishable.

---

## Visual Guide Concept

For evidence-backed form and structured review workflows, the user should be able to visually understand the connection between:

```text
structured target
  → evidence item / citation card
  → source annotation / highlighted passage
```

The repository should own the model and interaction state for this visual guide, not necessarily the final rendering implementation.

A visual guide may use:

```text
active target rect
active evidence card rect
active annotation rect
connector state
focus state
hover state
selection state
```

Rendering may be done by an application layer using SVG, canvas, or DOM overlays.

---

## Design Principles

### Evidence Links Are First-Class

A binding between evidence and target is not just metadata. It is a meaningful domain object.

### Evidence Is Reusable

The same evidence item may support multiple targets.

### Targets Are Generic

The model should support form fields first, but not be limited to forms.

### Relation Is Explicit

The system should distinguish evidence that supports, contradicts, explains, qualifies, or merely sources a target.

### Active State Is Shared

Evidence-backed workflows require coordinated active state across field, evidence item, and document highlight.

### Source Context Remains External

The repository should request source context through **citation-engine** and **evidence-anchor**, not resolve highlights itself.

### UI Logic Should Be Portable

The binding model should be reusable in different interfaces: forms, claim review, requirements tools, audit trails, and reports.

### Agent Compatibility

Evidence links should be machine-readable so agents can inspect missing evidence, weak evidence, contradictions, and unsupported fields.

---

## Expected Dependencies

This repository is expected to depend on shared types and contracts from:

```text
citation-engine
  EvidenceItem, EvidenceLink, EvidenceSet, CitationTarget, service contracts
```

It may interact with:

```text
evidence-anchor
  to request source resolution for active evidence

citation-work
  to receive collected evidence items

evidence-source
  to access source metadata and document context

citation-evidence
  to integrate evidence-backed forms and structured workflows
```

It should avoid direct dependency on viewer internals or document ingestion internals.

---

## First Useful Version

A first useful version of **evidence-binder** should provide:

* generic evidence target model,
* evidence link model,
* evidence set model,
* relation type model,
* target evidence state model,
* simple in-memory binding service,
* active target / active evidence state handling,
* helper logic for linking evidence to form fields,
* helper logic for listing evidence by target,
* helper logic for switching active evidence,
* initial visual guide state model.

The first version does not need a full form renderer, but it should make evidence-backed form workflows possible.

---

## Success Criteria

The repository is successful when another subsystem can use it to:

1. define a structured target such as a form field,
2. attach one or more evidence items to that target,
3. describe the relation between evidence and target,
4. retrieve all evidence for the target,
5. activate one evidence item,
6. coordinate target, evidence card, and source annotation state,
7. indicate whether the target has sufficient evidence.

A developer or coding agent should be able to understand from this repository how evidence becomes connected to structured work.

---

## Repository Character

This repository should be:

* relationship-focused,
* target-neutral,
* form-friendly but not form-limited,
* explicit about evidence relations,
* lightweight at first,
* compatible with multiple UI shells,
* useful for both human review and agentic inspection,
* careful not to absorb document or anchoring responsibilities.

---

## MVP Coordination — Code Lives Upstream

During the umbrella-first MVP phase (decided 2026-05-24), **the source code
for this subsystem does not live in this repository yet**. It lives in the
umbrella repo at `citation-evidence/src/binder/`.

This INTENT.md documents the *intended* responsibilities and boundaries.
When the binding model and visual-guide rect-registry contract have stabilized
through actual MVP use, the corresponding code extracts into this repository.

**Shared contracts** (EvidenceLink.status enum, EvidenceLink.relation enum,
EvidenceSet shape, rect registry contract, allowed dependency edges) are
maintained in the umbrella repo:

* `citation-evidence/wiki/SharedContracts.md`
* `citation-evidence/wiki/DependencyMap.md`
* `citation-evidence/docs/decisions/` (ADRs)

This subsystem's eventual code must not contradict those documents. The
target-evidence-state vocabulary in the original INTENT
(`no-evidence|candidate|confirmed|conflicting|insufficient|verified`) is now
canonical in `SharedContracts.md` §2.4. The relation vocabulary
(`supports|contradicts|explains|qualifies|source-for|context-for`) is now
canonical in `SharedContracts.md` §2.5; `derived-from` and `needs-check`
were dropped — `derived-from` is a domain-specific extension, `needs-check`
belongs on link status.

Under the dependency map, **`evidence-binder` may depend on `citation-engine`
and `evidence-anchor`** — but NOT on `evidence-source` or `citation-work`.
When the binder needs source context, it asks `evidence-anchor` to resolve
the annotation.

---

## Guiding Statement

**evidence-binder exists to connect cited evidence to the structured things it supports.**