Why strategy A failed the 99.9% gate at 60Hz before any code ran

Exit code 4. That was Spike.Meter’s verdict on the first real matrix run against the gate we’d written into the phase-1 spec for a Windows shell decorator: two physical pixels of error for 99.9% of sampled frames during a drag, no sustained lag past one refresh interval. Two separate passes had signed off on that number, a design review of the original ticket and then the phase-1 slicing document that turned the review into a testable spec. It read as rigorous. It was also arithmetically impossible for any implementation to pass.

What the spike was measuring

We’re building a small overlay window, Spike.Tracker in the spike, that has to sit flush above another process’s window and follow it in real time as it’s dragged around the desktop, the way an existing Windows window-tabbing utility already does. The design review had flagged a real constraint on the mechanism. SetWinEventHook on another process is normally delivered out-of-context, queued through the registering thread’s message loop, with no guarantee about which composited frame the callback lands in. We built the first spike to find out whether that mattered in practice.

Three pieces:

• Spike.Target is a plain popup window with four 16x16 fiducial markers baked into its corners.
• Spike.Tracker is the WinEvent-hook decorator under test.
• Spike.Meter runs DXGI Desktop Duplication on the same monitor and scans every composited frame for those markers, computing error and lag from pixels. It never asks GetWindowRect, which only tells you what the window thinks its position is. The meter tells you what actually got drawn.

Spike.Tracker ships four strategies: A chases the WinEvent hook, B rides an owned window that needs nothing per frame, D polls every 250ms, and the spec’s default pick was A.

A week of tuning the wrong thing

We spent the better part of a week assuming the gate was reachable and that a failing run meant a bug. Runs against strategy A came back consistently short of 99.9% inside 2px, so we did what you do when a number looks close. We tuned. We tried different z-order modes (after-target versus keep versus topmost), tighter coalescing in the hook callback, and stripped every allocation out of the render path so GC would never fire mid-drag. Each change moved the histogram a little. None of them touched the tail. We burned real spike time chasing a number that had nothing to do with the tracker’s code.

The flag that flipped the question

The --inject-delay flag is what broke the assumption. It applies every placement N nominal refresh intervals late on command, a known deliberate lag, so you can confirm the meter detects lag instead of reporting favorable noise. We ran it at --inject-delay 0, no injected lag at all, on top of the already-optimized strategy A. It still failed the pixel gate under --synthetic drag at real drag speeds. That’s where the question changed from “why is the tracker slow” to “what is this gate actually demanding.”

The arithmetic is short. Positional error on a moving target is velocity times lag. A hand-driven drag isn’t a fixed speed. The spike’s own drag mode drives the real cursor through SendInput with a hand-like wobble, and normal fast drags land somewhere around 500 to 1800 pixels per second. At 60Hz, one refresh interval is 16.7ms. A single frame of lag, the same frame the WinEvent hook’s out-of-context delivery already costs before any of our code runs, works out to 8 to 30 pixels of positional error at those speeds.

The gate asked for under 2 pixels, 99.9% of the time, during exactly the condition that produces 8 to 30. No z-order mode, no allocation-free render path, no amount of hook coalescing closes that gap, because the gap lies outside the implementation. The gate treated pixel error and frame lag as the same measurement.

What replaced it

The new gate measures the thing that is actually true or false about the mechanism: lag counted in frames, and the variance of that lag, with no translation into pixels. A decorator that’s reliably one frame behind, every time, at any drag speed, reads to a human eye as attached, because the offset is constant and the brain folds a fixed lag into the object. A decorator that’s sometimes zero frames behind and sometimes three, with the same average lag, reads as broken, because the change in offset is what your eye tracks.

Spike.Meter already had the raw material in frames.csv and its per-segment lag fields. The fix was to stop collapsing that into one pixel-error number and report the distribution and its spread instead.

Before an acceptance gate gets a third sign-off, work the arithmetic from the speeds and timings involved and see whether a correct implementation could pass it at all.

dxdev LESSON · paste into your AI coding agent
LESSON: Check That a Pass Threshold Is Reachable by Running the Measurement With Zero Injected Fault Before Tuning the Implementation
SOURCE: dxdev.com/blog/the-gate-that-was-arithmetically-impossible
WHAT HAPPENED: The team wrote a gate into a spec for a Windows overlay that tracks another process's window during a drag. Spike.Meter measured error from composited pixels and returned exit code 4 on the first real run. They assumed a bug and spent about a week tuning z-order modes, hook coalescing and render-path allocations, and none of it changed the tail. Running with --inject-delay 0 still failed the gate at real drag speeds, which showed the tracker was not the problem. Positional error is velocity times lag, so at 500 to 1800 pixels per second and a 16.7ms frame, one frame of lag already means 8 to 30 pixels. The gate demanded under 2 pixels during exactly the condition that produces 8 to 30, so it was replaced with lag counted in frames and the spread of that lag.
THE RULE: Before tuning an implementation to meet a threshold, check that the threshold is achievable by working out the arithmetic and by running the measurement with no injected fault. A gate that a correct implementation cannot pass is a broken instrument, not a stricter bar.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
      1. For each pass/fail threshold in a spec, there is a written derivation showing that a correct implementation can meet it under the conditions the test applies.
      2. The measurement harness has been run with a zero-fault or ideal baseline, such as an injected delay of 0, and that baseline result was reviewed before any tuning began.
      3. Metrics that mix two quantities, such as pixel error combining speed and frame lag, have been separated so the gate measures the property the mechanism actually controls.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.