bdo-toolkit 1.0.2__tar.gz → 1.0.3__tar.gz

{bdo_toolkit-1.0.2/src/bdo_toolkit.egg-info → bdo_toolkit-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.2
+Version: 1.0.3
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -28,6 +28,7 @@ Dynamic: license-file
 # bdo-toolkit
 
 [![CI](https://img.shields.io/github/actions/workflow/status/ychwu/bdo-toolkit/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/ychwu/bdo-toolkit/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/bdo-toolkit?style=flat-square&label=version)](https://pypi.org/project/bdo-toolkit/)
 [![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://github.com/ychwu/bdo-toolkit/blob/main/pyproject.toml)
 ![Tested on NA/EU](https://img.shields.io/badge/tested-NA%2FEU-5b61a8?style=flat-square)
 [![Package: Stable](https://img.shields.io/badge/package-stable-2f855a?style=flat-square)](https://ychwu.github.io/bdo-toolkit/#stability)
@@ -48,11 +49,21 @@ traffic into structured, application-ready data.
 
 ## Capabilities
 
-| In-game task | Python result | Status | Guide |
+bdo-toolkit exposes three passive workflows. Each can observe live traffic or
+replay a saved PCAP or PCAPNG file.
+
+| Capability | What it provides | Guide | Status |
 | --- | --- | --- | --- |
-| Watch supported item changes such as loot, gathering, and storage activity | A continuing stream of typed `BDOEvent` objects | Stable | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Log in or switch characters | One observational `ItemStateSnapshot` of inventory, known balances, and town storage | Beta | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Load the Arena of Solare Leaderboard | One `SolareCaptureResult`; a complete result contains a leaderboard snapshot | Beta | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
+| Item activity | A continuing stream of typed `BDOEvent` objects for supported loot, gathering, inventory, and storage changes | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) | Stable |
+| Inventory and town storage | A finite `ItemStateSnapshot` assembled from character-load traffic, with inventory, known balances, and observed town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) | Beta |
+| Arena of Solare leaderboards | A finite `SolareCaptureResult` containing overall rankings, class tables, and player statistics when the capture is complete | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) | Beta |
+
+These workflows include synchronous and
+[asyncio](https://ychwu.github.io/bdo-toolkit/#asyncio) sessions, capture and
+decoder health diagnostics, console and JSONL event writers, and a
+[command-line interface](https://ychwu.github.io/bdo-toolkit/#cli). Exact
+signatures, fields, lifecycle behavior, and failure contracts are in the
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index).
 
 Testing and validation cover **NA/EU only**. Compatibility with other regional
 services is unknown.
@@ -98,46 +109,12 @@ installed with the Python wheel.
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)
 for every script, its prerequisites, and the guide that explains it.
 
-## Documentation
-
-The documentation separates task-focused guides from the symbol-first API
-reference. Exact signatures, fields, lifecycle behavior, and failure contracts
-live there rather than in this README.
-
-| Goal | Start here |
-| --- | --- |
-| Understand the package | [Overview](https://ychwu.github.io/bdo-toolkit/#overview) |
-| Build with live item events | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Query character inventory and town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Rebuild item decoding after a patch | [Calibration](https://ychwu.github.io/bdo-toolkit/#calibration-workflow) |
-| Capture and query an Arena of Solare leaderboard | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
-| Integrate with an asyncio application | [Asyncio integration](https://ychwu.github.io/bdo-toolkit/#asyncio) |
-| Look up a class, function, or model | [API index](https://ychwu.github.io/bdo-toolkit/#api-index) |
-| Use the terminal interface | [Command line](https://ychwu.github.io/bdo-toolkit/#cli) |
-| Diagnose a problem | [Troubleshooting](https://ychwu.github.io/bdo-toolkit/#errors) |
-| Review data handling and project boundaries | [Safety & privacy](https://ychwu.github.io/bdo-toolkit/#stability) |
-
 ## Support
 
 For questions, contact me on Discord: `._.__.__._._.__._____.__._.___.`
 
 For bugs and feature requests, [open a GitHub issue](https://github.com/ychwu/bdo-toolkit/issues).
 
-## Development
-
-```powershell
-git clone https://github.com/ychwu/bdo-toolkit.git
-cd bdo-toolkit
-python -m pip install -e ".[dev]"
-python -m pytest -q -W error
-python -m mypy src/bdo_toolkit
-python -m pip wheel . --no-deps --wheel-dir dist
-```
-
-CI runs tests, type checking, wheel construction, and a CLI smoke test on
-Ubuntu and Windows with Python 3.14. Tests that require private
-game-session captures skip when those local fixtures are absent.
-
 ## License
 
 bdo-toolkit is available under the

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/README.md

@@ -1,6 +1,7 @@
 # bdo-toolkit
 
 [![CI](https://img.shields.io/github/actions/workflow/status/ychwu/bdo-toolkit/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/ychwu/bdo-toolkit/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/bdo-toolkit?style=flat-square&label=version)](https://pypi.org/project/bdo-toolkit/)
 [![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://github.com/ychwu/bdo-toolkit/blob/main/pyproject.toml)
 ![Tested on NA/EU](https://img.shields.io/badge/tested-NA%2FEU-5b61a8?style=flat-square)
 [![Package: Stable](https://img.shields.io/badge/package-stable-2f855a?style=flat-square)](https://ychwu.github.io/bdo-toolkit/#stability)
@@ -21,11 +22,21 @@ traffic into structured, application-ready data.
 
 ## Capabilities
 
-| In-game task | Python result | Status | Guide |
+bdo-toolkit exposes three passive workflows. Each can observe live traffic or
+replay a saved PCAP or PCAPNG file.
+
+| Capability | What it provides | Guide | Status |
 | --- | --- | --- | --- |
-| Watch supported item changes such as loot, gathering, and storage activity | A continuing stream of typed `BDOEvent` objects | Stable | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Log in or switch characters | One observational `ItemStateSnapshot` of inventory, known balances, and town storage | Beta | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Load the Arena of Solare Leaderboard | One `SolareCaptureResult`; a complete result contains a leaderboard snapshot | Beta | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
+| Item activity | A continuing stream of typed `BDOEvent` objects for supported loot, gathering, inventory, and storage changes | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) | Stable |
+| Inventory and town storage | A finite `ItemStateSnapshot` assembled from character-load traffic, with inventory, known balances, and observed town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) | Beta |
+| Arena of Solare leaderboards | A finite `SolareCaptureResult` containing overall rankings, class tables, and player statistics when the capture is complete | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) | Beta |
+
+These workflows include synchronous and
+[asyncio](https://ychwu.github.io/bdo-toolkit/#asyncio) sessions, capture and
+decoder health diagnostics, console and JSONL event writers, and a
+[command-line interface](https://ychwu.github.io/bdo-toolkit/#cli). Exact
+signatures, fields, lifecycle behavior, and failure contracts are in the
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index).
 
 Testing and validation cover **NA/EU only**. Compatibility with other regional
 services is unknown.
@@ -71,46 +82,12 @@ installed with the Python wheel.
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)
 for every script, its prerequisites, and the guide that explains it.
 
-## Documentation
-
-The documentation separates task-focused guides from the symbol-first API
-reference. Exact signatures, fields, lifecycle behavior, and failure contracts
-live there rather than in this README.
-
-| Goal | Start here |
-| --- | --- |
-| Understand the package | [Overview](https://ychwu.github.io/bdo-toolkit/#overview) |
-| Build with live item events | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Query character inventory and town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Rebuild item decoding after a patch | [Calibration](https://ychwu.github.io/bdo-toolkit/#calibration-workflow) |
-| Capture and query an Arena of Solare leaderboard | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
-| Integrate with an asyncio application | [Asyncio integration](https://ychwu.github.io/bdo-toolkit/#asyncio) |
-| Look up a class, function, or model | [API index](https://ychwu.github.io/bdo-toolkit/#api-index) |
-| Use the terminal interface | [Command line](https://ychwu.github.io/bdo-toolkit/#cli) |
-| Diagnose a problem | [Troubleshooting](https://ychwu.github.io/bdo-toolkit/#errors) |
-| Review data handling and project boundaries | [Safety & privacy](https://ychwu.github.io/bdo-toolkit/#stability) |
-
 ## Support
 
 For questions, contact me on Discord: `._.__.__._._.__._____.__._.___.`
 
 For bugs and feature requests, [open a GitHub issue](https://github.com/ychwu/bdo-toolkit/issues).
 
-## Development
-
-```powershell
-git clone https://github.com/ychwu/bdo-toolkit.git
-cd bdo-toolkit
-python -m pip install -e ".[dev]"
-python -m pytest -q -W error
-python -m mypy src/bdo_toolkit
-python -m pip wheel . --no-deps --wheel-dir dist
-```
-
-CI runs tests, type checking, wheel construction, and a CLI smoke test on
-Ubuntu and Windows with Python 3.14. Tests that require private
-game-session captures skip when those local fixtures are absent.
-
 ## License
 
 bdo-toolkit is available under the

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/src/bdo_toolkit/_reassembly.py

@@ -47,6 +47,7 @@ class TCPFlowState:
     scanner: StreamScanner
     max_pending_segments: int = MAX_PENDING_SEGMENTS
     max_pending_bytes: Optional[int] = None
+    defer_gap_timeouts: bool = False
     next_sequence: Optional[int] = None
     pending: dict[int, PendingSegment] = field(default_factory=dict)
     unanchored: dict[int, PendingSegment] = field(default_factory=dict)
@@ -280,7 +281,7 @@ class TCPFlowState:
                 # capture loss through the ordinary gap-reset accounting.
                 while self._pending_capacity_exceeded(self.pending):
                     self._resume_after_gap()
-            else:
+            elif not self.defer_gap_timeouts:
                 self.service_gaps(context.timestamp)
             return
 
@@ -411,6 +412,7 @@ class FlowManager:
         track_flow_generations: bool = False,
         max_pending_segments: int = MAX_PENDING_SEGMENTS,
         max_pending_bytes: Optional[int] = None,
+        defer_gap_timeouts: bool = False,
     ) -> None:
         if max_flows is not None and max_flows <= 0:
             raise ValueError("max_flows must be positive or None")
@@ -430,6 +432,8 @@ class FlowManager:
             raise TypeError("max_pending_bytes must be an integer or None")
         if max_pending_bytes is not None and max_pending_bytes <= 0:
             raise ValueError("max_pending_bytes must be positive or None")
+        if not isinstance(defer_gap_timeouts, bool):
+            raise TypeError("defer_gap_timeouts must be a boolean")
         self.server_ports = frozenset(server_ports)
         self._scanner_factory = scanner_factory
         self._max_flows = max_flows
@@ -440,6 +444,7 @@ class FlowManager:
         self._track_flow_generations = track_flow_generations
         self._max_pending_segments = max_pending_segments
         self._max_pending_bytes = max_pending_bytes
+        self._defer_gap_timeouts = defer_gap_timeouts
         self._next_flow_generation = 0
         self._flows: OrderedDict[FlowKey, TCPFlowState] = OrderedDict()
         self._tcp_gap_resets = 0
@@ -458,6 +463,7 @@ class FlowManager:
             scanner=self._scanner_factory(),
             max_pending_segments=self._max_pending_segments,
             max_pending_bytes=self._max_pending_bytes,
+            defer_gap_timeouts=self._defer_gap_timeouts,
             generation=generation,
             on_gap_reset=lambda resume_sequence: self._record_gap_reset(
                 flow,
@@ -484,13 +490,12 @@ class FlowManager:
             return self._tcp_gap_resets
 
     def service_gaps(self, now: float) -> int:
-        """Advance pending-gap timers using a caller-supplied wall clock.
+        """Advance pending-gap timers using a caller-supplied clock.
 
-        ``FlowManager`` does not own a timer thread. Live capture roots that
-        require wall-clock release should call this during their normal
-        poll/tick even when no packets arrived. The return value is the number
-        of new resets performed during this call; ``tcp_gap_resets`` is
-        cumulative.
+        ``FlowManager`` does not own a timer thread. Callers that defer
+        per-packet timeouts may invoke this at a lifecycle boundary they know
+        is safe. The return value is the number of new resets performed during
+        this call; ``tcp_gap_resets`` is cumulative.
         """
         with self._lock:
             before = self.tcp_gap_resets

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/src/bdo_toolkit/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the BDO Toolkit release version."""
 
-__version__ = "1.0.2"
+__version__ = "1.0.3"

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/src/bdo_toolkit/calibration.py

@@ -2354,9 +2354,29 @@ def _discover_source_container_decrement(
         )
 
         for quantity_offset in quantity_offsets:
-            # The current layout places context after instance; older layouts
-            # place it before instance. Both put context before the quantity.
+            # Known layouts vary whether context is before or after instance.
+            # Historical layouts put context before quantity. A newer layout
+            # puts quantity first, so admit a trailing context only when the
+            # same frame has one exact receipt-instance anchor; quantity and a
+            # context label alone are too weak.
             context_offset = _discover_context_offset(frame, quantity_offset)
+            if context_offset is None and exact_instance_offset is not None:
+                trailing_context_offset = (
+                    _discover_source_container_trailing_context_offset(
+                        frame,
+                        quantity_offset + 4,
+                    )
+                )
+                if (
+                    trailing_context_offset is not None
+                    and not _ranges_overlap(
+                        exact_instance_offset,
+                        8,
+                        trailing_context_offset,
+                        4,
+                    )
+                ):
+                    context_offset = trailing_context_offset
             if context_offset is None:
                 continue
             if exact_instance_offset is not None and _ranges_overlap(
@@ -2785,6 +2805,34 @@ def _discover_context_offset(frame: BDOFrame, before_offset: int) -> Optional[in
     return best_offset
 
 
+def _discover_source_container_trailing_context_offset(
+    frame: BDOFrame,
+    after_offset: int,
+) -> Optional[int]:
+    """Return one unique source context after a container quantity field.
+
+    This is deliberately narrower than ``_discover_context_offset``. The
+    caller requires an exact receipt-instance match before using this fallback,
+    and ambiguity among trailing context labels fails closed.
+    """
+
+    offsets: set[int] = set()
+    for context_bytes in SOURCE_CONTEXT_LABELS:
+        if (
+            context_bytes == CHARACTER_LOAD_CONTEXT
+            or context_bytes in STORAGE_DELTA_CONTEXTS
+        ):
+            continue
+        search_at = max(5, after_offset)
+        while True:
+            offset = frame.message.find(context_bytes, search_at)
+            if offset < 0:
+                break
+            offsets.add(offset)
+            search_at = offset + 1
+    return next(iter(offsets)) if len(offsets) == 1 else None
+
+
 def _discover_storage_context_offset(
     frame: BDOFrame,
     before_offset: int,

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/src/bdo_toolkit/solare/_live_tracker.py

@@ -291,12 +291,12 @@ class LiveSolareDiscoveryTracker:
         prefix rejection—remain authoritative at this boundary.
         """
 
+        last_candidate_activity_at = self._last_candidate_activity_at
         if (
             self.complete
             or self._tail_finalized
-            or self._last_candidate_activity_at is None
-            or now - self._last_candidate_activity_at
-            < LIVE_CANDIDATE_IDLE_SECONDS
+            or last_candidate_activity_at is None
+            or now < last_candidate_activity_at + LIVE_CANDIDATE_IDLE_SECONDS
         ):
             return False
         self.refresh()

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/src/bdo_toolkit/solare/_replay_capture.py

@@ -36,6 +36,7 @@ class SolareFrameCollector:
         on_traffic: Optional[Callable[[], None]] = None,
         *,
         retain_frames: bool = True,
+        defer_gap_timeouts: bool = False,
     ) -> None:
         self.ports = validate_server_ports(ports)
         self.frames: list[BDOFrame] = []
@@ -57,6 +58,7 @@ class SolareFrameCollector:
             max_flows=SOLARE_MAX_ACTIVE_FLOWS,
             max_pending_segments=SOLARE_MAX_PENDING_SEGMENTS,
             max_pending_bytes=SOLARE_MAX_PENDING_BYTES,
+            defer_gap_timeouts=defer_gap_timeouts,
             on_flow_eviction=self._count_flow_eviction,
             track_flow_generations=True,
         )

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/src/bdo_toolkit/solare/session.py

@@ -198,6 +198,7 @@ class LiveSolareSession:
                     on_frame=tracker.observe,
                     on_traffic=self._announce_traffic,
                     retain_frames=False,
+                    defer_gap_timeouts=True,
                 )
                 capture = LivePacketCapture(
                     capture_options=self._capture_options,
@@ -709,23 +710,15 @@ class LiveSolareSession:
             self._latch_confirmation()
 
     def _service_drained_clocks(self) -> None:
-        """Advance live-only clocks only after queued packet work is caught up.
+        """Advance candidate-idle time only after packet work is caught up.
 
-        Wall-clock TCP-gap recovery or candidate-tail closure while packets
-        remain queued could skip a delayed prefix or a later same-family
-        frame that Npcap already delivered. Waiting for an empty decode queue
-        preserves that evidence. The second check protects candidate
-        finalization from packets enqueued while gap service was running.
+        Live Solare deliberately does not perform timeout-based TCP gap
+        recovery while capture remains active. Native callback batching can
+        pause longer than the generic deadline even when the missing prefix is
+        still buffered. Reorder pressure remains bounded and immediate, and
+        finalization resolves any genuinely unfinished gap fail-closed.
         """
 
-        if not self._packet_queue.empty():
-            return
-
-        collector = self._collector
-        if collector is not None:
-            collector.service_gaps(time.time())
-            self._announce_tcp_gap_loss()
-
         if not self._packet_queue.empty():
             return
 

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3/src/bdo_toolkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.2
+Version: 1.0.3
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -28,6 +28,7 @@ Dynamic: license-file
 # bdo-toolkit
 
 [![CI](https://img.shields.io/github/actions/workflow/status/ychwu/bdo-toolkit/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/ychwu/bdo-toolkit/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/bdo-toolkit?style=flat-square&label=version)](https://pypi.org/project/bdo-toolkit/)
 [![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://github.com/ychwu/bdo-toolkit/blob/main/pyproject.toml)
 ![Tested on NA/EU](https://img.shields.io/badge/tested-NA%2FEU-5b61a8?style=flat-square)
 [![Package: Stable](https://img.shields.io/badge/package-stable-2f855a?style=flat-square)](https://ychwu.github.io/bdo-toolkit/#stability)
@@ -48,11 +49,21 @@ traffic into structured, application-ready data.
 
 ## Capabilities
 
-| In-game task | Python result | Status | Guide |
+bdo-toolkit exposes three passive workflows. Each can observe live traffic or
+replay a saved PCAP or PCAPNG file.
+
+| Capability | What it provides | Guide | Status |
 | --- | --- | --- | --- |
-| Watch supported item changes such as loot, gathering, and storage activity | A continuing stream of typed `BDOEvent` objects | Stable | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Log in or switch characters | One observational `ItemStateSnapshot` of inventory, known balances, and town storage | Beta | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Load the Arena of Solare Leaderboard | One `SolareCaptureResult`; a complete result contains a leaderboard snapshot | Beta | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
+| Item activity | A continuing stream of typed `BDOEvent` objects for supported loot, gathering, inventory, and storage changes | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) | Stable |
+| Inventory and town storage | A finite `ItemStateSnapshot` assembled from character-load traffic, with inventory, known balances, and observed town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) | Beta |
+| Arena of Solare leaderboards | A finite `SolareCaptureResult` containing overall rankings, class tables, and player statistics when the capture is complete | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) | Beta |
+
+These workflows include synchronous and
+[asyncio](https://ychwu.github.io/bdo-toolkit/#asyncio) sessions, capture and
+decoder health diagnostics, console and JSONL event writers, and a
+[command-line interface](https://ychwu.github.io/bdo-toolkit/#cli). Exact
+signatures, fields, lifecycle behavior, and failure contracts are in the
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index).
 
 Testing and validation cover **NA/EU only**. Compatibility with other regional
 services is unknown.
@@ -98,46 +109,12 @@ installed with the Python wheel.
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)
 for every script, its prerequisites, and the guide that explains it.
 
-## Documentation
-
-The documentation separates task-focused guides from the symbol-first API
-reference. Exact signatures, fields, lifecycle behavior, and failure contracts
-live there rather than in this README.
-
-| Goal | Start here |
-| --- | --- |
-| Understand the package | [Overview](https://ychwu.github.io/bdo-toolkit/#overview) |
-| Build with live item events | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Query character inventory and town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Rebuild item decoding after a patch | [Calibration](https://ychwu.github.io/bdo-toolkit/#calibration-workflow) |
-| Capture and query an Arena of Solare leaderboard | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
-| Integrate with an asyncio application | [Asyncio integration](https://ychwu.github.io/bdo-toolkit/#asyncio) |
-| Look up a class, function, or model | [API index](https://ychwu.github.io/bdo-toolkit/#api-index) |
-| Use the terminal interface | [Command line](https://ychwu.github.io/bdo-toolkit/#cli) |
-| Diagnose a problem | [Troubleshooting](https://ychwu.github.io/bdo-toolkit/#errors) |
-| Review data handling and project boundaries | [Safety & privacy](https://ychwu.github.io/bdo-toolkit/#stability) |
-
 ## Support
 
 For questions, contact me on Discord: `._.__.__._._.__._____.__._.___.`
 
 For bugs and feature requests, [open a GitHub issue](https://github.com/ychwu/bdo-toolkit/issues).
 
-## Development
-
-```powershell
-git clone https://github.com/ychwu/bdo-toolkit.git
-cd bdo-toolkit
-python -m pip install -e ".[dev]"
-python -m pytest -q -W error
-python -m mypy src/bdo_toolkit
-python -m pip wheel . --no-deps --wheel-dir dist
-```
-
-CI runs tests, type checking, wheel construction, and a CLI smoke test on
-Ubuntu and Windows with Python 3.14. Tests that require private
-game-session captures skip when those local fixtures are absent.
-
 ## License
 
 bdo-toolkit is available under the

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/tests/test_calibration.py

@@ -643,17 +643,18 @@ def test_one_session_1_4_deposits_and_5_withdrawal_keep_all_strides():
 
 
 @pytest.mark.parametrize(
-    ("layout", "expected_context", "expected_instance", "expected_quantity"),
+    ("layout", "expected_offsets"),
     [
-        ("current", 13, 5, 17),
-        ("legacy-different-instance", 7, 23, 32),
+        ("instance-context-quantity", (13, 5, 17)),
+        ("context-instance-quantity-different-instance", (7, 23, 32)),
+        ("quantity-instance-context", (34, 21, 5)),
+        ("trailing-context-without-exact-instance", None),
+        ("ambiguous-trailing-context", None),
     ],
 )
-def test_container_companion_discovers_both_known_field_orders(
+def test_container_companion_handles_known_field_orders_safely(
     layout,
-    expected_context,
-    expected_instance,
-    expected_quantity,
+    expected_offsets,
 ):
     from bdo_toolkit._protocol import BDOFrame, FlowKey, PacketContext
     from bdo_toolkit.calibration import (
@@ -679,17 +680,30 @@ def test_container_companion_discovers_both_known_field_orders(
     receipt_instance = bytes.fromhex("1122334455667788")
     source_context = bytes.fromhex("d0f205a3")
 
-    if layout == "current":
+    if layout == "instance-context-quantity":
         companion_message = bytearray(42)
         companion_message[5:13] = receipt_instance
         companion_message[13:17] = source_context
         companion_message[17:21] = quantity.to_bytes(4, "little")
-    else:
+    elif layout == "context-instance-quantity-different-instance":
         companion_message = bytearray(40)
         companion_message[7:11] = source_context
         companion_message[23:31] = bytes.fromhex("0102030405060708")
         companion_message[31] = 0x02
         companion_message[32:36] = quantity.to_bytes(4, "little")
+    else:
+        companion_message = bytearray(
+            48 if layout == "ambiguous-trailing-context" else 40
+        )
+        companion_message[5:9] = quantity.to_bytes(4, "little")
+        companion_message[21:29] = (
+            bytes.fromhex("0102030405060708")
+            if layout == "trailing-context-without-exact-instance"
+            else receipt_instance
+        )
+        companion_message[34:38] = source_context
+        if layout == "ambiguous-trailing-context":
+            companion_message[40:44] = bytes.fromhex("0471ee0e")
     companion = frame(0, 0xBEEF, companion_message)
 
     receipt_frame = frame(1, 0xCAFE, bytearray(80))
@@ -709,6 +723,11 @@ def test_container_companion_discovers_both_known_field_orders(
         [companion, receipt_frame], receipt, options
     )
 
+    if expected_offsets is None:
+        assert spec is None
+        return
+
+    expected_context, expected_instance, expected_quantity = expected_offsets
     assert spec is not None
     assert (spec.opcode, spec.length) == (0xBEEF, len(companion_message))
     assert spec.context_offset == expected_context

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/tests/test_character_state.py

@@ -99,7 +99,7 @@ def test_july17_character_state_report_recovers_inventory_and_storage():
         container.confidence == "provisional"
         for container in state.inventory.containers
     )
-    assert state.inventory.currency("Silver").quantity == 1_832_291_219
+    assert state.inventory.currency("Silver").quantity == 637_487_451_027
     assert state.inventory.currency(6).quantity == 363
     assert state.inventory.currency("Loyalties").quantity == 17_600
     assert state.inventory.currency(10).quantity == 105_742
@@ -137,7 +137,7 @@ def test_july17_character_state_report_recovers_inventory_and_storage():
     assert "capacity: unavailable" in output
     assert "Main Inventory [0x00, provisional]: 74 item stacks" in output
     assert "2 empty wrappers: unclassified" in output
-    assert "Silver: 1,832,291,219" in output
+    assert "Silver: 637,487,451,027" in output
     assert "/192" not in output
     assert "initial login vs character switch" in output
 
@@ -223,7 +223,7 @@ def test_july17_character_switch_classifies_exact_inventory_state():
         )
         for balance in inventory.currency_balances
     } == {
-        1: ("Silver", 1_832_291_219, 3, 0x18),
+        1: ("Silver", 637_487_451_027, 3, 0x18),
         6: ("Pearl", 363, 0, 0x10),
         7: ("Loyalties", 17_900, 1, 0x10),
         10: ("Crow Coin", 105_742, 0, 0x18),

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/tests/test_reassembly.py

@@ -371,6 +371,69 @@ def test_wall_clock_service_releases_complete_frame_behind_idle_gap():
     assert manager.tcp_gap_resets == 1
 
 
+def test_deferred_live_gap_timeout_does_not_skip_a_queued_prefix():
+    scanner = _RecordingScanner()
+    manager = FlowManager(
+        server_ports=(8889,),
+        scanner_factory=lambda: scanner,
+        defer_gap_timeouts=True,
+    )
+
+    _segment(
+        manager,
+        sequence=99,
+        timestamp=100.0,
+        syn=True,
+    )
+    _segment(
+        manager,
+        sequence=100,
+        payload=b"a",
+        timestamp=100.0,
+    )
+    _segment(
+        manager,
+        sequence=102,
+        payload=b"c",
+        timestamp=100.1,
+    )
+    # Processing a later queued packet after the deadline must not recover the
+    # gap before its already-queued prefix gets a chance to run.
+    _segment(
+        manager,
+        sequence=103,
+        payload=b"d",
+        timestamp=102.0,
+    )
+    _segment(
+        manager,
+        sequence=101,
+        payload=b"b",
+        timestamp=102.1,
+    )
+
+    assert b"".join(scanner.feeds) == b"abcd"
+    assert scanner.resets == 0
+    assert manager.tcp_gap_resets == 0
+
+
+def test_deferred_live_gap_timeout_still_resets_after_explicit_service():
+    scanner = _RecordingScanner()
+    manager = FlowManager(
+        server_ports=(8889,),
+        scanner_factory=lambda: scanner,
+        defer_gap_timeouts=True,
+    )
+
+    _segment(manager, sequence=99, timestamp=100.0, syn=True)
+    _segment(manager, sequence=100, payload=b"a", timestamp=100.0)
+    _segment(manager, sequence=102, payload=b"c", timestamp=100.1)
+
+    assert manager.service_gaps(100.1 + GAP_RESET_SECONDS) == 1
+    assert b"".join(scanner.feeds) == b"ac"
+    assert manager.tcp_gap_resets == 1
+
+
 @pytest.mark.parametrize("syn_sequence", [1000, 0xFFFFFFF8])
 def test_empty_syn_anchor_reassembles_second_half_first_and_deduplicates(
     syn_sequence: int,

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/tests/test_solare_replay.py

@@ -884,7 +884,10 @@ def test_candidate_idle_closes_overall_tail_amid_unrelated_traffic() -> None:
     # the global packet queue busy.
     assert not tracker.complete
     assert tracker._last_candidate_activity_at is not None
-    last_candidate = tracker._last_candidate_activity_at
+    # This monotonic-clock value reproduces a Linux float boundary where
+    # ``(last_candidate + 1.5) - last_candidate`` rounds just below 1.5.
+    last_candidate = 63.021708486
+    tracker._last_candidate_activity_at = last_candidate
     assert not tracker.service_candidate_idle(
         last_candidate + LIVE_CANDIDATE_IDLE_SECONDS - 0.001
     )

{bdo_toolkit-1.0.2 → bdo_toolkit-1.0.3}/tests/test_solare_session.py

@@ -598,16 +598,7 @@ def test_live_session_auto_stops_when_candidate_idle_confirms_final_window(
     assert session.stop_reason == "complete-snapshot"
 
 
-def test_drained_clock_service_waits_for_decoder_backlog() -> None:
-    class RecordingCollector:
-        def __init__(self) -> None:
-            self.service_calls = 0
-            self.tcp_gap_resets = 0
-
-        def service_gaps(self, _now: float) -> int:
-            self.service_calls += 1
-            return 0
-
+def test_drained_candidate_clock_waits_for_decoder_backlog() -> None:
     class RecordingTracker:
         complete = False
 
@@ -619,29 +610,26 @@ def test_drained_clock_service_waits_for_decoder_backlog() -> None:
             return False
 
     session = LiveSolareSession()
-    collector = RecordingCollector()
     tracker = RecordingTracker()
-    session._collector = collector  # type: ignore[assignment]
     session._tracker = tracker  # type: ignore[assignment]
     session._packet_queue.put_nowait(object())
 
     session._service_drained_clocks()
 
-    assert collector.service_calls == 0
     assert tracker.service_calls == 0
 
     session._packet_queue.get_nowait()
     session._service_drained_clocks()
 
-    assert collector.service_calls == 1
     assert tracker.service_calls == 1
 
 
-def test_drained_clock_services_quiet_tcp_gap_and_warns_fail_closed(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
+def test_live_clock_leaves_quiet_tcp_gap_for_finalization() -> None:
     session = LiveSolareSession()
-    collector = session_module.SolareFrameCollector((8889,))
+    collector = session_module.SolareFrameCollector(
+        (8889,),
+        defer_gap_timeouts=True,
+    )
     session._collector = collector
 
     collector.process_tcp_segment(
@@ -663,14 +651,14 @@ def test_drained_clock_services_quiet_tcp_gap_and_warns_fail_closed(
         payload=b"x",
         timestamp=100.1,
     )
-    monkeypatch.setattr(session_module.time, "time", lambda: 102.0)
-
     session._service_drained_clocks()
 
+    assert collector.tcp_gap_resets == 0
+    assert session._update_queue.empty()
+
+    collector.finish()
+
     assert collector.tcp_gap_resets == 1
-    warning = session._update_queue.get_nowait()
-    assert warning.kind is SolareUpdateKind.WARNING
-    assert "remain fail-closed" in warning.message
 
 
 def test_live_session_refuses_to_overwrite_existing_capture(