bar_cecp_velocity — Implementation Journal

What it did: This firing did the groundwork before any real feature code. We confirmed every build tool is installed, confirmed the trusted reference library (ordpy 1.2.2) loads, read its exact recipe for the two numbers our feature is built from (an 'entropy' score and a 'complexity' score), and wrote a small, version-locked Python file that reproduces the feature by calling that trusted library directly. We then ran it over 10,000 real Bitcoin price-bars to make sure it produces sane numbers.

Why: The whole point of this project is that our fast Rust version must give bit-for-bit the SAME answer as the trusted reference library. So before writing any Rust we lock down (a) which library is the authority, (b) exactly how it computes its numbers, and (c) a fixed sample of real data to test against. Getting these three things nailed first means the next step — proving the Rust matches — has a stable target that can never drift.

What it did: This was the decisive step. We wrote the real, fast (Rust) version of the new feature and PROVED it produces the same numbers as the trusted reference library — not approximately, but to 15 decimal places (a millionth of a millionth). We checked this on 9,801 real Bitcoin price-windows. We deliberately did this BEFORE building any of the surrounding plumbing, because if the maths can't be made to match, nothing else matters.

Why: The feature measures how fast a market's 'complexity fingerprint' is moving by comparing the first half of a window of prices to the second half and measuring the distance between the two fingerprints. The hard part is computing that fingerprint identically to the trusted library, down to tricky details like how it breaks ties when prices are equal. We front-loaded this proof so the rest of the work stands on solid ground.

What it did: With the maths proven, this firing connected the new feature into every place a finished bar travels: the in-memory bar record, the live streaming writer, the crash-recovery 'dead-letter' file, the columnar (Arrow) export, the Python bindings, the feature catalogue, and the database table definition. We mirrored exactly how the sibling 'dispersion' feature is wired, so the new column slots in beside it with no surprises. We then rebuilt everything and ran the guard tests that count columns end-to-end.

Why: A computed number is useless until it can be stored and shipped. The pipeline has many layers (live engine, recovery store, database, Python API), and each must agree on the exact set of columns. The project guards this with 'tripwire' tests that fail loudly if any layer forgets the new column — those tripwires are exactly what would have caught a missing column before it silently dropped data. Getting all layers in lock-step is the whole job of this stage.

What it did: This firing hammered the new feature with the project's full safety battery and extended each test to cover it. We proved the two underlying numbers (an 'entropy' score and a 'complexity' score) always stay inside their valid 0-to-1 box, and the feature itself always stays inside its valid 0-to-1.414 range — even on thousands of randomly generated price sequences, including deliberately broken ones. We proved the feature comes out identical whether bars are built in one big batch or one-trade-at-a-time live. And we proved it survives a simulated crash-and-resume with no gap and no wrong values.

Why: A feature can be correct on the test sample yet still blow up on a weird real-world window (all-equal prices, a sudden spike, a tiny dataset). The bounds tests are tripwires for a whole class of formula bugs — if our normalisation constant were wrong, the complexity score would slip outside its box long before the final number looked obviously wrong. The live-vs-batch and crash-recovery tests guarantee the production streaming engine and the historical backfill agree to the last digit, and that a restart never silently corrupts the feature.

What it did: This firing made the feature self-documenting and easy to run. We wrote a decision record (an ADR) explaining exactly what the feature is, why each design choice was made, and how it is proven correct. We added a set of named commands so anyone can regenerate the reference answers, run the fast test, run the full test suite, or get a one-line health check — both as project tasks and as Claude '/' slash commands. We registered the new command file with the project and confirmed the health check passes end-to-end.

Why: Every capability in this project must be discoverable as a named command, and every non-trivial decision must be written down so a future engineer (or the operator) understands it without reading the code. The health-check command ('doctor') is the gate for this stage: it lists the commands, checks every required file exists, and re-runs the make-or-break accuracy test — a single green button that proves the feature is wired and correct.

What it did: This firing ran the project's quality checks, fixed the few issues our new code introduced, and opened the Pull Request for review. The feature's own full test suite passes (47 tests), the safety 'ban-guard' passes, the code linter is clean on our new code, and our additions are correctly formatted. The PR (number 522) opens against the supervisor's repository for review — it does NOT merge or deploy; that stays the operator's decision.

