arq/fsm: IRS mirrors the ISS delivery-driven ladder

The IRS payload decoder tracked peer_tx_mode = the last-DECODED mode
(arq_modem_preferred_rx_mode() is hardcoded to DATAC16, so
select_payload_rx_mode's first branch is dead). When the ISS climbed the
ladder (e.g. MFSK->DATAC15) the IRS's dual decoder had no slot for the new
mode, missed the first burst of every climb, never ACKed it, and the ISS
retried and fell back -- the transfer oscillated at the MFSK floor and
crawled.

The IRS observes the same per-frame outcomes the sender climbs on, so it
now mirrors the same delivery-driven ladder: a clean new frame climbs, a
duplicate (sender retried and stepped down) steps down, and a full
IDLE_IRS idle-hold with no RX steps down toward the floor (reset-on-miss,
so a lost ACK that left us climbed above the sender re-rendezvous at the
floor). Keeps the payload decoder on the mode the peer's NEXT burst will
use, with no on-wire mode negotiation. ladder_step() is factored out of
record_tx_outcome so both ends apply identical rules.

Tests: test_irs_mirror_climbs_with_peer / _steps_down_on_duplicate /
_resets_toward_floor_on_silence.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: rafael2k

datalink_arq/arq_fsm.c

@@ -115,6 +115,9 @@ void arq_fsm_init(arq_session_t *sess)
     sess->speed_level    = 0;
     sess->tx_success_count = 0;
     sess->fast_ramp      = true;
+    sess->rx_speed_level = 0;
+    sess->rx_success_count = 0;
+    sess->rx_fast_ramp   = true;
 }
 
 int arq_fsm_timeout_ms(const arq_session_t *sess, uint64_t now)
@@ -151,6 +154,9 @@ static void reset_session_data_state(arq_session_t *sess)
     sess->speed_level        = 0;
     sess->tx_success_count   = 0;
     sess->fast_ramp          = true;
+    sess->rx_speed_level     = 0;
+    sess->rx_success_count   = 0;
+    sess->rx_fast_ramp       = true;
     sess->payload_mode       = arq_mode_ladder[0];   /* MFSK floor */
     sess->peer_tx_mode       = arq_mode_ladder[0];
     sess->pending_disconnect = false;
