[v0.5.0] docs — write ADR-007 (Cache)

[ayhammouda]

Context

Roadmap §4 assigns v0.5.0 the "Architecture Documentation & Launch" deliverables, including "ADRs 7 and 8 | Cache, Transport." ADR-007 documents the cache layer (layer 7 of the eight-layer contract, principle 2.7). The house template is the exact skeleton shared by docs/architecture/ADR-001-source-adapters.md and docs/architecture/ADR-006-serialization.md — those two files ARE the strict template (roadmap §9.1: "Agent w/ strict template"). This is a writing task: every claim must match the code; you are recording locked decisions, not making new ones.

Maintainer sign-off for this issue's filing: D3 in the 2026-07-08 gate record (see the sign-off comment on #63).

Goal

docs/architecture/ADR-007-cache.md accurately recording the shipped cache design.

Acceptance criteria

• docs/architecture/ADR-007-cache.md exists and follows the exact ADR-001/ADR-006 skeleton, in order: H1 # ADR-007: <Title>; metadata bullet header (Status: Accepted / Date: / Deciders: @ayhammouda / Roadmap refs:); ## Context and Problem Statement; ## Decision Drivers; ## Considered Options (numbered, each with inline Rejected/Accepted rationale); ## Decision Outcome; ### Consequences (Positive: and Negative / risks: paragraphs); ## Layer Contract (principle 2.7) (Inputs: / Outputs: / Invariants:); ## Links (roadmap refs + relative links to src files).
• Records all three cache mechanisms accurately, verified against code before writing: (1) persistent get_docs value cache — PersistentDocsCache (src/mcp_server_python_docs/services/persistent_cache.py): SQLite table retrieved_docs_cache, PK (index_fingerprint, version, slug, anchor, max_chars, start_index), WAL + synchronous=NORMAL, index-fingerprint invalidation (foreign-fingerprint rows deleted at init), best-effort posture (any failure disables the cache cleanly), single-lock thread safety, values = GetDocsResult.model_dump_json() with per-row compression column and legacy ALTER TABLE migration; (2) codec layer (src/mcp_server_python_docs/cache/codec.py): versioned codecs none/zstd/zstd-dict-v1, default zstd, zstd-dict-v1 is test-only forward-compat with no shipped trained dictionary; (3) in-memory LRU caches (src/mcp_server_python_docs/services/cache.py): section cache maxsize 512, symbol cache maxsize 128, process-lifetime, no TTL, restart-on-rebuild.
• Locked decision 5.7 is recorded verbatim as already-decided ("App-level zstd on retrieved-docs cache, no gate. Versioned codec column for forward-compat."), not re-litigated; compression is framed per decision 5.16 — an engineering footnote, never a headline.
• The diff is docs/architecture/ only: exactly one new file; zero source, test, README, tool-surface, or config changes.
• PR body uses Refs #63 (never Closes #63) and closes this issue only if every criterion is met.

Scope boundaries

Describe, do NOT change. No code edits of any kind, no new architectural decisions, no roadmap edits, no README changes. If the code contradicts a roadmap decision, that is a stop-and-comment, not a fix.

Forbidden-territory reminder

AGENT-EXECUTION-PIPELINE.md §2 is binding. Additionally for this run: pyproject.toml/uv.lock untouchable; no benchmark/comparative claims anywhere; never create docs/benchmarks/corpus.yml.

Validation commands

uv run ruff check src/ tests/
uv run ruff check benchmarks/        # additive until #84 lands in ci.yml
uv run pyright src/
uv run pyright benchmarks/           # additive until #84 lands
uv run pytest --tb=short -q
uv run pytest tests/benchmarks -q
uv run python-docs-mcp-server doctor

All must pass trivially (docs-only change). The PR body must additionally state "Diff is docs/architecture/ only" and include git diff --stat main...HEAD output proving it.

PR template

Title verbatim = this issue's title. Body: Refs #63; Closes #<this issue> only if all criteria met (checkbox each); full validation-gate output; the docs-only statement + diff stat; CodeRabbit triage when it comments; "Why this approach" for any unprescribed structural call; §7 supervisor-review disclosure.

Recovery

If code ground truth contradicts the roadmap or a locked decision, or a claim cannot be verified at file:line level: stop, comment here (what was attempted, what blocked, best read, "I am stopping pending guidance"). No silent scope expansion.

Effort estimate

2–4 hours.

[ayhammouda]

