b24api 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: b24api
-Version: 2.1.0
+Version: 2.2.0
 Summary: Bitrix24 API
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -139,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 integer identity. | Sequential by default; explicit range, partitioned, or auto execution may batch bounded work after a planning barrier. | Caller-asserted keyset contract, strict monotonic identity, bounded-plan canaries, and terminal empty confirmation. |
+| `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
@@ -216,25 +226,50 @@ 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`.
 
+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.
+
 ### No-count keyset
 
-Keyset traversal is sequential by default, preserving the compatible request shape and first-pull
-behavior. An explicit execution contract can instead capture both ordered boundaries, validate five
-capability canaries, and batch numeric ranges or occupied-anchor partitions. Planning completes
-before any row is emitted, so partial consumption still pays that barrier cost. Fast execution fails
-synchronously when its declared controls or policy capacity are ineligible.
+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.
 
-The caller must assert that the endpoint has a stable, unique integer key, honors strict numeric
-bounds and ordering, and satisfies the chosen page-completion rule. Concurrent mutation outside the
-captured middle is handled by the finishing sweep; mutation inside it is outside this assertion.
 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
-`canary_verified_bounds`.
+`caller_asserted_bounds`. Runtime traversal does not perform verifier canaries.
 
-<!-- tested: tests/client_v2_test.py::test_keyset_and_cursor_are_explicit_strict_alternatives -->
+<!-- tested: tests/keyset_fast_test.py::test_omitted_execution_defaults_to_auto -->
 ```python
-from b24api import AutoKeysetExecution, KeysetSpec, ParameterPath, StableIntegerKeysetContract
+from b24api import KeysetSpec, ParameterPath
 
 stream = client.iter_list_keyset(
     Request("example.item.list", replay_safety=ReplaySafety.SAFE),
@@ -244,7 +279,6 @@ stream = client.iter_list_keyset(
         filter_path=ParameterPath(("filter",)),
         order_path=ParameterPath(("order",)),
     ),
-    execution=AutoKeysetExecution(contract=StableIntegerKeysetContract()),
 )
 ```
 
@@ -273,6 +307,11 @@ 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.
@@ -283,6 +322,8 @@ contracts and selection guidance.
 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.1.0 → b24api-2.2.0}/README.md

@@ -127,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 integer identity. | Sequential by default; explicit range, partitioned, or auto execution may batch bounded work after a planning barrier. | Caller-asserted keyset contract, strict monotonic identity, bounded-plan canaries, and terminal empty confirmation. |
+| `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
@@ -204,25 +214,50 @@ 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`.
 
+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.
+
 ### No-count keyset
 
-Keyset traversal is sequential by default, preserving the compatible request shape and first-pull
-behavior. An explicit execution contract can instead capture both ordered boundaries, validate five
-capability canaries, and batch numeric ranges or occupied-anchor partitions. Planning completes
-before any row is emitted, so partial consumption still pays that barrier cost. Fast execution fails
-synchronously when its declared controls or policy capacity are ineligible.
+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.
 
-The caller must assert that the endpoint has a stable, unique integer key, honors strict numeric
-bounds and ordering, and satisfies the chosen page-completion rule. Concurrent mutation outside the
-captured middle is handled by the finishing sweep; mutation inside it is outside this assertion.
 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
-`canary_verified_bounds`.
+`caller_asserted_bounds`. Runtime traversal does not perform verifier canaries.
 
-<!-- tested: tests/client_v2_test.py::test_keyset_and_cursor_are_explicit_strict_alternatives -->
+<!-- tested: tests/keyset_fast_test.py::test_omitted_execution_defaults_to_auto -->
 ```python
-from b24api import AutoKeysetExecution, KeysetSpec, ParameterPath, StableIntegerKeysetContract
+from b24api import KeysetSpec, ParameterPath
 
 stream = client.iter_list_keyset(
     Request("example.item.list", replay_safety=ReplaySafety.SAFE),
@@ -232,7 +267,6 @@ stream = client.iter_list_keyset(
         filter_path=ParameterPath(("filter",)),
         order_path=ParameterPath(("order",)),
     ),
-    execution=AutoKeysetExecution(contract=StableIntegerKeysetContract()),
 )
 ```
 
@@ -261,6 +295,11 @@ 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.
@@ -271,6 +310,8 @@ contracts and selection guidance.
 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.1.0 → b24api-2.2.0}/b24api/__init__.py

