Extract binder package from citation-evidence (EBIND-WP-0001)

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>
2026-07-09 01:36:33 +02:00 · 2026-07-09 01:36:33 +02:00 · a10f080f12
commit a10f080f12
parent 87d4eb3006
36 changed files with 6643 additions and 170 deletions
--- a/workplans/EBIND-WP-0001-intent-placeholder.md
+++ b/workplans/EBIND-WP-0001-intent-placeholder.md
@ -4,97 +4,149 @@ type: workplan
 title: "Extract evidence-binder from citation-evidence"
 domain: infotech
 repo: evidence-binder
-status: ready
+status: done
 owner: codex
 topic_slug: citation_evidence_mvp
 created: "2026-06-21"
-updated: "2026-07-08"
+updated: "2026-07-09"
 state_hub_workstream_id: "405d789c-0e0b-4764-89ed-0f6140a143e7"
 ---

 # EBIND-WP-0001 — Extract evidence-binder from citation-evidence

-`evidence-binder` is still INTENT-only in this repo, but the current
-implementation already exists upstream in `../citation-evidence/src/binder/`.
-That slice includes a binding service, in-memory link repository, active-state
-machine, rect registry and overlay, provider wiring, and a small form-oriented
-reference UI. This workplan turns the placeholder into a concrete extraction
-plan that preserves the canonical contracts in
-`../citation-evidence/wiki/SharedContracts.md` and the allowed edges in
-`../citation-evidence/wiki/DependencyMap.md`.
+Extract `../citation-evidence/src/binder/` into this repository as a standalone
+package without changing the binder's canonical responsibilities: evidence
+links, active target/evidence state, and the visual-guide rect registry.

-## Lock Extraction Boundary And Contract Deltas
+The extracted package must conform to
+`../citation-evidence/wiki/SharedContracts.md`, respect
+`../citation-evidence/wiki/DependencyMap.md`, and remain dependent on
+`citation-engine` and `evidence-anchor` only.
+
+Prerequisites:
+
+- umbrella MVP binder slice already exists in `../citation-evidence/src/binder/`
+- `citation-engine` is already extracted and available as a sibling package
+- shared contract authority remains in the umbrella docs until binder extraction
+  is complete
+
+## Goals
+
+1. This repo becomes the canonical home of the binder implementation.
+2. Umbrella behavior remains unchanged after wireup.
+3. The extracted package stays target-neutral and does not pick up forbidden
+   `citation-work` or `evidence-source` dependencies.
+4. Tests, lint, and typecheck are green in both this repo and the umbrella
+   consumer after cutover.
+
+## Dependency Order
+
+```text
+T01 (boundary + contract lock)
+  └─ T02 (toolchain + package scaffold)
+       ├─ T03 (headless bindings + provider extraction)
+       │    └─ T04 (visual guide extraction)
+       ├─ T05 (reference UI surface decision)
+       └─ T06 (docs + local contract references)
+            └─ T07 (umbrella wireup)
+                 └─ T08 (verification + closeout)
+```
+
+---
+
+## T01 — Lock extraction boundary and contract deltas

 ```task
 id: EBIND-WP-0001-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "f2abe7f8-089b-4719-a739-18dc3224e9eb"
 ```

-Review the upstream binder slice (`services/`, `repos/`, `state/`,
-`visual-guide/`, `BinderProvider.tsx`, `FormRenderer.tsx`) against
-`SharedContracts.md` sections 2.4, 2.5, 4, and 7 plus `DependencyMap.md`
-section 2. Capture and resolve remaining deltas before extraction, including
-INTENT drift around `EvidenceTarget` naming, the dropped
-`derived-from` / `needs-check` relation values, and any event vocabulary that
-is not yet canonicalized.
+Review the upstream binder slice against the current shared contracts before any
+code moves:

