citation-evidence/wiki/DependencyMap.md

Dependency Map — citation-evidence

This document describes the allowed dependency edges between the subsystems of the citation-evidence ecosystem. It is the cycle-prevention contract.

It complements SharedContracts.md (which says what is shared) by saying who is allowed to depend on whom.

---

1. The rule

Types flow downward from citation-engine. Behavior flows upward into specialised repos. No subsystem may import another subsystem's behavior unless this map shows an edge.

The umbrella repo citation-evidence is allowed to depend on every subsystem; nothing depends on the umbrella.

---

2. Allowed edges

                       ┌───────────────────────┐
                       │   citation-evidence   │  (umbrella)
                       └───────────┬───────────┘
                                   │ depends on
        ┌──────────────────────────┼────────────────────────────┐
        ▼                          ▼                            ▼
┌───────────────┐         ┌────────────────┐          ┌────────────────┐
│  citation-    │         │  evidence-     │          │  citation-     │
│  work         │         │  binder        │          │  engine        │
└──────┬────────┘         └────────┬───────┘          └────────┬───────┘
       │                           │                           │
       │ depends on                │ depends on                │ depends on
       │                           │                           │   (nothing —
       ▼                           ▼                           │    leaf node)
┌────────────────┐         ┌────────────────┐                  │
│  evidence-     │         │  evidence-     │                  │
│  anchor        │         │  anchor        │                  │
└──────┬─────────┘         └────────┬───────┘                  │
       │                            │                          │
       │ depends on                 │ depends on               │
       ▼                            ▼                          ▼
┌────────────────┐         ┌────────────────┐         (citation-engine)
│  evidence-     │         │  citation-     │
│  source        │         │  engine        │
└────────┬───────┘         └────────────────┘
         │
         │ depends on
         ▼
┌────────────────┐
│  citation-     │
│  engine        │
└────────────────┘

In tabular form:

Repo	May depend on	Must not depend on
citation-engine	(nothing — it is the leaf)	every other subsystem
evidence-anchor	citation-engine	evidence-source, citation-work, evidence-binder, citation-evidence
evidence-source	citation-engine	evidence-anchor, citation-work, evidence-binder, citation-evidence
evidence-binder	citation-engine, evidence-anchor	evidence-source, citation-work, citation-evidence
citation-work	citation-engine, evidence-anchor, evidence-source	evidence-binder, citation-evidence
citation-evidence	all five subsystems	(nothing else in the ecosystem)

Notes:

• evidence-source does NOT depend on evidence-anchor. When an ingestion pipeline needs to know "could a selector resolve here?", the answer comes through events, not direct calls.
• citation-work does NOT depend on evidence-binder. Linking evidence to form fields is a separate workflow; the review workspace should function without it. A separate "evidence-backed form" application composes work + binder + engine.
• evidence-binder does NOT depend on evidence-source. When a binder needs source context, it asks evidence-anchor to resolve the annotation, which in turn knows nothing about how the document was ingested.

---

3. Communication channels

Direct imports are allowed only along the edges above. Where two subsystems need to coordinate without being allowed to import each other, they use one of these indirect channels:

Channel	Owner	Notes
Shared event bus	citation-engine	Vocabulary frozen in SharedContracts.md §4
Shared types package	citation-engine	Re-exported through @citation-evidence/engine (post-extraction)
Rect registry	evidence-binder	Used by form UI, evidence sidebar, viewer adapter
Persistence interfaces	citation-engine	Concrete adapters in subsystems but interfaces in engine

---

4. During umbrella-first MVP

While all code lives in citation-evidence/src/, the rule is enforced by folder structure and lint rules:

citation-evidence/src/
  shared/           ← what will become citation-engine (types + contracts)
  engine/           ← what will become citation-engine (services)
  anchor/           ← what will become evidence-anchor
  source/           ← what will become evidence-source
  work/             ← what will become citation-work (UI)
  binder/           ← what will become evidence-binder
  app/              ← the umbrella reference app

Lint rule (to be added in WP-0001):

• engine/ may import only from shared/.
• anchor/ may import only from shared/, engine/.
• source/ may import only from shared/, engine/.
• binder/ may import only from shared/, engine/, anchor/.
• work/ may import only from shared/, engine/, anchor/, source/.
• app/ may import from any.

Violating these rules in MVP is a lint error, not a runtime error. When subsystems extract into their own repos, the lint rule disappears and the package boundary enforces the same constraint.

---

5. Why these rules

1. citation-engine as the leaf prevents the most common monorepo pathology: the "core" repo accumulating UI/IO dependencies because it was easier than inverting a dependency.
2. citation-work ⊄ evidence-binder keeps the review workspace usable even when there is no form context (e.g. just collecting evidence for a report).
3. evidence-binder ⊄ evidence-source keeps binding logic from accidentally caring about ingestion details.
4. No subsystem depends on citation-evidence — the umbrella is a composition point, not a library.

---

6. Change process

Adding an edge to this map is a change to the contract.

• New edges require a short ADR in docs/decisions/.
• Removing an edge requires a refactoring plan (where do consumers go?).
• The MVP itself is an exception: edges that turn out to be wrong during umbrella-first development are recorded as "deferred reshape" items in the relevant workplan, not as ADRs.