[jasper-yl]

Which issue or RFC does this PR close?

Closes #2405. The design choices are the two described in this comment.

Rationale for this change

prepare refused to combine include_reuse with include_code, so the gateway, which only injects values that carry a reuse proof, could never inject code context. A proof for code needs its own dependency record, because code goes stale when repository files change, not when Artifact revisions change. Code evidence already carries what that record needs: the path, the file digest and the index fingerprint.

What changes are included in this PR?

Core

• context_reuse.py: a reuse proof now records one dependency per cited code file: {path, file_sha256, fingerprint}, deduplicated by path and sorted.
  • Code from another Scope is rejected (context-reuse-cross-scope-unsupported).
  • Code files and Atomic Memory roots share MAX_REUSE_DEPENDENCIES.
  • Both issuing and validating a proof call _current_code. It fails closed with context-reuse-source-changed when a cited file now has another digest, is missing, or would no longer be indexed. It fails with context-reuse-code-unavailable when the Scope has no usable code configuration or repository.
  • Proofs issued before this change have no code field and cite no code, so they validate as before.
• code/capture.py: worktree_digests reads only the listed files, with the same no-follow path walk, exclusion rules and content rules as a capture. CodeService.file_digests and ScopedCodeApplication.file_digests expose it.
  • Validation compares the cited files only, not the whole index fingerprint. An agent's edit elsewhere in the repository, or a rebuilt index, therefore leaves a proof valid; an edit to a cited file does not.
• application.py: the include_reuse + include_code rejection is removed, and the Scope's code application is passed to proof issue and validation. check already reports a failed proof as a context-refresh-required withhold.
• Docs: context-protection.md (English and Chinese) describes the code dependency.
• release/upgrade-support.json: src/powercontext/builtin/code is a managed persistence input, so the compatibility review is re-signed. The added sentence states that the change is a read-only lookup and leaves the index cache layout, manifest, graph rows, publication journal, SQL layout, migration resources and checksums unchanged.

Gateway

• PC_GATEWAY_INJECTION_CODE=on sets include_code on prepare. It is off by default, and the assembly stays memory_only.

• Executor::run: when before_send withholds a request that carried an injection, with context-refresh-required, the executor:

  1. drops that conversation's replay entry (ReplayCache::forget);
  2. restarts from the pre-injection request, prepares once more and checks again.

  A request refreshes at most once. A second refresh-required withhold, or one for a request without an injection, is returned as before. For code reuse this means one preparation per user message, plus one each time a cited source changes.

• Docs: deploy-server.md (English and Chinese) and gateway/README.md.

Not changed: the API contract text. The include_reuse description in openapi/powercontext.yaml still says code is rejected. Editing it moves the normalized contract digest, and the bundled Desktop contract then needs a newly qualified compatibility.json profile: a wheel built at the change and desktop/tests/real_server.py run in all four modes, which needs the Tauri toolchain. The description therefore stays stale until the next digest-moving change. The replacement text is in the review thread.

Are there any user-facing changes?

• prepare with include_reuse and include_code now returns a proof instead of context-reuse-code-unsupported.
• The gateway has a new opt-in, PC_GATEWAY_INJECTION_CODE.
• A stale replayed injection no longer reaches the client as a withhold; the gateway prepares again.

Deployments that change none of these settings behave as before.

How was this change tested?

• Core, against a real git repository and code index (tests/builtin/runtime/test_code_context_reuse.py):

  • test_code_reuse_revalidates_cited_files_only:
    • a proof citing budget.py validates;
    • editing an uncited file and rebuilding the index keep it valid;
    • editing the cited file fails with source-changed, and restoring its bytes makes it valid again;
    • removing the cited file fails with source-changed;
    • moving the repository away fails with code-unavailable.
  • test_code_reuse_is_bound_to_its_scope.
  • test_code_dependencies_stay_in_scope_and_within_the_bound: a cross-Scope origin, and MAX_REUSE_DEPENDENCIES + 1 files.

• The existing reuse test asserted the old rejection; it now checks that without a code index the proof simply cites no code.

• make check (lock, hooks, ruff, ty, upgrade policy) passes. pytest on the reuse, prepared-context, context-check and native-code suites: 182 passed, 3 skipped.

