b24api 2.4.2__tar.gz → 2.5.0__tar.gz

{b24api-2.4.2/b24api.egg-info → b24api-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: b24api
-Version: 2.4.2
+Version: 2.5.0
 Summary: Bitrix24 API
 Author-email: Shkarupa Alex <shkarupa.alex@gmail.com>
 License-Expression: MIT
@@ -269,6 +269,12 @@ 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.
 
+An endpoint that honors `start` only at a fixed server window and signals its end only with a
+shorter page (no usable `total`, no `next`) can declare that stop rule with
+`OffsetSpec(short_page_termination=ShortPageTermination.DECLARED_TERMINAL)`; its successful
+exhaustion is always `MECHANICS_ONLY`. See
+[Declared short-page closure](https://github.com/shkarupa-alex/b24api/blob/master/docs/recipes.md#declared-short-page-closure).
+
 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.
@@ -469,6 +475,10 @@ async with stream:
             record_completion(event.correlation, event.row_count)
 ```
 
+With `KeysetTraversal`, a binding may also set simple constant fields directly inside the keyset
+filter, such as `filter[=ownerId]`, while each binding keeps its own cursor; see
+[Keyset references with per-owner filters](https://github.com/shkarupa-alex/b24api/blob/master/docs/recipes.md#keyset-references-with-per-owner-filters).
+
 For messages across chats, use the same `iter_references()` shape: each binding updates the chat
 parameter and carries the chat correlation; choose `CursorTraversal` when the message endpoint is
 cursor-based. Identity tracking and completion remain scoped to each binding, so equal child IDs

{b24api-2.4.2 → b24api-2.5.0}/README.md

@@ -238,6 +238,12 @@ 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.
 
+An endpoint that honors `start` only at a fixed server window and signals its end only with a
+shorter page (no usable `total`, no `next`) can declare that stop rule with
+`OffsetSpec(short_page_termination=ShortPageTermination.DECLARED_TERMINAL)`; its successful
+exhaustion is always `MECHANICS_ONLY`. See
+[Declared short-page closure](https://github.com/shkarupa-alex/b24api/blob/master/docs/recipes.md#declared-short-page-closure).
+
 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.
@@ -438,6 +444,10 @@ async with stream:
             record_completion(event.correlation, event.row_count)
 ```
 
+With `KeysetTraversal`, a binding may also set simple constant fields directly inside the keyset
+filter, such as `filter[=ownerId]`, while each binding keeps its own cursor; see
+[Keyset references with per-owner filters](https://github.com/shkarupa-alex/b24api/blob/master/docs/recipes.md#keyset-references-with-per-owner-filters).
+
 For messages across chats, use the same `iter_references()` shape: each binding updates the chat
 parameter and carries the chat correlation; choose `CursorTraversal` when the message endpoint is
 cursor-based. Identity tracking and completion remain scoped to each binding, so equal child IDs

{b24api-2.4.2 → b24api-2.5.0}/b24api/completion/closure.py

@@ -14,6 +14,7 @@ SINGLE_RESPONSE_COMPLETE = "single response complete"
 QUALIFIED_TOTAL_REACHED = "qualified total reached"
 SPARSE_RAW_RANGE_COVERED = "qualified sparse raw range covered"
 ADMITTED_UPPER_BOUNDARY_REACHED = "exact admitted upper boundary reached"
+DECLARED_SHORT_PAGE_REACHED = "declared short page reached"
 
 
 def qualified_closure(terminal_reason: str | None) -> BindingClosure | None:
@@ -27,5 +28,7 @@ def qualified_closure(terminal_reason: str | None) -> BindingClosure | None:
             return BindingClosure.RAW_RANGE_COVERED
         case "exact admitted upper boundary reached":
             return BindingClosure.BOUNDARY_SEEN
+        case "declared short page reached":
+            return BindingClosure.DECLARED_SHORT_PAGE
         case _:
             return None

{b24api-2.4.2 → b24api-2.5.0}/b24api/completion/gate.py

@@ -31,6 +31,7 @@ from b24api.contracts.report import (
     Violation,
     ViolationSeverity,
 )
+from b24api.contracts.traversal import DECLARED_SHORT_PAGE_MINIMUM_WIDTH
 from b24api.contracts.violation import retain_violations
 
 if TYPE_CHECKING:
@@ -114,8 +115,15 @@ def _binding_closure_violation(binding: _Binding, event: BindingTerminal) -> str
             "completion_unknown_binding_claimed_known",
         ),
         (
+            # A declared short-page closure reports a missing page as its own witness failure below.
             binding.last_page_id < 0
-            and closure not in {BindingClosure.CALLER_STOP, BindingClosure.FAILURE, BindingClosure.UNKNOWN},
+            and closure
+            not in {
+                BindingClosure.CALLER_STOP,
+                BindingClosure.FAILURE,
+                BindingClosure.UNKNOWN,
+                BindingClosure.DECLARED_SHORT_PAGE,
+            },
             "completion_terminal_lacks_page_witness",
         ),
         (
@@ -150,10 +158,31 @@ def _binding_closure_violation(binding: _Binding, event: BindingTerminal) -> str
             ),
             "completion_missing_keyset_plan_witness",
         ),
+        (
+            closure is BindingClosure.DECLARED_SHORT_PAGE and not _declared_short_page_witnessed(binding, event),
+            "completion_invalid_declared_short_page_witness",
+        ),
+        (
+            closure is not BindingClosure.DECLARED_SHORT_PAGE and event.declared_short_page_width is not None,
+            "completion_unexpected_declared_short_page_width",
+        ),
     )
     return next((code for failed, code in checks if failed), None)
 
 
