feat(sp14): 5-lane Inbox UI with Payer-Rejected acknowledge action

Closes the gap between the SP10 backend (5 lanes) and the SP6
frontend (4 lanes). The Payer-Rejected lane (277CA STC A4/A6/A7)
is now rendered alongside Rejected/Candidates/Unmatched/Done,
with an Acknowledge bulk action that drops claims from the
working surface without erasing the original 277CA rejection
event (audit log stays intact, SP11).

Backend:
* Migration 0010: add payer_rejected_acknowledged_at +
  payer_rejected_acknowledged_actor columns + partial index.
* db.py: surface the two new columns on the Claim model.
* inbox_lanes.py: filter acknowledged claims out of the
  payer_rejected lane; expose the new fields on the row payload
  for forward-compat (e.g. a future 'Recently acknowledged' view).
* api.py:
  - POST /api/inbox/payer-rejected/acknowledge
    Bulk-acknowledge. Idempotent. Returns transitioned /
    already_acked / not_found / not_rejected counts so the UI
    can show '3 of 5 were already acknowledged' on a noop bulk.
    Writes a 'claim.payer_rejected_acknowledged' event to the
    SP11 hash-chained audit log.
  - GET /api/inbox/export.csv: accept 'payer_rejected' lane.
* test_acks.py: bump user_version assertion to 10.
* test_lane_filter_acknowledged.py: 4 tests for the lane filter
  and forward-compat row payload.
* test_payer_rejected_acknowledge.py: 6 tests for the endpoint
  (happy path, idempotency, no-op on non-rejected, missing
  ids, 400 on empty, audit-log wiring + chain integrity).

Frontend:
* lib/inbox-api.ts: add payer_rejected to InboxLanes, add
  acknowledgePayerRejected(), update exportInboxCsvUrl union.
* hooks/useInboxLanes.ts: add payer_rejected to initial state.
* hooks/useInboxLanes.test.ts: add payer_rejected to mocks.
* components/inbox/BulkBar.tsx: add 'payer_rejected' lane with
  Acknowledge action (no Resubmit, no Dismiss — payer-rejected
  is not eligible for either).
* components/inbox/BulkBar.test.tsx: add payer_rejected test.
* pages/Inbox.tsx: render the 5th lane, hook up onAcknowledge,
  include payer_rejected in the needEyes count.
* pages/Inbox.test.tsx: 3 new tests (5-lane render, need-eyes
  count, acknowledge action hits the right endpoint).
* components/inbox/InboxHeader.tsx: doc comment now explains
  why payer_rejected rolls up into need-eyes.

Pre-existing typecheck warnings in BulkBar.test.tsx / InboxRow
.test.tsx / Lane.tsx / download.test.ts are unchanged from
main — not touched here.

Test counts: backend 724 -> 734 (+10). Frontend 350 -> 354 (+4).

src/components/inbox/BulkBar.test.tsx

@@ -1,6 +1,6 @@
 // @vitest-environment happy-dom
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { cleanup, render, screen, fireEvent } from "@testing-library/react";
+import { cleanup, render, fireEvent } from "@testing-library/react";
 import { BulkBar } from "./BulkBar";
 
 afterEach(() => cleanup());