Agent context — #91 [v0.5.0] docs — write ADR-007 (Cache)

Status: DRAFT for dispatch (verified against main @ ab9e615, 2026-07-08)
Auditable copy: this content is mirrored as a comment on issue #91 (.planning/ is gitignored — the issue comment is the copy pre-flight verifies and the dispatch packet links).

1. Roadmap excerpt (why this exists)

• Roadmap §4 assigns v0.5.0 "Architecture Documentation & Launch", including
  "ADRs 7 and 8 | Cache, Transport". ADR-007 documents the cache layer —
  layer 7 of the eight-layer contract (principle 2.7).
• Decision 5.7 (locked, record VERBATIM): "App-level zstd on retrieved-docs
  cache, no gate. Versioned codec column for forward-compat."
• Decision 5.16: compression is an engineering footnote, never a headline —
  state it inside the outcome, do not lead with it.
• Writing task only: you are recording locked decisions, not making new ones.

2. Code touch-points (verify against merged main before starting)

Three cache mechanisms plus wiring (all line refs re-verified @ ab9e615):

• src/mcp_server_python_docs/services/persistent_cache.py — PersistentDocsCache:
  • Table retrieved_docs_cache created at :56-63; PK
    (index_fingerprint, version, slug, anchor, max_chars, start_index) :62.
  • PRAGMA journal_mode = WAL :54; PRAGMA synchronous = NORMAL :55.
  • Fingerprint invalidation at init — foreign-fingerprint rows DELETEd
    :65-68; fingerprint = resolved path + size + mtime_ns (:80-83).
  • Best-effort posture: init failure closes conn, sets _conn = None :70-74;
    get/put no-op when disabled (:107, :146); reads/writes log-and-skip.
  • One threading.Lock guards every execute/commit + stats counters :48.
  • compression column in CREATE :60; legacy ALTER TABLE migration in
    _ensure_compression_column :89-99.
  • Values = result.model_dump_json() codec-encoded :161-162; default codec
    DEFAULT_RETRIEVED_DOCS_CACHE_CODEC = "zstd" :19.
• src/mcp_server_python_docs/cache/codec.py — versioned codecs
  ["none", "zstd", "zstd-dict-v1"] :10; registry dispatch :108-112; decode
  keys off the codec stored with the row, never the current default;
  zstd-dict-v1 is test-only forward-compat — raises without an explicit
  dictionary (:97-98), no trained dictionary ships.
• src/mcp_server_python_docs/services/cache.py — in-memory LRU closures:
  section cache maxsize 512 :51; symbol cache maxsize 128 :85;
  process-lifetime, no TTL, restart-on-rebuild (module docstring :1-10).
• Wiring: server.py builds PersistentDocsCache :157-160, injects it into
  ContentService :162; lifespan finally closes it :208-213.
• Read path: content.py get_docs checks the persistent cache before any
  DB work :56-65 and returns hits unchanged.

3. Test patterns to follow

Not a test task — the deliverable is prose in the strict house skeleton
(ADR-001 / ADR-006 ARE the template). Sections in this exact order:
H1 # ADR-007: <Title>; metadata bullets Status: Accepted / Date: /
Deciders: @ayhammouda / Roadmap refs:; ## Context and Problem Statement; ## Decision Drivers; ## Considered Options (numbered, inline
Rejected/Accepted rationale); ## Decision Outcome; ### Consequences with
Positive: and Negative / risks: paragraphs; ## Layer Contract (principle 2.7) with Inputs: / Outputs: / Invariants:; ## Links
(roadmap refs + relative links to the src files above). Wrap prose ~80 cols,
factual, non-promotional. Filename: docs/architecture/ADR-007-cache.md.

4. Known pitfalls

• Diff is docs/architecture/ only — exactly one new file. Do NOT touch src,
  tests, README, tool surface, config, pyproject.toml, or uv.lock.
• The [v0.5.0] docs — write ADR-007 (Cache) #91 validation gate (ruff, pyright, pytest, doctor) must pass trivially;
  PR body states "Diff is docs/architecture/ only" + git diff --stat main...HEAD output proving it. Use Refs #63, never Closes #63.
• Code contradicting the roadmap or a locked decision = stop-and-comment on
  [v0.5.0] docs — write ADR-007 (Cache) #91; never fix either side silently.
• No benchmark/comparative claims; never create docs/benchmarks/corpus.yml.
• Branch: agent/91-adr-007-cache.

5. Decision log (worker fills in)

• …