b24api 2.1.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: b24api
-Version: 2.1.0
+Version: 2.3.0
 Summary: Bitrix24 API
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx[http2]>=0.28.1
+Requires-Dist: httpx[http2]<0.29,>=0.28.1
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: pydantic-settings>=2.10.1
 Dynamic: license-file
@@ -29,10 +29,10 @@ work so its HTTP/2 connection pool and rate state are reused.
 
 <!-- tested: tests/client_v2_test.py::test_call_and_call_response_have_stable_detached_types -->
 ```python
-from b24api import Bitrix24, Request
+from b24api import Bitrix24, Request, RouteKind
 
 async with Bitrix24() as client:
-    profile = await client.call(Request("profile"))
+    profile = await client.call(Request("profile", route=RouteKind.BARE))
 ```
 
 The client owns its default transport. An injected transport remains caller-owned. `aclose()` is
@@ -48,15 +48,17 @@ The operation is explicit and never hides malformed JSON by falling back to byte
 
 <!-- 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))
+from b24api import RouteKind
+archive = await client.call_bytes(Request("example.export.download", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE))
 payload = archive.body
 ```
 
 <!-- tested: tests/client_v2_test.py::test_call_and_call_response_have_stable_detached_types -->
 ```python
+from b24api import RouteKind
 from b24api import ReplaySafety
 
-request = Request("example.item.get", {"id": 7}, ReplaySafety.SAFE)
+request = Request("example.item.get", {"id": 7}, ReplaySafety.SAFE, route=RouteKind.BARE)
 decoded = await client.call(request)
 response = await client.call_response(request)
 ```
@@ -97,11 +99,12 @@ matching a result to the object, file, chat or database row that produced its re
 
 <!-- tested: tests/client_v2_test.py::test_logical_batch_is_unbounded_ordered_and_correlation_is_strictly_off_wire -->
 ```python
