cyclone/docs/superpowers/specs/2026-06-19-cyclone-db-reconciliation-design.md

# Cyclone DB + Reconciliation — Design

**Date:** 2026-06-19
**Status:** Draft (pending user review of this doc)
**Scope:** Second sub-project of the four-part Cyclone roadmap. Replaces the in-memory `InMemoryStore` with SQLite persistence via SQLAlchemy 2.0; adds automatic 837P ↔ 835 claim reconciliation on every successful 835 parse; ships a manual Reconciliation page for unmatched claims and remittances; extends the claim lifecycle to a 7-state model with reversal handling. Out of scope: additional 837P/835 validation rules (sub-project 3), 999 ACK / 270/271 (sub-project 3), per-claim detail drawer / batch diff / live NDJSON UI / advanced filters (sub-project 4).

---

## 1. Overview

Sub-project 1 (production-readiness, merged) gave Cyclone a thread-safe in-memory store + 6 GET endpoints + react-query wiring + 4 reference notes + a root README rewrite. The store is process-local and ephemeral: a uvicorn restart wipes every parsed batch, and there is no concept of "this remittance paid that claim."

This sub-project closes two real gaps:

1. **Persistence across restarts.** The same data must survive `Ctrl-C` and reappear when the backend comes back. We use SQLite via SQLAlchemy 2.0 (sync ORM). One file at `~/.local/share/cyclone/cyclone.db`, overridable via `CYCLONE_DB_URL`. A lightweight migration runner (`cyclone.db_migrate`) keeps the schema forward-compatible; the env var is the escape hatch to Postgres if SQLite ever becomes a real constraint.
2. **837P ↔ 835 reconciliation.** When an 835 parses, we attempt to auto-match each CLP back to a Claim we already have from a prior 837P parse. Matches update the Claim's lifecycle state and create `Match` + `ActivityEvent` rows. Unmatched CLPs surface on a new `/reconciliation` page where the operator can manually pair them. Reversals (CLP02=21/22) flip prior state, preserve history on the Match row, and emit an audit-trail activity event.

After this sub-project, a user can:

1. Start the backend (`python -m cyclone serve`); the SQLite file is auto-created.
2. Upload `co_medicaid_837p.txt` → 2 Claims appear with state `submitted`.
3. Upload `co_medicaid_835.txt` → the matched Claim flips to `paid`, the reversal (if present) flips back, the orphan CLP shows up in `/reconciliation`.
4. Open `/reconciliation` → manually pair the orphan → Claim state updates, orphan disappears from the bucket.
5. Restart the backend → everything still there.

## 2. Goals

1. **SQLite-backed persistence.** Replace `InMemoryStore` internals with SQLAlchemy 2.0 ORM models in `cyclone.db`. Public store API stays byte-compatible so `api.py` and the mappers change minimally.
2. **Automatic reconciliation on every 835 parse.** Match each CLP to a Claim via `claim_id` (CLM01 ↔ CLP01) within ±7 days of `service_date`. Apply the result to the Claim row, write a `Match` row, write one `ActivityEvent` per state transition. Failures are fail-soft (logged + activity event) and never block the parse response.
3. **7-state claim lifecycle.** `submitted → received → (paid | partial | denied) → reconciled → reversed`. Reversals of `paid`/`partial` Claims set the Claim to `reversed` and preserve the pre-reversal state on the `Match` row; other reversals log a no-op activity event.
4. **Manual reconciliation UI.** New `/reconciliation` page with two columns (unmatched Claims left, unmatched Remittances right). Click-to-select, "Match" / "Unmatch" buttons. State badge updates immediately via react-query invalidation.
5. **Real adjustment amounts.** `Remittance.adjustmentAmount` (currently hardcoded to `0.0` per `store.py:376`) aggregates from CAS segments, populated by the reconciliation step.
6. **Forward-compatible schema.** A ~40-LOC migration runner (`cyclone.db_migrate`) using SQLite's `PRAGMA user_version`. Migrations are idempotent SQL files in `backend/src/cyclone/migrations/NNNN_*.sql`.

## 3. Non-goals (this sub-project)

- More 837P validation rules (REF*G1, BHT06, etc.) — sub-project 3.
- 999 ACK / 270/271 / 277CA — sub-project 3.
- Deep CAS reason-code explanations surfaced to the operator — sub-project 3.
- Real-time streaming of NDJSON GET responses into the UI — sub-project 4.
- Per-claim detail drawer, batch diff, advanced filters, keyboard nav — sub-project 4.
- Multi-user / multi-machine support — explicitly local-only.
- Alembic — too much ceremony for one operator + one machine; `user_version` runner is sufficient.
- Renaming the 835 `ClaimPayment.payer_claim_control_number` field to its semantically correct name (`patient_control_number`) — left as a follow-up tech-debt note. We match against the existing field in this sub-project.

## 4. Stack

**Backend additions:**
- `sqlalchemy>=2.0,<3` in `backend/pyproject.toml`. No Alembic. No other Python deps.
- New module `backend/src/cyclone/db.py` — engine factory, `SessionLocal`, declarative `Base`, 6 ORM model classes.
- New module `backend/src/cyclone/db_migrate.py` — `PRAGMA user_version` runner, ~40 LOC.
- New module `backend/src/cyclone/reconcile.py` — pure-function match + apply (no DB session inside; receives lists of ORM objects, returns intent objects).
- New directory `backend/src/cyclone/migrations/` — `0001_initial.sql`, future `NNNN_*.sql`.

**Backend modifications:**
- `backend/src/cyclone/store.py` — internal rewrite from `list[BatchRecord]` + `RLock` to SQLAlchemy-backed. Public method signatures preserved.
- `backend/src/cyclone/api.py` — add 3 new endpoints (`GET /api/reconciliation/unmatched`, `POST /api/reconciliation/match`, `POST /api/reconciliation/unmatch`). Existing 6 endpoints continue to work; their handlers now read from SQLAlchemy via the store facade.
- `backend/src/cyclone/__main__.py` — call `db.init()` (engine + `create_all` + `db_migrate.run`) before uvicorn starts.
- `backend/tests/` — extend with ~32 new tests across `test_reconcile.py`, `test_db_migrate.py`, `test_store_reconcile.py`, plus API tests for the 3 new endpoints.

