test: kill the 136 surviving mutants in the path-guard modules

[cdeust]

Closes #74

Result: 0 unexplained surviving mutants across all three modules

Module	Tests	Before (issue)	Mutants	Killed	Equivalent	Unexplained
cortex_viz/infrastructure/wiki_read.py	tests/test_wiki_read.py	67	362	355	7	0
cortex_viz/server/http_standalone_static.py	tests/test_static_path_traversal.py	53	152	147	5	0
cortex_viz/server/http_file_diff.py	tests/test_git_diff_engine.py, tests/test_file_diff.py	16	120	120	0	0
Total		136	634	622	12	0

Every equivalent mutant carries a written proof in tests/MUTATION_NOTES.md
(new file, format follows the existing tests/js/MUTATION_NOTES.md
precedent) — no survivor was left un-triaged, and none were dismissed by
assertion.

Full local suite: 1310 passed, 10 skipped (was 1279/10 before this PR),
ruff check . and ruff format --check . both clean across the whole repo.

Commands and raw output

Each module was run with scripts/mutation_check.sh's pyproject-repoint
logic, invoking python3 -m mutmut run --max-children 3 directly (the
committed script doesn't expose --max-children; a local wrapper added it,
not committed — the repoint/cleanup logic is identical). Reproduce with:

scripts/mutation_check.sh tests/test_wiki_read.py cortex_viz/infrastructure/wiki_read.py
scripts/mutation_check.sh tests/test_static_path_traversal.py cortex_viz/server/http_standalone_static.py
scripts/mutation_check.sh tests/test_git_diff_engine.py,tests/test_file_diff.py cortex_viz/server/http_file_diff.py

(append --max-children 3 to the mutmut run line inside the script, or
edit pyproject.toml's [tool.mutmut] block by hand and run
python3 -m mutmut run --max-children 3 directly, to reproduce the exact
capped-parallelism runs below.)

wiki_read.py, final verification run:

>>> results:
    cortex_viz.infrastructure.wiki_read.x__page_item__mutmut_11: survived
    cortex_viz.infrastructure.wiki_read.x_read_page__mutmut_25: survived
    cortex_viz.infrastructure.wiki_read.x_list_bibliography__mutmut_18: survived
    cortex_viz.infrastructure.wiki_read.x_list_bibliography__mutmut_20: survived
    cortex_viz.infrastructure.wiki_read.x_list_bibliography__mutmut_23: survived
    cortex_viz.infrastructure.wiki_read.x_read_bibliography__mutmut_25: survived
    cortex_viz.infrastructure.wiki_read.x_save_page__mutmut_24: survived
38.07 mutations/second