+def _declared_short_page_witnessed(binding: _Binding, event: BindingTerminal) -> bool:
+    """Require the last acknowledged page to be non-empty and shorter than the declared window."""
+    width = event.declared_short_page_width
+    rows = binding.last_acknowledged_rows
+    return (
+        type(width) is int
+        and width >= DECLARED_SHORT_PAGE_MINIMUM_WIDTH
+        and binding.acknowledged_pages > 0
+        and rows is not None
+        and 0 < rows < width
+    )
+
+
 class CompletionGate:
     """Accept ordered evidence with O(active bindings + in-flight pages) memory."""
 

{b24api-2.4.2 → b24api-2.5.0}/b24api/completion/recorder.py

@@ -48,9 +48,14 @@ class CompletionSink(Protocol):
 class CompletionRecorder:
     """Emit bounded correlated events in the physical traversal lifecycle."""
 
-    def __init__(self) -> None:
-        """Admit the sole binding before its first possible page dispatch."""
+    def __init__(self, *, declared_short_page_width: int | None = None) -> None:
+        """Admit the sole binding before its first possible page dispatch.
+
+        ``declared_short_page_width`` is the window of a caller-declared short-page closure; it is
+        witnessed only when the binding actually closes on such a page.
+        """
         self.gate = CompletionGate(uuid4().hex)
+        self._declared_short_page_width = declared_short_page_width
         self._sequence = 0
         self._next_page = 0
         self._current: int | None = None
@@ -153,7 +158,14 @@ class CompletionRecorder:
         )
         self._current = None
 
-    def terminal(self, closure: BindingClosure, stream: StreamClosure, *, qualified_total: int | None = None) -> None:
+    def terminal(
+        self,
+        closure: BindingClosure,
+        stream: StreamClosure,
+        *,
+        qualified_total: int | None = None,
+        declared_short_page_width: int | None = None,
+    ) -> None:
         """Settle binding and producer before owned-resource cleanup."""
         self.gate.emit(
             BindingTerminal(
@@ -162,6 +174,7 @@ class CompletionRecorder:
                 binding_id=0,
                 closure=closure,
                 qualified_total=qualified_total,
+                declared_short_page_width=declared_short_page_width,
             )
         )
         self.gate.emit(
@@ -201,7 +214,14 @@ class CompletionRecorder:
             if state is KernelState.CANCELLED
             else StreamClosure.EARLY_CLOSE
         )
