feat(phase9 #97 D10.e prep): cursor pagination contract + 18 unit tests

Per design pack §C (canonical post-#1710 SSoT):
- aperag/mcp/cursor/codec.py: CursorPayload (sort_key + last_position + invariant_hash + issued_at + ttl_seconds 1h default + server_id + schema_version 1) + base64url JSON encode/decode + is_expired TTL check
- aperag/mcp/cursor/invariants.py: compute_invariant_hash sha256 over (sort_key + filters + collection_id + tenant_id + index_id) deterministic across dict ordering
- aperag/mcp/cursor/schemas.py: PaginationParams (cursor + limit conint 1..200) + PaginationResult[T] generic (items + next_cursor + total_count)
- aperag/mcp/cursor/errors.py: 6 canonical snake_case codes (cursor_invalid / cursor_expired / cursor_filter_mismatch / cursor_tenant_mismatch / cursor_index_changed / cursor_schema_unsupported per §C.3 + #1710 amendment) + CursorError exception + CursorErrorEnvelope wire shape + SILENT_RESET_FORBIDDEN guard
- aperag/mcp/cursor/__init__.py: public surface for D10.c read primitive imports

tests/unit_test/mcp/test_cursor_contract.py:
- 5 codec round-trip / wire format / TTL boundary tests
- 2 invariant_hash determinism + binding sensitivity tests
- 7 error envelope round-trip tests (parametrized over each canonical code) + SILENT_RESET_FORBIDDEN pin
- 4 PaginationParams/PaginationResult shape tests including end-to-end cursor flow

Pending D10.c stub head landing for `aperag/service/pagination.py` integration helper + `tests/e2e_http/hurl/<NN>_d10_pagination.hurl` cross-tool e2e — those are Window 1 work.

Author: Bryce

aperag/mcp/cursor/__init__.py

@@ -0,0 +1,58 @@
+# Copyright 2025 ApeCloud, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""D10.e (#97) opaque cursor pagination contract for MCP read primitives.
+
+Per ``docs/modularization/d10-design-pack.md`` §C — server-issued
+base64 cursor with stability invariants (sort key + filter / tenant
+/ index hash) plus 6 explicit error codes; never silently reset to
+first page (Weston msg=95b07155 hard lock).
+
+Public surface (D10.c read primitives import from here):
+
+* :class:`CursorPayload` — internal cursor structure (server only;
+  client treats wire string as opaque)
+* :func:`encode_cursor` / :func:`decode_cursor` — wire codec
+* :func:`compute_invariant_hash` — stable hash over cursor scope
+  bindings (filters / collection_id / tenant_id)
+* :class:`PaginationParams` / :class:`PaginationResult` — typed
+  request / response generic over the paginated item type
+* :class:`CursorError` + the 6 canonical error codes (pending
+  spec amendment double-sign per architect msg=669db73c — error
+  module loaded after canonical lock)
+
+Search-rank cursor (vector / fulltext score-based) is intentionally
+NOT shared with this module — D10.d carries its own cursor type
+with score-boundary invariants (per design pack §G D10.e Forbidden).
+"""
+
+from aperag.mcp.cursor.codec import (
+    CursorPayload,
+    decode_cursor,
+    encode_cursor,
+)
+from aperag.mcp.cursor.invariants import compute_invariant_hash
+from aperag.mcp.cursor.schemas import (
+    PaginationParams,
+    PaginationResult,
+)
+
+__all__ = [
+    "CursorPayload",
+    "PaginationParams",
+    "PaginationResult",
+    "compute_invariant_hash",
+    "decode_cursor",
+    "encode_cursor",
+]

aperag/mcp/cursor/codec.py

@@ -0,0 +1,106 @@
+# Copyright 2025 ApeCloud, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""D10.e cursor wire codec — opaque base64url-encoded JSON envelope.
+
+Per design pack §C.1: cursor is server-issued, treated by the
+client as an opaque string. This module exposes:
+
+* :class:`CursorPayload` — strongly typed internal structure
+* :func:`encode_cursor` — payload → wire string
+* :func:`decode_cursor` — wire string → payload, raising the
+  appropriate :class:`CursorError` on malformed / expired /
+  unsupported-schema input
+
+The codec is stateless: TTL and invariants live inside the payload
+and are checked at decode time. There is no server-side store —
+that is intentional (§C.0 idempotent + restart-stable).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+# CURSOR_SCHEMA_VERSION bumps when the on-wire payload shape changes
+# in an incompatible way. Decoders treat any `schema_version` they
+# don't know about as `cursor_schema_unsupported` (§C.3) — pending
+# the spec amendment double-sign on the canonical error code names
+# per architect msg=669db73c, the literal raised here is owned by
+# ``aperag.mcp.cursor.errors`` once that module lands.
+CURSOR_SCHEMA_VERSION: int = 1
+
+DEFAULT_TTL_SECONDS: int = 3600  # §C.4 1h default; per-tool override
+
+
+@dataclass
+class CursorPayload:
+    """Server-only structured cursor (never deserialized client-side)."""
+
+    sort_key: str
+    last_position: dict[str, Any]
+    invariant_hash: str
+    issued_at: int
+    server_id: str
+    schema_version: int = CURSOR_SCHEMA_VERSION
+    ttl_seconds: int = DEFAULT_TTL_SECONDS
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def is_expired(self, *, now: int | None = None) -> bool:
+        clock = time.time() if now is None else now
+        return int(clock) >= self.issued_at + self.ttl_seconds
+
+
+def encode_cursor(payload: CursorPayload) -> str:
+    """Encode a CursorPayload to its on-wire base64url JSON form.
+
+    The output is URL-safe and unpadded so it round-trips cleanly
+    through MCP request/response JSON without quoting or escaping.
+    """
+
+    raw = json.dumps(asdict(payload), separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(token: str) -> bytes:
+    pad = "=" * (-len(token) % 4)
+    return base64.urlsafe_b64decode(token + pad)
+
+
+def decode_cursor(token: str) -> CursorPayload:
+    """Decode a wire cursor string back to a CursorPayload.
+
+    On malformed / unsupported / expired input the caller is
+    responsible for raising the canonical CursorError code
+    (``cursor_invalid`` / ``cursor_schema_unsupported`` / etc) —
+    this codec only surfaces structural issues via ValueError /
+    KeyError; the canonical error mapping lives in
+    :mod:`aperag.mcp.cursor.errors` (pending spec amendment lock).
+    """
+
+    raw = _b64url_decode(token)
+    obj = json.loads(raw)
+    return CursorPayload(
+        schema_version=obj["schema_version"],
+        sort_key=obj["sort_key"],
+        last_position=obj["last_position"],
+        invariant_hash=obj["invariant_hash"],
+        issued_at=obj["issued_at"],
+        ttl_seconds=obj.get("ttl_seconds", DEFAULT_TTL_SECONDS),
+        server_id=obj["server_id"],
+        extra=obj.get("extra", {}),
+    )

aperag/mcp/cursor/errors.py

@@ -0,0 +1,95 @@
+# Copyright 2025 ApeCloud, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""D10.e canonical cursor error codes (§C.3 contract).
+
+Per architect canonical lock (msg=77bd1f6a / msg=05063521 /
+#1710) the 6 snake_case codes from design pack §C.3 are the only
+identifiers the wire surface uses; the SCREAMING_SNAKE shorthand
+that appeared in the §G summary was drafting noise and is
+backfilled via #1710.
+
+Each code carries a fixed *client recovery path* (§C.3 lines
+567-571) — collapsing distinct codes (e.g., merging the three
+invariant-mismatch variants into one) would force the client to
+over-react, which is why we keep them split:
+
+* ``cursor_invalid`` / ``cursor_schema_unsupported`` — restart
+  pagination from a null cursor.
+* ``cursor_expired`` — restart pagination.
+* ``cursor_filter_mismatch`` / ``cursor_tenant_mismatch`` —
+  client-side bug; surface to the operator.
+* ``cursor_index_changed`` — backend ops issue; retry from null.
+
+A single :class:`CursorError` exception carries the code; the wire
+mapping happens at the MCP tool boundary (D10.c read primitives /
+D10.d search primitives) where ``CursorError`` is caught and
+re-emitted as the tool's structured error envelope.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+CursorErrorCode = Literal[
+    "cursor_invalid",
+    "cursor_expired",
+    "cursor_filter_mismatch",
+    "cursor_tenant_mismatch",
+    "cursor_index_changed",
+    "cursor_schema_unsupported",
+]
+
+# Anti-pattern guard (§C.3): a server that silently resets to the
+# first page on cursor failure violates the explicit-not-silent
+# contract. Decoders MUST raise CursorError; callers MUST surface
+# the wire envelope rather than swallowing the error and starting
+# a fresh pagination on the user's behalf.
+SILENT_RESET_FORBIDDEN = True
+
+
+class CursorErrorEnvelope(BaseModel):
+    """Wire envelope for cursor errors emitted by D10 tools."""
+
+    code: CursorErrorCode
+    message: str
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class CursorError(Exception):
+    """Raised whenever a cursor cannot be honoured.
+
+    The ``code`` attribute carries one of the six canonical
+    :data:`CursorErrorCode` literals. ``details`` is reserved for
+    server-diagnostic data that is safe to expose to the client
+    (e.g., the offending invariant field name); operator-only
+    diagnostics belong in logs, not in the wire envelope.
+    """
+
+    def __init__(
+        self,
+        code: CursorErrorCode,
+        message: str,
+        *,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code: CursorErrorCode = code
+        self.message: str = message
+        self.details: dict[str, Any] = details or {}
+
+    def to_envelope(self) -> CursorErrorEnvelope:
+        return CursorErrorEnvelope(code=self.code, message=self.message, details=self.details)

aperag/mcp/cursor/invariants.py

@@ -0,0 +1,68 @@
+# Copyright 2025 ApeCloud, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""D10.e cursor stability invariants — sha256 over scope bindings.
+
+Per design pack §C.2 + Weston msg=95b07155 stability requirement, a
+cursor encodes a hash of the bindings that must NOT change for it
+to remain valid:
+
+* ``sort_key`` — primary sort field; switching changes ordering and
+  invalidates last_position.
+* ``filters`` — any user-supplied filter set, including search /
+  list narrowing predicates (mode flags, time windows, tags).
+* ``collection_id`` / ``tenant_id`` — tenancy boundary; reusing a
+  cursor across tenants is a security boundary violation.
+* ``index_id`` (optional) — when paginating against a versioned
+  index, the cursor pins to the index version it was issued
+  against; reindex bumps the id and any cursor with a stale hash
+  fails ``cursor_index_changed``.
+
+The function is intentionally insulated from §C error code naming
+(pending architect canonical lock per msg=441c5e56): callers
+compute the hash here and compare; the *response* mapping into
+``cursor_filter_mismatch`` / ``cursor_tenant_mismatch`` /
+``cursor_index_changed`` lives in ``aperag.mcp.cursor.errors``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def compute_invariant_hash(
+    *,
+    sort_key: str,
+    filters: dict[str, Any],
+    collection_id: str | None,
+    tenant_id: str,
+    index_id: str | None = None,
+) -> str:
+    """Return the canonical sha256 hex digest for these bindings.
+
+    Inputs are normalised via ``json.dumps(sort_keys=True)`` so the
+    hash is stable across dict ordering and Python re-serialisation.
+    """
+
+    payload = {
+        "sort_key": sort_key,
+        "filters": filters,
+        "collection_id": collection_id,
+        "tenant_id": tenant_id,
+        "index_id": index_id,
+    }
+    raw = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()