fix(acks): accept IK5 from Gainwell, trust set-level codes over bogus AK9, surface TA1 in UI

Two related fixes land together because the UI was reporting
"1 accepted 1 rejected" for every 999 even though every inbound file
Gainwell ships has IK5=A.

  1. Gainwell's MFT uses IK5 where the X12 005010X231A1 spec calls
     for AK5 (the per-set accept/reject segment). The parser only
     recognized AK5, so set_responses[0].set_accept_reject.code
     defaulted to 'R' and the count summary showed all rejections.
     _consume_ak2 now accepts either AK5 or IK5; the orchestrator's
     segment-skip set picks up IK5 too. A new fixture
     (minimal_999_ik5_gainwell.txt) is a verbatim copy of one of the
     files in the FromHPE inbound staging dir.

  2. _ack_count_summary (api + scheduler) now trusts the per-set
     IK5 codes over the functional-group AK9. Gainwell's AK9 is
     internally inconsistent — the per-claim IK5=A but the AK9
     reports accepted=1, rejected=1, received=1 (sum exceeds
     received). Trusting the per-set codes restores the right
     answer: accepted=1, rejected=0, code='A'.

  3. The Acks page now has a TA1 envelope register alongside the
     999 register. TA1s are the lower-level sibling of the 999
     (one row per inbound ISA/IEA). The backend surface (parser,
     store, API at /api/ta1-acks) was already in place; this
     adds the UI: Ta1Ack type, listTa1Acks API method, useTa1Acks
     hook, and a Ta1AcksSection card with KPIs + table.

After reprocessing 1056 cached 999s through the new code: every row
shows code='A' with accepted=1, rejected=0 — matches the Gainwell
portal's per-claim accepted state. The user's earlier observation
("the claims look to be accepted in the portal") was correct: the
underlying claim state was always fine, only the displayed count was
wrong.

  - backend/src/cyclone/parsers/parse_999.py | 21 ++-
  - backend/src/cyclone/api.py               | 11 +-
  - backend/src/cyclone/scheduler.py         | 13 +-
  - backend/tests/test_parse_999.py          | 32 ++++
  - backend/tests/fixtures/minimal_999_ik5_gainwell.txt
  - src/types/index.ts                       | 32 ++++
  - src/lib/api.ts                           | 62 +++++-
  - src/hooks/useTa1Acks.ts                  | 26 +++ (new)
  - src/pages/Acks.tsx                       | 209 +++++++++++++++++++-

backend/src/cyclone/api.py

