pycfdp 0.2.2__py3-none-any.whl

cfdp/pure/outputs.py

@@ -0,0 +1,203 @@
+"""Output taxonomy for the pure machine boundary (design D3/D8/D9).
+
+A pure machine's ``update_state(event) -> list[Output]`` returns an ordered list
+of :class:`Output` values. Each output is either an **effect** (a command the
+shell's ``EffectExecutor`` interprets) or an **internal event** (an existing
+``EventType`` the dispatcher re-enqueues on the shared FIFO queue).
+
+All outputs are frozen dataclasses so they are readable, pattern-matchable, and
+value-equatable — the last property is what makes differential trace comparison
+against the old machines possible.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+class TimerKind:
+    """The wall-clock timers a machine may drive (design D6)."""
+
+    ACK = "ACK"
+    NAK = "NAK"
+    INACTIVITY = "INACTIVITY"
+
+
+class IndicationKind:
+    """CFDP indications a machine may emit, mirroring ``CfdpEntity._indication_*``."""
+
+    TRANSACTION = "transaction"
+    EOF_SENT = "eof_sent"
+    EOF_RECEIVED = "eof_received"
+    TRANSACTION_FINISHED = "transaction_finished"
+    METADATA_RECEIVED = "metadata_received"
+    FILESEGMENT_RECEIVED = "filesegment_received"
+    SUSPENDED = "suspended"
+    RESUMED = "resumed"
+    REPORT = "report"
+    FAULT = "fault"
+    ABANDONED = "abandoned"
+
+
+class Output:
+    """Marker base class for everything a machine returns."""
+
+
+# --------------------------------------------------------------------------- #
+# Effects — commands the shell executes                                       #
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class SendPdu(Output):
+    """Encode and transmit a PDU the machine has already built (pure)."""
+
+    pdu: Any
+
+
+@dataclass(frozen=True)
+class OpenSource(Output):
+    """Open the transaction's source file for reading (send side)."""
+
+
+@dataclass(frozen=True)
+class OpenTemp(Output):
+    """Open a temporary file to receive incoming file data (receive side)."""
+
+
+@dataclass(frozen=True)
+class WriteSegment(Output):
+    """Write ``data`` at ``offset`` into the receive-side file."""
+
+    offset: int
+    data: bytes
+
+
+@dataclass(frozen=True)
+class ExecuteFilestoreRequests(Output):
+    """Execute the transaction's filestore requests against the filestore.
+
+    The receive side runs the Metadata-carried filestore requests (create /
+    delete / rename / ... ) at Finished time. The pure machine holds the request
+    TLVs but never touches the filestore; the shell interprets this effect via
+    ``cfdp.meta.execute_filestore_requests`` (design D3/D10 — mutating filestore
+    operations are returned commands, not sync queries).
+    """
+
+    requests: Any
+
+
+@dataclass(frozen=True)
+class Finalize(Output):
+    """Copy the completed temp file to its destination (receive side).
+
+    ``destination_filename`` carries the resolved destination path from machine
+    state. This matters for Class-2 recovery: when the Metadata PDU is lost and
+    later recovered via NAK, the destination filename is only known on the
+    machine (the frozen :class:`~cfdp.pure.transaction.Transaction` was built
+    from a filename-less Filedata/EOF PDU). ``None`` means "fall back to the
+    transaction's ``destination_filename``" — the Class-1 path, where Metadata
+    always arrives first, leaves this unset.
+    """
+
+    destination_filename: Any = None
+
+
+@dataclass(frozen=True)
+class CloseFile(Output):
+    """Close the transaction's open file handle."""
+
+
+@dataclass(frozen=True)
+class StartTimer(Output):
+    """(Re)start the timer of ``kind`` with the given interval in seconds."""
+
+    kind: str
+    interval: float
+
+
+@dataclass(frozen=True)
+class CancelTimer(Output):
+    """Cancel the timer of ``kind``."""
+
+    kind: str
+
+
+@dataclass(frozen=True)
+class SuspendTimer(Output):
+    """Suspend (cancel-without-forget) the timer of ``kind``."""
+
+    kind: str
+
+
+@dataclass(frozen=True)
+class ResumeTimer(Output):
+    """Resume (restart) a previously suspended timer of ``kind``."""
+
+    kind: str
+
+
+@dataclass(frozen=True)
+class ScheduleEvent(Output):
+    """Enqueue ``event`` on the shared FIFO queue after ``delay`` seconds.
+
+    Used for paced re-triggers (e.g. the ``inter_pdu_delay`` file-data pump).
+    A delay of ``0.0`` is an immediate re-enqueue.
+    """
+
+    event: str
+    delay: float = 0.0
+
+
+@dataclass(frozen=True)
+class EmitIndication(Output):
+    """Emit a CFDP indication of ``kind`` with positional ``args``.
+
+    ``kind`` is an :class:`IndicationKind` value; the shell maps it to the
+    matching ``CfdpEntity._indication_*`` call.
+    """
+
+    kind: str
+    args: tuple[Any, ...] = ()
+
+
+@dataclass(frozen=True)
+class PostUserMessage(Output):
+    """Post a message-to-user onto the entity's message thread."""
+
+    message: Any
+
+
+@dataclass(frozen=True)
+class RequestChecksum(Output):
+    """Ask the shell to compute the file checksum asynchronously (issue #21).
+
+    The result returns as an injected ``E42_CHECKSUM_READY`` event carrying the
+    value on ``event.checksum`` (design R1: the async-result channel is baseline
+    shell machinery so ``checksum`` runs off the single dispatcher thread and a
+    large-file checksum no longer stalls every other transaction).
+
+    ``checksum_type`` is the algorithm to use. ``from_temp_handle`` selects the
+    file: the receive side (``True``) reads back the shell-held in-progress temp
+    handle; the send side (``False``) opens the source file **afresh** so the
+    checksum worker never shares the file-data pump's handle (which it seeks and
+    later closes on a different thread).
+    """
+
+    checksum_type: int = 0
+    from_temp_handle: bool = False
+
+
+# --------------------------------------------------------------------------- #
+# Internal event — an existing EventType re-enqueued by the dispatcher        #
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class InternalEvent(Output):
+    """An existing ``EventType`` the machine re-feeds through the shell (D2/D8).
+
+    The dispatcher enqueues it on the shared FIFO queue immediately. Delayed
+    re-triggers use :class:`ScheduleEvent` instead.
+    """
+
+    event: str