**Frontend additions:**
- New page `src/pages/Reconciliation.tsx`.
- New hook `src/hooks/useReconciliation.ts` (queries + mutations, react-query invalidation cascade).
- New primitive `src/components/ui/claim-state-badge.tsx` (replaces 4-state logic with 7-state, same palette).
- Sidebar entry in `src/components/Sidebar.tsx` between Claims and Remittances.
- `src/types/index.ts` — add `ClaimState` enum (7 values) and `Match`/`UnmatchedClaim`/`UnmatchedRemittance` shapes.
- `src/lib/api.ts` — add 3 new methods (`listUnmatched`, `matchRemit`, `unmatchClaim`).

**Frontend modifications:**
- `src/components/StatusBadge.tsx` — delegate the 7-state subset to the new primitive; keep the 4-token palette (success / accent / warning / destructive / muted) unchanged.
- `src/pages/Claims.tsx` — render the new 7-state badge; accept `claim.state` directly from API instead of inferring from status text.
- `src/pages/Remittances.tsx` — render `adjustmentAmount` from the API (was hardcoded `0.0`).
- `vitest.config.ts` — exclude `.worktrees/` from test discovery (current worktree leftover from sub-project 1 causes duplicate test runs).

**No new npm deps.** All existing deps (`@tanstack/react-query`, `sonner`, `lucide-react`, etc.) cover the new surface.

## 5. Architecture

```
┌──────────────────────┐  POST /api/parse-{837,835}    ┌─────────────────────────┐
│  Vite/React UI       │ ────────────────────────────▶ │  FastAPI backend        │
│                      │  GET  /api/{batches,claims,   │  (uvicorn 127.0.0.1)    │
│  ┌────────────────┐  │       remittances,providers,  │  ┌────────────────────┐ │
│  │ react-query v5 │  │       activity,batches/{id}}  │  │ store (facade)     │ │
│  │ QueryClient    │  │  GET  /api/reconciliation/    │  │ add/get/iter_*     │ │
│  │ useQuery /     │  │       unmatched               │  │ list_unmatched     │ │
│  │ useMutation    │  │  POST /api/reconciliation/    │  │ manual_match       │ │
│  └────────────────┘  │       {match,unmatch}         │  │ manual_unmatch     │ │
│  ┌────────────────┐  │ ◀──────────────────────────── │  └────────┬───────────┘ │
│  │ zustand store  │  │   (JSON; NDJSON on list GETs) │           │             │
│  │ (sample data)  │  │                               │  ┌────────▼───────────┐ │
│  └────────────────┘  │                               │  │ cyclone.db          │ │
│                      │                               │  │ SQLAlchemy 2.0 ORM  │ │
│                      │                               │  │ 6 model classes     │ │
│                      │                               │  │ SessionLocal()      │ │
│                      │                               │  └────────┬───────────┘ │
│                      │                               │           │             │
│                      │                               │  ┌────────▼───────────┐ │
│                      │                               │  │ cyclone.reconcile   │ │
│                      │                               │  │ pure functions:     │ │
│                      │                               │  │  match()            │ │
│                      │                               │  │  apply_payment()    │ │
│                      │                               │  │  apply_reversal()   │ │
│                      │                               │  │  split_unmatched()  │ │
│                      │                               │  └────────────────────┘ │
│                      │                               │  ┌────────────────────┐ │
│                      │                               │  │ cyclone.db_migrate  │ │
│                      │                               │  │ PRAGMA user_version │ │
│                      │                               │  │ migrations/*.sql    │ │
│                      │                               │  └────────────────────┘ │
└──────────────────────┘                               └─────────────────────────┘
                                                          ▲
                                                          │ CORS allow
                                                          │ http://localhost:5173
                                                          │ only
```

**Boundary contracts:**

| Module | Public API | Pure? |
|---|---|---|
| `cyclone.db` | `init_db()`, `SessionLocal()`, model classes | No (engine + schema) |
| `cyclone.db_migrate` | `run(engine)` | Yes (modulo engine) |
| `cyclone.reconcile` | `match()`, `apply_payment()`, `apply_reversal()`, `split_unmatched()` | **Yes** (no DB session inside) |
| `cyclone.store` | `add()`, `get_batch()`, `iter_*()`, `list_unmatched()`, `manual_match()`, `manual_unmatch()` | No (owns sessions, calls reconcile) |
| `cyclone.api` | HTTP routes | No |
| React page/hook | HTTP shapes | No |

`reconcile.*` functions receive lists of ORM objects (or fabricated equivalents in tests) and return **intent objects** describing what should change. The caller (`store`) is responsible for persisting the intent inside a session. This keeps reconciliation unit-testable without a database.

## 6. Data model

`cyclone.db` declares 6 ORM model classes. SQLAlchemy 2.0 `DeclarativeBase` + `Mapped[...]` + `mapped_column(...)` typed syntax (no legacy `Column()`).

### 6.1 `Batch`

| Column | Type | Notes |
|---|---|---|
| `id` | `String(32)` PK | uuid4 hex (preserved from sub-project 1) |
| `kind` | `String(8)` | `"837p"` or `"835"` |
| `input_filename` | `String(512)` | original upload name |
| `parsed_at` | `DateTime(timezone=True)` | tz-aware UTC |
| `totals_json` | `JSON` | `{"claims": N, "paid": M, "denied": K, ...}` from the parser summary |
| `validation_json` | `JSON` | `{"passed": bool, "warnings": [...], "errors": [...]}` |
| `raw_result_json` | `JSON` | the full `ParseResult` / `ParseResult835` for `GET /api/batches/{id}` round-trip |

Indexed on `parsed_at DESC`.

### 6.2 `Claim`

| Column | Type | Notes |
|---|---|---|
| `id` | `String(64)` PK | 837P `claim_id` (CLM01); unique per (batch, claim_id) |
| `batch_id` | `String(32)` FK→`Batch.id` | ON DELETE CASCADE |
| `patient_control_number` | `String(64)` | CLM01; the match key |
| `service_date_from` | `Date` | CLM05 date range start |
| `service_date_to` | `Date` | CLM05 date range end |
| `charge_amount` | `Numeric(12,2)` | CLM02 |
| `provider_npi` | `String(16)` | 2010AA NM109 |
| `payer_id` | `String(32)` | NM1*PR N104 |
| `state` | `Enum(ClaimState)` | 7 values (see §6.7) |
| `state_before_reversal` | `Enum(ClaimState)?` | nullable; populated only when a reversal flips state back |
| `matched_remittance_id` | `String(64)?` FK→`Remittance.id` | nullable; current match (replaced on unmatch / re-match) |
| `raw_json` | `JSON` | full `ClaimOutput` for drill-down |

