administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages

Bound paged retrieval responses

Browse source
This commit is contained in:
Andraxion 2026-07-29 06:02:07 -04:00
parent 176b2d2784
commit 529accf858
15 changed files with 1567 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

23
docs/MCP_CONTRACT.md
View file

@ -49,6 +49,20 @@ project `max_results` policy. Omitted limits are still capped. Collection respon
they were truncated. Traversal also reports whether truncation came from the result limit or its
deterministic candidate-edge work budget; it does not scan or materialize the complete edge table.
`docforge_get_context` accepts optional `limit` and `cursor` arguments. Its page is one deterministic
stream containing selected entries first and explicit omission evidence second. The page receipt
reports the returned count, total evidence count, whether another page exists, and an opaque
generation-bound cursor. Packing also observes the configured MCP response limit. An individually
oversized entry advances as a hash-identified `response size limit` omission so pagination cannot
loop; targeted retrieval remains available for that node. The existing three-argument custom
context-provider contract is unchanged because pagination is applied after provider selection.
Version-1 cursors are canonical JSON encoded as base64url with a domain-separated SHA-256
corruption checksum. They are opaque and fail closed, but are not authenticated authorization
tokens. Cursors bind the project, adapter, source generation, operation parameters, collection
hash, and position. A changed generation or collection returns `stale_cursor` with
`restart_pagination`; DocForge never silently restarts at page one or combines generations.
Adapter-backed servers also validate their process-start implementation fingerprint before every
tool. `adapter_restart_required` is stale but not synchronizable. Its remediation is
`restart_project_server`; the current process does not reload project code, update Git staging, or
@ -101,6 +115,15 @@ Changeset listing returns draft and ready work by default. Stale, applied, and a
remain available through an explicit status or history request. Applied and abandoned proposals no
longer participate in overlap conflict detection.
Changeset list, inspection, validation, and diff reads accept optional `limit` and `cursor`
arguments. Direct Python and CLI methods still return their complete legacy result when pagination
is not requested. MCP defaults to bounded pages while preserving the exact changeset hash and
ordered operation sequence. Pages may contain fewer records than requested to remain inside the
response policy. Oversized inspection or validation pages return deterministic operation summaries
with hashes and character counts. An individually oversized diff becomes a sequence of
`canonical_json_chunk` pages; concatenating the ASCII chunks, decoding the JSON, and verifying its
payload hash reconstructs the exact `operations` and `changes` arrays without duplication.
Successful mutations return their existing full result while it fits the configured output limit.
Before any proposal, preview, or canonical mutation, the server verifies that a minimum exact
success receipt can fit. An impossible receipt fails with `result_too_large`,