citation-engine

Core domain model and engine services for the citation-evidence ecosystem.

This package provides the shared vocabulary (Document, Selector, Annotation, EvidenceItem, EvidenceLink, EvidenceSet, state enums, branded IDs, canonical text normalization) together with in-memory repositories, orchestration services, the event bus, and citation card renderers.

Published as @citation-evidence/engine.

Layout

src/
  shared/   # types, enums, pure helpers
  engine/   # services, repositories, rendering, persistence
wiki/
  SharedContracts.md   # conformance copy (authoritative: citation-evidence)

Installing

Local development (sibling checkout)

Repos are expected as siblings:

~/citation-evidence/
~/citation-engine/
~/evidence-anchor/
...

In the consumer's package.json:

{
  "dependencies": {
    "@citation-evidence/engine": "link:../citation-engine"
  }
}

Then pnpm install. TypeScript path aliases in consumers typically map @shared/* and @engine/* to ../citation-engine/src/shared/* and ../citation-engine/src/engine/* (see CE-WP-0009 in citation-evidence).

Registry install (when published)

pnpm add @citation-evidence/engine

Registry host TBD. See Publishing checklist below.

evidence-anchor (placeholder)

When evidence-anchor extracts, it will depend on engine types only:

{
  "dependencies": {
    "@citation-evidence/engine": "link:../citation-engine"
  }
}

Import shared types via @shared/* path aliases or @citation-evidence/engine/shared.

Development

pnpm install
pnpm test
pnpm typecheck
pnpm lint

Contract sync

See wiki/README.md. Changes to shared contracts land in citation-evidence/wiki/SharedContracts.md first, then sync here.

Extraction status

Code lives in src/shared/ and src/engine/, extracted from the umbrella MVP per workplans/CENG-WP-0001-intent-placeholder.md. The umbrella consumes this package via link: per CE-WP-0009.

Publishing checklist

Use when a package registry is configured (ADR-0002: independent repos + publish).

• Set private: false (or scoped private per org policy)
• Confirm files in package.json includes src/, wiki/, README.md, LICENSE
• Decide: TypeScript sources via exports (current) vs tsc emit to dist/
• Bump semver: patch for fixes, minor for additive contracts, major for breaks
• Run pnpm test && pnpm typecheck && pnpm lint before publish
• Update consumers from link: to registry version
• Document registry URL and auth in org runbook (not in this repo)

No publish CI step is configured yet — credentials and registry choice are out of scope until an external consumer requires it.

Related repos

• citation-evidence — umbrella reference workspace
• evidence-anchor — selector creation and resolution
• evidence-source — document ingestion
• citation-work — review workspace UX
• evidence-binder — evidence-to-field linking