Unique constraint on `batch_id, patient_control_number`. Indexed on `state`, `patient_control_number`, `service_date_from`.

### 6.3 `Remittance`

| Column | Type | Notes |
|---|---|---|
| `id` | `String(64)` PK | 835 `payer_claim_control_number` (CLP01) + ERA batch suffix to disambiguate within a batch; unique per (batch, pcn, suffix) |
| `batch_id` | `String(32)` FK→`Batch.id` | ON DELETE CASCADE |
| `payer_claim_control_number` | `String(64)` | CLP01 — the match key against `Claim.patient_control_number` |
| `claim_id` | `String(64)?` FK→`Claim.id` | nullable until matched; nullable if no match exists |
| `status_code` | `String(4)` | CLP02 |
| `status_label` | `String(32)?` | decoded by `claim_status_label` |
| `total_charge` | `Numeric(12,2)` | CLP03 |
| `total_paid` | `Numeric(12,2)` | CLP04 |
| `patient_responsibility` | `Numeric(12,2)?` | CLP05 |
| `adjustment_amount` | `Numeric(12,2)` | **NEW** — sum of `CasAdjustment.amount` for this CLP; populated by reconciliation |
| `received_at` | `DateTime(timezone=True)` | parsed_at of the parent batch |
| `service_date` | `Date?` | first SVC's `service_date` from the 835 (used by match for ±7d window) |
| `is_reversal` | `Boolean` | True if CLP02 ∈ {21, 22} |
| `raw_json` | `JSON` | full `ClaimPayment` for drill-down |

Indexed on `claim_id`, `payer_claim_control_number`, `status_code`.

### 6.4 `CasAdjustment`

| Column | Type | Notes |
|---|---|---|
| `id` | `Integer` PK autoincrement | |
| `remittance_id` | `String(64)` FK→`Remittance.id` | ON DELETE CASCADE |
| `group_code` | `String(4)` | CAS01 (CO, PR, OA, PI, CR) |
| `reason_code` | `String(8)` | CAS02 (e.g., "97", "16") |
| `amount` | `Numeric(12,2)` | CAS03 |
| `quantity` | `Numeric(10,2)?` | CAS04 (for unit-based adjustments) |

Indexed on `remittance_id`.

### 6.5 `Match`

| Column | Type | Notes |
|---|---|---|
| `id` | `Integer` PK autoincrement | |
| `claim_id` | `String(64)` FK→`Claim.id` | UNIQUE — one current match per Claim |
| `remittance_id` | `String(64)` FK→`Remittance.id` | ON DELETE CASCADE |
| `strategy` | `String(16)` | `"auto"` or `"manual"` |
| `matched_at` | `DateTime(timezone=True)` | |
| `prior_claim_state` | `Enum(ClaimState)?` | nullable; populated only when a reversal is applied, so we can recover the pre-reversal state |
| `is_reversal` | `Boolean` | denormalized for cheap filtering |

Indexed on `remittance_id`, `matched_at`.

### 6.6 `ActivityEvent`

| Column | Type | Notes |
|---|---|---|
| `id` | `Integer` PK autoincrement | |
| `ts` | `DateTime(timezone=True)` | default `utcnow` |
| `kind` | `String(32)` | `"parse_837"`, `"parse_835"`, `"reconcile"`, `"reconcile_failed"`, `"reversal"`, `"reversal_skipped"`, `"orphan_reversal"`, `"manual_match"`, `"manual_unmatch"`, `"match_conflict"`, `"invalid_state"` |
| `batch_id` | `String(32)?` | nullable; populated when the event ties to a batch |
| `claim_id` | `String(64)?` | nullable; populated when the event ties to a claim |
| `remittance_id` | `String(64)?` | nullable; populated when the event ties to a remittance |
| `payload_json` | `JSON` | event-specific (e.g., `{"count": 3, "matched": 2, "unmatched": 1}` for `reconcile`) |

Indexed on `ts DESC`, `kind`.

### 6.7 `ClaimState` enum

```python
import enum

class ClaimState(str, enum.Enum):
    SUBMITTED = "submitted"   # 837P parsed, no remittance yet
    RECEIVED = "received"     # 835 CLP matched; awaiting payment application
    PAID = "paid"             # matched + CLP04 >= CLM02 (full payment)
    PARTIAL = "partial"       # matched + 0 < CLP04 < CLM02
    DENIED = "denied"         # matched + CLP02=4
    RECONCILED = "reconciled" # matched + applied; final state on a non-reversal payment
    REVERSED = "reversed"     # matched + later CLP02=21/22 hit; prior state recoverable via Match.prior_claim_state
```

**Transition table:**

| From | Trigger | To | Side effects |
|---|---|---|---|
| (new) | `store.add(837)` | `submitted` | `ActivityEvent(kind="parse_837", claim_id=...)` |
| `submitted` | `reconcile.apply_payment` (CLP02 ∈ {1,2,3,19,20}, CLP04 ≥ CLM02) | `paid` → `reconciled` | `Match(strategy="auto")`, `ActivityEvent(kind="reconcile")` |
| `submitted` | `reconcile.apply_payment` (CLP04 < CLM02) | `partial` → `reconciled` | same |
| `submitted` | `reconcile.apply_payment` (CLP02 = 4) | `denied` → `reconciled` | same |
| `submitted` | `reconcile.apply_payment` (CLP02 ∉ {1,2,3,4,19,20}) | `received` → `reconciled` | same |
| `paid` or `partial` | `reconcile.apply_reversal` (CLP02 = 21 or 22) | `reversed` | `Match(strategy="auto", is_reversal=True, prior_claim_state=…)`, `ActivityEvent(kind="reversal")`. The original `paid`/`partial` Match row is preserved unchanged. |
| `reversed` | `reconcile.apply_reversal` again | no-op | `ActivityEvent(kind="reversal_skipped")` |
| any | manual `store.manual_match` | same as auto | `Match(strategy="manual")`, `ActivityEvent(kind="manual_match")` |
| any | manual `store.manual_unmatch` | `submitted` (if Claim is otherwise orphaned) | Match row deleted, `ActivityEvent(kind="manual_unmatch")` |

Transitions not in this table are **no-ops with a logged activity event** (e.g., `apply_payment` on a `denied` Claim is a no-op + `ActivityEvent(kind="invalid_state", payload={"current_state": "denied"})`).

## 7. Reconciliation algorithm

### 7.1 Match strategy — "strict auto-match"

