Guard every already-covered file with a repo-wide coverage ratchet

[TaprootFreak]

Why

The repo has exactly one coverage gate today: jest.frick.config.js, covering 7 files — 0.4 % of production code. Everywhere else, a change can drop coverage to zero and CI stays green.

What this does

Measures the whole suite once and pins every production file that already reaches 100 % on all four metrics. A drop below 100 on any pinned file now fails CI.

	before	after
Pinned files	7	399
Share of production code	0.4 %	25.1 %

This freezes coverage that already exists — no test was added to raise it.

One existing test is rewritten (see below), which means the pre-existing checks and sharded test jobs run a changed test too. This PR is therefore not configuration-only.

What it deliberately does not claim

It is a regression gate, not a quality statement. Overall coverage is 57.66 % of statements and 39.46 % of branches — the pinned set is simply what is complete today.

Of the 399 files, 217 carry real logic (functions and/or branches) and 182 are purely declarative (NestJS modules, constant files). They are kept as two commented blocks in the config so the number is not mistaken for test depth. Pinning the declarative ones is intentional: the moment logic is added to one, it must arrive with tests.

Measurement

Two properties matter, and docs/coverage-gate.md records both so the list stays reproducible:

1. Full compilation (tsconfig.coverage.json, isolatedModules: false) — same as the Frick gate. Transpile-only emit reports phantom uncovered branches on injected constructors and would understate dozens of files.
2. Whole suite runs — files are frequently covered by specs other than their own.

The gate job runs without the Postgres service the sharded test job uses, matching the measurement. The suites it enables are not in the pinned list, and running them can only raise coverage.

The Frick gate stays separate and untouched

It runs only its seven specs and therefore proves those specs alone reach 100 % — an assertion a whole-suite run cannot make, since there any spec may contribute the coverage. Two gates, two different questions.

Verification

• Gate passes with no threshold violation: 299/306 suites, 5170 tests, and it passed in CI as well (~16 min)
• Parallel execution yields byte-identical coverage totals to a --runInBand reference run — hence no --runInBand in the CI script
• Both failure modes verified against jest 29.7 rather than assumed: a file dropping below 100 exits 1 with threshold ... not met, and a deleted or renamed pinned file exits 1 with Coverage data ... was not found. The gate cannot silently stop protecting a file.
• format:check green, workflow YAML parses, config loads with 399 keys

Inventory

The collection glob matches 1,643 files under src/; 1,591 carry instrumentable code and appear in the report. The remaining 52 are type-only files that compile to no executable statements and therefore cannot be pinned. Test scaffolding (shared/utils/test.util.ts, shared/utils/test.shared.module.ts — 60 and 28 importers, all specs) is excluded, so an untested change to a test helper cannot fail a production gate.

One test changed, and why it belongs here

bitcoin-fee.service.spec.ts asserted parallel execution by wall-clock time (duration < 100ms for five mocked 10 ms calls). This gate runs the whole suite a second time per PR, which doubles the exposure to that timing assertion — a flaky required check is the worst kind, because it teaches a team to ignore red.

Checking it turned up more than flakiness. Replacing Promise.all in getTxFeeRates with a sequential loop left the old test green (27 passed): five sequential 10 ms calls total ~50 ms, under the limit. The assertion could only fail from machine load, never from the defect it existed to catch — it failed at 181 ms under load in exactly that way.

The test now counts how many calls are in flight at once and requires that maximum to equal the txid count. Against the same sequential mutation it fails with Expected: 5, Received: 1. Stable and, for the first time, effective. Coverage of the pinned BitcoinBasedFeeService is unchanged at 100 %.

Scope boundary

1062 partially covered and 130 uncovered files stay open — closing them means writing tests, which is deliberately not part of this change. docs/coverage-gate.md lists the gaps by area and names the 29 files already at ≥90 % on all four metrics as the next batch, so the boundary is documented rather than silent.

[TaprootFreak]

6 review passes to zero findings, two independent lenses each round (conformance against CONTRIBUTING, and logic/correctness), re-run in full against origin/develop...HEAD after every fix rather than as a delta.

What the rounds turned up:

Round	Findings
1	Test scaffolding (test.util.ts, test.shared.module.ts — 60 and 28 importers, all specs) was pinned as production; stale "three job groups" comment
2	Inventory misclassified 2 of 52 uncollected files; unverifiable measurement claims
3	Dating a claim does not make it checkable — removed what the repo cannot confirm
4	The gate exposed a pre-existing flaky test; section comments off-convention; a provenance claim
5	Scope description understated that an existing test changes; same provenance claim surviving in the workflow
6	none, both lenses

The round-4 finding was the substantive one. The should execute in parallel test asserted concurrency via wall-clock time. Replacing Promise.all in getTxFeeRates with a sequential loop left it green — five sequential 10 ms calls total ~50 ms, under its 100 ms limit. It could only fail from machine load, which it did at 181 ms, never from the defect it was written to catch. It now counts simultaneously in-flight calls; against the same mutation it fails with Expected: 5, Received: 1.

Mechanism verified rather than assumed, against jest 29.7's CoverageReporter:

• A pinned file dropping below 100 exits 1 with threshold ... not met
• A pinned file deleted, renamed or excluded exits 1 with Coverage data ... was not found — the gate cannot silently stop protecting a file
• Threshold keys resolve via path.resolve from the working directory; both the npm script and the workflow run from the repo root
• The 182 declarative pins are not vacuous: adding an unexecuted function moves a metric from 0/0 to 0/N and fails

All 12 checks green, including the new ratchet job at ~15 min.

[TaprootFreak]

Four review findings addressed, plus three follow-ups split out as issues.

Fixed here

The 2037-line threshold block	The 399 paths now live in PINNED_LOGIC and PINNED_DECLARATIVE, and coverageThreshold is generated from them. 2037 → 458 lines, one line per file instead of five, and the two groups are data rather than a comment. The pinned set is byte-identical: same 399 paths, same order, same grouping.
A red gate was not diagnosable	jest names the file and the metric but not the uncovered lines, so the only way to find out what to fix was a ~15-minute local rerun. The config now emits lcov and the job uploads coverage-gate/ as an artifact on failure (7-day retention).
The job had no timeout	timeout-minutes: 30. It is the most expensive job in the workflow, and without a bound a hang would have held a runner for the default six hours.
A pending promise survived a failing assertion	In bitcoin-fee.service.spec.ts the assertion sits between parking the mocked calls and releasing them, so on failure the release never ran. The release moved into a finally.

docs/coverage-gate.md also gained the three things it was silent about: that a newly added file with no coverage passes the gate, that unpinning a purely declarative file which first gains logic is an allowed outcome when the PR says so, and where the lcov artifact comes from.

Verification

• Whole-file check that the pinned set survived the refactor: 399 paths, identical in both membership and order, all four metrics still at 100, collectCoverageFrom and the header comment untouched.
• bitcoin-fee.service.spec.ts: 27/27 green.
• The rewritten parallelism test still catches the defect it exists for — replacing Promise.all in getTxFeeRates with a sequential loop fails it with Expected: 5, Received: 1, and with the finally in place the run now ends cleanly instead of leaving the call unsettled.
• tsc --noEmit clean, prettier --check clean on src/**/*.ts and on the gate config, workflow YAML parses with the expected job structure.

Follow-ups, tracked separately

• Make the coverage ratchet a required status check on develop #4386 — the ratchet reports as a check, but develop has no required status checks, so a red gate does not block a merge. The issue also proposes an observation window first: a flaky required check is worse than none.
• Coverage is not verified after a merge to develop #4387 — the gate runs on pull_request only. Two individually green pull requests can lower coverage together, and nothing re-checks develop afterwards.
• Cancel superseded PR workflow runs with a concurrency group #4388 — the workflow has no concurrency group, so superseded runs of this ~15-minute job run to completion.