-        self.terminal(closure, stream, qualified_total=qualified_total)
+        self.terminal(
+            closure,
+            stream,
+            qualified_total=qualified_total,
+            declared_short_page_width=(
+                self._declared_short_page_width if closure is BindingClosure.DECLARED_SHORT_PAGE else None
+            ),
+        )
 
     def cleanup(self, state: CleanupState) -> None:
         """Finish only after cleanup was observed."""

{b24api-2.4.2 → b24api-2.5.0}/b24api/completion/reference_recorder.py

@@ -64,7 +64,14 @@ class ReferenceCompletionRecorder:
         """Return the active adapter for one admitted binding."""
         return self._bindings[binding_id]
 
-    def terminal(self, binding_id: int, closure: BindingClosure, *, qualified_total: int | None = None) -> None:
+    def terminal(
+        self,
+        binding_id: int,
+        closure: BindingClosure,
+        *,
+        qualified_total: int | None = None,
+        declared_short_page_width: int | None = None,
+    ) -> None:
         """Retire one accounted binding after its final outcome is delivered."""
         self.gate.emit(
             BindingTerminal(
@@ -73,6 +80,7 @@ class ReferenceCompletionRecorder:
                 binding_id=binding_id,
                 closure=closure,
                 qualified_total=qualified_total,
+                declared_short_page_width=declared_short_page_width,
             )
         )
         del self._bindings[binding_id]

{b24api-2.4.2 → b24api-2.5.0}/b24api/contracts/__init__.py

