[v0.3.0] cache — add zstd codec layer to the retrieved-docs cache

[ayhammouda]

Closes #46

Acceptance criteria

• python -c 'from mcp_server_python_docs.cache.codec import list_supported; print(list_supported())' prints exactly ['none', 'zstd', 'zstd-dict-v1'] — verified with uv run python -c "from mcp_server_python_docs.cache.codec import list_supported; print(list_supported())".
• uv run pytest tests/cache/test_codec.py -q passes with at least 4 new tests — 5 codec tests pass, covering none, zstd, zstd-dict-v1 with an explicit test dictionary, and prior-version none decode.
• retrieved_docs_cache gains compression TEXT NOT NULL DEFAULT 'none' with checked ALTER TABLE migration — covered by test_legacy_uncompressed_cache_row_migrates_and_reads.
• uv run pytest tests/test_persistent_docs_cache.py -q still passes, with a new restart/default-codec test — 11 passed.
• New writes use one configurable default codec (zstd) and reads dispatch from stored compression — covered by persistent-cache tests and stdio cache smoke.

Validation gate output

$ uv run python -c "import zstandard; print(zstandard.__version__)"
0.25.0

$ uv run ruff check src/ tests/
All checks passed!

$ uv run pyright src/
0 errors, 0 warnings, 0 informations

$ uv run pytest --tb=short -q
305 passed in 22.97s

$ uv run python-docs-mcp-server doctor
All checks passed.

$ uv run pytest tests/test_stdio_smoke.py -q
4 passed in 4.78s

$ uv run pytest tests/cache/test_codec.py tests/test_persistent_docs_cache.py tests/test_mcp_get_docs_cache_smoke.py -q
17 passed in 6.04s

CodeRabbit review

• Blocking: None reported.
• Follow-up: None reported.
• False positive: None reported.
• Availability note: CodeRabbit status check passed, but its PR comment says the review was rate-limited and did not produce line findings.

Why this approach

The issue prescribed a versioned app-level cache codec and transparent old-row reads. This PR keeps the existing result_json column as the payload column, stores encoded bytes there for new rows, adds the compression discriminator, and migrates old tables by adding compression DEFAULT 'none'.

Why this triggered supervisor review

None.

[coderabbitai]

Warning

Review limit reached

@ayhammouda, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 38 minutes and 23 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9d316156-28b7-4662-a845-9e35dfe5bc82

📥 Commits

Reviewing files that changed from the base of the PR and between 13d6381 and af982e2.

📒 Files selected for processing (7)

• src/mcp_server_python_docs/cache/__init__.py
• src/mcp_server_python_docs/cache/codec.py
• src/mcp_server_python_docs/services/persistent_cache.py
• tests/cache/__init__.py
• tests/cache/test_codec.py
• tests/test_mcp_get_docs_cache_smoke.py
• tests/test_persistent_docs_cache.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/46-zstd-cache-codec-v2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ayhammouda]

Heimdall verification for PR #60 at f96e49761ba9435d6d40d14b3a1342995730d972: pass.

Scope/territory checked:

• Changed files are limited to the cache codec package, PersistentDocsCache, and cache-related tests/smoke coverage.
• No forbidden territory touched: no tool API shape, schema.sql, migrations, workflows, pyproject.toml, lockfile, README hero, SECURITY, or governing docs.
• Existing tests were extended, not deleted or weakened.
• Source diff is 149 inserted source lines, below the supervisor-review size trigger.

Commands run locally from a fresh clone checked out to the PR head:

$ uv run python -c "import zstandard; print(zstandard.__version__); from mcp_server_python_docs.cache.codec import list_supported; print(list_supported())"
0.25.0
['none', 'zstd', 'zstd-dict-v1']

$ uv run ruff check src/ tests/
All checks passed!

$ uv run pyright src/
0 errors, 0 warnings, 0 informations

$ uv run pytest --tb=short -q
305 passed in 21.63s

$ uv run python-docs-mcp-server doctor
All checks passed.

$ uv run pytest tests/cache/test_codec.py tests/test_persistent_docs_cache.py tests/test_mcp_get_docs_cache_smoke.py -q
17 passed in 4.75s

$ uv run pytest tests/test_stdio_smoke.py -q
4 passed in 4.01s

Implementation checks:

• retrieved_docs_cache adds compression TEXT NOT NULL DEFAULT 'none' and performs an existence-checked ALTER TABLE for older cache files.
• Reads dispatch through the stored compression value, not the current default codec.
• New writes use the single production default codec zstd.
• Legacy uncompressed rows are covered by test_legacy_uncompressed_cache_row_migrates_and_reads.
• Restart/readback for new compressed writes is covered by test_current_default_codec_reads_identically_after_restart.
• zstd-dict-v1 requires an explicit dictionary and ships no production dictionary artifact, matching issue scope.
• Cache read/write failures remain best-effort and are handled as cache misses/skipped writes.

GitHub checks observed green: CI matrix, Security Audit dependency audit, CodeQL, and CodeRabbit status context.

CodeRabbit triage: no substantive review findings were posted. The only CodeRabbit PR comment is a rate-limit/usage notice saying review could not start. Under OPENCLAW-FORGE-PROTOCOL.md §7, I treat that as an unavailable review signal, not a blocking finding, because independent Heimdall verification and GitHub checks are green. This should remain visible to Vision; do not treat the CodeRabbit status context as an actual review.

Risk not covered by tests: no production dictionary is provided for zstd-dict-v1, by design and out of scope for issue #46.

Label action: replacing verification-needed with verified. I am not merging or approving this PR.