-## Stand Up Standalone Package, Tests, And Repo Metadata
+- `services/`, `repos/`, `state/`, `visual-guide/`
+- `BinderProvider.tsx`, `FormRenderer.tsx`, `FieldDefinitionForm.tsx`
+- `../citation-evidence/wiki/SharedContracts.md` sections 2.4, 2.5, 4, and 7
+- `../citation-evidence/wiki/DependencyMap.md` section 2
+
+Resolve or explicitly record:
+
+- INTENT drift around `EvidenceTarget` naming and target vocabulary
+- dropped relation values `derived-from` / `needs-check`
+- event vocabulary mismatches such as removal semantics versus the canonical bus
+- exact files that extract into this repo versus remain umbrella-only
+
+Acceptance:
+
+- extraction inventory is explicit and bounded
+- no unresolved contract contradiction remains hidden in `INTENT.md`
+- forbidden dependency edges are called out before code copy starts
+
+## T02 — Stand up standalone package, tests, and repo metadata

 ```task
 id: EBIND-WP-0001-T02
-status: todo
+status: done
 priority: high
 state_hub_task_id: "122a254f-6490-4211-bde7-ce515c72c36a"
 ```

-Create the standalone package and test harness that this repo currently lacks,
-then refresh repo-local metadata so it stops looking like a placeholder. This
-includes package entrypoints, test scripts, baseline CI/tooling, `README.md`,
-`SCOPE.md`, and the stale capability metadata in
-`registry/indexes/capabilities.yaml`.
+Create the package scaffold this repo currently lacks:

-## Extract Headless Binding Model And Repository
+- `package.json` with `test`, `lint`, and `typecheck` scripts
+- TypeScript, Vitest, and lint config aligned with sibling extracted repos
+- entrypoints for binder exports
+- repo-local `README.md`, `SCOPE.md`, and capability metadata that describe the
+  package as real code rather than INTENT-only placeholder material
+
+Acceptance:
+
+- this repo can install, test, lint, and typecheck as an independent package
+- top-level docs describe the extracted package surface and repo boundary
+- `registry/indexes/capabilities.yaml` no longer advertises an empty placeholder
+
+## T03 — Extract headless bindings, state, and provider composition

 ```task
 id: EBIND-WP-0001-T03
-status: todo
+status: done
 priority: high
 state_hub_task_id: "d58501a4-b2e5-45fa-b504-e2c37ca48e68"
 ```

-Move the headless binding primitives from
-`../citation-evidence/src/binder/repos/in-memory-links.ts` and
-`../citation-evidence/src/binder/services/bindings.ts` with their tests. Keep
-the current query directions, default relation/status behavior, and event-bus
-emission semantics while staying independent of persistence, viewer internals,
-`citation-work`, and `evidence-source`.
+Extract the non-visual binder core:

-## Extract Active State And Provider Composition
+- `repos/in-memory-links.ts`
+- `services/bindings.ts` and its tests
+- `state/active.ts` and its tests
+- `BinderProvider.tsx`
+- package exports for the headless service and provider surface
+
+Preserve:
+
+- current query directions (`target -> links`, `evidence -> links`)
+- default relation/status behavior
+- active target / active evidence / active annotation coordination
+- bus injection and `initialLinks` restore behavior
+
+Acceptance:
+
+- headless binder behavior runs in this repo with passing tests
+- no persistence, viewer, `citation-work`, or `evidence-source` dependency is introduced
+- the binder package can mount its provider and expose the current state API
+
+## T04 — Extract rect registry, change pumps, and overlay

 ```task
 id: EBIND-WP-0001-T04
-status: todo
+status: done
 priority: high
+depends_on: [T03]
 state_hub_task_id: "b6f96550-c4a6-4ce1-bfde-4c91d33da687"
 ```

-Extract `state/active.ts` and `BinderProvider.tsx` so the binder owns the
-active target / active evidence / active annotation state triple plus the
-composition root that wires link storage, binding services, rect registry, and
-engine bus access. Preserve `initialLinks` restore behavior and bus injection
-without introducing a dependency on umbrella app code.
-
-## Extract Rect Registry, Change Pumps, And Overlay
-
-```task
-id: EBIND-WP-0001-T05
-status: todo
-priority: high
-state_hub_task_id: "58b55a71-eee4-4f3d-9bcd-7c3678320dd1"
-```
-
 Move the visual-guide contract from
 `../citation-evidence/src/binder/visual-guide/`, including
 `rect-registry.ts`, `events.ts`, `react-hooks.ts`, `Overlay.tsx`, and their
@ -102,27 +154,68 @@ tests. Preserve the section 7 rect kinds, invalidate/version semantics,
 requestAnimationFrame throttling, and the contract that independent renderers
 publish rects into one registry.

