Week 4 Day 9: Bound Tool Evidence

[skyzh]

Why

Large tool results should remain verifiable without consuming the model context on every later step. Day 9 teaches one learner-sized boundary: preserve exact result bytes externally, show the model a bounded identity/digest/preview, and retrieve one explicit byte range through the existing agent loop.

Change

• Add mirrored ArtifactRef, ArtifactStore, and BoundedEvidenceWorkspace course surfaces plus a TODO-only starter.
• Externalize only oversized successful results under store-local content-addressed identities; keep short/error results unchanged.
• Reserve .tool-artifacts/<artifact-id>/bytes/<start>-<end> for fail-closed, UTF-8-aligned half-open range retrieval.
• Emit a runnable default range whose end is at or below the byte cap and on a valid UTF-8 boundary, while independently supplied misaligned ranges still fail.
• Require max_range_bytes >= 4, the maximum UTF-8 code-point width, so every accepted configuration can advertise a nonempty valid range.
• Return the ordinary malformed-path observation when an otherwise shaped reserved path contains a decimal bound beyond Python's integer-conversion limit; never delegate that path to the learner workspace.
• Add 25 focused Day 9 cases, cumulative starter/API guards, and the Day 9 chapter/navigation.
• Preserve all merged Day 1–8 runtime/test bytes except Day 9-owned exports/navigation.

Review

Base 2539f2b789d45a9d6ccb5654744cc40dfdb0e434; head 9404e54e20d167515a2f27a6913fca0229a2cefc; tree 663f2797cd64dc294c03286baafd637de144472e. Exact delta: 12 paths, 1,138 insertions / 17 deletions. The final successor from 1ddae76 changes only reference evidence.py and the Day 9 reference test (25 insertions / 1 deletion); every starter, learner chapter/navigation, accepted learner guard, and unrelated byte is preserved.

Exact-head local gates: 481 passed / 8 intentional skips; cumulative Week 4 + sync 146/146; focused Day 9 + sync 61/61; Ruff, formatting, and diff checks clean. The learner copy is byte-identical: its TODO implementation remains expected-red with 22 failures, while the three shared public validation cases pass. Manual mdBook passes.

The new parameterized course-code regression sends 5,000-digit start and end components through execute, requires the exact short malformed-path observation, and replaces the learner workspace dispatcher with a failure sentinel to prove no fallthrough. Removing the conversion guard independently makes both cases raise raw ValueError. All earlier learner and production mutation controls remain unchanged.

The documented manual Qwen path and all model-facing semantics are unaffected because only malformed reserved-path handling changed. Hosted macOS run 31654000716, job 94304281363, is terminal SUCCESS on the exact head. Four fresh independent reviews are GO on this exact head; all prior-head verdicts remain expired.

AI-Assisted: GPT-5.6 Sol + Forge
Editorial contribution: Sentinel

Reviewed-by: GPT-5.6 Terra + Oracle (consistency)
Reviewed-by: GPT-5.6 Sol + Sage (correctness)
Reviewed-by: GPT-5.6 Sol + Tuner (performance)
Reviewed-by: GPT-5.6 Terra + Scholar (learner)