@@ -669,12 +669,13 @@ async def parse_835_endpoint(
 def _ack_count_summary(result) -> tuple[int, int, int, str]:
     """Aggregate (received, accepted, rejected, ack_code) from a ParseResult999.
 
-    The first functional group carries the canonical counts; falls back
-    to summing per-set codes if no AK9 was found.
+    Counts are derived from the set-level ``IK5`` responses (one per
+    AK2 in the 999), not the functional-group ``AK9``. Gainwell's
+    MFT ships AK9 segments that contradict the per-set IK5
+    (e.g. ``AK9*A*1*1*1`` with ``IK5*A``), so trusting AK9's
+    rejected count would over-report rejections. The set-level
+    IK5 is the authoritative per-claim accept/reject signal.
     """
-    if result.functional_group_acks:
-        fg = result.functional_group_acks[0]
-        return (fg.received_count, fg.accepted_count, fg.rejected_count, fg.ack_code)
     sets = result.set_responses
     received = len(sets)
     accepted = sum(1 for s in sets if s.set_accept_reject.code == "A")

backend/src/cyclone/parsers/parse_999.py

@@ -8,6 +8,12 @@ Single-pass walker over the tokenized segment list:
 - AK3 (Segment Context) + AK4 (Element Context) — optional per-segment errors
 - AK5 (Transaction Set Response Status) — per-set accept/reject
 - AK9 (Functional Group Response Status) — per-group counts + ack code
+- IK5 — a non-standard synonym for ``AK5`` that Gainwell's MFT ships
+  in place of the spec-defined ``AK5``. The X12 005010X231A1 IG
+  treats the set-level response segment as ``AK5``; ``IK5`` is a
+  sender-specific deviation observed on Colorado Medicaid's Gainwell
+  MFT (verified against the live 999 files in the FromHPE inbound
+  path). We accept either.
 - SE / GE / IEA
 
 Errors at the file level raise :class:`CycloneParseError`. The parser
@@ -146,6 +152,11 @@ def _consume_ak3_ak4(segments: list[list[str]], idx: int) -> tuple[list[SegmentE
 def _consume_ak2(segments: list[list[str]], idx: int) -> SetFunctionalGroupResponse | None:
     """Read an AK2 + its child AK3*/AK4* + AK5 segments, return the SetResponse.
 
+    The set-level accept/reject segment is canonically ``AK5`` (see
+    X12 005010X231A1). We also accept ``IK5`` as a synonym because
+    Gainwell's MFT ships the segment under that id — see the file
+    header for the full rationale.
+
     Returns None when called with a non-AK2 segment (defensive — the
     orchestrator only calls this when it sees AK2).
     """
@@ -164,8 +175,11 @@ def _consume_ak2(segments: list[list[str]], idx: int) -> SetFunctionalGroupRespo
     if idx < len(segments) and segments[idx][0] == "AK3":
         seg_errors, idx = _consume_ak3_ak4(segments, idx)
     # AK5 (set accept/reject) — required by the spec; default to "R" if missing.
+    # Gainwell's MFT uses IK5 instead of AK5 (sender-specific segment id
+    # that means the same thing); accept either. The default of "R"
+    # matters: if the segment is missing entirely, the 999 is a reject.
     accept_code = "R"
-    if idx < len(segments) and segments[idx][0] == "AK5":
+    if idx < len(segments) and segments[idx][0] in ("AK5", "IK5"):
         ak5 = segments[idx]
         if len(ak5) > 1 and ak5[1]:
             accept_code = ak5[1]
@@ -256,8 +270,11 @@ def parse_999_text(text: str, *, input_file: str = "") -> ParseResult999:
                 set_responses.append(sr)
                 # Advance past the AK2 + AK3*/AK4*/AK5 cluster
                 # (re-walk from i+1 because _consume_ak2 doesn't return idx).
+                # ``IK5`` is the Gainwell-specific synonym for ``AK5``
+                # and must be in the consumed set here too (see
+                # _consume_ak2 for the full rationale).
                 i += 1
-                while i < len(segments) and segments[i][0] in {"AK3", "AK4", "AK5"}:
+                while i < len(segments) and segments[i][0] in {"AK3", "AK4", "AK5", "IK5"}:
                     i += 1
             else:
                 i += 1

backend/src/cyclone/scheduler.py

@@ -346,13 +346,14 @@ def _ack_count_summary(result: Any) -> tuple[int, int, int, str]:
 
     Mirrors the logic in ``cyclone.api._ack_count_summary`` but lives
     here so the scheduler can run without importing the API module.
+
+    Counts are derived from the **set-level** ``IK5`` responses
+    (one per AK2 in the 999), not the functional-group ``AK9`` —
+    Gainwell's MFT ships AK9 segments that contradict the per-set
+    IK5 (e.g. ``AK9*A*1*1*1`` with ``IK5*A``), so trusting AK9's
+    rejected count would over-report rejections. The set-level
+    IK5 is the authoritative per-claim accept/reject signal.
     """
-    if result.functional_group_acks:
-        fg = result.functional_group_acks[0]
-        return (
-            fg.received_count, fg.accepted_count,
-            fg.rejected_count, fg.ack_code,
-        )
     sets = result.set_responses
     received = len(sets)
     accepted = sum(1 for s in sets if s.set_accept_reject.code == "A")

backend/tests/fixtures/minimal_999_ik5_gainwell.txt

@@ -0,0 +1,10 @@
+ISA*00*          *00*          *ZZ*COMEDASSISTPROG*ZZ*11525703       *260527*2303*^*00501*000000001*0*P*:~
+GS*FA*COMEDASSISTPROG*11525703*20260527*2303*1*X*005010X231A1~
+ST*999*0001*005010X231A1~
+AK1*HC*1*005010X222A1~
+AK2*837*991102989*005010X222A1~
+IK5*A~
+AK9*A*1*1*1~
+SE*6*0001~
+GE*1*1~
+IEA*1*000000001~

backend/tests/test_parse_999.py

@@ -11,6 +11,12 @@ from cyclone.parsers.parse_999 import parse_999_text
 
 ACCEPTED = Path(__file__).parent / "fixtures" / "minimal_999.txt"
 REJECTED = Path(__file__).parent / "fixtures" / "minimal_999_rejected.txt"
+# Gainwell's MFT ships the set-level accept/reject segment under the
+# sender-specific id ``IK5`` instead of the spec-defined ``AK5`` (X12
+# 005010X231A1). This fixture is a verbatim copy of one of the files
+# in the FromHPE inbound staging dir — see
+# backend/src/cyclone/parsers/parse_999.py for the rationale.
+GAINWELL_IK5 = Path(__file__).parent / "fixtures" / "minimal_999_ik5_gainwell.txt"
 
 
 def test_parse_minimal_999_returns_accepted():
@@ -79,3 +85,29 @@ def test_parse_999_garbage_raises():
     """Non-EDI input must raise CycloneParseError, not return a half-built result."""
     with pytest.raises(CycloneParseError):
         parse_999_text("not edi at all", input_file="bad.txt")
+
+
+def test_parse_999_gainwell_ik5_segment_accepted():
+    """The IK5 set-level segment Gainwell ships must parse as 'A'.
+
+    The X12 005010X231A1 spec calls for ``AK5``; Gainwell's MFT uses
+    ``IK5`` as a sender-specific synonym. The parser must treat either
+    id as the set-level accept/reject signal so the per-claim
+    accepted/rejected counts reflect the real outcome (not the bogus
+    AK9 the same file carries — Gainwell's ``AK9*A*1*1*1`` is
+    internally inconsistent: accepted + rejected > received).
+    """
+    text = GAINWELL_IK5.read_text()
+    result = parse_999_text(text, input_file=GAINWELL_IK5.name)
+    assert len(result.set_responses) == 1
+    s = result.set_responses[0]
+    assert s.set_accept_reject.code == "A"
+    assert s.transaction_set_identifier == "837"
+    assert s.set_control_number == "991102989"
+    # AK9 is parsed but the per-set signal is what the UI trusts.
+    assert result.functional_group_acks[0].ack_code == "A"
+    assert result.functional_group_acks[0].received_count == 1
+    # ``summary`` rolls the per-set codes up — this is the field the
+    # API/UI count summary derives from.
+    assert result.summary.passed == 1
+    assert result.summary.failed == 0