pycfdp 0.2.2__py3-none-any.whl

cfdp/pure/machines/receiver2.py

@@ -0,0 +1,893 @@
+"""Pure Class-2 (acknowledged) receiver machine (issue #19).
+
+A pure function of ``(state, event)`` returning an ordered ``list[Output]``. It
+obeys the machine contract:
+
+    Receiver2(transaction, config, query_port)
+    update_state(event) -> list[Output]
+
+No ``kernel`` reference, no threads, no open file descriptors, no wall clock.
+
+The Class-2 receiver is the most complex machine. On top of the Class-1 receiver
+it adds:
+
+* **NAK-driven recovery** — it computes a NAK list from its own received-segment
+  map (:meth:`_update_nak_list`) and sends NAKs (:class:`SendPdu`) while any gap
+  remains; a missing metadata is requested via the ``(0, 0)`` segment request;
+* a **NAK timer** (design D6) driving retransmission, with the expiration-limit
+  counter held in machine state and bumped on each ``E26_NAK_TIMEOUT`` via
+  :meth:`note_nak_timeout` (mirroring the real ``Timer._expired`` counter bump);
+* an **ACK timer** guarding the Finished/ACK-Finished handshake, whose limit
+  counter is likewise machine state, bumped via :meth:`note_ack_timeout`;
+* the **inactivity timer**, restarted on every inbound PDU (5.3.7);
+* **checksum verification** of the received temp file, computed asynchronously
+  (issue #21): the machine emits ``RequestChecksum`` and finishes in the
+  ``E42_CHECKSUM_READY`` continuation so a large-file checksum never blocks the
+  dispatcher;
+* the ``ACK(EOF)`` / ``Finished`` / ``ACK(Finished)`` handshake and cancellation
+  via a ``TRANSACTION_CANCELLED`` state.
+
+Reply PDUs (NAK, ACK, Finished) reuse the sender's first PDU header with the
+direction reversed (CCSDS 5.6.1 l). Rather than mutate the inbound PDU's header
+in place, this machine *copies* the relevant header fields once
+(:meth:`_reuse_senders_first_pdu_header`) and rebuilds each reply PDU from them,
+producing byte-identical output without mutating the inbound PDU (purity).
+
+The triggering inbound PDU rides on the single input door as ``event.pdu`` (see
+:class:`cfdp.event.Event`), matching the other receiver machines.
+
+Verified by differential trace testing against frozen golden fixtures captured
+from the pre-cutover implementation — see ``tests/test_pure_receiver2.py``. In
+particular the pre-cutover machine closed the received file **twice** on the
+happy path (``close_tempfile`` in SEND_FINISHED then ``shutdown``); this machine
+reproduces both :class:`CloseFile` outputs on purpose (the second close is a
+no-op).
+"""
+
+from cfdp.constants import (
+    ConditionCode,
+    DeliveryCode,
+    Direction,
+    DirectiveCode,
+    DirectiveSubTypeCode,
+    FaultHandlerAction,
+    FileStatus,
+    MachineState,
+    TransactionStatus,
+    TransmissionMode,
+)
+from cfdp.event import Event, EventType
+from cfdp.pdu import AckPdu, FinishedPdu, NakPdu
+
+from .. import indications
+from ..config import TransactionConfig
+from ..outputs import (
+    CancelTimer,
+    CloseFile,
+    ExecuteFilestoreRequests,
+    Finalize,
+    InternalEvent,
+    OpenTemp,
+    Output,
+    PostUserMessage,
+    RequestChecksum,
+    SendPdu,
+    StartTimer,
+    TimerKind,
+    WriteSegment,
+)
+from ..query_port import QueryPort
+from ..transaction import Transaction
+
+
+class Receiver2:
+    """Pure implementation of the Class 2 (acknowledged transfer) receiver."""
+
+    def __init__(
+        self,
+        transaction: Transaction,
+        config: TransactionConfig,
+        query_port: QueryPort,
+    ) -> None:
+        self.transaction = transaction
+        self.config = config
+        self.query_port = query_port
+
+        self.transmission_mode = TransmissionMode.ACKNOWLEDGED
+        self.state = MachineState.WAIT_FOR_EOF
+        self.file_size = None
+
+        # Request payload received off the inbound Metadata PDU (design D3). The
+        # old machine stashes these on the mutable Transaction; here they are
+        # machine state.
+        self.filestore_requests = None
+        self.messages_to_user = None
+        self.source_filename = transaction.source_filename
+        self.destination_filename = transaction.destination_filename
+        self.checksum_type = transaction.checksum_type
+
+        # Captured first-PDU header fields (design: reuse sender's header,
+        # direction reversed). None until the first inbound PDU is seen.
+        self._first_header = None
+
+        # Timer bookkeeping (design D6): the ACK timer's suspend flag and both
+        # expiration-limit counters are protocol state on the machine.
+        self._ack_timer_suspended = False
+        self._ack_expiration_counter = 0
+        self._nak_expiration_counter = 0
+
+        self._initialize()
+
+    # -- state reset (mirrors Machine.initialize) -------------------------- #
+
+    def _initialize(self):
+        # as per CCSDS 720.2-G-3, Page 5-13, g)
+        self.condition_code = ConditionCode.NO_ERROR
+        self.delivery_code = DeliveryCode.DATA_INCOMPLETE
+        self.frozen = False
+        self.metadata_received = False
+        self.pdu_received = False
+        self.suspended = False
+        self.file_status = FileStatus.UNREPORTED
+        self.filestore_responses = None
+        self.status_report = None
+
+        self.received_file_size = 0
+        # Whether a temp file handle is open (formerly transaction.file_handle
+        # truthiness). shutdown() emits CloseFile only if one was opened.
+        self._file_open = False
+        self.received_file_segments = {}
+        self.nak_list = []
+        self._progress = 0
+        self.received_file_checksum = None
+
+    # -- the single input door --------------------------------------------- #
+
+    def update_state(self, event: Event) -> list[Output]:
+        """See state table given in CCSDS 720.2-G-3, Table 5-4.
+
+        Returns the ordered list of :class:`~cfdp.pure.outputs.Output` produced
+        by handling ``event``. The triggering inbound PDU, if any, is read from
+        ``event.pdu``.
+        """
+        self._out: list[Output] = []
+        pdu = getattr(event, "pdu", None)
+
+        # as per CCSDS 720.2-G-3, 5.3.7: any inbound PDU restarts inactivity.
+        if pdu is not None:
+            self._restart_inactivity_timer()
+
+        if self.state == MachineState.WAIT_FOR_EOF:
+            self._update_wait_for_eof(event, pdu)
+        elif self.state == MachineState.GET_MISSING_DATA:
+            self._update_get_missing_data(event, pdu)
+        elif self.state == MachineState.SEND_FINISHED:
+            self._update_send_finished(event, pdu)
+        elif self.state == MachineState.TRANSACTION_CANCELLED:
+            self._update_transaction_cancelled(event, pdu)
+
+        out, self._out = self._out, []
+        return out
+
+    # -- WAIT_FOR_EOF state ------------------------------------------------ #
+
+    def _update_wait_for_eof(self, event, pdu):
+        if event.type == EventType.E0_ENTERED_STATE:
+            self._initialize()
+            self._restart_inactivity_timer()
+
+        elif event.type == EventType.E2_ABANDON_TRANSACTION:
+            self._issue_abandoned_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E3_NOTICE_OF_CANCELLATION:
+            self.state = MachineState.TRANSACTION_CANCELLED
+            self._emit(InternalEvent(EventType.E0_ENTERED_STATE))
+
+        elif event.type == EventType.E4_NOTICE_OF_SUSPENSION:
+            self._notice_of_suspension()
+
+        elif event.type == EventType.E5_SUSPEND_TIMERS:
+            self._suspend_inactivity_timer()
+
+        elif event.type == EventType.E6_RESUME_TIMERS:
+            self._resume_inactivity_timer()
+
+        elif event.type == EventType.E10_RECEIVED_METADATA:
+            self._reuse_senders_first_pdu_header(pdu)
+            if not self.metadata_received:
+                self._absorb_metadata(pdu)
+
+        elif event.type == EventType.E11_RECEIVED_FILEDATA:
+            self._issue_filesegment_received_indication(
+                pdu.segment_offset, len(pdu.file_data)
+            )
+            self._reuse_senders_first_pdu_header(pdu)
+            if not self._file_open:
+                self._open_tempfile()
+            self._store_file_data(pdu)
+            self._update_received_file_size(pdu)
+            # NAK list is recomputed lazily at send points (issue #32), not on
+            # every stored segment.
+
+        elif event.type == EventType.E12_RECEIVED_EOF_NO_ERROR:
+            self._reuse_senders_first_pdu_header(pdu)
+            # Persist the authoritative EOF file size so later NAK recomputes
+            # (GET_MISSING_DATA entry / NAK timeout) use it even when Metadata
+            # never arrived (issue #32).
+            self.file_size = pdu.file_size
+            self._update_nak_list(self.file_size)
+            self._send_ack_eof()
+
+            if self._is_file_size_error(pdu.file_size):
+                # Honor the configured fault handler: CANCEL/SUSPEND/ABANDON emit
+                # an internal event that sets its own state, so we must NOT fall
+                # through and overwrite it (issue #25). IGNORE returns True.
+                if not self._fault_file_size():
+                    return
+
+            self.received_file_checksum = pdu.file_checksum
+
+            if self._is_nak_list_empty():
+                self.state = MachineState.SEND_FINISHED
+            else:
+                self.state = MachineState.GET_MISSING_DATA
+            self._emit(InternalEvent(EventType.E0_ENTERED_STATE))
+
+        elif event.type == EventType.E13_RECEIVED_EOF_CANCEL:
+            self._reuse_senders_first_pdu_header(pdu)
+            self.condition_code = pdu.condition_code
+            if pdu.fault_location is not None:
+                self.status_report = {"fault_location": pdu.fault_location}
+            self._send_ack_eof()
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E27_INACTIVITY_TIMEOUT:
+            self._fault_inactivity()
+
+        elif event.type == EventType.E31_RECEIVED_SUSPEND_REQUEST:
+            self._emit(InternalEvent(EventType.E4_NOTICE_OF_SUSPENSION))
+
+        elif event.type == EventType.E32_RECEIVED_RESUME_REQUEST:
+            self._resume_request()
+
+        elif event.type == EventType.E33_RECEIVED_CANCEL_REQUEST:
+            self.condition_code = ConditionCode.CANCEL_REQUEST_RECEIVED
+            self._emit(InternalEvent(EventType.E3_NOTICE_OF_CANCELLATION))
+
+        elif event.type == EventType.E34_RECEIVED_REPORT_REQUEST:
+            self._issue_report_indication()
+
+        elif event.type == EventType.E40_RECEIVED_FREEZE:
+            self._freeze()
+
+        elif event.type == EventType.E41_RECEIVED_THAW:
+            self._thaw()
+
+    # -- GET_MISSING_DATA state -------------------------------------------- #
+
+    def _update_get_missing_data(self, event, pdu):
+        if event.type == EventType.E0_ENTERED_STATE:
+            if not self.suspended and not self.frozen:
+                self._update_nak_list(self.file_size)
+                self._send_nak()
+            self._restart_nak_timer()
+
+        elif event.type == EventType.E2_ABANDON_TRANSACTION:
+            self._issue_abandoned_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E3_NOTICE_OF_CANCELLATION:
+            self.state = MachineState.TRANSACTION_CANCELLED
+            self._emit(InternalEvent(EventType.E0_ENTERED_STATE))
+
+        elif event.type == EventType.E4_NOTICE_OF_SUSPENSION:
+            self._notice_of_suspension()
+
+        elif event.type == EventType.E5_SUSPEND_TIMERS:
+            self._suspend_inactivity_timer()
+
+        elif event.type == EventType.E6_RESUME_TIMERS:
+            self._restart_inactivity_timer()
+
+        elif event.type == EventType.E10_RECEIVED_METADATA:
+            if not self.metadata_received:
+                self._absorb_metadata(pdu)
+
+        elif event.type == EventType.E11_RECEIVED_FILEDATA:
+            if not self._file_open:
+                self._open_tempfile()
+            self._store_file_data(pdu)
+            self._update_received_file_size(pdu)
+            # NAK list is recomputed lazily at send points (issue #32).
+            self._restart_nak_timer()
+
+        elif event.type == EventType.E12_RECEIVED_EOF_NO_ERROR:
+            self._send_ack_eof()
+
+        elif event.type == EventType.E13_RECEIVED_EOF_CANCEL:
+            self.condition_code = pdu.condition_code
+            if pdu.fault_location is not None:
+                self.status_report = {"fault_location": pdu.fault_location}
+            self._send_ack_eof()
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E26_NAK_TIMEOUT:
+            self._restart_nak_timer()
+            self._update_nak_list(self.file_size)
+            if self._is_nak_list_empty():
+                self.state = MachineState.SEND_FINISHED
+                self._emit(InternalEvent(EventType.E0_ENTERED_STATE))
+            elif not self.suspended and not self.frozen:
+                if self._is_nak_limit_reached():
+                    if not self._fault_nak_limit():
+                        return
+                self._send_nak()
+
+        elif event.type == EventType.E27_INACTIVITY_TIMEOUT:
+            self._fault_inactivity()
+
+        elif event.type == EventType.E31_RECEIVED_SUSPEND_REQUEST:
+            self._emit(InternalEvent(EventType.E4_NOTICE_OF_SUSPENSION))
+
+        elif event.type == EventType.E32_RECEIVED_RESUME_REQUEST:
+            self._resume_request()
+
+        elif event.type == EventType.E33_RECEIVED_CANCEL_REQUEST:
+            self.condition_code = ConditionCode.CANCEL_REQUEST_RECEIVED
+            self._emit(InternalEvent(EventType.E3_NOTICE_OF_CANCELLATION))
+
+        elif event.type == EventType.E34_RECEIVED_REPORT_REQUEST:
+            self._issue_report_indication()
+
+        elif event.type == EventType.E40_RECEIVED_FREEZE:
+            self._freeze()
+
+        elif event.type == EventType.E41_RECEIVED_THAW:
+            self._thaw()
+
+    # -- SEND_FINISHED state ----------------------------------------------- #
+
+    def _update_send_finished(self, event, pdu):
+        if event.type == EventType.E0_ENTERED_STATE:
+            self.delivery_code = DeliveryCode.DATA_COMPLETE
+            self._cancel_nak_timer()
+
+            if self._is_file_transfer():
+                # Checksum verification is async (issue #21): compute the temp
+                # file's checksum off the event thread and finish in the E42
+                # continuation below.
+                self._emit(
+                    RequestChecksum(
+                        checksum_type=self.checksum_type, from_temp_handle=True
+                    )
+                )
+                return
+
+            if self.filestore_requests:
+                self._execute_filestore_requests()
+
+            self._send_finished()
+            self._restart_ack_timer()
+
+        elif event.type == EventType.E42_CHECKSUM_READY:
+            self._finish_after_checksum(event.checksum)
+
+        elif event.type == EventType.E2_ABANDON_TRANSACTION:
+            self._issue_abandoned_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E3_NOTICE_OF_CANCELLATION:
+            self.state = MachineState.TRANSACTION_CANCELLED
+            self._emit(InternalEvent(EventType.E0_ENTERED_STATE))
+
+        elif event.type == EventType.E4_NOTICE_OF_SUSPENSION:
+            self._notice_of_suspension()
+
+        elif event.type == EventType.E5_SUSPEND_TIMERS:
+            self._suspend_inactivity_timer()
+            self._suspend_ack_timer()
+
+        elif event.type == EventType.E6_RESUME_TIMERS:
+            self._restart_inactivity_timer()
+            self._resume_ack_timer()
+
+        elif event.type == EventType.E12_RECEIVED_EOF_NO_ERROR:
+            self._send_ack_eof()
+
+        elif event.type == EventType.E13_RECEIVED_EOF_CANCEL:
+            self.condition_code = pdu.condition_code
+            if pdu.fault_location is not None:
+                self.status_report = {"fault_location": pdu.fault_location}
+            self._send_ack_eof()
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E18_RECEIVED_ACK_FINISHED:
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E25_ACK_TIMEOUT:
+            self._restart_ack_timer()
+            if self._is_ack_limit_reached():
+                self._fault_ack_limit()
+            self._send_finished()
+
+        elif event.type == EventType.E27_INACTIVITY_TIMEOUT:
+            self._fault_inactivity()
+
+        elif event.type == EventType.E31_RECEIVED_SUSPEND_REQUEST:
+            self._emit(InternalEvent(EventType.E4_NOTICE_OF_SUSPENSION))
+
+        elif event.type == EventType.E32_RECEIVED_RESUME_REQUEST:
+            self._resume_request()
+
+        elif event.type == EventType.E33_RECEIVED_CANCEL_REQUEST:
+            self.condition_code = ConditionCode.CANCEL_REQUEST_RECEIVED
+            self._emit(InternalEvent(EventType.E3_NOTICE_OF_CANCELLATION))
+
+        elif event.type == EventType.E34_RECEIVED_REPORT_REQUEST:
+            self._issue_report_indication()
+
+        elif event.type == EventType.E40_RECEIVED_FREEZE:
+            self._freeze()
+
+        elif event.type == EventType.E41_RECEIVED_THAW:
+            self._thaw()
+
+    # -- TRANSACTION_CANCELLED state --------------------------------------- #
+
+    def _update_transaction_cancelled(self, event, pdu):
+        if event.type == EventType.E0_ENTERED_STATE:
+            self.suspended = False
+            self._send_finished()
+            self._restart_ack_timer()
+
+        elif event.type == EventType.E2_ABANDON_TRANSACTION:
+            self._issue_abandoned_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E4_NOTICE_OF_SUSPENSION:
+            self._notice_of_suspension()
+
+        elif event.type == EventType.E5_SUSPEND_TIMERS:
+            self._suspend_inactivity_timer()
+            self._suspend_ack_timer()
+
+        elif event.type == EventType.E6_RESUME_TIMERS:
+            self._restart_inactivity_timer()
+            self._resume_ack_timer()
+
+        elif event.type == EventType.E13_RECEIVED_EOF_CANCEL:
+            self.condition_code = pdu.condition_code
+            if pdu.fault_location is not None:
+                self.status_report = {"fault_location": pdu.fault_location}
+            self._send_ack_eof()
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E18_RECEIVED_ACK_FINISHED:
+            if self.condition_code != ConditionCode.NO_ERROR:
+                self._issue_transaction_finished_indication()
+                self._shutdown()
+
+        elif event.type == EventType.E25_ACK_TIMEOUT:
+            self._restart_ack_timer()
+            if self._is_ack_limit_reached():
+                self._emit(InternalEvent(EventType.E2_ABANDON_TRANSACTION))
+            else:
+                self.condition_code = ConditionCode.CANCEL_REQUEST_RECEIVED
+                self._send_finished()
+
+        elif event.type == EventType.E27_INACTIVITY_TIMEOUT:
+            self._issue_abandoned_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E31_RECEIVED_SUSPEND_REQUEST:
+            self._emit(InternalEvent(EventType.E4_NOTICE_OF_SUSPENSION))
+
+        elif event.type == EventType.E32_RECEIVED_RESUME_REQUEST:
+            self._resume_request()
+
+        elif event.type == EventType.E34_RECEIVED_REPORT_REQUEST:
+            self._issue_report_indication()
+
+        elif event.type == EventType.E40_RECEIVED_FREEZE:
+            self._freeze()
+
+        elif event.type == EventType.E41_RECEIVED_THAW:
+            self._thaw()
+
+    # -- shared suspend/resume/freeze/thaw helpers ------------------------- #
+
+    def _notice_of_suspension(self):
+        if not self.suspended:
+            self._issue_suspended_indication()
+            self.suspended = True
+            if not self.frozen:
+                self._emit(InternalEvent(EventType.E5_SUSPEND_TIMERS))
+
+    def _resume_request(self):
+        if self.suspended:
+            self._issue_resumed_indication()
+            self.suspended = False
+            if not self.frozen:
+                self._emit(InternalEvent(EventType.E6_RESUME_TIMERS))
+
+    def _freeze(self):
+        if not self.frozen:
+            self.frozen = True
+            if not self.suspended:
+                self._emit(InternalEvent(EventType.E5_SUSPEND_TIMERS))
+
+    def _thaw(self):
+        if self.frozen:
+            self.frozen = False
+            if not self.suspended:
+                self._emit(InternalEvent(EventType.E6_RESUME_TIMERS))
+
+    # -- output helper ----------------------------------------------------- #
+
+    def _emit(self, output):
+        self._out.append(output)
+
+    # -- queries / predicates ---------------------------------------------- #
+
+    def _is_file_transfer(self):
+        return bool(self.source_filename and len(self.source_filename) > 0)
+
+    def _is_file_size_error(self, file_size):
+        return self.received_file_size > file_size
+
+    def _is_file_checksum_failure(self, expected, calculated):
+        # ``calculated`` is the temp-file checksum computed asynchronously by the
+        # shell (issue #21) and delivered on E42_CHECKSUM_READY; ``expected`` is
+        # the EOF-carried value stashed on ``received_file_checksum``.
+        return calculated != expected
+
+    def _finish_after_checksum(self, calculated_checksum):
+        """E42 continuation: verify checksum, finalize, and send Finished (#21)."""
+        if self._is_file_checksum_failure(
+            self.received_file_checksum, calculated_checksum
+        ):
+            if not self._fault_file_checksum():
+                self._close_tempfile()
+                return
+        self._copy_tempfile_to_destfile()
+        self._close_tempfile()
+        self.file_status = FileStatus.RETAINED_SUCCESSFULLY
+
+        if self.filestore_requests:
+            self._execute_filestore_requests()
+
+        self._send_finished()
+        self._restart_ack_timer()
+
+    def _is_nak_list_empty(self):
+        return not self.nak_list
+
+    # -- NAK list computation (pure, mirrors Machine.update_nak_list) ------- #
+
+    def _update_nak_list(self, file_size=None):
+        self.nak_list = []
+        pointer = 0
+        if not self.metadata_received:
+            self.nak_list.append((0, 0))
+        for offset, length in sorted(self.received_file_segments.items()):
+            if offset > pointer:
+                self.nak_list.append((pointer, offset))
+            pointer = offset + length
+        if file_size is not None:
+            if pointer < file_size:
+                self.nak_list.append((pointer, file_size))
+
+    def _get_segment_requests(self):
+        return self.nak_list
+
+    # -- timer effects (design D6) ----------------------------------------- #
+
+    def _restart_inactivity_timer(self):
+        if not self.suspended:
+            self._emit(
+                StartTimer(
+                    kind=TimerKind.INACTIVITY,
+                    interval=self.config.transaction_inactivity_limit,
+                )
+            )
+
+    def _resume_inactivity_timer(self):
+        if not self.suspended:
+            self._emit(
+                StartTimer(
+                    kind=TimerKind.INACTIVITY,
+                    interval=self.config.transaction_inactivity_limit,
+                )
+            )
+
+    def _suspend_inactivity_timer(self):
+        self._emit(CancelTimer(kind=TimerKind.INACTIVITY))
+
+    def _restart_ack_timer(self):
+        self._emit(
+            StartTimer(kind=TimerKind.ACK, interval=self.config.ack_timer_interval)
+        )
+
+    def _suspend_ack_timer(self):
+        self._ack_timer_suspended = True
+        self._emit(CancelTimer(kind=TimerKind.ACK))
+
+    def _resume_ack_timer(self):
+        self._ack_timer_suspended = False
+        self._emit(
+            StartTimer(kind=TimerKind.ACK, interval=self.config.ack_timer_interval)
+        )
+
+    def _restart_nak_timer(self):
+        self._emit(
+            StartTimer(kind=TimerKind.NAK, interval=self.config.nak_timer_interval)
+        )
+
+    def _cancel_nak_timer(self):
+        self._emit(CancelTimer(kind=TimerKind.NAK))
+
+    def _is_ack_limit_reached(self):
+        limit = self.config.ack_timer_expiration_limit
+        if limit is None:
+            return False
+        return self._ack_expiration_counter >= limit
+
+    def _is_nak_limit_reached(self):
+        limit = self.config.nak_timer_expiration_limit
+        if limit is None:
+            return False
+        return self._nak_expiration_counter >= limit
+
+    # -- expiration counters (bumped by the shell's timer event) ----------- #
+
+    def note_ack_timeout(self):
+        """Mirror the real ``Timer._expired`` ACK counter bump (design D6)."""
+        self._ack_expiration_counter += 1
+
+    def note_nak_timeout(self):
+        """Mirror the real ``Timer._expired`` NAK counter bump (design D6)."""
+        self._nak_expiration_counter += 1
+
+    # -- fault handling ---------------------------------------------------- #
+
+    def _fault_inactivity(self):
+        return self._run_fault_handler(
+            self.config.get_fault_handler(ConditionCode.INACTIVITY_DETECTED)
+        )
+
+    def _fault_file_size(self):
+        return self._run_fault_handler(
+            self.config.get_fault_handler(ConditionCode.FILE_SIZE_ERROR)
+        )
+
+    def _fault_file_checksum(self):
+        return self._run_fault_handler(
+            self.config.get_fault_handler(ConditionCode.FILE_CHECKSUM_FAILURE)
+        )
+
+    def _fault_ack_limit(self):
+        return self._run_fault_handler(
+            self.config.get_fault_handler(ConditionCode.POSITIVE_ACK_LIMIT_REACHED)
+        )
+
+    def _fault_nak_limit(self):
+        return self._run_fault_handler(
+            self.config.get_fault_handler(ConditionCode.NAK_LIMIT_REACHED)
+        )
+
+    def _run_fault_handler(self, fault_handler):
+        """Return True if execution should continue (IGNORE), False otherwise."""
+        if fault_handler == FaultHandlerAction.CANCEL:
+            self._emit(InternalEvent(EventType.E33_RECEIVED_CANCEL_REQUEST))
+            return False
+        elif fault_handler == FaultHandlerAction.SUSPEND:
+            self._emit(InternalEvent(EventType.E31_RECEIVED_SUSPEND_REQUEST))
+            return False
+        elif fault_handler == FaultHandlerAction.IGNORE:
+            return True
+        elif fault_handler == FaultHandlerAction.ABANDON:
+            self._emit(InternalEvent(EventType.E2_ABANDON_TRANSACTION))
+            return False
+        else:
+            raise ValueError
+
+    # -- file lifecycle effects -------------------------------------------- #
+
+    def _open_tempfile(self):
+        self._emit(OpenTemp())
+        self._file_open = True
+
+    def _store_file_data(self, pdu):
+        self._emit(WriteSegment(offset=pdu.segment_offset, data=bytes(pdu.file_data)))
+        self.received_file_segments[pdu.segment_offset] = len(pdu.file_data)
+
+    def _copy_tempfile_to_destfile(self):
+        # Carry the machine-state destination filename: on a lost-then-recovered
+        # Metadata (F2 seq 1/6) the frozen transaction has no filename, only the
+        # machine does (updated from the late Metadata).
+        self._emit(Finalize(destination_filename=self.destination_filename))
+
+    def _close_tempfile(self):
+        # Mirror Machine.close_tempfile: it does NOT clear the handle, so a
+        # subsequent shutdown() closes it a second time.
+        self._emit(CloseFile())
+
+    def _update_received_file_size(self, pdu):
+        new_size = pdu.segment_offset + len(pdu.file_data)
+        if self.received_file_size < new_size:
+            self.received_file_size = new_size
+            self._progress = new_size
+
+    def _absorb_metadata(self, pdu):
+        """Absorb a received Metadata PDU into machine state.
+
+        Shared by the ``WAIT_FOR_EOF`` and ``GET_MISSING_DATA`` E10 handlers so
+        they cannot drift (issue #26). Critically it sets ``source_filename`` /
+        ``destination_filename`` / ``checksum_type`` from the PDU — when the
+        receiver was created from a filename-less Filedata/EOF (Metadata lost or
+        reordered) the frozen transaction carries none of these, so without this
+        the destination filename stays ``None`` (finalize goes nowhere) and the
+        checksum type stays the default MODULAR (spurious FILE_CHECKSUM_FAILURE).
+        The filenames/messages are set before the metadata-received indication so
+        it reports the resolved values.
+        """
+        self.source_filename = pdu.source_filename
+        self.destination_filename = pdu.destination_filename
+        # ``messages_to_user`` is read by the metadata-received indication below;
+        # ``filestore_requests`` is (re)set by _process_metadata_options before
+        # any read, so it is not assigned here.
+        self.messages_to_user = pdu.messages_to_user
+        self.checksum_type = pdu.checksum_type
+
+        self.metadata_received = True
+        self.file_size = pdu.file_size
+        self._issue_metadata_received_indication(pdu.file_size)
+
+        if self._is_file_transfer():
+            if not self._file_open:
+                self._open_tempfile()
+        self._process_metadata_options(pdu)
+
+    def _process_metadata_options(self, pdu):
+        self.filestore_requests = pdu.filestore_requests
+        self.messages_to_user = pdu.messages_to_user
+        for message in self.messages_to_user or []:
+            message.originating_transaction = self.transaction
+            self._emit(PostUserMessage(message=message))
+
+    def _execute_filestore_requests(self):
+        # Filestore-request execution is a shell effect (design D3/D10): the
+        # machine carries the request TLVs but never touches the filestore. The
+        # old machine calls ``execute_filestore_requests`` directly here; this
+        # machine emits the equivalent command for the EffectExecutor to run.
+        self._emit(ExecuteFilestoreRequests(requests=self.filestore_requests))
+
+    def _shutdown(self):
+        # Mirror Receiver2.shutdown: base close (handle only if opened), then
+        # all three timers' shutdown() -> CancelTimer, always.
+        if self._file_open:
+            self._emit(CloseFile())
+            self._file_open = False
+        self._emit(CancelTimer(kind=TimerKind.INACTIVITY))
+        self._emit(CancelTimer(kind=TimerKind.ACK))
+        self._emit(CancelTimer(kind=TimerKind.NAK))
+        self.state = MachineState.COMPLETED
+
+    # -- reply-PDU header reuse (CCSDS 5.6.1 l), pure copy) ---------------- #
+
+    def _reuse_senders_first_pdu_header(self, pdu):
+        if not self.pdu_received:
+            self.pdu_received = True
+            h = pdu.pdu_header
+            if h.direction == Direction.TOWARD_RECEIVER:
+                direction = Direction.TOWARD_SENDER
+            else:
+                direction = Direction.TOWARD_RECEIVER
+            self._first_header = {
+                "direction": direction,
+                "transmission_mode": h.transmission_mode,
+                "crc_flag": h.crc_flag,
+                "large_file_flag": h.large_file_flag,
+                "segmentation_control": h.segmentation_control,
+                "length_of_entity_ids": h.length_of_entity_ids,
+                "segmentation_metadata_flag": h.segmentation_metadata_flag,
+                "length_of_seq_number": h.length_of_seq_number,
+                "source_entity_id": h.source_entity_id,
+                "transaction_seq_number": h.transaction_seq_number,
+                "destination_entity_id": h.destination_entity_id,
+            }
+
+    # -- reply PDUs (pure builders) ---------------------------------------- #
+
+    def _send_nak(self):
+        # end_of_scope must cover every segment request. When the tail of the
+        # file is missing (up to the whole file when Metadata + all Filedata are
+        # lost) the nak_list carries a (pointer, file_size) request whose end is
+        # the EOF-declared file_size, which exceeds received_file_size. Scope to
+        # the known file_size so the NAK's scope encloses its own requests (a
+        # strict peer validates requests lie within [start_of_scope, end_of_scope]);
+        # fall back to received_file_size before EOF sets file_size.
+        end_of_scope = (
+            self.file_size if self.file_size is not None else self.received_file_size
+        )
+        pdu = NakPdu(
+            start_of_scope=0,
+            end_of_scope=end_of_scope,
+            segment_requests=self._get_segment_requests(),
+            **self._first_header,
+        )
+        self._emit(SendPdu(pdu=pdu))
+
+    def _send_ack_eof(self):
+        pdu = AckPdu(
+            directive_code_ack=DirectiveCode.EOF,
+            directive_subtype_code=DirectiveSubTypeCode.ACK_OTHERS,
+            condition_code=self.condition_code,
+            transaction_status=TransactionStatus.UNDEFINED,
+            **self._first_header,
+        )
+        self._emit(SendPdu(pdu=pdu))
+
+    def _send_finished(self):
+        pdu = FinishedPdu(
+            condition_code=self.condition_code,
+            delivery_code=self.delivery_code,
+            file_status=self.file_status,
+            filestore_responses=self.filestore_responses,
+            fault_location=None,
+            **self._first_header,
+        )
+        self._emit(SendPdu(pdu=pdu))
+
+    # -- indications ------------------------------------------------------- #
+
+    def _issue_metadata_received_indication(self, file_size):
+        self._emit(
+            indications.metadata_received(
+                self.transaction.id,
+                self.transaction.source_entity_id,
+                file_size,
+                self.source_filename,
+                self.destination_filename,
+                self.messages_to_user,
+            )
+        )
+
+    def _issue_filesegment_received_indication(self, offset, length):
+        self._emit(
+            indications.filesegment_received(self.transaction.id, offset, length)
+        )
+
+    def _issue_transaction_finished_indication(self):
+        self._emit(
+            indications.transaction_finished(
+                self.transaction.id,
+                self.condition_code,
+                self.file_status,
+                self.delivery_code,
+                self.filestore_responses,
+                self.status_report,
+            )
+        )
+
+    def _issue_suspended_indication(self):
+        self._emit(indications.suspended(self.transaction.id, self.condition_code))
+
+    def _issue_resumed_indication(self):
+        self._emit(indications.resumed(self.transaction.id, self._progress))
+
+    def _issue_report_indication(self):
+        self._emit(indications.report(self.transaction.id, self.status_report))
+
+    def _issue_abandoned_indication(self):
+        self._emit(
+            indications.abandoned(
+                self.transaction.id, self.condition_code, self._progress
+            )
+        )