@@ -2,6 +2,7 @@
 
 from b24api.client import Bitrix24
 from b24api.contracts import (
+    AdaptedPage,
     AmbiguityPolicy,
     AmbiguityReason,
     AutoKeysetExecution,
@@ -25,27 +26,39 @@ from b24api.contracts import (
     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,
@@ -99,6 +112,9 @@ from b24api.errors import (
     IdentityContractError,
     IncompleteTraversalError,
     InputSourceError,
+    KeysetCapabilityError,
+    PageAdaptationError,
+    PageAdaptationViolation,
     PaginationError,
     ProtocolError,
     ReferenceFailed,
@@ -110,6 +126,7 @@ from b24api.settings import Settings
 from b24api.transport import Transport, TransportCapabilities, WireRequest, WireResponse, WireTransport
 
 __all__ = [
+    "AdaptedPage",
     "AmbiguityPolicy",
     "AmbiguityReason",
     "AmbiguousExecutionError",
@@ -142,31 +159,46 @@ __all__ = [
     "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",

{b24api-2.1.0 → b24api-2.2.0}/b24api/_client_traversal.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 from typing import TYPE_CHECKING
 
-from b24api.contracts.keyset_execution import KeysetExecution, SequentialKeysetExecution
+from b24api.contracts.keyset_execution import AutoKeysetExecution, KeysetExecution, StableIntegerKeysetContract
+from b24api.contracts.page import IdentityPageAdapter, PageAdapter
 from b24api.contracts.request import IdentitySpec, RequestLike, ResultSelector, TraversalIdentity, canonical_request
 from b24api.contracts.response import ResultCollectionShape
 from b24api.contracts.traversal import CursorSpec, KeysetSpec, OffsetSpec, TotalTermination
@@ -21,7 +22,8 @@ _ROOT_SELECTOR = ResultSelector.root()
 _DEFAULT_OFFSET = OffsetSpec()
 _DEFAULT_COUNTED_OFFSET = OffsetSpec(total_termination=TotalTermination.EXACT_QUALIFIED)
 _DEFAULT_KEYSET = KeysetSpec()
-_DEFAULT_SEQUENTIAL_KEYSET_EXECUTION = SequentialKeysetExecution()
+_DEFAULT_AUTO_KEYSET_EXECUTION = AutoKeysetExecution(StableIntegerKeysetContract())
+_IDENTITY_PAGE_ADAPTER = IdentityPageAdapter()
 
 
 class _TraversalFacade:
@@ -51,6 +53,7 @@ class _TraversalFacade:
         collection_shape: ResultCollectionShape = ResultCollectionShape.SEQUENCE,
         page_size: int = 50,
         offset: OffsetSpec = _DEFAULT_OFFSET,
+        page_adapter: PageAdapter = _IDENTITY_PAGE_ADAPTER,
         policy: ExecutionPolicy | None = None,
     ) -> OperationStream[JsonValue]:
         """Return conservative sequential offset/server-next traversal."""
@@ -66,6 +69,7 @@ class _TraversalFacade:
                 collection_shape=collection_shape,
                 page_size=page_size,
                 offset=offset,
+                page_adapter=page_adapter,
                 policy=policy or self._default_policy,
                 deregister=self._discard_stream,
                 audit_violations=(() if audit_violation is None else (audit_violation,)),
@@ -82,6 +86,7 @@ class _TraversalFacade:
         page_size: int = 50,
         batch_size: int | None = None,
         offset: OffsetSpec = _DEFAULT_COUNTED_OFFSET,
+        page_adapter: PageAdapter = _IDENTITY_PAGE_ADAPTER,
         policy: ExecutionPolicy | None = None,
     ) -> OperationStream[JsonValue]:
         """Return exact direct-head plus physically batched counted traversal."""
@@ -98,6 +103,7 @@ class _TraversalFacade:
                 page_size=page_size,
                 batch_size=batch_size,
                 offset=offset,
+                page_adapter=page_adapter,
                 policy=policy or self._default_policy,
                 deregister=self._discard_stream,
                 audit_violations=(() if audit_violation is None else (audit_violation,)),
@@ -113,10 +119,11 @@ class _TraversalFacade:
         collection_shape: ResultCollectionShape = ResultCollectionShape.SEQUENCE,
         page_size: int = 50,
         keyset: KeysetSpec = _DEFAULT_KEYSET,
-        execution: KeysetExecution = _DEFAULT_SEQUENTIAL_KEYSET_EXECUTION,
+        execution: KeysetExecution = _DEFAULT_AUTO_KEYSET_EXECUTION,
+        page_adapter: PageAdapter = _IDENTITY_PAGE_ADAPTER,
         policy: ExecutionPolicy | None = None,
     ) -> OperationStream[JsonValue]:
-        """Return exact sequential no-count keyset traversal."""
+        """Return automatic no-count keyset traversal with explicit execution override."""
         self._require_open()
         canonical = canonical_request(request)
         audit_violation = self._audit_unknown(canonical)
@@ -130,6 +137,7 @@ class _TraversalFacade:
                 page_size=page_size,
                 keyset=keyset,
                 execution=execution,
+                page_adapter=page_adapter,
                 policy=policy or self._default_policy,
                 deregister=self._discard_stream,
                 audit_violations=(() if audit_violation is None else (audit_violation,)),
@@ -145,6 +153,7 @@ class _TraversalFacade:
         identity: IdentitySpec | None = None,
         collection_shape: ResultCollectionShape = ResultCollectionShape.SEQUENCE,
         page_size: int = 50,
+        page_adapter: PageAdapter = _IDENTITY_PAGE_ADAPTER,
         policy: ExecutionPolicy | None = None,
     ) -> OperationStream[JsonValue]:
         """Return strict dependent cursor traversal with empty confirmation."""
@@ -160,6 +169,7 @@ class _TraversalFacade:
                 identity=identity,
                 collection_shape=collection_shape,
                 page_size=page_size,
+                page_adapter=page_adapter,
                 policy=policy or self._default_policy,
                 deregister=self._discard_stream,
                 audit_violations=(() if audit_violation is None else (audit_violation,)),

{b24api-2.1.0 → b24api-2.2.0}/b24api/cli.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING, NoReturn, TextIO
 from b24api import (
     B24ApiError,
     Bitrix24,
+    KeysetCapabilityError,
     ReplaySafety,
     Request,
     Response,
@@ -20,10 +21,12 @@ from b24api import (
 from b24api.cli_contract import (
     CliUsageError,
     ListContractRoute,
+    VerifyKeysetContractRoute,
     cli_request,
     default_contract,
     list_stream,
     parse_list_contract,
+    parse_verify_keyset_contract,
     read_json_source,
 )
 
@@ -37,6 +40,8 @@ _USAGE = 2
 _UNAVAILABLE = 3
 _CORRECTNESS = 4
 _OUTPUT_CLOSED = 5
+_KEYSET_UNSUPPORTED = 6
+_KEYSET_INCONCLUSIVE = 7
 _INTERRUPTED = 130
 
 
@@ -119,6 +124,10 @@ def _parser() -> argparse.ArgumentParser:
         help="traversal mechanics (default: sequential)",
     )
     listing.add_argument("--contract", help="closed v1 traversal contract as @file or -")
+    verify = subparsers.add_parser("verify-keyset", help="verify strict keyset bounds for one portal method")
+    verify.add_argument("method", help="Bitrix24 REST method name")
+    verify.add_argument("--params", help="JSON object, @file, or - for stdin")
+    verify.add_argument("--contract", required=True, help="closed v1 verifier contract as @file")
     return parser
 
 
@@ -168,7 +177,20 @@ async def _list(
         raise RuntimeError("list traversal did not complete successfully")
 
 
-def main(  # noqa: PLR0911 - stable process-code boundary
+async def _verify_keyset(request: Request, route: VerifyKeysetContractRoute, stdout: TextIO) -> None:
+    async with Bitrix24() as client:
+        report = await client.verify_keyset_capability(
+            request,
+            selector=route.selector,
+            identity=route.identity,
+            collection_shape=route.collection_shape,
+            page_size=route.page_size,
+            keyset=route.keyset,
+        )
+    _write_json(stdout, report.to_dict())
+
+
+def main(  # noqa: C901, PLR0911, PLR0912 - stable process-code boundary
     argv: Sequence[str] | None = None,
     *,
     stdin: TextIO | None = None,
@@ -185,11 +207,16 @@ def main(  # noqa: PLR0911 - stable process-code boundary
         if args.command == "call":
             request = cli_request(args.method, params, ReplaySafety(args.replay_safety))
             asyncio.run(_call(args, request, output_stream))
-        else:
+        elif args.command == "list":
             contract = default_contract(args.strategy, args.contract, input_stream)
             route = parse_list_contract(args.strategy, contract)
             request = cli_request(args.method, params, ReplaySafety.UNKNOWN)
             asyncio.run(_list(request, route, output_stream, error_stream))
+        else:
+            contract = default_contract("verify-keyset", args.contract, input_stream)
+            verify_route = parse_verify_keyset_contract(contract)
+            request = cli_request(args.method, params, ReplaySafety.UNKNOWN)
+            asyncio.run(_verify_keyset(request, verify_route, output_stream))
     except KeyboardInterrupt:
         return _INTERRUPTED
     except SystemExit as error:
@@ -199,6 +226,12 @@ def main(  # noqa: PLR0911 - stable process-code boundary
         return _USAGE
     except BrokenPipeError:
         return _OUTPUT_CLOSED
+    except KeysetCapabilityError as error:
+        try:
+            _write_json(output_stream, error.report.to_dict())
+        except BrokenPipeError:
+            return _OUTPUT_CLOSED
+        return _KEYSET_UNSUPPORTED if error.verdict.value == "unsupported" else _KEYSET_INCONCLUSIVE
     except B24ApiError as error:
         _write_json(error_stream, _safe_error(error))
         return _CORRECTNESS

{b24api-2.1.0 → b24api-2.2.0}/b24api/cli_contract.py

@@ -19,6 +19,7 @@ from b24api import (
     RangeKeysetExecution,
     ReplaySafety,
     Request,
+    ResultCollectionShape,
     ResultSelector,
     SequentialKeysetExecution,
     StableIntegerKeysetContract,
@@ -32,7 +33,7 @@ if TYPE_CHECKING:
 
 _CONTRACT_VERSION = 1
 _PORTAL_BATCH_CAP = 50
-_SEQUENTIAL_KEYSET_EXECUTION = SequentialKeysetExecution()
+_DEFAULT_AUTO_KEYSET_EXECUTION = AutoKeysetExecution(StableIntegerKeysetContract())
 
 
 class CliUsageError(ValueError):
@@ -220,10 +221,10 @@ def _keyset(raw: object) -> KeysetSpec:
 def parse_keyset_execution(payload: Mapping[str, JsonValue] | None) -> KeysetExecution:
     """Parse the closed per-call keyset execution object."""
     if payload is None:
-        return SequentialKeysetExecution()
+        return _DEFAULT_AUTO_KEYSET_EXECUTION
     if not isinstance(payload, dict):
         raise CliUsageError("execution must be an object")
-    kind = payload.get("kind", "sequential")
+    kind = payload.get("kind", "auto")
     if not isinstance(kind, str):
         raise CliUsageError("execution.kind must be a string")
     if kind not in {"sequential", "range", "partitioned", "auto"}:
@@ -309,7 +310,42 @@ class ListContractRoute:
     identity: IdentitySpec | None
     page_size: int
     mechanics: OffsetSpec | KeysetSpec | CursorSpec
-    execution: KeysetExecution = _SEQUENTIAL_KEYSET_EXECUTION
+    execution: KeysetExecution = _DEFAULT_AUTO_KEYSET_EXECUTION
+
+
+@dataclass(frozen=True, slots=True)
+class VerifyKeysetContractRoute:
+    """Fully validated explicit keyset-verifier contract."""
+
+    selector: ResultSelector
+    identity: IdentitySpec
+    keyset: KeysetSpec
+    collection_shape: ResultCollectionShape = ResultCollectionShape.SEQUENCE
+    page_size: int = _PORTAL_BATCH_CAP
+
+
+def parse_verify_keyset_contract(contract: dict[str, object]) -> VerifyKeysetContractRoute:
+    """Validate the closed v1 verifier wire contract."""
+    _closed(
+        contract,
+        {"version", "selector", "identity", "keyset", "collection_shape", "page_size"},
+        label="verify-keyset contract",
+    )
+    selector, page_size = _common(contract, selector_required=True)
+    identity = _identity(contract.get("identity"), required=True)
+    try:
+        shape = ResultCollectionShape(
+            cast("str", contract.get("collection_shape", ResultCollectionShape.SEQUENCE.value)),
+        )
+    except (TypeError, ValueError) as error:
+        raise CliUsageError("collection_shape is invalid") from error
+    return VerifyKeysetContractRoute(
+        selector,
+        cast("IdentitySpec", identity),
+        _keyset(contract.get("keyset")),
+        shape,
+        page_size,
+    )
 
 
 def parse_list_contract(strategy: str, contract: dict[str, object]) -> ListContractRoute:
@@ -390,11 +426,13 @@ __all__ = [
     "CliUsageError",
     "KeysetExecutionJson",
     "ListContractRoute",
+    "VerifyKeysetContractRoute",
     "cli_request",
     "decode_one_object",
     "default_contract",
     "list_stream",
     "parse_keyset_execution",
     "parse_list_contract",
+    "parse_verify_keyset_contract",
     "read_json_source",
 ]