```
reconcile.match(unmatched_claims, new_remittances, *, window_days=7):
    matches = []
    used_remits = set()

    # Group claims by patient_control_number for O(1) lookup
    by_pcn: dict[str, list[Claim]] = {}
    for c in unmatched_claims:
        if c.patient_control_number and c.state in (SUBMITTED, RECEIVED, REVERSED):
            by_pcn.setdefault(c.patient_control_number, []).append(c)

    # Iterate remittances in batch order (preserves CLP ordering)
    for r in new_remittances:
        candidates = by_pcn.get(r.payer_claim_control_number, [])
        if not candidates:
            continue  # → unmatched bucket
        # Pick the claim whose service_date_from is closest to r.service_date
        # and within ±window_days. If r.service_date is None (rare), fall
        # back to "first claim in pcn bucket".
        chosen = None
        if r.service_date is not None:
            best_delta = None
            for c in candidates:
                if c.service_date_from is None:
                    continue
                delta = abs((c.service_date_from - r.service_date).days)
                if delta <= window_days and (best_delta is None or delta < best_delta):
                    chosen = c
                    best_delta = delta
        if chosen is None and candidates:
            chosen = candidates[0]  # no date info → first claim for that PCN

        if chosen is not None:
            matches.append(Match(
                claim=chosen,
                remittance=r,
                strategy="auto",
                is_reversal=r.is_reversal,
            ))
            used_remits.add(r.id)

    return matches
```

**Properties:**
- Deterministic: same inputs → same matches.
- O(C + R) where C = unmatched claims, R = new remittances; O(C) memory for the by_pcn index.
- Multiple Claims for the same PCN (e.g., resubmissions with frequency_code=7) → picks the closest by date; falls back to first if no dates.
- Multiple Remittances for the same PCN (e.g., split payments) → each Remittance gets its own Claim in the order they appear.
- Reversal CLPs are matched the same way; the `is_reversal` flag drives the apply step.

### 7.2 Apply — `apply_payment(claim, remit) → intent`

```python
def apply_payment(claim: Claim, remit: Remittance) -> ApplyIntent:
    if claim.state in (PAID, PARTIAL, DENIED, RECONCILED):
        # Already settled — refuse double-payment
        return ApplyIntent.noop(invalid_state=claim.state)

    if remit.status_code == "4":
        new_state = ClaimState.DENIED
    elif remit.total_paid is None or remit.total_paid <= 0:
        new_state = ClaimState.RECEIVED
    elif remit.total_paid >= claim.charge_amount:
        new_state = ClaimState.PAID
    else:
        new_state = ClaimState.PARTIAL

    return ApplyIntent(
        new_state=new_state,
        match_strategy="auto",
        activity_kind="reconcile",
    )
```

Caller (in `store`) persists the new state, creates the Match row, writes the ActivityEvent, and commits — all inside one session.

### 7.3 Apply — `apply_reversal(claim, remit) → intent`

```python
def apply_reversal(claim: Claim, remit: Remittance) -> ApplyIntent:
    if claim.state in (PAID, PARTIAL):
        return ApplyIntent(
            new_state=claim.state,         # no actual state change on the claim
            match_strategy="auto",
            is_reversal=True,
            prior_claim_state=claim.state, # recorded on the Match row
            activity_kind="reversal",
        )
    # Already reversed, denied, or never paid — log and skip
    return ApplyIntent.noop(
        skipped=True,
        reason=f"reversal on state {claim.state.value}",
        activity_kind="reversal_skipped",
    )
```

The Claim's own `state` **changes to `REVERSED`** on a reversal of `paid`/`partial` (the operator-facing view is "this payment was reversed"). The pre-reversal state lives on the new `Match` row as `prior_claim_state`, so the audit trail is preserved. A reversed Claim's `matched_remittance_id` points at the reversal remittance, and a separate `Match` row from the original payment also still exists — the audit history is queryable via `Claim.id` JOIN `Match.claim_id`.

### 7.4 Split unmatched

```python
def split_unmatched(claims, remits, matches) -> tuple[list[Claim], list[Remittance]]:
    matched_claim_ids = {m.claim_id for m in matches}
    matched_remit_ids = {m.remittance_id for m in matches}
    return (
        [c for c in claims if c.id not in matched_claim_ids],
        [r for r in remits if r.id not in matched_remit_ids],
    )
```

A Claim that has at least one match is **not** in the unmatched bucket, even if it's still in `submitted` (e.g., the matched Remit was a denial and the operator wants to see other matching Remits). Manual unmatch moves it back to the unmatched bucket.

### 7.5 Reconciliation trigger — `reconcile.run(session, batch_id)`

Called from `store.add()` after the 835's Batch + Remittances + CasAdjustments are persisted:

```python
def reconcile.run(session: Session, batch_id: str) -> ReconcileResult:
    try:
        new_remits = session.execute(
            select(Remittance).where(Remittance.batch_id == batch_id)
        ).scalars().all()

        unmatched_claims = session.execute(
            select(Claim).where(Claim.matched_remittance_id.is_(None))
        ).scalars().all()

        matches = reconcile.match(unmatched_claims, new_remits)

        intents = []
        for m in matches:
            if m.is_reversal:
                intent = reconcile.apply_reversal(m.claim, m.remittance)
            else:
                intent = reconcile.apply_payment(m.claim, m.remittance)
            intents.append((m, intent))

        for m, intent in intents:
            if intent.skipped:
                session.add(ActivityEvent(
                    kind=intent.activity_kind,
                    batch_id=batch_id,
                    claim_id=m.claim.id,
                    payload={"reason": intent.reason, "current_state": m.claim.state.value},
                ))
                continue

            # Persist the Match + state transition + activity event atomically
            session.add(Match(
                claim_id=m.claim.id,
                remittance_id=m.remittance.id,
                strategy=m.strategy,
                is_reversal=m.is_reversal,
                prior_claim_state=intent.prior_claim_state,
                matched_at=utcnow(),
            ))
            if not m.is_reversal:
                m.claim.state = intent.new_state
                m.claim.matched_remittance_id = m.remittance.id
            else:
                # Reversal of a paid/partial Claim: set state to REVERSED on
                # the Claim so the operator sees it; the original state is
                # recoverable via Match.prior_claim_state.
                m.claim.state = ClaimState.REVERSED
                m.claim.matched_remittance_id = m.remittance.id
            session.add(ActivityEvent(
                kind=intent.activity_kind,
                batch_id=batch_id,
                claim_id=m.claim.id,
                payload={"new_state": intent.new_state.value if intent.new_state else None},
            ))

        # Aggregate CAS adjustments into each Remittance's adjustment_amount
        for r in new_remits:
            total = session.execute(
                select(func.sum(CasAdjustment.amount)).where(CasAdjustment.remittance_id == r.id)
            ).scalar_one() or Decimal("0.00")
            r.adjustment_amount = total

        session.commit()

        unmatched_claims_after, unmatched_remits_after = reconcile.split_unmatched(
            unmatched_claims, new_remits, [m for m, _ in intents if not _.skipped]
        )
        return ReconcileResult(
            matched=len([i for i in intents if not i[1].skipped]),
            unmatched_claims=len(unmatched_claims_after),
            unmatched_remittances=len(unmatched_remits_after),
            skipped=len([i for i in intents if i[1].skipped]),
        )
    except Exception as e:
        session.rollback()
        log.exception("reconciliation failed for batch %s", batch_id)
        # In a fresh session (the original is rolled back), record the failure
        with SessionLocal() as s2:
            s2.add(ActivityEvent(
                kind="reconcile_failed",
                batch_id=batch_id,
                payload={"error": str(e)},
            ))
            s2.commit()
        return ReconcileResult(failed=True, error=str(e))
```