@@ -196,6 +202,9 @@ static void sess_enter(arq_session_t *sess, arq_conn_state_t new_state,
     {
         sess->dflow_state      = ARQ_DFLOW_IDLE_ISS;
         sess->peer_tx_mode     = sess->initial_payload_mode;
+        sess->rx_speed_level   = 0;   /* mirror back to the floor for a fresh session */
+        sess->rx_success_count = 0;
+        sess->rx_fast_ramp     = true;
         sess->tx_frame_present = false;
         sess->tx_frame_len     = 0;
         sess->tx_frame_retx    = false;
@@ -285,46 +294,72 @@ static void apply_speed_level(arq_session_t *sess)
         clamp_payload_mode_to_bandwidth(arq_mode_ladder[sess->speed_level]);
 }
 
-/** Record the outcome of the retained TX frame once its fate is known.
- *  Delivery-driven, no SNR/OLLA/reverse-hold: clean == the frame was delivered
- *  with no retransmission; else it needed at least one retry.  Any retry steps
- *  the ladder DOWN one rung immediately (toward MFSK) for reliability.  A run
- *  of clean deliveries steps it UP: the initial fast ramp climbs one rung per
- *  clean delivery until the first retry, after which it settles to
- *  ARQ_LADDER_UP_SUCCESSES clean deliveries per step. */
-static void record_tx_outcome(arq_session_t *sess, bool clean)
+/** Apply one delivery-driven ladder step to a (level, success_count, fast_ramp)
+ *  triple.  Shared by the ISS (TX outcomes) and the IRS mode mirror (RX
+ *  outcomes) so both ends climb/drop by exactly the same rule and stay locked
+ *  in step without any on-wire mode negotiation.
+ *
+ *  clean == the frame was delivered/received first try: a run of clean outcomes
+ *  climbs — the fast initial ramp climbs one rung per clean outcome until the
+ *  first miss, after which it settles to ARQ_LADDER_UP_SUCCESSES clean outcomes
+ *  per step.  A miss/retry steps DOWN one rung immediately (toward the MFSK
+ *  floor) and ends the fast ramp, so a deep fade parks at the floor with no
+ *  over-climb oscillation.  Returns the signed level change (for logging). */
+static int ladder_step(int *level, int *success_count, bool *fast_ramp, bool clean)
 {
+    int before = *level;
     if (!clean)
     {
-        sess->fast_ramp = false;   /* first retry ends the fast initial ramp */
-        if (sess->speed_level > 0)
+        *fast_ramp = false;
+        if (*level > 0)
+            (*level)--;
+        *success_count = 0;
+    }
+    else
+    {
+        (*success_count)++;
+        int need = *fast_ramp ? 1 : ARQ_LADDER_UP_SUCCESSES;
+        if (*success_count >= need && *level < ARQ_LADDER_LEVELS - 1)
         {
-            sess->speed_level--;
-            HLOGD(LOG_COMP, "Ladder step-down to %d (retry)", sess->speed_level);
+            (*level)++;
+            *success_count = 0;
         }
-        sess->tx_success_count = 0;
-        apply_speed_level(sess);
-        return;
     }
+    return *level - before;
+}
 
-    sess->tx_success_count++;
-    /* Step-up cadence (the single tuning knob, confirmed at OTA): the fast
-     * initial ramp climbs one rung per clean delivery until the first retry,
-     * after which it settles to ARQ_LADDER_UP_SUCCESSES clean deliveries per
-     * step.  A retry always steps down one rung, so a deep fade parks at the
-     * MFSK floor (no over-climb oscillation) while a clean link ramps quickly. */
-    int need = sess->fast_ramp ? 1 : ARQ_LADDER_UP_SUCCESSES;
-    if (sess->tx_success_count >= need &&
-        sess->speed_level < ARQ_LADDER_LEVELS - 1)
-    {
-        sess->speed_level++;
-        sess->tx_success_count = 0;
-        HLOGD(LOG_COMP, "Ladder step-up to %d (%d clean%s)",
-              sess->speed_level, need, sess->fast_ramp ? ", fast ramp" : "");
-    }
+/** Record the outcome of the retained TX frame once its fate is known.
+ *  Delivery-driven, no SNR/OLLA/reverse-hold: clean == the frame was delivered
+ *  with no retransmission; else it needed at least one retry. */
+static void record_tx_outcome(arq_session_t *sess, bool clean)
+{
+    int delta = ladder_step(&sess->speed_level, &sess->tx_success_count,
+                            &sess->fast_ramp, clean);
+    if (delta < 0)
+        HLOGD(LOG_COMP, "Ladder step-down to %d (retry)", sess->speed_level);
+    else if (delta > 0)
+        HLOGD(LOG_COMP, "Ladder step-up to %d", sess->speed_level);
     apply_speed_level(sess);
 }
 
+/** IRS: mirror the peer's (ISS) ladder from the outcome of a received DATA
+ *  frame so our payload decoder is already on the mode the peer's NEXT burst
+ *  will use.  clean_new == a new in-order frame decoded first try (mirrors the
+ *  sender's clean delivery); a duplicate (our ACK was lost, the sender retried
+ *  and stepped down) mirrors the sender's step-down.  Keeps peer_tx_mode ==
+ *  arq_mode_ladder[rx_speed_level]. */
+static void irs_mirror_peer_ladder(arq_session_t *sess, bool clean_new)
+{
+    int delta = ladder_step(&sess->rx_speed_level, &sess->rx_success_count,
+                            &sess->rx_fast_ramp, clean_new);
+    sess->peer_tx_mode =
+        clamp_payload_mode_to_bandwidth(arq_mode_ladder[sess->rx_speed_level]);
+    if (delta != 0)
+        HLOGD(LOG_COMP, "IRS RX-mode mirror %s to level %d (mode=%d)",
+              delta > 0 ? "climb" : "step-down",
+              sess->rx_speed_level, sess->peer_tx_mode);
+}
+
 /* IRS: arm the ACK deadline after a received DATA frame.  Stop-and-wait: one
  * frame per burst, so we always wait the channel guard before emitting the
  * pattern ACK (lets the ISS relay switch TX->RX before our tones arrive). */
@@ -1000,8 +1035,12 @@ static void fsm_connected(arq_session_t *sess, const arq_event_t *ev)
 static void irs_receive_data(arq_session_t *sess, const arq_event_t *ev)
 {
     update_local_snr(sess, ev);
-    sess->peer_tx_mode = ev->mode;
     bool new_frame = deliver_rx_checked(sess, ev);
+    /* Follow the sender's delivery-driven ladder: a new in-order frame is a
+     * clean delivery on its side (climb); a duplicate means it retried and
+     * stepped down.  This sets peer_tx_mode to the mode of the peer's NEXT
+     * burst so the payload decoder is already there when it arrives. */
+    irs_mirror_peer_ladder(sess, new_frame);
     if (new_frame && g_timing)
         arq_timing_record_data_rx(g_timing, (int)ev->seq,
                                   (int)ev->data_bytes, sess->local_snr_x10);
@@ -1209,7 +1248,6 @@ static void fsm_dflow(arq_session_t *sess, const arq_event_t *ev)
         else if (ev->id == ARQ_EV_RX_DATA)
         {
             update_local_snr(sess, ev);
-            sess->peer_tx_mode = ev->mode;
             sess->last_rx_ms = time_now_ms();
 
             if (ev->seq == sess->rx_expected)
@@ -1239,6 +1277,7 @@ static void fsm_dflow(arq_session_t *sess, const arq_event_t *ev)
                       "RX_DATA in WAIT_ACK (dup seq=%d expected=%d) — re-TX our seq=%d",
                       (int)ev->seq, (int)sess->rx_expected, (int)sess->tx_frame_seq);
                 deliver_rx_checked(sess, ev);   /* logs dup; no delivery */
+                irs_mirror_peer_ladder(sess, false);  /* peer retried → mirror step-down */
                 sess->tx_frame_retx = true;
                 dflow_enter(sess, ARQ_DFLOW_DATA_TX, UINT64_MAX, ARQ_EV_TIMER_RETRY);
                 send_data_burst(sess);
@@ -1323,6 +1362,16 @@ static void fsm_dflow(arq_session_t *sess, const arq_event_t *ev)
             }
             else
             {
+                /* Reset-on-miss: a full idle hold passed with no DATA.  If a
+                 * lost ACK left our RX-mode mirror climbed ABOVE the sender
+                 * (which stepped down on its retry), we can no longer decode
+                 * its bursts — silently stalling.  Step the mirror down one
+                 * rung toward the floor so the two ends re-rendezvous; the
+                 * MFSK floor is the guaranteed common ground.  At faster modes
+                 * frames arrive well within the hold, so this only fires on a
+                 * genuine stall (at the floor a step-down is a harmless no-op). */
+                if (sess->rx_speed_level > 0)
+                    irs_mirror_peer_ladder(sess, false);
                 enter_idle_irs(sess);   /* re-arm the idle hold */
             }
         }