Why: Opening a reviewable PR is the goal of the whole build. Before that, the code must pass the project's automated checks so a reviewer isn't distracted by formatting or lint noise. We were careful to fix only the issues OUR code introduced and to leave the rest of the repository untouched, while honestly documenting the pre-existing problems in the project that our change did not cause.

What it did: Two independent reviewer agents stress-tested the change: an 'Attacker' hunting for correctness flaws and a 'Defender' checking every claim in the Pull Request against the actual code and tests. Crucially, I did NOT trust the agents' word — I independently re-verified every single finding by reading the files and running the tests myself before acting on it. The make-or-break maths held up under a mutation test (deliberately breaking a key constant makes the accuracy test fail, proving the test really works). I fixed the few in-scope issues found, wrote up every challenge and its outcome in a 'Challenged and held' section on the PR, and then STOPPED. The loop never merges or deploys — that decision stays with the operator.

Why: A green test suite isn't enough; a feature this precise deserves an adversarial second and third look, with claims re-checked rather than taken on faith. The biggest catch was not even a code bug: the branch had drifted behind the target repository, so the PR was accidentally showing a 'revert' of someone else's recent change to an unrelated file — re-syncing fixed it. The other real catch was that the PR claimed the tie-handling was 'proven' when it was only argued in prose; I converted that into an actual machine-checked test so the claim is now enforced, not asserted.

What it did: The operator restarted the loop in 'gap-closure' mode (every 30 min) to tidy up the open Pull Request while it waits for Monday review. First, orienting: the target repo had moved 8 commits ahead (all docs/research, none touching our feature) and two follow-up hardening commits had already landed on our branch (a 2nd audit round + the golden-snapshot regeneration that was previously deferred). I merged the latest target-repo changes in — conflict-free — making the PR cleanly MERGEABLE (it was 'unknown' before). Then the actual gap-closure stage (R1): the feature's make-or-break accuracy test lived only in an opt-in command that nothing else ran, so the project's standard 'full quality check' never exercised it. I wired both the CECP and the sibling dispersion accuracy gates into that standard check, so any future regression now fails the main gate, not just an opt-in one. I did NOT merge — that stays the operator's Monday call.

Why: An open PR goes stale as the target branch advances; left alone it can drift into conflicts or show spurious 'reverts' of other people's work (exactly the trap caught in the Stage-6 audit). Keeping the branch continuously re-synced means the reviewer always sees a clean, conflict-free diff of only our feature, and can merge with one click whenever they choose.

What it did: Added a second 'golden snapshot' test that captures the feature's actual computed numbers. The existing golden snapshot only had 46 bars — all in the 200-bar warm-up period, so every value was blank (null). This new one runs the project's small, already-committed 10,000-trade sample at a very tight bar threshold, producing 462 bars — past the warm-up — so 263 of them carry real, non-null CECP values. Those values are now frozen into a committed file; the test re-computes them and fails if anything drifts. Importantly, it also checks the warm-up boundary exactly: the first 199 bars are blank, and bar #200 is the first to carry a value.

Why: A snapshot of real values is a cheap, strong guard against accidental change: if a future edit alters the feature's output (even slightly), this test turns red. The previous all-blank golden couldn't catch that. Crucially, I framed it honestly — this is a DRIFT guard, not a proof of correctness; correctness is owned by the separate bit-exact accuracy test against the trusted library. And I did it WITHOUT the large market-data download that blocked the original golden (which is still unreachable), by reusing the small committed sample at a tight threshold.

What it did: The make-or-break accuracy test passes only if the fast Rust output matches the trusted library to within one part in a billion (1e-9). That threshold used to be a loose number typed directly into the test, which a future edit could quietly widen to hide a regression. I moved it into a single named constant and added a build-time guard that REFUSES TO COMPILE if anyone sets it looser than 1e-9. I also looked at a second proposed guard and deliberately skipped it because it would have tested nothing real — documenting clearly why, and pointing to the three existing tests that already catch the exact failure it was meant to guard against.