cfdp/pure/query_port.py

@@ -0,0 +1,48 @@
+"""The read-only synchronous query port (design D3/D5).
+
+The machine may call these mid-decision, synchronously. Per D5 they touch only
+**local, fast, non-blocking** resources — the local filestore and the local
+transport-buffer readiness — never the remote peer. Anything remote or
+possibly-slow must be a command + injected result event instead.
+
+This module defines the interface only; concrete backing (filestore + transport
++ the in-progress temp handle) is wired up in the shell seam (issue #16).
+"""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class QueryPort(Protocol):
+    """Local-only, synchronous reads a pure machine may perform."""
+
+    def is_file(self, filename: str) -> bool:
+        """Return True if ``filename`` names an existing file in the filestore."""
+        ...
+
+    def size(self, filename: str) -> int:
+        """Return the size in bytes of ``filename`` (0 if absent)."""
+        ...
+
+    def checksum(self, checksum_type: int) -> int:
+        """Return the checksum of the transaction's current file.
+
+        No longer called by the pure machines: as of issue #21 checksum is an
+        async effect (:class:`~cfdp.pure.outputs.RequestChecksum` -> the
+        shell's :class:`~cfdp.shell.checksum_service.ChecksumService` ->
+        ``E42_CHECKSUM_READY``) so a large-file checksum never blocks the
+        dispatcher (design R1). Retained on the port interface for the
+        differential test harness, which splices the async hop synchronously.
+        """
+        ...
+
+    def read_segment(self, offset: int, length: int) -> tuple[int, bytes]:
+        """Read ``length`` bytes from the source file starting at ``offset``.
+
+        Returns ``(offset, data)`` mirroring the old ``Transaction.get_file_segment``.
+        """
+        ...
+
+    def transport_ready(self) -> bool:
+        """Return True if the local transport buffer can accept another PDU."""
+        ...

