docs: close review follow-ups from !1660 and !1693

Summary

Two documentation follow-ups (work items #701 (closed) and #702 (closed)) that align the specs and plans with review comments from !1693 (merged) and !1660 (merged) — all prose, no code.

From !1693 (merged) (S17 / Maven size-accounting plan). Two S17 passages still carried the repository-scope cost grounds that handbook MR !20835 replaces in ADR-007 (per-file/per-scope cardinality → partition-pruned-and-rare):

  • The Phase 8 Read-cost bullet now names per-scope proportionality instead of a per-scope cardinality bound, matching the corrected repository-scope bullet.
  • The Resolutions repository-statistics entry restates its grounds as partition-pruned to the repository's own namespace and rare, keeping its fallback clause.
  • The Maven size-accounting plan's S17 Files entry now records the second rework and that both reworked sites cite !20835 as the version of ADR-007 the grounds track.

From !1660 (merged) (S14 / step-14 plan). The step-14 plan's stale-row bullet claimed the client If-None-Match is evaluated only on the revalidation-304 outcome, but serveFillCachedRow evaluates it on the degraded transport-failure fallback too (all three arms: micro-race fresh row, revalidated row, fallback):

  • The plan bullet now says the condition is evaluated whenever a cached row is served — on the revalidation 304 and the degraded fallback — and never on a revalidation 200.
  • The client-conditional criterion (S14) gains the fallback outcome.
  • The error-mapping criterion and the error-cases table row now state the matching-validator exception: a bodyless 304 returns before the served-from-cache warning, so a cache-fallback 304 is not counted in the served-from-cache volume. (The drain arm's own warning was already removed on main by 2c1e28944, so the code answers the 304 before the log on every arm; the docs now say so where a reader checks.)

Governing ADRs

Testing

Docs-only, seven-line prose diff across four files. markdownlint-cli2 (repo config), vale (--minAlertLevel error), and lychee --offline --include-fragments all pass locally on the changed files; pre-commit hooks pass. No code change, so no Go tests run (repo CI skips unit tests on docs-only MRs).

No additional operational monitoring required — docs-only change with no runtime surface affected.

Closes #701 (closed) Closes #702 (closed)

Edited by Moaz Khalifa

Merge request reports

Loading
Loading