merge: SP38 orphan-ack housekeeping into main

Captures the historical 804-orphan 999 situation as a known
artifact (RUNBOOK entry + status command) and provides a
one-shot idempotent synthetic-batch seeder so future acks for
the orphan ST02s can resolve against batch_envelope_index.

6 commits merged atomically (no squash — the SP-N merge commit
is the audit record):
  d776a4a docs(spec): design for SP38 orphan-ack housekeeping
  8890627 docs(plan): SP38 orphan-ack housekeeping plan
  ad14b56 feat(sp38): CycloneStore.find_ack_orphan_st02_summary + reconcile_orphan_st02s
  9ef749c feat(sp38): 'cyclone ack-orphans {status,reconcile}' CLI subcommands
  76923a7 docs(sp38): RUNBOOK entry for orphan-ack housekeeping
  07ea7ca fix(sp38): restore per-kind control_number in find_ack_orphans + review cleanups

Test delta: +36 passed (12 store helper + 7 CLI + 17 claim_acks
regression including the pr-reviewer 277ca/ta1 control_number
fix). No new failures.

Live verified: cyclone ack-orphans status exits 0 with 4 distinct
orphan ST02s (419+226+106+53=804) matching the SQLite investigation.

.env.example

@@ -17,4 +17,24 @@ VITE_API_BASE_URL=
 
 # Optional. Set to 1 to disable auth entirely (DEV ONLY). When set,
 # the backend auto-grants admin access without checking credentials.
-# CYCLONE_AUTH_DISABLED=0
+# CYCLONE_AUTH_DISABLED=0
+
+# ─── Gainwell / HCPF SFTP credentials (operator convention) ─────────────
+# These mirror what /home/tyler/EDI/scripts/upload_claims.sh exports and
+# what the operator's SFTP client uses. Cyclone's secrets module looks up
+# CYCLONE_SFTP_PASSWORD (or _FILE), not GAINWELL_SFTP_PASS — to bridge:
+#
+#   export CYCLONE_SFTP_PASSWORD="$GAINWELL_SFTP_PASS"
+#
+# or for the daemon, set CYCLONE_SFTP_PASSWORD_FILE to a 0600 file.
+GAINWELL_SFTP_USER=colorado-fts\coxix_prod_11525703
+GAINWELL_SFTP_HOST=mft.gainwelltechnologies.com
+GAINWELL_SFTP_PASS=
+GAINWELL_REMOTE_DIR=/CO XIX/PROD/coxix_prod_11525703/ToHPE
+
+# CYCLONE_SFTP_PASSWORD=                 # mirror of GAINWELL_SFTP_PASS
+# CYCLONE_SFTP_PASSWORD_FILE=            # path to a 0600 file containing it
+
+# CYCLONE_SCHEDULER_AUTOSTART=           # 1/true/yes to start the MFT poll loop on API launch
+# CYCLONE_SCHEDULER_POLL_SECONDS=60      # poll interval when autostart is on
+# CYCLONE_TAIL_HEARTBEAT_S=15            # NDJSON stream heartbeat interval

.gitignore

@@ -20,6 +20,16 @@ build/
 *.swp
 *.swo
 
+# macOS extraction residue (AppleDouble / __MACOSX from unzip on macOS).
+# These are paired with every regular file in an extracted zip — never data.
+__MACOSX/
+._*
+
+# Operator drop zone (untracked working dir; contents are HCPF-delivered
+# inbound files, never source). Use `mkdir -p ingest && touch ingest/.gitkeep`
+# if you want the directory itself in the repo.
+ingest/
+
 # Local config
 .env
 .env.local

CLAUDE.md

@@ -125,7 +125,7 @@ Frontend triplet for any live page: `use<X>(params)` (initial fetch) + `useTailS
 
 ## Backend at a glance
 
-`backend/src/cyclone/` is a single namespace. The two largest files are `api.py` (~3,548 LOC, the only large file) and `store.py` (~2,423 LOC, the `CycloneStore` facade — SP21 is in flight to split it into a `cyclone/store/` subpackage; the public API stays unchanged). Subpackages: `api_routers/` (acks, admin, health, ta1_acks), `clearhouse/` (Clearhouse + SftpClient), `edi/` (filenames), `parsers/` (X12 transaction parsers + models + validators + serializers), `workflow/` (placeholder for future sub-project 6).
+`backend/src/cyclone/` is a single namespace. The two largest files are `api.py` (~3,548 LOC, the only large file) and `store.py` (~2,423 LOC, the `CycloneStore` facade — SP21 is in flight to split it into a `cyclone/store/` subpackage; the public API stays unchanged). Subpackages: `api_routers/` (acks, admin, health, ta1_acks), `clearhouse/` (Clearhouse + SftpClient), `edi/` (filenames), `parsers/` (X12 transaction parsers + models + validators + serializers), `submission/` (SP37 — canonical `submit_file` helper shared by `cyclone submit-batch` CLI + `POST /api/submit-batch` HTTP endpoint; owns parse → DB-write → SFTP-upload → audit per file), `workflow/` (placeholder for future sub-project 6).
 
 The store is the only read/write surface for the database; every mutating endpoint goes through it. All persistence flows through SQLAlchemy sessions via `db.SessionLocal()()`. SQLAlchemy ORM models live in `db.py`; 12 SQL migrations under `migrations/` (0001_initial through 0012_backups) are walked in order by `db_migrate.py`.
 
@@ -137,6 +137,34 @@ Config: `config/payers.yaml` is the on-disk source for providers / payers / clea
 
 Secrets live in the macOS Keychain (via `keyring` + `cyclone.secrets`): SQLCipher key (service `cyclone`, account `cyclone.db.key`), SFTP password, backup passphrase. No secrets on disk in plaintext.
 
+## Production SFTP posture (this box: manual mode)
+
+This host runs in **manual SFTP mode** against Gainwell's MOVEit Transfer MFT at `mft.gainwelltechnologies.com`. The seeded `dzinesco` clearhouse keeps `sftp_block.stub: true`; the operator moves files to/from Gainwell with their SFTP client and drops inbound files into `ingest/` for cyclone to ingest. Do NOT flip `stub` to `false` from this host — see "Auth caveat" below.
+
+### Env var convention
+
+The operator's shell exports the Gainwell creds as `GAINWELL_SFTP_USER`, `GAINWELL_SFTP_PASS`, `GAINWELL_SFTP_HOST`, `GAINWELL_REMOTE_DIR`. Cyclone's `secrets.get_secret()` looks up `CYCLONE_SFTP_PASSWORD` (or `CYCLONE_SFTP_PASSWORD_FILE`) per `secrets._ENV_NAME_FOR`. The two are NOT the same name — bridge them per-call or in your shell rc:
+
+```bash
+export CYCLONE_SFTP_PASSWORD="$GAINWELL_SFTP_PASS"
+```
+
+### Inbound drop zone
+
+`/home/tyler/dev/cyclone/ingest/` is the operator-maintained staging dir for inbound MFT files (999 acks, TA1, 835 remittances, 277CA claim acks). Files here are NOT auto-watched; processing happens via the procedure in `docs/RUNBOOK.md` § "Manual SFTP mode". At time of writing this dir holds ~1500 unprocessed 999 acks + 1 TA1 + 1 835 from early July 2026 — the local ingest flow clears them.
+
+### Auth caveat (do not retry)
+
+Paramiko reaches `MOVEit Transfer SFTP` cleanly (SSH kex completes, MOVEit offers password auth) but `AuthenticationException: Authentication failed` is returned despite the operator confirming the credentials are known-good from another host. Most likely cause: MOVEit Transfer's IP-based access control — this host's public IP `103.14.26.95` is not whitelisted. Repeated auth attempts risk account lockout. Do NOT keep guessing. Resolve by either: (a) whitelisting this IP with Gainwell's MFT admin, or (b) staying in manual mode and moving files via the operator's SFTP client.
+
+### Inbound ingestion paths
+
+The canonical way to write 999/TA1/277CA/835 rows into the DB is `Scheduler.process_inbound_files`, exposed as the CLI `cyclone pull-inbound --date YYYYMMDD` and the HTTP `POST /api/admin/scheduler/pull-inbound`. **There is no `parse-999` / `parse-ta1` / `parse-277ca` CLI command** (CLAUDE.md's "CLI" section above is aspirational on those three). The `parse-837` and `parse-835` CLIs exist but only emit JSON files to `--output-dir`; they do NOT write to the DB. For DB writes, use `pull-inbound` (which dedupes via `processed_inbound_files`).
+
+### Daemon hot-reload
+
+`python -m cyclone serve` runs as root (started by `tini`) and keeps the SFTP block in memory. Flipping `stub` directly in the DB (`store.update_clearhouse(...)`) does NOT auto-reload the daemon's view — either restart the daemon or use `PATCH /api/clearhouse` (which calls `scheduler.reconfigure_scheduler` to hot-reload).
+
 ## Frontend at a glance
 
 `src/` is React 18 + TypeScript + Vite. Routes register in `src/App.tsx` (11 pages, all under a `<Layout>` route wrapper). Pages are pure renderers — every page pairs with a `use<X>` data hook in `src/hooks/` and renders a `<PageHeader>` + a table/list/KPI grid. Drawers (`ClaimDrawer/`, `RemitDrawer/`, plus the new `ProviderDrawer/` and `AckDrawer/`) are mounted by the page and their open/close state is mirrored to the URL via `useDrawerUrlState` so deep-links round-trip. Drill-stack navigation is provided by `<DrillStackProvider>` in `src/components/drill/`.

backend/.gitignore

@@ -7,3 +7,4 @@ __pycache__/
 venv/
 build/
 dist/
+var/

backend/src/cyclone/api_routers/__init__.py

@@ -1 +1,57 @@
-"""Resource-group routers. Imported and registered by ``cyclone.api``."""
+"""Per-resource FastAPI routers.
+
+`api.py` does `for r in routers: app.include_router(r)`. New
+routers register themselves here in alphabetical order. Helpers
+shared by 2+ routers live in `_shared.py` (private to the package).
+
+Every router except ``health`` declares its own
+``APIRouter(dependencies=[Depends(matrix_gate)])`` — keep that
+invariant here so adding a new router doesn't silently miss the gate.
+"""
+from fastapi import APIRouter
+
+from cyclone.api_routers import (
+    acks,
+    activity,
+    admin,
+    batches,
+    claim_acks,
+    claims,
+    clearhouse,
+    config,
+    dashboard,
+    eligibility,
+    health,
+    inbox,
+    parse,
+    payers,
+    providers,
+    reconciliation,
+    remittances,
+    submission,
+    ta1_acks,
+)
+
+routers: list[APIRouter] = [
+    acks.router,        # gated
+    activity.router,    # gated
+    admin.router,       # gated
+    batches.router,     # gated
+    claim_acks.router,  # gated
+    claims.router,      # gated
+    clearhouse.router,  # gated
+    config.router,      # gated
+    dashboard.router,   # gated
+    eligibility.router, # gated
+    health.router,      # public — health probes must work pre-auth
+    inbox.router,       # gated
+    parse.router,       # gated
+    payers.router,      # gated
+    providers.router,   # gated
+    reconciliation.router, # gated
+    remittances.router, # gated
+    submission.router,  # gated
+    ta1_acks.router,    # gated
+]
+
+__all__ = ["routers"]

backend/src/cyclone/api_routers/_shared.py

@@ -0,0 +1,273 @@
+"""Cross-router helpers for the api_routers package.
+
+Private to the package (leading underscore). Only routers in this
+package import from here. Helpers graduate here when at least two
+routers need them — single-router helpers stay in the router that
+uses them.
+
+Helpers currently promoted here:
+
+- :func:`_actor_user_id` — promoted early (during SP36 Task 11
+  / clearhouse extraction) because the clearhouse router needs
+  it and the 2 remaining call-sites in ``api.py`` (parse-999 ack
+  block, parse-277ca ack block) are both inside the parse
+  surface that Task 16 will extract. Promoting now is cheaper
+  than leaving a cross-module ``from cyclone.api import _actor_user_id``
+  that would create an import-cycle at registry load time.
+
+- :data:`PAYER_FACTORIES` / :data:`PAYER_FACTORIES_835` — SP36
+  Task 16: payer config dicts lifted from ``api.py`` alongside
+  the ``_resolve_payer`` / ``_resolve_payer_835`` helpers that
+  consume them. The two helpers each touch a single ``PAYER_FACTORIES*``
+  dict; keeping both halves of the pair in one module removes a
+  circular import (parse.py → _shared._resolve_payer → api.PAYER_FACTORIES).
+
+- :func:`_resolve_payer` / :func:`_resolve_payer_835` — used by
+  ``parse-837`` and ``parse-835`` endpoints respectively. Promoted
+  in SP36 Task 16 alongside the PAYER_FACTORIES dicts.
+
+- :func:`_transaction_set_id_from_segments` — used by
+  ``parse-837`` and ``parse-835`` envelope guards. Promoted in
+  SP36 Task 16.
+
+- :func:`_build_and_persist_ack` — used by ``parse-837`` (when
+  ``?ack=true``). Promoted in SP36 Task 16.
+
+- :func:`_reconciliation_summary_for_batch` — used by
+  ``parse-835``. Promoted in SP36 Task 16.
+
+- :func:`_ta1_synthetic_source_batch_id` — used by ``parse-ta1``.
+  Promoted in SP36 Task 16.
+
+- :func:`_serialize_ta1` — used by ``parse-ta1`` to build the
+  raw TA1 round-trip text. Promoted in SP36 Task 16 per the
+  plan's "8 helpers" specification; technically a single-router
+  helper per D4 but moved here for symmetry with the other parse
+  serializers.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from fastapi import HTTPException, Request
+
+from cyclone import db
+from cyclone.parsers.batch_ack_builder import build_ack_for_batch
+from cyclone.parsers.payer import PayerConfig, PayerConfig835
+from cyclone.parsers.serialize_999 import serialize_999
+from cyclone.store import store
+
+log = logging.getLogger(__name__)
+
+
+# --------------------------------------------------------------------------- #
+# Actor user id (SP36 Task 11 — early-promoted)
+# --------------------------------------------------------------------------- #
+
+
+def _actor_user_id(request: Request) -> int | None:
+    """Return the acting user's id from ``request.state.user``, or None.
+
+    ``get_current_user``/``matrix_gate`` populate ``request.state.user``
+    for both the authenticated path and the AUTH_DISABLED escape hatch.
+    Returns None when the state hasn't been set (e.g. background jobs
+    or unit tests that bypass auth). Used to stamp ``user_id`` onto
+    audit events without crashing the request.
+    """
+    user = getattr(request.state, "user", None)
+    if user is None:
+        return None
+    return getattr(user, "id", None)
+
+
+# --------------------------------------------------------------------------- #
+# Payer config dicts (SP36 Task 16)
+# --------------------------------------------------------------------------- #
+#
+# Mirror cli._PAYER_FACTORIES. Kept here (not in the parse router) so
+# the ``_resolve_payer`` / ``_resolve_payer_835`` helpers can import
+# their backing dicts without a circular import.
+
+
+PAYER_FACTORIES: dict[str, Any] = {
+    "co_medicaid": PayerConfig.co_medicaid,
+    "generic_837p": PayerConfig.generic_837p,
+}
+
+PAYER_FACTORIES_835: dict[str, Any] = {
+    "co_medicaid_835": PayerConfig835.co_medicaid_835,
+    "generic_835": PayerConfig835.generic_835,
+}
+
+
+# --------------------------------------------------------------------------- #
+# Payer resolution (SP36 Task 16)
+# --------------------------------------------------------------------------- #
+
+
+def _resolve_payer(name: str) -> PayerConfig:
+    if name not in PAYER_FACTORIES:
+        raise HTTPException(
+            status_code=400,
+            detail={
+                "error": "Unknown payer",
+                "detail": f"Unknown payer {name!r}. Choose from: {', '.join(PAYER_FACTORIES)}",
+            },
+        )
+    return PAYER_FACTORIES[name]()
+
+
+def _resolve_payer_835(name: str) -> PayerConfig835:
+    if name not in PAYER_FACTORIES_835:
+        raise HTTPException(
+            status_code=400,
+            detail={
+                "error": "Unknown payer",
+                "detail": f"Unknown payer {name!r}. Choose from: {', '.join(PAYER_FACTORIES_835)}",
+            },
+        )
+    return PAYER_FACTORIES_835[name]()
+
+
+# --------------------------------------------------------------------------- #
+# Envelope detection (SP36 Task 16)
+# --------------------------------------------------------------------------- #
+
+
+def _transaction_set_id_from_segments(segments: list[list[str]]) -> str | None:
+    """Return the ST01 transaction-set id (``"837"``, ``"835"``, ``"999"``...).
+
+    SP35 helper: scans the first few tokenized segments for the ST
+    segment and returns its second element (ST01). Returns None when no
+    ST is present — e.g. a TA1 file, which uses the bare TA1 segment
+    and no ST envelope. The endpoint-level envelope guards treat
+    ``None`` as "no ST found; let the parser decide" so TA1 files
+    routed through the wrong endpoint still surface a parse error
+    rather than a misleading "expected 837p, got ''" message.
+    """
+    for seg in segments[:5]:  # ST is always the second segment after ISA
+        if seg and seg[0] == "ST" and len(seg) > 1:
+            return seg[1]
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# 999 ACK builder (SP36 Task 16)
+# --------------------------------------------------------------------------- #
+
+
+def _build_and_persist_ack(batch_id: str) -> dict | None:
+    """Build a 999 ACK for ``batch_id`` and persist the row.
+
+    Returns the ack payload dict (matches the ``/api/parse-999``
+    response shape so the JSON and NDJSON clients can share the
+    schema) or None if the build failed. The build is fail-soft:
+    errors are logged but never abort the 837 ingest, because the
+    user-visible 837 result is still correct.
+    """
+    try:
+        ack_result = build_ack_for_batch(batch_id)
+    except Exception:
+        log.exception("build_ack_for_batch failed for %s", batch_id)
+        return None
+    fg = ack_result.functional_group_acks[0] if ack_result.functional_group_acks else None
+    if fg is None:
+        return None
+    raw_text = serialize_999(ack_result, interchange_control_number=ack_result.envelope.control_number)
+    row = store.add_ack(
+        source_batch_id=batch_id,
+        accepted_count=fg.accepted_count,
+        rejected_count=fg.rejected_count,
+        received_count=fg.received_count,
+        ack_code=fg.ack_code,
+        raw_json=json.loads(ack_result.model_dump_json()),
+    )
+    return {
+        "id": row.id,
+        "accepted_count": fg.accepted_count,
+        "rejected_count": fg.rejected_count,
+        "received_count": fg.received_count,
+        "ack_code": fg.ack_code,
+        "source_batch_id": batch_id,
+        "raw_999_text": raw_text,
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Reconciliation summary (SP36 Task 16)
+# --------------------------------------------------------------------------- #
+
+
+def _reconciliation_summary_for_batch(batch_id: str) -> dict:
+    """Return ``{matched, unmatched_claims, unmatched_remittances, skipped}`` for a batch.
+
+    Reads from the DB after ``store.add()`` has already run reconciliation
+    synchronously (SP27 Task 10: ``reconcile.run(s, batch_id)`` inside the
+    ingest session, before commit). Counts are observed at this moment;
+    a subsequent manual match/unmatch will not be reflected until the
+    next request.
+
+    ``skipped`` is reserved for future use — the orchestrator tracks
+    skipped claims internally but does not surface a queryable count.
+    """
+    from sqlalchemy import func, select
+    from cyclone.db import Match, Remittance
+
+    with db.SessionLocal()() as s:
+        matched = s.execute(
+            select(func.count(Match.id)).where(
+                Match.remittance_id.in_(
+                    select(Remittance.id).where(Remittance.batch_id == batch_id)
+                )
+            )
+        ).scalar_one()
+
+    # Pull unmatched via the store (small result set; cheap).
+    unmatched = store.list_unmatched(kind="both")
+    return {
+        "matched": matched,
+        "unmatched_claims": len(unmatched["claims"]),
+        "unmatched_remittances": len(unmatched["remittances"]),
+        "skipped": 0,  # reserved — T10 does not persist a skipped count
+    }
+
+
+# --------------------------------------------------------------------------- #
+# TA1 synthetic source batch id (SP36 Task 16)
+# --------------------------------------------------------------------------- #
+
+
+def _ta1_synthetic_source_batch_id(interchange_control_number: str) -> str:
+    """Return a synthetic ``batches.id`` for a received TA1 with no source batch.
+
+    Mirrors :func:`_ack_synthetic_source_batch_id` (in
+    ``cyclone.handlers._ack_id``). The ta1_acks.source_batch_id
+    FK requires a row in batches; for received TA1s we synthesize an
+    id of the form ``TA1-<ISA13>``. The row is NOT created in batches
+    (same FK-is-no-op convention as the 999 path).
+    """
+    return f"TA1-{(interchange_control_number or '').strip() or '000000001'}"
+
+
+# --------------------------------------------------------------------------- #
+# TA1 serializer (SP36 Task 16)
+# --------------------------------------------------------------------------- #
+
+
+def _serialize_ta1(result) -> str:
+    """Render a TA1 file from a ParseResultTa1 for the ``raw_ta1_text`` field.
+
+    Mirrors what the parser consumed: ISA envelope → TA1 → IEA. We
+    rebuild minimal ISA fields from the envelope plus the TA1 segment
+    verbatim. The serializer is intentionally tiny — TA1 has no GS/ST,
+    so there's no functional-group structure to round-trip.
+    """
+    ta1 = result.ta1
+    parts = [
+        f"TA1*{ta1.control_number}*{ta1.interchange_date.strftime('%y%m%d') if ta1.interchange_date else ''}*"
+        f"{ta1.interchange_time or ''}*{ta1.ack_code}*{ta1.note_code or ''}*"
+        f"{ta1.ack_generated_date.strftime('%y%m%d') if ta1.ack_generated_date else ''}",
+    ]
+    return "~".join(parts) + "~"

backend/src/cyclone/api_routers/acks.py

@@ -1,12 +1,17 @@
-"""``/api/acks`` — list, detail, and live-tail stream for 999 ACKs.
+"""``/api/acks`` and ``/api/277ca-acks`` — list, detail, and live-tail.
 
-These are the persisted acknowledgment rows produced by
+999 ACKs are the persisted acknowledgment rows produced by
 ``POST /api/parse-999``. The frontend ``useAcks`` hook re-shapes the
 list payload to its ``Ack`` interface in ``src/types/index.ts``.
 
-The detail endpoint returns the full ``raw_json`` payload plus the
-regenerated ``raw_999_text`` so the UI can show "view source" without a
-second round-trip.
+277CA ACKs are the persisted Claim Acknowledgment rows produced by
+``POST /api/parse-277ca``. The frontend ``useAcks`` hook treats them
+as a second source alongside 999 — the row shape is normalised in
+``cyclone.store.ui.to_ui_two77ca_ack``.
+
+The 999 detail endpoint returns the full ``raw_json`` payload plus
+the regenerated ``raw_999_text`` so the UI can show "view source"
+without a second round-trip.
 
 SP25: ``/api/acks/stream`` joins the live-tail triplet — the Acks
 page mounts ``useTailStream("acks")`` and ``useMergedTail("acks", …)``
@@ -18,7 +23,7 @@ from __future__ import annotations
 import logging
 from typing import Any, AsyncIterator
 
-from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from fastapi.responses import StreamingResponse
 
 from cyclone import db
@@ -28,12 +33,13 @@ from cyclone.api_helpers import (
     tail_events,
     wants_ndjson,
 )
+from cyclone.auth.deps import matrix_gate
 from cyclone.parsers.models_999 import ParseResult999
 from cyclone.parsers.serialize_999 import serialize_999
 from cyclone.pubsub import EventBus
-from cyclone.store import store, to_ui_ack
+from cyclone.store import store, to_ui_ack, to_ui_two77ca_ack
 
-router = APIRouter()
+router = APIRouter(dependencies=[Depends(matrix_gate)])
 
 log = logging.getLogger(__name__)
 
@@ -177,3 +183,41 @@ def get_ack_endpoint(ack_id: int) -> dict:
     else:
         body["raw_999_text"] = None
     return body
+
+
+# -- 277CA ACKs -------------------------------------------------------------
+# SP36 Task 2: these two endpoints moved here from api.py (lines 1278-1318).
+# 277CA ACKs share the same shape-of-life contract as 999 ACKs: persisted by
+# a parse endpoint, listed newest-first, detail returns raw_json so the UI
+# can show "view source" without a round-trip.
+
+
+@router.get("/api/277ca-acks")
+def list_277ca_acks_endpoint(
+    limit: int = Query(100, ge=1, le=5000),
+) -> Any:
+    """Return the list of persisted 277CA ACKs, newest first.
+
+    SP28: each item gains ``linked_claim_ids`` (batch-fetched via
+    the shared ``_find_linked_claim_ids_for_acks`` helper — one
+    SELECT keyed on ``ack_kind``, no N+1) so the Acks page row
+    can render the "🔗 N claims" badge inline.
+    """
+    rows = store.list_277ca_acks()
+    items = [to_ui_two77ca_ack(r) for r in rows[:limit]]
+    ack_ids = [r.id for r in rows]
+    linked_map = _find_linked_claim_ids_for_acks(ack_ids, kind="277ca")
+    for item, aid in zip(items, ack_ids[:limit]):
+        item["linked_claim_ids"] = linked_map.get(aid, [])
+    return {"total": len(rows), "items": items}
+
+
+@router.get("/api/277ca-acks/{ack_id}")
+def get_277ca_ack_endpoint(ack_id: int) -> dict:
+    """Return one persisted 277CA ACK row with its parsed detail."""
+    row = store.get_277ca_ack(ack_id)
+    if row is None:
+        raise HTTPException(status_code=404, detail=f"277CA ACK {ack_id} not found")
+    body = to_ui_two77ca_ack(row)
+    body["raw_json"] = row.raw_json
+    return body

backend/src/cyclone/api_routers/activity.py

@@ -0,0 +1,102 @@
+"""``/api/activity`` and ``/api/activity/stream`` — operator-facing event log.
+
+Two endpoints, both gated by ``matrix_gate``:
+
+- ``GET /api/activity``          — paginated event list with ``kind`` /
+  ``since`` filters, plus an NDJSON variant when the caller sends
+  ``Accept: application/x-ndjson``.
+- ``GET /api/activity/stream``   — NDJSON live-tail: snapshot of the
+  most recent N events, then ``activity_recorded`` events as they
+  hit the store. Default ``limit`` is 50 (smaller than the list
+  endpoint's 200) because activity is high-volume — callers usually
+  want the most recent handful, not a full replay.
+
+The snapshot halves of ``/api/activity`` and ``/api/activity/stream``
+share the same in-memory filter logic (``kind`` + ``since``) so the
+two endpoints are interchangeable for the snapshot half.
+
+SP36 Task 10: this block moved here from ``api.py:2606`` (the
+``/api/activity*`` pair).
+"""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator
+
+from fastapi import APIRouter, Depends, Query, Request
+from fastapi.responses import StreamingResponse
+
+from cyclone.api_helpers import (
+    ndjson_line as _ndjson_line,
+    ndjson_stream_list as _ndjson_stream_list,
+    tail_events as _tail_events,
+    wants_ndjson as _wants_ndjson,
+)
+from cyclone.auth.deps import matrix_gate
+from cyclone.pubsub import EventBus
+from cyclone.store import store
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.get("/api/activity")
+def list_activity(
+    request: Request,
+    kind: str | None = Query(None),
+    since: str | None = Query(None),
+    limit: int = Query(200, ge=1, le=5000),
+) -> Any:
+    events = store.recent_activity(limit=limit)
+    if kind is not None:
+        events = [e for e in events if e["kind"] == kind]
+    if since is not None:
+        events = [e for e in events if e["timestamp"] >= since]
+    total = len(events)
+    has_more = False
+    if _wants_ndjson(request):
+        return StreamingResponse(
+            _ndjson_stream_list(events, total, total, has_more),
+            media_type="application/x-ndjson",
+        )
+    return {
+        "items": events,
+        "total": total,
+        "returned": total,
+        "has_more": has_more,
+    }
+
+
+@router.get("/api/activity/stream")
+async def activity_stream(
+    request: Request,
+    kind: str | None = Query(None),
+    since: str | None = Query(None),
+    limit: int = Query(50, ge=1, le=5000),
+) -> StreamingResponse:
+    """Stream Activity events as NDJSON: snapshot first, then live events.
+
+    Subscribes to ``activity_recorded``. Default ``limit`` is 50
+    (smaller than the list endpoint's 200) because activity is
+    high-volume — callers usually want the most recent handful, not a
+    full replay.
+    """
+    bus: EventBus = request.app.state.event_bus
+
+    async def gen() -> AsyncIterator[bytes]:
+        # Snapshot reuses the same in-memory filter as ``list_activity``
+        # so the two endpoints are interchangeable for the snapshot
+        # half.
+        events = store.recent_activity(limit=limit)
+        if kind is not None:
+            events = [e for e in events if e["kind"] == kind]
+        if since is not None:
+            events = [e for e in events if e["timestamp"] >= since]
+        for ev in events:
+            yield _ndjson_line({"type": "item", "data": ev})
+        yield _ndjson_line({
+            "type": "snapshot_end", "data": {"count": len(events)},
+        })
+
+        async for chunk in _tail_events(request, bus, ["activity_recorded"]):
+            yield chunk
+
+    return StreamingResponse(gen(), media_type="application/x-ndjson")

backend/src/cyclone/api_routers/admin.py

@@ -1,23 +1,44 @@
-"""``/api/admin/validate-provider`` — NPI + Tax ID liveness probe (SP20).
+"""``/api/admin/*`` — operator-only endpoints.
 
-Pure read-only endpoint that runs the local NPI Luhn + EIN format checks
-without touching the DB. Useful for:
-- operators vetting a new provider before adding them to the registry,
-- the dashboard's "validate" button on a Provider row,
-- smoke-testing the SP20 checks after a deploy.
+The /api/admin namespace covers:
 
-Both query params are optional; omitting one just skips that check.
-Returns the per-check result dict so the caller can distinguish "bad
-format" from "bad checksum".
+* **audit-log** (SP11): list + chain-verify the tamper-evident log
+* **db/rotate-key**: SQLCipher key rotation (SP12)
+* **backup**: create / list / status / verify / restore / prune / scheduler (SP15)
+* **scheduler**: backup & main scheduler control + processed-files log
+* **reload-config**: hot-reload ``config/payers.yaml`` after edits
+* **validate-provider**: NPI + Tax ID liveness probe (SP20)
+
+All routes on this router are gated by ``matrix_gate`` — declared
+once on the ``APIRouter`` constructor. ``/api/admin/validate-provider``
+lives here too because it's an admin-shaped read-only probe.
+
+SP36 Task 3: the 20 admin endpoints formerly in ``cyclone.api``
+(audit-log ×2, db/rotate-key ×1, backup ×10, scheduler ×6,
+reload-config ×1) moved here from ``api.py:3321-4052`` and
+``api.py:4269-4276``. The non-admin ``/api/config/*`` and
+``/api/payers/{id}/summary`` routes that bracketed those blocks
+stay in ``api.py`` for now — they're extracted in Tasks 5 & 6.
 """
 from __future__ import annotations
 
-from fastapi import APIRouter, Query
+import json
+import logging
+import threading
+import time
+from typing import Any
 
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from cyclone import db
+from cyclone.audit_log import verify_chain
+from cyclone.auth.deps import matrix_gate
+from cyclone.clearhouse import InboundFile
 from cyclone.npi import is_valid_npi, is_valid_tax_id, normalize_tax_id
 
+router = APIRouter(dependencies=[Depends(matrix_gate)])
 
-router = APIRouter()
+log = logging.getLogger(__name__)
 
 
 @router.get("/api/admin/validate-provider")
@@ -57,4 +78,751 @@ def validate_provider(
             "normalized": normalized,
         }
 
-    return result
+    return result
+
+
+# --------------------------------------------------------------------------- #
+# SP36 Task 3: the 20 admin endpoints below were moved here from api.py.       #
+# --------------------------------------------------------------------------- #
+
+
+# --------------------------------------------------------------------------- #
+# SP11: tamper-evident audit log (admin)
+# --------------------------------------------------------------------------- #
+
+
+@router.get("/api/admin/audit-log")
+def list_audit_log_endpoint(
+    entity_type: str | None = Query(default=None),
+    entity_id: str | None = Query(default=None),
+    event_type: str | None = Query(default=None),
+    limit: int = Query(default=100, ge=1, le=1000),
+) -> Any:
+    """List audit-log rows, newest first, with optional filters.
+
+    Filters match the (entity_type, entity_id) pair (typical use:
+    "show me everything that happened to claim C-123") or a single
+    event_type (typical use: "show me all clearhouse.submitted
+    events today").
+    """
+    with db.SessionLocal()() as s:
+        q = s.query(db.AuditLog)
+        if entity_type:
+            q = q.filter(db.AuditLog.entity_type == entity_type)
+        if entity_id:
+            q = q.filter(db.AuditLog.entity_id == entity_id)
+        if event_type:
+            q = q.filter(db.AuditLog.event_type == event_type)
+        rows = q.order_by(db.AuditLog.id.desc()).limit(limit).all()
+        return {
+            "total": len(rows),
+            "items": [
+                {
+                    "id": r.id,
+                    "event_type": r.event_type,
+                    "entity_type": r.entity_type,
+                    "entity_id": r.entity_id,
+                    "actor": r.actor,
+                    "payload": json.loads(r.payload_json) if r.payload_json else None,
+                    "created_at": r.created_at.isoformat() if r.created_at else None,
+                    "prev_hash": r.prev_hash,
+                    "hash": r.hash,
+                }
+                for r in rows
+            ],
+        }
+
+
+@router.get("/api/admin/audit-log/verify")
+def verify_audit_log_endpoint() -> Any:
+    """Walk the audit-log chain and verify every row's hash.
+
+    Returns ``{"ok": true, "checked": N}`` for a clean chain, or
+    ``{"ok": false, "checked": K, "first_bad_id": X, "reason": "..."}``
+    for a broken chain. This is the operator's "did anyone tamper?"
+    endpoint; run it on demand or via a nightly cron job.
+    """
+    with db.SessionLocal()() as s:
+        result = verify_chain(s)
+    return {
+        "ok": result.ok,
+        "checked": result.checked,
+        "first_bad_id": result.first_bad_id,
+        "reason": result.reason,
+    }
+
+
+# ---------------------------------------------------------------------------
+# SP15: SQLCipher key rotation
+#
+# Re-encrypts the DB in place with a fresh key, then updates the
+# Keychain so subsequent connections open with the new key. This is
+# a 1-time operation per rotation; for routine read/write the rest
+# of the API is unchanged.
+#
+# Concurrency: the rotation holds a module-level lock so two
+# concurrent requests can't race and end up with mismatched Keychain
+# + DB. The lock is a simple threading.Lock; a process restart
+# resets it (intentional — the operator's next start-up opens with
+# whatever key is in the Keychain).
+# ---------------------------------------------------------------------------
+from cyclone import db_crypto as _db_crypto
+from cyclone import secrets as _secrets
+
+_db_rotate_lock = threading.Lock()
+
+
+@router.post("/api/admin/db/rotate-key")
+def rotate_db_key_endpoint(body: dict | None = None) -> Any:
+    """Generate a fresh DB key, re-encrypt the DB, update the Keychain.
+
+    Request body (optional):
+        actor: who initiated the rotation. Defaults to "operator".
+        reason: human-readable reason. Written to the audit log.
+
+    Returns:
+        ``{ok, old_fingerprint, new_fingerprint, rotated_at, table_count}``
+        on success. On failure (DB not encrypted, rekey failed,
+        Keychain update failed) returns the same shape with
+        ``ok=false`` and a ``reason``. HTTP 503 is returned if the
+        rekey fails or encryption is not enabled.
+
+    The Keychain write happens *after* the rekey succeeds. If the
+    Keychain write fails, the DB has the new key but the Keychain
+    still has the old one — the endpoint returns 503 with a
+    "keychain update failed" reason and the operator must restore
+    the old key manually (``cyclone db restore-key <old_key>``) to
+    avoid being locked out.
+    """
+    body = body or {}
+    actor = body.get("actor") or "operator"
+    reason = body.get("reason") or ""
+
+    if not _db_crypto.is_encryption_enabled():
+        raise HTTPException(
+            status_code=400,
+            detail="encryption not enabled (sqlcipher3 missing or no Keychain key)",
+        )
+
+    # Acquire the lock; non-blocking so a stuck rotation doesn't
+    # silently hold up other requests.
+    if not _db_rotate_lock.acquire(blocking=False):
+        raise HTTPException(
+            status_code=409,
+            detail="another key rotation is in progress",
+        )
+    try:
+        url = db._resolve_url()
+        old_key = _db_crypto.get_db_key()
+        if not old_key:
+            raise HTTPException(
+                status_code=400,
+                detail="no DB key in Keychain; cannot rotate",
+            )
+
+        new_key = _db_crypto.generate_db_key()
+        result = _db_crypto.rotate_db_key(
+            url=url, old_key=old_key, new_key=new_key,
+        )
+        if not result.ok:
+            # Rekey failed. The DB still has the old key. The
+            # Keychain is unchanged. Caller should NOT retry with
+            # the same new key (it's lost); generate a fresh one.
+            log.error("SQLCipher rotate failed: %s", result.reason)
+            raise HTTPException(
+                status_code=503,
+                detail={
+                    "ok": False,
+                    "old_fingerprint": result.old_fingerprint,
+                    "new_fingerprint": result.new_fingerprint,
+                    "rotated_at": result.rotated_at,
+                    "reason": result.reason,
+                },
+            )
+
+        # Rekey succeeded. Now update the Keychain. If this fails
+        # the DB is locked behind the new key — operator must
+        # restore the old key manually.
+        if not _secrets.set_secret(_db_crypto.KEYCHAIN_ACCOUNT, new_key):
+            log.error("Keychain update failed after successful rekey!")
+            raise HTTPException(
+                status_code=503,
+                detail={
+                    "ok": False,
+                    "old_fingerprint": result.old_fingerprint,
+                    "new_fingerprint": result.new_fingerprint,
+                    "rotated_at": result.rotated_at,
+                    "reason": (
+                        "rekey succeeded but Keychain update failed — "
+                        "the DB is now encrypted with the new key but "
+                        "the Keychain still has the old one. "
+                        "Restore the old key to the Keychain to recover."
+                    ),
+                },
+            )
+
+        # Store the old key in the "previous" account for a grace
+        # period so the operator can roll back if they discover the
+        # new key is broken (e.g. the Keychain entry got truncated).
+        _secrets.set_secret(_db_crypto.KEYCHAIN_ACCOUNT_PREVIOUS, old_key)
+
+        # Rebuild the engine so subsequent connections use the new
+        # key. dispose_engine() closes every pooled connection that
+        # was using the old key; init_db() opens new ones with the
+        # new key from the (now-updated) Keychain.
+        db.reinit_engine()
+
+        # Audit log the rotation. We do this after the engine is
+        # rebuilt so the audit event is written with the new key —
+        # proving that the new key works for new writes.
+        try:
+            from cyclone.audit_log import append_event, AuditEvent
+            with db.SessionLocal()() as s:
+                append_event(s, AuditEvent(
+                    event_type="db.key_rotated",
+                    entity_type="database",
+                    entity_id="cyclone.db",
+                    actor=actor,
+                    payload={
+                        "old_fingerprint": result.old_fingerprint,
+                        "new_fingerprint": result.new_fingerprint,
+                        "table_count": result.table_count,
+                        "reason": reason,
+                    },
+                ))
+                s.commit()
+        except Exception as exc:  # noqa: BLE001
+            # Audit append is best-effort; rotation already succeeded.
+            log.warning("could not write audit event for rotation: %s", exc)
+
+        return {
+            "ok": True,
+            "old_fingerprint": result.old_fingerprint,
+            "new_fingerprint": result.new_fingerprint,
+            "rotated_at": result.rotated_at,
+            "table_count": result.table_count,
+        }
+    finally:
+        _db_rotate_lock.release()
+
+
+# ---------------------------------------------------------------------------
+# SP17: encrypted DB backups (admin)
+#
+# The actual encryption + lifecycle lives in :mod:`cyclone.backup` and
+# :mod:`cyclone.backup_service`. The scheduler (separate from the
+# MFT scheduler) lives in :mod:`cyclone.backup_scheduler`. These
+# endpoints expose the operator's manual controls plus a tick for
+# "take a backup right now."
+#
+# Restore is intentionally two-step: an idle browser tab can't nuke
+# the live DB. The first call returns a ``restore_token`` (a one-shot
+# 64-char hex) and a preview of the backup's fingerprint + table
+# count plus the live DB's. The second call with the token performs
+# the actual swap.
+# ---------------------------------------------------------------------------
+from cyclone import backup_service as _backup_svc_mod
+from cyclone import backup_scheduler as _backup_sched_mod
+
+
+def _backup_or_503():
+    try:
+        return _backup_svc_mod.get_backup_service()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc))
+
+
+@router.post("/api/admin/backup/create")
+def backup_create() -> Any:
+    """Take an encrypted backup right now. Returns the new backup metadata."""
+    from cyclone import audit_log as _audit
+    svc = _backup_or_503()
+    try:
+        result = svc.create_now()
+    except Exception as exc:  # noqa: BLE001
+        # Surface a 503 with the reason so the operator sees what
+        # went wrong without grepping server logs.
+        raise HTTPException(
+            status_code=503,
+            detail=f"backup failed: {type(exc).__name__}: {exc}",
+        )
+    # Audit the create. Best-effort; failure here doesn't roll back
+    # the backup (already on disk).
+    try:
+        with db.SessionLocal()() as s:
+            _audit.append_event(s, _audit.AuditEvent(
+                event_type="db.backup_created",
+                entity_type="database",
+                entity_id="cyclone.db",
+                actor="operator",
+                payload={
+                    "backup_id": result.backup.id,
+                    "db_fingerprint": result.backup.db_fingerprint,
+                    "table_count": result.backup.table_count,
+                    "triggered_by": "api",
+                },
+            ))
+            s.commit()
+    except Exception as exc:  # noqa: BLE001
+        log.warning("could not write backup_created audit event: %s", exc)
+
+    return {
+        "ok": True,
+        "backup": {
+            "id": result.backup.id,
+            "filename": result.backup.filename,
+            "size_bytes": result.backup.size_bytes,
+            "db_fingerprint": result.backup.db_fingerprint,
+            "table_count": result.backup.table_count,
+            "created_at": result.backup.created_at.isoformat(),
+            "key_fingerprint": result.backup.key_fingerprint,
+        },
+        "sidecar": {
+            "format_version": result.sidecar.format_version,
+            "kdf": result.sidecar.kdf,
+            "kdf_iterations": result.sidecar.kdf_iterations,
+            "cipher": result.sidecar.cipher,
+        },
+    }
+
+
+@router.get("/api/admin/backup/list")
+def backup_list(
+    limit: int = Query(default=100, ge=1, le=1000),
+    status: str | None = Query(default=None),
+) -> Any:
+    """List ``db_backups`` rows, newest first. Filters by status."""
+    svc = _backup_or_503()
+    rows = svc.list_backups(limit=limit, status=status)
+    return {
+        "count": len(rows),
+        "files": [
+            {
+                "id": r.id,
+                "filename": r.filename,
+                "backup_dir": r.backup_dir,
+                "size_bytes": r.size_bytes,
+                "db_fingerprint": r.db_fingerprint,
+                "table_count": r.table_count,
+                "created_at": r.created_at.isoformat() if r.created_at else None,
+                "completed_at": r.completed_at.isoformat() if r.completed_at else None,
+                "status": r.status,
+                "error_message": r.error_message,
+                "key_fingerprint": r.key_fingerprint,
+            }
+            for r in rows
+        ],
+    }
+
+
+@router.get("/api/admin/backup/status")
+def backup_status() -> Any:
+    """Snapshot of the backup subsystem (counts, disk usage, last run)."""
+    svc = _backup_or_503()
+    snap = svc.status()
+    # Also include the BackupScheduler's snapshot if configured.
+    try:
+        sched = _backup_sched_mod.get_backup_scheduler()
+        snap["scheduler"] = sched.status().as_dict()
+    except RuntimeError:
+        snap["scheduler"] = None
+    return snap
+
+
+@router.post("/api/admin/backup/{backup_id}/verify")
+def backup_verify(backup_id: int) -> Any:
+    """Decrypt + checksum-verify a backup against its sidecar."""
+    svc = _backup_or_503()
+    try:
+        v = svc.verify(backup_id)
+    except _backup_svc_mod.BackupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    return {
+        "backup_id": v.backup_id,
+        "filename": v.filename,
+        "ok": v.ok,
+        "expected_fingerprint": v.expected_fingerprint,
+        "actual_fingerprint": v.actual_fingerprint,
+        "table_count": v.table_count,
+        "reason": v.reason,
+    }
+
+
+@router.post("/api/admin/backup/{backup_id}/restore/initiate")
+def backup_restore_initiate(backup_id: int) -> Any:
+    """First step of the two-step restore. Returns a ``restore_token``."""
+    svc = _backup_or_503()
+    try:
+        init = svc.restore_initiate(backup_id)
+    except _backup_svc_mod.BackupError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return {
+        "backup_id": init.backup_id,
+        "filename": init.filename,
+        "size_bytes": init.size_bytes,
+        "restore_token": init.restore_token,
+        "expires_at": init.expires_at.isoformat(),
+        "preview": {
+            "backup_db_fingerprint": init.db_fingerprint,
+            "backup_table_count": init.table_count,
+            "current_db_fingerprint": init.current_db_fingerprint,
+            "current_table_count": init.current_table_count,
+        },
+        "warning": (
+            "Confirming will dispose the live engine and replace the DB "
+            "file with the backup. In-flight requests will error. "
+            "Re-issue the call with the restore_token within 5 minutes."
+        ),
+    }
+
+
+@router.post("/api/admin/backup/{backup_id}/restore/confirm")
+def backup_restore_confirm(
+    backup_id: int,
+    body: dict | None = None,
+) -> Any:
+    """Second step of the two-step restore. Performs the swap."""
+    body = body or {}
+    token = body.get("restore_token")
+    if not token or not isinstance(token, str):
+        raise HTTPException(
+            status_code=400,
+            detail="missing or invalid restore_token in request body",
+        )
+    actor = body.get("actor") or "operator"
+
+    svc = _backup_or_503()
+    try:
+        result = svc.restore_confirm(backup_id, token, actor=actor)
+    except _backup_svc_mod.BackupError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    # Audit the restore. Best-effort.
+    try:
+        from cyclone import audit_log as _audit
+        with db.SessionLocal()() as s:
+            _audit.append_event(s, _audit.AuditEvent(
+                event_type="db.backup_restored",
+                entity_type="database",
+                entity_id="cyclone.db",
+                actor=actor,
+                payload={
+                    "backup_id": result.backup_id,
+                    "filename": result.filename,
+                    "restored_from_fingerprint": result.restored_from_fingerprint,
+                    "new_db_fingerprint": result.new_db_fingerprint,
+                    "restored_at": result.restored_at.isoformat(),
+                },
+            ))
+            s.commit()
+    except Exception as exc:  # noqa: BLE001
+        log.warning("could not write backup_restored audit event: %s", exc)
+
+    return {
+        "ok": True,
+        "backup_id": result.backup_id,
+        "filename": result.filename,
+        "restored_from_fingerprint": result.restored_from_fingerprint,
+        "restored_at": result.restored_at.isoformat(),
+        "new_db_fingerprint": result.new_db_fingerprint,
+    }
+
+
+@router.post("/api/admin/backup/prune")
+def backup_prune() -> Any:
+    """Apply the retention policy now. Returns the deleted paths."""
+    from cyclone import audit_log as _audit
+    svc = _backup_or_503()
+    deleted = svc.prune()
+    actor = "operator"
+    if deleted:
+        try:
+            with db.SessionLocal()() as s:
+                _audit.append_event(s, _audit.AuditEvent(
+                    event_type="db.backup_pruned",
+                    entity_type="database",
+                    entity_id="cyclone.db",
+                    actor=actor,
+                    payload={"deleted_paths": deleted},
+                ))
+                s.commit()
+        except Exception as exc:  # noqa: BLE001
+            log.warning("could not write backup_pruned audit event: %s", exc)
+    return {"ok": True, "deleted_count": len(deleted), "deleted_paths": deleted}
+
+
+# ---------------------------------------------------------------------------
+# SP17: backup scheduler (admin)
+# ---------------------------------------------------------------------------
+
+
+@router.post("/api/admin/backup/scheduler/start")
+async def backup_scheduler_start() -> Any:
+    """Begin the backup scheduler loop."""
+    try:
+        sched = _backup_sched_mod.get_backup_scheduler()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc))
+    await sched.start()
+    return {"status": sched.status().as_dict()}
+
+
+@router.post("/api/admin/backup/scheduler/stop")
+async def backup_scheduler_stop() -> Any:
+    """Stop the backup scheduler loop."""
+    try:
+        sched = _backup_sched_mod.get_backup_scheduler()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc))
+    await sched.stop()
+    return {"status": sched.status().as_dict()}
+
+
+@router.post("/api/admin/backup/scheduler/tick")
+async def backup_scheduler_tick() -> Any:
+    """Run one backup tick now (create + prune + audit)."""
+    try:
+        sched = _backup_sched_mod.get_backup_scheduler()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc))
+    result = await sched.tick()
+    return {"ok": result.ok, "tick": result.as_dict()}
+
+
+# ---------------------------------------------------------------------------
+# SP16: live MFT polling scheduler (admin)
+#
+# The scheduler lives in :mod:`cyclone.scheduler` and is configured by
+# the lifespan handler. The endpoints below expose start / stop /
+# one-shot tick / status / history so an operator (or a cron job)
+# can drive the scheduler without touching the DB.
+#
+# Note: the scheduler is OFF by default. Auto-start is opt-in via
+# ``CYCLONE_SCHEDULER_AUTOSTART=true`` at launch. These endpoints
+# are the operator's manual controls.
+# ---------------------------------------------------------------------------
+from cyclone import scheduler as _scheduler_mod
+
+
+def _scheduler_or_503():
+    """Return the configured scheduler or raise 503."""
+    try:
+        return _scheduler_mod.get_scheduler()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc))
+
+
+@router.post("/api/admin/scheduler/start")
+async def scheduler_start() -> Any:
+    """Begin polling the MFT inbound path every poll_interval_seconds."""
+    sched = _scheduler_or_503()
+    await sched.start()
+    return {"status": sched.status().as_dict()}
+
+
+@router.post("/api/admin/scheduler/stop")
+async def scheduler_stop() -> Any:
+    """Stop polling. Waits up to 30s for the current tick to finish."""
+    sched = _scheduler_or_503()
+    await sched.stop()
+    return {"status": sched.status().as_dict()}
+
+
+@router.post("/api/admin/scheduler/tick")
+async def scheduler_tick() -> Any:
+    """Run a single poll cycle synchronously and return the result.
+
+    Useful for: forcing a poll without waiting for the next interval;
+    verifying SFTP connectivity; running a one-shot import from the
+    CLI (``curl -X POST .../api/admin/scheduler/tick``).
+    """
+    sched = _scheduler_or_503()
+    result = await sched.tick()
+    return {"ok": True, "tick": result.as_dict()}
+
+
+@router.post("/api/admin/scheduler/pull-inbound")
+async def scheduler_pull_inbound(
+    date: str = Query(
+        ..., pattern=r"^\d{8}$",
+        description="Date filter as YYYYMMDD; only filenames whose 8-digit "
+                    "timestamp (the 9th positional group in the inbound "
+                    "filename) matches are downloaded and processed.",
+    ),
+    file_types: str | None = Query(
+        default=None,
+        description="Optional comma-separated whitelist of file_types "
+                    "(999, TA1, 277, 277CA, 835). Defaults to 999+TA1.",
+    ),
+    limit: int = Query(default=2000, ge=1, le=10000),
+) -> Any:
+    """Targeted pull: list, filter to a date, download, and process.
+
+    Bypasses the alphabetical full-listing pass. Workflow:
+      1. ``SftpClient.list_inbound_names()`` — sub-second metadata-only
+         listing of the inbound MFT dir (skips ``*_warn.txt``).
+      2. Client-side filter: keep files whose 8-digit timestamp
+         substring equals ``date`` and whose ``file_type`` is in the
+         allowlist.
+      3. ``SftpClient.download_inbound(f)`` for each — fetches bytes
+         into the local cache.
+      4. ``Scheduler.process_inbound_files(files)`` — runs the same
+         per-file pipeline as a regular tick (already-processed files
+         are deduped via ``processed_inbound_files``).
+
+    Use this for the daily "process today's 999s" workflow without
+    paying the cost of downloading the full inbound set.
+
+    Returns ``{"ok": True, "summary": {...}}`` with
+    ``listed / matched / downloaded / processed / skipped / errored``
+    counters and the date / file_type filters applied.
+    """
+
+    from cyclone.clearhouse import SftpClient
+    from cyclone.edi.filenames import (
+        ALLOWED_FILE_TYPES,
+        parse_inbound_filename,
+    )
+    from cyclone.providers import SftpBlock
+
+    sched = _scheduler_or_503()
+    block: SftpBlock = sched._sftp_block  # noqa: SLF001 — internal but stable
+    client = SftpClient(block)
+
+    if file_types:
+        wanted = {t.strip().upper() for t in file_types.split(",") if t.strip()}
+        unknown = wanted - ALLOWED_FILE_TYPES
+        if unknown:
+            raise HTTPException(
+                status_code=400,
+                detail=f"file_types {sorted(unknown)!r} not in "
+                       f"{sorted(ALLOWED_FILE_TYPES)}",
+            )
+    else:
+        wanted = {"999", "TA1"}  # daily default — what the operator needs
+
+    started = time.monotonic()
+    try:
+        # Single SFTP listdir — fast, no download.
+        all_files = await asyncio.to_thread(client.list_inbound_names)
+    except Exception as exc:
+        log.exception("SFTP list_inbound_names failed")
+        raise HTTPException(
+            status_code=502,
+            detail=f"SFTP list failed: {type(exc).__name__}: {exc}",
+        ) from exc
+
+    listed = len(all_files)
+    matched: list[InboundFile] = []
+    for f in all_files:
+        if f.name.find(date) == -1:
+            continue
+        try:
+            parsed = parse_inbound_filename(f.name)
+        except ValueError:
+            continue
+        if parsed.file_type not in wanted:
+            continue
+        matched.append(f)
+        if len(matched) >= limit:
+            break
+
+    # Download in parallel-ish via to_thread (SftpClient serializes per
+    # connection; the overhead is dominated by the SFTP round trip).
+    downloaded = 0
+    download_errors: list[str] = []
+    for f in matched:
+        try:
+            await asyncio.to_thread(client.download_inbound, f)
+            downloaded += 1
+        except Exception as exc:  # noqa: BLE001
+            log.warning("Failed to download %s: %s", f.name, exc)
+            download_errors.append(f"{f.name}: {type(exc).__name__}: {exc}")
+
+    # Hand off to the scheduler pipeline (idempotent; dedupes via
+    # processed_inbound_files).
+    tick = await sched.process_inbound_files(matched)
+    duration = round(time.monotonic() - started, 3)
+    return {
+        "ok": True,
+        "summary": {
+            "date": date,
+            "file_types": sorted(wanted),
+            "limit": limit,
+            "listed": listed,
+            "matched": len(matched),
+            "downloaded": downloaded,
+            "download_errors": download_errors,
+            "processed": tick.files_processed,
+            "skipped": tick.files_skipped,
+            "errored": tick.files_errored,
+            "duration_s": duration,
+        },
+        "tick": tick.as_dict(),
+    }
+
+
+@router.get("/api/admin/scheduler/status")
+def scheduler_status() -> Any:
+    """Return the scheduler's runtime snapshot (running, counters, last tick)."""
+    sched = _scheduler_or_503()
+    return sched.status().as_dict()
+
+
+@router.get("/api/admin/scheduler/processed-files")
+def scheduler_processed_files(
+    limit: int = Query(default=100, ge=1, le=1000),
+    status: str | None = Query(default=None),
+) -> Any:
+    """List rows from ``processed_inbound_files``, newest first.
+
+    The operator's "what did the scheduler do?" view. Filters by
+    ``status`` (``ok`` / ``error`` / ``skipped`` / ``pending``).
+    Returns ``{"count": N, "files": [...]}`` where ``files[i]``
+    matches the ORM row as a JSON dict.
+    """
+    from cyclone.db import ProcessedInboundFile
+    from cyclone.scheduler import STATUS_OK, STATUS_ERROR, STATUS_SKIPPED, STATUS_PENDING
+
+    valid_statuses = {STATUS_OK, STATUS_ERROR, STATUS_SKIPPED, STATUS_PENDING}
+    if status is not None and status not in valid_statuses:
+        raise HTTPException(
+            status_code=400,
+            detail=f"status must be one of {sorted(valid_statuses)}",
+        )
+
+    with db.SessionLocal()() as s:
+        q = s.query(db.ProcessedInboundFile)
+        if status is not None:
+            q = q.filter(db.ProcessedInboundFile.status == status)
+        rows = q.order_by(db.ProcessedInboundFile.id.desc()).limit(limit).all()
+        return {
+            "count": len(rows),
+            "files": [
+                {
+                    "id": r.id,
+                    "sftp_block_name": r.sftp_block_name,
+                    "name": r.name,
+                    "size": r.size,
+                    "modified_at": r.modified_at.isoformat() if r.modified_at else None,
+                    "file_type": r.file_type,
+                    "processed_at": r.processed_at.isoformat() if r.processed_at else None,
+                    "parser_used": r.parser_used,
+                    "claim_count": r.claim_count,
+                    "status": r.status,
+                    "error_message": r.error_message,
+                }
+                for r in rows
+            ],
+        }
+
+
+@router.post("/api/admin/reload-config")
+def reload_config():
+    """Re-read ``config/payers.yaml`` and revalidate. Returns counts."""
+    from cyclone import payers as payer_loader
+    try:
+        configs = payer_loader.load_payer_configs()
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    return {"ok": True, "loaded": len(configs), "errors": []}

backend/src/cyclone/api_routers/batches.py

@@ -0,0 +1,515 @@
+"""``/api/batches*`` — read views + ZIP export over the parsed-batch population.
+
+Three endpoints, all gated by ``matrix_gate``:
+
+- ``POST /api/batches/{batch_id}/export-837`` — download a ZIP of
+  regenerated X12 837 files for the requested claim ids. Per-claim
+  payer config + clearhouse identity drive the submitter/receiver
+  blocks; per-claim millisecond offset on the filename keeps every
+  file in the bundle unique (HCPF requires this). Read-only — does
+  NOT mutate Claim state (compare with
+  ``/api/inbox/rejected/resubmit?download=true`` which DOES flip
+  ``REJECTED → SUBMITTED``).
+- ``GET  /api/batches``                       — summary list,
+  newest-first, capped at ``limit``. Each row includes ``claimIds``
+  (837P only, so the Upload page can render a one-click Re-export
+  button per row without a round-trip to ``/api/batches/{id}``).
+  SP30: also returns billing-outcome fields
+  (``acceptedCount`` / ``rejectedCount`` / ``pendingCount`` /
+  ``billedTotal`` / ``topRejectionReason`` / ``hasProblem``) so the
+  Dashboard "Recent batches" widget can render one row per batch
+  without an N+1 fetch.
+- ``GET  /api/batches/{batch_id}``            — full batch record
+  (parsed envelope + claims). 404 when unknown.
+
+Three single-router helpers stay in this file (per spec D4):
+
+- :func:`_batch_summary_claim_count`       — claim count (837P or 835).
+- :func:`_batch_summary_claim_ids`         — per-claim ids (837P only).
+- :func:`_batch_summary_billing_outcomes`  — per-batch GROUP BY state
+  aggregate plus the most-recent rejection reason.
+
+Inline imports inside handlers (preserved verbatim per spec D5):
+``zipfile``, ``datetime``, ``ZoneInfo``, ``build_outbound_filename``,
+``PayerConfigORM``, ``func`` (sqlalchemy).
+
+SP36 Task 14: this block moved here from ``api.py:1280`` (the 3
+``/api/batches*`` routes + 3 single-router helpers + the SP30
+state-bucket tuples and the ``# 277CA STC category`` note).
+"""
+from __future__ import annotations
+
+import io
+import json
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
+from fastapi.responses import StreamingResponse
+
+from cyclone import db
+from cyclone.api_helpers import (
+    ndjson_stream_list as _ndjson_stream_list,
+    wants_ndjson as _wants_ndjson,
+)
+from cyclone.auth.deps import matrix_gate
+from cyclone.db import Batch, Claim, ClaimState
+from cyclone.parsers.models import ClaimOutput
+from cyclone.parsers.serialize_837 import SerializeError as SerializeError837
+from cyclone.parsers.serialize_837 import serialize_837_for_resubmit
+from cyclone.store import BatchRecord, store
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.post("/api/batches/{batch_id}/export-837")
+def export_batch_837(request: Request, batch_id: str, body: dict):
+    """Download a ZIP of regenerated X12 837 files for the requested claim_ids.
+
+    Body shape: ``{"claim_ids": [str, ...]}``.
+
+    Each successfully serialized claim becomes an entry in the ZIP named
+    per the HCPF X12 File Naming Standards:
+    ``tp{tpid}-837P-{yyyymmddhhmmssSSS}-1of1.x12`` (with a per-claim
+    millisecond offset so every file in the bundle has a unique name).
+    The ``serialize_837_for_resubmit`` serializer is used so every file
+    gets a unique interchange / group control number — back-to-back
+    exports of the same set must produce different envelopes (required
+    by X12).
+
+    The submitter block (Loop 1000A — NM1*41 + PER) is populated from
+    the clearhouse singleton (dzinesco's identity in the seeded config)
+    and the receiver block (NM1*40) is populated from the per-payer
+    config. Without this wiring, the serializer falls back to
+    ``CYCLONE`` / ``RECEIVER`` placeholders and HCPF rejects the file.
+
+    No DB state is mutated by this endpoint — it is read-only. Compare
+    with ``/api/inbox/rejected/resubmit?download=true`` which ALSO flips
+    ``ClaimState.REJECTED → SUBMITTED``; the two endpoints are
+    intentionally separate.
+
+    Responses:
+      200 — ``application/zip`` with the .x12 entries. Per-claim failures
+            are surfaced via the ``X-Cyclone-Serialize-Errors`` header
+            (JSON-encoded array of ``{claim_id, reason}``).
+      400 — ``claim_ids`` missing or empty.
+      404 — ``batch_id`` unknown.
+      422 — every claim failed to serialize; body is JSON listing all
+            failures (``{"detail": {"serialize_errors": [...]}}``).
+    """
+    import zipfile
+    from datetime import datetime
+    from zoneinfo import ZoneInfo
+
+    from cyclone.edi.filenames import build_outbound_filename
+
+    ids = body.get("claim_ids") or []
+    if not ids:
+        raise HTTPException(400, "claim_ids required")
+
+    with db.SessionLocal()() as s:
+        batch = s.get(Batch, batch_id)
+        if batch is None:
+            raise HTTPException(404, f"unknown batch: {batch_id}")
+
+        serialize_errors: list[dict] = []
+        ordered_rows: list[tuple[str, "Claim"]] = []
+        for cid in ids:
+            c = s.get(Claim, cid)
+            if c is None:
+                serialize_errors.append({"claim_id": cid, "reason": "unknown claim_id"})
+                continue
+            ordered_rows.append((cid, c))
+
+    # Pull clearhouse identity (submitter). If unseeded, the serializer
+    # falls back to placeholder defaults — degraded but not a hard error.
+    ch = store.get_clearhouse()
+    submitter_kwargs: dict = {}
+    if ch is not None:
+        submitter_kwargs = {
+            "sender_id": ch.tpid,
+            "submitter_name": ch.submitter_name,
+            "submitter_contact_name": ch.submitter_contact_name,
+            "submitter_contact_email": ch.submitter_contact_email,
+        }
+        # Submitter phone is not in the clearhouse config today, but if
+        # it ever is, wire it here. Email is the canonical contact
+        # channel for HCPF submissions per the SP9 spec.
+        if getattr(ch, "submitter_contact_phone", None):
+            submitter_kwargs["submitter_contact_phone"] = ch.submitter_contact_phone
+
+    # Resolve per-claim payer config so each file's receiver (NM1*40)
+    # and SBR09 are correct. Cache so we don't re-query the same payer.
+    from cyclone.db import PayerConfigORM as _PayerConfigORM
+    _payer_cache: dict[str, dict | None] = {}
+
+    def _resolve_payer_cfg(claim_obj: ClaimOutput) -> dict | None:
+        pid = (claim_obj.payer.id or "").strip() if claim_obj.payer else ""
+        pname = (claim_obj.payer.name or "").strip() if claim_obj.payer else ""
+        cache_key = pid or pname
+        if cache_key in _payer_cache:
+            return _payer_cache[cache_key]
+        cfg: dict | None = None
+        with db.SessionLocal()() as ss:
+            # 1. Exact match on (payer_id, "837P")
+            if pid:
+                row = ss.get(_PayerConfigORM, (pid, "837P"))
+                if row is not None:
+                    cfg = dict(row.config_json)
+            # 2. Fallback: any row whose payer_id matches the parsed payer.name
+            #    (HCPF files emit "SKCO0" in NM109 but the canonical
+            #    payer_id in the DB is "CO_TXIX" — name-matching is the
+            #    pragmatic lookup for that case).
+            if cfg is None and pname:
+                row = (
+                    ss.query(_PayerConfigORM)
+                    .filter(_PayerConfigORM.transaction_type == "837P")
+                    .all()
+                )
+                for r in row:
+                    cj = dict(r.config_json)
+                    if cj.get("submitter_name") and pname.lower() in str(cj).lower():
+                        cfg = cj
+                        break
+                    if (r.payer_id or "").upper() == pname.upper():
+                        cfg = cj
+                        break
+            # 3. Last resort: first 837P row in the table.
+            if cfg is None:
+                row = (
+                    ss.query(_PayerConfigORM)
+                    .filter(_PayerConfigORM.transaction_type == "837P")
+                    .first()
+                )
+                if row is not None:
+                    cfg = dict(row.config_json)
+        _payer_cache[cache_key] = cfg
+        return cfg
+
+    # Build per-claim kwargs (receiver + SBR09) lazily. Receiver
+    # defaults to the parsed payer name/ID if no config row matches.
+    def _serialize_kwargs(claim_obj: ClaimOutput) -> dict:
+        payer_cfg = _resolve_payer_cfg(claim_obj) or {}
+        receiver_id = (
+            payer_cfg.get("receiver_id")
+            or (claim_obj.payer.id if claim_obj.payer else None)
+            or "RECEIVER"
+        )
+        receiver_name = (
+            payer_cfg.get("receiver_name")
+            or (claim_obj.payer.name if claim_obj.payer else None)
+            or receiver_id
+        )
+        sbr09 = payer_cfg.get("sbr09_default") or "MC"
+        return {
+            "receiver_id": receiver_id,
+            "receiver_name": receiver_name,
+            "claim_filing_indicator_code": sbr09,
+        }
+
+    # Base MT timestamp for HCPF filenames. We add a per-claim
+    # millisecond offset so each file in the ZIP has a unique 17-digit
+    # ts (HCPF requires that; the spec also enforces "1of1" for the
+    # sequence element).
+    base_ts = datetime.now(ZoneInfo("America/Denver"))
+
+    def _per_claim_filename(idx: int, cid: str) -> str:
+        if ch is None:
+            # No clearhouse — fall back to a per-claim friendly name.
+            return f"claim-{cid}.x12"
+        # Millisecond offset, with second/minute rollover.
+        offset_ms = (idx - 1) * 1  # 1 ms per claim is enough within an export
+        ts_mt = base_ts.fromtimestamp(
+            base_ts.timestamp() + offset_ms / 1000.0, tz=ZoneInfo("America/Denver")
+        )
+        return build_outbound_filename(ch.tpid, "837P", now_mt=ts_mt)
+
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, mode="w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for idx, (cid, c) in enumerate(ordered_rows, start=1):
+            if not c.raw_json:
+                serialize_errors.append({"claim_id": cid, "reason": "no raw_json"})
+                continue
+            try:
+                claim_obj = ClaimOutput.model_validate(c.raw_json)
+            except Exception as exc:
+                serialize_errors.append(
+                    {"claim_id": cid, "reason": f"raw_json invalid: {exc}"}
+                )
+                continue
+            try:
+                kwargs = {**submitter_kwargs, **_serialize_kwargs(claim_obj)}
+                text = serialize_837_for_resubmit(
+                    claim_obj, interchange_index=idx, **kwargs
+                )
+            except SerializeError837 as exc:
+                serialize_errors.append({"claim_id": cid, "reason": str(exc)})
+                continue
+            zf.writestr(_per_claim_filename(idx, cid), text)
+
+    success_count = len(ids) - len(serialize_errors)
+    if serialize_errors and success_count == 0:
+        # Every claim failed — surface the failure list in the body so the
+        # UI can render a useful error toast (the response is not a ZIP).
+        raise HTTPException(
+            422,
+            detail={"serialize_errors": serialize_errors},
+        )
+
+    buf.seek(0)
+    headers = {
+        "Content-Disposition": (
+            f'attachment; filename="batch-{batch_id}-{success_count}-claims.zip"'
+        ),
+    }
+    if serialize_errors:
+        headers["X-Cyclone-Serialize-Errors"] = json.dumps(serialize_errors)
+    return Response(
+        content=buf.getvalue(),
+        media_type="application/zip",
+        headers=headers,
+    )
+
+
+def _batch_summary_claim_count(rec: BatchRecord) -> int:
+    """Return the number of claims on a batch, handling both 837P and 835."""
+    if rec.kind == "837p":
+        return len(rec.result.claims)  # type: ignore[attr-defined]
+    if rec.kind == "835":
+        return len(rec.result.claims)  # type: ignore[attr-defined]
+    return 0
+
+
+def _batch_summary_claim_ids(rec: BatchRecord) -> list[str]:
+    """Return per-claim ids for an 837P batch, or ``[]`` otherwise.
+
+    The Upload page's History tab renders a one-click Re-export ZIP
+    button per row; that button calls
+    ``POST /api/batches/{id}/export-837`` with the row's claim ids.
+    Carrying them in the list response avoids an extra round-trip
+    to ``/api/batches/{id}`` for every row. 835 has no re-export
+    endpoint, so the list is empty for those — the UI uses the
+    empty list as the signal to hide the button.
+    """
+    if rec.kind != "837p":
+        return []
+    return [
+        c.claim_id
+        for c in rec.result.claims  # type: ignore[attr-defined]
+        if getattr(c, "claim_id", None)
+    ]
+
+
+# SP30: state buckets the Dashboard widget (and any future "how the
+# last batch billed" surface) reads at a glance. Keep these in sync
+# with ClaimState — adding a new state here is a deliberate decision
+# the operator needs to see, not a coincidence.
+_BATCH_SUMMARY_ACCEPTED_STATES: tuple[ClaimState, ...] = (
+    ClaimState.PAID,
+    ClaimState.RECEIVED,
+    ClaimState.RECONCILED,
+    ClaimState.PARTIAL,
+)
+_BATCH_SUMMARY_REJECTED_STATES: tuple[ClaimState, ...] = (
+    ClaimState.REJECTED,
+    ClaimState.DENIED,
+    ClaimState.REVERSED,
+)
+_BATCH_SUMMARY_PENDING_STATES: tuple[ClaimState, ...] = (
+    ClaimState.SUBMITTED,
+)
+# 277CA STC category A4/A6/A7 — payer-side rejections that may not
+# yet have flipped Claim.state (the operator hasn't acknowledged).
+# The Dashboard widget treats these as problems too, mirroring the
+# Inbox `rejected + payer_rejected` aggregation.
+_BATCH_SUMMARY_PAYER_REJECT_CODES: tuple[str, ...] = ("A4", "A6", "A7")
+
+
+def _batch_summary_billing_outcomes(
+    records: list[BatchRecord],
+) -> dict[str, dict]:
+    """Compute per-batch billing outcome for the Dashboard widget.
+
+    Returns ``{batch_id: {accepted, rejected, pending, billed,
+    top_rejection_reason, has_problem}}`` for every batch in
+    ``records``. Empty input → empty dict.
+
+    Two SQL queries, both bounded by the supplied batch ids:
+
+    1. One GROUP BY ``(batch_id, state)`` aggregate that produces
+       the accepted/rejected/pending counts and the sum of
+       ``charge_amount`` (the billed total). Single pass — no N+1.
+    2. One ordered scan over the rejected + payer-rejected subset
+       to pick the most recent rejection reason (truncated to 60
+       chars). Skipped when the first query found no rejections
+       and no payer-rejects, so the happy path stays at one query.
+
+    835 batches have no Claim rows — the GROUP BY returns no
+    rows for them, so the dict entry for an 835 batch is
+    ``{accepted:0, rejected:0, pending:0, billed:0.0,
+    top_rejection_reason:None, has_problem:False}`` (filled by
+    the caller's ``.get(id, defaults)`` pattern).
+    """
+    if not records:
+        return {}
+    from sqlalchemy import func  # local import to keep top-of-file light
+
+    batch_ids = [r.id for r in records]
+    outcome: dict[str, dict] = {
+        bid: {
+            "accepted": 0,
+            "rejected": 0,
+            "pending": 0,
+            "billed": 0.0,
+            "top_rejection_reason": None,
+            "has_problem": False,
+        }
+        for bid in batch_ids
+    }
+
+    with db.SessionLocal()() as s:
+        # ---- 1. GROUP BY (batch_id, state) for counts + billed total ----
+        rows = (
+            s.query(
+                Claim.batch_id,
+                Claim.state,
+                func.count(Claim.id),
+                func.coalesce(func.sum(Claim.charge_amount), 0),
+            )
+            .filter(Claim.batch_id.in_(batch_ids))
+            .group_by(Claim.batch_id, Claim.state)
+            .all()
+        )
+        any_rejection_or_payer = False
+        for batch_id, state, count, billed in rows:
+            slot = outcome.get(batch_id)
+            if slot is None:
+                continue  # batch has no row in our pre-allocated dict
+            count = int(count or 0)
+            billed_f = float(billed or 0)
+            slot["billed"] += billed_f
+            if state in _BATCH_SUMMARY_ACCEPTED_STATES:
+                slot["accepted"] += count
+            elif state in _BATCH_SUMMARY_REJECTED_STATES:
+                slot["rejected"] += count
+                any_rejection_or_payer = True
+            elif state in _BATCH_SUMMARY_PENDING_STATES:
+                slot["pending"] += count
+            # everything else (DRAFT, etc.) is excluded from the widget.
+
+        # ---- 2. Most-recent rejection reason + payer-reject probe ----
+        # Only run when we know there IS at least one rejection OR a
+        # payer-reject claim somewhere in the batch set; otherwise
+        # the first query alone is enough.
+        if any_rejection_or_payer:
+            rej_rows = (
+                s.query(
+                    Claim.batch_id,
+                    Claim.rejection_reason,
+                    Claim.payer_rejected_status_code,
+                )
+                .filter(
+                    Claim.batch_id.in_(batch_ids),
+                    Claim.state.in_(_BATCH_SUMMARY_REJECTED_STATES)
+                    | Claim.payer_rejected_status_code.in_(
+                        _BATCH_SUMMARY_PAYER_REJECT_CODES
+                    ),
+                )
+                .order_by(Claim.rejected_at.desc().nullslast())
+                .all()
+            )
+            seen_reason: set[str] = set()
+            for batch_id, reason, payer_code in rej_rows:
+                slot = outcome.get(batch_id)
+                if slot is None:
+                    continue
+                if payer_code in _BATCH_SUMMARY_PAYER_REJECT_CODES:
+                    slot["has_problem"] = True
+                # Capture the first non-null reason for this batch
+                # (rej_rows is ordered newest-first, so the first
+                # non-null wins). Truncate to 60 chars + ellipsis.
+                if (
+                    slot["top_rejection_reason"] is None
+                    and reason
+                    and batch_id not in seen_reason
+                ):
+                    r = reason.strip()
+                    if len(r) > 60:
+                        r = r[:60] + "…"
+                    slot["top_rejection_reason"] = r
+                    seen_reason.add(batch_id)
+                if (
+                    slot["rejected"] > 0
+                    or payer_code in _BATCH_SUMMARY_PAYER_REJECT_CODES
+                ):
+                    slot["has_problem"] = True
+
+    return outcome
+
+
+@router.get("/api/batches")
+def list_batches(
+    request: Request,
+    limit: int = Query(100, ge=1, le=1000),
+) -> Any:
+    """Summary of all parsed batches, newest first.
+
+    Each item includes ``claimIds`` (837P only) so the History tab
+    on the Upload page can render a one-click re-export button per
+    row without an extra round-trip to ``/api/batches/{id}``. The
+    list is still capped at ``limit`` claims; see the full result
+    via the by-id endpoint when more is needed.
+
+    SP30: also returns billing-outcome fields
+    (``acceptedCount`` / ``rejectedCount`` / ``pendingCount`` /
+    ``billedTotal`` / ``topRejectionReason`` / ``hasProblem``) so
+    the Dashboard "Recent batches" widget can render one row per
+    batch without an N+1 fetch. See
+    :func:`_batch_summary_billing_outcomes`.
+    """
+    records = store.list(limit=limit)
+    outcomes = _batch_summary_billing_outcomes(records)
+    items = [
+        {
+            "id": r.id,
+            "kind": r.kind,
+            "inputFilename": r.input_filename,
+            "parsedAt": r.parsed_at.isoformat().replace("+00:00", "Z"),
+            "claimCount": _batch_summary_claim_count(r),
+            "claimIds": _batch_summary_claim_ids(r),
+            "acceptedCount": outcomes.get(r.id, {}).get("accepted", 0),
+            "rejectedCount": outcomes.get(r.id, {}).get("rejected", 0),
+            "pendingCount": outcomes.get(r.id, {}).get("pending", 0),
+            "billedTotal": round(outcomes.get(r.id, {}).get("billed", 0.0), 2),
+            "topRejectionReason": outcomes.get(r.id, {}).get(
+                "top_rejection_reason"
+            ),
+            "hasProblem": outcomes.get(r.id, {}).get("has_problem", False),
+        }
+        for r in records
+    ]
+    all_records = store.all()
+    total = len(all_records)
+    returned = len(items)
+    has_more = total > returned
+    if _wants_ndjson(request):
+        return StreamingResponse(
+            _ndjson_stream_list(items, total, returned, has_more),
+            media_type="application/x-ndjson",
+        )
+    return {
+        "items": items,
+        "total": total,
+        "returned": returned,
+        "has_more": has_more,
+    }
+
+
+@router.get("/api/batches/{batch_id}")
+def get_batch(batch_id: str) -> Any:
+    rec = store.get(batch_id)
+    if rec is None:
+        raise HTTPException(
+            status_code=404,
+            detail={"error": "Not found", "detail": f"Batch {batch_id} not found"},
+        )
+    return json.loads(rec.result.model_dump_json())

backend/src/cyclone/api_routers/claim_acks.py

@@ -21,16 +21,17 @@ from __future__ import annotations
 import logging
 from typing import Any, AsyncIterator, Literal
 
-from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from fastapi.responses import JSONResponse, StreamingResponse
 from pydantic import BaseModel, Field
 
 from cyclone import db
 from cyclone.api_helpers import ndjson_line, tail_events
+from cyclone.auth.deps import matrix_gate
 from cyclone.pubsub import EventBus
 from cyclone.store import store, to_ui_claim_ack
 
-router = APIRouter()
+router = APIRouter(dependencies=[Depends(matrix_gate)])
 
 log = logging.getLogger(__name__)
 
@@ -291,7 +292,7 @@ def list_ack_orphans_endpoint(
     """List acks with no resolvable Claim row of their own kind.
 
     Used by the Inbox "Ack orphans" lane for the operator's manual
-    reconciliation flow. Mirrors ``/api/inbox/remit-orphans``.
+    reconciliation flow. Filters by kind: ``999``, ``277ca``, ``ta1``.
     """
     if kind is not None:
         items = store.find_ack_orphans(kind)

backend/src/cyclone/api_routers/claims.py

@@ -0,0 +1,472 @@
+"""``/api/claims*`` — Claims list / detail / streaming / serialize / line-reconciliation.
+
+Five endpoints, all gated by ``matrix_gate``:
+
+- ``GET /api/claims``                              — paginated list
+  with filter+sort, plus an NDJSON variant when the caller sends
+  ``Accept: application/x-ndjson``. SP27: counts the full filtered
+  population, not a page-limited sample.
+- ``GET /api/claims/stream``                       — NDJSON live-tail
+  on ``claim_written``. Snapshot first (eager
+  ``store.iter_claims``), then ``tail_events`` subscribes + emits
+  heartbeats. Registered before ``/api/claims/{claim_id}`` so the
+  literal ``stream`` segment isn't captured as a claim id.
+- ``GET /api/claims/{claim_id}``                   — full drawer
+  context (SP4) with the SP28 ``ack_links`` block pre-attached.
+  404 on missing id — never 500.
+- ``GET /api/claims/{claim_id}/serialize-837``     — regenerate X12
+  837P from the stored ``raw_json`` payload. 404 unknown claim, 422
+  no-``raw_json`` / unparseable / serializer failure.
+- ``GET /api/claims/{claim_id}/line-reconciliation`` — per-line 837
+  vs 835 side-by-side with CAS adjustments and a summary block.
+
+Three single-router helpers stay in this file (per spec D4):
+
+- :func:`_compact_ack_links_for_claim` — slim form
+  ``{ack_id, ack_kind, set_accept_reject_code, …}`` for the drawer
+  Acknowledgments panel.
+- :func:`_claim_line_dict`              — project an 837 service-line
+  dict from ``Claim.raw_json`` to wire shape.
+- :func:`_svc_to_dict`                  — project an ORM
+  ``ServiceLinePayment`` to wire shape.
+
+Inline imports inside handlers (preserved verbatim per spec D5):
+``select`` (sqlalchemy), ``LineReconciliation``/``ServiceLinePayment``/
+``CasAdjustment`` (cyclone.db), ``json as _json``, ``Decimal``.
+
+SP36 Task 15: this block moved here from ``api.py:1278`` (the 5
+``/api/claims*`` routes + 3 single-router helpers).
+"""
+from __future__ import annotations
+
+import json
+from decimal import Decimal
+from typing import Any, AsyncIterator
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+
+from cyclone import db
+from cyclone.api_helpers import (
+    ndjson_line as _ndjson_line,
+    ndjson_stream_list as _ndjson_stream_list,
+    tail_events as _tail_events,
+    wants_ndjson as _wants_ndjson,
+)
+from cyclone.auth.deps import matrix_gate
+from cyclone.db import Claim
+from cyclone.parsers.models import ClaimOutput
+from cyclone.parsers.serialize_837 import SerializeError as SerializeError837
+from cyclone.parsers.serialize_837 import serialize_837
+from cyclone.pubsub import EventBus
+from cyclone.store import store
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.get("/api/claims")
+def list_claims(
+    request: Request,
+    batch_id: str | None = Query(None),
+    status: str | None = Query(None),
+    provider_npi: str | None = Query(None),
+    payer: str | None = Query(None),
+    date_from: str | None = Query(None),
+    date_to: str | None = Query(None),
+    sort: str | None = Query(None),
+    order: str = Query("desc"),
+    limit: int = Query(100, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+) -> Any:
+    common = dict(
+        batch_id=batch_id,
+        status=status,
+        provider_npi=provider_npi,
+        payer=payer,
+        date_from=date_from,
+        date_to=date_to,
+    )
+    items = list(store.iter_claims(
+        sort=sort, order=order, limit=limit, offset=offset, **common,
+    ))
+    # SP27 Task 13b: count the full population, not a 100-row sample.
+    # `iter_claims` defaults to limit=100; counting its output silently
+    # capped the reported total at 100 even when the DB held 60k rows.
+    total = store.count_claims(**common)
+    returned = len(items)
+    has_more = total > offset + returned
+    if _wants_ndjson(request):
+        return StreamingResponse(
+            _ndjson_stream_list(items, total, returned, has_more),
+            media_type="application/x-ndjson",
+        )
+    return {
+        "items": items,
+        "total": total,
+        "returned": returned,
+        "has_more": has_more,
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Live-tail NDJSON streaming endpoints (Phase 3 — SP5)
+# --------------------------------------------------------------------------- #
+
+
+@router.get("/api/claims/stream")
+async def claims_stream(
+    request: Request,
+    status: str | None = Query(None),
+    provider_npi: str | None = Query(None),
+    payer: str | None = Query(None),
+    date_from: str | None = Query(None),
+    date_to: str | None = Query(None),
+    sort: str | None = Query(None),
+    order: str = Query("desc"),
+    limit: int = Query(100, ge=1, le=1000),
+) -> StreamingResponse:
+    """Stream Claims as NDJSON: snapshot first, then live events.
+
+    Wire format:
+      * ``{"type":"item","data":<claim>}`` per snapshot row, then per
+        new ``claim_written`` event
+      * ``{"type":"snapshot_end","data":{"count":N}}`` after the snapshot
+      * ``{"type":"heartbeat","data":{"ts":<iso>}}`` every
+        ``CYCLONE_TAIL_HEARTBEAT_S`` seconds when idle
+
+    Query params mirror :func:`list_claims` so a frontend can swap a
+    one-shot fetch for a tail with no URL surgery.
+
+    NOTE: registered before ``/api/claims/{claim_id}`` so the literal
+    ``stream`` path segment doesn't get matched as a claim id.
+    """
+    bus: EventBus = request.app.state.event_bus
+
+    async def gen() -> AsyncIterator[bytes]:
+        # 1. Snapshot (eager — iter_claims returns a list already).
+        rows = store.iter_claims(
+            status=status, provider_npi=provider_npi, payer=payer,
+            date_from=date_from, date_to=date_to,
+            sort=sort or "-submission_date", order=order, limit=limit,
+        )
+        for row in rows:
+            yield _ndjson_line({"type": "item", "data": row})
+        yield _ndjson_line({"type": "snapshot_end", "data": {"count": len(rows)}})
+
+        # 2. Subscribe + heartbeats.
+        async for chunk in _tail_events(request, bus, ["claim_written"]):
+            yield chunk
+
+    return StreamingResponse(gen(), media_type="application/x-ndjson")
+
+
+@router.get("/api/claims/{claim_id}")
+def get_claim_detail_endpoint(claim_id: str) -> dict:
+    """Return one claim with full drawer context (SP4).
+
+    Body shape is produced by :meth:`CycloneStore.get_claim_detail`:
+    header, state, service lines, diagnoses, parties, validation,
+    raw segments, ``stateHistory`` (most-recent-first, capped at 50),
+    and a populated ``matchedRemittance`` block when paired.
+
+    SP28: response gains ``ack_links: list[dict]`` (compact form:
+    ``[{ack_id, ack_kind, set_accept_reject_code, parsed_at}]``)
+    so the ``ClaimDrawer`` Acknowledgments panel can render on
+    initial load. TA1 batch-level rows (``claim_id IS NULL``) are
+    excluded — those don't belong to a specific claim.
+
+    Path param is ``claim_id`` (matches the SP3 ``/api/acks/{ack_id}``
+    convention). Returns 404 — never 500 — on a missing claim so the
+    UI can distinguish "doesn't exist" from a transient fetch error.
+    """
+    body = store.get_claim_detail(claim_id)
+    if body is None:
+        raise HTTPException(
+            status_code=404,
+            detail={
+                "error": "Not found",
+                "detail": f"Claim {claim_id} not found",
+            },
+        )
+    # SP28: attach ack_links (compact form for the drawer panel).
+    body["ack_links"] = _compact_ack_links_for_claim(claim_id)
+    return body
+
+
+def _compact_ack_links_for_claim(claim_id: str) -> list[dict]:
+    """Return compact ack_links for one claim, newest first.
+
+    TA1 batch-level rows (claim_id IS NULL) are filtered out — those
+    hang off the originating 837 batch, not a specific claim. The
+    shape is the slimmer ``{ack_id, ack_kind,
+    set_accept_reject_code, parsed_at, ak2_index}`` form so the
+    ClaimDrawer can render without an N+1 round-trip per row.
+    """
+    rows = store.list_acks_for_claim(claim_id)
+    out: list[dict] = []
+    for row in rows:
+        if row.claim_id is None:
+            continue
+        out.append({
+            "id": row.id,
+            "ack_id": row.ack_id,
+            "ack_kind": row.ack_kind,
+            "ak2_index": row.ak2_index,
+            "set_control_number": row.set_control_number,
+            "set_accept_reject_code": row.set_accept_reject_code,
+            "linked_at": (
+                row.linked_at.isoformat().replace("+00:00", "Z")
+                if row.linked_at is not None else ""
+            ),
+            "linked_by": row.linked_by,
+        })
+    return out
+
+
+@router.get("/api/claims/{claim_id}/serialize-837")
+def serialize_claim_as_837(claim_id: str):
+    """Return the claim as a regenerated X12 837P file (SP8).
+
+    Loads the ClaimOutput from the persisted ``raw_json`` and runs the
+    outbound serializer. Returns 404 if the claim doesn't exist, 422 if
+    the stored payload has no parseable ClaimOutput (data integrity
+    issue, not a transient failure).
+    """
+    with db.SessionLocal()() as s:
+        row = s.get(Claim, claim_id)
+        if row is None:
+            return JSONResponse(
+                {"error": "Not found", "detail": f"Claim {claim_id} not found"},
+                status_code=404,
+            )
+        if not row.raw_json:
+            return JSONResponse(
+                {
+                    "error": "Unprocessable",
+                    "detail": f"Claim {claim_id} has no raw_json; cannot serialize",
+                },
+                status_code=422,
+            )
+        try:
+            claim_obj = ClaimOutput.model_validate(row.raw_json)
+        except Exception as exc:
+            return JSONResponse(
+                {
+                    "error": "Unprocessable",
+                    "detail": f"Claim {claim_id} raw_json is malformed: {exc}",
+                },
+                status_code=422,
+            )
+
+    try:
+        text = serialize_837(claim_obj)
+    except SerializeError837 as exc:
+        return JSONResponse(
+            {"error": "Unprocessable", "detail": str(exc)},
+            status_code=422,
+        )
+
+    return Response(
+        content=text,
+        media_type="text/x12",
+        headers={
+            "Content-Disposition": f'attachment; filename="claim-{claim_id}.x12"'
+        },
+    )
+
+
+@router.get("/api/claims/{claim_id}/line-reconciliation")
+def get_claim_line_reconciliation(claim_id: str) -> dict:
+    """Per-line reconciliation view for the ClaimDrawer tab.
+
+    Spec §5.1. Returns the 837 service lines and 835 SVC composites
+    side-by-side, with per-line CAS adjustments and a summary block.
+
+    Architecture note: 837 service lines live in ``Claim.raw_json``
+    (not a separate ORM table), so the 837-side rows are read from the
+    JSON blob; the 835-side rows come from ``ServiceLinePayment`` ORM.
+    ``LineReconciliation.claim_service_line_number`` stores the 1-based
+    line number to join them.
+    """
+    from sqlalchemy import select
+    from cyclone.db import (
+        LineReconciliation, ServiceLinePayment, CasAdjustment,
+    )
+    import json as _json
+    from decimal import Decimal
+
+    with db.SessionLocal()() as s:
+        claim = s.get(db.Claim, claim_id)
+        if claim is None:
+            raise HTTPException(
+                status_code=404,
+                detail={"error": "Not found", "detail": f"Claim {claim_id} not found"},
+            )
+
+        # 837 service lines: from raw_json.
+        raw = claim.raw_json or {}
+        claim_lines_raw = raw.get("service_lines") or []
+        # Normalize to dicts for the response.
+        claim_lines = [_claim_line_dict(d) for d in claim_lines_raw]
+
+        # 835 service payments: ORM rows from the matched remit.
+        remits = list(
+            s.execute(
+                select(db.Remittance).where(db.Remittance.claim_id == claim_id)
+            ).scalars().all()
+        )
+        svc_payments: list[dict] = []
+        svc_ids: list[int] = []
+        if remits:
+            svc_rows = list(
+                s.execute(
+                    select(ServiceLinePayment).where(
+                        ServiceLinePayment.remittance_id.in_([r.id for r in remits])
+                    ).order_by(ServiceLinePayment.line_number)
+                ).scalars().all()
+            )
+            for svc in svc_rows:
+                d = _svc_to_dict(svc)
+                svc_payments.append(d)
+                svc_ids.append(svc.id)
+
+        # LineReconciliation rows.
+        lrs = list(
+            s.execute(
+                select(LineReconciliation).where(LineReconciliation.claim_id == claim_id)
+            ).scalars().all()
+        )
+        # Index by claim_service_line_number and service_line_payment_id.
+        lr_by_claim_num: dict[int, LineReconciliation] = {
+            lr.claim_service_line_number: lr for lr in lrs if lr.claim_service_line_number is not None
+        }
+        lr_by_svc: dict[int, LineReconciliation] = {
+            lr.service_line_payment_id: lr for lr in lrs if lr.service_line_payment_id is not None
+        }
+
+        # CAS rows grouped by svc id.
+        cas_by_svc: dict[int, list[CasAdjustment]] = {}
+        if svc_ids:
+            cas_rows = list(
+                s.execute(
+                    select(CasAdjustment).where(CasAdjustment.service_line_payment_id.in_(svc_ids))
+                ).scalars().all()
+            )
+            for c in cas_rows:
+                cas_by_svc.setdefault(c.service_line_payment_id, []).append(c)
+
+        # Build output lines array, preserving 837 order then 835-only.
+        svc_by_id: dict[int, dict] = {d["id"]: d for d in svc_payments}
+        lines_out: list[dict] = []
+        billed_total = Decimal("0")
+        paid_total = Decimal("0")
+        adjustment_total = Decimal("0")
+        matched_count = 0
+        used_svc_ids: set[int] = set()
+
+        for cl in claim_lines:
+            billed_total += Decimal(str(cl["charge"]))
+            lr = lr_by_claim_num.get(cl["line_number"])
+            if lr is None:
+                lines_out.append({
+                    "claim_service_line": cl,
+                    "service_line_payment": None,
+                    "status": "unmatched_837_only",
+                    "adjustments": [],
+                })
+                continue
+            svc_id = lr.service_line_payment_id
+            svc = svc_by_id.get(svc_id) if svc_id else None
+            if svc_id is not None:
+                used_svc_ids.add(svc_id)
+            cas_list = cas_by_svc.get(svc_id, []) if svc_id is not None else []
+            cas_total = sum((Decimal(str(c.amount)) for c in cas_list), Decimal("0"))
+            if svc:
+                paid_total += Decimal(str(svc["payment"]))
+            adjustment_total += cas_total
+            if lr.status == "matched":
+                matched_count += 1
+            lines_out.append({
+                "claim_service_line": cl,
+                "service_line_payment": svc,
+                "status": lr.status,
+                "adjustments": [
+                    {"group_code": c.group_code, "reason_code": c.reason_code,
+                     "amount": str(Decimal(str(c.amount)))}
+                    for c in cas_list
+                ],
+            })
+
+        # 835-only lines (no claim match).
+        for lr in lrs:
+            if lr.claim_service_line_number is not None:
+                continue
+            svc_id = lr.service_line_payment_id
+            if svc_id is None:
+                continue
+            if svc_id in used_svc_ids:
+                continue
+            svc = svc_by_id.get(svc_id)
+            cas_list = cas_by_svc.get(svc_id, [])
+            cas_total = sum((Decimal(str(c.amount)) for c in cas_list), Decimal("0"))
+            if svc:
+                paid_total += Decimal(str(svc["payment"]))
+            adjustment_total += cas_total
+            lines_out.append({
+                "claim_service_line": None,
+                "service_line_payment": svc,
+                "status": lr.status,
+                "adjustments": [
+                    {"group_code": c.group_code, "reason_code": c.reason_code,
+                     "amount": str(Decimal(str(c.amount)))}
+                    for c in cas_list
+                ],
+            })
+
+        return {
+            "claim_id": claim_id,
+            "summary": {
+                "billed_total": str(billed_total),
+                "paid_total": str(paid_total),
+                "adjustment_total": str(adjustment_total),
+                "matched_lines": matched_count,
+                "total_lines": len(claim_lines),
+            },
+            "lines": lines_out,
+        }
+
+
+def _claim_line_dict(d: dict) -> dict:
+    """Project an 837 service-line dict from ``Claim.raw_json`` to wire shape."""
+    from decimal import Decimal
+    proc = d.get("procedure") or {}
+    charge = d.get("charge")
+    units = d.get("units")
+    return {
+        "line_number": d.get("line_number"),
+        "procedure_qualifier": proc.get("qualifier", "HC"),
+        "procedure_code": proc.get("code", ""),
+        "modifiers": proc.get("modifiers") or [],
+        "charge": str(Decimal(str(charge))) if charge is not None else "0",
+        "units": str(Decimal(str(units))) if units is not None else None,
+        "unit_type": d.get("unit_type"),
+        "service_date": d.get("service_date"),
+    }
+
+
+def _svc_to_dict(svc) -> dict:
+    """Project an ORM ``ServiceLinePayment`` to wire shape."""
+    import json as _json
+    from decimal import Decimal
+    return {
+        "id": svc.id,
+        "line_number": svc.line_number,
+        "procedure_qualifier": svc.procedure_qualifier,
+        "procedure_code": svc.procedure_code,
+        "modifiers": _json.loads(svc.modifiers_json or "[]"),
+        "charge": str(Decimal(str(svc.charge))),
+        "payment": str(Decimal(str(svc.payment))),
+        "units": str(Decimal(str(svc.units))) if svc.units is not None else None,
+        "unit_type": svc.unit_type,
+        "service_date": svc.service_date.isoformat() if svc.service_date else None,
+    }

backend/src/cyclone/api_routers/clearhouse.py

@@ -0,0 +1,310 @@
+"""``/api/clearhouse*`` — singleton clearhouse config + SFTP submission.
+
+Three endpoints, all gated by ``matrix_gate``:
+
+- ``GET  /api/clearhouse``         — read the singleton clearhouse row
+  (dzinesco's identity, SFTP block, filename block). 404 when
+  unseeded.
+- ``PATCH /api/clearhouse``        — full-row replacement of the
+  singleton (SP25). Strict-validates ``sftp_block`` first (Pydantic
+  v2 default mode coerces strings-to-bools and would hide a real
+  operator mistake), then validates the whole body in loose mode.
+  Hot-reloads the running scheduler via
+  ``scheduler.reconfigure_scheduler`` so the next tick picks up the
+  new ``SftpBlock`` without a process restart.
+- ``POST /api/clearhouse/submit``  — submit a batch of claims to
+  the clearhouse. Stub: serializes via the SP7 serializer, builds
+  an HCPF-compliant outbound filename, copies the result to the
+  staging path. Per-claim audit events stamped with
+  ``actor="clearhouse-submit"``.
+
+Three single-router helpers stay in this file (per spec D4):
+
+- :func:`_load_claim_row`            — load a ``Claim`` row by id.
+- :func:`_serialize_claim_for_submit` — re-serialize a claim to X12
+  with optional per-call kwargs (submitter, receiver, SBR09, etc).
+- :func:`_serialize_claim_from_raw`  — best-effort serializer that
+  re-parses stored ``x12_text`` and re-emits.
+
+SP36 Task 11: this block moved here from ``api.py:2484`` (the 3
+``/api/clearhouse*`` routes + 3 single-router helpers).
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from cyclone import db
+from cyclone.api_routers._shared import _actor_user_id
+from cyclone.audit_log import AuditEvent, append_event
+from cyclone.auth.deps import matrix_gate
+from cyclone.db import Claim
+from cyclone.store import store
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.get("/api/clearhouse")
+def get_clearhouse():
+    """Return the singleton clearhouse config (dzinesco's identity, SFTP block, filename block)."""
+    ch = store.get_clearhouse()
+    if ch is None:
+        raise HTTPException(status_code=404, detail="clearhouse not seeded")
+    return json.loads(ch.model_dump_json())
+
+
+@router.patch("/api/clearhouse")
+async def patch_clearhouse(body: dict) -> Any:
+    """Replace the singleton clearhouse row (SP25).
+
+    The full ``Clearhouse`` model is required — we don't accept partial
+    updates because the operator-facing use case is "I'm switching the
+    loop to real MFT" or "I'm pointing at a different MFT server",
+    not "I'm tweaking one field at a time." Validation errors are
+    returned as 422 (Pydantic default).
+
+    After a successful write, the running scheduler is hot-reloaded
+    via ``scheduler.reconfigure_scheduler()`` so the next tick uses
+    the new SftpBlock without a process restart.
+    """
+    from cyclone import scheduler as _scheduler_mod
+    from cyclone.providers import Clearhouse as _Clearhouse, SftpBlock as _SftpBlock
+
+    # Strict-validate the sftp_block sub-dict FIRST. Pydantic v2's
+    # default mode coerces strings to bools (e.g. ``"stub": "yes"``
+    # silently becomes True), which would hide a real operator
+    # mistake. The Clearhouse model itself stays in loose mode so
+    # ISO-string ``updated_at`` (the JSON round-trip shape) keeps
+    # parsing.
+    raw_sb = body.get("sftp_block", {})
+    try:
+        _SftpBlock.model_validate(raw_sb, strict=True)
+    except Exception as exc:
+        raise HTTPException(
+            status_code=422, detail=f"invalid sftp_block: {exc}",
+        ) from exc
+
+    # Now validate the full body in loose mode.
+    try:
+        parsed = _Clearhouse.model_validate(body)
+    except Exception as exc:
+        raise HTTPException(
+            status_code=422, detail=str(exc),
+        ) from exc
+
+    # SP25: when sftp_block.stub=false, the block must carry an auth
+    # account name and a non-empty host. The Pydantic model catches
+    # some of these; this catches the "empty password_keychain_account"
+    # case (which Pydantic allows because it's a free-form dict).
+    sb = parsed.sftp_block
+    if not sb.stub:
+        if not sb.host:
+            raise HTTPException(
+                status_code=422,
+                detail="sftp_block.host is required when stub=false",
+            )
+        auth = sb.auth or {}
+        if not auth.get("password_keychain_account") and not auth.get("key_file"):
+            raise HTTPException(
+                status_code=422,
+                detail=(
+                    "sftp_block.auth must contain either "
+                    "'password_keychain_account' or 'key_file' when stub=false"
+                ),
+            )
+
+    updated = store.update_clearhouse(parsed)
+    await _scheduler_mod.reconfigure_scheduler(
+        updated.sftp_block,
+        sftp_block_name=updated.name or "default",
+    )
+    return json.loads(updated.model_dump_json())
+
+
+@router.post("/api/clearhouse/submit")
+def submit_to_clearhouse(request: Request, body: dict):
+    """Submit a batch of claims to the clearhouse (SFTP). SP9: stub.
+
+    Body: ``{"claim_ids": [...], "payer_id": "CO_TXIX"}``
+
+    Stub behavior: serializes each claim via the SP7 serializer, builds
+    an HCPF-compliant outbound filename, and copies the result to
+    ``{staging_dir}/{outbound_path}/{filename}`` instead of opening a
+    real SFTP connection. Returns a receipt per claim.
+    """
+    from cyclone.clearhouse import make_client
+    from cyclone.edi.filenames import build_outbound_filename
+
+    claim_ids = body.get("claim_ids", [])
+    payer_id = body.get("payer_id")
+    if not claim_ids:
+        raise HTTPException(status_code=400, detail="claim_ids required")
+    if not payer_id:
+        raise HTTPException(status_code=400, detail="payer_id required")
+
+    ch = store.get_clearhouse()
+    if ch is None:
+        raise HTTPException(status_code=500, detail="clearhouse not seeded")
+
+    # Submitter (Loop 1000A) comes from the clearhouse config. The
+    # receiver (NM1*40) and SBR09 come from the per-payer config and
+    # are resolved per-claim below. Without this wiring, the
+    # serializer would emit "CYCLONE" / "RECEIVER" placeholders and
+    # the file would be rejected by HCPF.
+    submitter_kwargs = {
+        "sender_id": ch.tpid,
+        "submitter_name": ch.submitter_name,
+        "submitter_contact_name": ch.submitter_contact_name,
+        "submitter_contact_email": ch.submitter_contact_email,
+    }
+    if getattr(ch, "submitter_contact_phone", None):
+        submitter_kwargs["submitter_contact_phone"] = ch.submitter_contact_phone
+
+    # Build a payer_id → PayerConfig837 map once so we can look up the
+    # receiver + SBR09 default for each claim.
+    from cyclone.db import PayerConfigORM as _PayerConfigORM
+
+    def _resolve_payer_cfg(claim_obj) -> dict | None:
+        pid = (claim_obj.payer.id or "").strip() if claim_obj.payer else ""
+        pname = (claim_obj.payer.name or "").strip() if claim_obj.payer else ""
+        with db.SessionLocal()() as ss:
+            if pid:
+                row = ss.get(_PayerConfigORM, (pid, "837P"))
+                if row is not None:
+                    return dict(row.config_json)
+            if pname:
+                rows = (
+                    ss.query(_PayerConfigORM)
+                    .filter(_PayerConfigORM.transaction_type == "837P")
+                    .all()
+                )
+                for r in rows:
+                    cj = dict(r.config_json)
+                    if (r.payer_id or "").upper() == pname.upper():
+                        return cj
+                    if pname.lower() in str(cj).lower():
+                        return cj
+            row = (
+                ss.query(_PayerConfigORM)
+                .filter(_PayerConfigORM.transaction_type == "837P")
+                .first()
+            )
+            return dict(row.config_json) if row else None
+
+    client = make_client(ch.sftp_block)
+    results = []
+    for cid in claim_ids:
+        try:
+            x12_text = _serialize_claim_for_submit(cid)
+        except Exception as exc:  # noqa: BLE001
+            results.append({"claim_id": cid, "ok": False, "error": str(exc)})
+            continue
+        # Re-resolve the claim so we can look up its payer config. We
+        # re-parse the stored x12_text to get a ClaimOutput (same path
+        # the serializer uses).
+        try:
+            from cyclone.parsers.parse_837 import parse as _parse837
+            claim_row_obj = _load_claim_row(cid)
+            if claim_row_obj is None or not (claim_row_obj.raw_json or {}).get("x12_text"):
+                raise RuntimeError("no stored x12_text for claim")
+            parsed = _parse837(claim_row_obj.raw_json["x12_text"])
+            claim_obj = parsed.claims[0] if parsed.claims else None
+        except Exception:
+            claim_obj = None
+        if claim_obj is not None:
+            payer_cfg = _resolve_payer_cfg(claim_obj) or {}
+            receiver_id = payer_cfg.get("receiver_id") or (claim_obj.payer.id if claim_obj.payer else None) or "RECEIVER"
+            receiver_name = payer_cfg.get("receiver_name") or (claim_obj.payer.name if claim_obj.payer else None) or receiver_id
+            sbr09 = payer_cfg.get("sbr09_default") or "MC"
+            # Re-serialize with the proper envelope values.
+            try:
+                x12_text = _serialize_claim_for_submit(
+                    cid,
+                    **{**submitter_kwargs, "receiver_id": receiver_id,
+                       "receiver_name": receiver_name,
+                       "claim_filing_indicator_code": sbr09},
+                )
+            except Exception as exc:  # noqa: BLE001
+                results.append({"claim_id": cid, "ok": False, "error": str(exc)})
+                continue
+        filename = build_outbound_filename(ch.tpid, "837P")
+        remote = f"{ch.sftp_block.paths['outbound']}/{filename}"
+        staging_path = client.write_file(remote, x12_text.encode("utf-8"))
+        results.append({
+            "claim_id": cid,
+            "ok": True,
+            "filename": filename,
+            "staging_path": str(staging_path),
+            "remote_path": remote,
+        })
+        # SP11: audit trail for each successful clearhouse submission.
+        with db.SessionLocal()() as audit_s:
+            append_event(audit_s, AuditEvent(
+                event_type="clearhouse.submitted",
+                entity_type="claim",
+                entity_id=cid,
+                payload={
+                    "filename": filename,
+                    "remote_path": remote,
+                    "tpid": ch.tpid,
+                    "stub": ch.sftp_block.stub,
+                },
+                actor="clearhouse-submit",
+                user_id=_actor_user_id(request),
+            ))
+            audit_s.commit()
+    return {"ok": True, "submitted": results, "stub": ch.sftp_block.stub}
+
+
+def _load_claim_row(claim_id: str):
+    """Helper: load a Claim row by id (or return None)."""
+    with db.SessionLocal()() as s:
+        return s.get(Claim, claim_id)
+
+
+def _serialize_claim_for_submit(claim_id: str, **kwargs) -> str:
+    """Serialize a claim to X12 for SFTP submission. Lazy import of the
+    serializer to avoid pulling FastAPI machinery at module import time.
+
+    Optional ``**kwargs`` are forwarded to the serializer — used to
+    pass through clearhouse submitter info and per-payer receiver info
+    so the regenerated file matches what the HCPF MFT expects.
+    """
+    from cyclone.parsers.serialize_837 import serialize_837
+    from cyclone import db
+    with db.SessionLocal()() as s:
+        row = s.get(db.Claim, claim_id)
+        if row is None:
+            raise ValueError(f"claim {claim_id!r} not found")
+        # Re-parse the stored raw_json to get a ClaimOutput
+        from cyclone.parsers.models import ClaimOutput, Envelope, Subscriber, Payer, BillingProvider
+        from cyclone.parsers.parse_837 import parse
+        raw = row.raw_json or {}
+        # Reconstruct minimal ClaimOutput from raw_json; this is best-effort.
+        return _serialize_claim_from_raw(row, raw, **kwargs)
+
+
+def _serialize_claim_from_raw(claim_row, raw: dict, **kwargs) -> str:
+    """Best-effort serializer that uses the stored raw_json to emit a fresh 837.
+
+    For SP9 this delegates to the existing serialize_837 helper if the
+    claim has a complete raw_segments array. Otherwise it returns a
+    minimal placeholder. ``**kwargs`` are forwarded to the serializer
+    so callers can pass through submitter / receiver / SBR09 values
+    from the clearhouse and per-payer configs.
+    """
+    from cyclone.parsers.serialize_837 import serialize_837
+    from cyclone.parsers.parse_837 import parse
+
+    # Re-parse the original batch text (need to re-derive from store).
+    # SP9 stub: if the claim has a `raw_json` with `x12_text`, use that.
+    if isinstance(raw, dict) and raw.get("x12_text"):
+        result = parse(raw["x12_text"])
+        if result.claims:
+            return serialize_837(result.claims[0], **kwargs)
+    # Fallback: raise so the caller sees an error.
+    raise RuntimeError(
+        f"claim {claim_row.id!r} cannot be re-serialized: no stored x12_text"
+    )

backend/src/cyclone/api_routers/config.py

@@ -0,0 +1,54 @@
+"""``/api/config/payers`` and ``/api/config/payers/{payer_id}/configs`` — payer-config read views.
+
+Both endpoints are read-only configuration surfaces used by the UI's
+"Edit payers" page:
+
+- ``GET /api/config/payers?is_active=...`` lists all configured
+  payers (PayerConfig records) — the set of payers the operator has
+  registered, regardless of whether they have inbound config blocks.
+- ``GET /api/config/payers/{payer_id}/configs`` returns the full
+  list of ``(transaction_type, config_json)`` blocks for a given
+  payer. Each block has a ``source``: ``"yaml"`` for the on-disk
+  ``config/payers.yaml`` default, ``"db"`` for any runtime override
+  recorded via ``/api/admin/reload-config``.
+
+These are configuration surfaces, not claim-processing surfaces.
+They live here (under ``/api/config/``) rather than under
+``/api/payers/`` because the latter is the drill-down rollup
+(see ``api_routers/payers.py``).
+
+SP36 Task 7: this block moved here from ``api.py:3167`` (after
+the SP21 provider-detail helper, before the Auth routers divider).
+"""
+from __future__ import annotations
+
+import json
+
+from fastapi import APIRouter, Depends, Query
+
+from cyclone import store
+from cyclone.auth.deps import matrix_gate
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.get("/api/config/payers")
+def list_configured_payers(is_active: bool | None = Query(default=True)):
+    return [json.loads(p.model_dump_json()) for p in store.list_payers(is_active=is_active)]
+
+
+@router.get("/api/config/payers/{payer_id}/configs")
+def list_payer_configs(payer_id: str):
+    """List all (transaction_type, config_json) blocks for a payer."""
+    from cyclone import payers as payer_loader
+    configs = [
+        {"transaction_type": tx, "config_json": block, "source": "yaml"}
+        for (pid, tx), block in payer_loader.all_configs().items()
+        if pid == payer_id
+    ]
+    # Also check the DB for runtime-overridden configs
+    for tx in ("837P", "835", "277CA", "999", "TA1"):
+        live = store.get_payer_config(payer_id, tx)
+        if live is not None:
+            configs.append({"transaction_type": tx, "config_json": live, "source": "db"})
+    return configs

backend/src/cyclone/api_routers/dashboard.py

@@ -0,0 +1,39 @@
+"""``/api/dashboard/kpis`` — server-aggregated Dashboard tiles.
+
+Backs the Dashboard's "Claims / Billed / Received / Pending AR /
+Denial rate" tiles + the monthly sparkline series + the
+top-providers and top-denials lists.
+
+Why this exists instead of ``GET /api/claims?limit=N``:
+The Dashboard's KPIs are aggregates over *every* claim — billed,
+received, denial rate, pending count, monthly billed/received. With
+60k+ claims in production, paginating ``/api/claims`` and reducing
+client-side silently produces wrong numbers (denial rate sampled,
+billed summed from the first 100 rows). This endpoint does the
+aggregation server-side in a single read so the Dashboard's numbers
+are always correct regardless of dataset size.
+
+SP36 Task 4: this single endpoint moved here from ``api.py:2732``.
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+
+from cyclone.auth.deps import matrix_gate
+from cyclone.store import dashboard_kpis
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.get("/api/dashboard/kpis")
+def get_dashboard_kpis(
+    months: int = Query(6, ge=1, le=24),
+    top_n_providers: int = Query(4, ge=0, le=50),
+    top_n_denials: int = Query(5, ge=0, le=50),
+) -> dict:
+    """Server-aggregated Dashboard KPIs over the whole claim population."""
+    return dashboard_kpis(
+        months=months,
+        top_n_providers=top_n_providers,
+        top_n_denials=top_n_denials,
+    )

backend/src/cyclone/api_routers/eligibility.py

@@ -0,0 +1,223 @@
+"""``/api/eligibility/request`` and ``/api/eligibility/parse-271`` — API-only eligibility pair.
+
+Builds a 270 inquiry from a small JSON body and parses a 271 response.
+Nothing is persisted to the DB — these are operator-driven, ephemeral
+operations per SP3 (P4 T23–T24). The 270 serializer pulls X12 from a
+``ParseResult270`` Pydantic; the 271 parser builds the same structure
+in reverse from the wire format.
+
+Why these are not ``GET /api/eligibility/...``: the 270 build is
+operator-initiated (pay-portal paste-back), so the inbound surface is
+a JSON ``POST``. The 271 inbound is a multipart file upload — same
+shape as ``/api/parse-999`` — so the file can be the actual 271 text
+saved from the payer portal.
+
+SP36 Task 5: this block moved here from ``api.py:2832`` (``270 / 271
+eligibility`` divider).
+"""
+from __future__ import annotations
+
+import json
+import logging
+from datetime import date as _date
+from typing import Any
+
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
+from fastapi.responses import JSONResponse
+
+from cyclone.auth.deps import matrix_gate
+from cyclone.parsers.exceptions import CycloneParseError
+from cyclone.parsers.models import BatchSummary, Envelope
+from cyclone.parsers.models_270 import (
+    EligibilityBenefitInquiry,
+    InformationReceiver270,
+    InformationSource270,
+    ParseResult270,
+    Subscriber270,
+)
+from cyclone.parsers.parse_271 import parse as parse_271_text
+from cyclone.parsers.serialize_270 import serialize_270
+
+log = logging.getLogger(__name__)
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+def _validate_eligibility_request(body: dict) -> tuple[ParseResult270, str]:
+    """Build a :class:`ParseResult270` from a request body dict.
+
+    The body shape is the minimum surface needed to build a valid 270
+    inquiry (per spec section 3.4 — operator-driven, ephemeral):
+
+    ::
+
+        {
+            "subscriber": {first_name, last_name, member_id, dob},
+            "provider":   {npi, name},
+            "payer":      {id, name},
+            "service_type_code": "1"
+        }
+
+    Returns ``(ParseResult270, service_type_code)``. Raises
+    :class:`HTTPException` (400) when the body is missing required
+    fields.
+    """
+    subscriber_in = body.get("subscriber") or {}
+    provider_in = body.get("provider") or {}
+    payer_in = body.get("payer") or {}
+    service_type_code = (body.get("service_type_code") or "").strip()
+
+    # Required-field checks. We surface a single 400 with the first
+    # missing field name to match the rest of the API's error contract.
+    if not service_type_code:
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "Bad request", "detail": "service_type_code is required"},
+        )
+    if not subscriber_in.get("member_id"):
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "Bad request", "detail": "subscriber.member_id is required"},
+        )
+    if not provider_in.get("npi"):
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "Bad request", "detail": "provider.npi is required"},
+        )
+    if not payer_in.get("name"):
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "Bad request", "detail": "payer.name is required"},
+        )
+
+    # Build the Pydantic models. The serializer handles all envelope
+    # generation (sender_id/receiver_id/control_number/transaction_date
+    # are filled in by the serializer with sensible defaults).
+    subscriber_dob_raw = subscriber_in.get("dob")
+    subscriber_dob: _date | None = None
+    if subscriber_dob_raw:
+        try:
+            subscriber_dob = _date.fromisoformat(subscriber_dob_raw)
+        except (TypeError, ValueError) as exc:
+            raise HTTPException(
+                status_code=400,
+                detail={
+                    "error": "Bad request",
+                    "detail": f"subscriber.dob must be YYYY-MM-DD: {exc}",
+                },
+            ) from exc
+
+    result = ParseResult270(
+        envelope=Envelope(
+            sender_id="SUBMITTERID",
+            receiver_id=str(payer_in.get("id") or "RECEIVERID"),
+            control_number="000000001",
+            transaction_date=_date.today(),
+            implementation_guide="005010X279A1",
+        ),
+        information_source=InformationSource270(
+            name=str(payer_in["name"]),
+            id=str(payer_in.get("id") or "") or None,
+        ),
+        information_receiver=InformationReceiver270(
+            name=str(provider_in.get("name") or ""),
+            npi=str(provider_in["npi"]),
+        ),
+        subscriber=Subscriber270(
+            member_id=str(subscriber_in["member_id"]),
+            first_name=str(subscriber_in.get("first_name") or "") or None,
+            last_name=str(subscriber_in.get("last_name") or "") or None,
+            dob=subscriber_dob,
+        ),
+        inquiries=[EligibilityBenefitInquiry(service_type_code=service_type_code)],
+        summary=BatchSummary(
+            input_file="eligibility_request",
+            control_number="000000001",
+            transaction_date=_date.today(),
+            total_claims=1,
+            passed=1,
+            failed=0,
+        ),
+    )
+    return result, service_type_code
+
+
+@router.post("/api/eligibility/request")
+def post_eligibility_request(body: dict) -> Any:
+    """Build a 270 eligibility inquiry from a small JSON body.
+
+    Returns ``{"raw_270_text": <X12>, "parsed": <ParseResult270>}``
+    so the operator can either download the raw text (paste into a
+    payer portal) or render the parsed fields directly. Per spec
+    section 3.4, nothing is persisted to the DB.
+    """
+    try:
+        result, _ = _validate_eligibility_request(body)
+    except HTTPException:
+        raise
+    except (KeyError, TypeError, ValueError) as exc:
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "Bad request", "detail": f"Malformed body: {exc}"},
+        ) from exc
+
+    raw_270_text = serialize_270(result)
+    return {
+        "raw_270_text": raw_270_text,
+        "parsed": json.loads(result.model_dump_json()),
+    }
+
+
+@router.post("/api/eligibility/parse-271")
+async def post_eligibility_parse_271(
+    file: UploadFile = File(...),
+) -> Any:
+    """Parse a 271 eligibility response and return the structured summary.
+
+    Accepts the raw 271 text as a file upload (multipart/form-data),
+    mirrors the ``/api/parse-999`` contract. Per spec section 3.4 the
+    result is NOT persisted — the operator re-pastes the 271 each
+    time they need a fresh read.
+
+    The response body is a JSON object with three top-level keys:
+    ``coverage_benefits``, ``subscriber``, and ``summary``. 400 is
+    returned on empty / undecodable / malformed EDI; 200 on success.
+    """
+    raw = await file.read()
+    if not raw:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Empty file", "detail": "Uploaded file contained no bytes."},
+        )
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Encoding error", "detail": str(exc)},
+        )
+
+    try:
+        result = parse_271_text(text, input_file=file.filename or "")
+    except CycloneParseError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Parse error", "detail": str(exc)},
+        )
+    except Exception as exc:  # pragma: no cover - safety net
+        log.exception("Unexpected parser failure on 271")
+        return JSONResponse(
+            status_code=500,
+            content={"error": "Internal server error", "detail": str(exc)},
+        )
+
+    return {
+        "coverage_benefits": [
+            json.loads(cb.model_dump_json()) for cb in result.coverage_benefits
+        ],
+        "subscriber": json.loads(result.subscriber.model_dump_json()),
+        "summary": json.loads(result.summary.model_dump_json()),
+        "envelope": json.loads(result.envelope.model_dump_json()),
+        "information_source": json.loads(result.information_source.model_dump_json()),
+        "information_receiver": json.loads(result.information_receiver.model_dump_json()),
+    }

backend/src/cyclone/api_routers/inbox.py

@@ -0,0 +1,342 @@
+"""``/api/inbox*`` — operator-facing Inbox surface (SP6 + SP14).
+
+Six endpoints, all gated by ``matrix_gate``:
+
+- ``GET  /api/inbox/lanes``                       — all lanes in one
+  call (``compute_lanes`` from :mod:`cyclone.inbox_lanes`).
+- ``POST /api/inbox/candidates/{remit_id}/match`` — manually link a
+  remit to a claim; surfaces 409 with the current state when the
+  claim is already matched.
+- ``POST /api/inbox/candidates/dismiss``          — add candidate
+  pairs to the session-scoped dismissed set (mutates
+  ``request.app.state.dismissed_pairs``).
+- ``POST /api/inbox/payer-rejected/acknowledge``  — SP14: mark
+  Payer-Rejected claims as acknowledged. Idempotent; returns the
+  count actually transitioned vs. already-acked / not-found /
+  not-rejected.
+- ``POST /api/inbox/rejected/resubmit``           — bulk move
+  REJECTED claims back to SUBMITTED. With
+  ``?download=true`` returns a ZIP of regenerated 837 files
+  (``serialize_837_for_resubmit`` with per-claim ``interchange_index``
+  for unique control numbers). Conflicts are omitted from the ZIP
+  and surfaced via the ``X-Cyclone-Serialize-Errors`` header.
+- ``GET  /api/inbox/export.csv``                  — stream a CSV for
+  a single lane (rejected / candidates / unmatched / done_today).
+
+All endpoints use ``request.app.state`` rather than the module-level
+``app`` global so they're robust against ``importlib.reload`` of
+the api module — the reload rebinds ``app`` to a new instance, but
+``request.app`` always points at the instance actually serving the
+current request.
+
+SP36 Task 13: this block moved here from ``api.py:1280`` (the 6
+``/api/inbox*`` routes, with the SP14 comment block preserved
+verbatim).
+"""
+from __future__ import annotations
+
+import csv
+import io
+import json
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
+from fastapi.responses import StreamingResponse
+
+from cyclone import db
+from cyclone.auth.deps import matrix_gate
+from cyclone.db import Claim, ClaimState, Remittance
+from cyclone.parsers.models import ClaimOutput
+from cyclone.parsers.serialize_837 import SerializeError as SerializeError837
+from cyclone.parsers.serialize_837 import serialize_837_for_resubmit
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.get("/api/inbox/lanes")
+def inbox_lanes(request: Request):
+    """Return all Inbox lanes in one call.
+
+    Uses ``request.app.state`` rather than the module-level ``app``
+    global so the endpoint is robust against ``importlib.reload`` of
+    this module (some tests do this to mutate the CORS allow-list).
+    After a reload, the module-level ``app`` rebinds to a new
+    FastAPI instance; ``request.app`` always points at the instance
+    that is actually serving the current request, so per-request
+    state stays consistent with the test's TestClient target.
+    """
+    dismissed_pairs = getattr(request.app.state, "dismissed_pairs", set())
+    with db.SessionLocal()() as session:
+        from cyclone.inbox_lanes import compute_lanes
+        lanes = compute_lanes(session, dismissed_pairs=dismissed_pairs)
+    return {
+        "rejected": lanes.rejected,
+        # SP10: payer-rejected lane (277CA STC A4/A6/A7). Distinct from
+        # the 999 envelope rejection in ``rejected`` above.
+        "payer_rejected": lanes.payer_rejected,
+        "candidates": lanes.candidates,
+        "unmatched": lanes.unmatched,
+        "done_today": lanes.done_today,
+    }
+
+
+@router.post("/api/inbox/candidates/{remit_id}/match")
+def inbox_match_candidate(remit_id: str, body: dict):
+    """Manually link a remit to a claim."""
+    claim_id = body.get("claim_id")
+    if not claim_id:
+        raise HTTPException(400, "claim_id required")
+    with db.SessionLocal()() as s:
+        claim = s.get(Claim, claim_id)
+        remit = s.get(Remittance, remit_id)
+        if claim is None or remit is None:
+            raise HTTPException(404, "claim or remit not found")
+        if claim.matched_remittance_id and claim.matched_remittance_id != remit_id:
+            raise HTTPException(
+                409,
+                detail={
+                    "error": "claim_already_matched",
+                    "current_state": (
+                        claim.state.value if hasattr(claim.state, "value")
+                        else str(claim.state)
+                    ),
+                    "matched_remittance_id": claim.matched_remittance_id,
+                },
+            )
+        claim.matched_remittance_id = remit_id
+        remit.claim_id = claim_id
+        s.commit()
+    return {"ok": True, "claim_id": claim_id, "remit_id": remit_id}
+
+
+@router.post("/api/inbox/candidates/dismiss")
+def inbox_dismiss_candidates(body: dict, request: Request):
+    """Add candidate pairs to the session-scoped dismissed set.
+
+    Uses ``request.app.state`` rather than the module-level ``app``
+    global so the endpoint is robust against ``importlib.reload`` of
+    this module (some tests do this to mutate the CORS allow-list).
+    After a reload, the module-level ``app`` rebinds to a new
+    FastAPI instance; ``request.app`` always points at the instance
+    that is actually serving the current request, so the test's
+    TestClient target is the one whose state we mutate.
+    """
+    pairs = body.get("pairs") or []
+    if not hasattr(request.app.state, "dismissed_pairs"):
+        request.app.state.dismissed_pairs = set()
+    for p in pairs:
+        cid = p.get("claim_id")
+        rid = p.get("remit_id")
+        if cid and rid:
+            request.app.state.dismissed_pairs.add(frozenset({cid, rid}))
+    return {"ok": True, "dismissed_count": len(pairs)}
+
+
+# --------------------------------------------------------------------------- #
+# SP14: Payer-Rejected acknowledge
+#
+# Operator hits "Acknowledge" on the Payer-Rejected Inbox lane to clear
+# the claim from the working surface. We don't delete the rejection
+# (the original payer_rejected_* fields stay for SP11 audit), we just
+# set payer_rejected_acknowledged_at so the lane query filters it out.
+#
+# Idempotent: re-acknowledging an already-acknowledged claim is a noop
+# (the timestamp is not bumped). Returns the count actually transitioned
+# so the UI can show "3 of 5 were already acknowledged".
+# --------------------------------------------------------------------------- #
+@router.post("/api/inbox/payer-rejected/acknowledge")
+def inbox_acknowledge_payer_rejected(body: dict):
+    """Mark Payer-Rejected claims as acknowledged by the operator."""
+    claim_ids = body.get("claim_ids") or []
+    actor = body.get("actor") or "operator"
+    if not isinstance(claim_ids, list) or not claim_ids:
+        raise HTTPException(400, "claim_ids must be a non-empty list")
+    if not all(isinstance(c, str) for c in claim_ids):
+        raise HTTPException(400, "claim_ids must be a list of strings")
+
+    with db.SessionLocal()() as session:
+        from cyclone.db import Claim
+        now = datetime.now(timezone.utc)
+        transitioned = 0
+        already_acked = 0
+        not_found = 0
+        not_rejected = 0
+        for cid in claim_ids:
+            claim = session.get(Claim, cid)
+            if claim is None:
+                not_found += 1
+                continue
+            if claim.payer_rejected_at is None:
+                not_rejected += 1
+                continue
+            if claim.payer_rejected_acknowledged_at is not None:
+                already_acked += 1
+                continue
+            claim.payer_rejected_acknowledged_at = now
+            claim.payer_rejected_acknowledged_actor = actor
+            transitioned += 1
+            # SP11: audit event for the acknowledge action.
+            try:
+                from cyclone.audit_log import append_event, AuditEvent
+                append_event(session, AuditEvent(
+                    event_type="claim.payer_rejected_acknowledged",
+                    entity_type="claim",
+                    entity_id=claim.id,
+                    actor=actor,
+                    payload={
+                        "payer_rejected_status_code": claim.payer_rejected_status_code,
+                        "payer_rejected_by_277ca_id": claim.payer_rejected_by_277ca_id,
+                    },
+                ))
+            except Exception:  # noqa: BLE001
+                # Audit append is best-effort; don't block the operator's
+                # acknowledge action on an audit-log failure.
+                pass
+        if transitioned:
+            session.commit()
+
+    return {
+        "ok": True,
+        "transitioned": transitioned,
+        "already_acked": already_acked,
+        "not_found": not_found,
+        "not_rejected": not_rejected,
+    }
+
+
+@router.post("/api/inbox/rejected/resubmit")
+def inbox_resubmit_rejected(
+    request: Request,
+    body: dict,
+    download: bool = Query(False, description="When true, return a ZIP of regenerated 837 files for the resubmitted claims (instead of JSON)."),
+):
+    """Bulk move REJECTED claims back to SUBMITTED.
+
+    With ``?download=true``, the response is a ``application/zip`` archive
+    containing one ``claim-{id}.x12`` per successfully resubmitted claim
+    (regenerated via ``serialize_837_for_resubmit`` so each file gets a
+    unique interchange/group control number). Conflicts are omitted from
+    the ZIP — they remain visible to the caller via the JSON shape of the
+    non-download path. Empty resubmit + download → 200 with an empty zip
+    so the UI can still hand the user a downloadable artifact.
+    """
+    ids = body.get("claim_ids") or []
+    if not ids:
+        raise HTTPException(400, "claim_ids required")
+    accepted: list[str] = []
+    conflicts: list[dict] = []
+    # Track which claims are about to be resubmitted (and their index in
+    # the bundle) so the download path can serialize them with unique
+    # control numbers — back-to-back resubmits in the same file would
+    # otherwise all share ISA13/GS06 = "000000001".
+    accepted_with_rows: list[tuple[str, "Claim"]] = []
+    with db.SessionLocal()() as s:
+        for cid in ids:
+            c = s.get(Claim, cid)
+            if c is None:
+                continue
+            if c.state != ClaimState.REJECTED:
+                conflicts.append({
+                    "claim_id": cid,
+                    "current_state": (
+                        c.state.value if hasattr(c.state, "value")
+                        else str(c.state)
+                    ),
+                })
+                continue
+            c.state = ClaimState.SUBMITTED
+            c.state_changed_at = datetime.now(timezone.utc)
+            c.rejection_reason = None
+            c.rejected_at = None
+            c.resubmit_count = (c.resubmit_count or 0) + 1
+            accepted.append(cid)
+            accepted_with_rows.append((cid, c))
+        s.commit()
+
+    if not download:
+        return {"ok": True, "resubmitted": accepted, "conflicts": conflicts}
+
+    # Build a ZIP of regenerated 837s for the accepted claims. Conflicts
+    # and missing ids are deliberately excluded — the user already saw
+    # them in the JSON response on prior actions; the download is the
+    # "give me the files I asked for" payload.
+    import zipfile
+    buf = io.BytesIO()
+    serialize_errors: list[dict] = []
+    with zipfile.ZipFile(buf, mode="w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for idx, (cid, c) in enumerate(accepted_with_rows, start=1):
+            if not c.raw_json:
+                serialize_errors.append({"claim_id": cid, "reason": "no raw_json"})
+                continue
+            try:
+                claim_obj = ClaimOutput.model_validate(c.raw_json)
+            except Exception as exc:
+                serialize_errors.append({"claim_id": cid, "reason": f"raw_json invalid: {exc}"})
+                continue
+            try:
+                text = serialize_837_for_resubmit(claim_obj, interchange_index=idx)
+            except SerializeError837 as exc:
+                serialize_errors.append({"claim_id": cid, "reason": str(exc)})
+                continue
+            zf.writestr(f"claim-{cid}.x12", text)
+    buf.seek(0)
+    headers = {
+        "Content-Disposition": (
+            f'attachment; filename="resubmit-{len(accepted)}-claims.zip"'
+        ),
+    }
+    # Surface per-claim serialization failures as a custom response header
+    # so the UI can show "10 resubmitted, 2 couldn't be regenerated" without
+    # parsing the binary. The header value is JSON-encoded; the UI is
+    # expected to JSON.parse it after a fetch with response.ok.
+    if serialize_errors:
+        headers["X-Cyclone-Serialize-Errors"] = json.dumps(serialize_errors)
+    return Response(
+        content=buf.getvalue(),
+        media_type="application/zip",
+        headers=headers,
+    )
+
+
+@router.get("/api/inbox/export.csv")
+def inbox_export_csv(lane: str, request: Request):
+    """Stream a CSV for a single lane.
+
+    Uses ``request.app.state`` rather than the module-level ``app``
+    global so the endpoint is robust against ``importlib.reload`` of
+    this module (see ``inbox_dismiss_candidates`` for context).
+    """
+    if lane not in {"rejected", "candidates", "unmatched", "done_today"}:
+        raise HTTPException(400, f"unknown lane: {lane}")
+    dismissed_pairs = getattr(request.app.state, "dismissed_pairs", set())
+    with db.SessionLocal()() as session:
+        from cyclone.inbox_lanes import compute_lanes
+        lanes = compute_lanes(session, dismissed_pairs=dismissed_pairs)
+    rows = getattr(lanes, lane)
+
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow([
+        "id", "kind", "patient_control_number", "charge_amount",
+        "payer_id", "provider_npi", "state", "rejection_reason",
+        "service_date", "score",
+    ])
+    for r in rows:
+        writer.writerow([
+            r.get("id") or r.get("payer_claim_control_number"),
+            r.get("kind"),
+            r.get("patient_control_number"),
+            r.get("charge_amount"),
+            r.get("payer_id"),
+            r.get("provider_npi") or r.get("rendering_provider_npi"),
+            r.get("state"),
+            r.get("rejection_reason"),
+            r.get("service_date_from") or r.get("service_date"),
+            r.get("score"),
+        ])
+    buf.seek(0)
+    return StreamingResponse(
+        iter([buf.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": f'attachment; filename="inbox-{lane}.csv"'},
+    )

backend/src/cyclone/api_routers/parse.py

@@ -0,0 +1,831 @@
+"""Parse endpoints — accept X12 uploads and ingest them.
+
+Five routes:
+
+* ``POST /api/parse-837`` — 837P professional claim ingest (the
+  primary upload path)
+* ``POST /api/parse-835`` — 835 ERA remittance ingest
+* ``POST /api/parse-999`` — 999 ACK ingest + auto-link claims
+* ``POST /api/parse-ta1`` — TA1 envelope ACK ingest + envelope-link batches
+* ``POST /api/parse-277ca`` — 277CA Claim Acknowledgment ingest
+
+The 7 cross-router helpers these endpoints need (and the two
+PAYER_FACTORIES dicts they consume) live in
+:mod:`cyclone.api_routers._shared`.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from typing import Any
+
+from fastapi import APIRouter, Depends, File, Query, Request, UploadFile
+from fastapi.responses import JSONResponse, StreamingResponse
+from sqlalchemy.exc import IntegrityError
+
+from cyclone import db
+from cyclone.api_helpers import (
+    client_wants_json as _client_wants_json,
+    drop_raw_segments_837 as _drop_raw_segments,
+    drop_raw_segments_835 as _drop_raw_segments_835,
+    has_claim_validation_errors as _has_claim_validation_errors,
+    has_835_validation_errors as _has_835_validation_errors,
+    ndjson_stream_837 as _ndjson_stream,
+    ndjson_stream_835 as _ndjson_stream_835,
+    strict_rewrite_837 as _strict_rewrite,
+    strict_rewrite_835 as _strict_rewrite_835,
+)
+from cyclone.api_routers._shared import (
+    _actor_user_id,
+    _build_and_persist_ack,
+    _reconciliation_summary_for_batch,
+    _resolve_payer,
+    _resolve_payer_835,
+    _serialize_ta1,
+    _ta1_synthetic_source_batch_id,
+    _transaction_set_id_from_segments,
+)
+from cyclone.audit_log import AuditEvent, append_event
+from cyclone.auth.deps import matrix_gate
+from cyclone.claim_acks import (
+    apply_277ca_acks as _apply_277ca_acks,
+    apply_999_acceptances as _apply_999_acceptances,
+    apply_ta1_envelope_link as _apply_ta1_envelope_link,
+)
+from cyclone.db import Batch, Claim
+from cyclone.handlers._ack_id import (
+    ack_count_summary as _ack_count_summary,
+    ack_synthetic_source_batch_id as _ack_synthetic_source_batch_id,
+    two77ca_synthetic_source_batch_id as _277ca_synthetic_source_batch_id,
+)
+from cyclone.inbox_state import apply_999_rejections
+from cyclone.inbox_state_277ca import apply_277ca_rejections
+from cyclone.parsers.exceptions import CycloneParseError
+from cyclone.parsers.parse_277ca import parse_277ca_text
+from cyclone.parsers.parse_837 import parse
+from cyclone.parsers.parse_835 import parse as parse_835
+from cyclone.parsers.parse_999 import parse_999_text
+from cyclone.parsers.parse_ta1 import parse_ta1_text
+from cyclone.parsers.segments import tokenize as _tokenize_segments
+from cyclone.parsers.serialize_999 import serialize_999
+from cyclone.parsers.validator_835 import validate as validate_835
+from cyclone.store import BatchRecord, store, utcnow
+
+log = logging.getLogger(__name__)
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.post("/api/parse-837")
+async def parse_837(
+    request: Request,
+    file: UploadFile = File(...),
+    payer: str = Query("co_medicaid"),
+    include_raw_segments: bool = Query(True),
+    strict: bool = Query(False),
+    ack: bool = Query(False),
+) -> Any:
+    # SP35: defense-in-depth input guards. Layer A (UI auto-detect) lives
+    # in src/pages/Upload.tsx; the server-side checks below are the
+    # authoritative fix because they protect every caller of the API
+    # (Upload page, CLI ingestion, any future bulk-import tool). Without
+    # these, an 835 file dropped on the Upload page while the dropdown
+    # still says "837p" produces a BatchRecord with claims=[] and a bogus
+    # row on the History tab. The fix is two checks run BEFORE we persist
+    # anything:
+    #
+    #   1. Envelope check — ST01 must be "837" or "837P". Anything else
+    #      (an 835, a 999, a 270, garbage that happens to have an ISA)
+    #      → 400 with error="Mismatched file kind", expected="837p",
+    #      detected_st=<whatever was there>.
+    #   2. Empty-claims check — even with the right envelope, if the
+    #      parser produced zero CLM segments (truncated file, header-only
+    #      test fixture) → 400 with error="No claims parsed". A real
+    #      production 837 batch with zero claims is never valid.
+    raw = await file.read()
+    if not raw:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Empty file", "detail": "Uploaded file contained no bytes."},
+        )
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Encoding error", "detail": str(exc)},
+        )
+
+    config = _resolve_payer(payer)
+
+    # SP35 guard 1: envelope check. Tokenize first so we can return a
+    # precise 400 (vs. relying on the parser's "no ISA envelope" error
+    # which is correct but doesn't say "you sent an 835 to the 837
+    # endpoint"). If tokenization itself fails we fall through to the
+    # parser, which raises CycloneParseError → 400 "Parse error" path.
+    try:
+        _segments = _tokenize_segments(text)
+        detected_st = _transaction_set_id_from_segments(_segments) or ""
+    except CycloneParseError:
+        detected_st = ""
+
+    if detected_st and not detected_st.upper().startswith("837"):
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Mismatched file kind",
+                "expected": "837p",
+                "detected_st": detected_st,
+                "detail": (
+                    f"File declares ST*{detected_st}* but this endpoint "
+                    f"expects ST*837*. Pick the matching endpoint on the "
+                    f"Upload page (or let auto-detect choose for you)."
+                ),
+            },
+        )
+
+    try:
+        result = parse(text, config, input_file=file.filename or "")
+    except CycloneParseError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Parse error", "detail": str(exc)},
+        )
+    except Exception as exc:  # pragma: no cover - safety net
+        log.exception("Unexpected parser failure")
+        return JSONResponse(
+            status_code=500,
+            content={"error": "Internal server error", "detail": str(exc)},
+        )
+
+    # SP35 guard 2: empty-claims check. With the envelope validated, the
+    # only way to land here is a header-only file (real, but useless)
+    # or a file whose CLM loops the parser couldn't extract. Either way
+    # we refuse to persist — a BatchRecord with claims=[] is what the
+    # original bug produced and is never what the operator wanted.
+    if not result.claims:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "No claims parsed",
+                "detail": (
+                    "The file passed the envelope check but contained no "
+                    "CLM segments. Refusing to persist an empty batch."
+                ),
+            },
+        )
+
+    if strict:
+        result = _strict_rewrite(result)
+    if not include_raw_segments:
+        result = _drop_raw_segments(result)
+
+    if _has_claim_validation_errors(result):
+        # Per spec: 422 when claims failed validation.
+        # Body still includes the full ParseResult so the client can show errors.
+        # Validation-failed parses are NOT persisted (the data is suspect);
+        # only parses that survive validation end up in the store.
+        return JSONResponse(
+            status_code=422,
+            content=json.loads(result.model_dump_json()),
+        )
+
+    # Persist the cleaned-up result so the cleaned result is what clients
+    # retrieve via /api/batches/{id}.
+    rec = BatchRecord(
+        id=uuid.uuid4().hex,
+        kind="837p",
+        input_filename=file.filename or "upload.txt",
+        parsed_at=utcnow(),
+        result=result,
+    )
+    try:
+        store.add(rec, event_bus=request.app.state.event_bus)
+    except IntegrityError as exc:
+        # ``(batch_id, patient_control_number)`` is UNIQUE — fires when a
+        # single batch file contains the same CLM01 control number twice,
+        # or when the same claim id has already been ingested in a prior
+        # batch. Surface as 409 with the batch id so the caller can look
+        # it up; do NOT 500 (a 500 without CORS headers is misreported by
+        # browsers as a CORS error and hides the real cause).
+        log.warning("Duplicate claim while persisting batch %s: %s", rec.id, exc)
+        return JSONResponse(
+            status_code=409,
+            content={
+                "error": "Duplicate claim",
+                "detail": (
+                    "This file (or one previously ingested with the same "
+                    "claim control number) collides with an existing "
+                    "record. Inspect the file for duplicate CLM01 "
+                    "control numbers, or remove the existing batch "
+                    "before retrying."
+                ),
+                "batch_id": rec.id,
+            },
+        )
+
+    if _client_wants_json(request):
+        body = json.loads(result.model_dump_json())
+        if ack:
+            ack_body = _build_and_persist_ack(rec.id)
+            if ack_body is not None:
+                body["ack"] = ack_body
+        # Surface the server-side batch id so the frontend can call
+        # /api/batches/{id}/export-837 (and any other batch-scoped
+        # endpoint) without a separate listBatches round-trip.
+        body["batch_id"] = rec.id
+        return JSONResponse(content=body)
+
+    # Default: NDJSON stream. Pass the server-side batch id so the
+    # streaming client (the React Upload page) can call batch-scoped
+    # endpoints like /api/batches/{id}/export-837 without a separate
+    # GET /api/batches round-trip.
+    return StreamingResponse(
+        _ndjson_stream(result, batch_id=rec.id),
+        media_type="application/x-ndjson",
+    )
+
+
+@router.post("/api/parse-835")
+async def parse_835_endpoint(
+    request: Request,
+    file: UploadFile = File(...),
+    payer: str = Query("co_medicaid_835"),
+    include_raw_segments: bool = Query(True),
+    strict: bool = Query(False),
+) -> Any:
+    raw = await file.read()
+    if not raw:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Empty file", "detail": "Uploaded file contained no bytes."},
+        )
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Encoding error", "detail": str(exc)},
+        )
+
+    config = _resolve_payer_835(payer)
+
+    # SP35 guard 1: envelope check. Mirrors the parse-837 path: tokenize,
+    # read ST01, reject anything that doesn't start with "835". Same
+    # defense-in-depth rationale — the UI auto-detect (src/pages/Upload.tsx)
+    # is layer A, but server-side guards protect every API caller.
+    try:
+        _segments_835 = _tokenize_segments(text)
+        detected_st_835 = _transaction_set_id_from_segments(_segments_835) or ""
+    except CycloneParseError:
+        detected_st_835 = ""
+
+    if detected_st_835 and not detected_st_835.upper().startswith("835"):
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "Mismatched file kind",
+                "expected": "835",
+                "detected_st": detected_st_835,
+                "detail": (
+                    f"File declares ST*{detected_st_835}* but this endpoint "
+                    f"expects ST*835*. Pick the matching endpoint on the "
+                    f"Upload page (or let auto-detect choose for you)."
+                ),
+            },
+        )
+
+    try:
+        result = parse_835(text, config, input_file=file.filename or "")
+    except CycloneParseError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Parse error", "detail": str(exc)},
+        )
+    except Exception as exc:  # pragma: no cover - safety net
+        log.exception("Unexpected parser failure")
+        return JSONResponse(
+            status_code=500,
+            content={"error": "Internal server error", "detail": str(exc)},
+        )
+
+    # SP35 guard 2: empty-claims check. Same as parse-837: a BatchRecord
+    # with claims=[] is never a valid production 835 batch and we refuse
+    # to persist it.
+    if not result.claims:
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": "No claims parsed",
+                "detail": (
+                    "The file passed the envelope check but contained no "
+                    "CLP segments. Refusing to persist an empty batch."
+                ),
+            },
+        )
+
+    # Always run the validator; attach the report so the JSON path can
+    # surface it and the NDJSON path can fold the counts into the summary.
+    # 835 validation is batch-level, so pass/fail applies uniformly to every
+    # claim payment in the batch (passed=N or 0, failed=0 or N).
+    report = validate_835(result, config)
+    n = len(result.claims)
+    claim_ids = [c.payer_claim_control_number for c in result.claims]
+    if report.passed:
+        passed, failed, failed_claim_ids = n, 0, []
+    else:
+        passed, failed, failed_claim_ids = 0, n, claim_ids
+    result = result.model_copy(update={
+        "validation": report,
+        "summary": result.summary.model_copy(update={
+            "passed": passed,
+            "failed": failed,
+            "failed_claim_ids": failed_claim_ids,
+        }),
+    })
+
+    if strict:
+        result = _strict_rewrite_835(result)
+    if not include_raw_segments:
+        result = _drop_raw_segments_835(result)
+
+    if _has_835_validation_errors(result):
+        return JSONResponse(
+            status_code=422,
+            content=json.loads(result.model_dump_json()),
+        )
+
+    # Persist the cleaned-up result so the cleaned result is what clients
+    # retrieve via /api/batches/{id}.
+    rec = BatchRecord(
+        id=uuid.uuid4().hex,
+        kind="835",
+        input_filename=file.filename or "upload.txt",
+        parsed_at=utcnow(),
+        result=result,
+    )
+    try:
+        store.add(rec, event_bus=request.app.state.event_bus)
+    except IntegrityError as exc:
+        log.warning("Duplicate remittance while persisting batch %s: %s", rec.id, exc)
+        return JSONResponse(
+            status_code=409,
+            content={
+                "error": "Duplicate remittance",
+                "detail": (
+                    "This 835 file (or one previously ingested with the "
+                    "same payer claim control number) collides with an "
+                    "existing record. Remove the existing remittance "
+                    "before retrying."
+                ),
+                "batch_id": rec.id,
+            },
+        )
+
+    if _client_wants_json(request):
+        body = json.loads(result.model_dump_json())
+        body["reconciliation"] = _reconciliation_summary_for_batch(rec.id)
+        return JSONResponse(content=body)
+
+    # Default: NDJSON stream. Pass the server-side batch id so the
+    # streaming client can call batch-scoped endpoints without a
+    # separate GET /api/batches round-trip (see /api/parse-837 for the
+    # parallel change).
+    return StreamingResponse(
+        _ndjson_stream_835(result, batch_id=rec.id),
+        media_type="application/x-ndjson",
+    )
+
+
+@router.post("/api/parse-999")
+async def parse_999_endpoint(
+    request: Request,
+    file: UploadFile = File(...),
+) -> Any:
+    """Parse a 999 ACK file, persist a row, and return JSON.
+
+    Behavior mirrors ``/api/parse-835``:
+    - 400 on empty / undecodable / malformed EDI (never 500).
+    - 200 on success with ``{"ack": {id, accepted_count, rejected_count,
+      received_count, ack_code, raw_999_text}, "parsed": <ParseResult999>}``.
+
+    The persisted ``acks.source_batch_id`` is a synthetic id
+    (``999-<ISA13>``) because a received 999 has no inbound 837 batch
+    to FK to. The dashboard's `/acks` list surfaces these; operators
+    can still see which interchange each row came from.
+    """
+    raw = await file.read()
+    if not raw:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Empty file", "detail": "Uploaded file contained no bytes."},
+        )
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Encoding error", "detail": str(exc)},
+        )
+
+    try:
+        result = parse_999_text(text, input_file=file.filename or "")
+    except CycloneParseError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Parse error", "detail": str(exc)},
+        )
+    except Exception as exc:  # pragma: no cover - safety net
+        log.exception("Unexpected parser failure on 999")
+        return JSONResponse(
+            status_code=500,
+            content={"error": "Internal server error", "detail": str(exc)},
+        )
+
+    received, accepted, rejected, ack_code = _ack_count_summary(result)
+    icn = result.envelope.control_number
+    synthetic_id = _ack_synthetic_source_batch_id(icn)
+
+    # Build the raw 999 text from the parsed result (round-trip).
+    raw_999_text = serialize_999(result, interchange_control_number=icn or "000000001")
+
+    # SP6 T4: move claims whose 999 set was rejected into ClaimState.REJECTED.
+    # The 999's set_control_number (AK202) is the source 837's ST02; in
+    # practice we look it up against patient_control_number because that's
+    # the field 999 ACKs cross-reference in this product.
+    with db.SessionLocal()() as session:
+        def _lookup(pcn: str):
+            return session.query(Claim).filter_by(patient_control_number=pcn).first()
+        _rejection_result = apply_999_rejections(
+            session, result, claim_lookup=_lookup,
+        )
+    if _rejection_result.matched:
+        bus = request.app.state.event_bus
+        for cid in _rejection_result.matched:
+            await bus.publish("claim.rejected", {"claim_id": cid})
+    if _rejection_result.orphans:
+        log.warning(
+            "999 had %d orphan set refs: %s",
+            len(_rejection_result.orphans),
+            _rejection_result.orphans[:5],
+        )
+
+    row = store.add_ack(
+        source_batch_id=synthetic_id,
+        accepted_count=accepted,
+        rejected_count=rejected,
+        received_count=received,
+        ack_code=ack_code,
+        raw_json=json.loads(result.model_dump_json()),
+        event_bus=request.app.state.event_bus,
+    )
+
+    # SP11: append one audit row per rejected claim. Each row chains
+    # to the previous one — see cyclone.audit_log.
+    if _rejection_result.matched:
+        with db.SessionLocal()() as audit_s:
+            for cid in _rejection_result.matched:
+                append_event(audit_s, AuditEvent(
+                    event_type="claim.rejected",
+                    entity_type="claim",
+                    entity_id=cid,
+                    payload={"source_batch_id": synthetic_id, "ack_id": row.id},
+                    actor="999-parser",
+                    user_id=_actor_user_id(request),
+                ))
+            audit_s.commit()
+
+    # SP28: auto-link the 999 AK2 set-responses to claims via the
+    # D10 two-pass join (ST02 via batch envelope index primary,
+    # Claim.patient_control_number fallback). Each created ClaimAck
+    # row publishes claim_ack_written so the live-tail subscribers
+    # on the claim and ack side see the link immediately.
+    claim_ack_links_count = 0
+    with db.SessionLocal()() as link_s:
+        batch_index = store.batch_envelope_index()
+
+        def _pcn_lookup(pcn: str):
+            return (
+                link_s.query(Claim)
+                .filter(Claim.patient_control_number == pcn)
+                .first()
+            )
+
+        link_result = _apply_999_acceptances(
+            link_s, result, ack_id=row.id,
+            batch_envelope_index=batch_index,
+            pc_claim_lookup=_pcn_lookup,
+        )
+        for link_row in link_result.linked:
+            store.add_claim_ack(
+                claim_id=link_row.claim_id,
+                batch_id=link_row.batch_id,
+                ack_id=row.id,
+                ack_kind="999",
+                ak2_index=link_row.ak2_index,
+                set_control_number=link_row.set_control_number,
+                set_accept_reject_code=link_row.set_accept_reject_code,
+                linked_by="auto",
+                event_bus=request.app.state.event_bus,
+            )
+            claim_ack_links_count += 1
+
+    return JSONResponse(content={
+        "ack": {
+            "id": row.id,
+            "accepted_count": accepted,
+            "rejected_count": rejected,
+            "received_count": received,
+            "ack_code": ack_code,
+            "source_batch_id": synthetic_id,
+            "raw_999_text": raw_999_text,
+            "claim_ack_links_count": claim_ack_links_count,
+        },
+        "parsed": json.loads(result.model_dump_json()),
+    })
+
+
+@router.post("/api/parse-ta1")
+async def parse_ta1_endpoint(
+    request: Request,
+    file: UploadFile = File(...),
+) -> Any:
+    """Parse a TA1 (Interchange Acknowledgment) file, persist a row, return JSON.
+
+    Mirrors ``/api/parse-999`` but for the lower-level envelope ack:
+      - 400 on empty / undecodable / malformed EDI (never 500).
+      - 200 on success with ``{"ta1": {id, control_number, ack_code,
+        note_code, interchange_date, interchange_time, sender_id,
+        receiver_id, source_batch_id, raw_ta1_text}, "parsed":
+        <ParseResultTa1>}``.
+
+    The persisted ``ta1_acks.source_batch_id`` is a synthetic id
+    (``TA1-<ISA13>``) because a received TA1 has no inbound batch to
+    FK to. The dashboard's ``/ta1-acks`` list surfaces these.
+
+    SP25: threads ``event_bus=request.app.state.event_bus`` into
+    ``store.add_ta1_ack`` so the live-tail ``ta1_ack_received``
+    stream fires on manual uploads (not just on the SFTP poller).
+    """
+    raw = await file.read()
+    if not raw:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Empty file", "detail": "Uploaded file contained no bytes."},
+        )
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Encoding error", "detail": str(exc)},
+        )
+
+    try:
+        result = parse_ta1_text(text, input_file=file.filename or "")
+    except CycloneParseError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Parse error", "detail": str(exc)},
+        )
+    except Exception as exc:  # pragma: no cover - safety net
+        log.exception("Unexpected parser failure on TA1")
+        return JSONResponse(
+            status_code=500,
+            content={"error": "Internal server error", "detail": str(exc)},
+        )
+
+    # Build the raw TA1 text from the parsed result (round-trip).
+    raw_ta1_text = _serialize_ta1(result)
+
+    row = store.add_ta1_ack(
+        source_batch_id=result.source_batch_id,
+        control_number=result.ta1.control_number,
+        interchange_date=result.ta1.interchange_date,
+        interchange_time=result.ta1.interchange_time,
+        ack_code=result.ta1.ack_code,
+        note_code=result.ta1.note_code,
+        ack_generated_date=result.ta1.ack_generated_date,
+        sender_id=result.envelope.sender_id,
+        receiver_id=result.envelope.receiver_id,
+        raw_json=json.loads(result.model_dump_json()),
+        event_bus=request.app.state.event_bus,
+    )
+
+    # SP28: TA1 envelope-level link to the originating Batch. The
+    # closure here matches the most-recent Batch whose envelope
+    # sender_id/receiver_id matches the TA1 — see spec §D4.
+    claim_ack_links_count = 0
+    with db.SessionLocal()() as link_s:
+        def _batch_lookup(sender_id, receiver_id):
+            rows = (
+                link_s.query(Batch)
+                .filter(
+                    Batch.kind == "837p",
+                    Batch.raw_result_json.isnot(None),
+                )
+                .order_by(Batch.parsed_at.desc())
+                .all()
+            )
+            for row in rows:
+                env = (row.raw_result_json or {}).get("envelope") or {}
+                if (
+                    env.get("sender_id") == sender_id
+                    and env.get("receiver_id") == receiver_id
+                ):
+                    return row
+            return None
+
+        link_result = _apply_ta1_envelope_link(
+            link_s, result, ack_id=row.id,
+            batch_lookup=_batch_lookup,
+        )
+        for link_row in link_result.linked:
+            store.add_claim_ack(
+                claim_id=link_row.claim_id,
+                batch_id=link_row.batch_id,
+                ack_id=row.id,
+                ack_kind="ta1",
+                ak2_index=link_row.ak2_index,
+                set_control_number=link_row.set_control_number,
+                set_accept_reject_code=link_row.set_accept_reject_code,
+                linked_by="auto",
+                event_bus=request.app.state.event_bus,
+            )
+            claim_ack_links_count += 1
+
+    return JSONResponse(content={
+        "ta1": {
+            "id": row.id,
+            "control_number": result.ta1.control_number,
+            "ack_code": result.ta1.ack_code,
+            "note_code": result.ta1.note_code,
+            "interchange_date": result.ta1.interchange_date.isoformat()
+                if result.ta1.interchange_date else None,
+            "interchange_time": result.ta1.interchange_time,
+            "sender_id": result.envelope.sender_id,
+            "receiver_id": result.envelope.receiver_id,
+            "source_batch_id": result.source_batch_id,
+            "raw_ta1_text": raw_ta1_text,
+            "claim_ack_links_count": claim_ack_links_count,
+        },
+        "parsed": json.loads(result.model_dump_json()),
+    })
+
+
+@router.post("/api/parse-277ca")
+async def parse_277ca_endpoint(
+    request: Request,
+    file: UploadFile = File(...),
+) -> Any:
+    """Parse a 277CA Claim Acknowledgment file, persist a row, and stamp rejections.
+
+    Behavior mirrors ``/api/parse-999``:
+    - 400 on empty / undecodable / malformed EDI (never 500).
+    - 200 on success with ``{"ack": {id, control_number, accepted_count,
+      rejected_count, payer_claim_control_numbers, raw_277ca_text},
+      "parsed": <ParseResult277CA>}``.
+
+    After parse, runs :func:`apply_277ca_rejections` to stamp the
+    payer-rejected fields on each matching claim row. The Inbox
+    Payer-Rejected lane lights up as a side-effect of this call.
+    """
+    raw = await file.read()
+    if not raw:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Empty file", "detail": "Uploaded file contained no bytes."},
+        )
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Encoding error", "detail": str(exc)},
+        )
+
+    try:
+        result = parse_277ca_text(text, input_file=file.filename or "")
+    except CycloneParseError as exc:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "Parse error", "detail": str(exc)},
+        )
+    except Exception as exc:  # pragma: no cover - safety net
+        log.exception("Unexpected parser failure on 277CA")
+        return JSONResponse(
+            status_code=500,
+            content={"error": "Internal server error", "detail": str(exc)},
+        )
+
+    icn = result.envelope.control_number
+    synthetic_id = _277ca_synthetic_source_batch_id(icn)
+
+    accepted = sum(1 for s in result.claim_statuses if s.classification == "accepted")
+    paid = sum(1 for s in result.claim_statuses if s.classification == "paid")
+    rejected = sum(1 for s in result.claim_statuses if s.classification == "rejected")
+    pended = sum(1 for s in result.claim_statuses if s.classification == "pended")
+
+    # Persist the 277CA row first so we have an id to attach to claims.
+    # SP25: thread the event bus so ``two77ca_ack_received`` fires.
+    row = store.add_277ca_ack(
+        source_batch_id=synthetic_id,
+        control_number=icn,
+        accepted_count=accepted,
+        rejected_count=rejected,
+        paid_count=paid,
+        pended_count=pended,
+        raw_json=json.loads(result.model_dump_json()),
+        event_bus=request.app.state.event_bus,
+    )
+
+    # Stamp payer-rejection fields on matching claims. The 277CA's
+    # REF*1K carries the patient's claim control number we sent in
+    # CLM01 — same convention the 999 ACK uses, so the lookup hits
+    # Claim.patient_control_number (mirrors apply_999_rejections).
+    with db.SessionLocal()() as session:
+        def _lookup(pcn: str):
+            return (
+                session.query(Claim)
+                .filter(Claim.patient_control_number == pcn)
+                .first()
+            )
+        apply_result = apply_277ca_rejections(
+            session, result, claim_lookup=_lookup, two77ca_id=row.id,
+        )
+    if apply_result.matched:
+        bus = request.app.state.event_bus
+        for cid in apply_result.matched:
+            await bus.publish("claim.payer_rejected", {"claim_id": cid})
+        # SP11: audit trail for each payer-rejected claim.
+        with db.SessionLocal()() as audit_s:
+            for cid in apply_result.matched:
+                append_event(audit_s, AuditEvent(
+                    event_type="claim.payer_rejected",
+                    entity_type="claim",
+                    entity_id=cid,
+                    payload={
+                        "source_batch_id": synthetic_id,
+                        "277ca_id": row.id,
+                    },
+                    actor="277ca-parser",
+                    user_id=_actor_user_id(request),
+                ))
+            audit_s.commit()
+    if apply_result.orphans:
+        log.warning(
+            "277CA had %d orphan status entries (no matching claim): %s",
+            len(apply_result.orphans),
+            apply_result.orphans[:5],
+        )
+
+    # SP28: auto-link the 277CA ClaimStatus entries to claims via
+    # the D10 two-pass join. Each ClaimAck row publishes
+    # claim_ack_written so the live-tail subscribers on the claim
+    # and ack side see the link immediately.
+    claim_ack_links_count = 0
+    with db.SessionLocal()() as link_s:
+        batch_index = store.batch_envelope_index()
+
+        def _pcn_lookup(pcn: str):
+            return (
+                link_s.query(Claim)
+                .filter(Claim.patient_control_number == pcn)
+                .first()
+            )
+
+        link_result = _apply_277ca_acks(
+            link_s, result, ack_id=row.id,
+            batch_envelope_index=batch_index,
+            pc_claim_lookup=_pcn_lookup,
+        )
+        for link_row in link_result.linked:
+            store.add_claim_ack(
+                claim_id=link_row.claim_id,
+                batch_id=link_row.batch_id,
+                ack_id=row.id,
+                ack_kind="277ca",
+                ak2_index=link_row.ak2_index,
+                set_control_number=link_row.set_control_number,
+                set_accept_reject_code=link_row.set_accept_reject_code,
+                linked_by="auto",
+                event_bus=request.app.state.event_bus,
+            )
+            claim_ack_links_count += 1
+
+    return JSONResponse(content={
+        "ack": {
+            "id": row.id,
+            "control_number": icn,
+            "accepted_count": accepted,
+            "rejected_count": rejected,
+            "paid_count": paid,
+            "pended_count": pended,
+            "source_batch_id": synthetic_id,
+            "matched_claim_ids": apply_result.matched,
+            "orphan_status_codes": apply_result.orphans,
+            "claim_ack_links_count": claim_ack_links_count,
+        },
+        "parsed": json.loads(result.model_dump_json()),
+    })

backend/src/cyclone/api_routers/payers.py

@@ -0,0 +1,149 @@
+"""``GET /api/payers/{payer_id}/summary`` — payer-level rollup for the drill-down panel.
+
+Returns billed/received totals, denial rate, and the top providers for
+a given ``payer_id`` (the X12 NM1*PR*PI qualifier, e.g. ``SKCO0``).
+Cached in-process for ``_SUMMARY_TTL_S`` seconds via a per-payer_id
+memo. The drill-down UI hammers this on every hover; the underlying
+query is O(claims) per payer, so the TTL keeps the panel responsive.
+
+Pubsub invalidation is intentionally NOT wired (see the long comment
+in the body). The 60s TTL keeps staleness bounded; a follow-up can
+wire targeted invalidation if the UI proves TTL-bounded staleness is
+unacceptable.
+
+404 when no claims AND no remits reference this payer_id — the UI
+uses that to distinguish a typo from a payer with zero traffic (the
+latter would still return a valid 200 with zeroed totals).
+
+SP36 Task 6: this block moved here from ``api.py:3188`` (the
+``SP21 Task 1.5: payer-level summary`` divider).
+"""
+from __future__ import annotations
+
+import logging
+from time import monotonic
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from cyclone import db
+from cyclone.auth.deps import matrix_gate
+from cyclone.db import Claim, ClaimState, Remittance
+
+log = logging.getLogger(__name__)
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+# Per-payer_id memoization for /api/payers/{payer_id}/summary. The drill-
+# down UI hammers this on every hover; the underlying query is O(claims)
+# per payer so a 60s TTL keeps the panel responsive. Process-local on
+# purpose — invalidation is driven by the TTL alone for now (see note
+# below).
+_SUMMARY_TTL_S = 60.0
+_summary_cache: dict[str, tuple[float, dict]] = {}
+
+
+def _clear_summary_cache() -> None:
+    """Test hook: wipe the process-local cache.
+
+    The 60s TTL means tests that want to assert on a recomputed payload
+    must clear the cache between requests. Not used by production code.
+    """
+    _summary_cache.clear()
+
+
+# Pubsub invalidation is intentionally NOT wired. The ``claim_written``
+# and ``remittance_written`` payloads emitted by ``store.add`` are the
+# UI-shaped dicts from ``to_ui_claim_from_orm`` / ``to_ui_remittance_from_orm``,
+# neither of which carries the X12 ``payer_id`` (NM1*PR*PI qualifier).
+# They carry ``payerName`` only, which is the human-readable name and not
+# the URL key we cache on. Wiring a subscriber here would either need a
+# DB lookup per event (re-deriving payer_id from Claim.id) or a different
+# cache key — both are out of scope for this task. The 60s TTL keeps
+# staleness bounded; a follow-up can wire targeted invalidation if the
+# UI proves TTL-bounded staleness is unacceptable.
+
+
+@router.get("/api/payers/{payer_id}/summary")
+def get_payer_summary(payer_id: str):
+    """Payer-level rollup for the drill-down panel.
+
+    Returns billed/received totals, denial rate, and top providers for
+    the given ``payer_id`` (the X12 NM1*PR*PI qualifier, e.g. ``SKCO0``).
+    Cached in-process for ``_SUMMARY_TTL_S`` seconds.
+
+    404 when no claims AND no remits reference this payer_id — the UI
+    uses that to distinguish a typo from a payer with zero traffic
+    (the latter would still return a valid 200 with zeroed totals).
+    """
+    now = monotonic()
+    cached = _summary_cache.get(payer_id)
+    if cached and (now - cached[0]) < _SUMMARY_TTL_S:
+        return cached[1]
+
+    log.debug("payer summary cache miss", extra={"payer_id": payer_id})
+
+    # Query claims + remits scoped to this payer_id. We bypass
+    # ``store.iter_claims`` because that helper filters by payer NAME
+    # substring, not by the X12 PI qualifier we use as the URL key.
+    with db.SessionLocal()() as s:
+        claim_rows: list[Claim] = (
+            s.query(Claim).filter(Claim.payer_id == payer_id).all()
+        )
+        claim_ids = [c.id for c in claim_rows]
+        remit_rows: list[Remittance] = []
+        if claim_ids:
+            remit_rows = (
+                s.query(Remittance)
+                .filter(Remittance.claim_id.in_(claim_ids))
+                .all()
+            )
+
+        if not claim_rows and not remit_rows:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Payer {payer_id!r} not found",
+            )
+
+        billed_total = sum(float(c.charge_amount or 0) for c in claim_rows)
+        received_total = sum(float(r.total_paid or 0) for r in remit_rows)
+        denied = sum(
+            1 for c in claim_rows if c.state == ClaimState.DENIED
+        )
+        claim_count = len(claim_rows)
+        denial_rate = (denied / claim_count) if claim_count else 0.0
+
+        provider_counts: dict[str, int] = {}
+        for c in claim_rows:
+            npi = c.provider_npi
+            if not npi:
+                continue
+            provider_counts[npi] = provider_counts.get(npi, 0) + 1
+        top_providers = [
+            {"npi": npi, "count": count}
+            for npi, count in sorted(
+                provider_counts.items(), key=lambda kv: -kv[1]
+            )[:5]
+        ]
+
+        # Best-effort payer display name from the first claim's raw
+        # payer object (NM1*PR name element, e.g. "COHCPF"). Falls
+        # back to the id when no parsed envelope is available.
+        payer_name = payer_id
+        for c in claim_rows:
+            raw = c.raw_json or {}
+            p = raw.get("payer") if isinstance(raw, dict) else None
+            if isinstance(p, dict) and p.get("name"):
+                payer_name = p["name"]
+                break
+
+    payload = {
+        "payer_id": payer_id,
+        "name": payer_name,
+        "claim_count": claim_count,
+        "billed_total": billed_total,
+        "received_total": received_total,
+        "denial_rate": denial_rate,
+        "top_providers": top_providers,
+    }
+    _summary_cache[payer_id] = (now, payload)
+    return payload

backend/src/cyclone/api_routers/providers.py

@@ -0,0 +1,150 @@
+"""``/api/providers`` and ``/api/config/providers*`` — read views over providers.
+
+Three endpoints across two URL prefixes, all gated by ``matrix_gate``:
+
+- ``GET /api/providers``                  — distinct provider list
+  derived from the Claims population (``store.distinct_providers()``),
+  with ``npi`` / ``state`` filters, pagination, and an NDJSON variant.
+- ``GET /api/config/providers``           — the configured provider
+  rows (3 NPIs for SP9), filtered by ``is_active``.
+- ``GET /api/config/providers/{npi}``     — one configured provider
+  plus a small drill-down block: ``recent_claims`` (top-10 by
+  ``submissionDate``) and ``recent_activity`` (top-10, joined via
+  ``Claim.id`` because ``ActivityEvent`` has no ``provider_npi``
+  column; the outer-join via ``Remittance.claim_id`` surfaces the
+  orphan ``remit_received`` events that were recorded pre-match).
+
+SP36 Task 12: this block moved here from ``api.py:2448`` (the
+``/api/providers`` list, the ``/api/config/providers`` list, and
+the ``/api/config/providers/{npi}`` detail) — three URL prefixes,
+one router per spec.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi.responses import StreamingResponse
+from sqlalchemy import desc, or_
+
+from cyclone import db
+from cyclone.api_helpers import (
+    ndjson_stream_list as _ndjson_stream_list,
+    wants_ndjson as _wants_ndjson,
+)
+from cyclone.auth.deps import matrix_gate
+from cyclone.db import Claim, Remittance
+from cyclone.store import store
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.get("/api/providers")
+def list_providers(
+    request: Request,
+    npi: str | None = Query(None),
+    state: str | None = Query(None),
+    limit: int = Query(100, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+) -> Any:
+    items = store.distinct_providers()
+    if npi is not None:
+        items = [p for p in items if p["npi"] == npi]
+    if state is not None:
+        items = [p for p in items if p.get("state") == state]
+    paged = items[offset:offset + limit]
+    total = len(items)
+    returned = len(paged)
+    has_more = total > offset + returned
+    if _wants_ndjson(request):
+        return StreamingResponse(
+            _ndjson_stream_list(paged, total, returned, has_more),
+            media_type="application/x-ndjson",
+        )
+    return {
+        "items": paged,
+        "total": total,
+        "returned": returned,
+        "has_more": has_more,
+    }
+
+
+@router.get("/api/config/providers")
+def list_configured_providers(is_active: bool | None = Query(default=True)):
+    """List the configured provider rows (3 NPIs for SP9)."""
+    return [json.loads(p.model_dump_json()) for p in store.list_providers(is_active=is_active)]
+
+
+@router.get("/api/config/providers/{npi}")
+def get_configured_provider(npi: str):
+    p = store.get_provider(npi)
+    if p is None:
+        raise HTTPException(status_code=404, detail=f"provider {npi!r} not found")
+    provider_dict = json.loads(p.model_dump_json())
+
+    # SP21 Task 1.6: extend the response with two top-N arrays that the
+    # drill-down peek panel hangs off. ``recent_claims`` reuses the
+    # existing store projection (already returns UI-shaped dicts with
+    # ``submissionDate``); ``recent_activity`` is a direct ORM join
+    # because ``ActivityEvent`` has no ``provider_npi`` column — the
+    # filter has to hop through ``Claim.id``.
+    recent_claims = sorted(
+        store.iter_claims(provider_npi=npi),
+        key=lambda c: c.get("submissionDate") or "",
+        reverse=True,
+    )[:10]
+
+    # Activity filter has TWO join paths back to a Claim for this
+    # provider:
+    #   1. ``ActivityEvent.claim_id IN (claim_ids)`` — events that were
+    #      recorded with a claim FK already set (claim_submitted,
+    #      manual_match, claim_paid, etc.).
+    #   2. ``Remittance.claim_id IN (claim_ids)`` — the original
+    #      ``remit_received`` event recorded at 835 ingest time
+    #      (``store.add`` lines 999-1003) is inserted with
+    #      ``claim_id=None`` because the remittance hasn't been matched
+    #      to a claim yet. The auto-reconcile pass later sets
+    #      ``Remittance.claim_id`` (``reconcile.run`` lines 289-293),
+    #      but the *original* ActivityEvent row stays orphaned. The
+    #      outer-join-then-OR lets us surface both shapes. Without
+    #      path 2, a provider's activity feed looks frozen the moment
+    #      an 835 lands — the most common activity, invisible.
+    with db.SessionLocal()() as s:
+        claim_ids = [
+            cid
+            for (cid,) in s.query(Claim.id)
+            .filter(Claim.provider_npi == npi)
+            .all()
+        ]
+        activity_rows = []
+        if claim_ids:
+            activity_rows = (
+                s.query(db.ActivityEvent)
+                .outerjoin(
+                    Remittance,
+                    db.ActivityEvent.remittance_id == Remittance.id,
+                )
+                .filter(or_(
+                    db.ActivityEvent.claim_id.in_(claim_ids),
+                    Remittance.claim_id.in_(claim_ids),
+                ))
+                .order_by(desc(db.ActivityEvent.ts))
+                .limit(10)
+                .all()
+            )
+
+    def _activity_to_ui(a):
+        return {
+            "id": a.id,
+            "ts": a.ts.isoformat().replace("+00:00", "Z") if a.ts else "",
+            "kind": a.kind,
+            "batchId": a.batch_id,
+            "claimId": a.claim_id,
+            "remittanceId": a.remittance_id,
+            "payload": a.payload_json or {},
+        }
+
+    provider_dict["recent_claims"] = recent_claims
+    provider_dict["recent_activity"] = [_activity_to_ui(a) for a in activity_rows]
+    return provider_dict

backend/src/cyclone/api_routers/reconciliation.py

@@ -0,0 +1,178 @@
+"""Reconciliation read views + manual match/unmatch write paths.
+
+Four endpoints:
+
+- ``GET  /api/reconciliation/unmatched`` — list of unmatched Claims
+  and unmatched Remittances (``store.list_unmatched(kind="both")``).
+- ``GET  /api/batch-diff``             — side-by-side diff of two
+  batches (used by the Batch Diff page). Lazy-imports
+  :func:`cyclone.batch_diff.diff_batches_to_wire` to keep the
+  module's import surface small until the endpoint is actually
+  hit.
+- ``POST /api/reconciliation/match``   — manually pair a Claim with
+  a Remittance (``store.manual_match``). Surfaces ``AlreadyMatchedError`` /
+  ``InvalidStateError`` as 409, and ``LookupError`` from the store
+  as 404 (``claim_or_remit_not_found``).
+- ``POST /api/reconciliation/unmatch`` — unpair a Claim (``store.manual_unmatch``).
+  Surfaces ``NotMatchedError`` as 409.
+
+All four are read-or-manual-override surfaces used by the
+Reconciliation page (the page that pairs Claims with Remittances
+when neither side has an automatic match key).
+
+SP36 Task 8: this block moved here from ``api.py:2450`` (the
+4 routes interleaved with a side-by-side batch-diff divider).
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from cyclone.auth.deps import matrix_gate
+from cyclone.store import (
+    AlreadyMatchedError,
+    InvalidStateError,
+    store,
+)
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.get("/api/reconciliation/unmatched")
+def get_reconciliation_unmatched() -> dict:
+    """Return unmatched Claims (left) and unmatched Remittances (right).
+
+    Powers the reconciliation review surface: every Claim with no
+    paired Remittance appears on the left, every Remittance with no
+    paired Claim appears on the right. The two lists are always present
+    (empty list, never absent) so the UI can index unconditionally.
+    """
+    return store.list_unmatched(kind="both")
+
+
+# --------------------------------------------------------------------------- #
+# Side-by-side diff between two batches (SP3 P4 / T18)
+# --------------------------------------------------------------------------- #
+
+
+@router.get("/api/batch-diff")
+def get_batch_diff(
+    a: str | None = Query(None),
+    b: str | None = Query(None),
+) -> dict:
+    """Return a side-by-side diff of two batches identified by id.
+
+    Query params: ``a=<batch_id>``, ``b=<batch_id>`` (both required).
+
+    Response body (snake_case keys, see :mod:`cyclone.batch_diff` for the
+    projector shapes):
+      - ``a`` / ``b`` — small metadata blocks (id, kind, parsedAt,
+        inputFilename, claimCount)
+      - ``added`` — claims present in B but not A
+      - ``removed`` — claims present in A but not B
+      - ``changed`` — claims present in both, with field deltas
+      - ``summary`` — precomputed counts
+
+    Errors:
+      - 400 — missing ``a`` or ``b``
+      - 404 — either batch id is unknown
+
+    Pure read endpoint — never mutates the store. Both 837P and 835
+    batches are accepted (mixed-kind diffs are valid: comparing the
+    submitted claims against the matching remittances).
+    """
+    if not a or not b:
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "Missing param", "detail": "Both ?a=<batch_id> and ?b=<batch_id> are required."},
+        )
+    try:
+        a_rec, b_rec = store.load_two_for_diff(a, b)
+    except LookupError as exc:
+        raise HTTPException(
+            status_code=404,
+            detail={"error": "Not found", "detail": str(exc)},
+        )
+
+    # Lazy import — keeps the module's import surface small until the
+    # endpoint is actually hit. Mirrors the same pattern used by other
+    # endpoint-local helpers (e.g. reconciler).
+    from cyclone.batch_diff import diff_batches_to_wire
+
+    return diff_batches_to_wire(a_rec, b_rec)
+
+
+@router.post("/api/reconciliation/match")
+def post_reconciliation_match(body: dict) -> dict:
+    """Manually pair a Claim with a Remittance (operator override).
+
+    Body: ``{"claim_id": ..., "remit_id": ...}``. Returns
+    ``{"claim": <ui>, "match": <ui>}`` on success. Errors:
+      - 400: missing ``claim_id`` or ``remit_id``
+      - 404: claim or remittance not found
+      - 409: claim already matched, or apply_* returned a noop
+        (claim in terminal state) — detail echoes ``current_state``
+        and ``activity_kind`` so the UI can render a precise message.
+    """
+    claim_id = body.get("claim_id")
+    remit_id = body.get("remit_id")
+    if not claim_id or not remit_id:
+        raise HTTPException(
+            status_code=400,
+            detail="claim_id and remit_id required",
+        )
+    try:
+        return store.manual_match(claim_id, remit_id)
+    except AlreadyMatchedError as e:
+        raise HTTPException(
+            status_code=409,
+            detail={"error": "already_matched", "message": str(e)},
+        )
+    except InvalidStateError as e:
+        raise HTTPException(
+            status_code=409,
+            detail={
+                "error": "invalid_state",
+                "current_state": e.current_state,
+                "activity_kind": e.activity_kind,
+            },
+        )
+    except LookupError:
+        # manual_match raises LookupError when the claim or remittance
+        # row is missing (we catch the parent class so any future
+        # KeyError subclasses in the store get the same treatment).
+        raise HTTPException(
+            status_code=404,
+            detail="claim_or_remit_not_found",
+        )
+
+
+@router.post("/api/reconciliation/unmatch")
+def post_reconciliation_unmatch(body: dict) -> dict:
+    """Remove the current match for a Claim; reset Claim to submitted.
+
+    Body: ``{"claim_id": ...}``. Returns
+    ``{"claim": <ui>, "deletedMatches": <count>}``. Errors:
+      - 400: missing ``claim_id``
+      - 404: claim not found
+      - 409: claim has no current match (NotMatchedError is mapped
+        by the store; we surface 409 to match the manual_match contract)
+    """
+    from cyclone.store import NotMatchedError
+    claim_id = body.get("claim_id")
+    if not claim_id:
+        raise HTTPException(
+            status_code=400,
+            detail="claim_id required",
+        )
+    try:
+        return store.manual_unmatch(claim_id)
+    except NotMatchedError as e:
+        raise HTTPException(
+            status_code=409,
+            detail={"error": "not_matched", "message": str(e)},
+        )
+    except LookupError:
+        raise HTTPException(
+            status_code=404,
+            detail="claim_not_found",
+        )

backend/src/cyclone/api_routers/remittances.py

@@ -0,0 +1,169 @@
+"""``/api/remittances`` and ``/api/remittances/stream`` — read views over the Remittance population.
+
+Four endpoints, all gated by ``matrix_gate``:
+
+- ``GET /api/remittances``                — paginated list with filter+sort,
+  plus an NDJSON variant when the caller sends ``Accept: application/x-ndjson``.
+- ``GET /api/remittances/summary``        — server-aggregated KPI tiles
+  (``count``, ``total_paid``, ``total_adjustments``) over the full
+  filtered population — never a page-limited sample (SP27 fix).
+- ``GET /api/remittances/stream``         — NDJSON live-tail: snapshot
+  of currently-known rows, then ``remittance_written`` events as
+  they hit the store. Subscribed to by the Remittances page.
+- ``GET /api/remittances/{remittance_id}`` — one remittance with its
+  labeled CAS ``adjustments`` array. 404 on missing id (never 500).
+
+``/api/remittances/stream`` is registered before
+``/api/remittances/{remittance_id}`` so the literal ``stream`` path
+segment is not captured as a remittance id.
+
+SP36 Task 9: this block moved here from ``api.py:2448`` (the 4
+``/api/remittances*`` routes, with the streaming route's
+``NOTE: registered before…`` comment preserved verbatim).
+"""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi.responses import StreamingResponse
+
+from cyclone.api_helpers import (
+    ndjson_line as _ndjson_line,
+    ndjson_stream_list as _ndjson_stream_list,
+    tail_events as _tail_events,
+    wants_ndjson as _wants_ndjson,
+)
+from cyclone.auth.deps import matrix_gate
+from cyclone.pubsub import EventBus
+from cyclone.store import store
+
+router = APIRouter(dependencies=[Depends(matrix_gate)])
+
+
+@router.get("/api/remittances")
+def list_remittances(
+    request: Request,
+    batch_id: str | None = Query(None),
+    payer: str | None = Query(None),
+    claim_id: str | None = Query(None),
+    date_from: str | None = Query(None),
+    date_to: str | None = Query(None),
+    sort: str | None = Query(None),
+    order: str = Query("desc"),
+    limit: int = Query(100, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+) -> Any:
+    common = dict(
+        batch_id=batch_id,
+        payer=payer,
+        claim_id=claim_id,
+        date_from=date_from,
+        date_to=date_to,
+    )
+    items = list(store.iter_remittances(
+        sort=sort, order=order, limit=limit, offset=offset, **common,
+    ))
+    # SP27 Task 13b: count the full population, not a 100-row sample.
+    # See the matching note in list_claims — same silent-failure pattern.
+    total = store.count_remittances(**common)
+    returned = len(items)
+    has_more = total > offset + returned
+    if _wants_ndjson(request):
+        return StreamingResponse(
+            _ndjson_stream_list(items, total, returned, has_more),
+            media_type="application/x-ndjson",
+        )
+    return {
+        "items": items,
+        "total": total,
+        "returned": returned,
+        "has_more": has_more,
+    }
+
+
+@router.get("/api/remittances/summary")
+def remittances_summary(
+    batch_id: str | None = Query(None),
+    payer: str | None = Query(None),
+    claim_id: str | None = Query(None),
+    date_from: str | None = Query(None),
+    date_to: str | None = Query(None),
+) -> dict:
+    """Server-aggregated KPI tiles for the Remittances page.
+
+    Returns ``{count, total_paid, total_adjustments}`` over the
+    full filtered remittance population — NOT a page-limited
+    sample. The Remittances page consumes this for its "Total paid"
+    and "Adjustments" tiles so they can't silently understate the
+    true DB population the way a page-local ``items.reduce(...)``
+    would. Mirrors the silent-incompleteness fix that
+    ``/api/dashboard/kpis`` (commit ``59c3275``) and
+    ``/api/remittances`` (commit ``d81b6ed``) made for their tiles.
+
+    Same filter parameters as ``/api/remittances``. Always returns
+    a populated dict (``{"count": 0, "total_paid": 0,
+    "total_adjustments": 0}`` when no rows match) so the frontend
+    can render the tiles directly without a loading-vs-empty
+    branch.
+    """
+    return store.summarize_remittances(
+        batch_id=batch_id, payer=payer, claim_id=claim_id,
+        date_from=date_from, date_to=date_to,
+    )
+
+
+@router.get("/api/remittances/stream")
+async def remittances_stream(
+    request: Request,
+    payer: str | None = Query(None),
+    claim_id: str | None = Query(None),
+    date_from: str | None = Query(None),
+    date_to: str | None = Query(None),
+    sort: str | None = Query(None),
+    order: str = Query("desc"),
+    limit: int = Query(100, ge=1, le=1000),
+) -> StreamingResponse:
+    """Stream Remittances as NDJSON: snapshot first, then live events.
+
+    Subscribes to ``remittance_written``. Default sort is
+    ``-received_date`` (newest-first), matching the list endpoint's
+    most common sort.
+
+    NOTE: registered before ``/api/remittances/{remittance_id}`` so
+    the literal ``stream`` path segment doesn't get matched as a
+    remittance id.
+    """
+    bus: EventBus = request.app.state.event_bus
+
+    async def gen() -> AsyncIterator[bytes]:
+        rows = store.iter_remittances(
+            payer=payer, claim_id=claim_id,
+            date_from=date_from, date_to=date_to,
+            sort=sort or "-received_date", order=order, limit=limit,
+        )
+        for row in rows:
+            yield _ndjson_line({"type": "item", "data": row})
+        yield _ndjson_line({"type": "snapshot_end", "data": {"count": len(rows)}})
+
+        async for chunk in _tail_events(request, bus, ["remittance_written"]):
+            yield chunk
+
+    return StreamingResponse(gen(), media_type="application/x-ndjson")
+
+
+@router.get("/api/remittances/{remittance_id}")
+def get_remittance(remittance_id: str) -> dict:
+    """Return one remittance with its labeled CAS ``adjustments`` array.
+
+    Path param is ``remittance_id`` (not ``id``) to avoid shadowing
+    FastAPI's internal ``id`` name and to keep OpenAPI docs self-
+    describing. Returns 404 when the remittance is missing — never 500.
+    """
+    body = store.get_remittance(remittance_id)
+    if body is None:
+        raise HTTPException(
+            status_code=404,
+            detail={"error": "Not found", "detail": f"Remittance {remittance_id} not found"},
+        )
+    return body

backend/src/cyclone/api_routers/submission.py

@@ -0,0 +1,186 @@
+"""SP37 Task 6: HTTP endpoint for the canonical submit-batch flow.
+
+Thin wrapper around ``cyclone.submission.submit_file`` — same logic as
+the ``cyclone submit-batch`` CLI (SP37 Task 5), just framed as JSON in
+/ JSON out and gated by ``matrix_gate``. The walker pattern, ``._*``
+AppleDouble skip, ``limit`` semantics, and per-file outcomes all match
+the CLI byte-for-byte so a batch run via the CLI and the same batch
+run via this endpoint produce identical DB + SFTP state.
+
+The endpoint deliberately does NOT inject an ``sftp_client_factory``:
+``submit_file`` defaults to its paramiko-based factory so SKIPPED is
+reachable in production (the ``SftpClient`` wrapper has no ``stat()``).
+Tests monkey-patch ``cyclone.api_routers.submission.submit_file``
+itself; that avoids the paramiko factory entirely without touching
+the helper's contract.
+
+Status code contract (per Task 6 spec §4):
+  - 200: completed run. Per-file failures live in the JSON body.
+  - 401: not authenticated (matrix_gate).
+  - 404: no clearhouse seeded (config-level "missing" → 4xx, not 5xx).
+  - 409: clearhouse SFTP block is in stub mode (refuses to upload).
+  - 422: ``ingest_dir`` missing on disk OR Pydantic body validation
+    failed (missing fields, wrong types).
+  - 5xx: truly unexpected exceptions propagate (do not swallow).
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, ConfigDict, Field
+
+from cyclone.auth.deps import matrix_gate
+from cyclone.store import store as cycl_store
+from cyclone.submission.core import submit_file
+from cyclone.submission.result import SubmitOutcome, SubmitResult
+
+log = logging.getLogger(__name__)
+
+# No `prefix=` here — every other gated router in this package declares
+# the full path in the decorator (clearhouse.py uses "/api/clearhouse",
+# parse.py uses "/api/parse-837", etc.). The decorator sets the full URL.
+router = APIRouter(
+    tags=["submission"],
+    dependencies=[Depends(matrix_gate)],
+)
+
+
+class SubmitBatchRequest(BaseModel):
+    """Body schema for ``POST /api/submit-batch``.
+
+    ``ingest_dir`` has no default so Pydantic raises 422 when it's
+    missing — better UX than letting the walker crash on a missing
+    path. ``validate_files`` and ``actor`` default so a minimal client
+    can skip them. ``limit`` truncates the file list after the walker
+    collects it (mirrors the CLI's post-collection ``if i > limit:
+    break`` semantics, but applied as a slice since the HTTP body
+    model is type-checked up-front).
+
+    The ``validate_files`` field is aliased to ``validate`` in the JSON
+    body to mirror the CLI's ``--validate`` flag and avoid the
+    hardcoded Pydantic warning about ``validate`` shadowing
+    ``BaseModel.validate``. ``populate_by_name=True`` lets tests
+    construct the model with either key.
+    """
+    model_config = ConfigDict(populate_by_name=True, protected_namespaces=())
+
+    ingest_dir: str
+    validate_files: bool = Field(default=True, alias="validate")
+    actor: str = "api-submit-batch"
+    limit: int | None = None
+
+
+@router.post("/api/submit-batch")
+def submit_batch(body: SubmitBatchRequest):
+    """Submit every ``batch-*-claims/*.x12`` under ``ingest_dir``.
+
+    Walks ``ingest_dir`` for any directory matching ``batch-*-claims``,
+    collects each one's ``*.x12`` files (sorted, with ``._*``
+    AppleDouble files skipped), truncates to ``limit`` if set, then
+    calls :func:`cyclone.submission.submit_file` per file with the
+    seeded clearhouse's ``sftp_block`` and ``actor`` from the body.
+
+    Returns counts (``submitted`` / ``skipped`` / ``failed``) plus a
+    per-file ``results`` array. Per-file failures NEVER change the
+    HTTP status code — the response is 200 whenever the run itself
+    completed.
+    """
+
+    # 1. Config-level guards. Order matters: a missing clearhouse is a
+    #    404 (config-level "missing"), but if it IS present and in stub
+    #    mode the operator's request is a 409 (configured-but-wrong).
+    clearhouse = cycl_store.get_clearhouse()
+    if clearhouse is None:
+        raise HTTPException(
+            status_code=404, detail="no clearhouse seeded",
+        )
+    sftp_block = clearhouse.sftp_block
+    if sftp_block.stub:
+        raise HTTPException(
+            status_code=409, detail="clearhouse SFTP block is in stub mode",
+        )
+
+    # 2. Resolve + validate the ingest dir. Use ``resolve()`` so a
+    #    symlink-relative path still produces a stable error message.
+    root = Path(body.ingest_dir).resolve()
+    if not root.exists():
+        raise HTTPException(
+            status_code=422,
+            detail=f"ingest_dir does not exist: {root}",
+        )
+
+    # 3. Walker — must match the CLI EXACTLY. Same sort, same ``._*``
+    #    AppleDouble skip. Any drift here is a quiet split between the
+    #    two surfaces and silently produces different batch outcomes.
+    files: list[Path] = []
+    for batch_dir in sorted(root.glob("batch-*-claims")):
+        files.extend(sorted(
+            p for p in batch_dir.glob("*.x12")
+            if not p.name.startswith("._")
+        ))
+
+    # 4. ``limit`` truncates after collection. The CLI uses an inline
+    #    ``if i > limit: break``; we slice instead because the HTTP
+    #    body model validates ``limit`` up-front (Pydantic-level int
+    #    check) and slicing keeps the walker branchless.
+    if body.limit is not None:
+        files = files[: body.limit]
+
+    if not files:
+        raise HTTPException(
+            status_code=422,
+            detail=f"no batch-*-claims/*.x12 files found under {root}",
+        )
+
+    # 5. Per-file submit. Wrap the helper call in try/except so an
+    #    unexpected exception in submit_file surfaces as a per-file
+    #    failure (outcome="unexpected") instead of crashing the whole
+    #    run. The helper's own SubmitOutcome enum covers every typed
+    #    failure path; an uncaught exception here is a true
+    #    surprise (bug or service outage mid-loop).
+    results: list[dict] = []
+    submitted = skipped = failed = 0
+    for src in files:
+        try:
+            r = submit_file(
+                src,
+                sftp_block=sftp_block,
+                actor=body.actor,
+                validate=body.validate_files,
+                # No ``sftp_client_factory`` — submit_file's default
+                # paramiko factory opens the real MFT. Tests
+                # monkey-patch submit_file itself instead of wiring a
+                # factory here.
+            )
+        except Exception as exc:  # noqa: BLE001
+            log.exception(
+                "submit-batch unexpected error on %s", src.name,
+            )
+            r = SubmitResult(
+                file=src.name,
+                outcome=SubmitOutcome.UNEXPECTED_ERROR,
+                error=f"{exc.__class__.__name__}: {exc}",
+            )
+
+        if r.outcome == SubmitOutcome.SUBMITTED:
+            submitted += 1
+        elif r.outcome == SubmitOutcome.SKIPPED:
+            skipped += 1
+        else:
+            failed += 1
+
+        results.append({
+            "file": r.file,
+            "outcome": r.outcome.value,
+            "batch_id": r.batch_id,
+            "error": r.error,
+        })
+
+    return {
+        "submitted": submitted,
+        "skipped": skipped,
+        "failed": failed,
+        "results": results,
+    }

backend/src/cyclone/api_routers/ta1_acks.py

@@ -16,15 +16,16 @@ from __future__ import annotations
 
 from typing import Any, AsyncIterator
 
-from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from fastapi.responses import StreamingResponse
 
 from cyclone.api_helpers import ndjson_line, tail_events
+from cyclone.auth.deps import matrix_gate
 from cyclone import db
 from cyclone.pubsub import EventBus
 from cyclone.store import store, to_ui_ta1_ack
 
-router = APIRouter()
+router = APIRouter(dependencies=[Depends(matrix_gate)])
 
 
 # SP25: ``_ta1_to_ui`` moved to ``cyclone.store.ui.to_ui_ta1_ack`` so

backend/src/cyclone/auth/permissions.py

@@ -38,11 +38,11 @@ PERMISSIONS: dict[tuple[str, str], set[Role]] = {
     ("GET", "/api/remittances"): ALL_ROLES,
     ("GET", "/api/providers"): ALL_ROLES,
     ("GET", "/api/batches"): ALL_ROLES,
-    ("GET", "/api/dashboard/summary"): ALL_ROLES,
+    ("GET", "/api/dashboard/kpis"): ALL_ROLES,  # dashboard summary cards (renamed from /summary)
     ("GET", "/api/activity"): ALL_ROLES,
     ("GET", "/api/inbox/lanes"): ALL_ROLES,
     ("GET", "/api/inbox/export.csv"): ALL_ROLES,
-    ("GET", "/api/reconcile"): ALL_ROLES,
+    ("GET", "/api/inbox/ack-orphans"): ALL_ROLES,  # Inbox "Ack orphans" lane — wired in src/hooks/useAckOrphans.ts
     ("GET", "/api/reconciliation"): ALL_ROLES,
     ("GET", "/api/acks"): ALL_ROLES,
     ("GET", "/api/ta1-acks"): ALL_ROLES,
@@ -50,7 +50,6 @@ PERMISSIONS: dict[tuple[str, str], set[Role]] = {
     ("GET", "/api/batch-diff"): ALL_ROLES,
     ("GET", "/api/config"): ALL_ROLES,
     ("GET", "/api/payers"): ALL_ROLES,
-    ("GET", "/api/audit-log"): ADMIN_ONLY,
 
     # Clearhouse (SFTP creds + dzinesco identity) — admin only.
     ("GET", "/api/clearhouse"): ADMIN_ONLY,
@@ -60,12 +59,12 @@ PERMISSIONS: dict[tuple[str, str], set[Role]] = {
     # Admin ops (audit log, backup, scheduler, db rotate, reload-config).
     ("GET", "/api/admin/audit-log"): ADMIN_ONLY,
     ("GET", "/api/admin/audit-log/verify"): ADMIN_ONLY,
-    ("GET", "/api/admin/backup"): ADMIN_ONLY,
-    ("POST", "/api/admin/backup"): ADMIN_ONLY,
-    ("GET", "/api/admin/backup/scheduler"): ADMIN_ONLY,
-    ("POST", "/api/admin/backup/scheduler"): ADMIN_ONLY,
-    ("GET", "/api/admin/scheduler"): ADMIN_ONLY,
-    ("POST", "/api/admin/scheduler"): ADMIN_ONLY,
+    ("GET", "/api/admin/backup"): ADMIN_ONLY,  # prefix; covers /list, /status, /{id}/restore/*, /{id}/verify
+    ("POST", "/api/admin/backup"): ADMIN_ONLY,  # prefix; covers /create, /prune, /{id}/restore/*
+    ("GET", "/api/admin/backup/scheduler"): ADMIN_ONLY,  # prefix; covers /start, /stop, /tick
+    ("POST", "/api/admin/backup/scheduler"): ADMIN_ONLY,  # prefix; covers /start, /stop, /tick
+    ("GET", "/api/admin/scheduler"): ADMIN_ONLY,  # prefix; covers /status, /processed-files
+    ("POST", "/api/admin/scheduler"): ADMIN_ONLY,  # prefix; covers /start, /stop, /tick, /pull-inbound
     ("POST", "/api/admin/db/rotate-key"): ADMIN_ONLY,
     ("POST", "/api/admin/reload-config"): ADMIN_ONLY,
     ("GET", "/api/admin/validate-provider"): ADMIN_ONLY,
@@ -80,15 +79,15 @@ PERMISSIONS: dict[tuple[str, str], set[Role]] = {
     ("POST", "/api/inbox/candidates"): WRITE_ROLES,
     ("POST", "/api/inbox/rejected"): WRITE_ROLES,
     ("POST", "/api/inbox/payer-rejected"): WRITE_ROLES,
-    ("POST", "/api/reconcile"): WRITE_ROLES,
     ("POST", "/api/reconciliation"): WRITE_ROLES,
-    ("POST", "/api/resubmit"): WRITE_ROLES,
     ("POST", "/api/acks"): WRITE_ROLES,
+    # Unlink a wrong claim-ack match — inverse of POST /api/inbox/candidates/{remit_id}/match.
+    # Prefix (not the placeholder path) because the matcher treats {kind}
+    # as a literal substring; only ``/api/acks`` actually matches real requests.
+    ("DELETE", "/api/acks"): WRITE_ROLES,
     ("POST", "/api/batches"): WRITE_ROLES,  # /export-837 regenerates X12 from DB rows
     ("POST", "/api/eligibility"): WRITE_ROLES,
-
-    # CSV export — read-only.
-    ("GET", "/api/export.csv"): ALL_ROLES,
+    ("POST", "/api/submit-batch"): WRITE_ROLES,  # SP37: canonical outbound path (mirrors CLI)
 }
 
 

backend/src/cyclone/clearhouse/__init__.py

@@ -94,6 +94,22 @@ def _op_timeout_seconds() -> float:
     return value
 
 
+@dataclass(frozen=True)
+class SftpStat:
+    """File metadata returned by :meth:`SftpClient.stat`.
+
+    Mirrors the subset of paramiko's ``SFTPAttributes`` that callers
+    actually need (``size``, ``modified_at``). Keeping the surface
+    narrow means callers don't need to import paramiko to consume
+    the result, and the wrapper's stub mode can populate it from a
+    plain ``os.stat_result`` without any paramiko dance.
+
+    Frozen so callers can hash / cache the result if they need to.
+    """
+    size: int
+    modified_at: datetime | None = None
+
+
 @dataclass
 class InboundFile:
     """A single file observed in the inbound MFT path."""
@@ -216,6 +232,30 @@ class SftpClient:
             return self._read_file_stub(remote_path)
         return self._read_file_paramiko(remote_path)
 
+    def stat(self, remote_path: str) -> SftpStat:
+        """Return file metadata for ``remote_path``.
+
+        Mirrors the subset of paramiko's ``SFTPAttributes`` that
+        callers need (``size`` for idempotency checks; ``modified_at``
+        for cache-busting). The SP37 submission helper uses
+        ``stat().size`` to short-circuit re-uploads of already-uploaded
+        files (the SKIPPED outcome path).
+
+        Stub mode: reads ``os.stat_result`` from
+        ``{staging_dir}/{remote_path}``.
+
+        Real mode: calls ``sftp.stat(remote_path)`` on a paramiko
+        connection.
+
+        Raises:
+            FileNotFoundError: if ``remote_path`` does not exist
+                (stub: missing local file; real: paramiko raises
+                ``IOError`` which is a ``FileNotFoundError`` subclass).
+        """
+        if self._stub:
+            return self._stat_stub(remote_path)
+        return self._stat_paramiko(remote_path)
+
     def _read_file_stub(self, remote_path: str) -> bytes:
         """Read bytes from ``{staging_dir}/{remote_path}`` (SP16 stub)."""
         staging = Path(self._block.staging_dir).resolve()
@@ -224,6 +264,25 @@ class SftpClient:
             raise FileNotFoundError(f"inbound stub file not found: {target}")
         return target.read_bytes()
 
+    def _stat_stub(self, remote_path: str) -> SftpStat:
+        """Return ``SftpStat`` for ``{staging_dir}/{remote_path}`` (SP37 stub).
+
+        Mirrors what paramiko's ``sftp.stat()`` returns in real mode:
+        ``size`` from ``st.st_size`` and ``modified_at`` from
+        ``st.st_mtime``. Raises ``FileNotFoundError`` if the local
+        file is missing — matches paramiko's ``IOError`` behavior
+        so the caller doesn't need to special-case stub mode.
+        """
+        staging = Path(self._block.staging_dir).resolve()
+        target = staging / remote_path.lstrip("/")
+        if not target.is_file():
+            raise FileNotFoundError(f"inbound stub file not found: {target}")
+        st = target.stat()
+        return SftpStat(
+            size=st.st_size,
+            modified_at=datetime.fromtimestamp(st.st_mtime),
+        )
+
     def get_secret(self, name: str) -> Optional[str]:
         """Fetch the auth secret from Keychain. Returns the stub secret if absent."""
         value = secrets.get_secret(name)
@@ -506,6 +565,20 @@ class SftpClient:
                 shutil.copyfileobj(f, buf, length=64 * 1024)
             return buf.getvalue()
 
+    def _stat_paramiko(self, remote_path: str) -> SftpStat:
+        """Return ``SftpStat`` for ``remote_path`` via paramiko.
+
+        Paramiko's ``SFTPAttributes`` already provides ``st_size`` and
+        ``st_mtime``; we project them into our narrow public
+        ``SftpStat`` shape so callers don't need to know about paramiko.
+        """
+        with self._connect() as (ssh, sftp):
+            attr = sftp.stat(remote_path)
+            return SftpStat(
+                size=attr.st_size or 0,
+                modified_at=datetime.fromtimestamp(attr.st_mtime or 0),
+            )
+
 
 # ---------------------------------------------------------------------------
 # Module-level helper

backend/src/cyclone/cli.py

@@ -768,6 +768,99 @@ def resubmit_rejected_claims(
     )
 
 
+@main.command("submit-batch")
+@click.option("--ingest-dir", default="ingest",
+              show_default=True,
+              help="Root dir holding batch-*-claims/ subfolders of .x12 files.")
+@click.option("--actor", default="cli-submit-batch",
+              show_default=True,
+              help="Audit-log actor tag for the clearhouse.submitted events.")
+@click.option("--validate/--no-validate", default=True,
+              help="Parse each file via parse_837 before upload.")
+@click.option("--limit", type=int, default=None,
+              help="Stop after N files (smoke-tests).")
+def submit_batch(
+    ingest_dir: str,
+    actor: str,
+    validate: bool,
+    limit: int | None,
+) -> None:
+    """Parse → DB-write → SFTP-upload each batch-*-claims/*.x12 (SP37).
+
+    Canonical outbound path. Mirrors ``resubmit-rejected-claims`` but
+    routes through ``cyclone.submission.submit_file``, which writes to
+    the DB before uploading. Use this as the preferred outbound path;
+    ``resubmit-rejected-claims`` remains for one-off cases where you
+    don't want a DB row (dzinesco-generated fixes not ready for
+    canonical tracking).
+
+    Exit codes: 0 = run completed (even with per-file failures), 1 =
+    unexpected exception, 2 = config-level failure (no clearhouse,
+    SFTP block in stub mode, ingest-dir missing).
+    """
+    from cyclone import db as db_mod
+    from cyclone.submission.core import submit_file
+    from cyclone.submission.result import SubmitOutcome
+    from cyclone.store import store as cycl_store
+
+    db_mod.init_db()
+    cycl_store.ensure_clearhouse_seeded()
+    clearhouse = cycl_store.get_clearhouse()
+    if clearhouse is None:
+        click.echo("No clearhouse seeded; cannot resolve SFTP block.", err=True)
+        sys.exit(2)
+    sftp_block = clearhouse.sftp_block
+    if sftp_block.stub:
+        click.echo("Clearhouse SFTP block is in stub mode; refusing to upload.", err=True)
+        sys.exit(2)
+
+    root = Path(ingest_dir).resolve()
+    if not root.exists():
+        click.echo(f"--ingest-dir does not exist: {root}", err=True)
+        sys.exit(2)
+
+    files: list[Path] = []
+    for batch_dir in sorted(root.glob("batch-*-claims")):
+        files.extend(sorted(p for p in batch_dir.glob("*.x12")
+                            if not p.name.startswith("._")))
+    if not files:
+        click.echo(f"No .x12 files under {root}", err=True)
+        sys.exit(2)
+
+    click.echo(f"found {len(files)} files under {root}")
+
+    submitted = 0
+    skipped = 0
+    failed = 0
+    for i, src in enumerate(files, 1):
+        if limit is not None and i > limit:
+            break
+        try:
+            result = submit_file(
+                src, sftp_block=sftp_block, actor=actor, validate=validate,
+            )
+        except Exception as exc:  # noqa: BLE001
+            click.echo(f"UNEXPECTED  {src.name}: {exc.__class__.__name__}: {exc}", err=True)
+            failed += 1
+            continue
+        if result.outcome == SubmitOutcome.SUBMITTED:
+            submitted += 1
+            click.echo(f"submitted  {src.name}  batch={result.batch_id}")
+        elif result.outcome == SubmitOutcome.SKIPPED:
+            skipped += 1
+            click.echo(f"skipped    {src.name}  (already uploaded)")
+        else:
+            failed += 1
+            click.echo(
+                f"{result.outcome.value:<10}  {src.name}  {result.error or ''}",
+                err=True,
+            )
+
+    click.echo(f"\nsummary: submitted={submitted} skipped={skipped} failed={failed}")
+    # Per-file failures don't bump exit code; details in stdout.
+    # (Per cyclone-cli convention.)
+
+
 @main.group()
 def backup() -> None:
     """Encrypted DB backup management (SP17)."""
@@ -1191,5 +1284,97 @@ def pull_inbound(
             click.echo(f"  {e}", err=True)
 
 
+# ---------------------------------------------------------------------------
+# SP38: ack-orphans status + reconcile
+# ---------------------------------------------------------------------------
+
+
+@main.group("ack-orphans")
+def ack_orphans_group() -> None:
+    """Inspect and reconcile 999 acks with no resolvable source claim.
+
+    "Orphans" are 999 acks whose source 837 batch is not present in
+    the ``batches`` table — typically because the source 837 was
+    submitted to HPE before the current ``cyclone.db`` snapshot was
+    created. They are real production data (valid audit history) but
+    cannot be auto-linked to claims.
+
+    See ``docs/superpowers/specs/2026-07-07-cyclone-orphan-ack-housekeeping-design.md``
+    for the full design and operator triage workflow.
+    """
+
+
+@ack_orphans_group.command("status")
+def ack_orphans_status_cmd() -> None:
+    """Print a per-ST02 summary of orphan 999 acks.
+
+    One row per distinct orphan ``set_control_number`` (ST02), ranked
+    by ``ack_count DESC`` so the heaviest backlog surfaces first.
+    Plus a TOTAL row at the bottom.
+
+    Exit codes: 0 on success, 1 on DB error.
+    """
+    from cyclone import db as db_mod
+    from cyclone.store import store as cycl_store
+
+    try:
+        db_mod.init_db()
+        summary = cycl_store.find_ack_orphan_st02_summary()
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"ack-orphans status failed: {type(exc).__name__}: {exc}", err=True)
+        sys.exit(1)
+
+    if not summary:
+        click.echo("no orphans (acks is empty or all are linked)")
+        return
+
+    # Table layout: ST02 | ACK COUNT | HAS BATCH
+    click.echo(f"{'ST02':<15} {'ACK COUNT':>10}   HAS BATCH")
+    click.echo(f"{'----':-<15} {'---------':->10}   ---------")
+    total = 0
+    for row in summary:
+        marker = "yes" if row["has_batch"] else "no"
+        click.echo(
+            f"{row['st02']:<15} {row['ack_count']:>10}   {marker}"
+        )
+        total += row["ack_count"]
+    click.echo(f"{'TOTAL':<15} {total:>10}")
+
+
+@ack_orphans_group.command("reconcile")
+@click.option("--dry-run", is_flag=True,
+              help="Print the plan but do not insert any rows.")
+def ack_orphans_reconcile_cmd(dry_run: bool) -> None:
+    """Insert synthetic batches rows for orphan ST02s that lack one.
+
+    For every orphan ST02 where no ``batches`` row exists, insert a
+    synthetic row marked with ``input_filename =
+    '<synthetic:orphan-reconcile>'`` so future 999 acks for the same
+    ST02s can resolve against the ``batch_envelope_index`` (though
+    they still won't link to claims — the source 837s were never
+    ingested).
+
+    Idempotent: re-running after a successful pass is a no-op.
+
+    Exit codes: 0 on success, 1 on DB error.
+    """
+    from cyclone import db as db_mod
+    from cyclone.store import store as cycl_store
+
+    try:
+        db_mod.init_db()
+        plan = cycl_store.reconcile_orphan_st02s(dry_run=dry_run)
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"ack-orphans reconcile failed: {type(exc).__name__}: {exc}", err=True)
+        sys.exit(1)
+
+    click.echo(
+        f"Created: {plan['created']} synthetic batch rows. "
+        f"Skipped: {plan['skipped']} (already had a batch row)."
+    )
+    if dry_run:
+        click.echo("(dry-run — no rows inserted)")
+
+
 if __name__ == "__main__":
     main()

backend/src/cyclone/db.py

@@ -221,6 +221,13 @@ class Batch(Base):
     totals_json: Mapped[Optional[dict]] = mapped_column(JSONText, nullable=True)
     validation_json: Mapped[Optional[dict]] = mapped_column(JSONText, nullable=True)
     raw_result_json: Mapped[Optional[dict]] = mapped_column(JSONText, nullable=True)
+    # SP37 Task 2: source 837's ST02 (transaction set control number).
+    # Populated from ``Envelope.transaction_set_control_number`` by
+    # ``store.write.add_record`` for 837P batches; NULL for 835 batches
+    # (the column is an 837P-specific join key for 999 AK2 resolution).
+    # Migration 0020 adds the column additively; no backfill required for
+    # pre-existing rows that lack the value.
+    transaction_set_control_number: Mapped[Optional[str]] = mapped_column(String(32), nullable=True)
 
     claims: Mapped[list["Claim"]] = relationship(
         back_populates="batch", cascade="all, delete-orphan"

backend/src/cyclone/handlers/handle_835.py

@@ -66,10 +66,12 @@ def handle(
     here was dead code anyway (the 835 event name is
     ``remittance_written``, not ``ack_received``).
     """
-    # TODO(sp27-pre-t5): move PAYER_FACTORIES_835 out of api.py into
-    # ``cyclone.payers`` to remove the lazy cyclic import below. The
-    # import works today because api.py also imports scheduler lazily.
-    from cyclone.api import PAYER_FACTORIES_835
+    # SP36 Task 16: PAYER_FACTORIES_835 moved from ``cyclone.api``
+    # to ``cyclone.api_routers._shared`` (cross-router helper). Import
+    # from the new home. The lazy import is still needed to avoid a
+    # circular import at registry load time (handle_835 is imported
+    # by the scheduler during the api lifespan).
+    from cyclone.api_routers._shared import PAYER_FACTORIES_835
 
     config = PAYER_FACTORIES_835["co_medicaid_835"]()
     try:

backend/src/cyclone/migrations/0020_add_batch_txn_set_control_number.sql

@@ -0,0 +1,27 @@
+-- version: 20
+-- SP37: Batch.transaction_set_control_number = parsed 837's ST02.
+--
+-- Today's 999 ack join (claim_acks.batch_envelope_index, Pass 1) matches
+-- on ``Batch.envelope.control_number == 999's set_control_number``. That
+-- never resolves in production because 999's set_control_number (AK201)
+-- echoes the source 837's ST02 (transaction set control number), not the
+-- ISA13 (interchange control number) that Envelope.control_number stores.
+-- Result: every AK2 set-response against a dzinesco-generated 837 turns
+-- into an orphan.
+--
+-- SP37 fixes this by adding a column populated from the parsed 837's
+-- ST02 on every ``add_record`` write, then updating Pass 1 to match on
+-- it (Task 2). This migration is the additive part: nullable, no
+-- default, backfills from ``raw_result_json.envelope.transaction_set_control_number``
+-- for any pre-existing batch rows that already carry the value.
+--
+-- No new index (column is a primary join key, not a range query; the
+-- existing batches table is small enough for a full scan during the
+-- 999 join — see SP37 §"Migration 0013").
+
+ALTER TABLE batches ADD COLUMN transaction_set_control_number TEXT;
+
+UPDATE batches
+SET transaction_set_control_number = json_extract(raw_result_json, '$.envelope.transaction_set_control_number')
+WHERE raw_result_json IS NOT NULL
+  AND json_extract(raw_result_json, '$.envelope.transaction_set_control_number') IS NOT NULL;

backend/src/cyclone/parsers/models.py

@@ -120,6 +120,13 @@ class Envelope(_Base):
     implementation_guide: str | None = None
     # SP3 P1 T2: BHT06 transaction type code (was: transaction_set_purpose_code, which is BHT02).
     transaction_type_code: str | None = None
+    # SP37 Task 2: X12 ST02 (transaction set control number). Distinct
+    # from ``control_number`` above, which is the ISA13 interchange
+    # control number. 999 acks echo ST02 back as AK201, so this is the
+    # join key that lets ``add_record``'s batch row round-trip back to
+    # its source 837. Populated only by the 837P parser today; other
+    # parsers share this class but leave the field None.
+    transaction_set_control_number: str | None = None
 
 
 class BatchSummary(_Base):

backend/src/cyclone/parsers/parse_837.py

@@ -83,6 +83,12 @@ def _build_envelope(segments: list[list[str]], input_file: str = "") -> tuple[En
             except (IndexError, ValueError) as exc:
                 log.warning("Could not parse BHT date: %s", exc)
         elif seg[0] == "ST" and envelope is not None:
+            # SP37 Task 2: capture ST02 (transaction set control number).
+            # 999 acks echo this back as AK201, so this is what makes the
+            # batch row joinable once the 999 ingests. Distinct from ISA13
+            # (which is already on ``control_number``).
+            if len(seg) > 2:
+                envelope = envelope.model_copy(update={"transaction_set_control_number": seg[2].strip()})
             if len(seg) > 3:
                 envelope = envelope.model_copy(update={"implementation_guide": seg[3]})
     return envelope, summary

backend/src/cyclone/store/__init__.py

@@ -38,7 +38,9 @@ Backward-compat shims for tests:
 
 from __future__ import annotations
 
+import json
 import threading
+import uuid
 from datetime import datetime, timezone
 
 
@@ -87,6 +89,7 @@ from .claim_acks import (
     list_acks_for_claim as _list_acks_for_claim,
     list_claims_for_ack as _list_claims_for_ack,
     remove_claim_ack as _remove_claim_ack,
+    _iter_orphan_999_st02s as _iter_orphan_999_st02s,
 )
 from .backups import add_backup_pending
 from .exceptions import AlreadyMatchedError, InvalidStateError, NotMatchedError
@@ -320,12 +323,167 @@ class CycloneStore:
         """Return acks with no resolvable link (Inbox ack-orphans lane)."""
         return _find_ack_orphans(kind)
 
+    def find_ack_orphan_st02_summary(self):
+        """Return per-ST02 summary of orphan 999 acks (sp38).
+
+        Output is a list of dicts, sorted by ``ack_count DESC`` so
+        the heaviest orphan ST02s surface first in CLI output:
+
+          ``{"st02": str, "ack_count": int, "has_batch": bool,
+             "batch_id": str | None}``
+
+        ``has_batch`` is True if a row exists in ``batches`` with
+        ``transaction_set_control_number == st02``. ``batch_id`` is
+        that row's ``id`` (or ``None``).
+
+        999-only. 277ca / ta1 orphans are tracked separately; their
+        "ST02" semantics differ (it's the interchange control number,
+        not the source 837's ST02) and aggregating them with 999
+        ST02s would conflate unrelated identifiers.
+
+        Used by the ``cyclone ack-orphans status`` and ``reconcile``
+        CLI subcommands (sp38). Sibling to ``find_ack_orphans(kind)``
+        which returns one row per orphan ack; the summary is the
+        aggregated form.
+        """
+        from cyclone import db
+        from cyclone.db import Batch
+
+        # (st02, ack_count) from the 999-orphan walk.
+        counts = dict(_iter_orphan_999_st02s())
+
+        if not counts:
+            return []
+
+        # Map ST02 -> existing batch row (if any). One query.
+        with db.SessionLocal()() as s:
+            existing = {
+                row.transaction_set_control_number: row.id
+                for row in s.query(Batch)
+                .filter(Batch.transaction_set_control_number.in_(counts.keys()))
+                .all()
+            }
+
+        out = []
+        for st02, ack_count in counts.items():
+            batch_id = existing.get(st02)
+            out.append({
+                "st02": st02,
+                "ack_count": ack_count,
+                "has_batch": batch_id is not None,
+                "batch_id": batch_id,
+            })
+        # Heaviest first; tie-break by st02 ascending for determinism.
+        out.sort(key=lambda r: (-r["ack_count"], r["st02"]))
+        return out
+
+    def reconcile_orphan_st02s(self, *, dry_run: bool = False) -> dict:
+        """One-shot synthetic-batch seeder for orphan ST02s (sp38).
+
+        Inserts a ``batches`` row for every orphan ST02 that does
+        NOT already have one. The synthetic row is marked with:
+
+          * ``kind = '837p'``
+          * ``input_filename = '<synthetic:orphan-reconcile>'``
+          * ``parsed_at = utcnow()``
+          * ``transaction_set_control_number = <orphan ST02>``
+          * ``totals_json = {"orphan_reconcile": true,
+                              "ack_count": <orphan count>}``
+          * ``validation_json = {"orphan_reconcile": true,
+                                 "note": "sp38 synthetic batch row;
+                                 source 837 was never ingested into
+                                 this DB snapshot"}``
+          * ``id = uuid4().hex`` (no claim rows, no claim_acks links)
+
+        Remaining columns (``claim_count``, ``received_count``, …) take
+        their schema defaults.
+
+        The sentinel ``<synthetic:orphan-reconcile>`` makes these
+        rows trivially distinguishable in queries — grep for that
+        string to find every row this method has created.
+
+        Future 999 acks referencing these ST02s will resolve
+        against the batch envelope index (so the operator can see
+        "this 999 is for a known orphan source") but will not link
+        to claims (because no claim rows exist for the synthetic
+        batch).
+
+        Args:
+            dry_run: If True, returns the plan but does not insert
+                any rows. Used by the CLI ``--dry-run`` flag so
+                operators can preview the reconcile.
+
+        Returns:
+            ``{"created": int, "skipped": int,
+               "synthetic_batch_ids": list[str]}``. ``created`` is
+            the count of rows inserted (or that WOULD be inserted
+            under dry_run). ``skipped`` is the count of orphan ST02s
+            that already had a batches row.
+
+        Idempotent: re-running after a successful pass is a no-op.
+        """
+        from cyclone import db
+        from cyclone.db import Batch
+
+        summary = self.find_ack_orphan_st02_summary()
+        if not summary:
+            return {"created": 0, "skipped": 0, "synthetic_batch_ids": []}
+
+        created = 0
+        skipped = 0
+        synthetic_ids: list[str] = []
+
+        if dry_run:
+            for row in summary:
+                if row["has_batch"]:
+                    skipped += 1
+                else:
+                    created += 1  # would-create count
+            return {"created": created, "skipped": skipped, "synthetic_batch_ids": []}
+
+        now = utcnow()
+        with db.SessionLocal()() as s:
+            for row in summary:
+                if row["has_batch"]:
+                    skipped += 1
+                    continue
+                new_id = uuid.uuid4().hex
+                s.add(Batch(
+                    id=new_id,
+                    kind="837p",
+                    input_filename="<synthetic:orphan-reconcile>",
+                    parsed_at=now,
+                    transaction_set_control_number=row["st02"],
+                    totals_json=json.dumps({
+                        "orphan_reconcile": True,
+                        "ack_count": row["ack_count"],
+                    }),
+                    validation_json=json.dumps({
+                        "orphan_reconcile": True,
+                        "note": (
+                            "sp38 synthetic batch row; source 837 was "
+                            "never ingested into this DB snapshot"
+                        ),
+                    }),
+                ))
+                synthetic_ids.append(new_id)
+                created += 1
+            s.commit()
+
+        return {"created": created, "skipped": skipped, "synthetic_batch_ids": synthetic_ids}
+
     def remove_claim_ack(self, link_id, *, event_bus=None):
         """Unlink one row. Publishes ``claim_ack_dropped`` on the bus."""
         return _remove_claim_ack(link_id, event_bus=event_bus)
 
     def batch_envelope_index(self):
-        """Return a {envelope.control_number: batch.id} map for D10 Pass 1."""
+        """Return a {key: batch.id} map populated from two columns (D10 Pass 1).
+
+        Each 837p batch contributes both ``Batch.raw_result_json.envelope.control_number``
+        (ISA13) and ``Batch.transaction_set_control_number`` (ST02); 835 batches
+        are excluded. Single ``.get(set_control_number)`` lookup resolves
+        either key — SP37 closes the 999 AK201 → source-batch gap.
+        """
         return _batch_envelope_index()
 
     # -- SP17: encrypted DB backups -------------------------------------

backend/src/cyclone/store/claim_acks.py

@@ -11,8 +11,10 @@ Five methods on top of the new ``ClaimAck`` ORM table:
   ack-orphans lane).
 * ``remove_claim_ack`` — unlink. Publishes ``claim_ack_dropped``.
 * ``batch_envelope_index`` — D10 in-memory map of
-  ``Batch.envelope.control_number → batch.id`` (cheap to rebuild;
-  re-built once per ingest).
+  ``{Batch.raw_result_json.envelope.control_number (ISA13) OR
+  Batch.transaction_set_control_number (ST02)} → batch.id``
+  (SP37: populated from two columns; cheap to rebuild, re-built
+  once per ingest).
 
 Each mutating method opens its own ``db.SessionLocal()()`` session
 so callers don't have to manage session lifecycles. Publishes are
@@ -22,9 +24,10 @@ subscriber cannot roll back the persisted row.
 
 from __future__ import annotations
 
+import json
 import logging
 from datetime import datetime, timezone
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Iterator
 
 from cyclone import db
 from cyclone.db import (
@@ -67,26 +70,43 @@ def _safe_publish(event_bus: "EventBus | None", kind: str, payload: dict) -> Non
 
 
 def batch_envelope_index() -> dict[str, str]:
-    """Build a ``{envelope.control_number: batch.id}`` map.
+    """Build a ``{key: batch.id}`` map populated from two columns.
 
-    D10 primary join key (spec §D10). Built once per ingest from
-    every Batch row whose ``raw_result_json`` carries an envelope —
-    cost is O(N batches), currently ~16, so trivial. Kept as a
-    plain dict so callers can ``index.get(scn)`` to resolve.
+    D10 primary join key (spec §D10). Each 837p batch row contributes
+    up to two entries:
+
+    * ``Batch.raw_result_json.envelope.control_number`` (ISA13)
+    * ``Batch.transaction_set_control_number`` (ST02, new in SP37)
+
+    Either key resolves to the same ``batch.id``; callers do a single
+    ``idx.get(set_control_number)`` lookup. Pass 2 (PCN) is unchanged.
+
+    Built once per ingest from every Batch row whose kind is "837p";
+    cost is O(N batches), currently small, so trivial. 835 batches
+    are excluded — the column is an 837P-specific join key (see
+    ``Batch.transaction_set_control_number`` docstring).
     """
-    out: dict[str, str] = {}
+    idx: dict[str, str] = {}
     with db.SessionLocal()() as s:
         rows = (
-            s.query(Batch.id, Batch.raw_result_json)
+            s.query(
+                Batch.id,
+                Batch.raw_result_json,
+                Batch.transaction_set_control_number,
+            )
             .filter(Batch.kind == "837p")
             .all()
         )
-        for bid, raw in rows:
+        for bid, raw, stcn in rows:
             env = (raw or {}).get("envelope") or {}
-            ctrl = env.get("control_number")
-            if isinstance(ctrl, str) and ctrl:
-                out[ctrl] = bid
-    return out
+            isa_cn = env.get("control_number")
+            if isinstance(isa_cn, str) and isa_cn:
+                # First write wins (setdefault) — if ISA13 and ST02
+                # ever collide they map to the same batch anyway.
+                idx.setdefault(isa_cn, bid)
+            if isinstance(stcn, str) and stcn:
+                idx.setdefault(stcn, bid)
+    return idx
 
 
 # ---------------------------------------------------------------------------
@@ -257,97 +277,152 @@ def find_ack_orphans(kind: str) -> list[dict]:
     out: list[dict] = []
     if kind == "999":
         ack_table = Ack
-        ctrl_attr = None
     elif kind == "277ca":
         ack_table = Two77caAck
-        ctrl_attr = "control_number"
     else:
         ack_table = Ta1Ack
-        ctrl_attr = "control_number"
 
     with db.SessionLocal()() as s:
-        # Every ack row of the given kind, with a LEFT JOIN against
-        # any claim_acks link; orphan when NO link was created.
-        if kind == "999":
-            # For 999, the "ack has no link" means no ClaimAck row
-            # was emitted at all (the auto-linker emits one per AK2
-            # even when the AK2 is rejected, so 999 with at least
-            # one AK2 that resolved to a claim is never an orphan).
-            # We treat a 999 as orphan when it has zero ClaimAck
-            # rows tied to its id.
-            all_acks = s.query(Ack).order_by(Ack.id.desc()).all()
-            for ack_row in all_acks:
-                count = (
-                    s.query(ClaimAck)
-                    .filter(ClaimAck.ack_kind == "999",
-                            ClaimAck.ack_id == ack_row.id)
-                    .count()
-                )
-                if count == 0:
-                    out.append({
-                        "kind": "999",
-                        "ack_id": ack_row.id,
-                        "control_number": _ack_control_number(ack_row, "999"),
-                        "parsed_at": (
-                            ack_row.parsed_at.isoformat().replace(
-                                "+00:00", "Z"
-                            ) if ack_row.parsed_at else None
-                        ),
-                    })
-        elif kind == "277ca":
-            all_acks = s.query(Two77caAck).order_by(Two77caAck.id.desc()).all()
-            for ack_row in all_acks:
-                count = (
-                    s.query(ClaimAck)
-                    .filter(ClaimAck.ack_kind == "277ca",
-                            ClaimAck.ack_id == ack_row.id)
-                    .count()
-                )
-                if count == 0:
-                    out.append({
-                        "kind": "277ca",
-                        "ack_id": ack_row.id,
-                        "control_number": ack_row.control_number or "",
-                        "parsed_at": (
-                            ack_row.parsed_at.isoformat().replace(
-                                "+00:00", "Z"
-                            ) if ack_row.parsed_at else None
-                        ),
-                    })
-        else:
-            all_acks = s.query(Ta1Ack).order_by(Ta1Ack.id.desc()).all()
-            for ack_row in all_acks:
-                count = (
-                    s.query(ClaimAck)
-                    .filter(ClaimAck.ack_kind == "ta1",
-                            ClaimAck.ack_id == ack_row.id)
-                    .count()
-                )
-                if count == 0:
-                    out.append({
-                        "kind": "ta1",
-                        "ack_id": ack_row.id,
-                        "control_number": ack_row.control_number or "",
-                        "parsed_at": (
-                            ack_row.parsed_at.isoformat().replace(
-                                "+00:00", "Z"
-                            ) if ack_row.parsed_at else None
-                        ),
-                    })
+        # Every ack row of the given kind; orphan when NO claim_acks
+        # link was created for it. The auto-linker emits one claim_acks
+        # row per AK2 even when the AK2 is rejected, so a 999 with at
+        # least one linked AK2 is never an orphan.
+        for ack_row in s.query(ack_table).order_by(ack_table.id.desc()).all():
+            count = (
+                s.query(ClaimAck)
+                .filter(ClaimAck.ack_kind == kind,
+                        ClaimAck.ack_id == ack_row.id)
+                .count()
+            )
+            if count > 0:
+                continue
+            out.append({
+                "kind": kind,
+                "ack_id": ack_row.id,
+                "control_number": _ack_control_number(ack_row, kind),
+                "parsed_at": (
+                    ack_row.parsed_at.isoformat().replace(
+                        "+00:00", "Z"
+                    ) if ack_row.parsed_at else None
+                ),
+            })
     return out
 
 
-def _ack_control_number(ack_row: Ack, kind: str) -> str:
-    """Best-effort control-number lookup for a 999 ack row.
+def _iter_orphan_999_st02s() -> Iterator[tuple[str, int]]:
+    """Yield ``(set_control_number, orphan_count)`` for each distinct orphan 999.
 
-    The 999 ORM row doesn't carry the envelope's control_number in
-    a dedicated column; we re-derive it from ``raw_json`` (the same
-    source :func:`cyclone.store.ui.to_ui_ack` uses for the patient
-    control number).
+    An orphan 999 has zero ``claim_acks`` rows tied to its id (per
+    :func:`find_ack_orphans`). The ST02 is the source 837's
+    ``transaction_set_control_number``, extracted from the 999's
+    ``set_responses[0].set_control_number`` field in ``raw_json``.
+
+    Used by :meth:`CycloneStore.find_ack_orphan_st02_summary` and
+    :meth:`CycloneStore.reconcile_orphan_st02s` (sp38) to enumerate
+    orphan ST02s without re-implementing the orphan-detection query.
+
+    Skips 999s whose ``raw_json`` is malformed or has no
+    ``set_responses`` entry — those are unprocessable regardless of
+    whether they have a matching batch row.
+
+    999-only. 277ca / ta1 orphans are tracked separately by the
+    store and are not aggregated here (their "ST02" semantics differ
+    from 999: it's the interchange control number, not the source
+    837's ST02).
     """
-    raw = ack_row.raw_json or {}
-    env = raw.get("envelope") or {}
-    return env.get("control_number") or ""
+    with db.SessionLocal()() as s:
+        # LEFT OUTER JOIN keeps all acks; orphan when no claim_acks row
+        # exists for (ack_kind='999', ack_id=acks.id).
+        rows = (
+            s.query(Ack)
+            .outerjoin(
+                ClaimAck,
+                (ClaimAck.ack_kind == "999") & (ClaimAck.ack_id == Ack.id),
+            )
+            .filter(ClaimAck.id.is_(None))
+            .all()
+        )
+        counts: dict[str, int] = {}
+        for ack_row in rows:
+            st02 = _extract_999_st02(ack_row)
+            if st02 is None:
+                continue
+            counts[st02] = counts.get(st02, 0) + 1
+    # Unsorted on purpose — the caller re-sorts by (-ack_count, st02)
+    # so the heaviest backlog surfaces first in CLI output. Sorting
+    # here would just be wasted CPU (and risk a different order if
+    # the caller's key changes).
+    yield from counts.items()
+
+
+def _extract_999_st02(ack_row: Ack) -> str | None:
+    """Return the source 837's ST02 from a 999 ack row, or ``None``.
+
+    Reads ``raw_json`` and pulls ``set_responses[0].set_control_number``.
+    Returns ``None`` if the JSON is malformed, ``set_responses`` is
+    empty, or the field is missing — callers should skip these rows
+    rather than treating them as orphans (they're unprocessable, not
+    just orphaned).
+
+    Note: the ``raw_json`` column is a SQLAlchemy JSON type so the
+    ORM hands it back as a Python dict, not a string. We accept
+    either form (dict or str) so this helper is robust to direct
+    SQLAlchemy access and to raw sqlite3 row access.
+    """
+    raw = ack_row.raw_json
+    if not raw:
+        return None
+    if isinstance(raw, dict):
+        parsed = raw
+    elif isinstance(raw, (str, bytes, bytearray)):
+        try:
+            parsed = json.loads(raw)
+        except (TypeError, ValueError):
+            return None
+    else:
+        return None
+    srs = parsed.get("set_responses") or []
+    if not srs:
+        return None
+    st02 = srs[0].get("set_control_number")
+    return str(st02) if st02 else None
+
+
+def _ack_control_number(ack_row, kind: str) -> str:
+    """Best-effort control-number lookup for an ack row of any kind.
+
+    Per-kind sources (preserved across the SP38 refactor of
+    :func:`find_ack_orphans`):
+
+      * ``999`` — 999 ORM row has no dedicated control_number column;
+        we re-derive it from ``raw_json.envelope.control_number``
+        (the same source :func:`cyclone.store.ui.to_ui_ack` uses).
+        Accepts both dict (post-ORM hydration) and str (raw sqlite3
+        row or freshly inserted JSON string).
+      * ``277ca`` / ``ta1`` — both carry the control number in a
+        dedicated ORM column (``ack_row.control_number``). Reading
+        from ``raw_json`` would yield empty strings.
+
+    Returns ``""`` (empty string) when the source field is missing
+    so the JSON renderer still emits a stable shape.
+    """
+    if kind == "999":
+        raw = ack_row.raw_json
+        if raw is None or raw == "":
+            return ""
+        if isinstance(raw, dict):
+            env = raw.get("envelope") or {}
+            return env.get("control_number") or ""
+        if isinstance(raw, (str, bytes, bytearray)):
+            try:
+                parsed = json.loads(raw)
+            except (TypeError, ValueError):
+                return ""
+            env = parsed.get("envelope") or {}
+            return env.get("control_number") or ""
+        return ""
+    # 277ca / ta1 — control_number is an ORM column on both tables.
+    return getattr(ack_row, "control_number", "") or ""
 
 
 __all__ = [

backend/src/cyclone/store/write.py

@@ -77,6 +77,17 @@ def add_record(record: BatchRecord, *, event_bus=None) -> None:
             totals_json=None,
             validation_json=None,
             raw_result_json=json.loads(record.result.model_dump_json()),
+            # SP37 Task 2: mirror the parsed 837's ST02 onto the batch
+            # row so 999 AK201 set_control_numbers can resolve back via
+            # Pass 1. The ``getattr`` chain handles the 835 path: the
+            # shared ``Envelope`` class is used by both 837P and 835
+            # parsers, but only ``parse_837`` populates this field — for
+            # 835 records it stays ``None`` and the column is NULL.
+            transaction_set_control_number=getattr(
+                getattr(record.result, "envelope", None),
+                "transaction_set_control_number",
+                None,
+            ),
         )
         s.add(batch_row)
 

backend/src/cyclone/submission/__init__.py

@@ -0,0 +1,17 @@
+"""SP37 Task 4: canonical 837P submission flow.
+
+The single public helper is ``submit_file`` — it owns parse → DB
+write → SFTP upload per file. CLI (``cyclone submit-batch``) and HTTP
+(``POST /api/submit-batch``) are thin wrappers; both call this helper
+so the ordering, idempotency, and audit shape are identical.
+
+DB-first, upload-second (per spec decision §2): if the DB write fails,
+no SFTP call is made. If the SFTP call fails after a successful DB
+write, the row exists but the file never landed — re-running is safe
+(idempotent DB write via add_record's s.get check; idempotent SFTP
+upload via stat-then-put).
+"""
+from .core import submit_file
+from .result import SubmitOutcome, SubmitResult
+
+__all__ = ["submit_file", "SubmitOutcome", "SubmitResult"]

backend/src/cyclone/submission/core.py

@@ -0,0 +1,225 @@
+"""SP37 Task 4: parse → DB write → SFTP upload, per file.
+
+Mirrors ``resubmit_rejected_claims`` but writes to the DB before
+uploading. Same idempotency check (``stat().st_size == local_size``)
+skips already-uploaded files without re-emitting audit events.
+
+DB-first, upload-second (per spec decision §2): if the DB write fails,
+no SFTP call is made. If the SFTP call fails after a successful DB
+write, the row exists but the file never landed — re-running is safe
+(idempotent DB write via add_record's s.get check; idempotent SFTP
+upload via stat-then-put).
+
+The default SFTP factory uses paramiko directly (not the
+``SftpClient`` wrapper) because the wrapper exposes ``write_file``,
+``list_inbound``, and ``read_file`` but no ``stat()`` — which makes
+the SKIPPED outcome unreachable in production.
+"""
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from cyclone import db as db_mod
+from cyclone.audit_log import AuditEvent, append_event
+from cyclone.parsers.parse_837 import parse as parse_837_text
+from cyclone.parsers.payer import PayerConfig
+from cyclone.providers import SftpBlock
+from cyclone.store import store as cycl_store
+from cyclone.store.records import BatchRecord837
+
+from .result import SubmitOutcome, SubmitResult
+
+log = logging.getLogger(__name__)
+
+# The companion-guide payer id we enforce for CO Medicaid submits.
+# Same value the legacy ``resubmit-rejected-claims`` CLI gates on.
+EXPECTED_PAYER_ID = "CO_TXIX"
+
+
+def _default_sftp_factory(sftp_block: SftpBlock) -> Any:
+    """Open a paramiko SFTP session to the real MFT. Mirrors
+    resubmit_rejected_claims._open_session (cli.py:620-640).
+    Caller is responsible for closing the session.
+
+    The returned ``sftp`` is a ``paramiko.SFTPClient`` — it exposes
+    ``stat(remote_path)`` (used for the idempotency check) and
+    ``put(local_path, remote_path)`` (used for the upload). The
+    underlying SSH handle is stashed on ``sftp._cyclone_ssh`` so the
+    caller can close it cleanly via ``getattr(sftp, "_cyclone_ssh",
+    None).close()`` after the upload finishes.
+
+    Raises:
+        RuntimeError: if the SFTP block is in stub mode (the CLI/HTTP
+            layer should already guard against this, but we re-check
+            here because paramiko will try to connect even when
+            ``stub=True``).
+    """
+    if sftp_block.stub:
+        # Same posture as resubmit_rejected_claims in cli.py:592-595:
+        # the operator refuses to upload in stub mode, and the helper
+        # surfaces that as SFTP_FAILED with an explicit error.
+        raise RuntimeError("SFTP block is in stub mode")
+
+    from paramiko import AutoAddPolicy, SSHClient
+
+    from cyclone.secrets import get_secret
+
+    pw = get_secret(sftp_block.auth.get("password_keychain_account", ""))
+    ssh = SSHClient()
+    ssh.set_missing_host_key_policy(AutoAddPolicy())
+    ssh.connect(
+        sftp_block.host, port=sftp_block.port,
+        username=sftp_block.username, password=pw,
+        timeout=15, banner_timeout=15, auth_timeout=15,
+    )
+    sftp = ssh.open_sftp()
+    # Attach ssh to sftp so the caller can close it cleanly.
+    sftp._cyclone_ssh = ssh
+    return sftp
+
+
+def submit_file(
+    path: Path,
+    *,
+    sftp_block: SftpBlock,
+    actor: str,
+    validate: bool = True,
+    sftp_client_factory: Callable[[SftpBlock], Any] | None = None,
+) -> SubmitResult:
+    """Submit one 837P file: parse → DB write → SFTP upload.
+
+    Args:
+        path: local 837P file.
+        sftp_block: the clearhouse SftpBlock (for paths + auth).
+        actor: audit-log actor tag (e.g. "api-submit-batch").
+        validate: parse the file before upload (default True). Catches
+            bad byte-fixes early.
+        sftp_client_factory: optional callable that returns an
+            SFTP-client-compatible object (must expose ``stat()`` and
+            ``write_file()``). Defaults to :func:`_default_sftp_factory`
+            which opens a real paramiko session. Tests inject a fake.
+
+    Returns:
+        SubmitResult with file, outcome, batch_id (when written),
+        error (when failed).
+    """
+    file_label = path.name
+    try:
+        content = path.read_bytes()
+    except OSError as exc:
+        return SubmitResult(file_label, SubmitOutcome.PARSE_FAILED, error=str(exc))
+
+    # 1. Validate via parse (optional but recommended).
+    parsed: Any = None
+    if validate:
+        try:
+            parsed = parse_837_text(content.decode(), PayerConfig.co_medicaid())
+        except Exception as exc:  # noqa: BLE001
+            log.warning("submit_file %s: parse failed: %s", file_label, exc)
+            return SubmitResult(file_label, SubmitOutcome.PARSE_FAILED, error=str(exc))
+        mismatch = next(
+            (c for c in parsed.claims if c.payer.id != EXPECTED_PAYER_ID),
+            None,
+        )
+        if mismatch is not None:
+            return SubmitResult(
+                file_label,
+                SubmitOutcome.PAYER_MISMATCH,
+                error=f"payer.id={mismatch.payer.id!r} (expected {EXPECTED_PAYER_ID!r})",
+            )
+
+    # 2. DB write — DB-first, upload-second invariant.
+    # ``parsed`` is required to construct a BatchRecord837 (it embeds the
+    # full ParseResult). validate=False therefore isn't a real path —
+    # the CLI/HTTP always pass validate=True — so reject it loudly
+    # rather than silently building an empty row.
+    if parsed is None:
+        return SubmitResult(
+            file_label,
+            SubmitOutcome.PARSE_FAILED,
+            error="validate=False is not supported; must parse to construct a BatchRecord",
+        )
+
+    # Use the same uuid4().hex id the existing /api/parse-837 path uses.
+    batch_id = uuid.uuid4().hex
+    record = BatchRecord837(
+        id=batch_id,
+        input_filename=file_label,
+        parsed_at=datetime.now(timezone.utc),
+        result=parsed,
+    )
+
+    try:
+        # ``cycl_store.add`` is the public facade method (per the
+        # CycloneStore class in store/__init__.py:158). It delegates
+        # to ``store.write.add_record``, which is the underlying
+        # SQLAlchemy write path.
+        cycl_store.add(record)
+    except Exception as exc:  # noqa: BLE001
+        log.warning("submit_file %s: DB write failed: %s", file_label, exc)
+        return SubmitResult(file_label, SubmitOutcome.DB_FAILED, error=str(exc))
+
+    # 3. SFTP upload. ``_default_sftp_factory`` opens a paramiko
+    # session directly because the SftpClient wrapper has no ``stat()``
+    # method — that omission made the SKIPPED outcome unreachable in
+    # production. Mirror cli.py:620-650.
+    remote_path = f"{sftp_block.paths['outbound']}/{file_label}"
+    factory = sftp_client_factory or _default_sftp_factory
+    sftp = factory(sftp_block)
+    local_size = len(content)
+    try:
+        try:
+            stat = sftp.stat(remote_path)
+            if stat.st_size == local_size:
+                # Already on remote at the right size — re-run is safe;
+                # do NOT emit a duplicate audit event.
+                return SubmitResult(file_label, SubmitOutcome.SKIPPED, batch_id=batch_id)
+        except (IOError, OSError):
+            pass  # not on remote yet
+        sftp.write_file(remote_path, content)
+    except Exception as exc:  # noqa: BLE001
+        log.warning("submit_file %s: SFTP failed: %s", file_label, exc)
+        return SubmitResult(
+            file_label, SubmitOutcome.SFTP_FAILED,
+            batch_id=batch_id, error=str(exc),
+        )
+    finally:
+        # Close the paramiko SSH handle the helper stashed on the
+        # SFTP client (paramiko does not auto-close on GC and a leak
+        # here costs a slot in MOVEit's per-IP session table).
+        ssh_handle = getattr(sftp, "_cyclone_ssh", None)
+        if ssh_handle is not None:
+            try:
+                ssh_handle.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+    # 4. Audit event — same shape the legacy resubmit_rejected_claims CLI
+    # uses (event_type="clearhouse.submitted", entity_type="claim_file",
+    # entity_id=filename, payload has remote_path + source + size).
+    # Best-effort: an audit failure must not roll back the upload.
+    try:
+        with db_mod.SessionLocal()() as session:
+            append_event(session, AuditEvent(
+                event_type="clearhouse.submitted",
+                entity_type="claim_file",
+                entity_id=file_label,
+                payload={
+                    "remote_path": remote_path,
+                    "source": "submit-batch",
+                    "size": local_size,
+                    "batch_id": batch_id,
+                },
+                actor=actor,
+            ))
+            session.commit()
+    except Exception as exc:  # noqa: BLE001
+        log.warning(
+            "submit_file %s: audit event failed: %s", file_label, exc,
+        )
+
+    return SubmitResult(file_label, SubmitOutcome.SUBMITTED, batch_id=batch_id)

backend/src/cyclone/submission/result.py

@@ -0,0 +1,48 @@
+"""SP37 Task 4: typed result for submit_file.
+
+The CLI and HTTP layer both consume SubmitResult; keeping it in one
+place means both surfaces agree on the response shape.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class SubmitOutcome(str, Enum):
+    """Outcome of a single submit_file invocation.
+
+    Audit-event invariant: ``SUBMITTED`` emits a ``clearhouse.submitted``
+    audit event; ``SKIPPED`` does NOT (re-running on an already-uploaded
+    file must not flood the audit log with duplicate events). All
+    failure outcomes (``PARSE_FAILED``, ``PAYER_MISMATCH``, ``DB_FAILED``,
+    ``SFTP_FAILED``, ``UNEXPECTED_ERROR``) emit no event either —
+    failures should be observable via the helper's return value, not
+    the audit log.
+
+    ``UNEXPECTED_ERROR`` is reserved for uncaught exceptions in the
+    helper's own code (e.g. a bug in ``cycl_store.add``) — distinct
+    from the typed ``SFTP_FAILED`` which means the SFTP layer itself
+    raised. Operators reading ``outcome="unexpected_error"`` know to
+    look at the bug tracker, not the SFTP server.
+    """
+    SUBMITTED = "submitted"
+    SKIPPED = "skipped"
+    PARSE_FAILED = "parse_failed"
+    PAYER_MISMATCH = "payer_mismatch"
+    DB_FAILED = "db_failed"
+    SFTP_FAILED = "sftp_failed"
+    UNEXPECTED_ERROR = "unexpected_error"
+
+
+@dataclass(frozen=True)
+class SubmitResult:
+    """Return value of ``submit_file``: filename, outcome, and optional
+    ``batch_id`` (populated when the DB write succeeded) and ``error``
+    (populated on any failure outcome; ``None`` on ``SUBMITTED`` /
+    ``SKIPPED``).
+    """
+    file: str
+    outcome: SubmitOutcome
+    batch_id: str | None = None
+    error: str | None = None

backend/tests/fixtures/submit-batch/single-claim.x12

@@ -0,0 +1,30 @@
+ISA*00*          *00*          *ZZ*11525703       *ZZ*COMEDASSISTPROG*260611*0814*^*00501*991102977*1*P*:~
+GS*HC*11525703*COMEDASSISTPROG*20260611*081417*991102977*X*005010X222A1~
+ST*837*991102977*005010X222A1~
+BHT*0019*00*ref-001*20260611*081417*CH~
+NM1*41*2*Test Submitter*****46*11525703~
+PER*IC*Test Contact*EM*test@example.com~
+NM1*40*2*COLORADO MEDICAL ASSISTANCE PROGRAM*****46*COMEDASSISTPROG~
+HL*1**20*1~
+PRV*BI*PXC*251E00000X~
+NM1*85*2*Test Provider Inc*****XX*1993999998~
+N3*123 Test St~
+N4*Denver*CO*80202~
+REF*EI*123456789~
+HL*2*1*22*0~
+SBR*P*18*******MC~
+NM1*IL*1*Doe*John****MI*ABC123~
+N3*456 Member St~
+N4*Denver*CO*80203~
+DMG*D8*19800101*M~
+NM1*PR*2*CO_TXIX*****PI*CO_TXIX~
+CLM*CLM001*100.00***12:B:1*Y*A*Y*Y~
+REF*G1*PA123~
+HI*ABK:Z00~
+LX*1~
+SV1*HC:99213*100.00*UN*1***1~
+DTP*472*D8*20260611~
+REF*6R*REF001~
+SE*26*991102977~
+GE*1*991102977~
+IEA*1*991102977~

backend/tests/test_ack_orphan_summary.py

@@ -0,0 +1,377 @@
+"""SP38: store-helper tests for ``find_ack_orphan_st02_summary``.
+
+The summary is the per-ST02 breakdown the ``cyclone ack-orphans``
+CLI commands consume. It enumerates every distinct orphan 999 ST02
++ ack count + whether a ``batches`` row already covers that ST02.
+
+Tests live here (not in ``test_apply_claim_ack_links.py``) because
+the helper is a sp38 surface, not an sp28 invariant. Keeping the
+tests in a sibling file matches the ``cyclone-tests`` convention.
+
+The autouse ``_auto_init_db`` fixture in ``conftest.py`` provides
+a fresh ``tmp_path/test.db`` for every test — no manual DB setup
+needed here.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+import pytest
+
+from cyclone import db
+from cyclone.db import Ack, Batch, ClaimAck
+from cyclone.store import CycloneStore
+
+
+def _now():
+    """A single shared 'now' for deterministic test timestamps."""
+    return datetime.now(timezone.utc)
+
+
+def _ingest_999(s, st02: str, *, batch_id: str | None = None) -> int:
+    """Insert a 999 ack row whose set_responses[0].set_control_number == st02.
+
+    Returns the new ack id. The 999 is an orphan (no claim_acks row
+    is inserted) so it surfaces in the summary.
+    """
+    raw = {
+        "envelope": {
+            "sender_id": "SUBMITTERID",
+            "receiver_id": "RECEIVERID",
+            "control_number": "000000099",
+            "transaction_date": "2024-01-01",
+            "implementation_guide": "005010X231A1",
+        },
+        "functional_group_acks": [],
+        "set_responses": [
+            {"set_control_number": st02, "transaction_set_identifier": "837",
+             "ak2": {"functional_id_code": "837"}, "segment_errors": [],
+             "set_accept_reject": {"code": "A"}}
+        ],
+        "summary": {"accepted_count": 1, "rejected_count": 0},
+    }
+    ack = Ack(
+        source_batch_id=batch_id or f"999-{st02}-test",
+        accepted_count=1,
+        rejected_count=0,
+        received_count=1,
+        ack_code="A",
+        parsed_at=_now(),
+        raw_json=json.dumps(raw),
+    )
+    s.add(ack)
+    s.flush()
+    return ack.id
+
+
+def _seed_batch(s, *, st02: str, batch_id: str | None = None) -> str:
+    """Insert a batches row with the given ST02. Returns the batch id."""
+    import uuid
+    bid = batch_id or uuid.uuid4().hex
+    s.add(Batch(
+        id=bid,
+        kind="837p",
+        input_filename="test.837p",
+        transaction_set_control_number=st02,
+        parsed_at=_now(),
+    ))
+    s.flush()
+    return bid
+
+
+def test_summary_returns_per_st02_counts():
+    """Two distinct orphan ST02s surface as two separate summary rows."""
+    with db.SessionLocal()() as s:
+        _ingest_999(s, "991102989")
+        _ingest_999(s, "991102989")  # same ST02 twice
+        _ingest_999(s, "991102988")
+        s.commit()
+
+    summary = CycloneStore().find_ack_orphan_st02_summary()
+    by_st02 = {row["st02"]: row for row in summary}
+    assert by_st02["991102989"]["ack_count"] == 2
+    assert by_st02["991102988"]["ack_count"] == 1
+    assert by_st02["991102989"]["has_batch"] is False
+    assert by_st02["991102988"]["has_batch"] is False
+
+
+def test_summary_sets_has_batch_true_when_batches_row_exists():
+    """When a batches row has the orphan ST02, ``has_batch`` is True
+    and ``batch_id`` matches the batches row's id."""
+    with db.SessionLocal()() as s:
+        bid = _seed_batch(s, st02="991102977")
+        _ingest_999(s, "991102977", batch_id=bid)
+        s.commit()
+
+    summary = CycloneStore().find_ack_orphan_st02_summary()
+    assert len(summary) == 1
+    row = summary[0]
+    assert row["st02"] == "991102977"
+    assert row["ack_count"] == 1
+    assert row["has_batch"] is True
+    assert row["batch_id"] == bid
+
+
+def test_summary_sorted_by_ack_count_descending():
+    """The summary is sorted so the heaviest orphans surface first
+    in the CLI output (matches the spec's intent that operators
+    triage the biggest backlog first)."""
+    with db.SessionLocal()() as s:
+        for _ in range(3):
+            _ingest_999(s, "991102988")
+        _ingest_999(s, "991102987")
+        for _ in range(5):
+            _ingest_999(s, "991102989")
+        s.commit()
+
+    summary = CycloneStore().find_ack_orphan_st02_summary()
+    counts = [row["ack_count"] for row in summary]
+    assert counts == sorted(counts, reverse=True)
+    assert counts[0] == 5  # 991102989 has the most
+
+
+def test_summary_excludes_999s_that_have_a_claim_acks_link():
+    """A 999 with a claim_acks row is NOT an orphan and must not
+    appear in the summary."""
+    with db.SessionLocal()() as s:
+        linked_id = _ingest_999(s, "991102977")
+        _ingest_999(s, "991102988")  # orphan, no link
+        # Manually insert a claim_acks link for the first 999.
+        s.add(ClaimAck(
+            claim_id="CLM-1",
+            batch_id="b1",
+            ack_id=linked_id,
+            ack_kind="999",
+            ak2_index=0,
+            set_control_number="991102977",
+            set_accept_reject_code="A",
+            linked_at=_now(),
+            linked_by="auto",
+        ))
+        s.commit()
+
+    summary = CycloneStore().find_ack_orphan_st02_summary()
+    by_st02 = {row["st02"]: row for row in summary}
+    assert "991102977" not in by_st02  # linked → not orphan
+    assert by_st02["991102988"]["ack_count"] == 1
+
+
+def test_summary_skips_999s_with_malformed_raw_json():
+    """999s whose raw_json is missing set_responses or is malformed
+    JSON are SKIPPED — they can't be reconciled, so they don't
+    contribute to the summary."""
+    with db.SessionLocal()() as s:
+        # Valid orphan
+        _ingest_999(s, "991102988")
+        # Malformed JSON — raw_json is not parseable
+        s.add(Ack(
+            source_batch_id="999-malformed",
+            accepted_count=1, rejected_count=0, received_count=1,
+            ack_code="A",
+            parsed_at=_now(),
+            raw_json="{not valid json",
+        ))
+        # Empty set_responses
+        s.add(Ack(
+            source_batch_id="999-empty",
+            accepted_count=1, rejected_count=0, received_count=1,
+            ack_code="A",
+            parsed_at=_now(),
+            raw_json=json.dumps({"envelope": {}, "set_responses": [], "summary": {}}),
+        ))
+        s.commit()
+
+    summary = CycloneStore().find_ack_orphan_st02_summary()
+    by_st02 = {row["st02"]: row for row in summary}
+    assert set(by_st02.keys()) == {"991102988"}
+    assert by_st02["991102988"]["ack_count"] == 1
+
+
+def test_summary_empty_when_no_orphans():
+    """With zero orphans, the summary is an empty list."""
+    summary = CycloneStore().find_ack_orphan_st02_summary()
+    assert summary == []
+
+
+# ---- Task 3: reconcile_orphan_st02s --------------------------------------- #
+
+
+def test_reconcile_creates_synthetic_batches_for_missing_st02s():
+    """``reconcile_orphan_st02s`` inserts one synthetic batch row per
+    orphan ST02 that doesn't already have a batches row.
+
+    Each synthetic row uses the sentinel ``input_filename`` and
+    ``kind = '837p'`` so they're trivially distinguishable in
+    queries (the spec: grep for ``<synthetic:orphan-reconcile>``
+    to find every row this SP38 created).
+    """
+    with db.SessionLocal()() as s:
+        _ingest_999(s, "991102989")
+        _ingest_999(s, "991102988")
+        s.commit()
+
+    plan = CycloneStore().reconcile_orphan_st02s(dry_run=False)
+
+    assert plan["created"] == 2
+    assert plan["skipped"] == 0
+    assert len(plan["synthetic_batch_ids"]) == 2
+
+    with db.SessionLocal()() as s:
+        rows = (
+            s.query(Batch)
+            .filter(Batch.input_filename == "<synthetic:orphan-reconcile>")
+            .all()
+        )
+        assert len(rows) == 2
+        assert all(r.kind == "837p" for r in rows)
+        st02s = {r.transaction_set_control_number for r in rows}
+        assert st02s == {"991102989", "991102988"}
+
+
+def test_reconcile_skips_st02s_that_already_have_a_batch():
+    """``reconcile`` does NOT create a synthetic row for an ST02
+    that already has a batches row — the operator's intent is to
+    fill gaps, not duplicate coverage."""
+    with db.SessionLocal()() as s:
+        existing = _seed_batch(s, st02="991102977")
+        _ingest_999(s, "991102977", batch_id=existing)
+        _ingest_999(s, "991102988")  # orphan, no batch
+        s.commit()
+
+    plan = CycloneStore().reconcile_orphan_st02s(dry_run=False)
+
+    assert plan["created"] == 1
+    assert plan["skipped"] == 1
+
+    with db.SessionLocal()() as s:
+        synthetic = (
+            s.query(Batch)
+            .filter(Batch.input_filename == "<synthetic:orphan-reconcile>")
+            .all()
+        )
+        assert len(synthetic) == 1
+        assert synthetic[0].transaction_set_control_number == "991102988"
+
+
+def test_reconcile_is_idempotent():
+    """Re-running reconcile after a successful pass is a no-op:
+    ``created=0, skipped=N``."""
+    with db.SessionLocal()() as s:
+        _ingest_999(s, "991102989")
+        s.commit()
+
+    CycloneStore().reconcile_orphan_st02s(dry_run=False)
+    plan2 = CycloneStore().reconcile_orphan_st02s(dry_run=False)
+
+    assert plan2["created"] == 0
+    assert plan2["skipped"] == 1
+
+    with db.SessionLocal()() as s:
+        n = (
+            s.query(Batch)
+            .filter(Batch.input_filename == "<synthetic:orphan-reconcile>")
+            .count()
+        )
+        assert n == 1
+
+
+def test_reconcile_dry_run_does_not_write():
+    """``dry_run=True`` returns the same plan shape but does not
+    insert any rows. Operators use this to preview the reconcile
+    before committing."""
+    with db.SessionLocal()() as s:
+        _ingest_999(s, "991102989")
+        s.commit()
+
+    plan = CycloneStore().reconcile_orphan_st02s(dry_run=True)
+
+    assert plan["created"] == 1
+    assert plan["skipped"] == 0
+
+    with db.SessionLocal()() as s:
+        n = (
+            s.query(Batch)
+            .filter(Batch.input_filename == "<synthetic:orphan-reconcile>")
+            .count()
+        )
+        assert n == 0  # no row inserted
+
+
+def test_reconcile_records_ack_count_in_totals_json():
+    """The synthetic row's ``totals_json`` includes ``ack_count`` so
+    future operators can see the orphan weight without re-querying."""
+    import json
+    with db.SessionLocal()() as s:
+        for _ in range(4):
+            _ingest_999(s, "991102989")
+        s.commit()
+
+    CycloneStore().reconcile_orphan_st02s(dry_run=False)
+
+    with db.SessionLocal()() as s:
+        row = (
+            s.query(Batch)
+            .filter(Batch.transaction_set_control_number == "991102989")
+            .one()
+        )
+        totals = json.loads(row.totals_json or "{}")
+        assert totals.get("orphan_reconcile") is True
+        assert totals.get("ack_count") == 4
+
+
+def test_reconcile_sentinel_is_grep_discoverable():
+    """``input_filename = '<synthetic:orphan-reconcile>'`` must be
+    discoverable via a plain ``LIKE '<synthetic:%>'`` query so
+    operators can find every sp38-created row without knowing the
+    exact sentinel string. Pins the spec's D2 grep-discoverability
+    invariant."""
+    with db.SessionLocal()() as s:
+        _ingest_999(s, "991102988")
+        s.commit()
+
+    CycloneStore().reconcile_orphan_st02s(dry_run=False)
+
+    with db.SessionLocal()() as s:
+        n = (
+            s.query(Batch)
+            .filter(Batch.input_filename.like("<synthetic:%>"))
+            .count()
+        )
+        assert n == 1
+
+
+def test_summary_skips_999s_with_non_dict_raw_json():
+    """``_extract_999_st02`` must tolerate the un-dict shapes a JSON
+    column can take (None, list) and never raise. Rows with
+    non-dict raw_json are skipped — they have no ST02 to contribute
+    to the summary regardless.
+
+    Note: the SQLAlchemy JSON column rejects bytes at insert time
+    (it must be JSON-serializable), so we don't exercise the
+    ``bytes`` branch here — that's a defensive-programming guard for
+    raw sqlite3 reads, not a normal ORM codepath.
+    """
+    with db.SessionLocal()() as s:
+        # Valid orphan — contributes 1 row
+        _ingest_999(s, "991102988")
+        # None — should be skipped, not raise
+        s.add(Ack(
+            source_batch_id="999-none-raw",
+            accepted_count=1, rejected_count=0, received_count=1,
+            ack_code="A", parsed_at=_now(),
+            raw_json=None,
+        ))
+        # list — not a dict; should be skipped (not raise)
+        s.add(Ack(
+            source_batch_id="999-list-raw",
+            accepted_count=1, rejected_count=0, received_count=1,
+            ack_code="A", parsed_at=_now(),
+            raw_json=[1, 2, 3],
+        ))
+        s.commit()
+
+    summary = CycloneStore().find_ack_orphan_st02_summary()
+    by_st02 = {row["st02"]: row for row in summary}
+    assert by_st02 == {"991102988": {"st02": "991102988", "ack_count": 1,
+                                     "has_batch": False, "batch_id": None}}

backend/tests/test_ack_orphans_cli.py

@@ -0,0 +1,210 @@
+"""SP38: CLI tests for ``cyclone ack-orphans {status,reconcile}``.
+
+Uses ``click.testing.CliRunner`` (matching the SP37-followup #5
+pattern that replaced ``subprocess.run`` with the in-process
+runner). The CLI commands are thin wrappers over the store helpers
+tested in ``test_ack_orphan_summary.py`` — these tests pin the
+shell-facing shape (table format, exit codes, --dry-run flag).
+
+The autouse ``_auto_init_db`` fixture in ``conftest.py`` provides
+a fresh ``tmp_path/test.db`` for every test; the CLI commands pick
+it up via the ``CYCLONE_DB_URL`` env var the fixture sets.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+import pytest
+from click.testing import CliRunner
+
+from cyclone import db
+from cyclone.cli import main
+from cyclone.db import Ack, Batch
+
+
+def _now():
+    return datetime.now(timezone.utc)
+
+
+def _ingest_orphan(s, st02: str) -> int:
+    """Insert a 999 ack row whose set_responses[0].set_control_number == st02.
+
+    Returns the new ack id. The 999 is an orphan (no claim_acks row)
+    so it surfaces in the summary.
+    """
+    raw = {
+        "envelope": {"sender_id": "S", "receiver_id": "R",
+                     "control_number": "000000099", "transaction_date": "2024-01-01",
+                     "implementation_guide": "005010X231A1"},
+        "functional_group_acks": [],
+        "set_responses": [
+            {"set_control_number": st02, "transaction_set_identifier": "837",
+             "ak2": {"functional_id_code": "837"}, "segment_errors": [],
+             "set_accept_reject": {"code": "A"}}
+        ],
+        "summary": {"accepted_count": 1, "rejected_count": 0},
+    }
+    ack = Ack(
+        source_batch_id=f"999-{st02}-cli-test",
+        accepted_count=1, rejected_count=0, received_count=1,
+        ack_code="A", parsed_at=_now(), raw_json=json.dumps(raw),
+    )
+    s.add(ack)
+    s.flush()
+    return ack.id
+
+
+# ---- cyclone ack-orphans status ------------------------------------------ #
+
+
+def test_status_prints_table_with_orphans():
+    """``cyclone ack-orphans status`` prints a table with ST02 +
+    ack count + has-batch flag, plus a TOTAL line at the bottom.
+
+    Mirrors the spec's intent: operators want a one-line-per-orphan
+    view that ranks the heaviest backlog first.
+    """
+    with db.SessionLocal()() as s:
+        _ingest_orphan(s, "991102989")
+        _ingest_orphan(s, "991102988")
+        s.commit()
+
+    runner = CliRunner()
+    result = runner.invoke(main, ["ack-orphans", "status"])
+    assert result.exit_code == 0, result.output
+    # Table header + two data rows + total line.
+    assert "ST02" in result.output
+    assert "ACK COUNT" in result.output
+    assert "991102989" in result.output
+    assert "991102988" in result.output
+    assert "TOTAL" in result.output
+
+
+def test_status_exits_zero_on_empty_db():
+    """With no orphans, status exits 0 and prints a 'no orphans' note."""
+    runner = CliRunner()
+    result = runner.invoke(main, ["ack-orphans", "status"])
+    assert result.exit_code == 0, result.output
+    # The empty case should be informative, not silent.
+    assert "no orphans" in result.output.lower() or "0" in result.output
+
+
+def test_status_table_includes_has_batch_column():
+    """When a ST02 already has a batches row, the table marks it
+    with ``yes`` (or similar) so operators can see which orphans
+    are unbacked vs already-covered.
+    """
+    with db.SessionLocal()() as s:
+        # Orphan with NO batch.
+        _ingest_orphan(s, "991102988")
+        # Orphan WITH a pre-existing batch row.
+        import uuid
+        bid = uuid.uuid4().hex
+        s.add(Batch(
+            id=bid, kind="837p", input_filename="test.837p",
+            transaction_set_control_number="991102977", parsed_at=_now(),
+        ))
+        _ingest_orphan(s, "991102977")
+        s.commit()
+
+    runner = CliRunner()
+    result = runner.invoke(main, ["ack-orphans", "status"])
+    assert result.exit_code == 0, result.output
+    # Look for "yes" / "no" markers in the table.
+    lines = result.output.splitlines()
+    has_yes = any("yes" in ln.lower() for ln in lines)
+    has_no = any("no" in ln.lower() for ln in lines)
+    assert has_yes and has_no, (
+        f"Expected table to mark 'yes' for ST02s with batches and "
+        f"'no' for ST02s without. Got:\n{result.output}"
+    )
+
+
+# ---- cyclone ack-orphans reconcile --------------------------------------- #
+
+
+def test_reconcile_creates_synthetic_batches():
+    """``cyclone ack-orphans reconcile`` inserts a synthetic batch
+    row for each orphan ST02 without one. Confirms the count + the
+    sentinel filename.
+    """
+    with db.SessionLocal()() as s:
+        _ingest_orphan(s, "991102989")
+        _ingest_orphan(s, "991102988")
+        s.commit()
+
+    runner = CliRunner()
+    result = runner.invoke(main, ["ack-orphans", "reconcile"])
+    assert result.exit_code == 0, result.output
+
+    # The CLI should print the created/skipped counts.
+    assert "Created" in result.output or "created" in result.output
+    assert "Skipped" in result.output or "skipped" in result.output
+
+    with db.SessionLocal()() as s:
+        synthetic = (
+            s.query(Batch)
+            .filter(Batch.input_filename == "<synthetic:orphan-reconcile>")
+            .all()
+        )
+        assert len(synthetic) == 2
+        st02s = {r.transaction_set_control_number for r in synthetic}
+        assert st02s == {"991102989", "991102988"}
+
+
+def test_reconcile_dry_run_does_not_write():
+    """``--dry-run`` returns the plan shape but does NOT insert rows.
+    Operators use this to preview before committing.
+    """
+    with db.SessionLocal()() as s:
+        _ingest_orphan(s, "991102989")
+        s.commit()
+
+    runner = CliRunner()
+    result = runner.invoke(main, ["ack-orphans", "reconcile", "--dry-run"])
+    assert result.exit_code == 0, result.output
+    # The plan reports the would-create count.
+    assert "1" in result.output  # would-create 1 row
+
+    # But no synthetic batch row was inserted.
+    with db.SessionLocal()() as s:
+        n = (
+            s.query(Batch)
+            .filter(Batch.input_filename == "<synthetic:orphan-reconcile>")
+            .count()
+        )
+        assert n == 0
+
+
+def test_reconcile_is_idempotent():
+    """A second reconcile after a successful pass is a no-op:
+    created=0, skipped=N. Tested at the CLI shell level so the
+    user-visible output also pins this invariant.
+    """
+    with db.SessionLocal()() as s:
+        _ingest_orphan(s, "991102989")
+        s.commit()
+
+    runner = CliRunner()
+    first = runner.invoke(main, ["ack-orphans", "reconcile"])
+    second = runner.invoke(main, ["ack-orphans", "reconcile"])
+    assert first.exit_code == 0
+    assert second.exit_code == 0
+
+    with db.SessionLocal()() as s:
+        n = (
+            s.query(Batch)
+            .filter(Batch.input_filename == "<synthetic:orphan-reconcile>")
+            .count()
+        )
+        assert n == 1  # still exactly one — second call was a no-op
+
+
+def test_reconcile_handles_no_orphans_gracefully():
+    """With zero orphans, reconcile exits 0 and prints an informative
+    message (no synthetic rows created, no error)."""
+    runner = CliRunner()
+    result = runner.invoke(main, ["ack-orphans", "reconcile"])
+    assert result.exit_code == 0, result.output
+    assert "0" in result.output  # created=0, skipped=0

backend/tests/test_acks.py

@@ -51,7 +51,7 @@ def test_migration_0002_creates_acks_table():
 
 def test_migration_latest_idempotent_on_fresh_db():
     """Re-running the migration on the same DB must be a no-op (PRAGMA
-    user_version already at the latest version — currently 19 after
+    user_version already at the latest version — currently 20 after
     0004-0006 line_reconciliation, 0005 ta1_acks, SP9's 0007
     providers/payers/clearhouse, SP10's 0008 payer_rejected,
     SP11's 0009 audit_log, SP14's 0010 payer_rejected_acknowledged,
@@ -61,15 +61,16 @@ def test_migration_latest_idempotent_on_fresh_db():
     claims.matched_remittance_id index, SP27-Task 17's 0017
     claim.patient_control_number backfill UPDATE, SP28's 0018
     claim_acks join table, SP32's 0019
-    rendering_provider_npi + service_provider_npi)."""
+    rendering_provider_npi + service_provider_npi, and SP37's 0020
+    transaction_set_control_number)."""
     with db.engine().begin() as c:
         v1 = c.exec_driver_sql("PRAGMA user_version").scalar() or 0
-    assert v1 == 19
+    assert v1 == 20
     # A second run should not raise and should not bump the version.
     db_migrate.run(db.engine())
     with db.engine().begin() as c:
         v2 = c.exec_driver_sql("PRAGMA user_version").scalar() or 0
-    assert v2 == 19
+    assert v2 == 20
 
 
 def test_add_ack_persists_row():

backend/tests/test_api_rotate_key.py

@@ -82,7 +82,9 @@ class TestRotateKeyEndpointWiring:
                             lambda n, v: fake_kc.__setitem__(n, v) or True)
         # The endpoint's actual rekey is stubbed; the real PRAGMA
         # rekey mechanics are tested in test_db_crypto.py::TestRotateDbKey.
-        monkeypatch.setattr("cyclone.api._db_crypto.rotate_db_key", _stub_rotate_ok)
+        # SP36 Task 3: this endpoint moved from cyclone.api to
+        # cyclone.api_routers.admin; patch the live import surface.
+        monkeypatch.setattr("cyclone.api_routers.admin._db_crypto.rotate_db_key", _stub_rotate_ok)
         db.init_db()
         yield db_file, fake_kc
         db._reset_for_tests()
@@ -151,7 +153,7 @@ class TestRotateKeyEndpointWiring:
                 rotated_at=datetime.now(timezone.utc).isoformat(),
                 reason="simulated PRAGMA rekey failure",
             )
-        monkeypatch.setattr("cyclone.api._db_crypto.rotate_db_key", _fail_rotate)
+        monkeypatch.setattr("cyclone.api_routers.admin._db_crypto.rotate_db_key", _fail_rotate)
 
         _, fake_kc = _fake_encrypted_env
         before = dict(fake_kc)
@@ -187,7 +189,8 @@ class TestRotateKeyEndpointWiring:
         restore-key command."""
         from cyclone import db
         # Override the set_secret at the import-site of the endpoint.
-        monkeypatch.setattr("cyclone.api._secrets.set_secret", lambda n, v: False)
+        # SP36 Task 3: endpoint moved to cyclone.api_routers.admin.
+        monkeypatch.setattr("cyclone.api_routers.admin._secrets.set_secret", lambda n, v: False)
 
         from fastapi.testclient import TestClient
         from cyclone.api import app
@@ -202,10 +205,11 @@ class TestRotateKeyEndpointWiring:
         """A second concurrent rotation request gets 409 — only one
         rotation can run at a time (the module-level lock)."""
         monkeypatch.setattr(
-            "cyclone.api._secrets.set_secret", lambda n, v: True,
+            "cyclone.api_routers.admin._secrets.set_secret", lambda n, v: True,
         )
-        from cyclone import api as api_mod
-        api_mod._db_rotate_lock.acquire()
+        # SP36 Task 3: lock moved with the endpoint into admin router.
+        from cyclone.api_routers import admin as admin_mod
+        admin_mod._db_rotate_lock.acquire()
         try:
             from fastapi.testclient import TestClient
             from cyclone.api import app
@@ -214,4 +218,4 @@ class TestRotateKeyEndpointWiring:
             assert r.status_code == 409
             assert "in progress" in r.json()["detail"]
         finally:
-            api_mod._db_rotate_lock.release()
+            admin_mod._db_rotate_lock.release()

backend/tests/test_api_submit_batch.py

@@ -0,0 +1,354 @@
+"""SP37 Task 6: POST /api/submit-batch endpoint.
+
+Thin HTTP wrapper around ``cyclone.submission.submit_file``. Mirrors the
+``cyclone submit-batch`` CLI walker exactly: each ``batch-*-claims/*.x12``
+under ``ingest_dir`` is submitted in order, ``._*`` AppleDouble files are
+skipped, ``limit`` truncates after collection.
+
+Tests monkey-patch ``cyclone.api_routers.submission.submit_file`` so we
+never touch the real paramiko factory or a live MFT.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+
+from cyclone.submission.result import SubmitOutcome, SubmitResult
+
+_FIXTURE = Path(__file__).parent / "fixtures" / "submit-batch" / "single-claim.x12"
+
+
+@pytest.fixture
+def client(tmp_path) -> TestClient:
+    """Standard TestClient; conftest.py autouse handles DB + auth gate.
+
+    Does NOT touch env vars (per the plan-vs-reality correction in
+    Task 6's instructions). Seeds the clearhouse then flips
+    ``sftp_block.stub`` to ``False`` so the file-walking tests reach
+    the walker (otherwise the default-seeded stub=True trips the 409
+    guard before any per-file work runs). The ``stub_mode`` test
+    re-seeds stub=True explicitly so its 409 still fires.
+    """
+    from cyclone import db as db_mod
+    from cyclone.store import store as cycl_store
+
+    db_mod._reset_for_tests()
+    db_mod.init_db()
+    cycl_store.ensure_clearhouse_seeded()
+    ch = cycl_store.get_clearhouse()
+    # Flip stub=False so the walker actually runs (SFTP calls are
+    # intercepted via the submit_file monkey-patch in each test).
+    cycl_store.update_clearhouse(
+        ch.model_copy(update={"sftp_block": ch.sftp_block.model_copy(update={"stub": False})}),
+    )
+
+    from cyclone.api import app
+
+    return TestClient(app)
+
+
+def _stage_batch(tmp_path: Path, n: int) -> Path:
+    """Copy N copies of the single-claim fixture into ``batch-test-claims/``."""
+    batch_dir = tmp_path / "batch-test-claims"
+    batch_dir.mkdir()
+    payload = _FIXTURE.read_bytes()
+    for i in range(n):
+        (batch_dir / f"claim-{i}.x12").write_bytes(payload)
+    return batch_dir
+
+
+# --------------------------------------------------------------------------- #
+# Happy path + walker semantics
+# --------------------------------------------------------------------------- #
+
+
+def test_submit_batch_happy_path(client: TestClient, tmp_path, monkeypatch):
+    """3 valid 837 files → 200 + body shape with submitted=3 (or skipped=3 on re-run).
+
+    Monkey-patches ``cyclone.api_routers.submission.submit_file`` to
+    return a synthetic SUBMITTED SubmitResult per file. Skipped stays
+    possible because SubmitResult's batch_id is what matters and the
+    fake returns it consistently — but a fresh DB should always land
+    in the SUBMITTED branch.
+    """
+    _stage_batch(tmp_path, 3)
+
+    def _fake_submit(path, **_kw):
+        return SubmitResult(
+            file=path.name, outcome=SubmitOutcome.SUBMITTED, batch_id="b1",
+        )
+
+    monkeypatch.setattr(
+        "cyclone.api_routers.submission.submit_file", _fake_submit,
+    )
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    # Tolerate either counter — counter totals are deterministic with a
+    # fresh DB, but the assertion below focuses on the structural shape
+    # the operator cares about: every file is accounted for.
+    assert body["submitted"] + body["skipped"] + body["failed"] == 3
+    assert isinstance(body["results"], list)
+    assert len(body["results"]) == 3
+    for row in body["results"]:
+        assert "file" in row
+        assert "outcome" in row
+        assert "batch_id" in row
+        assert "error" in row
+
+
+def test_submit_batch_skips_apple_double_files(client: TestClient, tmp_path, monkeypatch):
+    """``._foo.x12`` AppleDouble files must be skipped (mirrors the CLI walker)."""
+    batch_dir = tmp_path / "batch-test-claims"
+    batch_dir.mkdir()
+    (batch_dir / "real.x12").write_bytes(_FIXTURE.read_bytes())
+    (batch_dir / "._real.x12").write_bytes(b"\x00\x01\x02")  # macOS AppleDouble noise
+
+    def _fake_submit(path, **_kw):
+        return SubmitResult(
+            file=path.name, outcome=SubmitOutcome.SUBMITTED, batch_id="b1",
+        )
+
+    monkeypatch.setattr(
+        "cyclone.api_routers.submission.submit_file", _fake_submit,
+    )
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    # Only real.x12 was submitted (one call); AppleDouble was skipped.
+    assert len(body["results"]) == 1
+    assert body["results"][0]["file"] == "real.x12"
+
+
+def test_submit_batch_limit_truncates(client: TestClient, tmp_path, monkeypatch):
+    """``limit=1`` against 3 files → body has exactly 1 result."""
+    _stage_batch(tmp_path, 3)
+
+    submitted_files: list[str] = []
+
+    def _fake_submit(path, **_kw):
+        submitted_files.append(path.name)
+        return SubmitResult(
+            file=path.name, outcome=SubmitOutcome.SUBMITTED, batch_id="b1",
+        )
+
+    monkeypatch.setattr(
+        "cyclone.api_routers.submission.submit_file", _fake_submit,
+    )
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False, "limit": 1},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert len(body["results"]) == 1
+    assert body["submitted"] + body["skipped"] + body["failed"] == 1
+    assert len(submitted_files) == 1
+
+
+def test_submit_batch_empty_ingest_dir_returns_422(client: TestClient, tmp_path):
+    """No batch-*-claims dir under ingest_dir → 422 (matches the CLI's exit 2 path)."""
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 422, resp.text
+
+
+def test_submit_batch_per_file_failure_keeps_status_200(
+    client: TestClient, tmp_path, monkeypatch,
+):
+    """A SUBMITTED + SFTP_FAILED mix → 200 with failed=1, submitted=1.
+
+    Per-file failures live in the JSON body, NOT in the status code.
+    The endpoint always returns 200 on a completed run.
+    """
+    _stage_batch(tmp_path, 2)
+
+    outcomes = iter([
+        SubmitResult(file="claim-0.x12", outcome=SubmitOutcome.SUBMITTED, batch_id="b1"),
+        SubmitResult(
+            file="claim-1.x12", outcome=SubmitOutcome.SFTP_FAILED,
+            batch_id="b2", error="sftp down",
+        ),
+    ])
+
+    def _fake_submit(path, **_kw):
+        return next(outcomes)
+
+    monkeypatch.setattr(
+        "cyclone.api_routers.submission.submit_file", _fake_submit,
+    )
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["submitted"] == 1
+    assert body["failed"] == 1
+    assert body["skipped"] == 0
+    assert len(body["results"]) == 2
+    # The failure row carries the error string so the operator can see
+    # what went wrong without a separate API call.
+    assert body["results"][1]["outcome"] == "sftp_failed"
+    assert body["results"][1]["error"] == "sftp down"
+
+
+def test_submit_batch_unexpected_exception_recorded_in_results(
+    client: TestClient, tmp_path, monkeypatch,
+):
+    """If submit_file raises, the file lands in results[] as a failed row.
+
+    The router catches the exception, builds a SubmitResult with
+    ``outcome=SubmitOutcome.UNEXPECTED_ERROR`` (followup #3 — distinct
+    from the typed SFTP_FAILED path so operators can tell "real bug"
+    from "SFTP server down"), and counts it as ``failed``. The full
+    error string (including exception class name) is in ``error``.
+    """
+    _stage_batch(tmp_path, 1)
+
+    def _explode(path, **_kw):
+        raise RuntimeError("kaboom")
+
+    monkeypatch.setattr(
+        "cyclone.api_routers.submission.submit_file", _explode,
+    )
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["failed"] == 1
+    # Followup #3: marker is UNEXPECTED_ERROR, NOT SFTP_FAILED — the
+    # exception class+message in ``error`` tells the operator this
+    # was a real exception (not a typed failure).
+    assert body["results"][0]["outcome"] == SubmitOutcome.UNEXPECTED_ERROR.value
+    assert "kaboom" in body["results"][0]["error"]
+    assert "RuntimeError" in body["results"][0]["error"]
+
+
+# --------------------------------------------------------------------------- #
+# Request validation
+# --------------------------------------------------------------------------- #
+
+
+def test_submit_batch_missing_ingest_dir_returns_422(client: TestClient):
+    """Body without ``ingest_dir`` → 422 from Pydantic (NOT your manual check)."""
+    resp = client.post("/api/submit-batch", json={"validate": False})
+    assert resp.status_code == 422, resp.text
+
+
+def test_submit_batch_ingest_dir_missing_on_disk_returns_422(
+    client: TestClient, tmp_path,
+):
+    """Body has a path that doesn't exist on disk → 422."""
+    resp = client.post(
+        "/api/submit-batch",
+        json={
+            "ingest_dir": str(tmp_path / "does-not-exist"),
+            "validate": False,
+        },
+    )
+    assert resp.status_code == 422, resp.text
+    assert "does not exist" in resp.text or "does-not-exist" in resp.text
+
+
+# --------------------------------------------------------------------------- #
+# Clearhouse posture (404 / 409)
+# --------------------------------------------------------------------------- #
+
+
+def test_submit_batch_no_clearhouse_returns_404(client: TestClient, tmp_path, monkeypatch):
+    """Delete the clearhouse row → endpoint must refuse with 404, not 500.
+
+    404 per the Task 6 status code contract: a missing clearhouse is a
+    config-level "missing" (4xx), not an unexpected exception.
+    """
+    from cyclone import db as db_mod
+    from cyclone.db import ClearhouseORM
+
+    # Wipe the seeded clearhouse row.
+    with db_mod.SessionLocal()() as s:
+        row = s.get(ClearhouseORM, 1)
+        if row is not None:
+            s.delete(row)
+            s.commit()
+
+    _stage_batch(tmp_path, 1)
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 404, resp.text
+    assert "clearhouse" in resp.text.lower()
+
+
+def test_submit_batch_stub_mode_returns_409(client: TestClient, tmp_path, monkeypatch):
+    """When the seeded clearhouse's ``sftp_block.stub`` is True → 409.
+
+    The default client fixture flips stub=False so file-walking tests
+    reach the walker. This test flips it back to True so the
+    stub-mode 409 guard fires before any per-file work runs.
+    """
+    from cyclone.store import store as cycl_store
+
+    ch = cycl_store.get_clearhouse()
+    assert ch is not None
+    # Re-flip stub=True (the default client fixture set it to False).
+    cycl_store.update_clearhouse(
+        ch.model_copy(update={
+            "sftp_block": ch.sftp_block.model_copy(update={"stub": True}),
+        }),
+    )
+
+    _stage_batch(tmp_path, 1)
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 409, resp.text
+    assert "stub" in resp.text.lower()
+
+
+# --------------------------------------------------------------------------- #
+# Auth gate
+# --------------------------------------------------------------------------- #
+
+
+def test_submit_batch_auth_gate(client: TestClient, tmp_path, monkeypatch):
+    """No cookie + AUTH_DISABLED=False → 401 from matrix_gate.
+
+    The conftest autouse fixture sets ``AUTH_DISABLED = True`` at
+    fixture setup and resets to False at teardown. Inside the test we
+    flip the module attribute so the gate fires — but to avoid leaking
+    the flip into a sibling test we use monkeypatch.setattr (which
+    restores at test teardown, before conftest's finally block runs).
+    """
+    import cyclone.auth.deps as auth_deps
+
+    monkeypatch.setattr(auth_deps, "AUTH_DISABLED", False)
+
+    _stage_batch(tmp_path, 1)
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 401, resp.text

backend/tests/test_apply_claim_ack_links.py

@@ -34,6 +34,7 @@ from cyclone.claim_acks import (
     lookup_claims_for_ack_set_response,
 )
 from cyclone.db import (
+    Ack,
     Batch,
     Claim,
     ClaimState,
@@ -744,6 +745,75 @@ def test_store_facade_exposes_claim_ack_methods():
         assert hasattr(store, name), f"missing CycloneStore.{name}"
 
 
+# ---------------------------------------------------------------------------
+# SP38 follow-up: regression test for the 277ca / ta1 control_number
+# behavior preserved across the find_ack_orphans refactor.
+# ---------------------------------------------------------------------------
+
+
+def test_find_ack_orphans_returns_control_number_for_all_kinds():
+    """For each ack kind, ``find_ack_orphans(kind)`` must return the
+    control_number from the per-kind source:
+
+      * 999 — from raw_json.envelope.control_number
+      * 277ca — from the ORM column ``control_number``
+      * ta1 — from the ORM column ``control_number``
+
+    Regression for sp38 commit ad14b56 which initially routed all
+    three kinds through _ack_control_number and broke 277ca/ta1
+    (the helper only knew 999). Found by pr-reviewer 2026-07-07.
+    """
+    import json
+    import cyclone.db as _db_mod
+    Two77caAck = _db_mod.Two77caAck
+    Ta1Ack = _db_mod.Ta1Ack
+    parsed_at = datetime.now(timezone.utc)
+
+    with db.SessionLocal()() as s:
+        # 999 orphan with envelope.control_number in raw_json
+        s.add(Ack(
+            source_batch_id="999-orph-test",
+            accepted_count=1, rejected_count=0, received_count=1,
+            ack_code="A",
+            parsed_at=parsed_at,
+            raw_json=json.dumps({
+                "envelope": {"control_number": "999-ctrl-num",
+                             "sender_id": "S", "receiver_id": "R",
+                             "transaction_date": "2024-01-01",
+                             "implementation_guide": "005010X231A1"},
+                "set_responses": [],
+                "summary": {},
+            }),
+        ))
+        # 277ca orphan with control_number in ORM column
+        s.add(Two77caAck(
+            source_batch_id="277ca-orph-test",
+            accepted_count=1, rejected_count=0,
+            control_number="277CA-CTRL-NUM",
+            parsed_at=parsed_at,
+        ))
+        # ta1 orphan with control_number in ORM column
+        s.add(Ta1Ack(
+            source_batch_id="ta1-orph-test",
+            ack_code="A",
+            control_number="TA1-CTRL-NUM",
+            parsed_at=parsed_at,
+        ))
+        s.commit()
+
+    orphans_999 = store.find_ack_orphans("999")
+    orphans_277ca = store.find_ack_orphans("277ca")
+    orphans_ta1 = store.find_ack_orphans("ta1")
+
+    ctrl_999 = [o["control_number"] for o in orphans_999 if "999-ctrl-num" in o["control_number"]]
+    ctrl_277ca = [o["control_number"] for o in orphans_277ca]
+    ctrl_ta1 = [o["control_number"] for o in orphans_ta1]
+
+    assert "999-ctrl-num" in ctrl_999, f"999 control_number not found: {ctrl_999}"
+    assert "277CA-CTRL-NUM" in ctrl_277ca, f"277ca control_number empty: {ctrl_277ca}"
+    assert "TA1-CTRL-NUM" in ctrl_ta1, f"ta1 control_number empty: {ctrl_ta1}"
+
+
 # ---------------------------------------------------------------------------
 # Step 2.1 — pure walk-through unit test (no DB) for the orphan tracking
 # ---------------------------------------------------------------------------

backend/tests/test_auth_permissions_matrix.py

@@ -0,0 +1,50 @@
+"""SP37 follow-up #1: Fail-closed for unregistered paths.
+
+The permissions matrix is fail-closed — endpoints not listed are denied
+(None). The pre-existing ``("POST", "/api/resubmit"): WRITE_ROLES``
+entry was a dead prefix that ONLY matched the exact path ``/api/resubmit``
+(which is not a registered route). The actual resubmit lives at
+``/api/inbox/rejected/resubmit`` (already covered by its own entry).
+
+This test pins the fail-closed invariant: ``/api/resubmit`` MUST have
+no granted permission because no route is registered there. Without
+this test, a future contributor could re-add the dead entry (or any
+similar dead prefix) and the auth system would silently grant access
+to a non-existent path.
+"""
+from __future__ import annotations
+
+import pytest
+
+from cyclone.auth.permissions import PERMISSIONS, allowed_roles
+
+
+def test_api_resubmit_exact_path_not_in_matrix():
+    """``/api/resubmit`` (exact, no children) must NOT be in the matrix.
+
+    The actual resubmit endpoint is ``/api/inbox/rejected/resubmit``,
+    which has its own entry. The pre-existing
+    ``("POST", "/api/resubmit"): WRITE_ROLES`` entry only matched the
+    exact path ``/api/resubmit`` and never any real route.
+    """
+    assert ("POST", "/api/resubmit") not in PERMISSIONS
+
+
+def test_api_resubmit_returns_none_via_allowed_roles():
+    """Fail-closed: ``allowed_roles("POST", "/api/resubmit")`` is None.
+
+    The matrix default is DENY. A registered entry that matches the
+    path would return a non-empty set of roles; the absence of any
+    entry should return None.
+    """
+    assert allowed_roles("POST", "/api/resubmit") is None
+
+
+@pytest.mark.parametrize("path", [
+    "/api/resubmit",
+    "/api/resubmit/",
+    "/api/resubmit/anything",
+])
+def test_api_resubmit_prefix_variants_all_deny(path):
+    """No path under ``/api/resubmit`` should match any permission entry."""
+    assert allowed_roles("POST", path) is None

backend/tests/test_batch_envelope_index_sp37.py

@@ -0,0 +1,126 @@
+"""SP37 Task 3: batch_envelope_index populates from BOTH columns.
+
+The dict returned by ``batch_envelope_index`` should resolve lookups
+by EITHER ``Batch.raw_result_json.envelope.control_number`` (ISA13,
+preserved) OR ``Batch.transaction_set_control_number`` (ST02, new in
+SP37 Task 2). One dict, both keys — a single ``.get(set_control_number)``
+call hits whichever matches, so the D10 Pass 1 join in
+:func:`cyclone.claim_acks.lookup_claims_for_ack_set_response` resolves
+999 AK201 (which echoes the source 837's ST02) back to the right batch
+even when ST02 != ISA13.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pytest
+
+from cyclone import db as db_mod
+from cyclone.db import Batch
+from cyclone.store.claim_acks import batch_envelope_index
+
+
+@pytest.fixture(autouse=True)
+def _db(tmp_path, monkeypatch):
+    """Per-test DB; conftest's autouse already wires one too, but we
+    pin the URL again so this module is self-contained if anyone ever
+    lifts it out of the conftest tree."""
+    monkeypatch.setenv("CYCLONE_DB_URL", f"sqlite:///{tmp_path}/test.db")
+    db_mod._reset_for_tests()
+    db_mod.init_db()
+    yield
+
+
+def _make_batch(
+    s,
+    *,
+    id: str,
+    icn: str,
+    stcn: str | None = None,
+    raw_json: dict | None = None,
+) -> Batch:
+    """Insert one Batch row whose envelope + ST02 mirror what
+    ``store.write.add_record`` writes for an 837P batch."""
+    row = Batch(
+        id=id,
+        kind="837p",
+        input_filename=id + ".x12",
+        parsed_at=datetime.now(timezone.utc),
+        raw_result_json=raw_json or {"envelope": {"control_number": icn}},
+        transaction_set_control_number=stcn,
+    )
+    s.add(row)
+    s.commit()
+    s.refresh(row)
+    return row
+
+
+def test_index_resolves_by_envelope_control_number():
+    """Pre-SP37 path: ISA13 (envelope.control_number) still resolves."""
+    with db_mod.SessionLocal()() as s:
+        _make_batch(s, id="b1", icn="ISA000001")
+    idx = batch_envelope_index()
+    assert idx.get("ISA000001") == "b1"
+
+
+def test_index_resolves_by_transaction_set_control_number():
+    """SP37 path: ST02 (transaction_set_control_number) resolves too.
+
+    The whole point of Task 3 — Gainwell batches have ST02 != ISA13,
+    so 999 AK201 echoes ST02 and must hit this branch.
+    """
+    with db_mod.SessionLocal()() as s:
+        _make_batch(
+            s, id="b2", icn="ISA000002", stcn="ST000002",
+            raw_json={"envelope": {"control_number": "ISA000002"}},
+        )
+    idx = batch_envelope_index()
+    assert idx.get("ST000002") == "b2"
+    # Backward compat: ISA still resolves.
+    assert idx.get("ISA000002") == "b2"
+
+
+def test_index_handles_row_with_no_transaction_set_control_number():
+    """Pre-migration rows (stcn NULL) should still resolve by ISA.
+
+    Spec says: 'Pre-migration rows (stcn NULL) should still resolve by ISA.'
+    Production row ``b1`` (the only one with claims) has ST02 NULL because
+    the migration's backfill only ran over rows whose raw_result_json
+    envelope had the ST02 key — and that row was written before the
+    parser populated it.
+    """
+    with db_mod.SessionLocal()() as s:
+        _make_batch(s, id="b3", icn="ISA000003")  # no stcn
+    idx = batch_envelope_index()
+    assert idx.get("ISA000003") == "b3"
+    assert idx.get("ST000003") is None
+
+
+def test_index_ignores_non_837_batches():
+    """835 batches don't contribute to the 999 join index.
+
+    The D10 two-pass join is specifically for 837 → 999 linkage; 835
+    remittances live on the response side of the loop and have no ST02
+    join key. Filtering by ``kind == "837p"`` keeps the index scoped
+    correctly and avoids an 835 row shadowing an 837 ST02 by accident.
+    """
+    with db_mod.SessionLocal()() as s:
+        # Add an 837 row first so we can prove the 835 doesn't leak in.
+        _make_batch(s, id="b-837", icn="ISA837", stcn="ST837")
+        # And an 835 row whose ISA13 / ST02 would otherwise pollute.
+        s.add(Batch(
+            id="b-835",
+            kind="835",
+            input_filename="b-835.x12",
+            parsed_at=datetime.now(timezone.utc),
+            raw_result_json={"envelope": {"control_number": "ISA999"}},
+            transaction_set_control_number="ST999",
+        ))
+        s.commit()
+    idx = batch_envelope_index()
+    # 837 row resolves both ways.
+    assert idx.get("ISA837") == "b-837"
+    assert idx.get("ST837") == "b-837"
+    # 835 row contributes nothing.
+    assert "ISA999" not in idx
+    assert "ST999" not in idx

backend/tests/test_batch_txn_set_cn.py

@@ -0,0 +1,103 @@
+"""SP37 Task 2: add_record populates Batch.transaction_set_control_number.
+
+The column should mirror the source 837 envelope's
+``transaction_set_control_number`` (ST02) so the join-key update in
+Task 3 can resolve 999 ``set_control_number`` (AK201) values back to
+the right batch. The 835 path leaves the column NULL because the
+field is an 837P-specific join key (835 remittances don't need to
+resolve back to a source 837 — they're the response side of the loop).
+"""
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+from cyclone import db as db_mod
+from cyclone.db import Batch
+from cyclone.parsers.parse_837 import parse as parse_837_text
+from cyclone.parsers.payer import PayerConfig
+from cyclone.store import store as cycl_store
+from cyclone.store.records import BatchRecord837, BatchRecord835
+
+FIXTURE_837 = Path(__file__).parent / "fixtures" / "minimal_837p.txt"
+FIXTURE_835 = Path(__file__).parent / "fixtures" / "minimal_835.txt"
+
+
+def test_add_record_populates_transaction_set_control_number_for_837():
+    """parse_837 → add_record writes the parsed ST02 onto the Batch row.
+
+    The fixture's ST02 (``991102977``) must round-trip into the new
+    ``batches.transaction_set_control_number`` column. This is the
+    join key Task 3's 999-ingest Pass 1 update relies on.
+    """
+    text = FIXTURE_837.read_text()
+    parsed = parse_837_text(text, PayerConfig.co_medicaid())
+
+    record = BatchRecord837(
+        id="b-txn-cn-1",
+        input_filename="minimal_837p.txt",
+        parsed_at=datetime.now(timezone.utc),
+        result=parsed,
+    )
+    cycl_store.add(record)
+
+    with db_mod.SessionLocal()() as s:
+        row = s.get(Batch, "b-txn-cn-1")
+        assert row is not None
+        assert row.transaction_set_control_number == parsed.envelope.transaction_set_control_number
+        # Sanity: the fixture's ST02 must be the parsed-and-stored value.
+        assert row.transaction_set_control_number == "991102977"
+
+
+def test_envelope_model_exposes_transaction_set_control_number():
+    """The Envelope Pydantic model carries the new field with a None default.
+
+    Guards against a regression where someone removes the field from
+    the model — the rest of the chain (parser + ORM + write path)
+    silently degrades to None if the model loses the attribute.
+    """
+    from cyclone.parsers.models import Envelope
+
+    env = Envelope(
+        sender_id="S",
+        receiver_id="R",
+        control_number="000000001",
+        transaction_date=date(2026, 1, 1),
+    )
+    assert env.transaction_set_control_number is None
+
+    env2 = env.model_copy(update={"transaction_set_control_number": "0001"})
+    assert env2.transaction_set_control_number == "0001"
+
+
+def test_add_record_leaves_835_column_null():
+    """835 batches don't carry an ST02 join key; column stays NULL.
+
+    The shared ``Envelope`` class is used by both 837P and 835 parsers,
+    but only ``parse_837`` populates ``transaction_set_control_number``.
+    For 835 records the field is None and ``add_record`` writes NULL
+    to the column — verified end-to-end via a real 835 ingest.
+    """
+    text = FIXTURE_835.read_text()
+    from cyclone.parsers.parse_835 import parse as parse_835_text
+    parsed835 = parse_835_text(text, payer_config=None)  # type: ignore[arg-type]
+
+    # Sanity: the 835 envelope also has the field (shared model class),
+    # but the parser doesn't populate it — so it must be None.
+    assert parsed835.envelope.transaction_set_control_number is None
+
+    record = BatchRecord835(
+        id="b-txn-cn-835-1",
+        input_filename="minimal_835.txt",
+        parsed_at=datetime.now(timezone.utc),
+        result=parsed835,
+    )
+    cycl_store.add(record)
+
+    with db_mod.SessionLocal()() as s:
+        row = s.get(Batch, "b-txn-cn-835-1")
+        assert row is not None
+        assert row.transaction_set_control_number is None
+        # And the kind/kind round-trip is correct (sanity check that
+        # we did exercise the 835 path, not the 837 path).
+        assert row.kind == "835"

backend/tests/test_db_migrate.py

@@ -126,14 +126,15 @@ def test_migration_latest_idempotent_on_fresh_db(tmp_path: Path) -> None:
     SP28 bumped it to 18 with the claim_acks join table.
     SP32 bumped it to 19 with rendering_provider_npi +
     service_provider_npi on claims and remittances.
+    SP37 bumped it to 20 with batch transaction_set_control_number.
     """
     engine = _fresh_engine(tmp_path)
     db_migrate.run(engine)
     v_after_first = _user_version(engine)
-    assert v_after_first == 19, f"expected head=19, got {v_after_first}"
+    assert v_after_first == 20, f"expected head=20, got {v_after_first}"
 
     db_migrate.run(engine)
-    assert _user_version(engine) == 19, "second run should not bump version"
+    assert _user_version(engine) == 20, "second run should not bump version"
 
 
 def test_drop_claims_unique_constraint_migration(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
@@ -159,7 +160,7 @@ def test_drop_claims_unique_constraint_migration(tmp_path: Path, monkeypatch: py
     engine = _fresh_engine(tmp_path)
 
     db_migrate.run(engine)
-    assert _user_version(engine) == 19, f"expected head=19, got {_user_version(engine)}"
+    assert _user_version(engine) == 20, f"expected head=20, got {_user_version(engine)}"
 
     # Two claims in one batch with the same patient_control_number
     # must be insertable. If 0015's table recreation re-introduced a

backend/tests/test_migration_0020.py

@@ -0,0 +1,210 @@
+"""Tests for migration 0020_add_batch_txn_set_control_number.sql.
+
+SP37 adds a nullable ``batches.transaction_set_control_number`` column
+populated from the parsed 837's ST02 (transaction set control number)
+on every write. The 999 ack join (Pass 1) needs to resolve by ST02,
+not ISA13, so this column is the join key. This migration is purely
+additive: nullable, no default, backfills from
+``raw_result_json.envelope.transaction_set_control_number`` where the
+source JSON already carries it.
+
+For the backfill-shape tests we point ``db_migrate.MIGRATIONS_DIR``
+at the real migrations directory, apply all migrations once to bring
+the fresh DB up to v20, insert representative rows, then replay the
+exact UPDATE statement the migration uses. Replaying the UPDATE
+proves the SQL works as intended even though the migration itself
+already ran over an empty table.
+
+The backfill UPDATE is loaded directly from the migration file (not
+a hand-maintained copy) so the test cannot drift from production —
+see :func:`_load_migration_0020_backfill_sql` and the regression
+locks in ``test_migration_0020_no_drift.py``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+import sqlalchemy as sa
+
+from cyclone import db_migrate
+
+
+def _migration_0020_path() -> Path:
+    return (
+        Path(__file__).parent.parent / "src" / "cyclone" / "migrations"
+        / "0020_add_batch_txn_set_control_number.sql"
+    )
+
+
+def _extract_update_statements(sql: str) -> list[str]:
+    """Split a migration into statements; return the UPDATE ones.
+
+    Mirrors db_migrate.run()'s splitter (strip ``--`` comments,
+    split on ``;``) so the test extraction can never disagree with
+    what the runner actually executes.
+    """
+    lines = [
+        line for line in sql.splitlines()
+        if not line.strip().startswith("--")
+    ]
+    cleaned = "\n".join(lines)
+    return [
+        stmt.strip() for stmt in cleaned.split(";")
+        if stmt.strip()
+    ]
+
+
+def _load_migration_0020_backfill_sql() -> str:
+    """Return migration 0020's UPDATE statement (the backfill).
+
+    Reads the migration file at test time and extracts its UPDATE.
+    Test code that needs to replay the backfill against rows that
+    didn't exist when init_db ran uses this helper — guarantees the
+    replayed SQL is byte-identical to what production will run.
+    """
+    sql = _migration_0020_path().read_text()
+    updates = [
+        s for s in _extract_update_statements(sql)
+        if s.upper().startswith("UPDATE ")
+    ]
+    assert len(updates) == 1, (
+        f"expected exactly 1 UPDATE in migration 0020, found {len(updates)}: {updates}"
+    )
+    return updates[0]
+
+
+def _fresh_engine(path: Path) -> sa.Engine:
+    return sa.create_engine(f"sqlite:///{path}", future=True)
+
+
+def _table_info(engine: sa.Engine, table: str) -> list[tuple]:
+    """Return PRAGMA table_info rows for ``table`` as plain tuples."""
+    with engine.connect() as conn:
+        return list(conn.exec_driver_sql(f"PRAGMA table_info({table});").tuples())
+
+
+def _real_migrations_dir() -> Path:
+    return Path(__file__).parent.parent / "src" / "cyclone" / "migrations"
+
+
+@pytest.fixture
+def migrated_engine(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    """Yield an engine at v20 against which every real migration has run.
+
+    Points ``db_migrate.MIGRATIONS_DIR`` at the real migrations
+    directory so the test exercises the actual 0020 file, then runs
+    the migration runner on a per-test fresh DB.
+    """
+    monkeypatch.setattr(db_migrate, "MIGRATIONS_DIR", _real_migrations_dir())
+    engine = _fresh_engine(tmp_path / "mig0020.db")
+    db_migrate.run(engine)
+
+    # Confirm head is 20 (every migration applied).
+    with engine.connect() as conn:
+        v = conn.exec_driver_sql("PRAGMA user_version").scalar() or 0
+    assert v == 20, f"expected migration head=20, got {v}"
+
+    yield engine
+    engine.dispose()
+
+
+def test_migration_0020_creates_column(migrated_engine) -> None:
+    """Migration 0020 adds ``transaction_set_control_number`` to ``batches``."""
+    cols = _table_info(migrated_engine, "batches")
+    col_names = {row[1] for row in cols}
+    assert "transaction_set_control_number" in col_names, (
+        "batches.transaction_set_control_number missing — migration 0020 did not run. "
+        f"Existing columns: {sorted(col_names)}"
+    )
+
+
+def test_migration_0020_column_is_nullable(migrated_engine) -> None:
+    """The new column is nullable (no DEFAULT, no NOT NULL) so existing
+    batches that don't yet carry the ST02 stay valid."""
+    cols = {row[1]: row for row in _table_info(migrated_engine, "batches")}
+    row = cols["transaction_set_control_number"]
+    # PRAGMA table_info tuples: (cid, name, type, notnull, dflt_value, pk)
+    assert row[3] == 0, f"notnull flag must be 0 (nullable), got {row[3]}"
+    assert row[4] is None, f"dflt_value must be NULL, got {row[4]!r}"
+    assert "TEXT" in (row[2] or "").upper(), f"expected TEXT column, got {row[2]!r}"
+
+
+def test_migration_0020_backfills_when_key_present(
+    migrated_engine: sa.Engine,
+) -> None:
+    """Replay the migration's backfill UPDATE against a row whose
+    ``raw_result_json`` carries the key — must populate the new column.
+
+    Replay (rather than waiting for ``db_migrate.run()`` to do it) is
+    the only way to test the SQL against a row that didn't exist when
+    init_db() ran; the migration's UPDATE naturally runs only over
+    pre-existing rows.
+    """
+    st02_value = "ST0001"
+    raw_json = {"envelope": {"transaction_set_control_number": st02_value}}
+
+    with migrated_engine.begin() as conn:
+        conn.exec_driver_sql(
+            "INSERT INTO batches (id, kind, input_filename, parsed_at, raw_result_json) "
+            "VALUES ('B-ST02-1', '837p', 'mig0020-st02.txt', '2026-07-07 00:00:00', ?)",
+            (json.dumps(raw_json),),
+        )
+        conn.exec_driver_sql(_load_migration_0020_backfill_sql())
+
+    with migrated_engine.connect() as conn:
+        row = conn.exec_driver_sql(
+            "SELECT transaction_set_control_number FROM batches WHERE id='B-ST02-1'"
+        ).first()
+    assert row is not None
+    assert row[0] == st02_value, (
+        f"backfill failed: expected {st02_value!r}, got {row[0]!r}"
+    )
+
+
+def test_migration_0020_backfill_conditional_on_key_present(
+    migrated_engine: sa.Engine,
+) -> None:
+    """Replay the UPDATE against a row whose ``raw_result_json`` does NOT
+    carry the key — must stay NULL. Proves the UPDATE is conditional
+    (the ``json_extract(...) IS NOT NULL`` guard) rather than
+    unconditionally overwriting with NULL."""
+    raw_json = {"envelope": {"control_number": "ISA0001"}}  # no txn-set key
+    with migrated_engine.begin() as conn:
+        conn.exec_driver_sql(
+            "INSERT INTO batches (id, kind, input_filename, parsed_at, raw_result_json) "
+            "VALUES ('B-NOST-1', '837p', 'mig0020-nost.txt', '2026-07-07 00:00:00', ?)",
+            (json.dumps(raw_json),),
+        )
+        conn.exec_driver_sql(_load_migration_0020_backfill_sql())
+
+    with migrated_engine.connect() as conn:
+        row = conn.exec_driver_sql(
+            "SELECT transaction_set_control_number FROM batches WHERE id='B-NOST-1'"
+        ).first()
+    assert row is not None
+    assert row[0] is None, (
+        f"backfill must not overwrite when key is absent; got {row[0]!r}"
+    )
+
+
+def test_migration_0020_backfill_handles_null_raw_result_json(
+    migrated_engine: sa.Engine,
+) -> None:
+    """A Batch row with ``raw_result_json IS NULL`` (the prior SP's
+    unparsed state) must not crash the backfill and must stay NULL."""
+    with migrated_engine.begin() as conn:
+        conn.exec_driver_sql(
+            "INSERT INTO batches (id, kind, input_filename, parsed_at) "
+            "VALUES ('B-NULL-1', '837p', 'mig0020-null.txt', '2026-07-07 00:00:00')"
+        )
+        conn.exec_driver_sql(_load_migration_0020_backfill_sql())
+
+    with migrated_engine.connect() as conn:
+        row = conn.exec_driver_sql(
+            "SELECT transaction_set_control_number FROM batches WHERE id='B-NULL-1'"
+        ).first()
+    assert row is not None
+    assert row[0] is None

backend/tests/test_migration_0020_no_drift.py

@@ -0,0 +1,66 @@
+"""SP37 follow-up #4: detect drift between test BACKFILL_SQL and migration SQL.
+
+Followup #1 of the SP37 final-state tracker. The previous test file
+maintained a hand-copied ``BACKFILL_SQL`` constant alongside the
+migration file. If a future contributor edited one but not the other,
+the test would silently replay a different SQL than production —
+defeating the regression test.
+
+The fix: ``test_migration_0020.py`` now reads the migration file at
+test time and extracts its UPDATE. This file imports the helper and
+pins the invariant — so a future contributor who edits the migration
+automatically gets the new SQL replayed in tests, and a contributor
+who removes the backfill UPDATE gets a loud extraction failure.
+"""
+from __future__ import annotations
+
+from test_migration_0020 import (
+    _extract_update_statements,
+    _load_migration_0020_backfill_sql,
+    _migration_0020_path,
+)
+
+
+def test_migration_0020_backfill_sql_uses_migration_file():
+    """The backfill SQL used in tests must come from the migration file.
+
+    Guards against the previous pattern of a hand-maintained
+    BACKFILL_SQL constant that could drift from the actual migration.
+    """
+    sql = _load_migration_0020_backfill_sql()
+    # Sanity check: the SQL targets batches.transaction_set_control_number
+    # via json_extract on raw_result_json. If a contributor changes
+    # the column name or the JSON path, this assertion catches it.
+    assert "UPDATE batches" in sql
+    assert "SET transaction_set_control_number" in sql
+    assert "json_extract(raw_result_json" in sql
+    assert "$.envelope.transaction_set_control_number" in sql
+
+
+def test_migration_0020_backfill_sql_is_non_empty_single_statement():
+    """The helper returns a non-empty SQL string suitable for direct
+    execution via exec_driver_sql. The existing
+    ``test_migration_0020.py`` tests use this helper to replay the
+    SQL against representative rows — so any successful replay
+    exercises the migration's actual UPDATE.
+    """
+    sql = _load_migration_0020_backfill_sql()
+    assert sql  # non-empty
+    assert ";" not in sql  # already stripped by the splitter
+
+
+def test_migration_0020_has_exactly_one_update():
+    """Guardrail: if a future migration adds a second UPDATE, the
+    extraction fails loudly so the test author can decide which one
+    is the backfill.
+    """
+    sql = _migration_0020_path().read_text()
+    updates = [
+        s for s in _extract_update_statements(sql)
+        if s.upper().startswith("UPDATE ")
+    ]
+    assert len(updates) == 1, (
+        f"migration 0020 should have exactly 1 UPDATE (the backfill); "
+        f"found {len(updates)}. If you added a second UPDATE, update "
+        f"_load_migration_0020_backfill_sql() to pick the right one."
+    )

backend/tests/test_routes_have_auth_coverage.py

@@ -0,0 +1,107 @@
+"""Audit guard: every registered route MUST have a matching PERMISSIONS entry.
+
+This is the inverse of ``test_auth_permissions_matrix.py``: that one pins
+the fail-closed invariant for a specific dead prefix; this one pins the
+opposite — for every route that actually exists, the matrix MUST grant
+some role (otherwise operators hitting the route would get 403s in
+production but the tests would still pass because ``TestClient`` bypasses
+the ``matrix_gate`` middleware).
+
+Found via a one-shot audit on 2026-07-07, three production bugs surfaced:
+
+  - DELETE /api/acks/{kind}/{ack_id}/match-claim/{claim_id}
+    (used by the Inbox "Matched claims" operator flow to unlink a wrong
+    match)
+  - GET  /api/dashboard/kpis (dashboard summary cards)
+  - GET  /api/inbox/ack-orphans (Inbox "Ack orphans" lane — already
+    wired into the frontend via ``src/hooks/useAckOrphans.ts`` and
+    ``src/components/inbox/AckOrphansLane.tsx``)
+
+All three had registered routes + tests + (for #3) frontend callers,
+yet ``allowed_roles(method, path)`` returned ``None`` because no matrix
+entry covered the path. Fail-closed denied every role, so the operators
+saw 403s in production but every CI test passed.
+
+This test enumerates the real FastAPI route table (after all
+``include_router`` calls) and asserts each route has coverage. If a
+contributor adds a new route without a matching matrix entry, this test
+fires.
+"""
+from __future__ import annotations
+
+import pytest
+from fastapi.routing import APIRoute
+
+from cyclone.api import app
+from cyclone.auth.permissions import allowed_roles
+
+
+# Endpoints mounted by FastAPI itself (docs, openapi schema) — not part
+# of the application surface. Skipped from the coverage assertion because
+# they aren't protected by ``matrix_gate``.
+_INTERNAL_PATHS = frozenset(("/docs", "/openapi.json", "/redoc", "/docs/oauth2-redirect"))
+
+
+def _collect_routes(fastapi_app):
+    """Recursively collect (method, full_path) for every registered route.
+
+    FastAPI mounts sub-routers via ``_IncludedRouter`` wrappers; their
+    ``original_router`` exposes the routes mounted at the include point.
+    We recurse into those so every endpoint appears exactly once with its
+    full path (e.g. ``/api/auth/me``), no prefix doubling.
+    """
+    out: list[tuple[str, str]] = []
+    for r in fastapi_app.routes:
+        if isinstance(r, APIRoute):
+            for m in r.methods or set():
+                if m in {"GET", "POST", "PATCH", "DELETE", "PUT"}:
+                    out.append((m, r.path))
+        elif hasattr(r, "original_router"):
+            out.extend(_collect_routes(r.original_router))
+    return out
+
+
+ALL_ROUTES = _collect_routes(app)
+
+
+def test_internal_paths_not_in_collection():
+    """Sanity: docs/openapi/redoc are NOT in the collected routes because
+    we skip them via the APIRoute isinstance check (they're mounted as
+    Starlette Routes, not APIRoutes)."""
+    paths = {p for _, p in ALL_ROUTES}
+    assert not any(p in _INTERNAL_PATHS for p in paths), (
+        "FastAPI internal docs paths leaked into route collection — "
+        "fix _collect_routes() to filter on APIRoute, not method set"
+    )
+
+
+def test_every_route_has_matrix_coverage():
+    """Every registered (method, path) MUST match at least one PERMISSIONS entry.
+
+    Fail-closed means missing entries silently deny the route in
+    production. The frontend may have a working caller + the test suite
+    may be green (TestClient bypasses auth) but operators will see 403s.
+
+    To fix an uncovered route, add a ``("METHOD", "/api/foo"): ROLES``
+    entry to ``cyclone.auth.permissions.PERMISSIONS``. Prefix entries
+    (e.g. ``/api/inbox``) match child paths, so adding a prefix is
+    usually the lightest-touch fix.
+    """
+    uncovered = [
+        (m, p) for m, p in ALL_ROUTES if allowed_roles(m, p) is None
+    ]
+    assert not uncovered, (
+        "These routes are registered but have NO matching PERMISSIONS "
+        "entry — they will be denied (403) in production:\n  "
+        + "\n  ".join(f"{m} {p}" for m, p in sorted(uncovered))
+    )
+
+
+@pytest.mark.parametrize("verb,path", sorted(ALL_ROUTES))
+def test_each_route_individually_has_coverage(verb, path):
+    """Per-route parametrised coverage — failure output points at the
+    exact missing route. Complements the aggregate test by surfacing
+    each gap as its own test report entry."""
+    assert allowed_roles(verb, path) is not None, (
+        f"{verb} {path} has no PERMISSIONS entry — fail-closed will deny it"
+    )

backend/tests/test_sftp_client_stat.py

@@ -0,0 +1,150 @@
+"""SP37 follow-up #5: SftpClient.stat() method.
+
+The SftpClient wrapper previously exposed ``write_file``,
+``list_inbound``, ``list_inbound_names``, ``download_inbound``, and
+``read_file`` — but NO ``stat()``. The canonical
+``cyclone.submission.submit_file`` helper needs to compare the local
+file size against the remote file size for idempotency; the lack of
+``stat()`` forced the helper to bypass the wrapper and open paramiko
+directly (see ``submission/core.py:_default_sftp_factory``).
+
+This file adds a ``stat()`` method to the wrapper so the helper can
+use ``SftpClient(block=b)`` instead of bypassing the wrapper. Tests
+cover the stub implementation only (paramiko real-mode tests would
+need a real SFTP server).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from cyclone.clearhouse import SftpClient, SftpStat
+from cyclone.providers import SftpBlock
+
+
+def _stub_block(staging_dir: Path) -> SftpBlock:
+    return SftpBlock(
+        host="mft.example.com",
+        port=22,
+        username="user",
+        auth={"password_keychain_account": "x"},
+        paths={"inbound": "/inbound", "outbound": "/outbound"},
+        staging_dir=str(staging_dir),
+        stub=True,
+    )
+
+
+@pytest.fixture
+def staging(tmp_path: Path) -> Path:
+    """A staging dir pre-populated with one file. Mirrors what the
+    SP9 stub layout looks like when an operator has dropped a real
+    inbound file for testing."""
+    inbound = tmp_path / "inbound"
+    inbound.mkdir(parents=True)
+    (inbound / "test.txt").write_bytes(b"hello world\n")
+    return tmp_path
+
+
+# ---- SftpStat dataclass ----------------------------------------------------- #
+
+
+def test_sftp_stat_dataclass_exists():
+    """The wrapper exposes a small SftpStat dataclass for the result.
+
+    Mirrors the paramiko ``SFTPAttributes`` shape (at least ``size``)
+    but keeps the public surface narrow so callers can use it
+    without depending on paramiko.
+    """
+    assert SftpStat is not None
+    stat = SftpStat(size=42, modified_at=None)
+    assert stat.size == 42
+    assert stat.modified_at is None
+
+
+def test_sftp_stat_is_frozen():
+    """SftpStat is a frozen dataclass so it can be hashed / used as a
+    cache key by future callers without surprise mutation."""
+    from dataclasses import FrozenInstanceError
+
+    stat = SftpStat(size=1, modified_at=None)
+    with pytest.raises(FrozenInstanceError):
+        stat.size = 2  # type: ignore[misc]
+
+
+# ---- Public method --------------------------------------------------------- #
+
+
+def test_sftp_client_has_stat_method():
+    """``SftpClient`` exposes a ``stat(remote_path)`` public method.
+
+    Guards the API surface — a future contributor who renames or
+    removes ``stat()`` (forcing the helper to bypass the wrapper
+    again) would break this test, prompting them to update the
+    helper instead.
+    """
+    assert hasattr(SftpClient, "stat")
+    assert callable(SftpClient.stat)
+
+
+def test_sftp_client_stat_returns_size_in_stub_mode(staging: Path):
+    """Stub mode: ``stat(remote_path)`` returns the local staging
+    file's size via ``os.stat_result.st_size``. Mirrors what a real
+    paramiko ``SFTPAttributes.st_size`` would return for a remote file.
+    """
+    client = SftpClient(block=_stub_block(staging))
+    stat = client.stat("/inbound/test.txt")
+    assert stat.size == len(b"hello world\n")
+
+
+def test_sftp_client_stat_returns_modified_at_in_stub_mode(staging: Path):
+    """Stub mode: ``stat`` populates ``modified_at`` from the local
+    file's mtime. Mirrors paramiko's behavior for parity."""
+    client = SftpClient(block=_stub_block(staging))
+    stat = client.stat("/inbound/test.txt")
+    assert stat.modified_at is not None
+
+
+def test_sftp_client_stat_raises_for_missing_file(staging: Path):
+    """Stub mode: ``stat`` raises ``FileNotFoundError`` for a path
+    that doesn't exist locally — matches the real paramiko behavior
+    (which raises ``IOError``/``FileNotFoundError``). The helper's
+    SKIPPED-outcome short-circuit depends on this exception type.
+    """
+    client = SftpClient(block=_stub_block(staging))
+    with pytest.raises(FileNotFoundError):
+        client.stat("/inbound/missing.txt")
+
+
+def test_sftp_client_stat_handles_large_file(staging: Path):
+    """Stub mode: ``stat`` returns the correct size for non-trivial files.
+
+    Sanity check: the size path doesn't truncate or accidentally
+    cast (e.g. to int8) on larger files.
+    """
+    payload = b"x" * (1024 * 1024)  # 1 MiB
+    (staging / "inbound" / "big.bin").write_bytes(payload)
+    client = SftpClient(block=_stub_block(staging))
+    stat = client.stat("/inbound/big.bin")
+    assert stat.size == 1024 * 1024
+
+
+def test_sftp_client_stat_supports_idempotency_check(staging: Path):
+    """The submission helper's idempotency check works against the
+    wrapper now.
+
+    Replays the SKIPPED-outcome check from
+    ``cyclone.submission.submit_file`` (lines 178-182) using the
+    wrapper directly. Before this follow-up, the helper had to open
+    paramiko directly because the wrapper lacked ``stat()``.
+    """
+    payload = b"identical contents"
+    (staging / "outbound").mkdir(parents=True, exist_ok=True)
+    (staging / "outbound" / "claim.x12").write_bytes(payload)
+
+    client = SftpClient(block=_stub_block(staging))
+    local_size = len(payload)
+    # stat() returns the size that was previously uploaded.
+    remote_stat = client.stat("/outbound/claim.x12")
+    assert remote_stat.size == local_size  # idempotency check passes
+    # → SKIPPED outcome in the submission helper

backend/tests/test_submission.py

@@ -0,0 +1,214 @@
+"""SP37 Task 4: submit_file owns parse → DB write → SFTP upload.
+
+Tests use a fake SFTP client to avoid hitting the real clearhouse.
+The DB path is real (autouse ``_auto_init_db`` fixture in conftest.py)
+so the join-key wiring is exercised end-to-end.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from cyclone import db as db_mod
+from cyclone.submission.core import submit_file
+from cyclone.submission.result import SubmitOutcome
+
+
+_FIXTURE = Path(__file__).parent / "fixtures" / "submit-batch" / "single-claim.x12"
+
+
+class _FakeSftp:
+    """Implements just enough of SftpClient for submit_file's idempotency check.
+
+    After every successful ``write_file``, the file is added to
+    ``existing_files`` keyed by remote_path with the byte size — so a
+    subsequent ``stat`` returns the right size and the idempotency
+    check in ``submit_file`` short-circuits to ``SKIPPED``. Without
+    this bookkeeping, every re-run would look like the file isn't on
+    the remote and would re-upload.
+    """
+
+    def __init__(self, existing_files: dict[str, int] | None = None):
+        self.existing_files = existing_files or {}
+        self.put_calls: list[tuple[str, bytes]] = []
+
+    def stat(self, path: str):
+        if path not in self.existing_files:
+            raise IOError(f"no such file: {path}")
+        m = MagicMock()
+        m.st_size = self.existing_files[path]
+        return m
+
+    def write_file(self, remote_path: str, content: bytes):
+        self.put_calls.append((remote_path, content))
+        # Mirror the upload so a subsequent stat() sees it.
+        self.existing_files[remote_path] = len(content)
+
+
+def test_submit_file_happy_path():
+    """parse → DB write → SFTP upload, all steps succeed."""
+    fake = _FakeSftp()
+    sftp_block = MagicMock()
+    sftp_block.stub = False
+    sftp_block.paths = {"outbound": "/ToHPE"}
+
+    result = submit_file(
+        _FIXTURE,
+        sftp_block=sftp_block,
+        actor="test",
+        validate=True,
+        sftp_client_factory=lambda _block: fake,
+    )
+
+    assert result.outcome == SubmitOutcome.SUBMITTED
+    assert result.batch_id is not None
+    assert len(fake.put_calls) == 1
+    # DB row landed.
+    with db_mod.SessionLocal()() as s:
+        assert s.get(db_mod.Batch, result.batch_id) is not None
+
+
+def test_submit_file_skipped_when_remote_size_matches():
+    """Re-running submit_file on an already-uploaded file is SKIPPED.
+
+    The ``SKIPPED`` outcome is reached via the SFTP ``stat()`` check
+    (not via the DB) — same-size remote file ⇒ idempotency short-circuit.
+    Re-runs therefore don't emit a duplicate ``clearhouse.submitted``
+    audit event.
+    """
+    fake = _FakeSftp()
+    sftp_block = MagicMock(stub=False, paths={"outbound": "/ToHPE"})
+    factory = lambda _b: fake
+
+    r1 = submit_file(_FIXTURE, sftp_block=sftp_block, actor="t", sftp_client_factory=factory)
+    r2 = submit_file(_FIXTURE, sftp_block=sftp_block, actor="t", sftp_client_factory=factory)
+
+    # First call SUBMITTED, second call SKIPPED (size match on stat).
+    assert r1.outcome == SubmitOutcome.SUBMITTED
+    assert r2.outcome == SubmitOutcome.SKIPPED
+
+
+def test_submit_file_parse_fail(tmp_path):
+    """Bad 837 → PARSE_FAILED, no DB write, no SFTP call."""
+    bad = tmp_path / "bad.x12"
+    bad.write_bytes(b"not x12")
+    sftp_block = MagicMock(stub=False, paths={"outbound": "/ToHPE"})
+    fake = _FakeSftp()
+    factory = lambda _b: fake
+
+    result = submit_file(bad, sftp_block=sftp_block, actor="t", sftp_client_factory=factory)
+    assert result.outcome == SubmitOutcome.PARSE_FAILED
+    assert len(fake.put_calls) == 0
+
+
+def test_submit_file_db_fail(monkeypatch):
+    """If add raises, no SFTP call is made (DB-first invariant)."""
+    from cyclone.store import store as cycl_store
+    monkeypatch.setattr(cycl_store, "add", MagicMock(side_effect=RuntimeError("db down")))
+
+    sftp_block = MagicMock(stub=False, paths={"outbound": "/ToHPE"})
+    fake = _FakeSftp()
+    factory = lambda _b: fake
+
+    result = submit_file(_FIXTURE, sftp_block=sftp_block, actor="t", sftp_client_factory=factory)
+    assert result.outcome == SubmitOutcome.DB_FAILED
+    assert len(fake.put_calls) == 0
+
+
+def test_submit_file_sftp_fail():
+    """SFTP failure after DB write → SFTP_FAILED, DB row still present."""
+
+    class _Boom:
+        def stat(self, _p):
+            raise IOError("nope")
+        def write_file(self, _p, _c):
+            raise RuntimeError("sftp down")
+
+    sftp_block = MagicMock(stub=False, paths={"outbound": "/ToHPE"})
+    factory = lambda _b: _Boom()
+
+    result = submit_file(_FIXTURE, sftp_block=sftp_block, actor="t", sftp_client_factory=factory)
+    assert result.outcome == SubmitOutcome.SFTP_FAILED
+    # DB row was written before the SFTP call.
+    assert result.batch_id is not None
+    with db_mod.SessionLocal()() as s:
+        assert s.get(db_mod.Batch, result.batch_id) is not None
+
+
+def test_submit_file_payer_mismatch():
+    """PAYER_MISMATCH → no DB write, no SFTP call.
+
+    We monkeypatch ``parse_837_text`` to return a single claim whose
+    payer.id is ``OTHER_PAYER`` (the helper gates on the first
+    claim's payer — same posture as the legacy ``resubmit_rejected_claims``
+    CLI at cli.py:657-668).
+    """
+    from unittest.mock import patch
+
+    bad_claim = MagicMock()
+    bad_claim.payer.id = "OTHER_PAYER"
+    parsed_with_bad_payer = MagicMock()
+    parsed_with_bad_payer.claims = [bad_claim]
+    parsed_with_bad_payer.parsed_at = None
+    parsed_with_bad_payer.envelope.transaction_set_control_number = "ST123"
+
+    fake = _FakeSftp()
+    sftp_block = MagicMock(stub=False, paths={"outbound": "/ToHPE"})
+
+    with patch("cyclone.submission.core.parse_837_text", return_value=parsed_with_bad_payer):
+        result = submit_file(
+            _FIXTURE,
+            sftp_block=sftp_block,
+            actor="t",
+            validate=True,
+            sftp_client_factory=lambda _b: fake,
+        )
+    assert result.outcome == SubmitOutcome.PAYER_MISMATCH
+    assert "OTHER_PAYER" in (result.error or "")
+    assert len(fake.put_calls) == 0
+
+
+def test_submit_file_uses_default_paramiko_factory(monkeypatch):
+    """When no factory is supplied, helper should use paramiko directly
+    (not SftpClient wrapper, which lacks stat()).
+    """
+    fake_paramiko_sftp = _FakeSftp()
+    monkeypatch.setattr(
+        "cyclone.submission.core._default_sftp_factory",
+        lambda _block: fake_paramiko_sftp,
+    )
+
+    sftp_block = MagicMock()
+    sftp_block.stub = False
+    sftp_block.paths = {"outbound": "/ToHPE"}
+
+    result = submit_file(
+        _FIXTURE,
+        sftp_block=sftp_block,
+        actor="t",
+        validate=True,
+        # NO sftp_client_factory — should use the paramiko default
+    )
+    assert result.outcome == SubmitOutcome.SUBMITTED
+    assert len(fake_paramiko_sftp.put_calls) == 1
+
+
+def test_submit_batch_cli_help():
+    """`cyclone submit-batch --help` exits 0 and shows the flags.
+
+    Uses ``click.testing.CliRunner`` instead of ``subprocess.run`` for
+    ~10ms vs ~200ms per call. Same assertions — the CliRunner
+    ``result.exit_code`` matches the subprocess returncode, and
+    ``result.output`` is the Click-rendered help text (subprocess's
+    stdout).
+    """
+    from click.testing import CliRunner
+
+    from cyclone.cli import main
+
+    runner = CliRunner()
+    result = runner.invoke(main, ["submit-batch", "--help"])
+    assert result.exit_code == 0, result.output
+    assert "--ingest-dir" in result.output

backend/tests/test_unexpected_error_outcome.py

@@ -0,0 +1,139 @@
+"""SP37 follow-up #3: SubmitOutcome.UNEXPECTED_ERROR for non-typed failures.
+
+The router's per-file try/except previously coerced every unexpected
+exception to ``SubmitOutcome.SFTP_FAILED`` because the helper had no
+"unknown failure" enum value. That was misleading — a ``RuntimeError``
+from ``cycl_store.add`` (e.g. ``RuntimeError("db down")``) is
+definitely not an SFTP failure.
+
+This test pins the new behavior: ``SubmitOutcome.UNEXPECTED_ERROR``
+exists, the API surfaces it under the JSON key ``"unexpected_error"``,
+and the typed SFTP_FAILED path is reserved for actual SFTP failures.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+
+
+_FIXTURE = Path(__file__).parent / "fixtures" / "submit-batch" / "single-claim.x12"
+
+
+@pytest.fixture
+def client(tmp_path) -> TestClient:
+    """Standard TestClient; conftest.py autouse handles DB + auth gate.
+
+    Seeds the clearhouse then flips sftp_block.stub to False so the
+    file-walking tests reach the walker. Matches the fixture shape in
+    test_api_submit_batch.py — local because only these two test files
+    need it (no conftest move yet).
+    """
+    from cyclone import db as db_mod
+    from cyclone.store import store as cycl_store
+
+    db_mod._reset_for_tests()
+    db_mod.init_db()
+    cycl_store.ensure_clearhouse_seeded()
+    ch = cycl_store.get_clearhouse()
+    cycl_store.update_clearhouse(
+        ch.model_copy(update={"sftp_block": ch.sftp_block.model_copy(update={"stub": False})}),
+    )
+
+    from cyclone.api import app
+
+    return TestClient(app)
+
+
+def test_unexpected_error_enum_value_exists():
+    """The enum MUST have UNEXPECTED_ERROR so the API can distinguish
+    a non-typed exception from a real SFTP failure.
+    """
+    from cyclone.submission.result import SubmitOutcome
+
+    assert hasattr(SubmitOutcome, "UNEXPECTED_ERROR")
+    assert SubmitOutcome.UNEXPECTED_ERROR.value == "unexpected_error"
+
+
+def test_unexpected_error_is_distinct_from_typed_failures():
+    """The new value must NOT collide with any existing failure value."""
+    from cyclone.submission.result import SubmitOutcome
+
+    # Compare against the typed failure values only (not UNEXPECTED_ERROR
+    # itself, which would trivially be in any set including it).
+    typed_failure_values = {
+        SubmitOutcome.SUBMITTED.value,
+        SubmitOutcome.SKIPPED.value,
+        SubmitOutcome.PARSE_FAILED.value,
+        SubmitOutcome.PAYER_MISMATCH.value,
+        SubmitOutcome.DB_FAILED.value,
+        SubmitOutcome.SFTP_FAILED.value,
+    }
+    assert SubmitOutcome.UNEXPECTED_ERROR.value not in typed_failure_values
+
+
+def test_router_maps_unexpected_exception_to_unexpected_error(client: TestClient, monkeypatch, tmp_path):
+    """If submit_file raises an unexpected exception, the API surfaces
+    ``outcome="unexpected_error"`` (not ``"sftp_failed"``).
+    """
+    from cyclone.submission.result import SubmitResult, SubmitOutcome
+
+    # Stage one file so the walker has something to submit.
+    batch_dir = tmp_path / "batch-test-claims"
+    batch_dir.mkdir()
+    (batch_dir / "claim-0.x12").write_bytes(_FIXTURE.read_bytes())
+
+    def _explode(path, **_kw):
+        raise RuntimeError("kaboom")
+
+    monkeypatch.setattr(
+        "cyclone.api_routers.submission.submit_file", _explode,
+    )
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["failed"] == 1
+    # The operator-visible outcome MUST be "unexpected_error", not "sftp_failed".
+    assert body["results"][0]["outcome"] == SubmitOutcome.UNEXPECTED_ERROR.value
+    # The full exception class + message stays in ``error`` so the
+    # operator can tell it was a real exception, not a typed failure.
+    assert "kaboom" in body["results"][0]["error"]
+    assert "RuntimeError" in body["results"][0]["error"]
+
+
+def test_typed_sftp_failure_still_uses_sftp_failed(client: TestClient, monkeypatch, tmp_path):
+    """Typed SFTP failure (returned by submit_file) MUST still surface as
+    ``outcome="sftp_failed"`` — the new enum value is for *unexpected*
+    exceptions only, not the typed SFTP_FAILED path.
+    """
+    from cyclone.submission.result import SubmitResult, SubmitOutcome
+
+    batch_dir = tmp_path / "batch-test-claims"
+    batch_dir.mkdir()
+    (batch_dir / "claim-0.x12").write_bytes(_FIXTURE.read_bytes())
+
+    def _fake_submit(path, **_kw):
+        return SubmitResult(
+            file=path.name,
+            outcome=SubmitOutcome.SFTP_FAILED,
+            error="sftp connection refused",
+        )
+
+    monkeypatch.setattr(
+        "cyclone.api_routers.submission.submit_file", _fake_submit,
+    )
+
+    resp = client.post(
+        "/api/submit-batch",
+        json={"ingest_dir": str(tmp_path), "validate": False},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["failed"] == 1
+    assert body["results"][0]["outcome"] == SubmitOutcome.SFTP_FAILED.value
+    assert body["results"][0]["error"] == "sftp connection refused"

docs/RUNBOOK.md

@@ -138,3 +138,230 @@ started without the secret mount), the scheduler surfaces a
 `RuntimeError` at the next tick that names the env var and the
 missing path — this is intentional, so a silent fall-through doesn't
 mask a real misconfiguration.
+
+## Manual SFTP mode (this box's current posture)
+
+Use this when the host's IP isn't whitelisted with Gainwell's MFT, when
+you don't want a daemon polling every minute, or when you prefer to
+drag-drop files with FileZilla / WinSCP. The seeded `dzinesco`
+clearhouse ships in this mode (`sftp_block.stub: true`); no daemon
+changes required.
+
+**Posture.** `SftpClient` reads/writes to local staging instead of
+`mft.gainwelltechnologies.com`:
+
+- Outbound (`write_file`): `./var/sftp/staging/CO XIX/PROD/coxix_prod_11525703/ToHPE/`
+- Inbound (`list_inbound`): `./var/sftp/staging/CO XIX/PROD/coxix_prod_11525703/FromHPE/`
+
+(Paths are relative to the backend cwd; create the directories if
+absent.)
+
+### Daily flow (manual mode)
+
+1. **Pull inbound from Gainwell** with your SFTP client:
+   `/CO XIX/PROD/coxix_prod_11525703/FromHPE/`
+2. **Stage locally** in `./var/sftp/staging/CO XIX/PROD/coxix_prod_11525703/FromHPE/`
+   (or, equivalently, drop them in `/home/tyler/dev/cyclone/ingest/`
+   and copy in).
+3. **Process** with `pull-inbound` (writes acks/835s to DB, dedupes
+   via `processed_inbound_files`):
+
+   ```bash
+   cd /home/tyler/dev/cyclone/backend
+   mkdir -p "./var/sftp/staging/CO XIX/PROD/coxix_prod_11525703/FromHPE"
+   cp /home/tyler/dev/cyclone/ingest/*.x12 \
+      "./var/sftp/staging/CO XIX/PROD/coxix_prod_11525703/FromHPE/"
+   .venv/bin/python -m cyclone pull-inbound --date 20260701
+   .venv/bin/python -m cyclone pull-inbound --date 20260702
+   .venv/bin/python -m cyclone pull-inbound --date 20260703
+   ```
+
+4. **Submit outbound** with `POST /api/clearhouse/submit` (writes
+   serialized 837P files into the stub staging dir; you drag-drop
+   them to your SFTP client's `/CO XIX/PROD/coxix_prod_11525703/ToHPE/`).
+
+### Backfill a backlog
+
+`ingest/` often holds days of unprocessed acks. The copy + per-date
+`pull-inbound` flow above clears it. Files already in
+`processed_inbound_files` are skipped automatically — to re-process,
+delete the row first (`DELETE FROM processed_inbound_files WHERE name = ...`).
+
+### Submitting claims (canonical — SP37)
+
+For 837P files generated upstream (dzinesco) that you want cyclone to
+**track in the DB** before uploading, use the canonical submit path.
+This is the preferred outbound path going forward — it captures the
+batch's `transaction_set_control_number` (the ST02 control number that
+999 acks reference in AK201) so future 999 ack links resolve instead
+of becoming orphans.
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+
+# 1. Lay out files in batch-*-claims subdirs under your ingest dir:
+#    ingest/batch-2026-07-08-claims/claim-001.x12
+#    ingest/batch-2026-07-08-claims/claim-002.x12
+#    ...
+
+# 2. CLI — walks ingest/, parses, writes to DB, then SFTP-uploads.
+.venv/bin/python -m cyclone submit-batch \
+    --ingest-dir /home/tyler/dev/cyclone/ingest \
+    --actor cli-submit-batch
+
+# Or via HTTP (auth-gated by matrix_gate):
+curl -s -X POST http://localhost:8000/api/submit-batch \
+    -H 'Content-Type: application/json' \
+    -d '{"ingest_dir": "/home/tyler/dev/cyclone/ingest", "actor": "api-submit-batch"}'
+```
+
+Both surfaces share `cyclone.submission.submit_file` for the
+parse → DB-write → SFTP-upload chain (DB-first, upload-second
+invariant). The walker pattern is identical: `batch-*-claims/*.x12`,
+sorted, with `._*` AppleDouble files skipped.
+
+**When to use `submit-batch` vs `resubmit-rejected-claims`:**
+- `submit-batch` — canonical path for fresh 837s from dzinesco (or any
+  source) that should be tracked in the DB before upload. Default choice.
+- `resubmit-rejected-claims` — one-off path for cases where you do NOT
+  want a DB row (e.g., dzinesco-generated fixes not ready for canonical
+  tracking). Legacy, retained for backward compat.
+
+**Status codes / exit codes:**
+- HTTP 200 on completed runs (per-file failures live in the JSON body);
+  401 unauthenticated; 404 no clearhouse; 409 stub mode; 422 validation.
+- CLI exit 0 on completed runs (per-file failures counted, not bumped);
+  2 on config-level failures (no clearhouse / stub mode / missing dir).
+
+### Note on per-file parse CLIs
+
+`parse-837` and `parse-835` exist as CLIs but only emit JSON files to
+`--output-dir`; they do NOT write to the DB. There is no
+`parse-999` / `parse-ta1` / `parse-277ca` CLI in this version of
+cyclone — the canonical 999/TA1/277CA/835 ingestion path is
+`pull-inbound` → `Scheduler.process_inbound_files`. For inspection of
+a single file without DB writes, use the Python API:
+
+```python
+from cyclone.parsers.parse_999 import parse as parse_999
+result = parse_999(open("path.999.x12").read())
+```
+
+### Switching from manual → real (and back)
+
+When this host's IP is whitelisted with Gainwell's MFT admin, the
+SP25 procedure above flips the block. The CLI one-liner:
+
+```bash
+export CYCLONE_SFTP_PASSWORD="$GAINWELL_SFTP_PASS"
+.venv/bin/python -c "
+from cyclone import db, store
+from cyclone.providers import Clearhouse, SftpBlock
+db.init_db()
+ch = store.store.get_clearhouse()
+sb = ch.sftp_block.model_dump()
+sb['stub'] = False
+sb['auth'] = {'password_keychain_account': 'sftp.gainwell.password'}
+new = Clearhouse(
+    id=1, name=ch.name, tpid=ch.tpid,
+    submitter_id_qual=ch.submitter_id_qual,
+    submitter_name=ch.submitter_name,
+    submitter_contact_name=ch.submitter_contact_name,
+    submitter_contact_email=ch.submitter_contact_email,
+    filename_block=ch.filename_block,
+    sftp_block=SftpBlock.model_validate(sb, strict=True),
+    updated_at=ch.updated_at,
+)
+print('updated:', store.store.update_clearhouse(new).sftp_block.stub)
+"
+```
+
+Hot-reload via `PATCH /api/clearhouse` (preferred over direct DB
+write — it also calls `scheduler.reconfigure_scheduler` so the running
+daemon picks up the new block without a restart):
+
+```bash
+curl -s -b cookies.txt http://127.0.0.1:8000/api/clearhouse > /tmp/ch.json
+jq '.sftp_block.stub = false
+    | .sftp_block.auth = {"password_keychain_account": "sftp.gainwell.password"}' \
+   /tmp/ch.json > /tmp/ch-patched.json
+curl -X PATCH http://127.0.0.1:8000/api/clearhouse \
+     -H 'Content-Type: application/json' -b cookies.txt \
+     --data @/tmp/ch-patched.json
+```
+
+To revert, set `stub: true` and `auth: {"method": "keychain", "secret_ref": "sftp.gainwell.password"}`.
+
+## Known historical drift — the 804 orphan 999s
+
+The `acks` table may hold several hundred 999 acks whose source 837
+batch is not present in the `batches` table — the Inbox "Ack orphans"
+lane surfaces them at `GET /api/inbox/ack-orphans`. These are real
+production 999s (e.g. sender_id `COMEDASSISTPROG`) whose source 837s
+were submitted to HPE clearinghouse before the current
+`~/.local/share/cyclone/cyclone.db` snapshot was created. The source
+837s themselves were never re-ingested into the current DB, so the
+`claims` table has no rows that could link against them. SP37's
+canonical submit-batch flow captures ST02 going forward, so the
+orphan count is stable — not a forward-looking bug, just historical
+drift.
+
+**You cannot auto-link these orphans.** The source 837s are not in
+`ingest/`, `backend/var/sftp/staging/`, or any local path — they
+were transmitted to HPE and never came back. Cyclone is downstream
+of the clearinghouse and does not retain copies of outbound 837s
+after SFTP ACK. Do not attempt to re-ingest from SFTP inbound —
+those files are the 999 acks themselves, not the source 837s.
+
+### Triage path
+
+1. **Inspect the Inbox > AckOrphansLane** in the UI. Each row is a
+   999 ack with no resolvable claim. Sort by `parsed_at DESC` to
+   see the most recent first; older orphans are less likely to be
+   actionable.
+2. **Decide per row.** If the operator can identify the source 837
+   outside Cyclone (e.g. a manual record of what was submitted that
+   day), manually create a `claims` row + a `claim_acks` link via
+   `POST /api/parse-837` followed by `POST /api/inbox/candidates/{remit_id}/match`
+   or `POST /api/acks/.../match-claim`. If not, leave the orphan
+   alone — it stays as valid audit history.
+
+### Optional: seed synthetic batch rows (one-shot)
+
+`cyclone ack-orphans reconcile` inserts a synthetic `batches` row
+for every orphan ST02 that doesn't already have one. The synthetic
+row is marked with `input_filename = '<synthetic:orphan-reconcile>'`
+so it's trivially distinguishable in queries. Future 999 acks for
+the same ST02s will resolve against the batch envelope index (so
+the operator can see "this 999 is for a known orphan source") but
+will not link to claims (because no claim rows exist).
+
+```bash
+# Preview the reconcile without writing rows.
+cyclone ack-orphans reconcile --dry-run
+
+# Insert the synthetic batch rows.
+cyclone ack-orphans reconcile
+```
+
+Re-running `cyclone ack-orphans reconcile` after a successful pass
+is a no-op (idempotent). To inspect the per-ST02 breakdown at any
+time:
+
+```bash
+cyclone ack-orphans status
+```
+
+The status command prints a table with ST02, ACK COUNT, and HAS
+BATCH columns, ranked by ack count so the heaviest backlog
+surfaces first.
+
+### What this is NOT
+
+- **Not a backfill.** No `claims` rows are synthesized — the source
+  data is gone.
+- **Not auto-runnable.** The reconcile CLI is operator-invoked only;
+  it does not run on boot, in the SFTP polling scheduler, or via
+  cron.
+- **Not a deletion.** The orphan 999s are valid audit history and
+  must remain queryable.

docs/superpowers/plans/2026-07-06-cyclone-api-routers-split.md

@@ -0,0 +1,842 @@
+# API Routers Split Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Behaviour-preserving split of `backend/src/cyclone/api.py` (4,341 LOC, 63 routes + 2 exception handlers) into per-resource routers under `backend/src/cyclone/api_routers/`, leaving `api.py` as a thin shell (~250 LOC) and `api_routers/` as 13 new + 2 modified (acks, admin) + 3 unchanged (claim_acks, ta1_acks, health) routers with a private `_shared.py` for the 12 cross-router helpers.
+
+**Architecture:** Each router is a FastAPI `APIRouter` module that imports only from `cyclone.store`, `cyclone.api_helpers`, and `cyclone.api_routers._shared`. `api_routers/__init__.py` exports a `routers: list[APIRouter]`; `api.py` does `for r in routers: app.include_router(r)`. The lifespan, both exception handlers, and the auth-router import stay in `api.py`. Per the spec, this is structural-only — zero behavior change, zero public API change, zero test change.
+
+**Tech Stack:** Python 3.11+, FastAPI, Pydantic v2, SQLAlchemy 2.x, pytest, paramiko (already in tree), Docker (running compose for live tests).
+
+**Spec:** [`docs/superpowers/specs/2026-07-06-cyclone-api-routers-split-design.md`](../specs/2026-07-06-cyclone-api-routers-split-design.md)
+
+**Progress tracker:** `/tmp/refactor-cyclone.md` — append one line per task per the per-task cycle in §0.3.
+
+**Status:** Merged into main on 2026-07-07 — merge commit `f005494 merge: SP36 api-routers-split into main` (15 SP36 commits beneath). Branch `sp36-api-routers-split` deleted (local + remote) post-merge.
+
+**Outcome vs plan:**
+- `api.py`: 4,341 → 378 LOC (plan target ≤300; +78 due to 7 backward-compat shims — follow-up cleanup tracked)
+- Routers: 18 under `api_routers/` + private `_shared.py` (plan called for 13 new + 2 modified + 3 unchanged = 18)
+- Helpers promoted to `_shared.py`: 9 (1 from Task 11 early-promotion: `_actor_user_id`; 7 from Task 16: parse-related; plus PAYER_FACTORIES dicts). Plan called for 12 cross-router helpers; the plan's count assumed all helpers would graduate but per D4 the single-router helpers correctly stayed in their routers.
+- Behavior change: 0. Test changes: 0 (D5 invariant).
+- Shim cleanup follow-up: drop 3 test files' reliance on the 7 `cyclone.api.<name>` alias-imports (`tests/test_payer_summary.py`, `tests/test_api_stream_live.py`, `tests/test_api_dedup.py`) to delete all 7 shims in one PR (target: api.py ≤300 LOC).
+
+---
+
+## File structure
+
+```
+backend/src/cyclone/
+├── api.py                     ← thin shell (target: ~250 LOC, was 4,341)
+├── api_helpers.py             ← UNCHANGED (NDJSON helpers stay)
+└── api_routers/
+    ├── __init__.py            ← NEW: exports `routers: list[APIRouter]`
+    ├── _shared.py             ← NEW: 12 cross-router helpers
+    ├── parse.py               ← NEW: 5 routes (~800 LOC)
+    ├── inbox.py               ← NEW: 6 routes (~470 LOC)
+    ├── batches.py             ← NEW: 3 routes + helpers (~370 LOC)
+    ├── claims.py              ← NEW: 5 routes + helper (~720 LOC)
+    ├── reconciliation.py      ← NEW: 4 routes (~115 LOC)
+    ├── remittances.py         ← NEW: 4 routes (~140 LOC)
+    ├── dashboard.py           ← NEW: 1 route (~30 LOC)
+    ├── providers.py           ← NEW: 3 routes (~250 LOC)
+    ├── activity.py            ← NEW: 2 routes (~150 LOC)
+    ├── eligibility.py         ← NEW: 2 routes (~85 LOC)
+    ├── clearhouse.py          ← NEW: 3 routes (~250 LOC)
+    ├── config.py              ← NEW: 2 routes (~100 LOC)
+    ├── payers.py              ← NEW: 1 route (~85 LOC)
+    ├── admin.py               ← MODIFIED: absorb 20 routes (was 59 LOC → ~1,200)
+    ├── acks.py                ← MODIFIED: absorb 2 277ca-acks routes (was 179 → ~250)
+    ├── claim_acks.py          ← UNCHANGED
+    ├── ta1_acks.py            ← UNCHANGED
+    └── health.py              ← UNCHANGED
+```
+
+---
+
+## Task 0: Pre-flight — merge SP35, branch SP36, capture baseline, create tracker
+
+**Files:**
+- Read: `docs/superpowers/specs/2026-07-06-cyclone-api-routers-split-design.md`
+- Create: `/tmp/refactor-cyclone.md`
+- Create: `/tmp/refactor-pre-baseline.txt`
+
+- [ ] **Step 1: Confirm SP35 is clean and ready to merge**
+
+```bash
+cd /home/tyler/dev/cyclone
+git status
+git log --oneline -5
+```
+
+Expected: "On branch sp35-parse-input-guards, nothing to commit, working tree clean" and 4 commits from SP35 on top of `0193ee4 merge: SP33 co-txix-payer-fix into main`.
+
+- [ ] **Step 2: Push the SP35 branch and open the merge PR (if not already)**
+
+```bash
+git push -u origin sp35-parse-input-guards
+gh pr create --base main --head sp35-parse-input-guards --title "SP35 Parse Input Guards" --body "Closes the misroute silent-corruption path. See spec at docs/superpowers/specs/2026-07-06-cyclone-parse-input-guards-design.md and plan at docs/superpowers/plans/2026-07-06-cyclone-parse-input-guards.md."
+```
+
+If a PR is already open, verify it's approved. **Block on PR approval before continuing.**
+
+- [ ] **Step 3: Merge SP35 into main (atomic, no squash, no rebase)**
+
+```bash
+gh pr merge sp35-parse-input-guards --merge
+git checkout main
+git pull
+git log --oneline -3
+```
+
+Expected: top commit is `merge: SP35 parse-input-guards into main` (or `0193ee4` if SP35 already merged; either is fine).
+
+- [ ] **Step 4: Restart the running compose so the container reflects main**
+
+```bash
+cd /home/tyler/dev/cyclone
+docker compose restart cyclone-backend-1
+sleep 5
+docker ps --format '{{.Names}}\t{{.Status}}' | grep cyclone
+curl -s -o /dev/null -w "health: %{http_code}\n" http://192.168.0.49:8080/api/health
+```
+
+Expected: `cyclone-backend-1 Up ... (healthy)` and `health: 200` (or 401 if auth-on; either is fine, the live-test in §0.6 documents the expected code).
+
+- [ ] **Step 5: Create the SP36 branch off main**
+
+```bash
+git checkout -b sp36-api-routers-split
+git status
+```
+
+Expected: "On branch sp36-api-routers-split, nothing to commit, working tree clean."
+
+- [ ] **Step 6: Commit the SP36 spec to the new branch**
+
+```bash
+git add docs/superpowers/specs/2026-07-06-cyclone-api-routers-split-design.md
+git commit -m "docs(spec): SP36 api-routers-split — behaviour-preserving split of api.py (4,341 LOC) into per-resource routers under api_routers/"
+```
+
+- [ ] **Step 7: Capture the pytest baseline**
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+.venv/bin/pytest --tb=line -q 2>&1 | tee /tmp/refactor-pre-baseline.txt | tail -3
+```
+
+Expected: one line like `1176 passed, 1 failed, 10 skipped in 45.2s`. (The 1 pre-existing failure is an isolation flake in a recent test, not introduced by SP36.)
+
+- [ ] **Step 8: Create the working tracker**
+
+```bash
+cat > /tmp/refactor-cyclone.md <<'EOF'
+# SP36 API Routers Split — progress tracker
+
+Started: 2026-07-06
+Branch: sp36-api-routers-split (off main, post-SP35 merge)
+Spec: docs/superpowers/specs/2026-07-06-cyclone-api-routers-split-design.md
+Plan: docs/superpowers/plans/2026-07-06-cyclone-api-routers-split.md
+
+## Baseline (captured in Task 0 Step 7)
+- pytest: see /tmp/refactor-pre-baseline.txt
+
+## Per-task log
+EOF
+cat /tmp/refactor-cyclone.md
+```
+
+- [ ] **Step 9: Commit the working tracker (do NOT commit `/tmp/` to git — it lives outside the repo)**
+
+No git action. `/tmp/refactor-cyclone.md` is a working file, not part of the repo. It's referenced from the per-task log steps and lives until the SP36 merge is done.
+
+- [ ] **Step 10: Sanity check the worktree before Task 1**
+
+```bash
+cd /home/tyler/dev/cyclone
+git log --oneline -3
+git diff --stat main..HEAD
+ls backend/src/cyclone/api_routers/
+wc -l backend/src/cyclone/api.py
+```
+
+Expected: working tree has the spec commit; `api_routers/` has 5 files (acks, admin, claim_acks, health, ta1_acks + `__init__.py`); `api.py` is 4,341 LOC.
+
+---
+
+## Task 1: Create `api_routers/__init__.py` and `_shared.py` skeleton
+
+**Files:**
+- Create: `backend/src/cyclone/api_routers/_shared.py`
+- Modify: `backend/src/cyclone/api_routers/__init__.py`
+
+This task creates the destination for cross-router helpers. We do **not** move any helpers in this task — we just establish the file with stubs that re-export the existing `api.py` helpers. The actual move happens in Task 2 when `acks.py` absorbs the 277ca-acks routes and needs `_serialize_ta1` from the new home.
+
+- [ ] **Step 1: Create `_shared.py` with the 12 helpers as thin re-exports from `api.py`**
+
+```python
+# backend/src/cyclone/api_routers/_shared.py
+"""Cross-router helpers for the api_routers package.
+
+Private to the package (leading underscore). Only routers in this
+package import from here. Single-router helpers stay private to the
+router that uses them.
+"""
+from cyclone.api import (  # type: ignore[F401]  # re-export; removed in Task 2
+    _actor_user_id,
+    _resolve_payer,
+    _resolve_payer_835,
+    _transaction_set_id_from_segments,
+    _build_and_persist_ack,
+    _reconciliation_summary_for_batch,
+    _ta1_synthetic_source_batch_id,
+    _serialize_ta1,
+    _serialize_ta1_from_row,
+    _batch_summary_claim_count,
+    _batch_summary_claim_ids,
+    _batch_summary_billing_outcomes,
+)
+```
+
+- [ ] **Step 2: Update `__init__.py` to export the existing routers**
+
+```python
+# backend/src/cyclone/api_routers/__init__.py
+"""Per-resource FastAPI routers.
+
+`api.py` does `for r in routers: app.include_router(r)`. New
+routers register themselves here in alphabetical order.
+"""
+from fastapi import APIRouter
+
+from cyclone.api_routers import acks, admin, claim_acks, health, ta1_acks
+
+routers: list[APIRouter] = [
+    acks.router,
+    admin.router,
+    claim_acks.router,
+    health.router,
+    ta1_acks.router,
+]
+
+__all__ = ["routers"]
+```
+
+- [ ] **Step 3: Update `api.py` to use the registry**
+
+Replace the trailing `app.include_router` block (the lines that include each existing router explicitly) with:
+
+```python
+from cyclone.api_routers import routers
+for r in routers:
+    app.include_router(r)
+```
+
+The auth-router includes (the `from cyclone.auth.routes import router as auth_router; app.include_router(auth_router)` block) stay as-is — those routers live in `cyclone.auth`, not `api_routers`.
+
+- [ ] **Step 4: Verify the existing test suite still passes (no router moved yet, just plumbing)**
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+.venv/bin/pytest --tb=line -q 2>&1 | tail -3
+```
+
+Expected: identical counts to `/tmp/refactor-pre-baseline.txt`. Any delta = revert Task 1.
+
+- [ ] **Step 5: Live test — hit a few existing routes to confirm registration works**
+
+```bash
+for route in /api/health /api/admin/audit-log /api/277ca-acks /api/claim-acks; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" "http://192.168.0.49:8080${route}")
+  echo "GET ${route} -> ${code}"
+done
+```
+
+Expected: each line returns `200` or `401` (auth-on, no cookie). Anything else = investigate before continuing.
+
+- [ ] **Step 6: Restart compose to load the new registry**
+
+```bash
+cd /home/tyler/dev/cyclone
+docker compose restart cyclone-backend-1
+sleep 5
+for route in /api/health /api/admin/audit-log /api/277ca-acks /api/claim-acks; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" "http://192.168.0.49:8080${route}")
+  echo "POST-RESTART GET ${route} -> ${code}"
+done
+```
+
+Expected: same codes as Step 5.
+
+- [ ] **Step 7: Autoreview — spawn a pr-reviewer subagent on the staged diff**
+
+```bash
+cd /home/tyler/dev/cyclone
+git add -A
+git diff --cached --stat
+# Spawn reviewer (paste the staged diff into the prompt)
+```
+
+Reviewer prompt: "Review this staged diff. Verify: (1) `api_routers/_shared.py` re-exports every helper name listed in the spec §3.3; (2) `api_routers/__init__.py` exports `routers: list[APIRouter]` and imports each existing router; (3) `api.py` was edited to use the `for r in routers: app.include_router(r)` pattern; (4) the auth-router include block is preserved verbatim; (5) no other lines in `api.py` were touched. Return PASS or FAIL: <reason>."
+
+- [ ] **Step 8: Commit**
+
+```bash
+cd /home/tyler/dev/cyclone
+git add backend/src/cyclone/api_routers/_shared.py backend/src/cyclone/api_routers/__init__.py backend/src/cyclone/api.py
+git commit -m "feat(sp36): wire api_routers/__init__.py as the registration point"
+```
+
+- [ ] **Step 9: Append to the working tracker**
+
+```bash
+cat >> /tmp/refactor-cyclone.md <<EOF
+
+### [task 1] wire api_routers/__init__.py registry
+- pre:  $(grep -E '^[0-9]+ passed' /tmp/refactor-pre-baseline.txt | head -1)
+- post: $(cd /home/tyler/dev/cyclone/backend && .venv/bin/pytest --tb=line -q 2>&1 | tail -1)
+- live: $(for r in /api/health /api/admin/audit-log /api/277ca-acks /api/claim-acks; do curl -s -o /dev/null -w "GET $r -> %{http_code} | " "http://192.168.0.49:8080$r"; done)
+- reviewer: PASS
+EOF
+```
+
+---
+
+## Task 2: Extract `acks.py` (absorb 2 277ca-acks routes + move 2 TA1 helpers to `_shared.py`)
+
+**Files:**
+- Modify: `backend/src/cyclone/api_routers/acks.py`
+- Modify: `backend/src/cyclone/api_routers/_shared.py` (drop 2 re-exports)
+- Modify: `backend/src/cyclone/api.py` (delete lines 1281-1354 + the helper definitions for `_serialize_ta1` and `_serialize_ta1_from_row`)
+
+We pick `acks.py` first because it has the smallest blast radius: 2 GET routes + 2 small serializers. The serializers are used only by `acks.py`, so they move to `acks.py` as private functions, not to `_shared.py`.
+
+Wait — re-reading the spec, the 2 TA1 serializers are listed in §3.3 `_shared.py` surface. They are used by `acks.py` ONLY today. Per D4, single-router helpers stay in the router. Update §3.3 inline as we learn: `_serialize_ta1` and `_serialize_ta1_from_row` stay in `acks.py` because only that router uses them.
+
+- [ ] **Step 1: Pre-flight pytest baseline**
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+.venv/bin/pytest --tb=line -q 2>&1 | tee /tmp/refactor-pre-acks.txt | tail -1
+```
+
+- [ ] **Step 2: Move the 2 route handlers from `api.py` to `acks.py`**
+
+Read the existing `api_routers/acks.py` to understand its current structure (likely already imports `matrix_gate`, defines `router = APIRouter(...)`).
+
+Append to `acks.py`:
+
+```python
+from typing import Optional
+from fastapi import Depends, Query
+from cyclone.api import matrix_gate  # re-use the existing dep
+
+# The next two route handlers were at api.py:1281-1354 before this
+# task. They are moved verbatim — no logic change.
+
+
+@router.get("/api/277ca-acks", dependencies=[Depends(matrix_gate)])
+def list_277ca_acks_endpoint(...):  # copy the signature and body from api.py:1282
+    ...
+
+
+@router.get("/api/277ca-acks/{ack_id}", dependencies=[Depends(matrix_gate)])
+def get_277ca_ack_endpoint(ack_id: int) -> dict:
+    ...  # copy from api.py:1314
+```
+
+The two TA1 serializers `_serialize_ta1(result)` and `_serialize_ta1_from_row(row)` move to `acks.py` as private functions, NOT to `_shared.py`. They are only used by `acks.py`.
+
+- [ ] **Step 3: Delete the moved code from `api.py`**
+
+Remove lines 1281-1354 from `api.py` (the 2 route handlers + 2 helpers). Verify `wc -l backend/src/cyclone/api.py` is now ~4,200 (was 4,341; we removed ~135 lines).
+
+- [ ] **Step 4: Run pytest post-cut and diff against pre**
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+.venv/bin/pytest --tb=line -q 2>&1 | tee /tmp/refactor-post-acks.txt | tail -1
+diff <(grep -E '^[0-9]+ passed' /tmp/refactor-pre-acks.txt | head -1) \
+     <(grep -E '^[0-9]+ passed' /tmp/refactor-post-acks.txt | head -1) && echo "BASELINE MATCH"
+```
+
+Expected: `BASELINE MATCH` (any pass/fail/skip count change is a regression).
+
+- [ ] **Step 5: Restart compose + live test**
+
+```bash
+cd /home/tyler/dev/cyclone
+docker compose restart cyclone-backend-1
+sleep 5
+for r in /api/277ca-acks /api/277ca-acks/1; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" "http://192.168.0.49:8080${r}")
+  echo "GET ${r} -> ${code}"
+done
+```
+
+Expected: `200` (with admin cookie) or `401` (without). The same code that the route returned in Task 1 Step 5.
+
+- [ ] **Step 6: Autoreview**
+
+```bash
+cd /home/tyler/dev/cyclone
+git add -A
+git diff --cached --stat
+```
+
+Spawn `pr-reviewer` subagent. Prompt: "Review the staged diff for SP36 Task 2 (acks.py absorbs 2 277ca-acks routes). Verify: (1) `acks.py` now contains the 2 moved route handlers; (2) the 2 TA1 serializer helpers (`_serialize_ta1`, `_serialize_ta1_from_row`) moved to `acks.py` as private functions, not to `_shared.py`; (3) `api.py` lost ~135 lines; (4) no helper was duplicated; (5) every moved route still has `dependencies=[Depends(matrix_gate)]`; (6) `_shared.py` was NOT changed (since the 2 serializers stayed in `acks.py`). Return PASS or FAIL: <reason>."
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd /home/tyler/dev/cyclone
+git commit -m "feat(sp36): extract acks router — absorb /api/277ca-acks list/get + TA1 serializers"
+```
+
+- [ ] **Step 8: Append to the working tracker**
+
+```bash
+cat >> /tmp/refactor-cyclone.md <<EOF
+
+### [task 2] extract acks router
+- pre:  $(grep -E '^[0-9]+ passed' /tmp/refactor-pre-acks.txt | head -1)
+- post: $(grep -E '^[0-9]+ passed' /tmp/refactor-post-acks.txt | head -1)
+- live: $(for r in /api/277ca-acks /api/277ca-acks/1; do curl -s -o /dev/null -w "GET $r -> %{http_code} | " "http://192.168.0.49:8080$r"; done)
+- reviewer: PASS
+EOF
+```
+
+---
+
+## Task 3: Extract `admin.py` (absorb 20 admin routes)
+
+**Files:**
+- Modify: `backend/src/cyclone/api_routers/admin.py` (grow from 59 → ~1,200 LOC)
+- Modify: `backend/src/cyclone/api.py` (delete lines 3372-4316, 69 admin routes, ~950 LOC)
+
+- [ ] **Step 1: Pre-flight pytest baseline**
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+.venv/bin/pytest --tb=line -q 2>&1 | tee /tmp/refactor-pre-admin.txt | tail -1
+```
+
+- [ ] **Step 2: Read the existing `admin.py` to see the router pattern**
+
+```bash
+head -60 backend/src/cyclone/api_routers/admin.py
+```
+
+The existing `admin.py` likely has 1 route or none (it's only 59 LOC). It will grow to ~1,200 LOC after this task.
+
+- [ ] **Step 3: Append the 20 admin route handlers from `api.py:3372-4316` to `admin.py`**
+
+Move verbatim. The handlers are:
+- `/api/admin/audit-log` (GET, line 3372)
+- `/api/admin/audit-log/verify` (GET, line 3414)
+- `/api/admin/db/rotate-key` (POST, line 3454)
+- 10 backup routes (lines 3614-3860)
+- 6 scheduler routes (lines 3894-4052)
+- `/api/admin/reload-config` (POST, line 4316)
+
+All retain `dependencies=[Depends(matrix_gate)]`.
+
+- [ ] **Step 4: Delete lines 3372-4316 from `api.py`**
+
+```bash
+cd /home/tyler/dev/cyclone
+# Verify line range first
+sed -n '3370,3380p' backend/src/cyclone/api.py
+sed -n '4314,4320p' backend/src/cyclone/api.py
+# Use a Python script to delete the range (safer than sed for multi-line blocks)
+python3 -c "
+import pathlib
+p = pathlib.Path('backend/src/cyclone/api.py')
+lines = p.read_text().splitlines(keepends=True)
+# Find the first @app. line in the 3372-4316 range and the line AFTER the last @app. + body
+# Easiest: delete the contiguous block from line 3372 to line 4316 inclusive
+# (the user verifies the boundaries by reading the file before this step)
+new = lines[:3371] + lines[4316:]
+p.write_text(''.join(new))
+print(f'api.py: {len(lines)} -> {len(new)} lines')
+"
+wc -l backend/src/cyclone/api.py
+```
+
+Expected: `api.py` shrinks by ~944 lines.
+
+- [ ] **Step 5: Run pytest post-cut and diff**
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+.venv/bin/pytest --tb=line -q 2>&1 | tee /tmp/refactor-post-admin.txt | tail -1
+diff <(grep -E '^[0-9]+ passed' /tmp/refactor-pre-admin.txt | head -1) \
+     <(grep -E '^[0-9]+ passed' /tmp/refactor-post-admin.txt | head -1) && echo "BASELINE MATCH"
+```
+
+- [ ] **Step 6: Restart compose + live test a representative admin route**
+
+```bash
+cd /home/tyler/dev/cyclone
+docker compose restart cyclone-backend-1
+sleep 5
+for r in /api/admin/audit-log /api/admin/backup/list /api/admin/scheduler/status; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" "http://192.168.0.49:8080${r}")
+  echo "GET ${r} -> ${code}"
+done
+```
+
+Expected: each returns `200` (admin auth) or `401` (no auth). Same codes as Task 1.
+
+- [ ] **Step 7: Autoreview**
+
+Spawn `pr-reviewer` subagent. Prompt: "Review the staged diff for SP36 Task 3 (admin.py absorbs 20 admin routes). Verify: (1) `admin.py` grew from ~59 LOC to ~1,200 LOC; (2) all 20 admin routes from `api.py:3372-4316` are now in `admin.py`; (3) each route retains `dependencies=[Depends(matrix_gate)]`; (4) no helper or import was duplicated; (5) `api.py` shrunk by ~944 lines. Return PASS or FAIL: <reason>."
+
+- [ ] **Step 8: Commit**
+
+```bash
+cd /home/tyler/dev/cyclone
+git add -A
+git commit -m "feat(sp36): extract admin router — absorb 20 admin endpoints (audit, db, backup, scheduler, reload-config)"
+```
+
+- [ ] **Step 9: Append to the working tracker**
+
+```bash
+cat >> /tmp/refactor-cyclone.md <<EOF
+
+### [task 3] extract admin router
+- pre:  $(grep -E '^[0-9]+ passed' /tmp/refactor-pre-admin.txt | head -1)
+- post: $(grep -E '^[0-9]+ passed' /tmp/refactor-post-admin.txt | head -1)
+- live: $(for r in /api/admin/audit-log /api/admin/backup/list /api/admin/scheduler/status; do curl -s -o /dev/null -w "GET $r -> %{http_code} | " "http://192.168.0.49:8080$r"; done)
+- reviewer: PASS
+EOF
+```
+
+---
+
+## Tasks 4-16: Extract the remaining 13 routers (one task per router)
+
+Each task follows the same 9-step cycle as Tasks 2 and 3:
+
+1. Pre-flight pytest baseline → `/tmp/refactor-pre-{name}.txt`
+2. Move the route handler(s) (and any single-router helpers) to the new router module
+3. Delete the moved code from `api.py`
+4. Run pytest post-cut → `/tmp/refactor-post-{name}.txt`, diff against pre
+5. Restart compose, live test one representative route
+6. Autoreview (pr-reviewer subagent)
+7. Commit `feat(sp36): extract {name} router`
+8. Append to `/tmp/refactor-cyclone.md`
+
+The order is **lowest-risk first** (per §8 of the spec): leaf routers with few routes, no cross-router helpers, no streaming. Then medium. Then the large coupled ones (`inbox`, `batches`, `claims`). Finally `parse.py` (most coupled to the store).
+
+| Task | Router | Routes | Source lines in api.py | Notes |
+|---|---|---|---|---|
+| 4 | `dashboard.py` | 1 | 2780-2807 | Trivial. `_kpis()` helper if any stays in the router. |
+| 5 | `eligibility.py` | 2 | 3013-3098 | Self-contained. |
+| 6 | `payers.py` | 1 | 4230-4315 | Self-contained. |
+| 7 | `config.py` | 2 | 4174-4229 | Loads payer configs; self-contained. |
+| 8 | `reconciliation.py` | 4 | 2511-2651 | Uses `cyclone.store.reconcile`; no cross-router helpers. |
+| 9 | `remittances.py` | 4 | 2652-2779 | One streaming route (`/api/remittances/stream`). |
+| 10 | `activity.py` | 2 | 2838-3012 | One streaming route (`/api/activity/stream`). |
+| 11 | `clearhouse.py` | 3 | 3099-3360 | Uses `SftpClient`; no cross-router helpers. |
+| 12 | `providers.py` | 3 | 2808-2837 + 3361-3371 + 4100-4173 | Three different URL prefixes; one router. |
+| 13 | `inbox.py` | 6 | 1355-2033 | Uses `matrix_gate` heavily. Largest leaf. |
+| 14 | `batches.py` | 3 | 1600-1808 + 1858-2102 | 3 `_batch_summary_*` helpers stay in this router (single-router). |
+| 15 | `claims.py` | 5 | 2103-2510 | 1 streaming route + `_compact_ack_links_for_claim` stays in this router. |
+| 16 | `parse.py` | 5 | 403-1280 | Most coupled to store. Promotes the 8 cross-router parse helpers to `_shared.py` in this task. |
+
+**Task 16 special step**: when extracting `parse.py`, update `_shared.py` to **define** the 8 parse-related helpers (rather than re-export from `api.py`), and remove the corresponding re-export lines. The 8 helpers being promoted to `_shared.py`:
+
+```python
+# In api_routers/_shared.py (Task 16, replacing the re-exports added in Task 1)
+from cyclone.api import _actor_user_id  # still re-exported; no parse-only helper
+# The 8 parse helpers are now DEFINED here (or moved verbatim from api.py)
+# ...
+def _resolve_payer(name: str) -> PayerConfig: ...
+def _resolve_payer_835(name: str) -> PayerConfig835: ...
+def _transaction_set_id_from_segments(segments): ...
+def _build_and_persist_ack(batch_id: str) -> dict | None: ...
+def _reconciliation_summary_for_batch(batch_id: str) -> dict: ...
+def _ta1_synthetic_source_batch_id(icn: str) -> str: ...
+```
+
+Each task uses the canonical 9-step cycle. The reviewer prompt for each task enumerates: (1) routes moved verbatim, (2) no helpers duplicated, (3) `api.py` shrunk, (4) `dependencies=[Depends(matrix_gate)]` preserved, (5) imports clean, (6) commit message follows `feat(sp36): extract {name} router`.
+
+---
+
+## Task 17: Final integration tests + one-shot verification + open PR
+
+**Files:**
+- Read: `/tmp/refactor-cyclone.md` (the per-step log)
+- Modify: `backend/src/cyclone/api.py` (should now be ~250 LOC)
+- Create: PR description
+
+- [ ] **Step 1: Run the full backend test suite**
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+.venv/bin/pytest --tb=line -q 2>&1 | tee /tmp/refactor-post-final.txt | tail -1
+diff <(grep -E '^[0-9]+ passed' /tmp/refactor-pre-baseline.txt | head -1) \
+     <(grep -E '^[0-9]+ passed' /tmp/refactor-post-final.txt | head -1) && echo "BASELINE MATCH"
+```
+
+Expected: `BASELINE MATCH`. Any delta = investigate the last task before proceeding.
+
+- [ ] **Step 2: Run every API integration test verbosely**
+
+```bash
+cd /home/tyler/dev/cyclone/backend
+.venv/bin/pytest tests/test_api_*.py -v 2>&1 | tail -30
+```
+
+Expected: every test green (or the same pre-existing skipped set as the baseline).
+
+- [ ] **Step 3: Run the frontend suite**
+
+```bash
+cd /home/tyler/dev/cyclone
+npm test 2>&1 | tail -10
+```
+
+Expected: all green.
+
+- [ ] **Step 4: Run the frontend typecheck, build, and lint**
+
+```bash
+cd /home/tyler/dev/cyclone
+npm run typecheck 2>&1 | tail -5
+npm run build 2>&1 | tail -5
+npm run lint 2>&1 | tail -5
+```
+
+Expected: all clean.
+
+- [ ] **Step 5: One-shot verification — file sizes**
+
+```bash
+cd /home/tyler/dev/cyclone
+echo "api.py: $(wc -l < backend/src/cyclone/api.py) lines (target ≤ 300)"
+echo "routers (sorted):"
+wc -l backend/src/cyclone/api_routers/*.py | sort -n
+```
+
+Expected: `api.py` ≤ 300; no router over 1,400 LOC (admin is largest at ~1,200).
+
+- [ ] **Step 6: One-shot verification — no `session.add` / `s.add(` / `session.commit` in routers**
+
+```bash
+cd /home/tyler/dev/cyclone
+grep -rn "session.add\|s\.add(\|session\.commit" backend/src/cyclone/api_routers/ || echo "NO WRITE LEAKS"
+```
+
+Expected: `NO WRITE LEAKS` (writes go through `cyclone.store` only).
+
+- [ ] **Step 7: One-shot verification — every `@app.` decorator is gone from `api.py`**
+
+```bash
+cd /home/tyler/dev/cyclone
+git grep -n "^@app\." backend/src/cyclone/api.py | grep -v exception_handler || echo "NO ROUTE DECORATORS IN api.py"
+```
+
+Expected: `NO ROUTE DECORATORS IN api.py` (only the 2 exception handlers remain).
+
+- [ ] **Step 8: One-shot verification — registry has every router**
+
+```bash
+cd /home/tyler/dev/cyclone
+python3 -c "
+from cyclone.api_routers import routers
+print(f'routers registered: {len(routers)}')
+for r in routers:
+    print(f'  - {r.prefix if hasattr(r, \"prefix\") else \"(no prefix)\"} {r.routes[0].path if r.routes else \"\"}')
+"
+```
+
+Expected: 18 routers registered (5 existing + 13 new). Each has at least one route.
+
+- [ ] **Step 9: Live matrix — one route per URL prefix, expect 2xx or documented code**
+
+```bash
+cd /home/tyler/dev/cyclone
+declare -a routes=(
+  /api/health
+  /api/admin/audit-log
+  /api/admin/backup/list
+  /api/admin/scheduler/status
+  /api/claims
+  /api/claims/stream
+  /api/claim-acks
+  /api/remittances
+  /api/remittances/stream
+  /api/activity
+  /api/activity/stream
+  /api/dashboard/kpis
+  /api/providers
+  /api/config/providers
+  /api/config/payers
+  /api/payers/CO_TXIX/summary
+  /api/inbox/lanes
+  /api/batches
+  /api/clearhouse
+  /api/eligibility/request
+  /api/277ca-acks
+  /api/reconciliation/unmatched
+)
+for r in "${routes[@]}"; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" "http://192.168.0.49:8080${r}")
+  echo "GET ${r} -> ${code}"
+done
+```
+
+Expected: each returns `200` (admin cookie) or `401` (no cookie). All should be `200` if you have a session cookie, otherwise `401`. Anything else (`500`, `404`, `422`) = investigate.
+
+- [ ] **Step 10: Restart compose one final time, run the live matrix again**
+
+```bash
+cd /home/tyler/dev/cyclone
+docker compose restart cyclone-backend-1
+sleep 10
+# Re-run the Step 9 loop
+```
+
+Expected: same codes as Step 9.
+
+- [ ] **Step 11: Open the PR**
+
+```bash
+cd /home/tyler/dev/cyclone
+git push -u origin sp36-api-routers-split
+gh pr create --base main --head sp36-api-routers-split \
+  --title "SP36 API Routers Split" \
+  --body "$(cat <<'EOF'
+Behaviour-preserving split of `backend/src/cyclone/api.py` (4,341 LOC, 63 routes + 2 exception handlers) into per-resource routers under `api_routers/`. `api.py` shrinks to ~250 LOC. Zero public API change, zero test change, zero behavior change.
+
+Spec: docs/superpowers/specs/2026-07-06-cyclone-api-routers-split-design.md
+Plan: docs/superpowers/plans/2026-07-06-cyclone-api-routers-split.md
+Progress log: /tmp/refactor-cyclone.md (in this container, not committed)
+
+Routers extracted (one commit each):
+- [x] acks.py (absorb 2 277ca-acks routes)
+- [x] admin.py (absorb 20 admin routes)
+- [x] dashboard.py
+- [x] eligibility.py
+- [x] payers.py
+- [x] config.py
+- [x] reconciliation.py
+- [x] remittances.py
+- [x] activity.py
+- [x] clearhouse.py
+- [x] providers.py
+- [x] inbox.py
+- [x] batches.py
+- [x] claims.py
+- [x] parse.py
+
+12 cross-router helpers promoted to `api_routers/_shared.py` (private).
+
+Verification: pytest baseline matches, all API integration tests green, frontend suite + typecheck + build + lint clean, one-route-per-prefix live matrix returns 2xx.
+EOF
+)"
+```
+
+- [ ] **Step 12: Final append to the working tracker**
+
+```bash
+cat >> /tmp/refactor-cyclone.md <<EOF
+
+## Final integration (Task 17)
+- backend pytest: $(grep -E '^[0-9]+ passed' /tmp/refactor-post-final.txt | head -1) (baseline: $(grep -E '^[0-9]+ passed' /tmp/refactor-pre-baseline.txt | head -1))
+- api.py: $(wc -l < /home/tyler/dev/cyclone/backend/src/cyclone/api.py) lines
+- largest router: $(wc -l /home/tyler/dev/cyclone/backend/src/cyclone/api_routers/*.py | sort -n | tail -1)
+- PR: SP36 API Routers Split (open, awaiting review)
+EOF
+cat /tmp/refactor-cyclone.md
+```
+
+---
+
+## Task 18: Merge after review (post-approval)
+
+**Files:**
+- (no file changes; pure git operation)
+
+- [ ] **Step 1: Confirm PR is approved**
+
+```bash
+gh pr view sp36-api-routers-split --json reviews --jq '.reviews[-1].state'
+```
+
+Expected: `APPROVED`. If not, block on review.
+
+- [ ] **Step 2: Atomic merge into main (no squash, no rebase)**
+
+```bash
+cd /home/tyler/dev/cyclone
+gh pr merge sp36-api-routers-split --merge
+git checkout main
+git pull
+git log --oneline -3
+```
+
+Expected: top commit is `merge: SP36 api-routers-split into main` (subject matches the PR title; the SP-N merge-commit subject is identical to the PR title per the cyclone-spec skill).
+
+- [ ] **Step 3: Restart compose to pick up main**
+
+```bash
+cd /home/tyler/dev/cyclone
+docker compose restart cyclone-backend-1
+sleep 5
+docker ps --format '{{.Names}}\t{{.Status}}' | grep cyclone
+```
+
+- [ ] **Step 4: Final live test**
+
+```bash
+for r in /api/health /api/claims /api/admin/audit-log; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" "http://192.168.0.49:8080${r}")
+  echo "GET ${r} -> ${code}"
+done
+```
+
+Expected: `200` (with cookie) or `401` (without).
+
+- [ ] **Step 5: Archive the working tracker**
+
+```bash
+cp /tmp/refactor-cyclone.md /home/tyler/dev/cyclone/docs/superpowers/refactor-logs/2026-07-06-sp36-api-routers-split.md
+mkdir -p /home/tyler/dev/cyclone/docs/superpowers/refactor-logs
+mv /tmp/refactor-cyclone.md /home/tyler/dev/cyclone/docs/superpowers/refactor-logs/2026-07-06-sp36-api-routers-split.md
+git add docs/superpowers/refactor-logs/2026-07-06-sp36-api-routers-split.md
+git commit -m "docs(sp36): archive refactor progress log"
+```
+
+---
+
+## Self-review (per the writing-plans skill)
+
+**Spec coverage:**
+- §1 Scope (in/out): covered by Task 0 Step 1-3 (pre-flight) and Task 17 Step 1-9 (verification)
+- §2.1 D1 (mirrors store): Task 1 establishes the layout that mirrors the store
+- §2.1 D2 (admin stays one): Tasks 1-3, no further admin split
+- §2.1 D3 (registry pattern): Task 1 Step 3
+- §2.1 D4 (_shared.py single-router rule): Tasks 2, 4-16
+- §2.1 D5 (no logic change): enforced by Step 4 diff in every router task
+- §2.1 D6 (live-test + autoreview + commit per router): every router task has Steps 5-7
+- §2.1 D7 (merge SP35 first): Task 0 Steps 2-3
+- §2.1 D8 (one-shot verification): Task 17 Steps 5-9
+- §3 Architecture: Task 1 (file layout) + Tasks 2-16 (router extractions) + Task 17 (final shape)
+- §4 Data flow: Task 17 Step 9 (live matrix)
+- §5 Testing: Task 0 Step 7 (baseline) + every router task Step 4 (diff) + Task 17 Steps 1-4
+- §6 Threat model: implicit (auth gate preserved in every moved route)
+- §7 Risks: mitigated by Step 4 diff and Step 6 autoreview
+- §8 Rollout: Tasks 0 + 17 + 18
+
+**Placeholder scan:** no "TBD", "TODO", "fill in details". The only thing close is the Task 16 inline code snippet for the `_shared.py` migration, which is concrete (8 helper names listed) not a placeholder.
+
+**Type consistency:** the `_shared.py` API is defined in Task 1 Step 1 (re-export from `cyclone.api`) and realized in Task 16 Step 16 (define locally). Names match. The `routers: list[APIRouter]` registry is defined in Task 1 Step 2 and consumed in Task 1 Step 3. Names match.
+
+**Gaps found and fixed during self-review:**
+- Task 2 originally said the 2 TA1 serializers go to `_shared.py`; corrected to keep them in `acks.py` (per D4 — single-router helpers stay in the router).
+- Task 16 originally lumped the 8 parse helpers into Task 1's re-export; corrected so Task 1 only adds re-exports and Task 16 promotes them to definitions.

docs/superpowers/plans/2026-07-07-cyclone-orphan-ack-housekeeping.md

@@ -0,0 +1,214 @@
+# Orphan-ack housekeeping Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use
+> superpowers:subagent-driven-development (recommended) or
+> superpowers:executing-plans to implement this plan task-by-task. Steps
+> use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Surface the 804 historical orphan acks to operators via a
+RUNBOOK entry + CLI, and provide a one-shot idempotent synthetic-batch
+seeder so future acks for those ST02s can resolve against the
+`batch_envelope_index` instead of remaining forever-orphans.
+
+**Architecture:** Two thin CLI subcommands under `cyclone ack-orphans
+{status,reconcile}` backed by a single store helper
+`find_ack_orphan_st02_summary()`. The helper returns a structured
+list[dict]; the CLI formats it. Reconcile uses the same SQLAlchemy
+session the rest of the store uses, so it inherits the DB-first
+invariant (no direct sqlite3 calls, no parallel writers).
+
+**Tech Stack:** Python 3.11, FastAPI, SQLAlchemy, Click (CLI),
+pytest, the existing `backend/tests/conftest.py` autouse fixtures.
+
+**Spec:** [`docs/superpowers/specs/2026-07-07-cyclone-orphan-ack-housekeeping-design.md`](../specs/2026-07-07-cyclone-orphan-ack-housekeeping-design.md)
+
+---
+
+## File structure
+
+```
+backend/
+  src/cyclone/
+    cli.py                              # + ack-orphans status + reconcile subcommands
+    store/
+      __init__.py                       # + find_ack_orphan_st02_summary() facade method
+      claim_acks.py                     # extract _iter_orphan_st02s() helper
+  tests/
+    test_ack_orphan_summary.py          # NEW: store-helper tests
+    test_ack_orphans_cli.py             # NEW: CLI tests via CliRunner
+docs/
+  RUNBOOK.md                            # + "Known historical drift" section
+```
+
+---
+
+## Task 1: Extract `_iter_orphan_st02s()` helper from `find_ack_orphans`
+
+The current `find_ack_orphans(kind)` walks the `acks` table directly
+and does its own LEFT JOIN against `claim_acks`. Both the new store
+helper (`find_ack_orphan_st02_summary`) and the existing
+`find_ack_orphans` need to enumerate the orphan ST02s. Extract the
+walk into a private helper in `claim_acks.py` that returns a flat
+list of `(st02, ack_count)` tuples — the only join key needed for
+the summary, and the seed for `find_ack_orphans`'s per-kind filter.
+
+- [ ] Read `backend/src/cyclone/store/claim_acks.py:250-330` to confirm
+      the current shape of `find_ack_orphans`.
+- [ ] Add `_iter_orphan_st02s() -> Iterator[tuple[str, int]]` to
+      `claim_acks.py`. One SELECT against `acks` joining
+      `claim_acks` on `(claim_acks.ack_kind = '999' AND
+      claim_acks.ack_id = acks.id)`, yielding `(set_control_number,
+      ack_count)` for each group where no claim_acks row exists.
+      For 277ca / ta1 the same shape but with the matching ack table
+      and `claim_acks.ack_kind` filter.
+- [ ] Refactor `find_ack_orphans(kind)` to consume the helper.
+      No behavior change; same return shape, same idempotent
+      semantics. All existing tests must still pass.
+
+**RED→GREEN test gate:** `cd backend && .venv/bin/pytest
+tests/test_api_claim_acks.py tests/test_apply_claim_ack_links.py -v`
+must remain green.
+
+## Task 2: Add `find_ack_orphan_st02_summary()` to the store facade
+
+- [ ] Add `find_ack_orphan_st02_summary(self) -> list[dict]` to
+      `CycloneStore` in `backend/src/cyclone/store/__init__.py`.
+      Returns `[{"st02": str, "ack_count": int,
+      "has_batch": bool, "batch_id": str | None}, ...]`.
+- [ ] `has_batch` is `True` if a row exists in `batches` with
+      `transaction_set_control_number = st02`. `batch_id` is that
+      row's `id` (or `None`).
+- [ ] Sort the result by `ack_count DESC` so the heaviest orphans
+      surface first in the CLI output.
+
+**RED test first:** write
+`backend/tests/test_ack_orphan_summary.py::test_summary_returns_per_st02_counts`
+with a seeded DB (two orphan ST02s, one with a batch, one without)
+and assert the shape. Watch it fail (no facade method yet), then
+implement to GREEN.
+
+## Task 3: Test the synthetic-batch seeder
+
+The reconcile CLI inserts synthetic `batches` rows for any orphan
+ST02 that doesn't already have one. This is a write; the store
+helper needs a paired write-side method.
+
+- [ ] Add `reconcile_orphan_st02s(self, dry_run: bool = False) ->
+      dict` to `CycloneStore`. Returns `{"created": int, "skipped":
+      int, "synthetic_batch_ids": list[str]}`.
+- [ ] For each ST02 in the summary where `has_batch is False`, insert
+      a `batches` row with: `kind = '837p'`, `input_filename =
+      '<synthetic:orphan-reconcile>'`, `totals_json =
+      '{"orphan_reconcile": true, "ack_count": N}'`,
+      `validation_json = '{"orphan_reconcile": true, "note":
+      "sp38 synthetic batch row; source 837 was never ingested into
+      this DB snapshot"}'`, `id = uuid4().hex`. The remaining
+      columns take their defaults.
+- [ ] When `dry_run=True`, return the plan without writing.
+- [ ] Idempotency: re-running after a previous reconcile returns
+      `created=0, skipped=N`. Test this explicitly.
+
+**RED test:** `test_reconcile_is_idempotent` — run reconcile twice,
+assert the row count is unchanged after the second call.
+
+**RED test:** `test_reconcile_uses_synthetic_input_filename_sentinel`
+— assert every created row has `input_filename =
+'<synthetic:orphan-reconcile>'`.
+
+**RED test:** `test_reconcile_dry_run_does_not_write` — pass
+`dry_run=True`, assert `created == N` in the plan but
+`batches` row count is unchanged.
+
+## Task 4: Add `cyclone ack-orphans status` CLI subcommand
+
+- [ ] Open `backend/src/cyclone/cli.py`, locate the existing
+      `submit-batch` group.
+- [ ] Add an `ack-orphans` group with a `status` subcommand.
+- [ ] `status` calls `cycl_store.find_ack_orphan_st02_summary()`,
+      prints a table: `ST02 | ACK COUNT | HAS BATCH`. Total line at
+      the bottom.
+- [ ] Exit 0 on success, exit 1 on DB error (matching the
+      `cyclone-cli` convention: 1 = unexpected exception, including
+      SQLAlchemy DB errors).
+
+**RED test:** `tests/test_ack_orphans_cli.py::test_status_prints_table`
+using `CliRunner.invoke(["ack-orphans", "status"])`. Assert exit
+code 0, assert the table contains the seeded ST02s and the total
+line.
+
+## Task 5: Add `cyclone ack-orphans reconcile` CLI subcommand
+
+- [ ] Same `ack-orphans` group, `reconcile` subcommand.
+- [ ] Accepts `--dry-run` flag (default False).
+- [ ] Calls `cycl_store.reconcile_orphan_st02s(dry_run=dry_run)`,
+      prints `Created: N synthetic batch rows. Skipped: M (already
+      had a batch row).`.
+- [ ] Exit 0 on success, exit 1 on DB error (same convention as
+      `status`).
+
+**RED test:** `tests/test_ack_orphans_cli.py::test_reconcile_creates_synthetic_batches`
+— seed two orphan ST02s (one with batch, one without), invoke
+`reconcile`, assert `created=1`, assert a row with
+`input_filename='<synthetic:orphan-reconcile>'` exists.
+
+**RED test:** `tests/test_ack_orphans_cli.py::test_reconcile_dry_run_flag`
+— invoke `reconcile --dry-run`, assert `created=1` in plan but
+no DB row inserted.
+
+**RED test:** `tests/test_ack_orphans_cli.py::test_reconcile_is_idempotent`
+— invoke `reconcile` twice, assert the second invocation reports
+`created=0`.
+
+## Task 6: Add RUNBOOK.md entry
+
+- [ ] Open `docs/RUNBOOK.md`, find the existing "Operator triage"
+      section.
+- [ ] Add a `## Known historical drift` subsection under it.
+- [ ] Content (3-4 paragraphs):
+    - What the 804 orphans are (real production 999s whose source
+      837s pre-date the current DB snapshot).
+    - Why they cannot be auto-linked (the source 837s were not
+      preserved).
+    - How to triage them via the Inbox > AckOrphansLane.
+    - Optional: `cyclone ack-orphans status` to see the ST02
+      breakdown, `cyclone ack-orphans reconcile` to seed synthetic
+      batch rows for them.
+
+## Task 7: Live verification + autoreview + commit
+
+- [ ] Run the full backend test suite: `cd backend && .venv/bin/pytest`.
+      Confirm pre-existing failure count (20) is unchanged.
+- [ ] Live-run `cyclone ack-orphans status` against the current
+      `~/.local/share/cyclone/cyclone.db`. Confirm output matches the
+      SQLite investigation: 5 distinct ST02s, 805 total orphan rows.
+- [ ] Run autoreview (subagent) on the diff.
+- [ ] Commit with the SP-N commit prefixes. Per the SP38 spec, the
+      work is: store-helper extraction (Tasks 1-3), CLI (Tasks 4-5),
+      docs (Task 6). Three commits, all prefixed
+      `feat(sp38): …`. Plus a `merge: SP38 orphan-ack housekeeping
+      into main` commit at the end of the review cycle.
+
+---
+
+## Anti-patterns
+
+- **Don't add a UI for the CLI commands.** Spec is explicit: no UI
+  change.
+- **Don't auto-run reconcile on boot.** Operators invoke it
+  manually after they accept the drift.
+- **Don't try to backfill claim rows.** Source data is gone; no
+  way to fabricate claim rows that would be meaningful.
+- **Don't put the synthetic sentinel in a constant somewhere.** The
+  string `<synthetic:orphan-reconcile>` appears in the spec, the
+  plan, the store helper, the CLI output, and the seeded batches
+  table. Keep it inline so a future grep finds it.
+
+## Related skills to load while implementing
+
+- `cyclone-spec` — already loaded (this plan is its output).
+- `cyclone-cli` — for the `click.testing.CliRunner` pattern and the
+  exit-code convention.
+- `cyclone-store` — for the facade re-export pattern in
+  `store/__init__.py`.
+- `cyclone-tests` — for the `tmp_path/test.db` conftest pattern and
+  the BACKFILL_SQL-loads-from-file pattern from SP37 followup #1.

docs/superpowers/specs/2026-07-06-cyclone-api-routers-split-design.md

@@ -0,0 +1,374 @@
+# Sub-project 36 — API Routers Split: Design Spec
+
+**Date:** 2026-07-06
+**Status:** Merged into main (`f005494 merge: SP36 api-routers-split into main` on 2026-07-07)
+**Branch:** `sp36-api-routers-split` (merged + deleted)
+**Aesthetic direction:** No UI changes. Pure backend structural refactor — the public HTTP surface is byte-for-byte identical.
+
+---
+
+## 1. Scope
+
+`backend/src/cyclone/api.py` has grown to 4,341 LOC across 63 route handlers and 2 exception handlers. The `api_routers/` subpackage exists but holds only 5 small routers (`acks`, `admin`, `claim_acks`, `health`, `ta1_acks`, totalling ~700 LOC). SP21 split the persistence layer into a `cyclone/store/` subpackage; SP36 finishes that era of work by splitting the HTTP surface into per-resource routers that mirror the store's domain boundaries.
+
+The split is **behaviour-preserving**: every URL, every HTTP method, every status code, every response shape, every header is unchanged. The migration set, the store facade, the pubsub event contract, the auth boundary, the live-tail wire format, the parser pipeline, the CLI, and the frontend are all untouched. The work is moving code from one file to many files, registering the new files as FastAPI routers, and verifying the public surface is byte-for-byte identical.
+
+**In scope:**
+
+- Extract the 63 routes currently in `api.py` into per-domain routers under `api_routers/`:
+  - `parse.py` (5 routes: 837, 835, 999, ta1, 277ca)
+  - `inbox.py` (6 routes: lanes, candidates/match, candidates/dismiss, payer-rejected/acknowledge, rejected/resubmit, export.csv)
+  - `batches.py` (3 routes: list, get, export-837) + the three `_batch_summary_*` helpers
+  - `claims.py` (5 routes: list, stream, get, serialize-837, line-reconciliation) + `_compact_ack_links_for_claim`
+  - `reconciliation.py` (4 routes: unmatched, batch-diff, match, unmatch)
+  - `remittances.py` (4 routes: list, summary, stream, get)
+  - `dashboard.py` (1 route: kpis)
+  - `providers.py` (3 routes: providers, config/providers, config/providers/{npi})
+  - `activity.py` (2 routes: list, stream)
+  - `eligibility.py` (2 routes: request, parse-271)
+  - `clearhouse.py` (3 routes: get, patch, submit)
+  - `config.py` (2 routes: config/payers, config/payers/{id}/configs)
+  - `payers.py` (1 route: {id}/summary)
+  - `admin.py` (existing, absorb 20 routes: audit-log ×2, db/rotate-key, backup ×10, scheduler ×6, reload-config)
+  - `acks.py` (existing, absorb 2 routes: 277ca-acks list/get)
+- Move the 12 cross-router helper functions to `api_routers/_shared.py` (private to the package, leading underscore).
+- Reduce `api.py` to a thin shell: `app = FastAPI(...)`, `lifespan`, both `@app.exception_handler`s, and the `include_router` loop driven by a `routers: list[APIRouter]` exported from `api_routers/__init__.py`.
+- Keep `_ndjson_line` and `_tail_events` in `api_helpers.py` (already correct home; not duplicated).
+- Live-test after each router is extracted: `curl` a representative route, assert the expected status code, then run a backend `pytest` baseline diff to confirm zero regressions.
+- Autoreview after each router is extracted: spawn a `pr-reviewer` subagent on the staged diff before commit; the reviewer checks (a) route registration, (b) no orphan imports, (c) no leaked business logic, (d) no leaked auth-bypass.
+- Commit per-router with `feat(sp36): extract {router-name} router` prefix per the SP-N convention.
+- Track progress in `/tmp/refactor-cyclone.md` per the user's standing directive: each step logged with pre/post pytest counts, live-test result, and reviewer verdict.
+- Single atomic merge commit into `main` once every router is extracted, the full backend test suite matches the Step-0 baseline, the full frontend test suite is green, and a one-route-per-prefix live matrix returns 2xx.
+
+**Out of scope:**
+
+- No new endpoints, no behavior changes, no status code changes, no response shape changes, no header changes. Refactor is byte-for-byte transparent to clients.
+- No change to the auth boundary. The auth boundary is the HTTP layer (login required, bcrypt + HttpOnly session cookie); unchanged. The new routers mount under the same `matrix_gate` dependency, same as today.
+- No change to the store facade, `db.py`, any `store/` module, the pubsub event bus, the parsers, the serializers, the CLI, the audit log, or the migration set.
+- No change to `api_helpers.py` beyond ensuring it's still importable from its existing path. (Routers that need `_ndjson_line` / `_tail_events` continue to import from `cyclone.api_helpers`.)
+- No splitting of `admin.py` into `admin_audit.py` / `admin_db.py` / `admin_backup.py` / `admin_scheduler.py`. That's a separate concern (~1,200 LOC of admin endpoints, but still one domain) and is filed as a possible follow-up SP.
+- No renaming of any endpoint. No path normalization.
+- No frontend changes. No changes to `src/`, `vite.config.ts`, `package.json`, or any UI asset.
+- No documentation changes other than the spec + plan files for SP36 itself. The cyclone-skills (`.superpowers/skills/cyclone-api-router/SKILL.md`) will be re-read at the start of the next increment that adds an endpoint; the skills don't reference the specific module layout and don't need edits.
+- No new tests. The existing test suite (`backend/tests/test_api_*.py`, sibling `src/**/*.test.tsx`) is the regression net. Pytest baseline (passed / failed-pre-existing / skipped counts) captured before, asserted equal after.
+
+---
+
+## 2. Decisions (locked during brainstorming)
+
+### D1. Routers mirror the store's domain boundaries, not URL prefixes alone
+
+The store split (SP21) landed `cyclone/store/{batches, claim_detail, acks, inbox, providers, kpis, ...}`. The new routers should mirror that. A reader who knows the store should be able to guess where a route lives. Three of the routers that don't have a 1-to-1 store counterpart (`reconciliation.py`, `eligibility.py`, `dashboard.py`) still get their own files because they are independent domains at the HTTP surface; their handlers call into a mix of store methods + helper functions.
+
+### D2. `admin.py` stays one router even at ~1,200 LOC
+
+The admin surface has 20 routes across 4 sub-domains (audit log, db key rotation, backups, scheduler) and a natural 4-way split would be cleaner. We keep it as one router for SP36 because (a) the routes all share the `matrix_gate` admin-only dep, (b) the SP's goal is per-domain router extraction, and (c) splitting admin recursively would balloon the diff. The follow-up that does the admin sub-split is filed as a separate concern.
+
+### D3. `api_routers/__init__.py` is the registration point
+
+`api.py` does:
+```python
+from cyclone.api_routers import routers
+for r in routers:
+    app.include_router(r)
+```
+Cleaner than 19 individual `include_router` calls, easier to grep ("where is route X registered?"), and gives us a single line to flip for future feature flags. The auth router import (`from cyclone.auth.routes import router as auth_router`) keeps its explicit include in `api.py` because it's not under `api_routers/`.
+
+### D4. `_shared.py` is the home for cross-router helpers only
+
+A helper moves to `_shared.py` if and only if at least two routers use it. Single-router helpers (`_compact_ack_links_for_claim` for `claims.py`, `_batch_summary_*` for `batches.py`) stay private to the router that uses them. The 12 cross-router helpers listed in Section 3.3 are the full `_shared.py` surface. If a future router needs a helper that's currently in a single-router file, that helper is promoted to `_shared.py` as part of that future change.
+
+### D5. No business logic in route handlers, but no logic change either
+
+Route handlers before SP36 validate input, call the store, return the result. Route handlers after SP36 do the same thing in the same order. We do not refactor handlers as we move them — no extraction of common patterns, no introduction of dependencies-injection helpers, no factoring of duplicated try/except. The SP is a structural move, not a code-quality pass. Any "this looks like it could be cleaner" observations go in `/tmp/refactor-cyclone.md` as candidates for a future SP, not into this one.
+
+### D6. Live-test + autoreview + commit happens per router, not at the end
+
+Each router extraction is one `feat(sp36): extract {name} router` commit. The cycle is: pytest baseline → cut → pytest diff → curl the moved routes → autoreview → commit → update `/tmp/refactor-cyclone.md`. This means a router can be reverted individually if a regression slips through, the diff for review is small and focused, and the live system stays green throughout. The single atomic merge at the end folds all 19 router commits (5 existing routers + 14 new) into `main`.
+
+### D7. The merge of SP35 into main happens before the SP36 branch is cut
+
+SP35 (`sp35-parse-input-guards`) is sitting on a clean working tree with all four commits reviewable. SP36 branches from `main`, so SP35 must land first. This is a hard pre-condition: if SP35 isn't merged before the SP36 branch is cut, the SP36 branch will carry SP35's commits under it and the audit trail breaks.
+
+### D8. The one-shot verification commands in Section 5.3 are the merge gate
+
+A short battery of grep / wc / curl commands runs at the very end, before the merge commit. Any failure of these gates the merge until resolved. The commands check: `api.py` is thin, no router is over 1,400 LOC, no `session.add` / `s.add` / `session.commit` call leaks into a router file, every route decorator is registered, and a one-route-per-prefix live matrix returns 2xx.
+
+---
+
+## 3. Architecture
+
+### 3.1 Target file layout
+
+```
+backend/src/cyclone/
+├── api.py                     ← thin shell: app, lifespan, exception handlers, include_router loop (~250 LOC)
+├── api_helpers.py             ← cross-cutting helpers (NDJSON, tail-events) — UNCHANGED
+└── api_routers/
+    ├── __init__.py            ← exports `routers: list[APIRouter]`; auth-router stays in api.py
+    ├── _shared.py             ← 12 cross-router helpers (private to the package)
+    ├── parse.py               ← 5 routes (~800 LOC)
+    ├── inbox.py               ← 6 routes (~470 LOC)
+    ├── batches.py             ← 3 routes + _batch_summary_* helpers (~370 LOC)
+    ├── claims.py              ← 5 routes + _compact_ack_links_for_claim (~720 LOC)
+    ├── reconciliation.py      ← 4 routes (~115 LOC)
+    ├── remittances.py         ← 4 routes (~140 LOC)
+    ├── dashboard.py           ← 1 route (~30 LOC)
+    ├── providers.py           ← 3 routes (~250 LOC)
+    ├── activity.py            ← 2 routes (~150 LOC)
+    ├── eligibility.py         ← 2 routes (~85 LOC)
+    ├── clearhouse.py          ← 3 routes (~250 LOC)
+    ├── config.py              ← 2 routes (~100 LOC)
+    ├── payers.py              ← 1 route (~85 LOC)
+    ├── admin.py               ← existing, absorbs 16 routes (~1,200 LOC total)
+    ├── acks.py                ← existing, absorbs 2 277ca-acks routes
+    ├── claim_acks.py          ← existing, unchanged
+    ├── ta1_acks.py            ← existing, unchanged
+    └── health.py              ← existing, unchanged
+```
+
+### 3.2 Endpoints per router (authoritative)
+
+| Router | Method | URL | Source line in api.py |
+|---|---|---|---|
+| parse | POST | `/api/parse-837` | 403 |
+| parse | POST | `/api/parse-835` | 650 |
+| parse | POST | `/api/parse-999` | 822 |
+| parse | POST | `/api/parse-ta1` | 986 |
+| parse | POST | `/api/parse-277ca` | 1124 |
+| acks (absorbed) | GET | `/api/277ca-acks` | 1281 |
+| acks (absorbed) | GET | `/api/277ca-acks/{ack_id}` | 1313 |
+| inbox | GET | `/api/inbox/lanes` | 1355 |
+| inbox | POST | `/api/inbox/candidates/{remit_id}/match` | 1382 |
+| inbox | POST | `/api/inbox/candidates/dismiss` | 1411 |
+| inbox | POST | `/api/inbox/payer-rejected/acknowledge` | 1446 |
+| inbox | POST | `/api/inbox/rejected/resubmit` | 1506 |
+| inbox | GET | `/api/inbox/export.csv` | 1809 |
+| batches | POST | `/api/batches/{batch_id}/export-837` | 1600 |
+| batches | GET | `/api/batches` | 2034 |
+| batches | GET | `/api/batches/{batch_id}` | 2092 |
+| claims | GET | `/api/claims` | 2103 |
+| claims | GET | `/api/claims/stream` | 2152 |
+| claims | GET | `/api/claims/{claim_id}` | 2199 |
+| claims | GET | `/api/claims/{claim_id}/serialize-837` | 2262 |
+| claims | GET | `/api/claims/{claim_id}/line-reconciliation` | 2314 |
+| reconciliation | GET | `/api/reconciliation/unmatched` | 2511 |
+| reconciliation | GET | `/api/batch-diff` | 2528 |
+| reconciliation | POST | `/api/reconciliation/match` | 2575 |
+| reconciliation | POST | `/api/reconciliation/unmatch` | 2620 |
+| remittances | GET | `/api/remittances` | 2652 |
+| remittances | GET | `/api/remittances/summary` | 2693 |
+| remittances | GET | `/api/remittances/stream` | 2724 |
+| remittances | GET | `/api/remittances/{remittance_id}` | 2763 |
+| dashboard | GET | `/api/dashboard/kpis` | 2780 |
+| providers | GET | `/api/providers` | 2808 |
+| providers | GET | `/api/config/providers` | 3361 |
+| providers | GET | `/api/config/providers/{npi}` | 4100 |
+| activity | GET | `/api/activity` | 2838 |
+| activity | GET | `/api/activity/stream` | 2865 |
+| eligibility | POST | `/api/eligibility/request` | 3013 |
+| eligibility | POST | `/api/eligibility/parse-271` | 3039 |
+| clearhouse | GET | `/api/clearhouse` | 3099 |
+| clearhouse | PATCH | `/api/clearhouse` | 3108 |
+| clearhouse | POST | `/api/clearhouse/submit` | 3174 |
+| config | GET | `/api/config/payers` | 4174 |
+| config | GET | `/api/config/payers/{payer_id}/configs` | 4179 |
+| payers | GET | `/api/payers/{payer_id}/summary` | 4230 |
+| admin | GET | `/api/admin/audit-log` | 3372 |
+| admin | GET | `/api/admin/audit-log/verify` | 3414 |
+| admin | POST | `/api/admin/db/rotate-key` | 3454 |
+| admin | POST | `/api/admin/backup/create` | 3614 |
+| admin | GET | `/api/admin/backup/list` | 3668 |
+| admin | GET | `/api/admin/backup/status` | 3697 |
+| admin | POST | `/api/admin/backup/{backup_id}/verify` | 3711 |
+| admin | POST | `/api/admin/backup/{backup_id}/restore/initiate` | 3730 |
+| admin | POST | `/api/admin/backup/{backup_id}/restore/confirm` | 3758 |
+| admin | POST | `/api/admin/backup/prune` | 3810 |
+| admin | POST | `/api/admin/backup/scheduler/start` | 3838 |
+| admin | POST | `/api/admin/backup/scheduler/stop` | 3849 |
+| admin | POST | `/api/admin/backup/scheduler/tick` | 3860 |
+| admin | POST | `/api/admin/scheduler/start` | 3894 |
+| admin | POST | `/api/admin/scheduler/stop` | 3902 |
+| admin | POST | `/api/admin/scheduler/tick` | 3910 |
+| admin | POST | `/api/admin/scheduler/pull-inbound` | 3923 |
+| admin | GET | `/api/admin/scheduler/status` | 4045 |
+| admin | GET | `/api/admin/scheduler/processed-files` | 4052 |
+| admin | POST | `/api/admin/reload-config` | 4316 |
+
+### 3.3 `_shared.py` surface (12 helpers)
+
+| Helper | Routers that use it | Source line in api.py |
+|---|---|---|
+| `_actor_user_id(request)` | most | 54 |
+| `_resolve_payer(name)` | parse (837, 999, ta1, 277ca) | 333 |
+| `_resolve_payer_835(name)` | parse (835) | 345 |
+| `_transaction_set_id_from_segments(segments)` | parse (999, ta1) | 357 |
+| `_build_and_persist_ack(batch_id)` | parse (after 837) | 573 |
+| `_reconciliation_summary_for_batch(batch_id)` | parse (after 837) | 615 |
+| `_ta1_synthetic_source_batch_id(icn)` | parse (ta1) | 975 |
+| `_serialize_ta1(result)` | acks | 1324 |
+| `_serialize_ta1_from_row(row)` | acks | 1341 |
+| `_batch_summary_claim_count(rec)` | batches | 1858 |
+| `_batch_summary_claim_ids(rec)` | batches | 1867 |
+| `_batch_summary_billing_outcomes(...)` | batches | 1912 |
+
+### 3.4 Stays in `api.py`
+
+- `app = FastAPI(...)` instantiation
+- `lifespan` (init_db, scheduler, bus, sessions, etc.)
+- `@app.exception_handler(HTTPException)` at 313
+- `@app.exception_handler(Exception)` at 386
+- The trailing `from cyclone.auth.routes import router as auth_router; app.include_router(auth_router)` block
+- The `__all__ = ["app"]` line at the end
+
+### 3.5 Stays in `api_helpers.py`
+
+- `_ndjson_line`
+- `_tail_events`
+
+### 3.6 External import surface — what callers see
+
+A grep over the codebase for `from cyclone.api import` and `import cyclone.api` will return the same set of symbols after SP36 lands as before:
+
+- `from cyclone.api import app` — used by `python -m cyclone serve`, by tests (`from cyclone import api` then `app.state.*`), by the test `conftest.py`.
+- `app.state.event_bus`, `app.state.db`, `app.state.scheduler` — read by tests and by `api_routers/` (via `Request`).
+
+The new `cyclone.api_routers` package exports `routers: list[APIRouter]`. Anything in `api_routers/` that needs to be imported from outside (e.g. a router-level fixture in a future test) is reachable as `from cyclone.api_routers.parse import router`, etc.
+
+---
+
+## 4. Data flow & error handling
+
+**Data flow (per request):**
+
+1. FastAPI receives the request, runs the `matrix_gate` dependency (auth + role check), then dispatches to the matching route in the matching router.
+2. The route handler validates inputs (path params, query params, body via Pydantic if a body model exists).
+3. The handler calls `cyclone.store.<method>(...)` for write paths and reconciliation, or opens a `db.SessionLocal()() for one-off reads` (existing pattern; this is how the dashboard KPIs, the activity feed, the configuration endpoints, and the live-tail snapshot reads work today).
+4. The result is serialized via `to_ui_<entity>` (from `cyclone.store.ui`) for entity-shaped responses, or via a small local serializer for non-entity shapes (e.g. the dashboard KPI shape, the reconciliation summary, the eligibility 271 response).
+5. The handler returns `JSONResponse`, `StreamingResponse` (NDJSON), or `Response` (CSV for `/api/inbox/export.csv`).
+6. **Streaming endpoints** (`/api/claims/stream`, `/api/remittances/stream`, `/api/activity/stream`) keep the snapshot-then-live-subscription two-phase pattern. `_ndjson_line` and `_tail_events` come from `api_helpers.py`; the matching router imports them.
+7. **The event bus contract is unchanged.** Every write through `cyclone.store.add(...)` still publishes `claim_written` / `remittance_written` / `activity_recorded` on the in-process `EventBus`. The stream-endpoint routers subscribe to those exact event names. The SP doesn't introduce new event kinds, doesn't rename existing kinds, doesn't change payloads.
+
+**Error handling:**
+
+- Routers raise `HTTPException` for client errors. Same status codes, same `detail` strings, same `error` envelope (`{error, detail}`). No change.
+- The two global exception handlers stay in `api.py` (D2 of brainstorming): `@app.exception_handler(HTTPException)` re-emits with the cyclone error envelope, `@app.exception_handler(Exception)` logs and returns 500.
+- Streaming endpoints catch domain exceptions and yield `{"type": "error", "data": {"message": ...}}` NDJSON chunks instead of raising — existing pattern, preserved per router.
+- `StoreNotFound` / `StoreConflict` / `StoreInvalidState` are translated to 404 / 409 / 409 by the existing translation path. No change.
+- The auth path (`matrix_gate` dep) returns 401/403 unchanged.
+
+**No behavior change anywhere in the data flow or error path.** The SP is a structural move, not a correctness pass.
+
+---
+
+## 5. Testing approach
+
+### 5.1 Per-router cycle (live-test + autoreview + commit)
+
+For each router extracted (one `feat(sp36): extract {name} router` commit):
+
+1. **Pre-flight pytest baseline.** From the project root:
+   ```
+   cd backend && .venv/bin/pytest --tb=line -q 2>&1 | tee /tmp/refactor-{N}-pre.txt | tail -3
+   ```
+   Capture the `XXX passed, YY failed, ZZ skipped` line. Expect roughly `~1,176 passed, ~1 failed (pre-existing isolation flake), ~10 skipped` per the SP21 store-split spec baseline.
+2. **Cut.** Move the route handler(s) + their single-router helpers to the new router module, register the router in `api_routers/__init__.py`, delete the moved code from `api.py`, update imports. No logic change.
+3. **Post-cut pytest diff.** Same command as (1), output to `/tmp/refactor-{N}-post.txt`. Diff:
+   ```
+   diff <(awk '/passed|failed|skipped/ {print}' /tmp/refactor-{N}-pre.txt) \
+        <(awk '/passed|failed|skipped/ {print}' /tmp/refactor-{N}-post.txt)
+   ```
+   Required: zero diff. Any delta = revert the cut and investigate.
+4. **Live test.** Server is running in `cyclone-backend-1` on the host. Hit one representative route from the moved router. Required status codes:
+   - GET endpoints → 200 (or the documented non-200, e.g. 401 if auth is mocked off in the test environment)
+   - POST endpoints → 200, 201, 400, 401, 403, 409 (whatever the existing happy path / known-error path is)
+   - Streaming endpoints → 200 with `Content-Type: application/x-ndjson` and a valid first `snapshot_end` chunk
+5. **Autoreview.** Spawn a `pr-reviewer` subagent on the staged diff. The reviewer prompt enumerates: (a) the new router is registered in `api_routers/__init__.py`; (b) no orphan imports left in `api.py`; (c) no `session.add` / `s.add` / `session.commit` / direct `db.SessionLocal()() call that does a write` appears in any router file (reads are OK); (d) the router's `dependencies=[Depends(matrix_gate)]` matches the original; (e) docstrings are preserved. Reviewer returns a one-line verdict (PASS / FAIL: <reason>). On FAIL, fix and re-review.
+6. **Commit.** `feat(sp36): extract {name} router` per the SP-N convention.
+7. **Log** to `/tmp/refactor-cyclone.md`:
+   ```
+   [step N] extracted {name}
+     pre:  passed={X} failed={Y} skipped={Z}
+     post: passed={X} failed={Y} skipped={Z}
+     live: GET /api/{route} → {code} | POST /api/{route} → {code}
+     reviewer: PASS | FAIL: <reason>
+   ```
+
+### 5.2 Pre-merge integration test
+
+After all 19 routers are extracted, the full suite runs:
+
+- `cd backend && .venv/bin/pytest --tb=line -q` — full backend suite, must match Step 0 baseline to the digit
+- `cd backend && .venv/bin/pytest tests/test_api_*.py -v` — every API integration test, all green
+- `cd .. && npm test` — frontend suite, all green
+- `cd .. && npm run typecheck` — frontend typecheck clean
+- `cd .. && npm run build` — frontend build green
+- `cd .. && npm run lint` — frontend lint clean
+
+### 5.3 Pre-merge one-shot verification (D8 of brainstorming)
+
+These commands run, and all must pass, before the merge commit is created:
+
+- `wc -l backend/src/cyclone/api.py` — expect ≤ 300
+- `wc -l backend/src/cyclone/api_routers/*.py | sort -n` — expect no router over 1,400 LOC (admin is the largest at ~1,200)
+- `grep -rn "session.add\|s\.add(\|session\.commit" backend/src/cyclone/api_routers/` — expect zero hits (writes go through `cyclone.store` only)
+- `grep -rn "from cyclone.api_routers" backend/src/cyclone/api.py` — expect one hit (the `routers` import in `__init__` block)
+- `python -c "from cyclone.api_routers import routers; print(len(routers))"` — expect ≥ 18 (5 existing + 14 new, minus whatever routers ended up merged during the SP)
+- Live matrix — for every URL prefix in Section 3.2, `curl -s -o /dev/null -w "%{http_code}\n" http://192.168.0.49:8080/api/{prefix}/...` returns 2xx (or the documented error code)
+- `git grep -n "@app\." backend/src/cyclone/api.py` — expect zero hits (every route decorator now lives in a router)
+
+### 5.4 No new tests
+
+The existing test suite is the regression net. We do not add new tests, do not modify existing tests, do not add new fixtures. The pre/post pytest baseline diff is the test for the SP.
+
+---
+
+## 6. Threat model (post-SP24 alignment)
+
+The auth boundary is the HTTP layer: login required, bcrypt + HttpOnly session cookie. The new routers mount under `matrix_gate` (same as today), so every moved route stays auth-gated. No route is exposed that wasn't exposed before. No auth check is weakened.
+
+The file-system threat model is unchanged: SQLCipher at rest (when the macOS Keychain entry + `sqlcipher3` are both present, otherwise plain SQLite), secrets in the macOS Keychain via `keyring`, no secrets on disk in plaintext. SP36 doesn't touch the DB layer, the secrets module, or the configuration loader.
+
+LAN-only by design. The auth boundary is the network boundary; the production deployment is the host firewall + compose port publishing. Don't expose the published ports to the WAN — unchanged.
+
+---
+
+## 7. Risks & mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| A route handler silently changes behavior during the cut (typo, off-by-one, wrong import) | medium | high | Pre/post pytest diff is the test. The diff must be zero; any delta reverts. |
+| A helper gets duplicated instead of moved (one copy in old location, one in new) | low | medium | Autoreview explicitly checks for orphan imports in `api.py` and for `def _helper_name` definitions appearing twice. |
+| The `api_routers/__init__.py` registration misses a router and a route 404s in production | low | high | Pre-merge one-shot verification §5.3 includes a live matrix that hits every URL prefix. |
+| The `matrix_gate` dep is dropped from one route during the cut | low | critical | Autoreview explicitly checks `dependencies=[Depends(matrix_gate)]` matches the original on every moved route. |
+| Two routers end up importing each other (creates a cycle) | low | medium | The convention is "routers import only `cyclone.store`, `cyclone.api_helpers`, `cyclone.api_routers._shared`" — autoreview checks for any other cross-router import. |
+| A `from cyclone.api import` somewhere in the codebase breaks because we removed a top-level symbol | low | high | The external import surface (D6 of brainstorming) is the test: `git grep "from cyclone.api import"` before and after must be identical in symbol set. |
+| The merge of SP35 into main fails or introduces conflicts | low | high | D7 of brainstorming: SP35 merge is a hard pre-condition; if it doesn't land cleanly, SP36 doesn't start. |
+| A streaming endpoint regresses silently (returns the right status code but the wrong first chunk) | medium | medium | The live test for streaming endpoints asserts `Content-Type: application/x-ndjson` and parses the first `snapshot_end` line, not just the HTTP code. |
+| The frontend test suite picks up a backend change (e.g. a renamed JSON field that the UI consumes) | very low | medium | The refactor is byte-for-byte transparent to clients; if a frontend test fails, that's a real regression and we investigate. |
+
+---
+
+## 8. Rollout
+
+1. **Merge SP35 into main.** Fast-forward or merge commit (no squash, no rebase). The branch `sp35-parse-input-guards` has 4 reviewable commits and a clean working tree.
+2. **Restart compose if needed.** `docker compose restart cyclone-backend-1` after the SP35 merge so the running container reflects main.
+3. **Create the SP36 branch.** `git checkout -b sp36-api-routers-split` from main.
+4. **Extract routers, one per commit.** Order: lowest-risk first (admin, health, claim_acks, ta1_acks already exist; then the small leaf routers `dashboard.py`, `eligibility.py`, `payers.py`, `config.py`; then the medium ones `reconciliation.py`, `remittances.py`, `activity.py`, `clearhouse.py`, `providers.py`; then the larger ones `inbox.py`, `batches.py`, `claims.py`; finally `parse.py` since it's the most coupled to the store facade). Each step follows §5.1.
+5. **Run the §5.2 integration tests.**
+6. **Run the §5.3 one-shot verification.**
+7. **Open the PR.** Title: `SP36 API Routers Split`. Body: links to this spec, the SP36 plan (when written), and a checklist of every router extracted.
+8. **Merge after review.** Single atomic `merge: SP36 api-routers-split into main` commit, no squash, no rebase.
+
+---
+
+## 9. Open questions
+
+None at spec time. The brainstorming Q&A resolved all of:
+
+- Which file to split? `api.py`. Confirmed.
+- What shape? Per-resource routers mirroring the store's domain boundaries. Confirmed.
+- Branch from where? Merge SP35 first, then from main. Confirmed.
+- Where do the cross-router helpers go? `api_routers/_shared.py` (private). Confirmed.
+- `admin.py` — one router or split further? One router for this SP, follow-up later. Confirmed.
+- How granular are the commits? One router per commit. Confirmed.

docs/superpowers/specs/2026-07-07-cyclone-orphan-ack-housekeeping-design.md

@@ -0,0 +1,187 @@
+# Sub-project 38 — Orphan-ack housekeeping: Design Spec
+
+**Date:** 2026-07-07
+**Status:** Draft, awaiting user sign-off
+**Branch:** `sp38-orphan-ack-housekeeping`
+**Aesthetic direction:** No new UI
+
+## 1. Scope
+
+Cyclone's `acks` table currently holds 805 rows of which 804 are
+unresolved "orphans" — 999 acks that reference source 837 batches
+whose `transaction_set_control_number` (ST02) does not appear in any
+row of the `batches` table. Investigation on 2026-07-07 surfaced the
+root cause: the orphan rows are real production 999s (sender_id =
+`COMEDASSISTPROG`) whose source 837s were submitted to HPE clearinghouse
+by a prior state of the codebase (or an upstream system) before the
+current `cyclone.db` snapshot was created. The source 837s themselves
+were never re-ingested into the current DB, so the `claims` table has
+no rows that could link against these acks. The orphan count is a
+historical-data artifact, not a forward-looking bug; the SP37 canonical
+submit-batch flow already captures ST02 going forward, so the count
+stays at 804 and does not grow.
+
+This SP-N captures that situation, surfaces it to operators via a
+RUNBOOK entry, and adds a one-shot housekeeping helper so operators
+can (a) confirm the orphans are stable and (b) optionally seed
+synthetic batch rows for the orphan ST02s so that *future* acks for
+the same ST02s can resolve against the `batch_envelope_index` instead
+of remaining forever-orphans.
+
+**In scope:**
+
+- A RUNBOOK.md entry under "Known historical drift" describing the
+  804-orphan root cause, the operator's triage path (Inbox >
+  AckOrphansLane, already working as of SP37 followup commit
+  `893a662`), and the choice to accept the drift.
+- A `cyclone ack-orphans status` CLI subcommand that prints the
+  distinct orphan ST02s + ack count per ST02 + the total orphan count
+  + the count of orphan rows whose ST02 matches a `batches` row vs
+  those that don't. Deterministic, exit 0 on success / 1 on DB
+  error (matching the `cyclone-cli` skill convention: 1 =
+  unexpected exception, including DB-side errors).
+- A `cyclone ack-orphans reconcile` CLI subcommand that creates
+  synthetic `batches` rows for each distinct orphan ST02 that does
+  NOT already exist in `batches`. Synthetic rows are marked with
+  `kind = '837p'`, `input_filename = '<synthetic:orphan-reconcile>'`,
+  `totals_json = '{"orphan_reconcile": true, "ack_count": N}'`, and
+  `validation_json = '{"orphan_reconcile": true, "note": "synthetic
+  batch row created by sp38 to allow future acks for ST02 X to resolve
+  via batch_envelope_index; the original 837 source data was never
+  ingested into this DB snapshot"}'`. Idempotent: re-running on the
+  same DB does not create duplicate synthetic rows.
+- A pure read-side helper `cyclone.store.find_ack_orphan_st02_summary()`
+  that returns the per-ST02 summary the CLI consumes; the helper is
+  the testable surface and the CLI is a thin wrapper.
+- Tests for both CLI subcommands + the store helper, using the
+  existing `tmp_path/test.db` conftest pattern.
+
+**Out of scope:**
+
+- Re-ingesting the original 837 source files. The source 837s are
+  not in `ingest/`, `backend/var/sftp/staging/`, or any local path —
+  they were transmitted to HPE and never came back. Cyclone is
+  downstream of the clearinghouse and does not retain copies of
+  outbound 837s after SFTP ACK.
+- Auto-linking the 804 orphan acks to `claims`. There are no claim
+  rows for the orphan ST02s (the `claims` table has only 2 rows in
+  the current DB snapshot, both for ST02 `991102977` which is *not*
+  an orphan). Auto-linking is not possible without source data.
+- A UI for the `ack-orphans status` / `reconcile` commands. The
+  Inbox AckOrphansLane (post-`893a662`) is the operator's view of
+  the orphans; the CLI is for ad-hoc investigation and the one-shot
+  reconciliation.
+- Removing or archiving the 804 orphan acks. They are valid audit
+  history (real production traffic was acknowledged by HPE) and
+  must remain queryable.
+- Any change to the `claim_acks` join logic or the
+  `batch_envelope_index`. The orphan detection behavior is correct
+  as of SP37; this SP only adds housekeeping around the existing
+  behavior.
+
+## 2. Decisions (locked during brainstorming)
+
+**D1: Accept the historical drift, do not backfill.**
+
+The 804 orphans reflect a database snapshot that is younger than the
+traffic that produced the acks. The source 837s are not recoverable.
+SP37's canonical submit-batch flow captures ST02 going forward, so
+the count will stay at 804 + future-test-runs rather than grow
+indefinitely. The right operator posture is to acknowledge the drift
+in RUNBOOK.md and surface it via the existing Inbox AckOrphansLane.
+
+**D2: Synthetic batch rows are `kind = '837p'` with a distinct
+`input_filename` sentinel.**
+
+This makes them trivially distinguishable from real ingest batches
+in queries (e.g. `WHERE input_filename LIKE '<synthetic:%>'`). The
+sentinel is `<synthetic:orphan-reconcile>` so any future contributor
+who sees these rows in the DB can grep the codebase for that string
+and find this spec.
+
+**D3: Synthetic rows get NO claims, NO `claim_acks` links.**
+
+The reconciliation pass creates batch rows but does not synthesize
+claim rows for them. The `claims` table stays accurate to what was
+actually ingested. Future acks referencing these synthetic ST02s
+will resolve against the batch envelope index (so the operator can
+see "this 999 is for a known orphan source") but will not link to
+claims.
+
+**D4: Reconcile is idempotent, not auto-runnable.**
+
+The CLI does not auto-run on boot, in the SFTP polling scheduler,
+or via cron. Operators run it manually after they confirm the drift
+is acceptable. Idempotency means a second run is a no-op rather
+than an error.
+
+**D5: Both CLI commands live under `cyclone ack-orphans`.**
+
+This groups them under a shared verb, matching the existing
+`cyclone submit-batch`, `cyclone parse-999`, `cyclone backup`
+subcommand shape. The CLI file is `backend/src/cyclone/cli.py`
+(where `submit-batch` already lives); no new top-level CLI module.
+
+**D6: The store helper is the testable surface; the CLI is a thin
+wrapper.**
+
+`find_ack_orphan_st02_summary() -> list[dict]` is what the tests
+target. The CLI parses flags, calls the helper, formats output,
+sets the exit code. Mirrors the existing `cyclone-cli` convention.
+
+## 3. Open questions
+
+None. The operator has confirmed the design via the brainstorming
+Q&A on 2026-07-07: docs + housekeeping helper + synthetic-batch
+migration, no UI change, no auto-runnable reconcile.
+
+## 4. Test impact
+
+Per `cyclone-tests` (autouse conftest at `backend/tests/conftest.py`):
+
+- `backend/tests/test_ack_orphan_summary.py` — new, tests the store
+  helper directly. 999-only (matches the helper's scope; 277ca /
+  ta1 orphans are tracked by `find_ack_orphans(kind)` but their
+  "ST02" semantics differ — see §1 — so they are excluded from
+  the per-ST02 summary). Asserts the summary shape, asserts
+  idempotency of the reconcile insert, asserts the sentinel
+  `input_filename` is preserved, asserts the `kind = '837p'`
+  invariant.
+- `backend/tests/test_ack_orphans_cli.py` — new, tests the CLI
+  subcommands via `click.testing.CliRunner` (matching the
+  SP37-followup #5 pattern). Asserts exit codes (0 / 1), stdout
+  shape, idempotency of reconcile.
+- No frontend test impact (no UI change).
+- No migration test impact (no schema change; the synthetic batch
+  rows are inserted via SQLAlchemy at runtime, not via the
+  `migrations/` directory).
+
+## 5. Files expected to change
+
+- `docs/RUNBOOK.md` — append "Known historical drift" section under
+  the existing "Operator triage" section.
+- `backend/src/cyclone/store/__init__.py` — add
+  `CycloneStore.find_ack_orphan_st02_summary` + a private
+  `_reconcile_orphan_st02` helper. Re-export through the
+  facade so callers don't need to import from the subpackage
+  directly.
+- `backend/src/cyclone/store/claim_acks.py` — extract the orphan
+  ST02 walk from `find_ack_orphans` into a reusable helper that
+  both `find_ack_orphans` and `find_ack_orphan_st02_summary` can
+  call. Avoids duplicate SQL.
+- `backend/src/cyclone/cli.py` — add the two subcommands.
+- `backend/tests/test_ack_orphan_summary.py` — new, store-helper
+  tests.
+- `backend/tests/test_ack_orphans_cli.py` — new, CLI tests.
+- `docs/superpowers/plans/2026-07-07-cyclone-orphan-ack-housekeeping.md`
+  — the implementation plan, written after this spec is signed off.
+
+## 6. Auth boundary
+
+The auth boundary is HTTP (login required, bcrypt + HttpOnly session
+cookie); file-system threats remain the local-only threat model
+(SQLCipher at rest, macOS Keychain). The two new CLI subcommands
+are operator-invoked only and bypass the HTTP auth boundary by design
+(matching all existing `cyclone` CLI subcommands); they read the
+DB directly via `db.SessionLocal()` and require shell access to the
+host running Cyclone. No change to the threat model.

docs/superpowers/specs/2026-07-07-cyclone-submit-batch-canonical-flow-design.md

@@ -0,0 +1,217 @@
+# Sub-project 37 — Canonical `submit-batch` flow: Design Spec
+
+**Date:** 2026-07-07
+**Status:** Draft, awaiting user sign-off
+**Branch:** `sp37-submit-batch-canonical-flow` (off main, post-SP36 merge)
+**Aesthetic direction:** No UI changes. Pure backend structural + data-model addition — the public HTTP surface gains one new endpoint; existing CLIs and endpoints are preserved unchanged.
+
+---
+
+## 1. Scope
+
+Today, cyclone's `claims` table is essentially empty in production (`clm-1` is the only row as of 2026-07-07). The reason is structural: dzinesco generates the 837P files (in `ingest/corrected/batch-*-claims/*.x12`), cyclone's `resubmit-rejected-claims` CLI only validates and re-uploads them to Gainwell's MFT — it never writes the claims to the DB. When 999 acknowledgments come back referencing those batches, every AK2 set-response becomes an orphan because there is no `Batch` row to join against.
+
+The 999→claim join (the D10 two-pass join in `claim_acks.lookup_claims_for_ack_set_response`) has two paths:
+
+- **Pass 1 (primary):** `Batch.envelope.control_number == 999's set_control_number`. This currently fails because the 999's `set_control_number` (AK201) echoes the source 837's **ST02** (transaction set control number), not the **ISA13** (interchange control number). The parsed `Envelope` model stores ISA13 in `control_number`, so the keys never collide even when the DB row exists.
+- **Pass 2 (fallback):** `Claim.patient_control_number == 999's set_control_number`. This also fails because the `_claim_837_row` ORM builder sets `patient_control_number = claim.claim_id` (CLM01), and CLM01 ≠ ST02 in production batches.
+
+The fix is twofold: (a) make cyclone write a `Batch` + `Claim` rows at submission time so there is something to join against, and (b) make the join key actually match — by storing the ST02 explicitly on `Batch` and using it in Pass 1.
+
+**In scope:**
+
+- A new top-level CLI `cyclone submit-batch` that does parse → DB write → SFTP upload per file, in that order.
+- A new HTTP endpoint `POST /api/submit-batch` with the same semantics.
+- A shared helper module `cyclone.submission.submit_file` so the CLI and HTTP path share one source of truth.
+- A new nullable column `Batch.transaction_set_control_number`, populated from the parsed 837's ST02 on every `add_record` write.
+- An Alembic migration `0013_add_batch_txn_set_control_number.py` (additive, nullable, backfills from `raw_result_json.envelope.transaction_set_control_number` where present).
+- An update to `claim_acks.batch_envelope_index` so Pass 1 also matches on `transaction_set_control_number` (Pass 2 unchanged).
+- Per-claim `claim_submitted` activity events and per-file `clearhouse.submitted` audit events (same shape `resubmit-rejected-claims` already emits).
+
+**Out of scope (explicit):**
+
+- Deprecating `parse-837` CLI or `/api/parse-837` endpoint. They remain for one-off testing and dry-run validation.
+- Deprecating `resubmit-rejected-claims`. It remains the "validate-then-upload without DB write" path for the dzinesco-generated files that aren't ready for canonical tracking.
+- UI changes. The Claims page already renders the fields a new tracked claim needs; the existing `claim_written` live-tail event fires automatically from `add_record`.
+- Bulk backfill of the existing `ingest/corrected/batch-*-claims/*.x12` backlog. A follow-up SP will walk that directory once `submit-batch` is proven.
+- Any change to the `claims` row schema beyond the new `Batch` column.
+- SFTP auth work. This box stays in manual mode (post-2026-07-07 incident); `submit-batch` works in stub mode for local testing and against a whitelisted IP for production.
+
+## 2. Decisions (locked during brainstorming)
+
+These were each a multiple-choice question with operator sign-off on 2026-07-07.
+
+1. **Where does the DB write happen?** New canonical `submit` flow. `submit-batch` parses → writes to DB → uploads, replacing neither `parse-837` nor `resubmit-rejected-claims` but superseding them as the preferred path.
+2. **DB vs upload ordering?** DB-first, upload-second. If DB write fails, the file never goes on the wire. If DB write succeeds but upload fails, re-running is safe (idempotent DB write, idempotent SFTP put).
+3. **Join key for 999 acks?** Add `Batch.transaction_set_control_number` column. Update Pass 1 to match on it. Don't repurpose `envelope.control_number` (preserves backward compat with existing joins) and don't force CLM01 == ST02 (Gainwell's existing 999s use different values).
+4. **Deprecation posture?** Add `submit-batch`; preserve `parse-837` and `resubmit-rejected-claims`. Document `submit-batch` as preferred in CLAUDE.md + RUNBOOK. Future SP can deprecate if usage shifts.
+
+## 3. Architecture
+
+The new flow is a single, small public surface — one CLI command, one HTTP endpoint, one shared helper. The helper owns the parse → write → upload sequence and is the only place that knows about the order.
+
+### Module layout
+
+A new package `cyclone.submission` (under `backend/src/cyclone/submission/`) holds the shared helper:
+
+- `__init__.py` — re-exports `submit_file`, `SubmitResult`, `SubmitOutcome`
+- `core.py` — `submit_file(path: Path, *, sftp_block, actor: str, event_bus=None, validate: bool = True) -> SubmitResult`. Owns its own DB session for the parse-write step, returns a result dataclass the caller inspects.
+- `cli.py` — Click handler for `cyclone submit-batch`. Walks `--ingest-dir`, calls `submit_file` per file, aggregates counts, exits 0/1/2 per cyclone-cli convention.
+- `api.py` — FastAPI handler for `POST /api/submit-batch`. Mounted in `api_routers/submission.py`. Calls `submit_file` per file. Auth-gated by the existing `matrix_gate`.
+
+### `submit_file` algorithm
+
+The walker globs `<ingest_dir>/batch-*-claims/*.x12` (mirrors `resubmit-rejected-claims` exactly — same pattern, same `_`-prefix skip for AppleDouble residue). For each matched file:
+
+1. Read bytes; if `validate=True`, run `parse_837_text(bytes, payer_cfg)`. On parse failure, record `{path, "parse_failed", exc}` and return without writing or uploading.
+2. Run a payer-id check (must be `CO_TXIX`); on mismatch, record and return.
+3. Call `store.add_record(record, event_bus=...)`. On DB failure, record and return (no SFTP call).
+4. Build the remote path `{outbound_root}/{filename}`. Open an `SftpClient` (the seeded singleton). On SFTP connect failure, record and return — the DB row is already written; the re-run will skip it via idempotency.
+5. `sftp_client.stat(remote_path)` — if `st_size == local_size`, mark as `skipped` (already uploaded; do not re-emit audit). Otherwise `sftp_client.write_file(remote_path, bytes)`.
+6. On successful upload, emit one `clearhouse.submitted` audit event with `source_file`, `batch_id`, `actor`.
+
+### Idempotency
+
+Two layers, both per-file:
+
+- **DB layer:** `store.add_record` already does a `s.get(Claim, claim.claim_id)` check before insert. A re-parse of the same file logs "claim already exists; skipping" and continues. Re-running `submit-batch` on an already-tracked file is a no-op on the DB.
+- **SFTP layer:** the `sftp.stat().st_size == local_size` check before `write_file` short-circuits already-uploaded files.
+
+### Failure modes summary
+
+- Parse fails → no DB write, no SFTP put, file counted as `failed`.
+- Payer-id mismatch → same as parse fail.
+- DB write fails → no SFTP put, file counted as `failed`. The DB session rolls back; no orphan rows.
+- SFTP connect fails → DB row already committed; file counted as `failed`. Re-run is safe.
+- SFTP stat succeeds + size match → counted as `skipped`; no audit event.
+- SFTP write fails → file counted as `failed`. DB row already committed. Re-run is safe.
+- Crash between DB write and SFTP put → DB row exists, file never landed. Re-run will see the size mismatch (remote doesn't have it) and upload.
+
+## 4. Data flow & error handling
+
+### `POST /api/submit-batch`
+
+Request body (JSON):
+- `ingest_dir: string` — root directory holding `batch-*-claims/*.x12` subfolders (mirrors the CLI flag).
+- `validate: bool = true` — pass-through to `submit_file`.
+- `actor: string = "api-submit-batch"` — audit actor tag.
+- `limit: int | null = null` — stop after N files (smoke test).
+
+Response body (200):
+- `submitted: int` — files uploaded this run.
+- `skipped: int` — files already on remote (size match).
+- `failed: int` — files that hit parse / payer / DB / SFTP errors.
+- `results: list<{file: string, outcome: "submitted"|"skipped"|"parse_failed"|"payer_mismatch"|"db_failed"|"sftp_failed", batch_id: string|null, error: string|null}>` — per-file detail.
+
+Status codes:
+- `200` — run completed (may have failures; details in the response body).
+- `401` — no auth cookie (matrix_gate).
+- `422` — body validation failure.
+- `500` — unexpected exception (caught by the existing `@app.exception_handler(Exception)`).
+
+### CLI exit codes (per `cyclone-cli` convention)
+
+- `0` — run completed, even with some per-file failures (the per-file detail is in stdout).
+- `1` — unexpected exception (uncaught error in the walker or the helper itself).
+- `2` — config-level failure (no clearhouse seeded, SFTP block in stub mode for non-stubbed invocation, ingest-dir doesn't exist).
+
+### Audit + live-tail events
+
+- `claim_submitted` (one per Claim row) — emitted by `add_record` already; no new code path.
+- `clearhouse.submitted` (one per successful upload) — emitted by `submit_file` after the SFTP put succeeds. Same actor tag and payload shape as the current `resubmit-rejected-claims` path uses.
+
+### Migration `0013_add_batch_txn_set_control_number.py`
+
+- `op.add_column('batches', sa.Column('transaction_set_control_number', sa.String(32), nullable=True))`.
+- Backfill: `UPDATE batches SET transaction_set_control_number = json_extract(raw_result_json, '$.envelope.transaction_set_control_number') WHERE raw_result_json IS NOT NULL AND json_extract(raw_result_json, '$.envelope.transaction_set_control_number') IS NOT NULL`.
+- Reversible: drop column.
+- The down migration is `op.drop_column('batches', 'transaction_set_control_number')`.
+
+### Join-key update in `claim_acks.batch_envelope_index`
+
+The existing function reads every `Batch` row whose `raw_result_json` has an envelope and returns `dict[str, str]` keyed by `envelope.control_number`. The updated version returns the **same shape** — a single `dict[str, str]` — but **populated from two columns**:
+
+- Each row contributes one entry keyed by `envelope.control_number` (preserved).
+- Each row also contributes one entry keyed by `transaction_set_control_number` (new), when that column is non-NULL.
+
+If both keys resolve to the same value (Gainwell batches where the ST02 happens to equal the ISA13 — unusual but legal), the second insert is a no-op. If they differ, both keys point to the same `batch.id` — a single `idx.get(set_control_number)` lookup will match either one. The dict may grow by up to `len(batches)` new entries; callers that previously assumed `len(index) == len(batches)` are unaffected because that invariant was already loose (multiple ST02s can share one ISA13).
+
+`lookup_claims_for_ack_set_response` Pass 1 is unchanged at the call site — one `idx.get(set_control_number)` lookup that succeeds whether the source 837's ST02 matches a `transaction_set_control_number` row or an `envelope.control_number` row. Pass 2 (PCN) fires as today if both miss.
+
+## 5. Testing approach
+
+Per `cyclone-tests` skill: pytest under `backend/tests/`, two flavors — `test_api_*` (FastAPI integration) and `test_*` (pure unit). Frontend tests out of scope (no UI changes).
+
+### Unit tests (`backend/tests/test_submission.py`)
+
+- `submit_file happy path` — mock SFTP, real DB; assert one Batch + N Claim rows + one audit event.
+- `submit_file idempotency on DB` — call `submit_file` twice with the same file; assert second call returns `skipped` (DB no-op).
+- `submit_file idempotency on SFTP` — mock SFTP `stat` to return matching size; assert `skipped`, no second `write_file` call, no second audit event.
+- `submit_file parse fail` — pass a bad 837; assert no DB write, no SFTP call, `parse_failed` outcome.
+- `submit_file payer mismatch` — pass a valid 837 with wrong payer_id; assert no DB write, no SFTP call, `payer_mismatch` outcome.
+- `submit_file DB fail` — monkey-patch `add_record` to raise; assert no SFTP call, `db_failed` outcome.
+- `submit_file SFTP fail` — mock SFTP `write_file` to raise; assert `sftp_failed` outcome, DB row still present.
+- `submit_file re-run after partial failure` — submit a file that fails SFTP, then submit again with SFTP working; assert second run uploads and emits audit.
+
+### Integration tests (`backend/tests/test_api_submit_batch.py`)
+
+- `POST /api/submit-batch` happy path — 3 valid 837 fixtures in `ingest_dir`; assert 200 + body shape.
+- `POST /api/submit-batch` auth gate — no cookie → 401 (matrix_gate).
+- `POST /api/submit-batch` body validation — missing `ingest_dir` → 422.
+
+### Migration tests (`backend/tests/test_migration_0013.py`)
+
+- Up + down on a fresh DB; column exists + is nullable; backfill populates the column from raw JSON.
+
+### Join-key update tests (`backend/tests/test_claim_acks_index.py`)
+
+- `batch_envelope_index` returns both maps; Pass 1 finds a claim by ST02 even when ISA13 differs; Pass 1 finds by ISA13 (backward compat); Pass 2 fallback still works.
+
+### Live test (after merge)
+
+Walk an actual `ingest/batch-*-claims/` directory via the CLI; verify:
+- `claims` table has new rows with the expected `patient_control_number` (CLM01).
+- `batches` table has new rows with `transaction_set_control_number` matching the parsed ST02.
+- Live-tail `claim_written` events fire on the API.
+
+Then drop a synthetic 999 (with the matching AK2 set_control_number) into `ingest/`, run `pull-inbound`, verify the `ClaimAck` link row is created (not an orphan).
+
+## 6. Threat model (post-SP24 alignment)
+
+No new attack surface. The new endpoint and CLI:
+
+- Are gated by the existing `matrix_gate` (HTTP) and `CYCLONE_AUTH_DISABLED` env var.
+- Use the same SFTP client and credential paths as `resubmit-rejected-claims` today.
+- Write to the same store facade; no new SQL surface.
+- Emit the same audit events with the same payload shape.
+
+The `transaction_set_control_number` column is operator-visible (it's in the raw `batches` row), but no auth boundary depends on it being absent. PII exposure is unchanged (the column carries the same value the 999 ack would have echoed back — already public-to-Gainwell).
+
+## 7. Risks & mitigations
+
+- **Risk:** The new `submission` package is the third "command runner" in the codebase (alongside `cli.py`'s standalone commands and `scheduler.py`). **Mitigation:** Keep `submit_file` as a pure helper with no FastAPI/Click dependencies; the API and CLI handlers are thin wrappers. Document the layering in `submission/__init__.py`'s module docstring.
+- **Risk:** `resubmit-rejected-claims` and `submit-batch` will diverge over time (one writes to DB, one doesn't). **Mitigation:** Both call the same `submit_file` helper if `submit-batch`'s `--write-to-db` flag is set to true (default). Document the divergence point in RUNBOOK.
+- **Risk:** Migration backfill could be slow on a large DB. **Mitigation:** `UPDATE ... WHERE json_extract(...) IS NOT NULL` is one pass; on a million-row DB this is sub-second. Index on `transaction_set_control_number` not added (low cardinality per batch; existing `ix_claims_patient_control_number` covers the hot path).
+- **Risk:** Live-tail event volume doubles when `submit-batch` runs (one `claim_submitted` per claim in addition to the historical `claim_written`). **Mitigation:** This is desired behavior — the operator wants the activity feed to show submissions. Document in the RUNBOOK that submitting a 1000-claim batch will publish ~1000 events.
+
+## 8. Rollout
+
+- **Branch:** `sp37-submit-batch-canonical-flow`, off main as of `710104f`.
+- **Implementation order:**
+  1. Migration `0013` + backfill (additive, no behavior change yet).
+  2. Update `claim_acks.batch_envelope_index` + Pass 1 lookup (no behavior change yet — the new map is built but unused until `submit-batch` writes rows).
+  3. `cyclone/submission/core.py` helper + unit tests.
+  4. CLI handler `cyclone submit-batch` + smoke test.
+  5. HTTP handler `POST /api/submit-batch` + integration tests.
+  6. Live test with one of the existing `ingest/batch-*-claims/*.x12` directories (will be in stub mode on this host).
+- **Live test cadence:** per the user's standing directive — live-test after each significant step, run autoreview, commit.
+- **Merge shape:** single atomic merge commit per SP-N convention. No squash. No rebase.
+- **Post-merge:** RUNBOOK update for the canonical flow; CLAUDE.md update to mark `submit-batch` as preferred.
+
+## 9. Open questions
+
+None blocking the spec. Tracked for follow-up SPs:
+
+- **Backfill command** — once `submit-batch` is proven, a `cyclone backfill-claims` CLI that walks the existing `ingest/corrected/batch-*-claims/*.x12` backlog (without uploading — they're already on Gainwell's side) and writes the DB rows. This is what would un-orphan the 1491+ orphan 999 acks currently in the DB.
+- **Deprecation timeline for `resubmit-rejected-claims`** — once `submit-batch` is the default, consider folding `resubmit-rejected-claims` into a `--no-write-to-db` flag on `submit-batch` to consolidate the surface.
+- **Cross-link to 277CA acks** — same `transaction_set_control_number` join key will resolve 277CA orphans if/when those arrive. The migration and index update cover both 999 and 277CA since both use Pass 1.