+from b24api import RouteKind
 from b24api import Command, CommandSuccess
 
 commands = (
     Command(
-        Request("example.item.get", {"id": item_id}, ReplaySafety.SAFE),
+        Request("example.item.get", {"id": item_id}, ReplaySafety.SAFE, route=RouteKind.BARE),
         correlation=item_id,
     )
     for item_id in source_ids
@@ -139,23 +142,34 @@ 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
+from b24api import RouteKind
 from b24api import IdentityCoercion, IdentitySpec, ResultSelector
 
 identity = IdentitySpec(
@@ -166,7 +180,7 @@ identity = IdentitySpec(
 )
 
 stream = client.iter_list(
-    Request("example.item.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.item.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     identity=identity,
 )
@@ -184,10 +198,11 @@ 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 RouteKind
 from b24api import ResultCollectionShape
 
 stream = client.iter_list(
-    Request("example.dictionary.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.dictionary.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     collection_shape=ResultCollectionShape.MAPPING_VALUES,
 )
@@ -204,8 +219,9 @@ bounded physical batches.
 
 <!-- tested: tests/client_v2_test.py::test_counted_traversal_preserves_frozen_request_shape_and_exact_identity -->
 ```python
+from b24api import RouteKind
 stream = client.iter_list_counted(
-    Request("example.item.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.item.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     identity=identity,
     page_size=50,
@@ -216,35 +232,79 @@ 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.
+Keep the guard beside the traversal, for example under
+`if os.environ.get("ENV") != "PROD":`; set `ENV=PROD` only after qualifying the exact portal,
+credentials, method, request/filter, identity, ordering representation, and page cap.
+
+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
+import os
+
+from b24api import KeysetSpec, ParameterPath, ReplaySafety, Request, ResultSelector, RouteKind
+
+request = Request("example.item.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE)
+selector = ResultSelector(("items",))
+keyset = KeysetSpec(
+    filter_path=ParameterPath(("filter",)),
+    order_path=ParameterPath(("order",)),
+)
+
+if os.environ.get("ENV") != "PROD":
+    # Accepting an ID filter does not prove strict bounds or ordering.
+    await client.verify_keyset_capability(
+        request,
+        selector=selector,
+        identity=identity,
+        page_size=50,
+        keyset=keyset,
+    )
 
 stream = client.iter_list_keyset(
-    Request("example.item.list", replay_safety=ReplaySafety.SAFE),
-    selector=ResultSelector(("items",)),
+    request,
+    selector=selector,
     identity=identity,
-    keyset=KeysetSpec(
-        filter_path=ParameterPath(("filter",)),
-        order_path=ParameterPath(("order",)),
-    ),
-    execution=AutoKeysetExecution(contract=StableIntegerKeysetContract()),
+    page_size=50,
+    keyset=keyset,
 )
 ```
 
@@ -255,10 +315,11 @@ message-list methods.
 
 <!-- tested: tests/client_v2_test.py::test_keyset_and_cursor_are_explicit_strict_alternatives -->
 ```python
+from b24api import RouteKind
 from b24api import CursorSpec, ParameterPath
 
 stream = client.iter_list_cursor(
-    Request("example.message.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.message.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     cursor=CursorSpec(
         parameter_path=ParameterPath(("LAST_ID",)),
@@ -273,6 +334,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,8 +349,11 @@ 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 RouteKind
 from b24api import (
     BatchDispatch,
     Binding,
@@ -305,7 +374,7 @@ bindings = (
 )
 
 stream = client.iter_references(
-    Request("example.comment.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.comment.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     bindings,
     traversal=SequentialTraversal(selector=ResultSelector(("items",)), identity=identity),
     dispatch=BatchDispatch(batch_size=25, concurrency=2),
@@ -325,6 +394,7 @@ under different parents are not conflated.
 
 <!-- tested: tests/client_v2_test.py::test_bound_references_apply_nested_updates_off_wire_and_emit_exact_completion -->
 ```python
+from b24api import RouteKind
 from b24api import (
     Binding,
     CursorSpec,
@@ -346,7 +416,7 @@ chat_bindings = (
 )
 
 messages = client.iter_references(
-    Request("example.message.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.message.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     chat_bindings,
     traversal=CursorTraversal(
         selector=ResultSelector(("items",)),
@@ -389,13 +459,19 @@ and publish the same final report where the Python exception type permits it.
 ## Resource boundaries
 
 `ExecutionPolicy` bounds requests, pages, elapsed time, attempts, decompressed response bytes,
-buffered commands and rows, direct concurrency and active references. The default response ceiling
-is 16 MiB and is enforced while streaming, before JSON decoding.
-
-Sequential and counted exact traversal retain observed identities in memory. There is no database,
-spill file or identity-count refusal. Crossing 100,000 distinct identities emits one
-`RuntimeWarning`; exact tracking continues. Strict keyset and cursor traversal retain only
-monotonic progression state when sufficient.
+buffered commands and rows, retained unordered identity keys, direct concurrency and active
+references. The default response ceiling is 16 MiB and is enforced while streaming, before JSON
+decoding.
+
+Sequential, counted, and multi-reference exact traversal retain at most `max_identity_keys`
+observed identities per operation in memory (100,000 by default). All active reference bindings
+share that ceiling. A page that would exceed it is rejected atomically with typed budget evidence.
+Set a larger finite ceiling when the expected aggregate cardinality is known, or pass
+`identity_store=` to `iter_list`/`iter_list_counted` so a caller-owned `IdentityStore` (for example a
+SQLite table keyed by `identity_store_key(...)`) proves uniqueness while in-process identity memory
+stays bounded by one page; the client never closes that store. Repeated-page detection still keeps
+one short fingerprint per page, so raise `max_pages` deliberately for very long traversals.
+Strict keyset and cursor traversal retain only monotonic progression state when sufficient.
 
 ## CLI
 
@@ -404,10 +480,10 @@ errors go to stderr. Credentials come only from `Settings` and cannot be passed
 
 <!-- tested-console: tests/cli_test.py::test_call_routes_replay_safety_and_keeps_success_data_on_stdout -->
 ```console
-b24api call profile
-b24api call example.item.get --params '{"id":7}' --raw --replay-safety safe
-b24api list example.item.list --params @params.json
-b24api list example.item.list --strategy counted --contract @counted-contract.json
+b24api call profile --route bare
+b24api call example.item.get --route bare --params '{"id":7}' --raw --replay-safety safe
+b24api list example.item.list --route bare --params @params.json
+b24api list example.item.list --route bare --strategy counted --contract @counted-contract.json
 ```
 
 The `--raw` CLI option selects the response envelope; it does not alter the Python API. Advanced

{b24api-2.1.0 → b24api-2.3.0}/README.md

@@ -17,10 +17,10 @@ work so its HTTP/2 connection pool and rate state are reused.
 
 <!-- tested: tests/client_v2_test.py::test_call_and_call_response_have_stable_detached_types -->
 ```python
-from b24api import Bitrix24, Request
+from b24api import Bitrix24, Request, RouteKind
 
 async with Bitrix24() as client:
-    profile = await client.call(Request("profile"))
+    profile = await client.call(Request("profile", route=RouteKind.BARE))
 ```
 
 The client owns its default transport. An injected transport remains caller-owned. `aclose()` is
@@ -36,15 +36,17 @@ The operation is explicit and never hides malformed JSON by falling back to byte
 
 <!-- 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))
+from b24api import RouteKind
+archive = await client.call_bytes(Request("example.export.download", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE))
 payload = archive.body
 ```
 
 <!-- tested: tests/client_v2_test.py::test_call_and_call_response_have_stable_detached_types -->
 ```python
+from b24api import RouteKind
 from b24api import ReplaySafety
 
-request = Request("example.item.get", {"id": 7}, ReplaySafety.SAFE)
+request = Request("example.item.get", {"id": 7}, ReplaySafety.SAFE, route=RouteKind.BARE)
 decoded = await client.call(request)
 response = await client.call_response(request)
 ```
@@ -85,11 +87,12 @@ matching a result to the object, file, chat or database row that produced its re
 
 <!-- tested: tests/client_v2_test.py::test_logical_batch_is_unbounded_ordered_and_correlation_is_strictly_off_wire -->
 ```python
+from b24api import RouteKind
 from b24api import Command, CommandSuccess
 
 commands = (
     Command(
-        Request("example.item.get", {"id": item_id}, ReplaySafety.SAFE),
+        Request("example.item.get", {"id": item_id}, ReplaySafety.SAFE, route=RouteKind.BARE),
         correlation=item_id,
     )
     for item_id in source_ids
@@ -127,23 +130,34 @@ 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
+from b24api import RouteKind
 from b24api import IdentityCoercion, IdentitySpec, ResultSelector
 
 identity = IdentitySpec(
@@ -154,7 +168,7 @@ identity = IdentitySpec(
 )
 
 stream = client.iter_list(
-    Request("example.item.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.item.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     identity=identity,
 )
@@ -172,10 +186,11 @@ 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 RouteKind
 from b24api import ResultCollectionShape
 
 stream = client.iter_list(
-    Request("example.dictionary.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.dictionary.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     collection_shape=ResultCollectionShape.MAPPING_VALUES,
 )
@@ -192,8 +207,9 @@ bounded physical batches.
 
 <!-- tested: tests/client_v2_test.py::test_counted_traversal_preserves_frozen_request_shape_and_exact_identity -->
 ```python
+from b24api import RouteKind
 stream = client.iter_list_counted(
-    Request("example.item.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.item.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     identity=identity,
     page_size=50,
@@ -204,35 +220,79 @@ 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.
+Keep the guard beside the traversal, for example under
+`if os.environ.get("ENV") != "PROD":`; set `ENV=PROD` only after qualifying the exact portal,
+credentials, method, request/filter, identity, ordering representation, and page cap.
+
+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
+import os
+
+from b24api import KeysetSpec, ParameterPath, ReplaySafety, Request, ResultSelector, RouteKind
+
+request = Request("example.item.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE)
+selector = ResultSelector(("items",))
+keyset = KeysetSpec(
+    filter_path=ParameterPath(("filter",)),
+    order_path=ParameterPath(("order",)),
+)
+
+if os.environ.get("ENV") != "PROD":
+    # Accepting an ID filter does not prove strict bounds or ordering.
+    await client.verify_keyset_capability(
+        request,
+        selector=selector,
+        identity=identity,
+        page_size=50,
+        keyset=keyset,
+    )
 
 stream = client.iter_list_keyset(
-    Request("example.item.list", replay_safety=ReplaySafety.SAFE),
-    selector=ResultSelector(("items",)),
+    request,
+    selector=selector,
     identity=identity,
-    keyset=KeysetSpec(
-        filter_path=ParameterPath(("filter",)),
-        order_path=ParameterPath(("order",)),
-    ),
-    execution=AutoKeysetExecution(contract=StableIntegerKeysetContract()),
+    page_size=50,
+    keyset=keyset,
 )
 ```
 
@@ -243,10 +303,11 @@ message-list methods.
 
 <!-- tested: tests/client_v2_test.py::test_keyset_and_cursor_are_explicit_strict_alternatives -->
 ```python
+from b24api import RouteKind
 from b24api import CursorSpec, ParameterPath
 
 stream = client.iter_list_cursor(
-    Request("example.message.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.message.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     cursor=CursorSpec(
         parameter_path=ParameterPath(("LAST_ID",)),
@@ -261,6 +322,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,8 +337,11 @@ 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 RouteKind
 from b24api import (
     BatchDispatch,
     Binding,
@@ -293,7 +362,7 @@ bindings = (
 )
 
 stream = client.iter_references(
-    Request("example.comment.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.comment.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     bindings,
     traversal=SequentialTraversal(selector=ResultSelector(("items",)), identity=identity),
     dispatch=BatchDispatch(batch_size=25, concurrency=2),
@@ -313,6 +382,7 @@ under different parents are not conflated.
 
 <!-- tested: tests/client_v2_test.py::test_bound_references_apply_nested_updates_off_wire_and_emit_exact_completion -->
 ```python
+from b24api import RouteKind
 from b24api import (
     Binding,
     CursorSpec,
@@ -334,7 +404,7 @@ chat_bindings = (
 )
 
 messages = client.iter_references(
-    Request("example.message.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.message.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     chat_bindings,
     traversal=CursorTraversal(
         selector=ResultSelector(("items",)),
@@ -377,13 +447,19 @@ and publish the same final report where the Python exception type permits it.
 ## Resource boundaries
 
 `ExecutionPolicy` bounds requests, pages, elapsed time, attempts, decompressed response bytes,
-buffered commands and rows, direct concurrency and active references. The default response ceiling
-is 16 MiB and is enforced while streaming, before JSON decoding.
-
-Sequential and counted exact traversal retain observed identities in memory. There is no database,
-spill file or identity-count refusal. Crossing 100,000 distinct identities emits one
-`RuntimeWarning`; exact tracking continues. Strict keyset and cursor traversal retain only
-monotonic progression state when sufficient.
+buffered commands and rows, retained unordered identity keys, direct concurrency and active
+references. The default response ceiling is 16 MiB and is enforced while streaming, before JSON
+decoding.
+
+Sequential, counted, and multi-reference exact traversal retain at most `max_identity_keys`
+observed identities per operation in memory (100,000 by default). All active reference bindings
+share that ceiling. A page that would exceed it is rejected atomically with typed budget evidence.
+Set a larger finite ceiling when the expected aggregate cardinality is known, or pass
+`identity_store=` to `iter_list`/`iter_list_counted` so a caller-owned `IdentityStore` (for example a
+SQLite table keyed by `identity_store_key(...)`) proves uniqueness while in-process identity memory
+stays bounded by one page; the client never closes that store. Repeated-page detection still keeps
+one short fingerprint per page, so raise `max_pages` deliberately for very long traversals.
+Strict keyset and cursor traversal retain only monotonic progression state when sufficient.
 
 ## CLI
 
@@ -392,10 +468,10 @@ errors go to stderr. Credentials come only from `Settings` and cannot be passed
 
 <!-- tested-console: tests/cli_test.py::test_call_routes_replay_safety_and_keeps_success_data_on_stdout -->
 ```console
-b24api call profile
-b24api call example.item.get --params '{"id":7}' --raw --replay-safety safe
-b24api list example.item.list --params @params.json
-b24api list example.item.list --strategy counted --contract @counted-contract.json
+b24api call profile --route bare
+b24api call example.item.get --route bare --params '{"id":7}' --raw --replay-safety safe
+b24api list example.item.list --route bare --params @params.json
+b24api list example.item.list --route bare --strategy counted --contract @counted-contract.json
 ```
 
 The `--raw` CLI option selects the response envelope; it does not alter the Python API. Advanced