datalink_arq/arq_fsm.h

@@ -175,9 +175,22 @@ typedef struct
     bool     fast_ramp;                /* faster initial climb: 1 rung per clean
                                         * delivery until the first retry, then
                                         * ARQ_LADDER_UP_SUCCESSES-per-step       */
-    int      peer_tx_mode;             /* mode peer last TX'd in = my payload
-                                        * RX decoder mode when IRS; updated
-                                        * from ev->mode on every DATA frame    */
+    int      peer_tx_mode;             /* my payload RX decoder mode when IRS =
+                                        * arq_mode_ladder[rx_speed_level]; the
+                                        * mode the peer's NEXT DATA burst uses  */
+
+    /* --- IRS-side mirror of the peer's (ISS) delivery-driven ladder --------
+     * The IRS observes the same per-frame outcomes the sender climbs on (a
+     * clean new frame == a clean delivery; a duplicate == a sender retry), so
+     * applying the identical ladder rule keeps rx_speed_level == the sender's
+     * speed_level with no on-wire mode negotiation.  Without it the decoder can
+     * only ever track a mode it has ALREADY decoded, so it misses the first
+     * burst of every mode the sender climbs to (stalling the transfer at the
+     * MFSK floor).  A prolonged RX gap (a lost ACK left us above the sender)
+     * steps this back down toward the floor so the two ends re-rendezvous. */
+    int      rx_speed_level;           /* mirror of the peer's ladder index    */
+    int      rx_success_count;         /* clean receives toward a mirror step-up*/
+    bool     rx_fast_ramp;             /* mirror of the peer's fast initial ramp*/
 
     /* --- Retry/timeout bookkeeping --- */
     int      tx_retries_left;          /* retries remaining for current frame  */

