b24api 2.0.0__tar.gz → 2.2.0__tar.gz

{b24api-2.0.0/b24api.egg-info → b24api-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: b24api
-Version: 2.0.0
+Version: 2.2.0
 Summary: Bitrix24 API
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -43,6 +43,15 @@ idempotent and closes active streams before the owned transport.
 Use `call()` for detached decoded JSON and `call_response()` when you also need the immutable
 response envelope: `result`, `total`, `next`, timing and bounded diagnostic evidence.
 
+Use `call_bytes()` when a successful method response is a file rather than a Bitrix JSON envelope.
+The operation is explicit and never hides malformed JSON by falling back to bytes.
+
+<!-- tested: tests/client_findings_3_test.py::test_binary_call_returns_every_success_byte_without_json_sniffing -->
+```python
+archive = await client.call_bytes(Request("example.export.download", replay_safety=ReplaySafety.SAFE))
+payload = archive.body
+```
+
 <!-- tested: tests/client_v2_test.py::test_call_and_call_response_have_stable_detached_types -->
 ```python
 from b24api import ReplaySafety
@@ -130,20 +139,30 @@ more specialized mechanics have explicit names and explicit preconditions.
 
 | Operation | Use it when | Network mechanics | Completion proof |
 |---|---|---|---|
-| `iter_list` | The method supports ordinary offset pagination. | Pages are requested sequentially using server `next`; no separate count request is made. | Continuation and empty terminal page; add identity for duplicate detection. |
+| `iter_list` | The method supports ordinary offset pagination. | Sequential requests follow server `next` (the next offset). Ordinary counted Bitrix list endpoints do server-side COUNT for `total` plus LIMIT/OFFSET page retrieval. | Continuation and empty terminal page; add identity for duplicate detection. |
 | `iter_list_counted` | The first response provides an exact filtered `total` and stable offset pages. | Head page is direct; all known tail offsets are grouped into physical Bitrix batches. | Exact total, ranges and identities. |
-| `iter_list_keyset` | The method may omit `total`, but reliably supports ordering and filtering by a unique identity. | Sequential pages advance an identity boundary; no count request. | Strict monotonic identity and empty terminal page. |
+| `iter_list_keyset` | The method may omit `total`, but reliably supports ordering and filtering by a unique integer identity. | Auto by default: it plans first, then selects boundary-only, sequential, range, or partitioned execution; runtime sends no diagnostic canaries. | Caller-asserted keyset contract, strict monotonic identity, active bound validation, and terminal empty confirmation. |
 | `iter_list_cursor` | Each next request depends on a cursor from the previous response. | Sequential dependent cursor requests. | Strict unique monotonic cursor and empty terminal page. |
+| `iter_cursors` | One or many parent-bound cursor traversals need correlation and shared batching. | Lazy per-parent drivers share the reference batch queue; each binding may have `start_cursor`. | Isolated strict cursor progress and terminal event per binding. |
 | `iter_references` | The same list method must run for many parent parameter sets, such as comments per owner or messages per chat. | Bindings are scheduled with direct or physical-batch dispatch; each binding has its own traversal state. | Per-binding rows, completion/failure and caller correlation. |
 
 `page_size` is a local decoded-page cap. It is sent to Bitrix only when you provide the endpoint's
 exact `limit_path`; the client never guesses method-specific parameter names.
 
+### List traversal comparison
+
+![List traversal comparison](list-traversal-comparison.svg)
+
 ### Sequential offset
 
 This is the canonical default. It follows the `next` returned by the server and confirms the end
-with an empty page. A `total` present in the response is observational; this strategy does not add
-a separate count request.
+with an empty page. For ordinary counted Bitrix list endpoints, `next` is an offset for the next
+LIMIT/OFFSET page, not a keyset cursor. Producing `total` involves a separate server-side count
+query in addition to retrieving the page. These database operations are performed inside the same
+REST request: the client does not issue an additional HTTP call just for the count. This distinction
+matters for performance: not making a separate HTTP count call does **not** mean avoiding server-side
+COUNT work. `iter_list` does not suppress that work; a returned `total` is observational and does not
+control this strategy's completion. Exact database implementation is endpoint-specific.
 
 <!-- tested: tests/client_v2_test.py::test_iter_list_is_sequential_mechanics_only_and_report_is_post_cleanup -->
 ```python
@@ -169,6 +188,24 @@ async with stream:
 Without `identity`, successful exhaustion is reported as `MECHANICS_ONLY`: pagination completed,
 but the client cannot prove that the portal did not duplicate or substitute rows.
 
+Mapping-backed collections are explicit as well. `MAPPING_VALUES` yields values from a selected
+mapping in insertion order; `MAPPING_VALUES_OR_EMPTY` additionally accepts only an empty terminal
+sequence and records that degradation in the operation report.
+
+<!-- tested: tests/client_findings_3_test.py::test_shape_rejection_is_retained_as_zero_admission_page_evidence -->
+```python
+from b24api import ResultCollectionShape
+
+stream = client.iter_list(
+    Request("example.dictionary.list", replay_safety=ReplaySafety.SAFE),
+    selector=ResultSelector(("items",)),
+    collection_shape=ResultCollectionShape.MAPPING_VALUES,
+)
+async with stream:
+    async for value in stream:
+        consume(value)
+```
+
 ### Counted, physically batched tail
 
 The first direct page must contain an exact filtered `total` and, when more rows exist, `next`.
@@ -189,13 +226,48 @@ stream = client.iter_list_counted(
 Use it only when `total` is exact for the supplied filter and offset pages are stable. Any missing
 range, overlap, duplicate identity or total contradiction raises `IncompleteTraversalError`.
 
-### No-count keyset
+Physical batching reduces HTTP exchanges, but does not suppress server-side COUNT in ordinary
+counted list subrequests. Each command still performs its own offset page retrieval and associated
+total calculation on the server. Do not confuse batching these commands with a no-count traversal.
 
-Keyset traversal does not ask the server for a count. The method must honor ordering and a strict
-identity boundary such as `filter[>ID]`. It is intentionally sequential because a future boundary
-cannot be known safely before the preceding page arrives.
+### No-count keyset
 
-<!-- tested: tests/client_v2_test.py::test_keyset_and_cursor_are_explicit_strict_alternatives -->
+Keyset traversal uses automatic execution by default. Omitting `execution` is equivalent to
+`AutoKeysetExecution(StableIntegerKeysetContract())`: the client captures both ordered boundaries,
+then selects boundary-only, sequential, range, or partitioned execution from the observed geometry
+and available policy capacity. Planning completes before any row is emitted, so partial consumption
+still pays that barrier cost. A sequential selection made by auto is a cost decision; a failed or
+contradictory fast plan is never silently restarted as sequential.
+
+By using the default, the caller asserts that the endpoint has a stable, unique integer key, honors
+strict numeric bounds and ordering, and satisfies empty-confirmation completion. Concurrent mutation
+outside the captured middle is handled by the finishing sweep; mutation inside it is outside this
+assertion. Pass `SequentialKeysetExecution()` explicitly when an endpoint cannot satisfy the fast
+contract or when the previous request-by-request behavior is required.
+
+Static incompatibility with the auto contract raises `CapabilityError` from the
+`iter_list_keyset(...)` call before iteration begins. A portal that accepts but contradicts the
+declared controls fails before emission with `IncompleteTraversalError`; auto never restarts that
+operation silently. `KeysetTraversal` inside reference traversal remains sequential-only. The
+terminal report now includes `keyset_execution` for omitted-execution keyset calls so consumers can
+see the requested and selected plan.
+
+Use `await client.verify_keyset_capability(...)` as a development/CI/staging guard on a stable
+representative fixture. It performs five strict-bound checks and returns only a `VERIFIED` report;
+unsupported and inconclusive verdicts raise `KeysetCapabilityError`. The ordinary
+`iter_list_keyset()` remains a separate caller-asserted operation with zero verifier canaries and
+may emit a partial prefix before a late endpoint contradiction is detected.
+
+Every list operation also accepts an immutable `PageAdapter` strategy. The adapter synchronously
+maps selected frozen items using sibling result metadata while preserving cardinality, order and
+configured identities. The identity adapter is the default and preserves existing JSON output.
+
+An advisory `total` may only raise an automatic cost estimate and never proves completion. Reports
+record the selected strategy and reason: unbounded auto continuation has the same
+`ordered_prefix_only` assurance as sequential traversal, while bounded plans additionally report
+`caller_asserted_bounds`. Runtime traversal does not perform verifier canaries.
+
+<!-- tested: tests/keyset_fast_test.py::test_omitted_execution_defaults_to_auto -->
 ```python
 from b24api import KeysetSpec, ParameterPath
 
@@ -235,12 +307,23 @@ stream = client.iter_list_cursor(
 Cursor values must be unique and strictly monotonic. If an endpoint exposes only a non-unique
 boundary, use an application-owned direct-call workflow or supply a unique tie-breaker.
 
+For multiple parent-bound cursor chains, `iter_cursors()` keeps cursor progress and correlation
+isolated per binding while ready pages share the physical batch queue.
+
+![Cursor batching across independent chats](cursor-batching.svg)
+
+See [architecture](docs/architecture.md), [migration](docs/migration.md),
+[performance](docs/performance.md), and [endpoint recipes](docs/recipes.md) for the complete
+contracts and selection guidance.
+
 ### One list method across many parent entities
 
 `Binding` applies exact parameter updates to a base request and carries parent correlation. The
 client remains unaware of entity types: a binding can represent a deal, lead, chat or any other
 caller-defined parent.
 
+![Reference batching across leads and deals](references-batching.svg)
+
 <!-- tested: tests/client_v2_test.py::test_bound_references_apply_nested_updates_off_wire_and_emit_exact_completion -->
 ```python
 from b24api import (

{b24api-2.0.0 → b24api-2.2.0}/README.md

@@ -31,6 +31,15 @@ idempotent and closes active streams before the owned transport.
 Use `call()` for detached decoded JSON and `call_response()` when you also need the immutable
 response envelope: `result`, `total`, `next`, timing and bounded diagnostic evidence.
 
+Use `call_bytes()` when a successful method response is a file rather than a Bitrix JSON envelope.
+The operation is explicit and never hides malformed JSON by falling back to bytes.
+
+<!-- tested: tests/client_findings_3_test.py::test_binary_call_returns_every_success_byte_without_json_sniffing -->
+```python
+archive = await client.call_bytes(Request("example.export.download", replay_safety=ReplaySafety.SAFE))
+payload = archive.body
+```
+
 <!-- tested: tests/client_v2_test.py::test_call_and_call_response_have_stable_detached_types -->
 ```python
 from b24api import ReplaySafety
@@ -118,20 +127,30 @@ more specialized mechanics have explicit names and explicit preconditions.
 
 | Operation | Use it when | Network mechanics | Completion proof |
 |---|---|---|---|
-| `iter_list` | The method supports ordinary offset pagination. | Pages are requested sequentially using server `next`; no separate count request is made. | Continuation and empty terminal page; add identity for duplicate detection. |
+| `iter_list` | The method supports ordinary offset pagination. | Sequential requests follow server `next` (the next offset). Ordinary counted Bitrix list endpoints do server-side COUNT for `total` plus LIMIT/OFFSET page retrieval. | Continuation and empty terminal page; add identity for duplicate detection. |
 | `iter_list_counted` | The first response provides an exact filtered `total` and stable offset pages. | Head page is direct; all known tail offsets are grouped into physical Bitrix batches. | Exact total, ranges and identities. |
-| `iter_list_keyset` | The method may omit `total`, but reliably supports ordering and filtering by a unique identity. | Sequential pages advance an identity boundary; no count request. | Strict monotonic identity and empty terminal page. |
+| `iter_list_keyset` | The method may omit `total`, but reliably supports ordering and filtering by a unique integer identity. | Auto by default: it plans first, then selects boundary-only, sequential, range, or partitioned execution; runtime sends no diagnostic canaries. | Caller-asserted keyset contract, strict monotonic identity, active bound validation, and terminal empty confirmation. |
 | `iter_list_cursor` | Each next request depends on a cursor from the previous response. | Sequential dependent cursor requests. | Strict unique monotonic cursor and empty terminal page. |
+| `iter_cursors` | One or many parent-bound cursor traversals need correlation and shared batching. | Lazy per-parent drivers share the reference batch queue; each binding may have `start_cursor`. | Isolated strict cursor progress and terminal event per binding. |
 | `iter_references` | The same list method must run for many parent parameter sets, such as comments per owner or messages per chat. | Bindings are scheduled with direct or physical-batch dispatch; each binding has its own traversal state. | Per-binding rows, completion/failure and caller correlation. |
 
 `page_size` is a local decoded-page cap. It is sent to Bitrix only when you provide the endpoint's
 exact `limit_path`; the client never guesses method-specific parameter names.
 
+### List traversal comparison
+
+![List traversal comparison](list-traversal-comparison.svg)
+
 ### Sequential offset
 
 This is the canonical default. It follows the `next` returned by the server and confirms the end
-with an empty page. A `total` present in the response is observational; this strategy does not add
-a separate count request.
+with an empty page. For ordinary counted Bitrix list endpoints, `next` is an offset for the next
+LIMIT/OFFSET page, not a keyset cursor. Producing `total` involves a separate server-side count
+query in addition to retrieving the page. These database operations are performed inside the same
+REST request: the client does not issue an additional HTTP call just for the count. This distinction
+matters for performance: not making a separate HTTP count call does **not** mean avoiding server-side
+COUNT work. `iter_list` does not suppress that work; a returned `total` is observational and does not
+control this strategy's completion. Exact database implementation is endpoint-specific.
 
 <!-- tested: tests/client_v2_test.py::test_iter_list_is_sequential_mechanics_only_and_report_is_post_cleanup -->
 ```python
@@ -157,6 +176,24 @@ async with stream:
 Without `identity`, successful exhaustion is reported as `MECHANICS_ONLY`: pagination completed,
 but the client cannot prove that the portal did not duplicate or substitute rows.
 
+Mapping-backed collections are explicit as well. `MAPPING_VALUES` yields values from a selected
+mapping in insertion order; `MAPPING_VALUES_OR_EMPTY` additionally accepts only an empty terminal
+sequence and records that degradation in the operation report.
+
+<!-- tested: tests/client_findings_3_test.py::test_shape_rejection_is_retained_as_zero_admission_page_evidence -->
+```python
+from b24api import ResultCollectionShape
+
+stream = client.iter_list(
+    Request("example.dictionary.list", replay_safety=ReplaySafety.SAFE),
+    selector=ResultSelector(("items",)),
+    collection_shape=ResultCollectionShape.MAPPING_VALUES,
+)
+async with stream:
+    async for value in stream:
+        consume(value)
+```
+
 ### Counted, physically batched tail
 
 The first direct page must contain an exact filtered `total` and, when more rows exist, `next`.
@@ -177,13 +214,48 @@ stream = client.iter_list_counted(
 Use it only when `total` is exact for the supplied filter and offset pages are stable. Any missing
 range, overlap, duplicate identity or total contradiction raises `IncompleteTraversalError`.
 
-### No-count keyset
+Physical batching reduces HTTP exchanges, but does not suppress server-side COUNT in ordinary
+counted list subrequests. Each command still performs its own offset page retrieval and associated
+total calculation on the server. Do not confuse batching these commands with a no-count traversal.
 
-Keyset traversal does not ask the server for a count. The method must honor ordering and a strict
-identity boundary such as `filter[>ID]`. It is intentionally sequential because a future boundary
-cannot be known safely before the preceding page arrives.
+### No-count keyset
 
-<!-- tested: tests/client_v2_test.py::test_keyset_and_cursor_are_explicit_strict_alternatives -->
+Keyset traversal uses automatic execution by default. Omitting `execution` is equivalent to
+`AutoKeysetExecution(StableIntegerKeysetContract())`: the client captures both ordered boundaries,
+then selects boundary-only, sequential, range, or partitioned execution from the observed geometry
+and available policy capacity. Planning completes before any row is emitted, so partial consumption
+still pays that barrier cost. A sequential selection made by auto is a cost decision; a failed or
+contradictory fast plan is never silently restarted as sequential.
+
+By using the default, the caller asserts that the endpoint has a stable, unique integer key, honors
+strict numeric bounds and ordering, and satisfies empty-confirmation completion. Concurrent mutation
+outside the captured middle is handled by the finishing sweep; mutation inside it is outside this
+assertion. Pass `SequentialKeysetExecution()` explicitly when an endpoint cannot satisfy the fast
+contract or when the previous request-by-request behavior is required.
+
+Static incompatibility with the auto contract raises `CapabilityError` from the
+`iter_list_keyset(...)` call before iteration begins. A portal that accepts but contradicts the
+declared controls fails before emission with `IncompleteTraversalError`; auto never restarts that
+operation silently. `KeysetTraversal` inside reference traversal remains sequential-only. The
+terminal report now includes `keyset_execution` for omitted-execution keyset calls so consumers can
+see the requested and selected plan.
+
+Use `await client.verify_keyset_capability(...)` as a development/CI/staging guard on a stable
+representative fixture. It performs five strict-bound checks and returns only a `VERIFIED` report;
+unsupported and inconclusive verdicts raise `KeysetCapabilityError`. The ordinary
+`iter_list_keyset()` remains a separate caller-asserted operation with zero verifier canaries and
+may emit a partial prefix before a late endpoint contradiction is detected.
+
+Every list operation also accepts an immutable `PageAdapter` strategy. The adapter synchronously
+maps selected frozen items using sibling result metadata while preserving cardinality, order and
+configured identities. The identity adapter is the default and preserves existing JSON output.
+
+An advisory `total` may only raise an automatic cost estimate and never proves completion. Reports
+record the selected strategy and reason: unbounded auto continuation has the same
+`ordered_prefix_only` assurance as sequential traversal, while bounded plans additionally report
+`caller_asserted_bounds`. Runtime traversal does not perform verifier canaries.
+
+<!-- tested: tests/keyset_fast_test.py::test_omitted_execution_defaults_to_auto -->
 ```python
 from b24api import KeysetSpec, ParameterPath
 
@@ -223,12 +295,23 @@ stream = client.iter_list_cursor(
 Cursor values must be unique and strictly monotonic. If an endpoint exposes only a non-unique
 boundary, use an application-owned direct-call workflow or supply a unique tie-breaker.
 
+For multiple parent-bound cursor chains, `iter_cursors()` keeps cursor progress and correlation
+isolated per binding while ready pages share the physical batch queue.
+
+![Cursor batching across independent chats](cursor-batching.svg)
+
+See [architecture](docs/architecture.md), [migration](docs/migration.md),
+[performance](docs/performance.md), and [endpoint recipes](docs/recipes.md) for the complete
+contracts and selection guidance.
+
 ### One list method across many parent entities
 
 `Binding` applies exact parameter updates to a base request and carries parent correlation. The
 client remains unaware of entity types: a binding can represent a deal, lead, chat or any other
 caller-defined parent.
 
+![Reference batching across leads and deals](references-batching.svg)
+
 <!-- tested: tests/client_v2_test.py::test_bound_references_apply_nested_updates_off_wire_and_emit_exact_completion -->
 ```python
 from b24api import (

b24api-2.2.0/b24api/__init__.py

@@ -0,0 +1,253 @@
+"""One explicit, method-agnostic b24api v2 public surface."""
+
+from b24api.client import Bitrix24
+from b24api.contracts import (
+    AdaptedPage,
+    AmbiguityPolicy,
+    AmbiguityReason,
+    AutoKeysetExecution,
+    BatchDispatch,
+    BinaryEvidence,
+    BinaryResponse,
+    Binding,
+    BodyEncoding,
+    ClosureWitness,
+    Command,
+    CommandFailure,
+    CommandNotExecuted,
+    CommandOutcome,
+    CommandOutcomeUnknown,
+    CommandSuccess,
+    CompositeIdentitySpec,
+    ConsistencyPolicy,
+    CountedTraversal,
+    CursorSpec,
+    CursorTraversal,
+    DeliveryOrder,
+    DirectDispatch,
+    ExecutionPolicy,
+    FrozenJson,
+    FrozenMapping,
+    IdentityCoercion,
+    IdentityComponent,
+    IdentityPageAdapter,
+    IdentitySpec,
+    KeysetAssuranceSource,
+    KeysetCapabilityCheckName,
+    KeysetCapabilityCheckOutcome,
+    KeysetCapabilityCheckResult,
+    KeysetCapabilityReport,
+    KeysetCapabilityVerdict,
+    KeysetExecution,
+    KeysetExecutionKind,
+    KeysetExecutionReport,
+    KeysetInconclusiveReason,
+    KeysetPageCompletion,
+    KeysetPhase,
+    KeysetSelectionReason,
+    KeysetSpec,
+    KeysetTraversal,
+    MembershipRecheck,
+    NotExecutedReason,
+    OffsetContinuation,
+    OffsetSpec,
+    OperationReport,
+    OperationStream,
+    PageAdapter,
+    PageDispatch,
+    PageOutcome,
+    PageRecord,
+    PageRejectionCode,
+    PageView,
+    ParameterPath,
+    ParameterUpdate,
+    PartialResult,
+    PartitionedKeysetExecution,
+    RangeKeysetExecution,
+    ReferenceComplete,
+    ReferenceEvent,
+    ReferenceFailure,
+    ReferenceItem,
+    ReferenceNotExecuted,
+    ReferenceOutcome,
+    ReferenceOutcomeUnknown,
+    ReplaySafety,
+    Request,
+    RequestHeaders,
+    RequestSummary,
+    Response,
+    ResultCollectionShape,
+    ResultErrorShape,
+    ResultErrorSpec,
+    ResultSelector,
+    RetryPolicy,
+    SequentialKeysetExecution,
+    SequentialTraversal,
+    SplitOrderSpec,
+    StableIntegerKeysetContract,
+    TerminalState,
+    TotalHintMode,
+    TotalTermination,
+    TraceClass,
+    TraversalAssurance,
+    TraversalIdentity,
+    UnknownRequestAudit,
+    UnknownRequestCollector,
+    Violation,
+    ViolationSeverity,
+    partition_command_outcomes,
+    partition_reference_outcomes,
+    traversal_control_paths,
+)
+from b24api.errors import (
+    AmbiguousExecutionError,
+    ApiResponseError,
+    B24ApiError,
+    BatchCommandError,
+    BatchFailed,
+    BudgetExceededError,
+    CapabilityError,
+    EnvelopeContractError,
+    HTTPGatewayError,
+    IdentityContractError,
+    IncompleteTraversalError,
+    InputSourceError,
+    KeysetCapabilityError,
+    PageAdaptationError,
+    PageAdaptationViolation,
+    PaginationError,
+    ProtocolError,
+    ReferenceFailed,
+    ResponseTooLargeError,
+    ResultShapeError,
+    TransportError,
+)
+from b24api.settings import Settings
+from b24api.transport import Transport, TransportCapabilities, WireRequest, WireResponse, WireTransport
+
+__all__ = [
+    "AdaptedPage",
+    "AmbiguityPolicy",
+    "AmbiguityReason",
+    "AmbiguousExecutionError",
+    "ApiResponseError",
+    "AutoKeysetExecution",
+    "B24ApiError",
+    "BatchCommandError",
+    "BatchDispatch",
+    "BatchFailed",
+    "BinaryEvidence",
+    "BinaryResponse",
+    "Binding",
+    "Bitrix24",
+    "BodyEncoding",
+    "BudgetExceededError",
+    "CapabilityError",
+    "ClosureWitness",
+    "Command",
+    "CommandFailure",
+    "CommandNotExecuted",
+    "CommandOutcome",
+    "CommandOutcomeUnknown",
+    "CommandSuccess",
+    "CompositeIdentitySpec",
+    "ConsistencyPolicy",
+    "CountedTraversal",
+    "CursorSpec",
+    "CursorTraversal",
+    "DeliveryOrder",
+    "DirectDispatch",
+    "EnvelopeContractError",
+    "ExecutionPolicy",
+    "FrozenJson",
+    "FrozenMapping",
+    "HTTPGatewayError",
+    "IdentityCoercion",
+    "IdentityComponent",
+    "IdentityContractError",
+    "IdentityPageAdapter",
+    "IdentitySpec",
+    "IncompleteTraversalError",
+    "InputSourceError",
+    "KeysetAssuranceSource",
+    "KeysetCapabilityCheckName",
+    "KeysetCapabilityCheckOutcome",
+    "KeysetCapabilityCheckResult",
+    "KeysetCapabilityError",
+    "KeysetCapabilityReport",
+    "KeysetCapabilityVerdict",
+    "KeysetExecution",
+    "KeysetExecutionKind",
+    "KeysetExecutionReport",
+    "KeysetInconclusiveReason",
+    "KeysetPageCompletion",
+    "KeysetPhase",
+    "KeysetSelectionReason",
+    "KeysetSpec",
+    "KeysetTraversal",
+    "MembershipRecheck",
+    "NotExecutedReason",
+    "OffsetContinuation",
+    "OffsetSpec",
+    "OperationReport",
+    "OperationStream",
+    "PageAdaptationError",
+    "PageAdaptationViolation",
+    "PageAdapter",
+    "PageDispatch",
+    "PageOutcome",
+    "PageRecord",
+    "PageRejectionCode",
+    "PageView",
+    "PaginationError",
+    "ParameterPath",
+    "ParameterUpdate",
+    "PartialResult",
+    "PartitionedKeysetExecution",
+    "ProtocolError",
+    "RangeKeysetExecution",
+    "ReferenceComplete",
+    "ReferenceEvent",
+    "ReferenceFailed",
+    "ReferenceFailure",
+    "ReferenceItem",
+    "ReferenceNotExecuted",
+    "ReferenceOutcome",
+    "ReferenceOutcomeUnknown",
+    "ReplaySafety",
+    "Request",
+    "RequestHeaders",
+    "RequestSummary",
+    "Response",
+    "ResponseTooLargeError",
+    "ResultCollectionShape",
+    "ResultErrorShape",
+    "ResultErrorSpec",
+    "ResultSelector",
+    "ResultShapeError",
+    "RetryPolicy",
+    "SequentialKeysetExecution",
+    "SequentialTraversal",
+    "Settings",
+    "SplitOrderSpec",
+    "StableIntegerKeysetContract",
+    "TerminalState",
+    "TotalHintMode",
+    "TotalTermination",
+    "TraceClass",
+    "Transport",
+    "TransportCapabilities",
+    "TransportError",
+    "TraversalAssurance",
+    "TraversalIdentity",
+    "UnknownRequestAudit",
+    "UnknownRequestCollector",
+    "Violation",
+    "ViolationSeverity",
+    "WireRequest",
+    "WireResponse",
+    "WireTransport",
+    "partition_command_outcomes",
+    "partition_reference_outcomes",
+    "traversal_control_paths",
+]

b24api-2.2.0/b24api/_audit.py

@@ -0,0 +1,78 @@
+"""Lazy admission-time observation for logical command sources."""
+
+from __future__ import annotations
+from collections.abc import AsyncIterable, AsyncIterator, Callable, Iterable, Iterator
+from typing import TYPE_CHECKING, Protocol, Self, runtime_checkable
+
+from b24api.contracts.command import Command
+
+if TYPE_CHECKING:
+    from b24api.contracts.report import Violation
+    from b24api.contracts.request import Request
+
+
+@runtime_checkable
+class _SyncClosable(Protocol):
+    def close(self) -> None: ...
+
+
+@runtime_checkable
+class _AsyncClosable(Protocol):
+    async def aclose(self) -> None: ...
+
+
+class _SyncAuditSource[C](Iterator[Command[C]]):
+    def __init__(self, source: Iterable[Command[C]], audit: Callable[[Request], Violation | None]) -> None:
+        self._iterator = iter(source)
+        self._audit = audit
+        self.violations: list[Violation] = []
+
+    def __iter__(self) -> Self:
+        return self
+
+    def __next__(self) -> Command[C]:
+        command = next(self._iterator)
+        if isinstance(command, Command):
+            violation = self._audit(command.request)
+            if violation is not None:
+                self.violations.append(violation)
+        return command
+
+    def close(self) -> None:
+        if isinstance(self._iterator, _SyncClosable):
+            self._iterator.close()
+
+
+class _AsyncAuditSource[C](AsyncIterator[Command[C]]):
+    def __init__(self, source: AsyncIterable[Command[C]], audit: Callable[[Request], Violation | None]) -> None:
+        self._iterator = aiter(source)
+        self._audit = audit
+        self.violations: list[Violation] = []
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def __anext__(self) -> Command[C]:
+        command = await anext(self._iterator)
+        if isinstance(command, Command):
+            violation = self._audit(command.request)
+            if violation is not None:
+                self.violations.append(violation)
+        return command
+
+    async def aclose(self) -> None:
+        if isinstance(self._iterator, _AsyncClosable):
+            await self._iterator.aclose()
+
+
+def audit_command_source[C](
+    source: Iterable[Command[C]] | AsyncIterable[Command[C]],
+    audit: Callable[[Request], Violation | None],
+) -> Iterable[Command[C]] | AsyncIterable[Command[C]]:
+    """Observe each command exactly when its lazy source admits it."""
+    if isinstance(source, AsyncIterable):
+        return _AsyncAuditSource(source, audit)
+    return _SyncAuditSource(source, audit)
+
+
+__all__ = ["audit_command_source"]