cfdp/pure/transaction.py

@@ -0,0 +1,43 @@
+"""Frozen ``Transaction`` value type (design D3, "Data model").
+
+This is the immutable identity + descriptor of a transaction: entity ids, the
+sequence number, transmission mode, filenames, and checksum type — exactly the
+fields the design's "Data model" section lists, nothing more. It carries **no**
+``kernel`` reference, **no** ``file_handle``, and **no** mutable runtime state —
+all of that moves into the pure machine as plain data or into the shell. The
+request payload (messages-to-user / filestore requests) is *not* identity; it
+arrives with the creating event, not on this descriptor.
+
+This is the only transaction type in the codebase; it is re-exported as the
+public ``cfdp.Transaction`` (the pre-cutover mutable, kernel-coupled Transaction
+was removed with the old machines, issue #22).
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from ..constants import ChecksumType
+
+# The identity of a transaction: ``(source_entity_id, seq_number)``. Entity ids
+# are protocol-opaque (int or bytes depending on the deployment), hence ``Any``
+# for the first slot. This is the single most repeated implicit type across the
+# machines and shell — naming it once makes those signatures self-documenting.
+TransactionId = tuple[Any, int]
+
+
+@dataclass(frozen=True)
+class Transaction:
+    """Immutable end-to-end descriptor of a single File Delivery Unit transfer."""
+
+    source_entity_id: Any
+    seq_number: int
+    destination_entity_id: Any
+    transmission_mode: int
+    source_filename: str | None = None
+    destination_filename: str | None = None
+    checksum_type: int = ChecksumType.MODULAR
+
+    @property
+    def id(self) -> TransactionId:
+        """Transaction id: ``(source_entity_id, seq_number)``."""
+        return (self.source_entity_id, self.seq_number)

cfdp/remote_entity_config.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class RemoteEntityConfig:
+    ack_timer_interval: float | None = None
+    ack_timer_expiration_limit: int | None = None
+    nak_timer_interval: float | None = None
+    nak_timer_expiration_limit: int | None = None
+    transaction_inactivity_limit: float | None = None
+    default_fault_handlers: dict | None = None
+    inter_pdu_delay: float | None = None

cfdp/shell/__init__.py

@@ -0,0 +1,44 @@
+"""Imperative shell for the pure state machines (issue #16).
+
+The pure machines (``cfdp.pure.machines``) are functions of ``(state, event)``
+returning an ordered ``list[Output]`` (design D1). This package is the
+**imperative shell** that runs them over real I/O:
+
+* :class:`~cfdp.shell.effect_executor.EffectExecutor` — interprets effect
+  outputs and owns the ``tid -> handle`` file table and file lifecycle (D10).
+* :class:`~cfdp.shell.query_port.EntityQueryPort` — backs the synchronous,
+  local-only query port a machine calls mid-decision (D3/D5), reading the source
+  filestore and the shell-held in-progress temp handle.
+* :class:`~cfdp.shell.machine_registry.MachineRegistry` — the ``tid -> machine``
+  map, machine creation (from ``put`` and from inbound Metadata/Filedata/EOF),
+  completion detection and TTL reaping (D7).
+* :class:`~cfdp.shell.timer_service.TimerService` — the ``(tid, kind)`` wall-clock
+  table with start/cancel/suspend/resume semantics; injects an expiry as a normal
+  ``EventType`` event onto the shared FIFO so pure machines stay threadless (D6).
+* :class:`~cfdp.shell.dispatcher.Dispatcher` — owns the single event thread +
+  queue, feeds events to the owning machine, walks the returned ordered output
+  list executing effects inline and re-enqueuing internal events on the shared
+  FIFO queue (D8), with a rigid per-effect exception boundary that maps a
+  failing effect to a fault event injected into the owning machine only (D4/D7).
+
+Wired into :class:`cfdp.core.CfdpEntity` for all transfers — both Class-1
+(``UNACKNOWLEDGED``) and Class-2 (``ACKNOWLEDGED``). This is the only machine
+stack (the old machines were removed at the cutover, issue #22).
+"""
+
+from .checksum_service import ChecksumService
+from .dispatcher import Dispatcher
+from .effect_executor import EffectExecutor, FileTable
+from .machine_registry import MachineRegistry
+from .query_port import EntityQueryPort
+from .timer_service import TimerService
+
+__all__ = [
+    "EffectExecutor",
+    "FileTable",
+    "EntityQueryPort",
+    "MachineRegistry",
+    "Dispatcher",
+    "TimerService",
+    "ChecksumService",
+]

cfdp/shell/checksum_service.py

@@ -0,0 +1,136 @@
+"""The shell's async-checksum worker (design R1 / issue #21).
+
+A whole-file checksum is O(file size). Computing it on the single dispatcher
+thread — as the sync query port did — freezes *every* transaction for the
+duration of a large-file checksum. This service moves that work off the event
+thread: a pure machine emits a ``RequestChecksum`` effect, the service computes
+the value on a worker thread, and marshals the result back onto the entity's
+shared FIFO as an ``E42_CHECKSUM_READY`` event (design D8 — the same one input
+door as every other event). The worker never touches machine state directly.
+
+**Which file is checksummed** mirrors the sync query port exactly (design D10):
+the receive side reads back the shell-held temp handle in the
+:class:`~cfdp.shell.effect_executor.FileTable`; the send side (no handle in the
+table) opens the source afresh.
+
+**Thread-safety / no leaks.** Workers are daemon threads tracked in a set under
+a lock; :meth:`stop` joins them so no worker outlives entity shutdown (the suite
+has active-thread-count assertions). A worker whose transaction was reaped while
+it ran still injects its event harmlessly — the dispatcher drops an event for an
+absent machine.
+
+**Every worker resolves to exactly one injected event** (issue #24). The happy
+path injects ``E42_CHECKSUM_READY``. If the computation itself fails (source
+file removed before the worker reopens it, temp-handle read error, filestore
+backend error), the worker must NOT silently drop the event: a Sender1 parked on
+the EOF continuation has no inactivity timer, so a missing event strands the
+transaction forever. On any compute failure the worker instead injects a
+terminating ``E33_RECEIVED_CANCEL_REQUEST`` so the parked machine runs its
+cancellation/fault path to a terminal state.
+"""
+
+import threading
+
+from .. import logger
+from ..event import Event, EventType
+
+
+class ChecksumService:
+    """Computes file checksums off the event thread and injects the result."""
+
+    def __init__(self, entity, file_table):
+        self._entity = entity
+        self._files = file_table
+        self._lock = threading.Lock()
+        self._workers = set()
+
+    def request(self, tid, transaction, checksum_type, from_temp_handle=False):
+        """Compute ``transaction``'s file checksum on a worker, then inject E42.
+
+        Returns immediately; the result arrives later as an
+        ``E42_CHECKSUM_READY`` event on the entity FIFO for this transaction.
+        ``from_temp_handle`` picks the receive-side temp handle vs the send-side
+        source-opened-afresh (see :class:`~cfdp.pure.outputs.RequestChecksum`).
+        """
+        worker = threading.Thread(
+            target=self._run,
+            args=(tid, transaction, checksum_type, from_temp_handle),
+            daemon=True,
+        )
+        with self._lock:
+            self._workers.add(worker)
+        worker.start()
+
+    def _run(self, tid, transaction, checksum_type, from_temp_handle):
+        try:
+            try:
+                value = self._compute_value(
+                    tid, transaction, checksum_type, from_temp_handle
+                )
+            except Exception:
+                # A dropped event strands the parked machine forever (a Sender1
+                # has no inactivity timer). Guarantee exactly one terminating
+                # event so it reaches a terminal state (issue #24).
+                logger.exception(
+                    "checksum computation failed for transaction %s; "
+                    "injecting a cancellation to terminate the parked machine",
+                    tid,
+                )
+                self._entity.trigger_event(
+                    Event(transaction, EventType.E33_RECEIVED_CANCEL_REQUEST)
+                )
+            else:
+                self._entity.trigger_event(
+                    Event(transaction, EventType.E42_CHECKSUM_READY, checksum=value)
+                )
+        finally:
+            with self._lock:
+                self._workers.discard(threading.current_thread())
+
+    def _compute_value(self, tid, transaction, checksum_type, from_temp_handle):
+        """Read the checksum, mirroring ``EntityQueryPort.checksum`` (design D10).
+
+        Receive side (``from_temp_handle``): read back the shell-held temp
+        handle. Send side: open the source **afresh** so the worker never shares
+        the file-data pump's source handle (concurrent seek/close on another
+        thread). Isolated so a test can wrap it to simulate a slow computation.
+        """
+        if from_temp_handle:
+            handle = self._files.get(tid)
+            if handle is None:
+                # A receive-side RequestChecksum is only emitted for a file
+                # transfer whose temp handle the shell opened, so a missing
+                # handle is an abnormal state (reaped/dropped). Returning 0 here
+                # would be miscompared against the real EOF checksum and fault a
+                # correctly-delivered file; raise instead so the worker's
+                # exactly-one-terminating-event fallback injects E33 (issue #24).
+                raise ValueError(f"no temp handle for transaction {tid} to checksum")
+            return handle.calculate_checksum(checksum_type)
+        source = transaction.source_filename
+        if not source:
+            return 0
+        fh = self._entity.filestore.open(source)
+        try:
+            return fh.calculate_checksum(checksum_type)
+        finally:
+            fh.close()
+
+    def active_worker_count(self):
+        with self._lock:
+            return len(self._workers)
+
+    def stop(self):
+        """Join every outstanding worker so none leaks past entity shutdown."""
+        with self._lock:
+            workers = list(self._workers)
+        for worker in workers:
+            if worker is not threading.current_thread():
+                worker.join(timeout=5)
+                if worker.is_alive():
+                    logger.warning(
+                        "checksum worker %s did not finish within 5s of stop(); "
+                        "it keeps running as a daemon",
+                        worker.name,
+                    )
+        with self._lock:
+            self._workers.clear()

cfdp/shell/dispatcher.py

@@ -0,0 +1,185 @@
+"""The dispatcher: runs a pure machine's outputs against the shell (design D8).
+
+``update_state(event)`` returns one ordered ``list[Output]`` mixing effects and
+internal events. The :class:`Dispatcher` walks that list in order (design D8):
+
+* an **effect** is executed immediately, in place, via the
+  :class:`~cfdp.shell.effect_executor.EffectExecutor`;
+* an **internal event** (or a delayed :class:`~cfdp.pure.outputs.ScheduleEvent`)
+  is **re-enqueued** on the shared FIFO queue — via the entity's
+  ``trigger_event`` so the file-data pump's ``inter_pdu_delay`` pacing (and any
+  test hook on ``trigger_event``) still applies.
+
+It never drains to quiescence: it walks one event's outputs, enqueues the
+follow-ups, and returns to the queue. That is what keeps the file-data pump
+interruptible by a mid-transfer cancel/suspend (design D8).
+
+**Per-effect exception boundary (design D4/D7, required).** Each effect runs
+inside a ``try``; a raised exception is caught, mapped to the corresponding
+fault event, and injected into the *owning* machine only. It never escapes to
+kill the event thread or disturb another transaction. An effect whose failure
+has no mapping abandons that one transaction (an ``E2_ABANDON_TRANSACTION``)
+and is logged.
+"""
+
+from .. import logger
+from ..constants import ConditionCode, FaultHandlerAction, MachineState
+from ..event import Event, EventType
+from ..pure.outputs import (
+    CloseFile,
+    Finalize,
+    InternalEvent,
+    OpenSource,
+    OpenTemp,
+    ScheduleEvent,
+    SendPdu,
+    WriteSegment,
+)
+
+# Filestore/file effects: a failure here is a FILESTORE_REJECTION fault (design
+# D4, issue #28). The action is resolved from the machine's configured
+# ``FILESTORE_REJECTION`` handler (default CANCEL) rather than hardcoding cancel,
+# so a configured IGNORE/SUSPEND/ABANDON is honored.
+_FILESTORE_FAULT_EFFECTS = (
+    OpenSource,
+    OpenTemp,
+    WriteSegment,
+    Finalize,
+    CloseFile,
+)
+
+# How each FaultHandlerAction maps to an injected event, mirroring the machines'
+# own ``_run_fault_handler`` (issue #28). IGNORE injects nothing (continue).
+_FAULT_ACTION_EVENT = {
+    FaultHandlerAction.CANCEL: EventType.E33_RECEIVED_CANCEL_REQUEST,
+    FaultHandlerAction.SUSPEND: EventType.E31_RECEIVED_SUSPEND_REQUEST,
+    FaultHandlerAction.ABANDON: EventType.E2_ABANDON_TRANSACTION,
+}
+
+
+class Dispatcher:
+    """Walks a pure machine's output list, executing effects and re-feeding events."""
+
+    def __init__(self, entity, registry, executor):
+        self._entity = entity
+        self._registry = registry
+        self._executor = executor
+
+    def dispatch(self, machine, event):
+        """Feed ``event`` to ``machine`` and process its returned outputs.
+
+        Returns nothing; side effects (I/O, re-enqueued events, completion
+        marking) happen in place. This is the single entry the entity's event
+        thread calls for a pure (new-stack) machine.
+        """
+        # Bump the ACK/NAK expiration-limit counter BEFORE the handler reads it
+        # (issue #29). These counters are protocol state on the machine; the
+        # machine's E25/E26 handler reads them via ``_is_ack_limit_reached`` /
+        # ``_is_nak_limit_reached``, so the bump must land first — otherwise the
+        # limit never trips and retransmission loops forever (F2 seq 7/8).
+        #
+        # This used to run on the TimerService's timer thread, a lost-update race
+        # with this event thread. E25/E26 are produced ONLY by the TimerService,
+        # so this single-threaded event-thread site is the one safe place to bump.
+        # Class-1 machines lack ``note_*`` methods but also never receive E25/E26,
+        # so ``getattr(..., None)`` guards them harmlessly.
+        if event.type == EventType.E25_ACK_TIMEOUT:
+            note = getattr(machine, "note_ack_timeout", None)
+            if note is not None:
+                note()
+        elif event.type == EventType.E26_NAK_TIMEOUT:
+            note = getattr(machine, "note_nak_timeout", None)
+            if note is not None:
+                note()
+
+        try:
+            outputs = machine.update_state(event)
+        except Exception:
+            # A machine that raises is a bug, not a protocol fault; contain it
+            # to this transaction rather than killing the event thread.
+            logger.exception(
+                "Pure machine raised handling %s for %s",
+                event.type,
+                machine.transaction.id,
+            )
+            self._mark_if_complete(machine)
+            return
+
+        for out in outputs:
+            if isinstance(out, InternalEvent):
+                self._enqueue(machine, out.event)
+            elif isinstance(out, ScheduleEvent):
+                self._enqueue(machine, out.event)
+            else:
+                self._run_effect(machine, out)
+
+        self._mark_if_complete(machine)
+
+    # -- effect execution with the D4 exception boundary ------------------- #
+
+    def _run_effect(self, machine, effect):
+        try:
+            self._executor.execute(machine.transaction.id, machine.transaction, effect)
+        except Exception:
+            logger.exception(
+                "Effect %r failed for %s; faulting that transaction only",
+                type(effect).__name__,
+                machine.transaction.id,
+            )
+            self._inject_fault(machine, effect)
+
+    def _inject_fault(self, machine, effect):
+        """Map a failed effect to a fault event injected into ``machine`` (D4).
+
+        A failed filestore/file effect is a FILESTORE_REJECTION fault: resolve the
+        configured handler (default CANCEL) and map it exactly as the machines'
+        own ``_run_fault_handler`` does — CANCEL -> E33, SUSPEND -> E31,
+        ABANDON -> E2, IGNORE -> inject nothing (continue). This honors a
+        configured non-default handler instead of always cancelling (issue #28).
+        """
+        if isinstance(effect, _FILESTORE_FAULT_EFFECTS):
+            action = machine.config.get_fault_handler(ConditionCode.FILESTORE_REJECTION)
+            if action == FaultHandlerAction.IGNORE:
+                # IGNORE: continue as if the effect succeeded. There is nothing to
+                # inject; the transaction proceeds. (The world side-effect did not
+                # happen, matching how the machines treat an ignored fault.)
+                return
+            event_type = _FAULT_ACTION_EVENT.get(action)
+            if event_type is None:
+                # Unknown action: fail safe by abandoning just this transaction.
+                event_type = EventType.E2_ABANDON_TRANSACTION
+            self._enqueue(machine, event_type)
+        elif isinstance(effect, SendPdu):
+            # A transport send failure is NOT a filestore rejection, so it does
+            # NOT consult the FILESTORE_REJECTION handler (issue #28). There is no
+            # CFDP condition code for "local transport send failed", so we map it
+            # to a contained cancel of just this transaction (E33): the machine's
+            # E33 handler sets CANCEL_REQUEST_RECEIVED and shuts the transaction
+            # down cleanly. Cancel (not abandon) preserves the long-standing
+            # behavior the Class-1 shell-seam contract test relies on, and unlike
+            # a filestore rejection this action is fixed rather than configurable.
+            self._enqueue(machine, EventType.E33_RECEIVED_CANCEL_REQUEST)
+        else:
+            # No mapping for this effect: abandon just this transaction.
+            self._enqueue(machine, EventType.E2_ABANDON_TRANSACTION)
+
+    # -- re-feed onto the shared FIFO queue (design D8) -------------------- #
+
+    def _enqueue(self, machine, event_type):
+        self._entity.trigger_event(Event(machine.transaction, event_type))
+
+    # -- completion detection ---------------------------------------------- #
+
+    def _mark_if_complete(self, machine):
+        # Only COMPLETED is terminal (issue #23). TRANSACTION_CANCELLED is NOT:
+        # a Class-2 machine entering it has just armed its cancel-handshake ACK
+        # timer (sends EOF-cancel/Finished-cancel then ``_restart_ack_timer``).
+        # Treating it as terminal would call ``_on_pure_machine_complete`` ->
+        # ``_timer_service.cancel_all`` and instantly kill that ACK timer, making
+        # the E25 retransmit path dead code. The Class-2 cancel machines reach
+        # COMPLETED via ``_shutdown()`` only once the handshake actually closes
+        # (ACK-EOF / Finished received, or abandonment after the ACK limit).
+        # Class-1 cancel goes straight to COMPLETED (never TRANSACTION_CANCELLED),
+        # so prompt teardown is preserved.
+        if machine.state == MachineState.COMPLETED:
+            self._entity._on_pure_machine_complete(machine.transaction.id)