test(mutation): kill sqlite_sql_translate.py's 20 surviving mutants (#265)

[cdeust]

Summary

Issue #265 filed a scoped mutmut run (mutmut 3.x, coding-standards.md §12)
against mcp_server/infrastructure/sqlite_sql_translate.py's
_translate_sql/_returning_was_stripped — the SQL-dialect translation
module extracted from sqlite_compat.py in #260 — reporting 20 surviving
mutants. This PR closes it: every survivor is killed by a new test or
documented as a provable equivalent mutant.

Note on provenance: sqlite_sql_translate.py did not exist on main yet
when this work started (it is created by the still-open #266,
fix-sqlite-datetime-adapter-260). Rather than stack on that unmerged
branch — main advances fast in this repo from concurrent sessions, and a
stacked branch's own doc-count-bump commits kept conflicting on every
rebase — this PR cherry-picks #266's single substantive commit
(fix(sqlite): register explicit datetime adapter, close deprecation warning, byte-identical diff) directly onto current main, then adds the
#265 fix on top. When #266 merges first, expect a trivial merge: the
production-code files (sqlite_compat.py, sqlite_sql_translate.py,
test_wiki_pipeline_sqlite.py, test_sqlite_datetime_adapter_260.py) will
resolve automatically since both sides converge on identical final content;
only the shared doc-count files (.bestpractices.json, CLAUDE.md,
CONTRIBUTING.md, README.md, docs/ASSURANCE-CASE.md,
assets/badge-tests.svg) will show a real conflict — resolve by taking
either side's shape and re-running pytest --collect-only -q for the true
absolute, same as every other doc-count conflict in this repo's recent
history.

Root cause of the 20 survivors

Every one is the same shape: a mutant dropping (or re-spelling the case of)
the flags=re.IGNORECASE argument on one of the module's re.sub/re.search
calls. Every existing case-insensitivity fixture in
test_wiki_pipeline_sqlite.py happens to supply an input whose case already
matches the pattern's own literal spelling, so the flag's presence was never
observable by any existing assertion.

A fresh scoped run on this tree measured 19 of the 20 named ids still
surviving (mutmut_136 had flipped to killed between runs — confirmed
non-deterministic mutant/worker ordering, not a real fix, since the same
regex-equivalence argument that classifies its siblings applies to it
unchanged). All 20 named ids are accounted for below.

Invariant-to-test map

Mutant id	Rule	Kind	Resolution
mutmut_8	_returning_was_stripped regex	real gap	test_returning_was_stripped_matches_lowercase_returning (monkeypatches _SUPPORTS_RETURNING=False, lowercase returning)
mutmut_10	same regex, case-only pattern respell	equivalent	IGNORECASE folds RETURNING/returning identically
mutmut_38	SERIAL PRIMARY KEY respell	equivalent	same
mutmut_51	TIMESTAMPTZ respell	equivalent	same
mutmut_62	DEFAULT NOW() — drops IGNORECASE	real gap	test_translate_sql_default_now_lowercase_still_translates
mutmut_64	DEFAULT NOW() respell	equivalent	same
mutmut_78	standalone NOW() respell	equivalent	same
mutmut_92	UPDATE ... SET alias rule respell	equivalent	same
mutmut_105	ANY(...) respell	equivalent	same
mutmut_117	&& overlap — drops IGNORECASE	real gap	test_translate_sql_array_overlap_matches_uppercase_column
mutmut_119	&& capture char-class respell	equivalent	[a-z_] vs [A-Z_] fold identically under IGNORECASE
mutmut_134	xmax drop — drops IGNORECASE	real gap	test_translate_sql_xmax_drop_matches_uppercase_and_lowercase_as
mutmut_136	xmax drop, AS→as respell	equivalent	same
mutmut_137	xmax drop, xmax→XMAX respell	equivalent	same
mutmut_149	IS DISTINCT FROM respell	equivalent	same
mutmut_161	RETURNING strip in _translate_sql — drops IGNORECASE	real gap	test_translate_sql_strips_lowercase_returning_when_unsupported
mutmut_163	RETURNING strip respell	equivalent	same
mutmut_175	wiki. flatten, char-class respell	equivalent	same
mutmut_186	array_length — drops IGNORECASE	real gap	test_translate_sql_array_length_matches_uppercase
mutmut_188	array_length respell	equivalent	same

Every "equivalent" classification is backed by a differential harness run
(compile original vs. mutated pattern, run uppercase/lowercase/mixed-case
probes, diff match results — identical in every case) rather than asserted
by inspection alone; the reasoning is also inlined in the new test file's
module docstring.

Completion Ledger

Path introduced	Asserting test
_returning_was_stripped matches lowercase returning (IGNORECASE required)	test_returning_was_stripped_matches_lowercase_returning
_translate_sql translates lowercase default now()	test_translate_sql_default_now_lowercase_still_translates
_translate_sql translates an uppercase &&-overlap column	test_translate_sql_array_overlap_matches_uppercase_column
_translate_sql drops XMAX/lowercase-as xmax clause	test_translate_sql_xmax_drop_matches_uppercase_and_lowercase_as
_translate_sql strips lowercase returning when unsupported	test_translate_sql_strips_lowercase_returning_when_unsupported
_translate_sql translates uppercase ARRAY_LENGTH	test_translate_sql_array_length_matches_uppercase
14 equivalent mutants (case-respell under preserved IGNORECASE)	documented in the new file's module docstring, empirically verified

Mutation results

• Runner: mutmut 3.6.0, scoped to mcp_server/infrastructure/sqlite_sql_translate.py
• Before: 201 mutants, 19 survived (of the issue's 20 named ids; mutmut_136 flip explained above)
• After: 201 mutants, 187 killed, 14 survived — all 14 documented equivalent, 0 unaccounted-for

Test plan

• Reproduced the issue's 19/20 survivors on this tree before any fix
• Added tests_py/infrastructure/test_sqlite_sql_translate_265.py (6 tests, all fail on pre-fix code)
• Re-ran scoped mutmut: 6 killed, 14 equivalent (verified empirically), 0 unaccounted-for
• ruff check + ruff format --check clean
• pyright on the new test file + sqlite_sql_translate.py: 0 errors
• Full suite: 6609 passed, 117 subtests passed (measured pytest --collect-only -q == 6609, resynced after rebasing onto fix(mutmut): make RepoBadge/Ranking mutation-testable (issue #262, 3rd pass) #283's mutation-testability pass which had itself bumped the count to 6588)
• Doc-claim/badge counts resynced to the measured absolute: check_doc_claims.py --test-count 6609 and generate_repo_badges.py --check --test-count 6609 both pass
• All 19 CI jobs green on the exact pushed head (Analyze x3, Build Package, CodeQL, Docker Build x2, Docker Smoke, Fuzz PR batch x2, Lint, Test Python 3.10-3.13, Test SQLite backend, Test Windows, Type Check); mergeable: MERGEABLE, mergeStateStatus: CLEAN against current main

Closes #265

🤖 Generated with Claude Code

https://claude.ai/code/session_012Yu6EnWspTfqHoGkExyS6u