**Critical invariant:** the Batch + Remittances + CasAdjustments are persisted **before** `reconcile.run` is called. A reconciliation crash never rolls back the parse.

## 8. Migration runner — `cyclone.db_migrate`

```python
# cyclonedb_migrate.py (~40 LOC)
from pathlib import Path
import re
import sqlalchemy as sa

MIGRATIONS_DIR = Path(__file__).parent / "migrations"
VERSION_RE = re.compile(r"^--\s*version:\s*(\d+)", re.MULTILINE)


def run(engine: sa.Engine) -> None:
    with engine.begin() as conn:
        current = conn.exec_driver_sql("PRAGMA user_version").scalar() or 0
        # Ensure user_version PRAGMA exists (no-op on SQLite 3.x)
        migrations = sorted(MIGRATIONS_DIR.glob("*.sql"))
        for path in migrations:
            sql = path.read_text()
            m = VERSION_RE.search(sql)
            if not m:
                raise RuntimeError(f"{path.name}: missing '-- version: N' header")
            version = int(m.group(1))
            if version <= current:
                continue
            # Each migration is its own transaction so a failure doesn't
            # leave the DB half-upgraded.
            with engine.begin() as conn2:
                # Strip the -- comment lines before executing
                statements = [s.strip() for s in sql.split(";") if s.strip() and not s.strip().startswith("--")]
                for stmt in statements:
                    conn2.exec_driver_sql(stmt)
                conn2.exec_driver_sql(f"PRAGMA user_version = {version}")
            current = version
```

Initial migration `backend/src/cyclone/migrations/0001_initial.sql`:
```sql
-- version: 1
CREATE TABLE batches (...);
CREATE TABLE claims (...);
-- ... all 6 tables
```

The runner is idempotent (re-running on an up-to-date DB is a no-op) and atomic per migration (each file in its own transaction).

## 9. Store facade

`cyclone.store` keeps its current public surface, but the internals are SQLAlchemy-backed. Public methods accept and return the same UI-shaped dicts as today; the SQLAlchemy ORM objects stay internal.

```python
class CycloneStore:  # renamed from InMemoryStore; old name kept as a compat alias
    def add(self, record: BatchRecord) -> str:
        """Persist the BatchRecord; for 835 batches, run reconciliation."""
        ...

    def get_batch(self, batch_id: str) -> dict | None: ...
    def iter_claims(self, *, batch_id=None, status=None, payer=None,
                    date_from=None, date_to=None, sort="service_date_from",
                    order="desc", limit=100, offset=0) -> list[dict]: ...
    def iter_remittances(self, *, batch_id=None, status=None, payer=None,
                         claim_id=None, date_from=None, date_to=None,
                         sort="received_at", order="desc", limit=100,
                         offset=0) -> list[dict]: ...
    def distinct_providers(self) -> list[dict]: ...
    def recent_activity(self, *, limit=200) -> list[dict]: ...

    # NEW in sub-project 2
    def list_unmatched(self, *, kind: Literal["claim", "remit", "both"] = "both") -> dict:
        """Returns {claims: [...], remittances: [...]}; only unmatched rows."""

    def manual_match(self, claim_id: str, remittance_id: str) -> Match:
        """Pair a Claim with a Remittance. Raises MatchConflict if either is already matched."""

    def manual_unmatch(self, claim_id: str) -> None:
        """Remove the Claim's current Match and reset to submitted state."""


store = CycloneStore()  # module-level singleton; first .add() lazy-inits the engine
```

**Session handling:** each public method opens its own `with SessionLocal() as s:` and commits/rolls back before returning. No long-lived sessions, no cross-request transaction leakage. The exception is `add()` for 835 batches, which uses one session for parse persistence and a second (or the same) session for `reconcile.run`.

## 10. API additions

| Method | Path | Body | Response | Notes |
|---|---|---|---|---|
| GET | `/api/reconciliation/unmatched` | — | `{claims: [...], remittances: [...]}` | Each Claim/Remittance carries the same UI shape as `/api/claims` / `/api/remittances` plus `id` (the FK). Sorted oldest-first so the operator works the backlog top-down. |
| POST | `/api/reconciliation/match` | `{claim_id, remit_id}` | `{claim: Claim, match: Match}` | 200 on success. 409 on conflict (already_matched, invalid_state). |
| POST | `/api/reconciliation/unmatch` | `{claim_id}` | `{claim: Claim}` | 200 on success. 404 if no current match. |

Existing endpoints continue to work with the same shapes. Internal mapping changes:

| Endpoint | Change |
|---|---|
| `GET /api/claims` | `status` filter accepts the 7-state enum; response `Claim` now includes `state` directly (no longer inferred from a separate status field). The `status` field on the response is kept for backward-compat but equals `state`. |
| `GET /api/remittances` | `adjustmentAmount` now reflects the CAS-aggregated value (was hardcoded `0.0`). |
| `POST /api/parse-835` | Response includes `reconciliation: {matched, unmatched_claims, unmatched_remittances, skipped}` so the UI can show a one-line summary toast. |

## 11. Frontend additions

### 11.1 `/reconciliation` page

