Let the library carry the proof¶

There is a kind of code that is satisfying to write and expensive to keep: a hand-rolled tally, a group-by loop over an action log, an isinstance/raise validation chain, a little date-math helper. It works. It has tests -- often a lot of tests, because hand-rolled imperative logic has many edge cases and each one earns its own case. And every one of those lines, production and test alike, is now yours to maintain forever.

A mature library can delete most of it. Not because the library is shorter -- though it usually is -- but because the library is more trusted than the tests you wrote to pin your version. collections.Counter has been exercised by the entire Python ecosystem for a decade. A DuckDB GROUP BY carries a correctness proof far larger than any local unit suite. When you swap your code for theirs, you get to delete the production code AND the fine-grained tests that proved the production code, because the thing doing the work now arrives with its own proof attached.

This is the third post in a thread. The first two built a machine: Code comments written for the robot, not the human introduced the codemap: annotations and the risk-vs-complexity score; The test that knows what it is introduced the test taxonomy and its evidence: provenance mark. This post is about the machine doing a concrete, useful job: finding which hand-rolled code is worth replacing, and proving the swap is safe before it lands. The full protocol lives in the review-rule docs; this is the field report on why the annotation system is exactly the right instrument for it.

The technique, and its metric¶

The move is narrow on purpose. Take ordinary backend Python that does parsing, grouping, validation, serialization, retry, statistics, or tabular work, and replace it with a trusted library that already does that job: DuckDB SQL for anything that groups, aggregates, joins, or scans the action log; Pydantic for hand-written validation and response shaping; the stdlib collections, itertools, statistics, datetime, and secrets for the long tail. The review spec ranks the allowlist by leverage first and risk second, and stdlib replacements usually win because they add no dependency at all.

The score that decides whether a swap is worth it is a ratio:

```text (code removed + test removed) / (new-dependency risk + behavior-change risk)

The numerator is the whole footprint, not just production lines: the headline metric pairs net production LOC against net test LOC and test count, because deleting fifteen brittle hand-written cases is as real a win as deleting the loop they pinned. The denominator is the honest cost: a third-party install is a standing liability, and any swap can change behavior at the edges. A library swap is justified only when the library is more trusted than the tests being deleted, and only when the replacement is proven semantically equivalent on real server-shaped fixtures. Absent that proof, you have not refactored -- you have rewritten, blind.

The annotation system already knows which code to pick¶

Here is the part that makes this a post in the AI-enablement thread and not a generic "use more libraries" listicle.

"Which hand-rolled unit is worth replacing, and which one is too dangerous to touch casually" is not a new question. It is, almost exactly, the question the codemap scorer already answers for any proposed change. The library-replacement review does not invent a new ranking; it reads the annotations that are already there.

Three signals from the risk score do the work, and each one is grounded in the overview docs:

The maturity multiplier flags the load-bearing code. maturity_risk_multipliers rank stable (1.35) above active (1.0) above experimental (0.75). Mature code is load-bearing, so a careless swap costs the most exactly where the multiplier is highest. This is the counterintuitive lesson from Code comments written for the robot, not the human applied to refactors: "it is stable, so it is safe to replace" is backwards. Stable code is where you most want a golden test before you touch anything.
Coverage gating makes the under-tested unit score hotter. Risk is computed per capability and discharged only by the share of severity that coverage confidence allows. A unit with a thin covers: mark and no behavior-preservation evidence keeps most of its severity in the risk total. That is the right bias: the under-tested unit is both the most tempting to shrink and the most dangerous to shrink without first pinning its behavior.
port_missing_characterization names the precise danger. In port mode, a changed unit with no behavior-preservation coverage takes a 12.0 bonus -- the single biggest flag in the whole weights table. That number exists to say one thing: replacing code that has no characterization test is the riskiest move the system knows how to spot. It is the golden-test-first rule of the replacement protocol, expressed as a risk weight instead of a sentence. You can run it directly:

The concrete command lives in the private project wrapper for this workflow.

And the finder closes the loop. The automated entry point for the review is the library-replacement-candidates verb (the project scripts). It scans backend Python for the grep-able candidate smells -- accumulation loops, manual tallies, validation chains -- and then ranks each hit by the same annotations: it reads each unit's codemap: risk flags and maturity:, multiplies by a heuristic test-LOC-to-production-LOC ratio, and emits a ranked ledger. The closed capability vocabulary in the controlled vocabulary is the join key that lets the finder, the score, and the tests all name the same subsystem. The annotations are not decoration here; they are the targeting system.

A worked example: a tally the finder flagged¶

Run the finder and one real row that comes back is this:

The example table uses private project paths, so this public version describes the result in prose.

illustrative "before": hand-rolled accumulation¶

scores = {} for action in flips: pid = action.player_id if pid not in scores: scores[pid] = 0 scores[pid] += 1

collapses to:

```python

illustrative "after": let the library carry it¶

from collections import Counter scores = Counter(action.player_id for action in flips)

Counter is rank 4 on the allowlist: very high buck, low risk, zero new dependency. The missing-key scaffolding, the += 1, and every test that pinned the "what happens on the first flip for a new player" edge are now the library's job, proven far beyond this repo.

Run the golden test. Equal output proves equivalence. If the snapshot differs, you have found either a latent bug in the old code or an intentional semantic gap -- the classic traps are default-value semantics, empty-input edges, and tie ordering. A real diff stops being a refactor: you file a separate bug ticket with live-repro evidence and follow the bug-fix rules, rather than smuggling a behavior change in under the word "cleanup."

Delete the redundant tests. Once the golden test stays green, delete the now-redundant fine-grained unit tests, keeping one thin contract or golden test. The review spec is emphatic that this is not optional tidying: the explicit deletion step is where the test-footprint reduction actually lands. This is the deletion the trusted library bought you.

Re-stamp. Finally, in the same edit, update the unit's codemap: hash and flip the taxonomy evidence: mark from handcrafted to fixture. Both are hard rules, not courtesies: a stale annotation hash is a lint-annotations failure, and a mismatched test mark is a lint-test-marks failure. The annotation that targeted the swap gets re-stamped by the swap. The loop closes on itself.

What is primitive today¶

I want to be honest about the edges, the same way Code comments written for the robot, not the human was.

The finder ranks approximately. It is static AST plus line-pattern heuristics over a test-LOC ratio and the codemap fields -- it surfaces candidates, it does not certify them. Its own ledger says so at the top. The most visible failure mode: the highest-scoring rows in a real run are often inside the relevant engine module, which is zero-dependency by architectural rule, so a DuckDB or Pydantic suggestion there is simply illegal and a human has to throw it out. A high rank is an invitation to look, not a verdict.

And the equivalence guarantee is per-candidate, not global. Nothing here proves the catalog is library-pure or that the replacements are collectively correct. Each swap earns its safety from its own golden test against its own real fixture, one candidate per ticket, narrow diff, proof attached. The system does not promise the codebase is right; it promises that this unit's behavior was pinned before this library carried it forward. That is a smaller claim than a global correctness guarantee, and it is the only one the technique can actually back.

That smaller claim is the whole point. The annotations tell you where to aim. The golden test proves the one shot you take. And the trusted library -- not your deleted unit suite -- carries the proof from there.

The two halves of the machine this post leans on are Code comments written for the robot, not the human, which owns the risk score and the maturity multiplier, and The test that knows what it is, which owns the test taxonomy and the evidence: mark. This post was the third beat: annotate, test, and then use both to safely make the codebase smaller.

Related work

The systematic prior-art search this admonition used to defer is now its own chapter: What the literature got to first (and the parts we made mandatory). The short version: annotation-driven refactor targeting draws on deep literatures -- library-replacement linters (pyupgrade, refurb, Sourcery) and characterization-test tooling (approval tests, golden-master testing) -- and the per-candidate golden-master-before-swap discipline is old. What I believe is uncommon is joining a risk/maturity annotation score to the candidate ranking, so the same metadata both targets the swap and enforces the golden-test gate. That chapter tells the convergence-and-enforcement story in full.

Or: subscribe to the newsletter for more posts on building this stuff.