-## Decide Binder-Owned Reference UI Surface
+Acceptance:
+
+- section 7 rect-registry contract is implemented here without behavioral drift
+- overlay redraw behavior still depends on rect invalidation rather than polling
+- rect registry, hook, and overlay tests pass from this repo
+
+## T05 — Decide binder-owned reference UI surface
+
+```task
+id: EBIND-WP-0001-T05
+status: done
+priority: medium
+depends_on: [T03, T04]
+state_hub_task_id: "58b55a71-eee4-4f3d-9bcd-7c3678320dd1"
+```
+
+Make an explicit decision for the small React form surface:
+
+- keep `FormRenderer.tsx` and `FieldDefinitionForm.tsx` as supported binder exports, or
+- move them to examples/reference UI and narrow the package surface accordingly
+
+The decision must preserve the architectural rule that binder is form-friendly
+but target-neutral and does not depend on `citation-work`.
+
+Acceptance:
+
+- the repo documents which React UI pieces are contractual versus illustrative
+- any retained UI exports compile and test here
+- any demoted UI files no longer blur the subsystem boundary
+
+## T06 — Refresh docs and local contract references

 ```task
 id: EBIND-WP-0001-T06
-status: todo
+status: done
 priority: medium
+depends_on: [T01, T02]
 state_hub_task_id: "39164219-5f35-49cf-874a-00fd0c902007"
 ```

-Decide whether `FormRenderer.tsx` and `FieldDefinitionForm.tsx` remain binder
-exports, move into examples, or shift into an application layer. Whatever the
-outcome, keep binder form-friendly but target-neutral, avoid a `citation-work`
-dependency, and document which React surfaces are supported versus merely
-illustrative.
+Update the repo's local reference material so the extracted package is
+understandable without reopening the umbrella implementation:

-## Cut Over Umbrella Integration And Verify Boundaries
+- refresh `README.md` and `SCOPE.md`
+- update `INTENT.md` where it still implies placeholder-only state
+- add or copy the minimum local contract references needed for conformance
+- document the dependency rule: binder may depend on engine and anchor, not on
+  source, work, or umbrella behavior
+
+Acceptance:
+
+- a developer can orient from this repo alone and understand what extracts here
+- local docs do not contradict the umbrella shared-contract authority
+- repo metadata no longer looks like a pre-extraction stub
+
+## T07 — Cut over umbrella integration and verify boundaries

 ```task
 id: EBIND-WP-0001-T07
-status: todo
+status: done
 priority: high
+depends_on: [T04, T05, T06]
 state_hub_task_id: "efceaee5-43a8-4ecf-9025-a5843eecada0"
 ```

@ -133,17 +226,39 @@ edges to `citation-evidence` behavior, `citation-work`, or `evidence-source`,
 and keep shared-contract changes flowing through the umbrella docs until the
 cutover is complete.

-## Exit Criteria
+Acceptance:
+
+- umbrella resolves binder imports through this repo rather than a duplicate local copy
+- binder-specific code is deleted or reduced to package-facing glue in the umbrella repo
+- dependency-boundary checks still enforce the allowed edge set after wireup
+
+## T08 — Verification and closeout

 ```task
 id: EBIND-WP-0001-T08
-status: todo
+status: done
 priority: medium
+depends_on: [T07]
 state_hub_task_id: "2c89dfcb-1526-46d9-936d-8f97f4e48d76"
 ```

-Exit when this repo exports the binder service, active-state flow, and
-visual-guide rect-registry contract with passing tests; repo docs and metadata
-match the canonical shared contracts; and the umbrella app can define a target,
-link evidence, activate evidence, and draw the field-to-card-to-highlight
-overlay without relying on the upstream `src/binder/` implementation.
+Verification:
+
+- `pnpm test` is green in `evidence-binder`
+- `pnpm typecheck` is green in `evidence-binder`
+- `pnpm lint` is green in `evidence-binder`
+- umbrella consumer tests/typecheck/lint stay green after wireup
+- manual smoke still covers the field -> evidence card -> highlight visual guide path
+
+Acceptance:
+
+- this repo exports the binder service, active-state flow, and rect-registry contract
+- umbrella behavior is unchanged on the MVP evidence-backed form flow
+- all tasks can be closed individually by a Ralph loop without further task splitting
+
+## Out Of Scope
+
+- changing canonical enum vocabularies outside the shared-contract process
+- taking ownership of document ingestion, selector resolution, or viewer internals
+- making `citation-work` import binder directly
+- publish/distribution work beyond the extraction and sibling-consumer wireup