# 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`:

```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)

```bash
pnpm add @citation-evidence/engine
```

Registry host TBD. See [Publishing checklist](#publishing-checklist) below.

### evidence-anchor (placeholder)

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

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

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

## Development

```bash
pnpm install
pnpm test
pnpm typecheck
pnpm lint
```

## Contract sync

See [`wiki/README.md`](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`](../citation-evidence/) — umbrella reference workspace
- [`evidence-anchor`](../evidence-anchor/) — selector creation and resolution
- [`evidence-source`](../evidence-source/) — document ingestion
- [`citation-work`](../citation-work/) — review workspace UX
- [`evidence-binder`](../evidence-binder/) — evidence-to-field linking