docs(rfc): add recall sufficiency gate proposal - #1560
Open
AlexStocks wants to merge 3 commits into
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1556
Rationale for this change
prepare_contextis single-pass by construction: one search per participating family, then fit tomax_bytes, thenrender. When that one search under-retrieves, the operation still returns normally — it just delivers fewer items, or a
normal empty result. RFC 1489 gave callers control over which families participate, their order, and a per-family item
limit, but did not address what the Runtime should do when the participating families together return too little to be
useful.
This PR adds the RFC proposing an internal recall sufficiency gate with bounded expansion. It is a documentation-only
change; no runtime behaviour changes here.
What changes are included in this PR?
docs/en/rfcs/0000-recall-sufficiency-gate.md— new RFC.docs/zh/rfcs/0000-recall-sufficiency-gate.md— the Chinese counterpart.The proposal is deliberately narrow:
limittoward the existing Builder ceilings; switch
SearchMemoryRequest.modefrom the hard-codedautotohybrid);max_bytes, never the trust wrapper, neverthe citation form;
unselected family is neither searched nor given output budget;
RecallEfforttrace, following the RFC 0080reranktrace precedent, andstays out of the HTTP v1 response;
Two small observability counters (
truncated_items,dropped_items) are proposed because neither is counted anywheretoday (
prepared_context.py:462-463,prepared_text.py:103-104), and without them an expansion that changed nothingcannot be interpreted honestly.
The RFC also records what it cannot do: there is no time-window or as-of parameter on either
PrepareContextRequestorSearchMemoryRequest, so "relax the time window" — the most common host-side expansion action — is not available in v1and would need its own contract change.
Are there any user-facing changes?
None. This PR adds a design document only. The proposed feature is off by default, keeps
PreparedContext(schema, status, content, content_bytes)unchanged, and requires no OpenAPI change(
make api-generateis not needed).How was this change tested?
Documentation only. Every code reference in the RFC was verified against
masterwhile writing it:PreparedContextBuildercandidate ceilings:src/powercontext/builtin/runtime/prepared_context.py:103-110; theinvariant raises at
:165-169.src/powercontext/builtin/runtime/application.py:727(
_prepare),:814(_recall_scope),:849(mode="auto").prepared_context.py:461-463andsrc/powercontext/builtin/runtime/prepared_text.py:103-104.PreparedContextStatusvalues:src/powercontext/builtin/runtime/models.py:58.tests/builtin/runtime/test_prepared_context.py,tests/e2e/test_builtin_runtime.py,tests/e2e/test_context_text_assembly.py.No build or test command was run for this PR, since it changes no code.
AI usage statement
AI assistance (WorkBuddy, agent mode) was used to draft both RFC documents and to cross-check the code references
above. Design decisions, scope boundaries, and all file/line citations were reviewed and verified against
masterbythe author.