• Gateway: cargo fmt, clippy -D warnings and cargo test: 136 passed.

  • a_stale_reuse_proof_drops_the_replay_and_prepares_once_more: three steps of one tool loop. The replay that turns stale is withheld, prepared again and sent with the new value; the stale value is never sent, and the next step replays the new value.
  • a_request_refreshes_at_most_once.
  • refresh_required_without_an_injection_is_withheld_directly.
  • code_evidence_is_requested_only_when_enabled.

  With the refresh branch disabled, the first two fail.

• End to end with a Server and a gateway built from this branch, on a git repository bound to the Scope and indexed with powercontext code index, and a scripted Responses upstream. The client was simulated with curl: one conversation (X-PowerContext-Conversation-ID) whose user message asks about the indexed function, followed by tool continuations.

  Request	Between requests	prepare_context	check_context	Code in the upstream body
  1	(none)	1	2	original budget.py
  2	nothing changed	0 (replay)	2	original
  3	cited file edited, index rebuilt	1	3 (refresh withhold, send, release)	edited version only
  4	cited file edited, index not rebuilt	1	3	none (the stale index serves no code); request still released

  All four requests returned 200. The code-reuse benchmark and safety validation you offered in feat(context): let reuse proofs cover code evidence, so the gateway can inject code context #2405 are not part of this PR.

AI usage statement

Built with Claude Code (Claude Opus 5.5), which wrote the change, the tests and the docs, and ran the checks above.

🤖 Generated with Claude Code

[AlexStocks]

P2: the machine-readable contract still says include_reuse rejects code.

Removing this guard is the point of the PR, but openapi/powercontext.yaml is not part of the change set and at this head it still states, on the include_reuse request field:

Return a versioned context and reuse envelope. Supported for single-Scope Atomic Memory with complete bounded dependencies; unsupported selected families, code, or references are rejected explicitly.

That sentence is false at 02bd987c: prepare_reuse/validate_reuse accept code dependencies (context_reuse.py:80, :194), application.py no longer raises context-reuse-code-unsupported, and the new prose in docs/{en,zh}/docs/operate/context-protection.md says the opposite ("The reuse profile supports a single Scope, selected Atomic Memory, and code evidence (include_code: true)" / 中文版第 46 行). Two files in the same PR series now describe the same flag incompatibly, and the contract one is the older, wrong one. context-reuse-code-unavailable and context-reuse-source-changed are also unlisted there, while the doc enumerates when each fires.

Consequences beyond wording:

• openapi/powercontext.yaml is the source for the published API reference, so clients keep modelling include_reuse + include_code as rejected and will not send the combination.
• The file is also the digest input for the bundled Desktop contract: desktop/src-tauri/src/transport/operations.json contractSha256 equals sha256(LF(openapi/powercontext.yaml)) (verified: this branch's openapi hashes to the recorded value). A prose-only edit therefore moves that digest too, which is presumably why it was left alone; the churn is deferred, not avoided, and the next PR that touches openapi inherits the wrong sentence.
• No check catches this: make api-generate-check / js-api-generate-check compare generated code against the same file, so description drift is invisible.

Minimum fix: replace the code mention with what the proof now records per cited file ({path, file_sha256, fingerprint}, validated against the current worktree) and regenerate the Desktop contract digest in the same commit, or record in the PR why the contract stays stale until the next digest-moving change.

[jasper-yl]

Thanks, you're right that the contract and the docs now disagree. I left openapi/powercontext.yaml alone for the reason you guessed, and I should have said so in the PR.

Changing that description moves the normalized contract digest. That needs a new qualified Desktop profile in compatibility.json for the new digest: a wheel built at the PR commit and desktop/tests/real_server.py run against it in all four modes, as for sqlite-atomic-112db11e-v1. That run builds the Tauri server_probe example, which I can't build in this environment (no GTK/WebKit toolchain). Only updating operations.json/operations.ts would fail test_bundled_desktop_contract_has_a_qualified_business_profile.

So I've recorded in the PR description that the contract text stays stale until the next digest-moving change, with the exact replacement:

Return a versioned context and reuse envelope. Supported for a single Scope with complete bounded dependencies: selected Atomic Memory, and code evidence recorded per cited file as path, file digest and index fingerprint and validated against the current worktree (context-reuse-source-changed, context-reuse-code-unavailable). Unsupported selected families or references are rejected explicitly.

If you'd rather have it in this PR, I'm happy to make the change, provided a maintainer can run the Desktop qualification for the resulting commit, or I can open an issue so the next contract change picks it up.

[hidb4ai]

Rechecked at 2d324ac48: both runtime findings from my review are fixed in the original real-Git/SQLite scenarios. This existing documentation gap remains: the include_reuse description in openapi/powercontext.yaml and the generated Python request model still says code is rejected, while the runtime now accepts it.

Documentation follow-up (non-blocking): please track the source-contract correction together with the required generated artifacts and Desktop qualification. The PR-body explanation records why it is deferred, but the published API guidance consumed by clients still needs that correction.

[jasper-yl]

Thanks for rechecking. Tracked in #2431, with the replacement text and the generation and Desktop qualification steps, so the next digest-moving contract change can include it.

[AlexStocks]

对照 #2431 的修复步骤做了一次核对，供后续跟进参考：该 issue 的 Steps to fix 已覆盖本次改动需要的全部四步——改 openapi/powercontext.yaml 的 include_reuse 描述、make api-generate / make js-api-generate / pnpm --dir desktop generate、为新契约摘要补 Desktop 资格记录与 desktop/VALIDATION.md 证据、make contract-test。也就是说契约冲突的修复路径是完整的，缺的只是"移动摘要"这个时机。

因此本线程保持打开直到 #2431 落地即可，不需要在本 PR 内先改描述：本 PR 现在只留下"文档与 openapi 说法相反"这一处不一致，源码侧（prepare 记录、check 复验、file_digests 读工作区而非索引）已在上一轮核对通过。

[frf12]

@jasper-yl Please keep this work on the feat/code-context-reuse feature branch for now and do not merge it into master. We will run the code-reuse benchmark and safety validation on our side, and consider merging into master only after those are complete and we have reviewed the results.

[hidb4ai]

I reproduced two code-reuse contract failures at this head: ineligible Git paths remain reusable, and mixed provenance can exceed the shared dependency limit. Details inline.

[hidb4ai]

[P2] Honor Git inventory eligibility when revalidating cited files

With the default include_untracked=False, prepare a proof citing tracked src/sample/budget.py, then run git rm --cached src/sample/budget.py, add that path to .gitignore, and rebuild the index. A fresh prepare omits the file, but validate_reuse still succeeds and enforcing before_send returns allow for the old code. _excluded checks configured patterns and content rules; this lookup never checks the tracked/untracked/ignore eligibility used by capture. Consequently a no-longer-indexable file remains reusable until expiry, contrary to the documented source_ineligible behavior. Recheck the current Git eligibility of the cited paths and invalidate their proofs when they become ineligible, while preserving reuse across unrelated file changes.

[jasper-yl]

Thanks, confirmed. Fixed in 2d324ac. worktree_digests now checks the cited paths against the same _inventory the capture uses (tracked files, plus untracked and not ignored ones when include_untracked is set), and refuses symlinks and submodules as the capture does. Your scenario (git rm --cached, add to .gitignore, rebuild) now fails with context-reuse-source-changed even though the bytes are unchanged; it is test_a_cited_file_that_leaves_the_git_inventory_stops_reuse against a real repository and index. Unrelated file changes still keep the proof valid.

[hidb4ai]

[P2] Count the complete Memory snapshot in the shared dependency limit

This counts selected Memory roots, but read_dependency_snapshot also includes their historical ancestors and Source records. In a real SQLite runtime, creating 31 Atomic Memories, merging them into one, and preparing that merged Memory with two cited code files issues and validates a proof containing 63 Memory dependency records plus 2 code records: 65 dependencies. This check sees only 1 + 2; validate_reuse repeats the same root-based check. Enforce the shared 64-dependency limit against the full Memory snapshot plus code dependencies at issuance and validation, so adding code cannot exceed the declared bound.

[jasper-yl]

Thanks, confirmed. Fixed in 2d324ac. The bound is now checked against the complete Atomic Memory snapshot returned by read_dependency_snapshot (ancestors and Sources included) plus the code files, both when the proof is issued and when it is validated. The early root-plus-code check remains as a cheap pre-check. test_the_full_memory_snapshot_and_code_share_the_dependency_bound reproduces one root whose snapshot has 63 records, plus two code files, and gets context-reuse-dependency-limit.

[hidb4ai]

LGTM

[frf12]

@jasper-yl We have completed the benchmark and pushed the experiment branch to frf12/powercontext, commit 331fad2c52a93b0308d587bccc55362cfcc9cc69.

We did not observe a benefit from code graph injection in this tested configuration. The fixed sample contains 66 SWE-bench Pro tasks (11 repositories × 6, seed 2425, not selected by historical solve results). Both arms used gpt-5.6-sol / medium, with memory recall/injection/sedimentation, plugins, Codex memories and web search disabled.

Metric	Code OFF	Code ON
Solved	45/66 (68.18%)	44/66 (66.67%)
Recorded non-cached input tokens	2,840,525	4,905,810
Mean agent time	337.27 s	360.77 s

The one-task solve difference does not establish a stable quality regression. Token figures are known subtotals, with missing usage observations.

The branch includes the runner, fixed cohort, per-case results, experiment patches and recovery instructions. The full report documents the 64 original pairs plus two technical-recovery pairs, all retry costs and the grader-only network recovery.

The tested integration used #2425 at 02bd987c8ff3ed9958e7e49592935ae9d6513912 and #2429 at 84641150e5706d6b6556041fe38ebb3bb0b491fc, plus the documented benchmark patches. The later #2425 commit 2d324ac48bda75812061fdcac7a6a728fa2a278a was not included in this run.

Please review this branch, its configuration and the results, and confirm from your side whether they match the intended behavior.

[jasper-yl]

@frf12 thank you for the careful run and for publishing the branch and data. The configuration matches what #2425 is meant to test in isolation: code evidence through the gateway, with steering, memory, plugins and web search off. Your result agrees with our own data:

• Our measurements. In our Codex runs (feat(context): let reuse proofs cover code evidence, so the gateway can inject code context #2405, feat(gateway): an optional fixed instruction that cuts agent steps, measured at about 0.6× token cost on SWE-bench Pro #2411), code injection alone cost about 1.0–1.2× the plain gateway. Code injection plus the fixed instruction cost 0.61×, the same as the instruction alone (0.61×). The saving came from the instruction (now feat(gateway): add an operator instruction to Responses requests #2421), not from code injection. I should have said that more plainly in feat(context): let reuse proofs cover code evidence, so the gateway can inject code context #2405 instead of presenting the combination.
• Cache-aware cost from your main66.json (uncached input 1, cached input 0.1, output 8): ON/OFF geometric mean 1.18×, in line with our 1.0–1.2×.
• Where the extra cost comes from. ON made only 4.5% more requests (2,510 vs 2,402), so the agent did not take more steps. But non-cached input per request rose 65% (1,955 vs 1,183 tokens), in 57 of 66 tasks. Code injection is losing prompt cache.

My hypothesis for the cache loss is the refresh path I added: when the agent edits a cited file, the next replay fails revalidation, the gateway prepares again, and the injected block in the turn's user message changes. Every byte after it, including the whole tool history, is then uncached. With 234 prepares in total, ON averages roughly two to three per arm against one per turn for OFF, which fits this. The logs would confirm it: count context-refresh-required withholds per ON arm.

So I don't think #2425 should merge as it is. A code-injection design would at least have to keep the conversation's cached prefix intact: check freshness when a value is first injected, and keep replaying that exact value for the rest of the conversation, as the agent's own tool outputs already do, instead of rewriting it. Even then our data shows no gain over the instruction alone. I'd keep #2405 open only for that design question and leave the branch and your results as the reference. I don't think another run is warranted until a design is agreed.

[AlexStocks]

@jasper-yl the github ci action failed.

[hidb4ai]

Re-reviewed unchanged head 2d324ac48 after reading the newly published benchmark and the author’s response. The two earlier correctness findings remain fixed.

Design note (non-blocking): I recommend holding the merge pending an agreed code-injection design and evidence of benefit. The 66-task report shows OFF 45/66 versus ON 44/66, with recorded non-cached input tokens up 72.71%. That one-task difference does not establish a quality regression, and the token figures are incomplete usage subtotals. The run used 02bd987c8 plus documented benchmark patches; the current head was not benchmarked. Refresh-induced prompt-cache loss remains a hypothesis requiring trace confirmation. These results do not currently support an efficiency claim for the feature.

CI is also incomplete: code-seekdb (3.14, 0) was canceled after exceeding the job’s 30-minute limit during migration tests, which failed the aggregate CI result. I found no evidence establishing that timeout as a defect introduced by this PR.

[hidb4ai]

Mergeability update for head 2d324ac48: the current target master (ae1de765) now conflicts in release/upgrade-support.json. I confirmed the content conflict with git merge-tree --write-tree against those exact commits; GitHub also reports CONFLICTING / DIRTY.

Please synchronize with the target branch, resolve the compatibility declaration against the final merged persistence inputs, and rerun the required checks before merging. This merge conflict appeared after the previous review.