feat(parsers+api+ui+db): 999 ACK transaction set end-to-end (SP3 P3)

backend/src/cyclone/store.py

@@ -39,6 +39,7 @@ from pydantic import BaseModel, ConfigDict, model_validator
 
 from cyclone import db
 from cyclone.db import (
+    Ack,
     ActivityEvent,
     Batch,
     CasAdjustment,
@@ -1088,6 +1089,58 @@ class CycloneStore:
                 for r in rows
             ]
 
+    # -- 999 ACKs (SP3 P3 T13) -------------------------------------------
+
+    def add_ack(
+        self,
+        *,
+        source_batch_id: str,
+        accepted_count: int,
+        rejected_count: int,
+        received_count: int,
+        ack_code: str,
+        raw_json: dict,
+    ) -> db.Ack:
+        """Persist a 999 ACK row and return it.
+
+        ``source_batch_id`` must reference an existing ``batches.id``.
+        For received 999s with no source batch the caller should pass a
+        synthetic id (e.g. ``"999-<interchange_control_number>"``) —
+        see ``/api/parse-999`` for that policy.
+
+        ``raw_json`` is the full ``ParseResult999`` model dump; the
+        detail endpoint surfaces it without re-parsing the original
+        X12 text.
+        """
+        with db.SessionLocal()() as s:
+            row = Ack(
+                source_batch_id=source_batch_id,
+                accepted_count=accepted_count,
+                rejected_count=rejected_count,
+                received_count=received_count,
+                ack_code=ack_code,
+                parsed_at=utcnow(),
+                raw_json=raw_json,
+            )
+            s.add(row)
+            s.commit()
+            s.refresh(row)
+            return row
+
+    def list_acks(self) -> list[db.Ack]:
+        """Return every 999 ACK row, newest first (auto-increment id desc)."""
+        with db.SessionLocal()() as s:
+            return (
+                s.query(Ack)
+                .order_by(Ack.id.desc())
+                .all()
+            )
+
+    def get_ack(self, ack_id: int) -> db.Ack | None:
+        """Return a single ACK row by id, or ``None`` if not found."""
+        with db.SessionLocal()() as s:
+            return s.get(Ack, ack_id)
+
     # -- manual reconciliation (T12) -----------------------------------
 
     def list_unmatched(self, *, kind: str = "both") -> dict: