From d7d1097cec929a58e6ee735ba0505088c9ece8a2 Mon Sep 17 00:00:00 2001 From: Adam J Esslinger Date: Wed, 19 Aug 2026 09:19:58 -0400 Subject: [PATCH] docs: capture the TDD pattern for source-level parity gaps #34/#36/#38/#39 all came from a full source-level audit against the builtin's actual Rust (pool_manager.rs, drivers/postgres/), not from the 82-test SQL-text parity suite -- every one lived in a code path that suite doesn't exercise (TLS/pool-config semantics, extract.rs's wire-format type dispatch). Recording where to look and how each was proven with a standalone unit test (no live DB/TLS handshake needed) so the next parity audit starts from this pattern instead of rediscovering it. --- CLAUDE.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index ba15986..916a3ff 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,6 +72,32 @@ migration, now applied across the repo boundary. built-in's implementation first and match its SQL/behavior exactly — don't improve on it silently; behavioral differences are regressions here, not fixes. +- **Parity gaps beyond SQL text**: the 82-test parity suite (see "Cross-Repo + Parity Check" above) and this repo's own SQL-builder unit tests cover + query text well, but four gaps found by a full source-level audit against + the builtin (`src-tauri/src/pool_manager.rs` and + `src-tauri/src/drivers/postgres/`) all lived in code paths that suite + doesn't exercise directly: TLS/pool-config semantics (issues #34, #36, + #38 — mTLS client-cert not honored, pool cache key ignoring TLS params + entirely, `verify-ca` incorrectly enforcing hostname checks) and + wire-format type coverage in `extract.rs` (#39 — `MONEY` silently + decoding to `null`). When auditing for parity, read the builtin's actual + Rust source for the subsystem (not just its SQL strings) — connection/TLS + config and `extract.rs`'s `Type::` dispatch table are the areas most + likely to silently diverge, since they're exercised by config values and + column types rather than by query shape. +- **TDD for parity bugs without a live database**: prove the divergence + with a standalone unit test *before* fixing it, even when the real bug + only manifests during a live TLS handshake or a live column read. For + TLS/verifier bugs, construct the verifier type directly and call + `verify_server_cert` against a real (but locally-generated, long-validity) + cert/CA fixture — no live server needed (see `#38`'s + `verify_ca_cert_verifier_accepts_a_chain_valid_cert_with_mismatched_hostname` + test in `src/client_tests.rs`). For wire-format bugs, call the type's + `FromSql::from_sql`/`accepts` directly with hand-built wire bytes (see + `#39`'s `money_decodes_the_same_8_byte_wire_format_as_int8` in + `src/extract_tests.rs`). Confirm the test fails against the current code + for the right reason before implementing the fix. - **Testing**: prefer real PostgreSQL over mocks for integration-level behavior. Extract pure logic (SQL builders, value binding, pagination math) into testable functions with unit tests in a sibling `_tests.rs`