bdo-toolkit 1.0.4__tar.gz → 1.0.6__tar.gz

{bdo_toolkit-1.0.4/src/bdo_toolkit.egg-info → bdo_toolkit-1.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.4
+Version: 1.0.6
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -47,6 +47,17 @@ traffic into structured, application-ready data.
 > captures. It does not send or modify packets, replay traffic to the game,
 > automate gameplay, inspect process memory, or bypass anti-cheat software.
 
+## Live-capture limitations
+
+Live capture depends heavily on your network setup and on whether the capture
+backend can see BDO traffic. VPNs and routing services such as ExitLag may require
+manual interface, local IP, and port settings; automatic detection may select the
+wrong connection. Traffic visible only as an encrypted tunnel cannot be decoded.
+Follow [Diagnose capture when automatic selection fails](https://ychwu.github.io/bdo-toolkit/#capture-foundation/diagnose-network)
+to inspect connections on Windows, select grouped capture settings, and verify
+them with game activity. The guide covers VPNs, local proxies, and cases where
+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

{bdo_toolkit-1.0.4 → bdo_toolkit-1.0.6}/README.md

@@ -20,6 +20,17 @@ traffic into structured, application-ready data.
 > captures. It does not send or modify packets, replay traffic to the game,
 > automate gameplay, inspect process memory, or bypass anti-cheat software.
 
+## Live-capture limitations
+
+Live capture depends heavily on your network setup and on whether the capture
+backend can see BDO traffic. VPNs and routing services such as ExitLag may require
+manual interface, local IP, and port settings; automatic detection may select the
+wrong connection. Traffic visible only as an encrypted tunnel cannot be decoded.
+Follow [Diagnose capture when automatic selection fails](https://ychwu.github.io/bdo-toolkit/#capture-foundation/diagnose-network)
+to inspect connections on Windows, select grouped capture settings, and verify
+them with game activity. The guide covers VPNs, local proxies, and cases where
+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

{bdo_toolkit-1.0.4 → bdo_toolkit-1.0.6}/src/bdo_toolkit/__init__.py

@@ -3,6 +3,7 @@
 from ._async_sessions import AsyncCalibrationSession, AsyncLiveCaptureSession
 from ._capture_options import LiveCaptureOptions, PacketCaptureOptions
 from ._capture_runtime import CaptureEndpoint
+from .capture_diagnosis import CaptureCandidate, CaptureDiagnosis, CaptureSettingsProposal, diagnose_capture
 from .capture import (
     CaptureIntegrityError,
     LiveCaptureHealth,
@@ -40,7 +41,7 @@ from .origin_learning import (
     promote_origin_candidates,
 )
 from .writers import ConsoleEventWriter, JsonlEventWriter
-from . import solare
+from . import agris, solare
 from ._version import __version__
 
 __all__ = [
@@ -48,6 +49,10 @@ __all__ = [
     "AsyncLiveCaptureSession",
     "BDOEvent",
     "CaptureEndpoint",
+    "CaptureCandidate",
+    "CaptureDiagnosis",
+    "CaptureSettingsProposal",
+    "diagnose_capture",
     "CaptureIntegrityError",
     "ConsoleEventWriter",
     "DecoderDiagnostic",
@@ -78,6 +83,7 @@ __all__ = [
     "StorageLocation",
     "__version__",
     "capture_live",
+    "agris",
     "fetch_opcode_profile",
     "load_opcode_profile",
     "promote_origin_candidates",

{bdo_toolkit-1.0.4 → bdo_toolkit-1.0.6}/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.4 → bdo_toolkit-1.0.6}/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.4 → bdo_toolkit-1.0.6}/src/bdo_toolkit/_version.py

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

bdo_toolkit-1.0.6/src/bdo_toolkit/agris/__init__.py

@@ -0,0 +1,16 @@
+"""Experimental passive Agris balances with required-cap cold discovery.
+
+No item profile, persisted layout, starting balance, or consumption calculation
+is used. A uniquely matching inferred layout is not universal semantic proof.
+"""
+from ._capture import AgrisCaptureHealth
+from .async_session import AsyncLiveAgrisSession
+from .models import AgrisBalance, AgrisDetectionError, AgrisDiscoveryOptions, AgrisLayout, AgrisStatus
+from .replay import AgrisReplay, replay_agris
+from .session import LiveAgrisSession
+
+__all__ = [
+    "AgrisBalance", "AgrisCaptureHealth", "AgrisDetectionError", "AgrisDiscoveryOptions",
+    "AgrisLayout", "AgrisReplay", "AgrisStatus", "AsyncLiveAgrisSession",
+    "LiveAgrisSession", "replay_agris",
+]

bdo_toolkit-1.0.6/src/bdo_toolkit/agris/_capture.py

@@ -0,0 +1,87 @@
+"""Shared Agris transport adapter and immutable capture diagnostics."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Iterable
+
+from .._capture_backend import validate_server_ports
+from .._framing import FrameCollectorScanner
+from .._protocol import FlowKey
+from .._reassembly import FlowManager
+from ._discovery import AgrisTracker
+
+
+@dataclass(frozen=True)
+class AgrisCaptureHealth:
+    """Loss indicators; unavailable native counters remain None, not zero."""
+
+    packets_processed: int = 0
+    packets_accepted: int = 0
+    packet_queue_overflows: int = 0
+    event_queue_overflows: int = 0
+    tcp_gap_resets: int = 0
+    flow_state_evictions: int = 0
+    pcap_received: int | None = None
+    pcap_dropped: int | None = None
+    pcap_interface_dropped: int | None = None
+    capture_buffer_bytes: int | None = None
+    cleanup_incomplete: bool = False
+
+    @property
+    def capture_is_clean(self) -> bool:
+        """No known loss; unknown kernel counters are not proof of completeness."""
+        return not (self.packet_queue_overflows or self.event_queue_overflows
+                    or self.tcp_gap_resets or self.flow_state_evictions
+                    or self.pcap_dropped or self.pcap_interface_dropped)
+
+    def to_dict(self) -> dict[str, object]:
+        return {**asdict(self), "capture_is_clean": self.capture_is_clean}
+
+
+class AgrisFlowManager(FlowManager):
+    """Generic framing, with no opcode hints or item-profile dependency."""
+
+    def __init__(self, tracker: AgrisTracker, ports: Iterable[int], *, live: bool = False):
+        self.tracker = tracker
+        self.finishing = False
+        self.clock = 0.0
+        self.evictions = 0
+        super().__init__(server_ports=validate_server_ports(ports),
+                         scanner_factory=lambda: FrameCollectorScanner(tracker.observe),
+                         max_flows=64, max_pending_bytes=4 * 1024 * 1024,
+                         track_flow_generations=True, defer_gap_timeouts=live,
+                         on_flow_reset=tracker.gap_reset, on_flow_close=self._closed,
+                         on_flow_eviction=self._evicted)
+
+    def _closed(self, flow: FlowKey) -> None:
+        if not self.finishing:
+            self.tracker.close_flow(flow)
+
+    def _evicted(self) -> None:
+        self.evictions += 1
+        self.tracker.invalidate("Agris flow-state limit reached; discovery is incomplete")
+
+    def process_tcp_segment(self, *, source_ip: str, source_port: int,
+                            destination_ip: str, destination_port: int, sequence: int,
+                            payload: bytes, timestamp: float, syn: bool = False,
+                            rst: bool = False, fin: bool = False) -> None:
+        super().process_tcp_segment(source_ip=source_ip, source_port=source_port,
+                                    destination_ip=destination_ip, destination_port=destination_port,
+                                    sequence=sequence, payload=payload, timestamp=timestamp,
+                                    syn=syn, rst=rst, fin=fin)
+        if source_port in self.server_ports:
+            self.clock = max(self.clock, timestamp)
+
+    def refresh(self, now: float | None = None) -> None:
+        self.clock = max(self.clock, now if now is not None else self.clock)
+        self.tracker.refresh(self.clock)
+
+    def finish(self) -> None:
+        # EOF is not a network disconnect. Preserve the final observation, but
+        # do not forgive actual gaps exposed by draining buffered segments.
+        self.finishing = True
+        try:
+            super().finish()
+            self.refresh()
+        finally:
+            self.finishing = False

bdo_toolkit-1.0.6/src/bdo_toolkit/agris/_discovery.py

@@ -0,0 +1,287 @@
+"""Bounded cold discovery, separate from selected-layout balance decoding.
+
+No remembered opcode, message size, field offset, or profile participates in
+identity. A unique capped decreasing uint32LE column remains an inference,
+not proof that an unrelated resource cannot share those characteristics.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import NoReturn
+
+from .._protocol import BDOFrame, FlowKey
+from ..events import Flow
+from ._validation import validate_expected_maximum_points
+from .models import (
+    AgrisBalance,
+    AgrisDetectionError,
+    AgrisDiscoveryOptions,
+    AgrisDiscoveryState,
+    AgrisLayout,
+    AgrisStatus,
+)
+
+
+@dataclass
+class _Column:
+    last: int
+    distinct: int = 1
+
+
+@dataclass
+class _Family:
+    caps: set[int]
+    columns: dict[int, _Column]
+    observed_at: float
+
+
+type _FamilyKey = tuple[FlowKey, int, int, int]
+type _CandidateKey = tuple[_FamilyKey, int, int]
+
+
+def _public_flow(flow: FlowKey) -> Flow:
+    return Flow(flow.source_ip, flow.source_port, flow.destination_ip, flow.destination_port)
+
+
+class AgrisTracker:
+    """Single-owner tracker; no raw frame history or consumption arithmetic.
+
+    Before selection, a family's surviving columns must be nonincreasing and
+    in range from its first observation. Contradicted hypotheses never restart
+    midway through that family. After selection, direct decoding permits equal
+    and increasing balances while discovery still checks competing hypotheses.
+    """
+
+    def __init__(
+        self,
+        *,
+        expected_maximum_points: int,
+        options: AgrisDiscoveryOptions | None = None,
+        on_balance: Callable[[AgrisBalance], None] | None = None,
+    ) -> None:
+        self.expected_maximum_points = validate_expected_maximum_points(expected_maximum_points)
+        if options is not None and not isinstance(options, AgrisDiscoveryOptions):
+            raise TypeError("options must be AgrisDiscoveryOptions or None")
+        if on_balance is not None and not callable(on_balance):
+            raise TypeError("on_balance must be callable or None")
+        self.options = options if options is not None else AgrisDiscoveryOptions()
+        self._on_balance = on_balance
+        self._families: dict[_FamilyKey, _Family] = {}
+        self._column_count = 0
+        self._observed_frames = 0
+        self._clock = 0.0
+        self._selected: _CandidateKey | None = None
+        self._unique: _CandidateKey | None = None
+        self._unique_since = 0.0
+        self._candidates: tuple[_CandidateKey, ...] = ()
+        self._candidates_dirty = False
+        self._invalid_reason: str | None = None
+        self._latest_balance: AgrisBalance | None = None
+        self._selected_version = 0
+        self._published_version = -1
+        self._tracking = False
+
+    @property
+    def clock(self) -> float:
+        """Latest settling clock, distinct from a balance's packet timestamp."""
+
+        return self._clock
+
+    def invalidate(self, reason: str) -> NoReturn:
+        """Latch the first integrity failure and withdraw current authority."""
+
+        if self._invalid_reason is None:
+            self._invalid_reason = reason
+        self._tracking = False
+        raise AgrisDetectionError(self._invalid_reason)
+
+    def observe(self, frame: BDOFrame) -> None:
+        if self._invalid_reason is not None:
+            raise AgrisDetectionError(self._invalid_reason)
+        if not math.isfinite(frame.context.timestamp):
+            self.invalidate("A frame has a non-finite observation timestamp.")
+        self._observed_frames += 1
+        self._clock = max(self._clock, frame.context.timestamp)
+        message = frame.message
+        if self._selected is not None:
+            chosen = self._selected[0]
+            if frame.context.flow == chosen[0] and frame.context.flow_generation != chosen[1]:
+                self.invalidate("Selected connection epoch changed; restart discovery.")
+        if len(message) < 5:
+            self.refresh()
+            return
+        key = (frame.context.flow, frame.context.flow_generation, frame.opcode, len(message))
+        if self._selected is not None:
+            chosen = self._selected[0]
+            if key[:3] == chosen[:3]:
+                if key != chosen or frame.flag != 0 or frame.length != len(message):
+                    self.invalidate("Selected message shape changed; restart discovery.")
+                self._decode_selected(frame)
+        if frame.flag != 0 or frame.length != len(message):
+            self.refresh()
+            return
+        if key not in self._families:
+            self._add_family(key, message, frame.context.timestamp)
+        else:
+            self._update_family(key, message, frame.context.timestamp)
+        self.refresh()
+
+    def _add_family(self, key: _FamilyKey, message: bytes, observed_at: float) -> None:
+        if len(self._families) >= self.options.max_families:
+            self.invalidate("Discovery family limit reached; no hypotheses were silently evicted.")
+        cap_bytes = self.expected_maximum_points.to_bytes(4, "little")
+        caps: set[int] = set()
+        offset = message.find(cap_bytes, 5)
+        while offset != -1:
+            caps.add(offset)
+            offset = message.find(cap_bytes, offset + 1)
+        columns: dict[int, _Column] = {}
+        if caps:
+            for offset in range(5, len(message) - 3):
+                value = int.from_bytes(message[offset : offset + 4], "little")
+                if value <= self.expected_maximum_points:
+                    if self._column_count + len(columns) >= self.options.max_columns:
+                        self.invalidate("Discovery column limit reached; no hypotheses were silently evicted.")
+                    columns[offset] = _Column(value)
+        self._column_count += len(columns)
+        self._families[key] = _Family(caps, columns, observed_at)
+        self._candidates_dirty = True
+
+    def _update_family(self, key: _FamilyKey, message: bytes, observed_at: float) -> None:
+        family = self._families[key]
+        family.observed_at = observed_at
+        family.caps.intersection_update(
+            offset for offset in tuple(family.caps)
+            if int.from_bytes(message[offset : offset + 4], "little") == self.expected_maximum_points
+        )
+        for offset, column in tuple(family.columns.items()):
+            value = int.from_bytes(message[offset : offset + 4], "little")
+            selected_column = self._selected is not None and self._selected[:2] == (key, offset)
+            if not family.caps or value > self.expected_maximum_points or (value > column.last and not selected_column):
+                del family.columns[offset]
+                self._column_count -= 1
+            else:
+                # Only comparison counts support inference: never derive spending.
+                if value < column.last and column.distinct < self.options.minimum_updates:
+                    column.distinct += 1
+                column.last = value
+        self._candidates_dirty = True
+
+    def _decode_selected(self, frame: BDOFrame) -> None:
+        assert self._selected is not None
+        _, offset, cap_offset = self._selected
+        remaining = int.from_bytes(frame.message[offset : offset + 4], "little")
+        maximum = int.from_bytes(frame.message[cap_offset : cap_offset + 4], "little")
+        if maximum != self.expected_maximum_points or remaining > maximum:
+            self.invalidate("Selected balance or cap is outside the validated layout constraints.")
+        self._latest_balance = AgrisBalance(
+            remaining_points=remaining,
+            maximum_points=maximum,
+            observed_at=frame.context.timestamp,
+            flow=_public_flow(frame.context.flow),
+            connection_epoch=frame.context.flow_generation,
+        )
+        self._selected_version += 1
+
+    def _find_candidates(self) -> None:
+        if not self._candidates_dirty:
+            return
+        candidates: list[_CandidateKey] = []
+        for key, family in self._families.items():
+            for offset, column in family.columns.items():
+                if column.distinct < self.options.minimum_updates:
+                    continue
+                for cap_offset in sorted(family.caps):
+                    if abs(cap_offset - offset) < 4:
+                        continue
+                    if len(candidates) >= self.options.max_candidates:
+                        self.invalidate("Discovery candidate limit reached; uniqueness is unresolved.")
+                    candidates.append((key, offset, cap_offset))
+        self._candidates = tuple(candidates)
+        self._candidates_dirty = False
+
+    def refresh(self, now: float | None = None) -> AgrisStatus:
+        """Advance observation time and publish only the newest authorized balance.
+
+        Live owners must not advance time while accepted packets remain queued.
+        Offline owners use capture timestamps, never today's wall clock.
+        """
+
+        if now is not None:
+            if isinstance(now, bool) or not isinstance(now, (int, float)):
+                raise TypeError("now must be a finite number or None")
+            if not math.isfinite(now):
+                raise ValueError("now must be finite")
+            self._clock = max(self._clock, now)
+        if self._invalid_reason is not None:
+            return self.snapshot()
+        self._find_candidates()
+        unique = self._candidates[0] if len(self._candidates) == 1 else None
+        if unique != self._unique:
+            self._unique = unique
+            self._unique_since = self._clock
+        was_tracking = self._tracking
+        self._tracking = False
+        if unique is not None and self._clock - self._unique_since >= self.options.settle_seconds:
+            if self._selected is not None and unique != self._selected:
+                self.invalidate("A different hypothesis replaced the selected layout; restart discovery.")
+            if self._selected is None:
+                self._selected = unique
+                key, offset, _ = unique
+                family = self._families[key]
+                self._latest_balance = AgrisBalance(
+                    remaining_points=family.columns[offset].last,
+                    maximum_points=self.expected_maximum_points,
+                    observed_at=family.observed_at,
+                    flow=_public_flow(key[0]),
+                    connection_epoch=key[1],
+                )
+            self._tracking = True
+        if self._tracking and (not was_tracking or self._published_version != self._selected_version):
+            assert self._latest_balance is not None
+            self._published_version = self._selected_version
+            if self._on_balance is not None:
+                self._on_balance(self._latest_balance)
+        return self.snapshot()
+
+    def snapshot(self) -> AgrisStatus:
+        """Read immutable state without advancing time or emitting events."""
+
+        state: AgrisDiscoveryState
+        if self._invalid_reason is not None:
+            state = "invalid"
+        elif len(self._candidates) > 1:
+            state = "ambiguous"
+        elif not self._candidates:
+            state = "searching"
+        elif self._tracking:
+            state = "tracking"
+        else:
+            state = "settling"
+        return AgrisStatus(
+            status=state,
+            expected_maximum_points=self.expected_maximum_points,
+            balance=self._latest_balance if state == "tracking" else None,
+            candidates=tuple(
+                AgrisLayout(key[2], key[3], offset, cap_offset, _public_flow(key[0]), key[1])
+                for key, offset, cap_offset in self._candidates
+            ),
+            observed_frames=self._observed_frames,
+            reason=self._invalid_reason,
+        )
+
+    def close_flow(self, flow: FlowKey) -> None:
+        if self._selected is not None and self._selected[0][0] == flow:
+            self.invalidate("Selected connection ended; restart discovery for a new connection.")
+        for key in tuple(self._families):
+            if key[0] == flow:
+                self._column_count -= len(self._families.pop(key).columns)
+                self._candidates_dirty = True
+        self.refresh()
+
+    def gap_reset(self, flow: FlowKey, generation: int, resume_sequence: int) -> None:
+        # Reassembly gap recovery need not increment the connection generation.
+        self.invalidate("TCP gap detected; restart discovery with an intact capture.")

bdo_toolkit-1.0.6/src/bdo_toolkit/agris/_validation.py

@@ -0,0 +1,13 @@
+"""Validation shared by every Agris acquisition entry point."""
+
+from __future__ import annotations
+
+
+def validate_expected_maximum_points(value: object) -> int:
+    """Require an explicit, positive uint32 cap; never infer a default."""
+
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError("expected_maximum_points must be an integer")
+    if not 1 <= value <= 0xFFFFFFFF:
+        raise ValueError("expected_maximum_points must be between 1 and 4294967295")
+    return value