tests/datalink_arq/test_arq_fsm.c

@@ -664,6 +664,113 @@ void test_timeout_ms_idle(void)
     TEST_ASSERT_GREATER_THAN(60000, ms);
 }
 
+/* ---- IRS payload-mode mirror: follow the peer's delivery-driven ladder ----
+ *
+ * The IRS's payload decoder must be on the mode the peer's NEXT burst will use,
+ * NOT the last one it decoded — otherwise it misses the first burst of every
+ * mode the sender climbs to and the transfer stalls at the MFSK floor (the
+ * -x sock regression).  Since the IRS observes the same per-frame outcomes the
+ * sender climbs on, it mirrors the same ladder. */
+
+/* LISTENING -> ACCEPTING -> CONNECTED as the answerer: IRS role, IDLE_IRS. */
+static void goto_connected_irs(void)
+{
+    enter_accepting();
+    arq_event_t ev = make_event(ARQ_EV_RX_ACK);
+    ev.session_id = 0x42;
+    arq_fsm_dispatch(&sess, &ev);
+    TEST_ASSERT_EQUAL_INT(ARQ_CONN_CONNECTED, sess.conn_state);
+    TEST_ASSERT_EQUAL_INT(ARQ_DFLOW_IDLE_IRS, sess.dflow_state);
+}
+
+/* In-order DATA frame carrying `n` payload bytes.  HAS_DATA keeps us the IRS
+ * across frames (the sender has more to send).  mode is set to what the peer
+ * actually sent, but the mirror deliberately ignores it (anticipation, not
+ * follow-the-decoded-mode). */
+static arq_event_t make_data_event(uint8_t seq, int mode, size_t n)
+{
+    arq_event_t ev = make_event(ARQ_EV_RX_DATA);
+    ev.session_id  = 0x42;
+    ev.seq         = seq;
+    ev.mode        = mode;
+    ev.rx_flags    = ARQ_FLAG_HAS_DATA;
+    ev.data_bytes  = n;
+    ev.payload_len = n;
+    for (size_t i = 0; i < n && i < sizeof(ev.payload); i++)
+        ev.payload[i] = (uint8_t)(seq * 17 + i);
+    return ev;
+}
+
+/* Run the ACK_TX cycle (guard timer -> pattern ACK -> TX complete) back to
+ * IDLE_IRS, so the next DATA frame is received in the same state a real IRS is. */
+static void complete_ack_tx(void)
+{
+    arq_event_t ev = make_event(ARQ_EV_TIMER_ACK);
+    arq_fsm_dispatch(&sess, &ev);
+    ev = make_event(ARQ_EV_TX_COMPLETE);
+    arq_fsm_dispatch(&sess, &ev);
+    TEST_ASSERT_EQUAL_INT(ARQ_DFLOW_IDLE_IRS, sess.dflow_state);
+}
+
+/* Each clean in-order frame climbs the sender one rung (fast initial ramp);
+ * the IRS mirror climbs in lock step so peer_tx_mode names the NEXT burst's
+ * mode before it arrives. */
+void test_irs_mirror_climbs_with_peer(void)
+{
+    goto_connected_irs();
+    TEST_ASSERT_EQUAL_INT(MERCURY_MODE_MFSK, sess.peer_tx_mode);
+
+    arq_event_t ev = make_data_event(0, MERCURY_MODE_MFSK, 90);
+    arq_fsm_dispatch(&sess, &ev);
+    TEST_ASSERT_EQUAL_INT(FREEDV_MODE_DATAC15, sess.peer_tx_mode);   /* level 1 */
+    complete_ack_tx();
+
+    ev = make_data_event(1, FREEDV_MODE_DATAC15, 30);
+    arq_fsm_dispatch(&sess, &ev);
+    TEST_ASSERT_EQUAL_INT(FREEDV_MODE_DATAC4, sess.peer_tx_mode);    /* level 2 */
+    complete_ack_tx();
+
+    ev = make_data_event(2, FREEDV_MODE_DATAC4, 54);
+    arq_fsm_dispatch(&sess, &ev);
+    TEST_ASSERT_EQUAL_INT(FREEDV_MODE_DATAC3, sess.peer_tx_mode);    /* level 3 */
+}
+
+/* A duplicate frame means our ACK was lost and the sender retried, stepping ITS
+ * ladder down — the mirror must step down too so we can decode the retransmit. */
+void test_irs_mirror_steps_down_on_duplicate(void)
+{
+    goto_connected_irs();
+    arq_event_t ev = make_data_event(0, MERCURY_MODE_MFSK, 90);
+    arq_fsm_dispatch(&sess, &ev);
+    complete_ack_tx();
+    ev = make_data_event(1, FREEDV_MODE_DATAC15, 30);
+    arq_fsm_dispatch(&sess, &ev);
+    complete_ack_tx();
+    TEST_ASSERT_EQUAL_INT(FREEDV_MODE_DATAC4, sess.peer_tx_mode);    /* climbed to level 2 */
+
+    /* Duplicate of an already-delivered seq (rx_expected has advanced past it). */
+    ev = make_data_event(0, MERCURY_MODE_MFSK, 90);
+    arq_fsm_dispatch(&sess, &ev);
+    TEST_ASSERT_EQUAL_INT(FREEDV_MODE_DATAC15, sess.peer_tx_mode);   /* stepped down to level 1 */
+}
+
+/* Reset-on-miss: a full idle hold with no DATA (a lost ACK left us climbed above
+ * the sender) steps the mirror down toward the floor so the two ends re-sync. */
+void test_irs_mirror_resets_toward_floor_on_silence(void)
+{
+    goto_connected_irs();
+    arq_event_t ev = make_data_event(0, MERCURY_MODE_MFSK, 90);
+    arq_fsm_dispatch(&sess, &ev);
+    complete_ack_tx();
+    TEST_ASSERT_EQUAL_INT(FREEDV_MODE_DATAC15, sess.peer_tx_mode);   /* climbed to level 1 */
+
+    /* Idle-hold fires with no reverse backlog and a recent RX (not dead yet). */
+    fake_tx_backlog_fake.return_val = 0;
+    ev = make_event(ARQ_EV_TIMER_PEER_BACKLOG);
+    arq_fsm_dispatch(&sess, &ev);
+    TEST_ASSERT_EQUAL_INT(MERCURY_MODE_MFSK, sess.peer_tx_mode);     /* stepped back to the floor */
+}
+
 int main(void)
 {
     UNITY_BEGIN();
@@ -695,5 +802,8 @@ int main(void)
     RUN_TEST(test_default_call_accept_slots_are_short);
     RUN_TEST(test_stop_listen);
     RUN_TEST(test_timeout_ms_idle);
+    RUN_TEST(test_irs_mirror_climbs_with_peer);
+    RUN_TEST(test_irs_mirror_steps_down_on_duplicate);
+    RUN_TEST(test_irs_mirror_resets_toward_floor_on_silence);
     return UNITY_END();
 }