Why: A safety threshold is only as good as the discipline keeping it tight. By pinning it as one constant with a compile-time check, a reviewer immediately sees any attempt to loosen it (the build breaks unless they also edit the guard). The second guard was a trap: the key number it would check (the count of ordering patterns, 6) is fixed by construction, so the test would always pass and prove nothing. Shipping it would create false confidence; skipping it with a clear written rationale is the honest, higher-quality choice.

What it did: Fixed two issues in the compatibility layer (NOT part of the CECP feature itself — kept on a separate commit so the operator can split it out). First, a date-conversion helper was dividing a microsecond timestamp as if it were milliseconds, which threw every cached date ~1000x into the future and crashed with 'year 50012'. Second, the test meant to check 'graceful behaviour when the database is unreachable' wasn't actually unreachable in our environment — it quietly connected to a real database and only failed because of the first bug. I corrected the math and rewrote the test to genuinely force the unreachable path, so it now verifies the real graceful-fallback behaviour.

Why: These were caught by the adversarial audit as a pre-existing, non-CECP problem. The contract asked to close it but keep it on its own clearly-labelled commit so the operator can cherry-pick or split it from the feature PR — it shouldn't blur the line of what the CECP change touched. The test fix matters because a test that silently connects to a live database isn't testing 'no database'; it gives false confidence. Forcing the failure makes the test honest and reproducible anywhere.

What it did: Added a new command (cecp:oracle-fresh) that regenerates the feature's 'correct answers' file from scratch and compares it to the committed one — failing loudly if they differ meaningfully. This guards against a subtle risk: someone edits the small Python wrapper that defines the feature but forgets to refresh the committed reference numbers, so the fast Rust version would keep being checked against stale answers. The new command runs the regeneration and a numerical comparison, and it's now part of the feature's full quality check. I ran it for real (it needed to fetch the trusted library, which worked here) and it passed; I also proved it actually catches drift by deliberately nudging one number and watching it fail.

Why: The whole feature rests on a committed file of reference numbers. If the recipe that produces those numbers drifts away from the committed file, the safety net silently develops a hole. This check re-ties the recipe to the committed file every time it runs. I deliberately made the comparison NUMERICAL with a tiny tolerance rather than an exact byte-match, because regenerating on a slightly different Python version produces meaningless differences in the last digit or two — a byte-match would cry wolf on that noise, while a tolerance of one-trillionth catches any real change but ignores the noise.

What it did: Wrote a short, annotated walkthrough (for the operator only) of the small Python 'wrapper' that defines the feature. There is exactly one class of issue the automated accuracy check can NEVER catch — whether the feature's DEFINITION (not its maths) is the one we actually intend — and this document lays it out in plain terms with a 3-question checklist for the merge decision. This is a prepared read, kept in the loop's scratch folder (NOT in the code or the Pull Request); the loop cannot 'close' this item itself, because doing so would require building a second, independent version of the feature, which is explicitly forbidden.

Why: The trusted library only produces the two underlying numbers (entropy and complexity); it has no opinion on how we combine them into the final feature. Our reference and the fast version use the same combining logic, so if that logic were wrong, both would be wrong together and still pass the accuracy check — the test would stay green on a wrong definition. The only way to catch that is a human reading the three definitional choices and confirming they match intent. This document makes that read fast and unambiguous so the operator isn't left guessing what to look at.

What it did: Final tidy-up of the gap-closure round. I refreshed the Pull Request description with a clear 'Round 2 — gap closure' table summarising the six follow-up items (five closed in code, one left as an explicit human read for the operator), kept the existing audit section intact, and confirmed the PR is clean and one-click mergeable. Then I marked the loop DONE and stopped it — the recurring schedule is cancelled, and no further firings will run. The loop never merges; that single decision stays with the operator on Monday.

Why: The operator restarted the loop to close the audit's loose ends while the PR waited for review. With all five code-closable gaps done and the one human-only gap clearly prepared, there is nothing left for an automated loop to do — continuing would just churn. Documenting every gap and its evidence in the PR means the reviewer sees the full, honest picture and can merge confidently (or ask for the one human definition-check first).