Two-column layout, hairline chrome matching the rest of the UI. Both columns are independently scrollable. Each row is click-to-select; the "Match" button is disabled until exactly one row from each column is selected.

```
┌────────────────────────────────────────────────────────────────────────────┐
│  RECONCILIATION                                                             │
│                                                                             │
│  Unmatched claims (3)                                  Unmatched remits (1)  │
│  ─────────────────────                                 ─────────────────────│
│  ▸ CLM-001 · 2026-06-01 · $124.00                      ▸ CLP-001 · $62.00   │
│    Billed: $124.00  ·  NPI 1234567890                    Status 22 (reversal)│
│                                                          Service 2026-06-02  │
│  ▸ CLM-007 · 2026-05-29 · $88.50                                                │
│    Billed: $88.50   ·  NPI 1234567890                                            │
│                                                                             │
│  ▸ CLM-014 · 2026-05-15 · $240.00                                                │
│    Billed: $240.00  ·  NPI 1234567890                                            │
│                                                                             │
│  [   Match selected   ]   [   Clear selection   ]                            │
└────────────────────────────────────────────────────────────────────────────┘
```

States:
- Empty (both columns empty) → `<EmptyState eyebrow="Reconciliation · nothing pending" message="Every claim and remittance is paired." />`.
- Loading → `<Skeleton variant="card" />` × 2 columns.
- Error → `<ErrorState error onRetry={refetch} />` at the top.
- Match success → both rows fade out (250ms accent-tinted), toast "Matched CLM-001 ↔ CLP-001".
- Match conflict (409) → `<ErrorState>` with `{error: "already_matched", existing_match_id}` and a "View existing match" affordance that focuses the matched row in the Claims page (route push to `/claims?focus={id}`).

### 11.2 `useReconciliation` hook

```ts
// src/hooks/useReconciliation.ts
export function useReconciliation() {
  const queryClient = useQueryClient();
  const unmatched = useQuery({
    queryKey: ['reconciliation', 'unmatched'],
    queryFn: () => api.listUnmatched(),
    refetchInterval: 30_000,
  });

  const match = useMutation({
    mutationFn: (args: { claimId: string; remitId: string }) =>
      api.matchRemit(args.claimId, args.remitId),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['reconciliation'] });
      queryClient.invalidateQueries({ queryKey: ['claims'] });
      queryClient.invalidateQueries({ queryKey: ['remittances'] });
      queryClient.invalidateQueries({ queryKey: ['activity'] });
    },
  });

  const unmatch = useMutation({
    mutationFn: (args: { claimId: string }) => api.unmatchClaim(args.claimId),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['reconciliation'] });
      queryClient.invalidateQueries({ queryKey: ['claims'] });
      queryClient.invalidateQueries({ queryKey: ['remittances'] });
      queryClient.invalidateQueries({ queryKey: ['activity'] });
    },
  });

  return { unmatched, match, unmatch };
}
```

### 11.3 `claim-state-badge` primitive

Replaces the 4-state logic in `StatusBadge.tsx` with the 7-state enum. Same color palette (success / accent / warning / destructive / muted) — new states reuse existing tokens:

| State | Token |
|---|---|
| `submitted` | accent (blue) |
| `received` | accent (blue, slightly muted) |
| `paid` | success (green) |
| `partial` | warning (amber) |
| `denied` | destructive (red) |
| `reconciled` | success (green, with checkmark icon) |
| `reversed` | warning (amber, with rotate-ccw icon) |
| `draft` (legacy) | muted |

### 11.4 Sidebar entry

```tsx
<NavItem to="/reconciliation" icon={<GitMerge />}>
  Reconciliation
  {unmatchedCount > 0 ? (
    <span className="ml-auto text-[10px] font-mono tabular-nums text-warning">
      {unmatchedCount}
    </span>
  ) : null}
</NavItem>
```

The badge count comes from `useReconciliation().unmatched.data?.claims.length + .remittances.length`. Capped at "99+".

### 11.5 Vitest config cleanup

```ts
// vitest.config.ts (excerpt)
export default defineConfig({
  test: {
    exclude: [...defaultExclude, '.worktrees/**'],
  },
});
```

This stops vitest from picking up `.worktrees/prod-readiness/` (leftover from sub-project 1; gitignored but on disk).

## 12. Data flow

**Worked example — parse-835 with 3 CLPs: one paid, one reversal, one orphan.**

```
POST /api/parse-835 (multipart .txt)
  ↓
parse_835.orchestrate() → ParseResult835(claims=[R_A, R_B, R_C])
                              R_A: CLP02=1, total_paid=124.00, total_charge=124.00
                              R_B: CLP02=22 (reversal), total_paid=-88.50
                              R_C: CLP02=1, total_paid=62.00  (no matching Claim in DB)
  ↓
api.parse_835_route() builds BatchRecord835 + 3 ClaimPayment shapes
  ↓
store.add(batch) inside `with SessionLocal() as s:`
   s.add(Batch row, id=batch_id)
   s.add(Remittance rows: R_A, R_B, R_C; CasAdjustments for each)
   s.commit()                              ← ERA persisted, no matter what
   ↓
   reconcile.run(s, batch_id):
      new_remits = [R_A, R_B, R_C]
      unmatched_claims = [Claim_A (state=submitted, PCN=CLM-001),
                          Claim_B (state=paid,      PCN=CLM-007)]
      matches = match(...)
         → R_A matches Claim_A (PCN=CLM-001, dates within window) → Match(A, R_A, auto)
         → R_B matches Claim_B (PCN=CLM-007) → Match(B, R_B, auto, is_reversal=True)
         → R_C: no Claim with PCN=CLM-099 → unmatched_remits += 1
      intents:
         Match(A, R_A) → apply_payment → new_state=paid (124 ≥ 124)
         Match(B, R_B) → apply_reversal → no state change; prior_claim_state=paid
      s.add(Match rows)
      Claim_A.state = paid
      Claim_A.matched_remittance_id = R_A.id
      Claim_B.state = REVERSED (was paid; original paid-Match row preserved)
      Claim_B.matched_remittance_id = R_B.id
      s.add(ActivityEvents: "reconcile" for A, "reversal" for B)
      for each Remit: s.add CAS-aggregated adjustment_amount
      s.commit()
   on exception:
      log.exception(); s.rollback() (original session)
      s2 = new session; s2.add(ActivityEvent(kind="reconcile_failed")); s2.commit()
   ↓
returns 200 with {parsed_at, totals, reconciliation: {matched: 2, unmatched_claims: 0, unmatched_remittances: 1, skipped: 0}}
  ↓
Frontend useParse('835').onSuccess invalidates
  ['batches', 'claims', 'remittances', 'activity', 'reconciliation/unmatched', 'providers']
  ↓
react-query refetches 6 queries in parallel
  ↓
Claims table: Claim_A row flashes green (state paid), Claim_B row gets a "reversed" sub-badge
Remittances table: R_A, R_B, R_C all show real adjustmentAmount
Reconciliation page: R_C appears in the right column with a badge count of 1
Sidebar: "Reconciliation" nav item shows "1"
```