362 total mutants generated (355 killed, all 7 shown above are the
documented equivalents). Load/disk before: 5,31 / 5,69 / 6,22, 27Gi free
(coordinator's baseline snapshot). Load/disk after this module's final run:
7,54 / 8,11 / 8,36, 25Gi free.

http_standalone_static.py, final verification run:

>>> results:
    cortex_viz.server.http_standalone_static.x_serve_static__mutmut_4: survived
    cortex_viz.server.http_standalone_static.x_serve_static__mutmut_5: survived
    cortex_viz.server.http_standalone_static.x_serve_static__mutmut_8: survived
    cortex_viz.server.http_standalone_static.x_serve_static__mutmut_9: survived
    cortex_viz.server.http_standalone_static.x_serve_shared_asset__mutmut_10: survived
19.43 mutations/second

152 total mutants generated (147 killed, all 5 shown above are the
documented equivalents; the module's earlier serve_file_diff "no tests"
gap — 4 mutants with zero associated tests — is also closed, now covered
and killed). Load before: 7,06 / 8,09 / 8,17, 24Gi free. Load after:
9,53 / 8,51 / 8,31, 24Gi free.

http_file_diff.py, final verification run:

>>> results:
42.37 mutations/second

120/120 killed, empty results list (no survivors, no equivalents needed).
Load before: 7,64 / 8,41 / 8,31, 24Gi free. Load after: 8,76 / 7,75 / 7,98, 22Gi free.

All three runs stayed under --max-children 3, one module at a time, never
two campaigns in parallel. The 1-minute load average crossed 10 twice
between modules (never mid-run); each time the in-flight run was allowed to
finish and the next was held until the load dropped back under 7, per the
coordinator's stop rule. mutants/ and .mutmut-cache were deleted and
pyproject.toml restored after every run — no leftover artifacts, disk
stayed in the 22–27Gi-free range throughout (never approached the incident
threshold from the 2026-08-09 disk-exhaustion writeup).

What changed (see individual commits for the full per-module rationale)

• wiki_read.py: added coverage for list_pages/list_projects/
  list_bibliography/_title_from/_page_item/_iter_md/_parse_list
  (previously zero assertions), UTF-8 pinning under a non-UTF-8 process
  locale (locale.setlocale(LC_ALL, "C") in-process — a subprocess-based
  approach was tried first and abandoned because it's invisible to
  mutmut's coverage-based test-to-mutant association; see
  tests/MUTATION_NOTES.md for the full account), invalid-UTF-8-byte
  robustness, exact response-shape assertions, and the suffix-refusal gate
  on save_page/read_bibliography.
• http_standalone_static.py: response framing headers, the full
  content-type table, the filename-whitelist regex boundary, three
  defense-in-depth segment-rejection payloads that net to a legitimately
  contained file if the pre-check is bypassed, and wiring tests for the
  previously-untested serve_file_diff delegate.
• http_file_diff.py: store-forwarding proofs at all four call sites
  along the name-resolution chain, an exact-string reason assertion, and a
  full-dict-equality response-shape assertion.

No structural changes to any guard were required — every survivor was a
test gap, not a code defect, and none of the equivalent mutants indicated
dead code (verified per §9's "survivors that mark dead code are removed,
not tested" clause: list_bibliography's two equivalent mutants are
equivalent because its ASCII-only consumers can't observe encoding
differences, not because that code path is unreachable).

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

[cdeust]

ZETETIC-REVIEW: APPROVE

Reviewed against the equivalence proofs and the numbers, not against the report.

The issue's own framing was the thing to reject, and it was. #74's title reads "(pre-existing, outside the changed lines)". Debt in material we touch is ours regardless of who created it; that phrasing appears nowhere in the delivery, and the work treats all 136 survivors as owed rather than inherited.

Result: 634 mutants, 622 killed, 12 equivalent with written proofs, 0 unexplained.

Module	Mutants	Killed	Equivalent	Unexplained	Survivors before
wiki_read.py	362	355	7	0	67
http_standalone_static.py	152	147	5	0	53
http_file_diff.py	120	120	0	0	16

The equivalence proofs are proofs, not shrugs, which is the part that usually rots. Spot-checked the largest class — five mutants turning encoding="utf-8" into encoding="UTF-8" — against the claim that Python's codec registry normalises case. Ran it here: codecs.lookup("UTF-8") is codecs.lookup("utf-8") → True. The mutant resolves to the same codec object; no input can distinguish it. An equivalent mutant is a proof obligation and this one is discharged.

The methodological find is worth more than the count. The first attempt at testing the encoding pins drove locale through a subprocess with LC_ALL=C. That reproduces the real divergence, yet the mutants kept reporting "survived" — a spawned child's execution is invisible to mutmut's coverage-based test-to-mutant scheduling, so the tests passed in isolation while never being scheduled against their targets. Replaced with in-process locale.setlocale, which Path.read_text/write_text actually consult and the tracer can see. A test that cannot be attributed to the mutant it kills is a test that proves nothing about that mutant, and this failure mode is silent in both directions. Recording it in MUTATION_NOTES.md is what stops the next person losing an afternoon to it.

Every survivor was a test gap, not a code defect — missing assertions, loose in (403, 404) and substring checks, untested delegate wiring. No guard needed restructuring, and none was restructured to make a number move.

The shared-machine protocol was honoured under real pressure. Capped at --max-children 3, one module at a time, load and disk logged before and after each run. Two load-crossed-ten events were both handled by finishing the in-flight run and pausing between modules — never mid-run, which would have produced a false result rather than a partial one. No mutants/ or .mutmut-cache left behind, on a machine that hit 100% disk earlier this month.

Debt closed in passing, correctly. The uv sync --frozen trap — pytest and mutmut live in the dev extras, so a bare sync silently falls through to the system Python via PATH — is now in this repo's CLAUDE.md with its symptom, not just the corrected command. The symptom is what saves the next reader; a fix alone leaves them unable to recognise they are in it.

Full suite 1310 passed / 10 skipped, up from the 1279 baseline. ruff check and ruff format --check clean. All 12 checks green at 19519ef, including the four required ones.

No declared violation, no deferral, no "pre-existing" left standing. Merging.

[cdeust]

ZETETIC-REVIEW: APPROVE

Re-verdict at the current head — the branch was updated onto the main that now carries #132, so the earlier approval is stale and does not speak for this diff.

Everything in that earlier review stands: 634 mutants, 622 killed, 12 equivalent with written proofs, 0 unexplained, against 136 survivors in the issue. I re-ran the largest equivalence class here rather than trusting it — codecs.lookup("UTF-8") is codecs.lookup("utf-8") returns True, so the encoding-case mutants resolve to the same codec object and no input can distinguish them. Every survivor was a test gap, not a code defect, and no guard was restructured to make a number move.

What changed since, and why it was the right fix. Five CodeQL threads blocked the merge — main has required_conversation_resolution enabled, so an open thread stops a merge no matter how green the checks are. The finding was legitimate: tests/test_file_diff.py imported cortex_viz.server.http_file_diff both as a module and by name. Resolving the threads to silence the alert would have been the wrong move; the file now standardises on the single hfd module alias, which is the form three tests genuinely need in order to monkeypatch attributes. One path, as the guideline asks. The threads then went outdated on their own, because the flagged lines no longer exist — which is the correct way for a thread to close.

The propagation check was done rather than assumed: test_wiki_read.py, test_static_path_traversal.py and test_git_diff_engine.py were inspected for the same dual-import pattern and are clean. That pattern spreads by copy-paste between neighbouring test files, so checking was not optional.

The mutation campaign was correctly not re-run for an import-style change in a test file — the counts stand, and a re-run under a machine shared with another session's measurement would have risked two invalid results instead of preserving one valid one.

Full suite 1310 passed / 10 skipped. ruff check and ruff format --check clean. 12/12 checks green after the branch update, no unresolved threads.

No declared violation, no deferral, no "pre-existing" left standing. Merging, and closing #74.