bdo-toolkit 1.0.5__tar.gz → 1.0.7__tar.gz

{bdo_toolkit-1.0.5/src/bdo_toolkit.egg-info → bdo_toolkit-1.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.5
+Version: 1.0.7
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -37,10 +37,10 @@ Dynamic: license-file
 Passive, read-only Python tooling that turns live or recorded Black Desert
 traffic into structured, application-ready data.
 
-[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
-[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
-[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
-[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
+[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
+[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
+[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
 [Report an issue](https://github.com/ychwu/bdo-toolkit/issues)
 
 > **Passive, read-only boundary.** bdo-toolkit observes local traffic or saved
@@ -60,16 +60,18 @@ no usable adapter is found. Discovery does not apply settings or verify decoding
 
 ## Capabilities
 
-bdo-toolkit exposes three passive workflows. Each can observe live traffic or
-replay a saved PCAP or PCAPNG file.
+bdo-toolkit exposes four passive workflows. Item activity, item state, and
+Solare support live capture and saved PCAP or PCAPNG replay. Grind tracking
+combines supported observations in one live session.
 
 | Capability | What it provides | Guide | Status |
 | --- | --- | --- | --- |
 | 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 |
+| Grind tracking | One capture for confirmed mob drops, with optional profile-based Agris and solo XP | [GrindSession](https://ychwu.github.io/bdo-toolkit/#grind-session) | Experimental |
 
-These workflows include synchronous and
+The standalone 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
@@ -115,7 +117,7 @@ installed with the Python wheel.
 | Observe live item activity | [`examples/live_transfer_log.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_transfer_log.py) |
 | Capture inventory and town storage on character load | [`examples/live_character_load_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_character_load_snapshot.py) |
 | Rebuild an item profile after a patch | [`examples/live_calibrate_profile.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibrate_profile.py) |
-| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
+| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
 | Capture an Arena of Solare leaderboard load | [`examples/solare_live_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/solare_live_snapshot.py) |
 
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)

{bdo_toolkit-1.0.5 → bdo_toolkit-1.0.7}/README.md

@@ -10,10 +10,10 @@
 Passive, read-only Python tooling that turns live or recorded Black Desert
 traffic into structured, application-ready data.
 
-[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
-[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
-[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
-[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
+[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
+[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
+[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
 [Report an issue](https://github.com/ychwu/bdo-toolkit/issues)
 
 > **Passive, read-only boundary.** bdo-toolkit observes local traffic or saved
@@ -33,16 +33,18 @@ no usable adapter is found. Discovery does not apply settings or verify decoding
 
 ## Capabilities
 
-bdo-toolkit exposes three passive workflows. Each can observe live traffic or
-replay a saved PCAP or PCAPNG file.
+bdo-toolkit exposes four passive workflows. Item activity, item state, and
+Solare support live capture and saved PCAP or PCAPNG replay. Grind tracking
+combines supported observations in one live session.
 
 | Capability | What it provides | Guide | Status |
 | --- | --- | --- | --- |
 | 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 |
+| Grind tracking | One capture for confirmed mob drops, with optional profile-based Agris and solo XP | [GrindSession](https://ychwu.github.io/bdo-toolkit/#grind-session) | Experimental |
 
-These workflows include synchronous and
+The standalone 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
@@ -88,7 +90,7 @@ installed with the Python wheel.
 | Observe live item activity | [`examples/live_transfer_log.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_transfer_log.py) |
 | Capture inventory and town storage on character load | [`examples/live_character_load_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_character_load_snapshot.py) |
 | Rebuild an item profile after a patch | [`examples/live_calibrate_profile.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibrate_profile.py) |
-| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
+| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
 | Capture an Arena of Solare leaderboard load | [`examples/solare_live_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/solare_live_snapshot.py) |
 
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)

{bdo_toolkit-1.0.5 → bdo_toolkit-1.0.7}/src/bdo_toolkit/__init__.py

@@ -41,7 +41,7 @@ from .origin_learning import (
     promote_origin_candidates,
 )
 from .writers import ConsoleEventWriter, JsonlEventWriter
-from . import solare
+from . import agris, grind, solare, xp
 from ._version import __version__
 
 __all__ = [
@@ -83,10 +83,13 @@ __all__ = [
     "StorageLocation",
     "__version__",
     "capture_live",
+    "agris",
+    "grind",
     "fetch_opcode_profile",
     "load_opcode_profile",
     "promote_origin_candidates",
     "replay_pcap",
     "storage_location",
     "solare",
+    "xp",
 ]

{bdo_toolkit-1.0.5 → bdo_toolkit-1.0.7}/src/bdo_toolkit/_calibration/_records.py

@@ -508,10 +508,45 @@ def _discover_storage_context_offset(
         before_offset=before_offset,
     )
     if len(candidates) == 1:
-        return candidates[0][0]
+        offset = candidates[0][0]
+        if _storage_candidate_aliases_batch_count(frame, before_offset, offset):
+            return None
+        return offset
     return None
 
 
+def _storage_candidate_aliases_batch_count(
+    frame: BDOFrame, item_offset: int, destination_offset: int,
+) -> bool:
+    """A batch count cannot also provide independent destination evidence.
+
+    Require complete, uniformly spaced records and a plausible normalized
+    envelope. This only discounts a single-frame town candidate when every
+    geometrically possible count column overlaps it. A separate count column
+    preserves the destination signal (and any intrinsic direction conflict).
+    Cross-frame destination/count authority is deliberately unchanged.
+    """
+    if frame.length != len(frame.message):
+        return False
+    offsets = _full_transfer_record_offsets(frame, item_offset, item_offset + 35)
+    stride = uniform_stride(offsets) if len(offsets) > 1 else None
+    if stride is None or item_offset not in offsets:
+        return False
+    count = len(offsets)
+    base_length = frame.length - (count - 1) * stride
+    prefix_length = frame.length - count * stride
+    if not (200 <= base_length <= 300 and 5 <= prefix_length <= offsets[0]):
+        return False
+    count_offsets = [
+        offset for offset in range(5, prefix_length - 1)
+        if int.from_bytes(frame.message[offset:offset + 2], "little") == count
+    ]
+    return bool(count_offsets) and all(
+        _ranges_overlap(offset, 2, destination_offset, 4)
+        for offset in count_offsets
+    )
+
+
 def _discover_storage_context_offset_from_frames(
     frames: Iterable[BDOFrame],
     *,

{bdo_toolkit-1.0.5 → bdo_toolkit-1.0.7}/src/bdo_toolkit/_engine.py

@@ -41,16 +41,20 @@ class _TeeScanner:
         primary: TargetMessageScanner,
         tap: Optional[FrameCollectorScanner],
         stream_observer: Optional[Callable[[bytes, PacketContext], None]],
+        unhinted_tap: Optional[FrameCollectorScanner] = None,
     ) -> None:
         self._primary = primary
         self._tap = tap
         self._stream_observer = stream_observer
+        self._unhinted_tap = unhinted_tap
 
     def feed(self, data, context) -> None:
         if self._stream_observer is not None:
             self._stream_observer(data, context)
         if self._tap is not None:
             self._tap.feed(data, context)
+        if self._unhinted_tap is not None:
+            self._unhinted_tap.feed(data, context)
         self._primary.feed(data, context)
 
     def scan_standalone(self, data, context) -> None:
@@ -58,6 +62,8 @@ class _TeeScanner:
             self._stream_observer(data, context)
         if self._tap is not None:
             self._tap.scan_standalone(data, context)
+        if self._unhinted_tap is not None:
+            self._unhinted_tap.scan_standalone(data, context)
         self._primary.scan_standalone(data, context)
 
     def can_anchor_at_start(self, data: bytes) -> bool:
@@ -69,6 +75,8 @@ class _TeeScanner:
     def reset(self) -> None:
         if self._tap is not None:
             self._tap.reset()
+        if self._unhinted_tap is not None:
+            self._unhinted_tap.reset()
         self._primary.reset()
 
 
@@ -189,6 +197,8 @@ class PacketEngine:
         message_observer: Optional[MessageObserver] = None,
         max_pending_segments: int = MAX_PENDING_SEGMENTS,
         max_pending_bytes: Optional[int] = None,
+        defer_gap_timeouts: bool = False,
+        unhinted_frame_observer: Optional[Callable[[BDOFrame], None]] = None,
     ) -> None:
         self.event_specs = tuple(event_specs)
         self.events_found = 0
@@ -203,7 +213,7 @@ class PacketEngine:
                 self.event_specs,
                 message_observer=message_observer,
             )
-            if frame_observer is None and stream_observer is None:
+            if frame_observer is None and stream_observer is None and unhinted_frame_observer is None:
                 return primary
             tap = (
                 FrameCollectorScanner(
@@ -213,7 +223,12 @@ class PacketEngine:
                 if frame_observer is not None
                 else None
             )
-            return _TeeScanner(primary, tap, stream_observer)
+            # Optional telemetry must keep its standalone synchronization
+            # authority. Item opcode hints are only for the existing item tap;
+            # accidental headers in a midstream prefix must not steer XP/Agris.
+            unhinted_tap = (FrameCollectorScanner(unhinted_frame_observer)
+                            if unhinted_frame_observer is not None else None)
+            return _TeeScanner(primary, tap, stream_observer, unhinted_tap)
 
         self._flow_manager = FlowManager(
             server_ports=server_ports,
@@ -226,6 +241,7 @@ class PacketEngine:
             idle_timeout=_ITEM_FLOW_IDLE_SECONDS,
             max_pending_segments=max_pending_segments,
             max_pending_bytes=max_pending_bytes,
+            defer_gap_timeouts=defer_gap_timeouts,
         )
         self._seen_event_keys: set[
             tuple[FlowKey, int, int, int, Optional[int], bytes]

{bdo_toolkit-1.0.5 → bdo_toolkit-1.0.7}/src/bdo_toolkit/_item_state/inventory.py

@@ -185,17 +185,17 @@ def _discover_inventory_tail_layout(
             observed_codes: set[int] = set()
             valid = True
             for frame, group, _, _ in frame_groups:
-                codes = {
+                codes = [
                     frame.message[int(event.record_offset) + container_relative]
                     for event in group
                     if event.record_offset is not None
                     and int(event.record_offset) + container_relative
                     < len(frame.message)
-                }
-                if len(codes) != 1:
+                ]
+                if len(codes) != len(group) or len(set(codes)) != 1:
                     valid = False
                     break
-                code = next(iter(codes))
+                code = codes[0]
                 if code not in _INVENTORY_CONTAINER_LABELS:
                     valid = False
                     break

bdo_toolkit-1.0.7/src/bdo_toolkit/_observation_session.py

@@ -0,0 +1,376 @@
+"""Private bounded observation-session lifecycle shared by Agris and solo XP."""
+from __future__ import annotations
+
+from collections.abc import Iterator
+import math
+from pathlib import Path
+from queue import Empty, Full, Queue
+from threading import Event, Lock, Thread, current_thread
+import time
+from types import TracebackType
+from typing import Any, Callable, Protocol, Self
+
+from ._capture_options import LiveCaptureOptions
+from ._capture_runtime import CaptureEndpoint, CaptureStats, LivePacketCapture, _attach_cleanup_owner
+from ._capture_backend import SegmentConsumer
+from .capture import CaptureIntegrityError
+
+
+class ObservationManager(SegmentConsumer, Protocol):
+    @property
+    def tcp_gap_resets(self) -> int: ...
+
+    def service_gaps(self, now: float) -> int: ...
+
+
+class ObservationSession[T, S]:
+    """Single owner for acquisition, bounded delivery, deadlines and cleanup.
+
+    Domains own their decoder, status/health view and clean-stop result policy.
+    Factories are explicit so existing domain test seams remain unchanged.
+    """
+
+    _JOIN_TIMEOUT = 15.0
+    _START_TIMEOUT = 15.0
+
+    def __init__(self, *, label: str, snapshot: Callable[[], S],
+                 manager: ObservationManager, refresh: Callable[[float | None], None],
+                 live_options: LiveCaptureOptions | None,
+                 capture_seconds: float | None, save_pcap: str | Path | None,
+                 capture_factory: Callable[..., LivePacketCapture],
+                 handler_factory: Callable[..., Callable[[object], None]],
+                 writer_factory: Callable[..., Any]) -> None:
+        if live_options is not None and not isinstance(live_options, LiveCaptureOptions):
+            raise TypeError("live_options must be LiveCaptureOptions or None")
+        if capture_seconds is not None and (isinstance(capture_seconds, bool)
+                or not isinstance(capture_seconds, (float, int))
+                or not math.isfinite(capture_seconds) or capture_seconds <= 0):
+            raise ValueError("capture_seconds must be finite and positive")
+        self._options = live_options or LiveCaptureOptions()
+        self._label, self._snapshot, self._refresh = label, snapshot, refresh
+        self._capture_factory, self._handler_factory, self._writer_factory = capture_factory, handler_factory, writer_factory
+        self._events: Queue[T] = Queue(self._options.event_queue_size)
+        self._packets: Queue[object] = Queue(self._options.packet_queue_size)
+        self._manager = manager
+        self._status = snapshot()
+        self._seconds = capture_seconds
+        self._save_path = Path(save_pcap).expanduser().resolve() if save_pcap is not None else None
+        if self._save_path is not None and self._save_path.suffix.lower() not in {".pcap", ".pcapng"}:
+            raise ValueError("save_pcap must end in .pcap or .pcapng")
+        self._state_lock = Lock()
+        self._lifecycle_lock = Lock()
+        self._consumer_lock = Lock()
+        self._stop_requested = Event()
+        self._ready = Event()
+        self._worker_done = Event()
+        self._stopped = Event()
+        self._worker: Thread | None = None
+        self._capture: LivePacketCapture | None = None
+        self._capture_started = False
+        self._start_attempted = False
+        self._cleanup_incomplete = False
+        self._handler: Callable[[object], None] | None = None
+        self._writer: Any = None
+        self._stats = CaptureStats()
+        self._error: BaseException | None = None
+        self._stop_reason: str | None = None
+        self._accepted = self._processed = self._packet_overflows = self._event_overflows = 0
+
+    def _on_clean_stop(self) -> None:
+        pass
+
+    @property
+    def endpoint(self) -> CaptureEndpoint | None:
+        return self._capture.endpoint if self._capture is not None else None
+
+    @property
+    def running(self) -> bool:
+        return self._ready.is_set() and not self._worker_done.is_set() and self.error is None
+
+    @property
+    def stopped(self) -> bool:
+        return self._stopped.is_set()
+
+    @property
+    def cleanup_incomplete(self) -> bool:
+        with self._state_lock:
+            return self._cleanup_incomplete
+
+    @property
+    def error(self) -> BaseException | None:
+        with self._state_lock:
+            return self._error
+
+    @property
+    def stop_reason(self) -> str | None:
+        with self._state_lock:
+            return self._stop_reason
+
+    def _record_error(self, error: BaseException) -> None:
+        with self._state_lock:
+            if self._error is None:
+                self._error = error
+            self._stop_reason = "error"
+        self._stop_requested.set()
+
+    def raise_if_failed(self) -> None:
+        error = self.error
+        if error is not None:
+            raise error
+
+    def _accept(self, packet: object) -> None:
+        if self._stop_requested.is_set():
+            return
+        try:
+            self._packets.put_nowait(packet)
+        except Full:
+            with self._state_lock:
+                self._packet_overflows += 1
+            error = CaptureIntegrityError(f"{self._label} packet queue overflow; capture incomplete")
+            self._record_error(error)
+            raise error
+        with self._state_lock:
+            self._accepted += 1
+
+    def _publish(self, balance: T) -> None:
+        try:
+            self._events.put_nowait(balance)
+        except Full as exc:
+            with self._state_lock:
+                self._event_overflows += 1
+            raise CaptureIntegrityError(f"{self._label} balance queue overflow; consumer too slow") from exc
+
+    def _update_status(self) -> None:
+        status = self._snapshot()
+        with self._state_lock:
+            self._status = status
+
+    def _read_stats(self, *, final: bool = False) -> None:
+        capture = self._capture
+        if capture is None:
+            return
+        stats = capture.stats if final else capture.snapshot_stats()
+        with self._state_lock:
+            self._stats = stats
+        if (stats.dropped or 0) > 0 or (stats.interface_dropped or 0) > 0:
+            raise CaptureIntegrityError(f"{self._label} capture backend reported dropped packets")
+
+    def start(self) -> None:
+        with self._lifecycle_lock:
+            if self._start_attempted:
+                raise RuntimeError(f"{self._label} sessions are single-use")
+            self._start_attempted = True
+            worker = Thread(target=self._run, name=f"bdo-toolkit-{self._label.lower()}", daemon=True)
+            self._worker = worker
+            try:
+                worker.start()
+            except BaseException as exc:
+                self._record_error(exc)
+                self._worker_done.set()
+                self._stopped.set()
+                raise
+        try:
+            if not self._ready.wait(self._START_TIMEOUT):
+                raise TimeoutError(f"{self._label} capture startup did not become ready")
+            self.raise_if_failed()
+        except BaseException as primary:
+            self._record_error(primary)
+            self._stop_requested.set()
+            try:
+                self.stop()
+            except BaseException as cleanup:
+                if cleanup is not primary:
+                    primary.add_note(f"{self._label} startup cleanup also failed: {cleanup!r}")
+            if self.cleanup_incomplete:
+                _attach_cleanup_owner(primary, self, context=f"{self._label} startup")
+            raise
+
+    def _process(self, packet: object) -> None:
+        if self._writer is not None:
+            self._writer.write(packet)
+        # Keep raw accepted packets even when an earlier loss invalidated decode.
+        if self.error is None:
+            assert self._handler is not None
+            self._handler(packet)
+            self._refresh(None)
+            self._update_status()
+        with self._state_lock:
+            self._processed += 1
+
+    def _run(self) -> None:
+        try:
+            if self._save_path is not None:
+                if self._save_path.exists():
+                    raise FileExistsError(f"refusing to overwrite existing capture: {self._save_path}")
+                self._save_path.parent.mkdir(parents=True, exist_ok=True)
+                self._writer = self._writer_factory(self._save_path)
+            self._handler = self._handler_factory(self._manager)
+            self._capture = self._capture_factory(capture_options=self._options, on_packet=self._accept)
+            self._capture.start()
+            self._capture_started = True
+            self._capture.raise_if_failed()
+            self._ready.set()
+            deadline = time.monotonic() + self._seconds if self._seconds is not None else None
+            next_stats = 0.0
+            while not self._stop_requested.is_set():
+                self._capture.raise_if_failed()
+                if not self._capture.running:
+                    raise CaptureIntegrityError(f"{self._label} capture backend stopped unexpectedly")
+                if deadline is not None and time.monotonic() >= deadline:
+                    with self._state_lock:
+                        self._stop_reason = "duration"
+                    break
+                if time.monotonic() >= next_stats:
+                    self._read_stats()
+                    next_stats = time.monotonic() + 1.0
+                try:
+                    packet = self._packets.get(timeout=0.05)
+                except Empty:
+                    # No dequeued packet is outstanding here. A queued backlog
+                    # must never be treated as a wall-clock TCP gap.
+                    if self._packets.empty():
+                        now = time.time()
+                        self._manager.service_gaps(now)
+                        self._refresh(now)
+                        self._update_status()
+                else:
+                    self._process(packet)
+        except BaseException as exc:
+            self._record_error(exc)
+        finally:
+            self._stop_requested.set()
+            try:
+                self._shutdown()
+            except BaseException as exc:
+                self._record_error(exc)
+            self._ready.set()  # Unblocks failed startup with its original error.
+            self._worker_done.set()
+
+    def _shutdown(self) -> None:
+        capture = self._capture
+        if capture is not None:
+            try:
+                if not capture.stopped and (self._capture_started or capture.cleanup_incomplete):
+                    capture.stop()
+                capture.raise_if_failed()
+            except BaseException as exc:
+                self._record_error(exc)
+            incomplete = capture.cleanup_incomplete or (self._capture_started and not capture.stopped)
+            if incomplete:
+                with self._state_lock:
+                    self._cleanup_incomplete = True
+                self._record_error(RuntimeError(f"{self._label} native cleanup is incomplete; retry stop()"))
+                return
+            try:
+                self._read_stats(final=True)
+            except BaseException as exc:
+                self._record_error(exc)
+        while True:
+            try:
+                packet = self._packets.get_nowait()
+            except Empty:
+                break
+            try:
+                self._process(packet)
+            except BaseException as exc:
+                self._record_error(exc)
+        if self.error is None:
+            try:
+                self._manager.finish()
+            except BaseException as exc:
+                self._record_error(exc)
+        self._update_status()
+        if self._writer is not None:
+            try:
+                self._writer.close()
+            except BaseException as exc:
+                self._record_error(exc)
+                with self._state_lock:
+                    self._cleanup_incomplete = True
+                return
+            self._writer = None
+        with self._state_lock:
+            self._cleanup_incomplete = False
+            self._stop_reason = self._stop_reason or "requested"
+        if self.error is None:
+            self._on_clean_stop()
+        self._stopped.set()
+
+    def stop(self) -> None:
+        if not self._start_attempted:
+            raise RuntimeError(f"{self._label} session was not started")
+        if self._worker is current_thread():
+            raise RuntimeError(f"{self._label} stop() cannot join its decoder thread")
+        self._stop_requested.set()
+        with self._lifecycle_lock:
+            worker = self._worker
+            if worker is not None and worker.is_alive():
+                worker.join(self._JOIN_TIMEOUT)
+            if worker is not None and worker.is_alive():
+                with self._state_lock:
+                    self._cleanup_incomplete = True
+                self._record_error(RuntimeError(f"{self._label} decoder cleanup timed out; retry stop()"))
+            elif self.cleanup_incomplete:
+                self._shutdown()
+            error = self.error
+            if error is not None:
+                if self.cleanup_incomplete:
+                    _attach_cleanup_owner(error, self, context=f"{self._label} stop")
+                raise error
+
+    def poll(self, timeout: float | None = None) -> T | None:
+        if timeout is not None and (isinstance(timeout, bool) or not isinstance(timeout, (float, int))
+                                    or not math.isfinite(timeout) or timeout < 0):
+            raise ValueError("timeout must be finite and nonnegative")
+        if not self._start_attempted:
+            raise RuntimeError(f"{self._label} session was not started")
+        if not self._consumer_lock.acquire(blocking=False):
+            raise RuntimeError(f"{self._label} sessions support one balance consumer")
+        try:
+            deadline = None if timeout is None else time.monotonic() + timeout
+            while True:
+                self.raise_if_failed()
+                try:
+                    balance = self._events.get_nowait()
+                except Empty:
+                    pass
+                else:
+                    self.raise_if_failed()
+                    return balance
+                if self.stopped:
+                    return None
+                remaining = None if deadline is None else deadline - time.monotonic()
+                if remaining is not None and remaining <= 0:
+                    return None
+                try:
+                    balance = self._events.get(timeout=min(0.05, remaining) if remaining is not None else 0.05)
+                except Empty:
+                    pass
+                else:
+                    self.raise_if_failed()
+                    return balance
+        finally:
+            self._consumer_lock.release()
+
+    def events(self) -> Iterator[T]:
+        while True:
+            balance = self.poll()
+            if balance is not None:
+                yield balance
+            elif self.stopped:
+                return
+
+    def __enter__(self) -> Self:
+        self.start()
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc_value: BaseException | None,
+                 traceback: TracebackType | None) -> None:
+        try:
+            self.stop()
+        except BaseException as cleanup:
+            if exc_value is None:
+                raise
+            if self.cleanup_incomplete:
+                _attach_cleanup_owner(exc_value, self, context=f"{self._label} context")
+            exc_value.add_note(f"{self._label} context cleanup also failed: {cleanup!r}")

{bdo_toolkit-1.0.5 → bdo_toolkit-1.0.7}/src/bdo_toolkit/_profile_runtime.py

@@ -14,6 +14,8 @@ from .profiles import (
     OpcodeProfile,
     OriginCompanionFamily,
     ProfileError,
+    AgrisProfileLayout,
+    XPProfileLayout,
 )
 
 
@@ -39,6 +41,14 @@ def validate_runtime_profile(profile: OpcodeProfile) -> RuntimeProfileValidation
         )
     if profile.active is not True:
         raise ProfileError(f"Opcode profile is inactive: {profile.path}")
+    if profile.xp is not None:
+        if not isinstance(profile.xp, XPProfileLayout):
+            raise ProfileError("xp must be an XPProfileLayout")
+        profile.xp.__post_init__()
+    if profile.agris is not None:
+        if not isinstance(profile.agris, AgrisProfileLayout):
+            raise ProfileError("agris must be an AgrisProfileLayout")
+        profile.agris.__post_init__()
 
     loaded_specs = event_specs_from_profile(profile)
     decrement_specs = tuple(