**Invariants:**
- ERA is persisted before reconciliation runs. A reconciliation crash never loses the 835.
- An unmatched CLP creates a `Remittance` with `claim_id=NULL` and `matched_remittance_id` unset on no Claim. No orphan `Claim` row is fabricated.
- A reversal of a `paid`/`partial` Claim sets `Claim.state = REVERSED`; the pre-reversal state is preserved on the new `Match.prior_claim_state`. The original `paid`/`partial` Match row is preserved unchanged. UI shows the Claim state as "reversed" with the prior state recoverable from the Match row.
- 837P parse never triggers reconciliation — Claims stay `submitted` until an 835 arrives.
- `manual_unmatch` deletes the Match row, clears `Claim.matched_remittance_id`, resets `Claim.state` to `submitted`, and writes an `ActivityEvent(kind="manual_unmatch")`.

## 13. Error handling

| Failure | Behavior |
|---|---|
| Reconciliation crashes mid-run | Logged at `ERROR` with batch_id + traceback. `ActivityEvent(kind="reconcile_failed")` written in a fresh session. Batch + Remittances + CasAdjustments remain persisted. CLPs from this batch that weren't matched yet sit in the unmatched bucket awaiting manual fix or a future ERA. Operator sees the failure in the Activity feed. |
| DB unreachable / corrupt file on startup | `db.init()` raises. `python -m cyclone serve` exits non-zero. Operator sees the traceback in the terminal. No half-started server. |
| Migration fails (bad SQL, disk full) | Transaction rolled back, `user_version` unchanged, exit non-zero. Next startup retries the same migration. No partial schema. |
| Manual match conflict (claim already matched, or remit already matched) | API returns `409 Conflict` with body `{error: "already_matched", existing_match_id}`. Frontend `ErrorState` with a "View existing match" affordance. |
| State transition invalid (e.g. `apply_payment` on a `denied` claim) | `apply_payment` no-ops and writes `ActivityEvent(kind="invalid_state", payload={current_state})`. Claim row unchanged. Operator must unmatch first. |
| Orphan reversal (CLP02=21/22 with no prior Claim) | Remittance stored with `claim_id=NULL`, `is_reversal=True`. Surfaces in the unmatched-remits bucket with a red badge. `ActivityEvent(kind="orphan_reversal")` written. No state mutation. |
| Reversal of a Claim whose state isn't `paid`/`partial` | `apply_reversal` no-ops. `ActivityEvent(kind="reversal_skipped", payload={claim_id, current_state})` written. |
| Concurrent parse-837 + parse-835 | Single SQLite writer + `busy_timeout=5000ms` queues the second write. FastAPI handlers are short so contention is theoretical. If timeout exceeded, returns `503` with body `{error: "db_busy"}`. |
| Bad CAS segment | Parser's existing validation surfaces as a warning on the parse response; `CasAdjustment` only created for well-formed rows. If an insert fails (e.g., NULL amount), reconcile crashes → fail-soft path triggers. |
| `manual_unmatch` on an already-unmatched Claim | 404 from the API. Frontend button disabled when no match exists. |

**No silent failures.** Every anomaly produces an `ActivityEvent` so the operator sees it in the feed.

## 14. Testing

### 14.1 Backend (`backend/tests/`)

**`test_reconcile.py` (~12 tests, pure-function):**
- Match: same PCN, dates within window → matched.
- Match: same PCN, dates outside ±7d → unmatched.
- Match: different NPI but same PCN → still matches (PCN is the key; NPI is metadata).
- Match: multiple Claims for same PCN (resubmissions) → picks closest by date.
- Match: multiple Remittances for same PCN (split payments) → each gets its own Match.
- Match: Remittance with no PCN match → unmatched.
- `apply_payment`: CLP04 ≥ CLM02 → `paid`.
- `apply_payment`: 0 < CLP04 < CLM02 → `partial`.
- `apply_payment`: CLP02=4 → `denied`.
- `apply_payment`: CLP02=other valid code → `received`.
- `apply_reversal`: Claim state=`paid` → no state change, `prior_claim_state=paid` recorded.
- `apply_reversal`: Claim state=`denied` → no-op + reason logged.
- `split_unmatched`: correctly partitions claims and remits by match set.

**`test_db_migrate.py` (~3 tests):**
- Fresh DB: applies all migrations in order, bumps `user_version` to latest.
- Upgrading an old DB (user_version=0): applies 0001 only.
- Re-running on up-to-date DB: no-op (idempotent).
- Migration missing `-- version:` header: raises loudly.

**`test_store_reconcile.py` (~10 tests, integration, in-memory SQLite via `StaticPool`):**
- add(837) → Claims persisted with state=submitted.
- add(835) with auto-match → Claim state updated, Match row created, ActivityEvent written.
- add(835) with reversal → Claim state preserved, Match.prior_claim_state set, ActivityEvent(kind="reversal").
- add(835) with orphan CLP → Remittance stored with claim_id=NULL, list_unmatched("remit") returns it.
- `list_unmatched("both")` shape correctness.
- `manual_match` happy path.
- `manual_match` on already-matched Claim → raises MatchConflict.
- `manual_unmatch` happy path.
- Persistence across `SessionLocal()` instances (simulates restart — data still present).
- Adjustment amounts aggregated from CasAdjustment rows.

**API tests (extend existing `test_api_gets.py` and `test_api_parse_persists.py`, ~7 new):**
- `GET /api/reconciliation/unmatched` shape.
- `POST /api/reconciliation/match` happy path (200 + Claim/Match in response).
- `POST /api/reconciliation/match` conflict (409 with `already_matched`).
- `POST /api/reconciliation/unmatch` happy path (200).
- `POST /api/reconciliation/unmatch` on unmatched Claim (404).
- parse-835 fixture → reconciliation runs → `/api/claims` reflects new state.
- Failed reconcile still persists the batch (fault injection via monkeypatched reconcile).

