Skip to content

test(cache): lock in byte-stability of MCP and protocol payloads#8

Closed
jhonatanjunio wants to merge 1 commit into
mainfrom
feat/p3-cache-stability
Closed

test(cache): lock in byte-stability of MCP and protocol payloads#8
jhonatanjunio wants to merge 1 commit into
mainfrom
feat/p3-cache-stability

Conversation

@jhonatanjunio

Copy link
Copy Markdown
Owner

Closes #7

Summary

Adds regression-guard tests that lock in byte-stability of every squeez surface that lands in Claude's cacheable prefix. With a warm cache the same session costs ~10× less; a silent drift in one of these payloads can quietly destroy that. Now any breaking change must explicitly break a test.

Audit findings

Surface Cacheable? Status
protocol::full_payload() Yes (tool-result text) ✅ Already stable (two &'static str concatenations)
mcp_server::tools_list_response Yes (MCP tools layer) ✅ Already stable apart from JSON-RPC id
mcp_server::initialize_response Yes (MCP handshake) ✅ Already stable apart from id
persona::text(...) Yes (banner content) include_str! constants — pointer-identical
wrap header (# squeez […]) No — each call is a fresh tool-result, suffixed not prefixed n/a, elapsed_ms correctly varies

No code changes were needed — every audited surface is already cache-friendly. This PR is preventive: it ships the tests and doc comments so the next refactor can't silently regress us.

What changed

  • tests/test_cache_stability.rs (179 lines) — 7 byte-equality assertions plus a tiny strip_id helper test.
  • src/commands/protocol.rs::full_payload — doc comment naming the cache-stability requirement.
  • src/commands/mcp_server.rs::tools_list_response and initialize_response — same doc comments referencing the test file.

Test output

running 7 tests
test persona_text_is_identity_stable ... ok
test mcp_initialize_payload_is_stable_modulo_id ... ok
test protocol_payload_constants_are_compile_time_stable ... ok
test strip_id_helper_works ... ok
test protocol_payload_is_byte_stable_across_calls ... ok
test mcp_tools_list_payload_is_stable_modulo_id ... ok
test mcp_protocol_tool_payload_is_stable_across_calls ... ok

test result: ok. 7 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s

Out of scope

  • Server-side cache regressions (e.g. Claude Code bugs that bypass the cache) — outside our control.
  • Banners outside MCP (e.g. init's session-start stdout) — those are message content, not part of the cached prefix; per-session variation is expected.

Claude's prompt cache uses tools -> system -> messages invalidation. Anything
squeez emits into the cacheable layers must be byte-stable across calls, or
the cache (~10x cost reduction) silently dies.

Adds `tests/test_cache_stability.rs` with regression-guard assertions on:
- `protocol::full_payload()` byte-identical across 100 invocations
- `protocol::SQUEEZ_PROTOCOL` + `SQUEEZ_MARKERS_SPEC` compose deterministically
- `persona::text(...)` returns the same &'static str (pointer-equal)
- MCP `tools/list` response identical apart from the JSON-RPC `id`
- MCP `initialize` response identical apart from `id`
- MCP `tools/call` for `squeez_protocol` byte-stable across 20 invocations

Also documents the cache-stability requirement inline on each audited surface
so future contributors know which strings must stay deterministic.

Audit findings: no regressions; all cacheable surfaces already stable. This
PR is preventive — tests fail loudly if anyone introduces drift later.

Closes claudioemmanuel#131

Signed-off-by: Jhonatan Junio <jhonatanjuniocp@gmail.com>
@jhonatanjunio jhonatanjunio force-pushed the feat/p3-cache-stability branch from b2af1d6 to 4f6d43b Compare May 18, 2026 17:12
@jhonatanjunio

Copy link
Copy Markdown
Owner Author

Superseded by upstream PR — moved to claudioemmanuel/squeez. See README of this fork for the upstream link.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

P3: Cache-stability audit — lock in byte-identical MCP and protocol payloads

1 participant