tegwick
a10f080f12
Extracts citation-evidence/src/binder/ into this repo as the standalone @citation-evidence/evidence-binder package: headless binding service + in-memory link repo, active-state machine, the SharedContracts §7 rect-registry contract (registry, change pumps, hooks, SVG overlay), and the target-neutral reference FormRenderer. - toolchain mirrors sibling extracted repos (pnpm/tsc/vitest/eslint); imports rewritten from @shared/@engine aliases to the engine's @citation-evidence/engine package specifiers - dependency boundary (engine + anchor only; no source/work/umbrella) enforced via eslint no-restricted-imports - docs: extraction inventory + contract deltas, ADR-0001 (reference UI kept as supported exports), refreshed README/SCOPE/INTENT, populated capabilities index - typecheck + lint green, 37 tests passing Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
125 lines
4 KiB
Markdown
125 lines
4 KiB
Markdown
# 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.
|