Skip to content

Commit 8f60e9b

Browse files
earayu符炫炜
andauthored
docs(modularization): D10 spec amendment — back-align §G D10.e cursor error codes to §C.3 canonical (#1710)
Per [D10 spec amendment] thread (Bryce msg=441c5e56 + PM msg=40e98684 + architect 双签): §G D10.e Deliverable summary (line 1115) had 6 SCREAMING_SNAKE codes that did not match §C.3 body's 6 snake_case codes. The §G summary was a drafting slip from the rushed §G decomposition amendment commit (36b5835); §C.3 body remains the canonical source because: 1. Casing — wire format is snake_case to match the rest of the ApeRAG API surface (existing error codes use snake_case in JSON wire format). 2. Granularity — §C.3 body splits invariant violation into 3 distinct codes (cursor_filter_mismatch / cursor_tenant_mismatch / cursor_index_changed) because line 567-571 maps DIFFERENT client recovery paths to each: - cursor_filter_mismatch → client bug, surface to user - cursor_tenant_mismatch → security violation, distinct telemetry - cursor_index_changed → backend ops issue, retry from null Collapsing them into a single cursor_invariant_mismatch would lose this distinction and force clients to over-react. 3. CURSOR_FOREIGN and CURSOR_PAGE_OUT_OF_RANGE in §G summary did not appear in §C.3 body and had no client-recovery path defined — they were drafting noise, not real codes. §G D10.e summary now cites §C.3 verbatim and points readers at the §C.3 body for the client-recovery mapping (single source of truth). Doc-only change. No implementation impact. Unblocks task #97 (D10.e cursor errors.py). Co-authored-by: 符炫炜 <fuxuanwei@apecloud.io>
1 parent 7e4b17f commit 8f60e9b

1 file changed

Lines changed: 1 addition & 1 deletion

File tree

docs/modularization/d10-design-pack.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1112,7 +1112,7 @@ Lane-to-§ mapping is one-to-one with the design pack so reviewers can locate sp
11121112

11131113
#### D10.e — Pagination + cursor contract (§C)
11141114

1115-
- **Deliverable**: opaque base64 cursor + `invariant_hash` field + 6 explicit error codes (`CURSOR_EXPIRED` / `CURSOR_INVARIANT_MISMATCH` / `CURSOR_MALFORMED` / `CURSOR_FOREIGN` / `CURSOR_PAGE_OUT_OF_RANGE` / `CURSOR_VERSION_MISMATCH`); cursor is **never silently reset** — explicit error always.
1115+
- **Deliverable**: opaque base64 cursor + `invariant_hash` field + 6 explicit error codes per §C.3 canonical (`cursor_invalid` / `cursor_expired` / `cursor_filter_mismatch` / `cursor_tenant_mismatch` / `cursor_index_changed` / `cursor_schema_unsupported`); cursor is **never silently reset** — explicit error always. Wire-format casing is **snake_case** to match the rest of the API surface; client-recovery path mapping is in §C.3 body (line 567-571), not duplicated here.
11161116
- **Owner candidate**: @Bryce (canonical caller-migration discipline from #90 round-4 fix-forward; pagination semantics are caller-sensitive) — fallback @cuiwenbo.
11171117
- **Write-set boundary**:
11181118
- `aperag/mcp/cursor/codec.py` + `cursor/invariants.py` + `cursor/errors.py` (new package)

0 commit comments

Comments
 (0)