**Total new backend tests: ~32.** Target: 178 + 32 = **210 passing**.

### 14.2 Frontend (`src/`)

**`src/hooks/useReconciliation.test.ts` (~2 tests):**
- Returns `{unmatched, match, unmatch}` with the right query keys.
- `match.onSuccess` invalidates `['reconciliation', 'claims', 'remittances', 'activity']`.

**`src/pages/Reconciliation.test.tsx` (~2 tests):**
- Renders both columns with unmatched rows; Match button disabled until both selections made.
- Clicking Match calls `api.matchRemit(claimId, remitId)` and renders `ErrorState` on 409.

**Total new frontend tests: ~4.** Target: 3 + 4 = **7 passing**.

### 14.3 End-to-end smoke (manual, documented in the plan)

1. Delete `~/.local/share/cyclone/cyclone.db` if it exists.
2. Start backend on clean DB → file auto-created at `~/.local/share/cyclone/cyclone.db`.
3. `sqlite3 ~/.local/share/cyclone/cyclone.db ".tables"` → 6 tables present.
4. Upload `co_medicaid_837p.txt` → 2 Claims appear with state `submitted` on `/claims`.
5. Upload `co_medicaid_835.txt` → matched Claims flip to `paid`, reversal (if present) flips one back, orphan CLP sits in `/reconciliation`.
6. Open `/reconciliation` → match the orphan → row disappears from the bucket, Claim state updates.
7. `Ctrl-C` the backend; restart → all data still present.
8. `pytest` still passes (210 tests).
9. `npm run build` clean.
10. `vitest` runs 7 tests once (no `.worktrees/` duplicates).

## 15. Migration / rollout

- **No production data to migrate.** Sub-project 1 used an in-memory store; restarting wipes everything by design.
- The default `~/.local/share/cyclone/cyclone.db` is the home directory of the current user. Override with `CYCLONE_DB_URL=postgresql://...` to swap engines without code changes.
- `python -m cyclone serve` calls `db.init()` before uvicorn starts. If `init()` raises, the process exits non-zero. The previous in-memory store is gone; this is a one-way upgrade.
- Backups are a manual `sqlite3 ~/.local/share/cyclone/cyclone.db ".backup /path/to/backup.db"` — documented in the README.

## 16. Out of scope (explicitly)

- Alembic migrations (overkill for one operator + one machine).
- Real-time streaming of NDJSON GET responses into the UI.
- Per-claim detail drawer, batch diff view.
- Multi-status filters, date-range filters, saved filter sets.
- Keyboard-driven navigation.
- 999 ACK, 270/271, 277CA transaction types.
- More 837P validation rules (REF*G1 enforcement, BHT06).
- 835 CAS deep-parsing with reason-code explanations surfaced to the operator.
- Renaming the 835 `ClaimPayment.payer_claim_control_number` field to its semantically correct name (`patient_control_number`).
- Multi-user / multi-machine / auth (any kind).
- Rate limiting, request size limits beyond FastAPI defaults.
- Structured logging, log levels via env, JSON logs.
- Health-check enhancements.
- Docker / docker-compose / any deploy artifact.
- Pre-commit hooks, Makefile, .editorconfig, CONTRIBUTING.md, lint config.
- E2E browser tests (Playwright/Cypress).

## 17. Acceptance checklist

### 17.1 Functional

- [ ] `pytest` passes; total ≥ 178 + 32 = **210**.
- [ ] `npm run build` clean; `npm run typecheck` clean.
- [ ] `npm test` runs 7 tests once (no `.worktrees/` duplicates).
- [ ] Backend startup creates `~/.local/share/cyclone/cyclone.db` with 6 tables.
- [ ] Parse-837 → Claims appear with state `submitted` on `/claims`.
- [ ] Parse-835 → matched Claims transition through the state machine; orphan CLPs land in `/reconciliation`.
- [ ] Reversal of a `paid` Claim sets `Claim.state = REVERSED`, sets `Match.prior_claim_state=paid`, writes `reversal` activity event. The original `paid` Match row is preserved.
- [ ] Manual match from `/reconciliation` removes both rows from the bucket and updates the Claim state.
- [ ] Manual unmatch from `/claims` (or via API) reverses the pairing.
- [ ] Backend restart preserves all data.
- [ ] `CYCLONE_DB_URL=postgresql://...` switches the engine (smoke-tested against a throwaway SQLite file at a custom path).
- [ ] Reconciliation crash on a malformed 835 fixture still persists the ERA and writes a `reconcile_failed` activity event.

### 17.2 Visual / aesthetic

- [ ] `/reconciliation` uses the existing surface / hairline chrome; no new colors, no new typeface, no new layout primitive.
- [ ] Empty state on `/reconciliation` uses the `EmptyState` primitive with an instrument-label eyebrow ("Reconciliation · nothing pending").
- [ ] Match button echoes the sidebar `nav-active` 1px accent line treatment.
- [ ] Matched rows fade out (250ms accent-tinted, not destructive — they succeeded, not errored).
- [ ] Conflict (409) renders `ErrorState` with a "View existing match" affordance, not a destructive takeover.
- [ ] Sidebar nav badge for unmatched count uses the existing `text-warning` + monospace tabular-nums treatment; capped at "99+".
- [ ] `claim-state-badge` reuses the existing 4-token palette — no new color tokens introduced.
- [ ] `adjustmentAmount` shown in the Remittances table is the CAS-aggregated value (real dollar figure from the 835), not `0.0`.

### 17.3 Operational

- [ ] Migrations live in `backend/src/cyclone/migrations/0001_initial.sql` with a `-- version: 1` header.
- [ ] `cyclone.db_migrate.run(engine)` is idempotent and atomic per migration.
- [ ] Failed migration rolls back `user_version` to its prior value.
- [ ] README documents `CYCLONE_DB_URL` and the default DB file path; documents the `sqlite3 .backup` recipe.
- [ ] Vitest config excludes `.worktrees/`.

### 17.4 Audit

- [ ] Every reconciliation anomaly (crash, skip, conflict, orphan reversal) writes an `ActivityEvent` so the operator sees it in the feed.
- [ ] The 1 outstanding TODO marker in `backend/src/cyclone/store.py:376` (`adjustmentAmount: 0.0`) is removed.
- [ ] The 107 unchecked checkboxes in `docs/superpowers/plans/2026-06-19-cyclone-production-readiness.md` are ticked off in a single housekeeping commit.