@@ -136,6 +136,7 @@ from b24api.contracts.traversal import (
     PageStride,
     RawTotalSource,
     SequentialTraversal,
+    ShortPageTermination,
     SparseRawBound,
     SplitOrderSpec,
     TotalTermination,
@@ -265,6 +266,7 @@ __all__ = [
     "RouteKind",
     "SequentialKeysetExecution",
     "SequentialTraversal",
+    "ShortPageTermination",
     "SlotContract",
     "SlotShape",
     "SparseRawBound",

{b24api-2.4.2 → b24api-2.5.0}/b24api/contracts/completion.py

@@ -26,6 +26,7 @@ class BindingClosure(StrEnum):
     SINGLE_RESPONSE = "single_response"
     BOUNDARY_SEEN = "boundary_seen"
     KEYSET_PLAN_COVERED = "keyset_plan_covered"
+    DECLARED_SHORT_PAGE = "declared_short_page"
     CALLER_STOP = "caller_stop"
     FAILURE = "failure"
     UNKNOWN = "unknown"
@@ -142,6 +143,7 @@ class BindingTerminal(CompletionEvent):
     closure: BindingClosure
     qualified_total: int | None = None
     qualified_witnesses: int | None = None
+    declared_short_page_width: int | None = None
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)

{b24api-2.4.2 → b24api-2.5.0}/b24api/contracts/reference.py

@@ -13,6 +13,7 @@ if TYPE_CHECKING:
     from collections.abc import Iterable
 
     from b24api.contracts.command import NotExecutedReason
+    from b24api.contracts.completion import BindingClosure
     from b24api.contracts.error_base import B24ApiError
 
 _SUMMARY_MAXIMUM = 256
@@ -83,13 +84,19 @@ class ReferenceItem[C]:
 
 @dataclass(frozen=True, slots=True)
 class ReferenceComplete[C]:
-    """Successful binding terminal, with source-exhaustion evidence distinguished."""
+    """Successful binding terminal, with source-exhaustion evidence distinguished.
+
+    ``closure`` names the witness that ended this binding (for example ``SOURCE_EMPTY`` or
+    ``DECLARED_SHORT_PAGE``); it is excluded from equality and hashing, so comparisons by the
+    other fields keep their meaning, and it is ``None`` only on a value built without it.
+    """
 
     binding_index: int
     correlation: C = field(repr=False)
     row_count: int
     exhausted: bool = True
     stop_reason: str | None = None
+    closure: BindingClosure | None = field(default=None, compare=False)
 
 
 @dataclass(frozen=True, slots=True)

{b24api-2.4.2 → b24api-2.5.0}/b24api/contracts/traversal.py

@@ -23,6 +23,9 @@ _ORDER = ParameterPath(("order",))
 _ROOT_SELECTOR = ResultSelector.root()
 _SEQUENTIAL_KEYSET_EXECUTION = SequentialKeysetExecution()
 _IDENTITY_PAGE_ADAPTER = IdentityPageAdapter()
+# A one-row window has no short page: every non-empty page would be full. The contract, the offset plan and the
+# completion gate all enforce this one bound, so they share this single definition.
+DECLARED_SHORT_PAGE_MINIMUM_WIDTH = 2
 
 
 class OffsetContinuation(StrEnum):
@@ -41,6 +44,22 @@ class TotalTermination(StrEnum):
     EXACT_QUALIFIED = "exact_qualified"
 
 
+class ShortPageTermination(StrEnum):
+    """Whether a short page may end a fixed-step offset traversal.
+
+    Some endpoints honor ``start`` only at a fixed server window, report no usable total and send no
+    ``next``, so the only end signal is a page shorter than that window. The client cannot prove
+    that from the wire: a short page may also mean a truncated or misbehaving response. ``DISABLED``
+    therefore keeps refusing an unexplained short page. ``DECLARED_TERMINAL`` is the caller's own
+    qualification of the endpoint: a non-empty page shorter than the declared window closes the
+    traversal as exhausted. That result proves the declared stop rule was met, not that the
+    snapshot is complete, so its assurance stays ``MECHANICS_ONLY``.
+    """
+
+    DISABLED = "disabled"
+    DECLARED_TERMINAL = "declared_terminal"
+
+
 class CursorDomain(StrEnum):
     """How a cursor control is interpreted by its qualified endpoint."""
 
@@ -161,6 +180,27 @@ def _validate_offset_extensions(spec: OffsetSpec) -> None:  # noqa: C901 - close
             raise ValueError("sparse raw bound requires its declared page_stride")
         if spec.total_termination is not TotalTermination.DISABLED:
             raise ValueError("sparse raw bound owns closure independently of selected count")
+    if spec.short_page_termination is ShortPageTermination.DECLARED_TERMINAL:
+        _validate_declared_short_page(spec)
+
+
+def _validate_declared_short_page(spec: OffsetSpec) -> None:
+    """Admit a declared short-page closure only over one exact fixed wire window."""
+    if (
+        spec.continuation is not OffsetContinuation.FIXED_STEP
+        or spec.total_termination is not TotalTermination.DISABLED
+    ):
+        raise ValueError("declared short-page termination requires fixed-step continuation without a total")
+    if spec.page_index is not None or spec.sparse_raw_bound is not None:
+        raise ValueError("declared short-page termination cannot combine with page_index or a sparse raw bound")
+    stride = spec.page_stride
+    if stride is None:
+        raise ValueError("declared short-page termination requires a qualified page_stride")
+    width = stride.max_decoded_rows
+    if not spec.step == stride.wire_increment == width or width < DECLARED_SHORT_PAGE_MINIMUM_WIDTH:
+        raise ValueError("declared short-page termination requires step equal to one decoded window of at least 2")
+    if stride.requested_wire_limit is not None and stride.requested_wire_limit != width:
+        raise ValueError("declared short-page termination requires a requested wire limit equal to the window")
 
 
 @dataclass(frozen=True, slots=True)
@@ -176,12 +216,14 @@ class OffsetSpec:
     page_index: PageIndex | None = None
     page_stride: PageStride | None = None
     sparse_raw_bound: SparseRawBound | None = None
+    short_page_termination: ShortPageTermination = ShortPageTermination.DISABLED
 
     def __post_init__(self) -> None:
         """Validate offset mechanics and completion semantics."""
-        if not isinstance(self.continuation, OffsetContinuation) or not isinstance(
-            self.total_termination,
-            TotalTermination,
+        if (
+            not isinstance(self.continuation, OffsetContinuation)
+            or not isinstance(self.total_termination, TotalTermination)
+            or not isinstance(self.short_page_termination, ShortPageTermination)
         ):
             raise TypeError("offset controls must use their declared enum types")
         _validate_offset_extensions(self)
@@ -402,6 +444,7 @@ __all__ = [
     "OffsetContinuation",
     "OffsetSpec",
     "SequentialTraversal",
+    "ShortPageTermination",
     "SplitOrderSpec",
     "TotalTermination",
     "TraversalSpec",

{b24api-2.4.2 → b24api-2.5.0}/b24api/references/binding.py

@@ -9,7 +9,7 @@ from b24api._sources import OwnedSource
 from b24api.contracts.command import NotExecutedReason
 from b24api.contracts.json import _freeze_json
 from b24api.contracts.reference import Binding
-from b24api.contracts.traversal import CursorTraversal, TraversalSpec, traversal_control_paths
+from b24api.contracts.traversal import CursorTraversal, KeysetTraversal, TraversalSpec, traversal_control_paths
 from b24api.errors import CapabilityError, InputSourceError, PaginationError
 from b24api.references.outcome import ReferenceRequest
 from b24api.traversal.cursor_domain import validate_cursor_value
@@ -18,6 +18,7 @@ from b24api.traversal.values import _coerce_identity
 
 if TYPE_CHECKING:
     from b24api.contracts.json import JsonValue
+    from b24api.contracts.reference import ParameterUpdate
     from b24api.contracts.report import Violation
     from b24api.contracts.request import ParameterPath, Request
 
@@ -51,12 +52,71 @@ def _overlaps(left: tuple[str | int, ...], right: tuple[str | int, ...]) -> bool
     return left[:shared] == right[:shared]
 
 
+_CONTROL_COLLISION = "binding update collides with a traversal control path"
+_FILTER_COMBINATORS = frozenset({"logic", "and", "or"})
+
+
+def binding_update_conflict(traversal: TraversalSpec, update: ParameterUpdate) -> str | None:
+    """Return a stable local-validation reason, or None when this update may compose.
+
+    Every traversal control path stays exclusive, except that a keyset binding may set one simple
+    sibling field directly inside ``KeysetSpec.filter_path`` (for example ``=ownerId``): the
+    traversal writes only its own cursor key there, so a constant beside it composes with the
+    binding's own cursor. ``traversal_control_paths`` names the containers a traversal writes and
+    does not decide admission.
+    """
+    update_path = _normalized(update.path)
+    filter_path = _normalized(traversal.keyset.filter_path) if isinstance(traversal, KeysetTraversal) else None
+    for control in traversal_control_paths(traversal):
+        normalized = _normalized(control)
+        if normalized != filter_path and _overlaps(update_path, normalized):
+            return _CONTROL_COLLISION
+    if not isinstance(traversal, KeysetTraversal) or filter_path is None or not _overlaps(update_path, filter_path):
+        return None
+    return _keyset_filter_conflict(traversal, update, len(filter_path))
+
+
+def _keyset_filter_conflict(traversal: KeysetTraversal, update: ParameterUpdate, depth: int) -> str | None:
+    """Admit one scalar sibling field of the keyset filter whose name differs from the cursor field."""
+    parts = update.path.path
+    if len(parts) != depth + 1:
+        return "binding may set only a direct field inside the keyset filter"
+    cursor_field = traversal.identity.filter_key
+    if not cursor_field.isidentifier():
+        # An operator-bearing cursor key cannot be compared by field name, so nothing may sit beside it.
+        return "keyset filter key is not a simple field name"
+    field = _filter_field(parts[-1])
+    if field is None or field.casefold() in _FILTER_COMBINATORS:
+        return "binding keyset filter key is not a simple field"
+    if field.casefold() == cursor_field.casefold():
+        return "binding keyset filter key names the cursor field"
+    if not _flat_scalar(update.value):
+        return "binding keyset filter value is not a scalar or a flat scalar list"
+    return None
+
+
+def _filter_field(key: str | int) -> str | None:
+    """Strip a leading filter operator and return the remaining simple field name, if any."""
+    if not isinstance(key, str):
+        return None
+    index = 0
+    while index < len(key) and not (key[index].isalnum() or key[index] == "_"):
+        index += 1
+    field = key[index:]
+    return field if field.isidentifier() else None
+
+
+def _flat_scalar(value: JsonValue) -> bool:
+    if isinstance(value, list):
+        return all(not isinstance(item, dict | list) for item in value)
+    return not isinstance(value, dict)
+
+
 def _validate_binding_controls(binding: Binding[object], traversal: TraversalSpec) -> None:
-    controls = tuple(_normalized(path) for path in traversal_control_paths(traversal))
     for update in binding.updates:
-        update_path = _normalized(update.path)
-        if any(_overlaps(update_path, control) for control in controls):
-            raise ValueError("binding update collides with a traversal control path")
+        reason = binding_update_conflict(traversal, update)
+        if reason is not None:
+            raise ValueError(reason)
 
 
 def _matching_key(mapping: dict[str, JsonValue], requested: str) -> str | None:

{b24api-2.4.2 → b24api-2.5.0}/b24api/references/dispatch.py

@@ -25,6 +25,7 @@ from b24api.references.outcome import (
 
 if TYPE_CHECKING:
     from b24api.contracts.command import NotExecutedReason
+    from b24api.contracts.completion import BindingClosure
     from b24api.contracts.json import FrozenJson, JsonValue
     from b24api.contracts.report import PageRecord, Violation
     from b24api.contracts.request import Request
@@ -83,6 +84,7 @@ class _DoneEvent:
     stopped_reason: str | None = None
     terminal_reason: str | None = None
     qualified_total: int | None = None
+    declared_short_page_width: int | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -106,6 +108,7 @@ class _KernelReferenceComplete:
     reference: ReferenceRequest
     row_count: int
     stopped_reason: str | None = None
+    closure: BindingClosure | None = None
 
 
 @dataclass(frozen=True, slots=True)

{b24api-2.4.2 → b24api-2.5.0}/b24api/references/facade.py

@@ -23,6 +23,7 @@ from b24api.contracts.reference import (
     ReferenceOutcome,
     ReferenceOutcomeUnknown,
 )
+from b24api.contracts.report import TraversalAssurance
 from b24api.contracts.request import (
     IdentitySpec,
     Request,
@@ -35,6 +36,7 @@ from b24api.contracts.traversal import (
     CountedTraversal,
     KeysetTraversal,
     SequentialTraversal,
+    ShortPageTermination,
     TraversalSpec,
 )
 from b24api.errors import (
@@ -221,6 +223,7 @@ class _ReferenceEventMapper:
                 event.row_count,
                 exhausted=event.stopped_reason is None,
                 stop_reason=event.stopped_reason,
+                closure=event.closure,
             )
         context = cast("_BindingContext", event.correlation)
         self._item_indexes.pop(context.index, None)
@@ -256,6 +259,16 @@ class _ReferenceEventMapper:
         )
 
 
+def _reference_assurance(traversal: TraversalSpec) -> TraversalAssurance | None:
+    """Declare mechanics only for a declared short-page closure: it proves the stop rule, not empty later windows."""
+    if (
+        isinstance(traversal, SequentialTraversal)
+        and traversal.offset.short_page_termination is ShortPageTermination.DECLARED_TERMINAL
+    ):
+        return TraversalAssurance.MECHANICS_ONLY
+    return None
+
+
 def _reference_variant(outcome: ReferenceOutcome[object]) -> str:
     if isinstance(outcome, ReferenceItem):
         return "item"
@@ -377,6 +390,7 @@ def reference_stream[C](
         source,
         mapper,
         operation="iter_reference_outcomes" if tolerant else "iter_references",
+        assurance=_reference_assurance(traversal),
         classify=_reference_variant,
         error_mapper=lambda error, report: _reference_error(error, report, mapper),
         error_items=lambda error: _reference_error_items(error, mapper),

{b24api-2.4.2 → b24api-2.5.0}/b24api/references/scheduler.py

@@ -47,6 +47,8 @@ from b24api.references.outcome import (
 )
 from b24api.references.support import (
     _active_limit,
+    _declared_short_page_width,
+    _done_closure,
     _finish_done_completion,
     _finish_task,
     _new_page_records,
@@ -392,6 +394,7 @@ class ReferenceScheduler:
                     run.stopped_reason,
                     driver.terminal_reason,
                     driver.expected_total,
+                    _declared_short_page_width(self.plan, driver.terminal_reason),
                 ),
             )
         except asyncio.CancelledError:
@@ -652,6 +655,7 @@ class ReferenceScheduler:
                     event.work.reference,
                     event.row_count,
                     event.stopped_reason,
+                    _done_closure(event),
                 )
             return
         request = event.work.reference.request

{b24api-2.4.2 → b24api-2.5.0}/b24api/references/support.py

@@ -5,7 +5,7 @@ import asyncio
 import contextlib
 from typing import TYPE_CHECKING
 
-from b24api.completion.closure import qualified_closure
+from b24api.completion.closure import DECLARED_SHORT_PAGE_REACHED, qualified_closure
 from b24api.contracts.completion import BindingClosure
 from b24api.contracts.report import PageRecord, Violation, ViolationSeverity
 from b24api.traversal.plans import (
@@ -33,6 +33,13 @@ def _done_closure(event: _DoneEvent) -> BindingClosure:
     return qualified_closure(event.terminal_reason) or BindingClosure.SOURCE_EMPTY
 
 
+def _declared_short_page_width(plan: ListPlan, terminal_reason: str | None) -> int | None:
+    """Return the declared window a reference's short-page closure is witnessed against, else None."""
+    if isinstance(plan, OffsetSequentialPlan) and terminal_reason == DECLARED_SHORT_PAGE_REACHED:
+        return plan.short_page_width
+    return None
+
+
 def _finish_done_completion(completion: ReferenceCompletionRecorder, event: _DoneEvent) -> None:
     """Retire an acknowledged reference with its qualified closure evidence."""
     completion.binding(event.work.index).complete_omitted_empty()
@@ -41,6 +48,9 @@ def _finish_done_completion(completion: ReferenceCompletionRecorder, event: _Don
         event.work.index,
         closure,
         qualified_total=event.qualified_total if closure is BindingClosure.QUALIFIED_TOTAL else None,
+        declared_short_page_width=(
+            event.declared_short_page_width if closure is BindingClosure.DECLARED_SHORT_PAGE else None
+        ),
     )
 
 

{b24api-2.4.2 → b24api-2.5.0}/b24api/traversal/control_preflight.py

@@ -27,6 +27,9 @@ def _aligned_initial_offset(driver: StrategyContext, plan: OffsetSequentialPlan)
     if stride is not None and initial_offset % stride.server_granularity:
         # The server would silently serve the floor window, repeating or skipping raw rows.
         raise CapabilityError("initial offset must align with the qualified server page granularity")
+    if initial_offset != 0 and OffsetTerminalRule.DECLARED_SHORT_PAGE in plan.terminal:
+        # A declared short page closes only the collection read from its first window.
+        raise CapabilityError("declared short-page traversal must start at offset zero")
     if initial_offset != plan.initial_control and OffsetTerminalRule.QUALIFIED_TOTAL in plan.terminal:
         # The exact total counts the whole collection; a suffix never reaches it and would end incomplete.
         raise CapabilityError(

{b24api-2.4.2 → b24api-2.5.0}/b24api/traversal/driver.py

@@ -14,6 +14,7 @@ from b24api.contracts.policy import (
     ExecutionPolicy,
     IdentityCoercion,
     IdentityRequirement,
+    SnapshotRequirement,
     TotalSemantics,
 )
 from b24api.contracts.report import (
@@ -68,6 +69,7 @@ from b24api.traversal.plans import (
     KeysetTerminalRule,
     ListPlan,
     OffsetSequentialPlan,
+    OffsetTerminalRule,
     SingleResponsePlan,
 )
 from b24api.traversal.sequential import CountedStrategy, OffsetStrategy, SingleResponseStrategy
@@ -391,6 +393,17 @@ class PaginationDriver:
         )
         if isinstance(plan, KeysetPlan) and plan.terminal is KeysetTerminalRule.BOUNDARY_ID_SEEN:
             raise CapabilityError("boundary-id keyset requires an externally reviewed boundary contract")
+        if (
+            isinstance(plan, OffsetSequentialPlan)
+            and OffsetTerminalRule.DECLARED_SHORT_PAGE in plan.terminal
+            and (
+                consistency.total_semantics is not TotalSemantics.IGNORE
+                or consistency.confirmation_policy is not ConfirmationPolicy.NONE
+                or consistency.snapshot_requirement is not SnapshotRequirement.TRAVERSAL_ONLY
+            )
+        ):
+            # A declared short page proves only the endpoint's stop rule, never a total, boundary or snapshot.
+            raise CapabilityError("declared short-page traversal supports only the traversal-only consistency policy")
         return _EffectiveConsistency(
             duplicate_policy,
             total_semantics,

{b24api-2.4.2 → b24api-2.5.0}/b24api/traversal/facade.py

@@ -26,7 +26,7 @@ from b24api.contracts.policy import (
 from b24api.contracts.report import KeysetSelectionSummary, TraversalAssurance, Violation
 from b24api.contracts.request import IdentitySpec, RequestLike, ResultSelector, TraversalIdentity, canonical_request
 from b24api.contracts.request_summary import RouteKind
-from b24api.contracts.traversal import OffsetContinuation, TotalTermination
+from b24api.contracts.traversal import OffsetContinuation, ShortPageTermination, TotalTermination
 from b24api.contracts.wire import BodyEncoding
 from b24api.errors import CapabilityError
 from b24api.traversal.counted import CountedItemStream
@@ -105,7 +105,10 @@ def sequential_stream(  # noqa: PLR0913
     """Compose conservative sequential offset/server-next traversal."""
     ledger = _checked_identity_store(identity_store, identity)
     plan = sequential_offset_plan(offset, page_size=page_size, duplicate_policy=DuplicatePolicy.REPORT)
-    if offset.total_termination is TotalTermination.EXACT_QUALIFIED:
+    if offset.short_page_termination is ShortPageTermination.DECLARED_TERMINAL:
+        # A declared short page proves the endpoint's stop rule, not that later windows are empty.
+        assurance = TraversalAssurance.MECHANICS_ONLY
+    elif offset.total_termination is TotalTermination.EXACT_QUALIFIED:
         assurance = (
             TraversalAssurance.IDENTITY_AND_COUNT_MATCHED if identity is not None else TraversalAssurance.COUNT_MATCHED
         )