@@ -12,6 +12,7 @@ describe("BulkBar", () => {
         lane="rejected"
         count={3}
         onResubmit={vi.fn()}
+        onAcknowledge={() => {}}
         onDismiss={vi.fn()}
         onExport={vi.fn()}
       />,
@@ -28,6 +29,7 @@ describe("BulkBar", () => {
         lane="rejected"
         count={2}
         onResubmit={onResubmit}
+        onAcknowledge={() => {}}
         onDismiss={() => {}}
         onExport={() => {}}
       />,
@@ -39,12 +41,36 @@ describe("BulkBar", () => {
     expect(onResubmit).toHaveBeenCalledOnce();
   });
 
+  it("SP14: payer_rejected lane shows Acknowledge (not Resubmit/Dismiss)", () => {
+    // Payer-rejected claims are not eligible for resubmit (the payer
+    // already said no); the operator can only acknowledge them as
+    // "I've seen this" and export the row set for follow-up.
+    const onAcknowledge = vi.fn();
+    const { container, getByTestId } = render(
+      <BulkBar
+        lane="payer_rejected"
+        count={4}
+        onResubmit={() => {}}
+        onAcknowledge={onAcknowledge}
+        onDismiss={() => {}}
+        onExport={() => {}}
+      />,
+    );
+    expect(container.textContent).toMatch(/acknowledge/i);
+    expect(container.textContent).not.toMatch(/re-?submit/i);
+    expect(container.textContent).not.toMatch(/dismiss/i);
+    const ack = getByTestId("payer-rejected-acknowledge");
+    fireEvent.click(ack);
+    expect(onAcknowledge).toHaveBeenCalledOnce();
+  });
+
   it("hides when count is zero", () => {
     const { container } = render(
       <BulkBar
         lane="rejected"
         count={0}
         onResubmit={() => {}}
+        onAcknowledge={() => {}}
         onDismiss={() => {}}
         onExport={() => {}}
       />,

src/components/inbox/BulkBar.tsx

@@ -1,13 +1,40 @@
+// ---------------------------------------------------------------------------
+// BulkBar
+//
+// Per-lane floating action bar. Each Inbox lane has its own BulkBar —
+// the bar shows when the lane has a selection and exposes the actions
+// appropriate to that lane:
+//
+//   * rejected       → Re-submit (move back to SUBMITTED)
+//   * payer_rejected  → Acknowledge (drop from working surface; SP14)
+//   * candidates     → Dismiss (suppress a remit/claim pair)
+//   * unmatched      → (no destructive action; just export)
+//   * done_today     → (read-only; just export)
+//
+// Every lane gets the Export CSV action so the operator can ship
+// anything actionable to a file for off-system follow-up (appeals,
+// re-keying, posting to the billing system of record, etc).
+// ---------------------------------------------------------------------------
+
+type LaneKey =
+  | "rejected"
+  | "payer_rejected"
+  | "candidates"
+  | "unmatched"
+  | "done_today";
+
 export function BulkBar({
   lane,
   count,
   onResubmit,
+  onAcknowledge,
   onDismiss,
   onExport,
 }: {
-  lane: "rejected" | "candidates" | "unmatched" | "done_today";
+  lane: LaneKey;
   count: number;
   onResubmit: () => void;
+  onAcknowledge: () => void;
   onDismiss: () => void;
   onExport: () => void;
 }) {
@@ -52,6 +79,16 @@ export function BulkBar({
           Re-submit ({count})
         </button>
       )}
+      {lane === "payer_rejected" && (
+        <button
+          onClick={onAcknowledge}
+          data-testid="payer-rejected-acknowledge"
+          className="px-2.5 py-1 rounded-sm uppercase tracking-[0.12em] transition-colors hover:bg-[color:var(--tt-amber)]/10 focus-visible:outline-none focus-visible:bg-[color:var(--tt-amber)]/10"
+          style={{ color: "var(--tt-ink)", fontWeight: 600 }}
+        >
+          Acknowledge ({count})
+        </button>
+      )}
       {lane === "candidates" && (
         <button
           onClick={onDismiss}

src/components/inbox/InboxHeader.tsx

@@ -1,3 +1,16 @@
+// ---------------------------------------------------------------------------
+// InboxHeader
+//
+// Compact working-surface header: the day/date, a live clock, and the
+// two top-line counts ("N items need eyes" and "N done today") that
+// anchor the operator's day. "Need eyes" is computed by the Inbox
+// page (sum of actionable lanes) and passed in.
+//
+// SP14: payer_rejected (277CA) is now part of the actionable lanes —
+// it's a working-surface rejection that needs operator follow-up.
+// The Inbox page sums it into the needEyes count.
+// ---------------------------------------------------------------------------
+
 export function InboxHeader({
   needEyesCount,
   doneTodayCount,

src/hooks/useInboxLanes.test.ts

@@ -39,6 +39,8 @@ function emptyLanesPayload() {
     ok: true,
     json: async () => ({
       rejected: [],
+      // SP14: payer-rejected lane was added to the working surface.
+      payer_rejected: [],
       candidates: [],
       unmatched: [],
       done_today: [],
@@ -74,6 +76,7 @@ describe("useInboxLanes", () => {
     await waitFor(() => expect(result.current.loading).toBe(false));
     expect(result.current.lanes).toEqual({
       rejected: [],
+      payer_rejected: [],
       candidates: [],
       unmatched: [],
       done_today: [],

src/hooks/useInboxLanes.ts

@@ -31,6 +31,8 @@ const REFETCH_DEBOUNCE_MS = 250;
 export function useInboxLanes() {
   const [lanes, setLanes] = useState<InboxLanes>({
     rejected: [],
+    // SP14: the 5th working-surface lane (277CA STC A4/A6/A7).
+    payer_rejected: [],
     candidates: [],
     unmatched: [],
     done_today: [],

src/lib/inbox-api.ts

@@ -1,9 +1,13 @@
 // ---------------------------------------------------------------------------
 // Inbox API client (sub-project 6).
 //
-// Mirrors the four-lane working surface: rejected / candidates / unmatched /
-// done_today. Plus the actions: manual match, dismiss, resubmit, export.
-// All non-2xx responses throw (so callers can branch on status).
+// Mirrors the five-lane working surface: rejected / payer_rejected /
+// candidates / unmatched / done_today. Plus the actions: manual match,
+// dismiss, resubmit, acknowledge, export. All non-2xx responses throw
+// (so callers can branch on status).
+//
+// SP14: added the `payer_rejected` lane (277CA STC A4/A6/A7) and the
+// `acknowledge` action — distinct from the 999 envelope `rejected` lane.
 // ---------------------------------------------------------------------------
 
 export type ScoreBreakdown = {
@@ -39,6 +43,17 @@ export type InboxClaimRow = {
     matched_lines: number;
     total_lines: number;
   } | null;
+  // SP10/SP14: payer-side rejection fields. Populated on the
+  // `payer_rejected` lane with the 277CA STC category, reason,
+  // and source 277CA id. The ack fields are always null on the
+  // lane (we filter acknowledged claims out) but exposed for
+  // forward-compat.
+  payer_rejected_at?: string | null;
+  payer_rejected_reason?: string | null;
+  payer_rejected_status_code?: string | null;
+  payer_rejected_by_277ca_id?: string | null;
+  payer_rejected_acknowledged_at?: string | null;
+  payer_rejected_acknowledged_actor?: string | null;
 };
 
 export type InboxCandidateRow = {
@@ -59,6 +74,8 @@ export type InboxCandidateRow = {
 
 export type InboxLanes = {
   rejected: InboxClaimRow[];
+  /** SP14: 277CA STC A4/A6/A7 — payer-side rejection, distinct from 999. */
+  payer_rejected: InboxClaimRow[];
   candidates: InboxCandidateRow[];
   unmatched: InboxClaimRow[];
   done_today: InboxClaimRow[];
@@ -173,7 +190,38 @@ export async function resubmitRejectedWithDownload(
 }
 
 export function exportInboxCsvUrl(
-  lane: "rejected" | "candidates" | "unmatched" | "done_today",
+  lane:
+    | "rejected"
+    | "payer_rejected"
+    | "candidates"
+    | "unmatched"
+    | "done_today",
 ): string {
   return joinUrl(`/api/inbox/export.csv?lane=${lane}`);
 }
+
+// ---------------------------------------------------------------------------
+// SP14: Payer-Rejected acknowledge
+//
+// Marks the listed claims as acknowledged by the operator. Acknowledged
+// claims drop out of the Payer-Rejected Inbox lane. The original 277CA
+// rejection event stays in the audit log (SP11) — we only flip a
+// working-surface flag.
+// ---------------------------------------------------------------------------
+export type AcknowledgeResult = {
+  ok: boolean;
+  transitioned: number;
+  already_acked: number;
+  not_found: number;
+  not_rejected: number;
+};
+
+export async function acknowledgePayerRejected(
+  claimIds: string[],
+  actor: string = "operator",
+): Promise<AcknowledgeResult> {
+  return postJson<AcknowledgeResult>(
+    "/api/inbox/payer-rejected/acknowledge",
+    { claim_ids: claimIds, actor },
+  );
+}

src/pages/Inbox.test.tsx

@@ -12,13 +12,17 @@ afterEach(() => {
 });
 
 describe("Inbox page", () => {
-  it("renders the four lane headers", async () => {
+  it("renders the five lane headers", async () => {
+    // SP14: the Payer-Rejected lane was added (277CA STC A4/A6/A7).
+    // The Inbox now renders 5 lanes: REJECTED, PAYER REJECTED,
+    // CANDIDATES, UNMATCHED, DONE.
     vi.stubGlobal(
       "fetch",
       vi.fn().mockResolvedValue({
         ok: true,
         json: async () => ({
           rejected: [],
+          payer_rejected: [],
           candidates: [],
           unmatched: [],
           done_today: [],
@@ -28,12 +32,117 @@ describe("Inbox page", () => {
     const { container } = render(<Inbox />);
     await waitFor(() => {
       expect(container.textContent).toContain("REJECTED");
+      expect(container.textContent).toContain("PAYER REJECTED");
       expect(container.textContent).toContain("CANDIDATES");
       expect(container.textContent).toContain("UNMATCHED");
       expect(container.textContent).toContain("DONE");
     });
   });
 
+  it("SP14: payer-rejected row count rolls up into the need-eyes header", async () => {
+    // The "need eyes" total in the header is the operator's
+    // anchor for the day. Payer-rejected claims are actionable
+    // (operator must acknowledge or follow up), so they count
+    // toward the need-eyes total alongside 999 rejected, candidates,
+    // and unmatched.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          rejected: [],
+          payer_rejected: [
+            { id: "PR1", kind: "claim", patient_control_number: "PR1",
+              charge_amount: 250, payer_id: "CO_TXIX", provider_npi: "1881068062",
+              state: "submitted", rejection_reason: "A7 invalid dx",
+              service_date_from: null, payer_rejected_status_code: "A7",
+              payer_rejected_reason: "invalid diagnosis",
+              payer_rejected_at: "2026-06-20T10:00:00Z" },
+          ],
+          candidates: [],
+          unmatched: [],
+          done_today: [],
+        }),
+      }),
+    );
+    const { container } = render(<Inbox />);
+    await waitFor(() => {
+      expect(container.textContent).toContain("1");
+      expect(container.textContent).toContain("items need eyes");
+    });
+  });
+
+  it("SP14: acknowledging selected payer-rejected claims calls the API and refetches", async () => {
+    // The user selects a payer-rejected claim, hits Acknowledge, and
+    // the inbox calls /api/inbox/payer-rejected/acknowledge with the
+    // claim id, then refetches the lane payload.
+    const fetchMock = vi.fn().mockImplementation(async (url: string) => {
+      if (url.includes("/api/inbox/lanes")) {
+        return {
+          ok: true,
+          json: async () => ({
+            rejected: [],
+            payer_rejected: [
+              { id: "PR1", kind: "claim", patient_control_number: "PR1",
+                charge_amount: 250, payer_id: "CO_TXIX", provider_npi: "1881068062",
+                state: "submitted", rejection_reason: "A7 invalid dx",
+                service_date_from: null, payer_rejected_status_code: "A7",
+                payer_rejected_reason: "invalid diagnosis",
+                payer_rejected_at: "2026-06-20T10:00:00Z" },
+            ],
+            candidates: [],
+            unmatched: [],
+            done_today: [],
+          }),
+        };
+      }
+      if (url.includes("/api/inbox/payer-rejected/acknowledge")) {
+        return {
+          ok: true,
+          json: async () => ({
+            ok: true,
+            transitioned: 1,
+            already_acked: 0,
+            not_found: 0,
+            not_rejected: 0,
+          }),
+        };
+      }
+      return { ok: true, json: async () => ({}) };
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { container, getByTestId } = render(<Inbox />);
+    await waitFor(() => {
+      expect(container.textContent).toContain("PR1");
+    });
+
+    // Select the PR1 claim via its checkbox.
+    const checkbox = container.querySelector(
+      'input[type="checkbox"][aria-label="Select PR1"]',
+    ) as HTMLInputElement;
+    expect(checkbox).toBeTruthy();
+    await act(async () => {
+      checkbox.click();
+    });
+
+    // Hit Acknowledge. The bulk action bar button is wired to the
+    // /api/inbox/payer-rejected/acknowledge endpoint.
+    const ackButton = getByTestId("payer-rejected-acknowledge");
+    await act(async () => {
+      ackButton.click();
+    });
+
+    // The mock was called with the acknowledge URL.
+    const ackCall = fetchMock.mock.calls.find(
+      (c) => typeof c[0] === "string" && c[0].includes("/api/inbox/payer-rejected/acknowledge"),
+    );
+    expect(ackCall).toBeTruthy();
+    expect(ackCall).toBeDefined();
+    const ackBody = JSON.parse(ackCall![1].body);
+    expect(ackBody.claim_ids).toEqual(["PR1"]);
+  });
+
   it("SP8: multi-select resubmit opens bundle modal; Resubmit + Download triggers api + downloadBlob", async () => {
     // Two rejected claims → user selects both → Re-submit → modal appears
     // → user clicks Resubmit + Download → backend is hit with
@@ -53,6 +162,7 @@ describe("Inbox page", () => {
                 state: "rejected", rejection_reason: "old", service_date: null,
                 score: null },
             ],
+            payer_rejected: [],
             candidates: [],
             unmatched: [],
             done_today: [],

src/pages/Inbox.tsx

@@ -1,9 +1,15 @@
 // ---------------------------------------------------------------------------
-// Inbox page (sub-project 6).
+// Inbox page (sub-project 6, SP14).
 //
-// Full-bleed dark working surface for the four-lane triage workflow.
+// Full-bleed dark working surface for the five-lane triage workflow.
 // Wires useInboxLanes + Lane + InboxHeader + BulkBar. Bulk actions call
 // the inbox API client and refetch on completion.
+//
+// SP14: added the `payer_rejected` lane (277CA STC A4/A6/A7) and the
+// Acknowledge bulk action. The Payer-Rejected lane sits between
+// `rejected` (envelope) and `candidates` (recon opportunities) so the
+// operator's eye flow is: envelope problems → payer problems →
+// auto-recon opportunities → claims still in flight → done today.
 // ---------------------------------------------------------------------------
 
 import { useState } from "react";
@@ -16,10 +22,16 @@ import {
   dismissCandidates,
   resubmitRejected,
   resubmitRejectedWithDownload,
+  acknowledgePayerRejected,
 } from "@/lib/inbox-api";
 import { downloadBlob } from "@/lib/download";
 
-type LaneKey = "rejected" | "candidates" | "unmatched" | "done_today";
+type LaneKey =
+  | "rejected"
+  | "payer_rejected"
+  | "candidates"
+  | "unmatched"
+  | "done_today";
 
 function rowKey(row: LaneRow): string {
   return row.kind === "remit" ? (row as { payer_claim_control_number: string }).payer_claim_control_number : row.id;
@@ -29,6 +41,7 @@ export default function Inbox() {
   const { lanes, loading, error, refetch } = useInboxLanes();
   const [selected, setSelected] = useState<Record<LaneKey, string[]>>({
     rejected: [],
+    payer_rejected: [],
     candidates: [],
     unmatched: [],
     done_today: [],
@@ -127,6 +140,18 @@ export default function Inbox() {
     }
   }
 
+  async function onAcknowledge() {
+    // SP14: drop selected payer-rejected claims from the working
+    // surface. The backend persists an `acknowledged_at` timestamp;
+    // the original 277CA rejection (status code, reason, source 277CA
+    // id) stays intact for the SP11 audit log.
+    const ids = selected.payer_rejected;
+    if (ids.length === 0) return;
+    await acknowledgePayerRejected(ids);
+    setSelected((prev) => ({ ...prev, payer_rejected: [] }));
+    await refetch();
+  }
+
   function onExport(lane: LaneKey) {
     if (selected[lane].length === 0) return;
     window.open(exportInboxCsvUrl(lane), "_blank");
@@ -162,8 +187,15 @@ export default function Inbox() {
     );
   }
 
+  // SP14: payer_rejected is also actionable — a 277CA rejection that
+  // needs operator follow-up. Without it, payer-side rejections would
+  // hide behind the 999 envelope "rejected" lane and the operator
+  // could miss a high-value denial.
   const needEyes =
-    lanes.rejected.length + lanes.candidates.length + lanes.unmatched.length;
+    lanes.rejected.length +
+    lanes.payer_rejected.length +
+    lanes.candidates.length +
+    lanes.unmatched.length;
 
   return (
     <div
@@ -179,6 +211,19 @@ export default function Inbox() {
           onRowClick={() => {}}
           onSelectionChange={(ids) => setLaneSelected("rejected", ids)}
         />
+        {/*
+          SP14: payer-rejected (277CA STC A4/A6/A7). Distinct accent
+          from the 999 envelope rejected lane — the operator's eye
+          flow is: 999 problems → payer problems → reconciliation
+          opportunities → claims still in flight → done today.
+        */}
+        <Lane
+          name="PAYER REJECTED"
+          accent="oxblood"
+          rows={lanes.payer_rejected}
+          onRowClick={() => {}}
+          onSelectionChange={(ids) => setLaneSelected("payer_rejected", ids)}
+        />
         <Lane
           name="CANDIDATES"
           accent="amber"
@@ -207,13 +252,23 @@ export default function Inbox() {
         lane="rejected"
         count={selected.rejected.length}
         onResubmit={onResubmit}
+        onAcknowledge={() => {}}
         onDismiss={() => {}}
         onExport={() => onExport("rejected")}
       />
+      <BulkBar
+        lane="payer_rejected"
+        count={selected.payer_rejected.length}
+        onResubmit={() => {}}
+        onAcknowledge={onAcknowledge}
+        onDismiss={() => {}}
+        onExport={() => onExport("payer_rejected")}
+      />
       <BulkBar
         lane="candidates"
         count={selected.candidates.length}
         onResubmit={() => {}}
+        onAcknowledge={() => {}}
         onDismiss={onDismiss}
         onExport={() => onExport("candidates")}
       />
@@ -221,6 +276,7 @@ export default function Inbox() {
         lane="unmatched"
         count={selected.unmatched.length}
         onResubmit={() => {}}
+        onAcknowledge={() => {}}
         onDismiss={() => {}}
         onExport={() => onExport("unmatched")}
       />
@@ -228,6 +284,7 @@ export default function Inbox() {
         lane="done_today"
         count={selected.done_today.length}
         onResubmit={() => {}}
+        onAcknowledge={() => {}}
         onDismiss={() => {}}
         onExport={() => onExport("done_today")}
       />