# Frame probe — the five-minute discriminating test

**Slug:** `frame-probe` · **Lesson:** `probe-first` · **Status:** check green in this tree (tally in the library receipt; registry flip is the integrator's step).

## Lesson

Before any lane is briefed on a visual defect, run the cheapest
discriminating test (LEARNING-PROTOCOL §10, rule 38): name the
region the eye named, name the value the complaint names, diff the
two frames, count the value in the box. The instrument answers
exactly one question — *did THIS change, HERE?* — and answers it
before any census, theory or rebuild exists.

The founding failure (THE-PICTURE-CASE, 2026-11-06): the founder
rejected a frame for grey holes in two NPCs; the discriminating test
existed at minute zero and was first run at minute ~29, after lanes
had already been briefed on a wrong theory. When it ran, it took
~2 minutes by hand and convicted instantly: the "fix" (v16 → v17)
had changed 546 px, all (0,0,0) → (0,0,8), and had not touched the
named defect by one pixel — the road grey in the figure boxes stood
at 223 / 206 in both frames. The real fix (v17 → v18) removed it:
223 → 0, 206 → 0.

Two disciplines ride with the instrument:

- **A count without its box is half a fact.** Counts are
  convention-sensitive at the ±1-edge level (the record carried
  223 / 224 / 239 / 307 for the same defect under different boxes
  and two printed table figures no box supports). Briefs cite boxes
  by coordinates. The canonical boxes here are the sweep's Stage-6
  boxes, settled by the probe receipt's Correction of Record.
- **The gate must bite.** Assertions are part of the instrument:
  the receipt's negative control (asserting the wrong night's diff)
  fails with exit 1. This port restages that control in its check.

## Provenance

Port of `~/workspace/tools/frame_probe.py` (committed house tool,
TOOLBOX-listed), calibrated by `~/workspace/classroom/
overnight-2026-11-07/RECEIPT-probe.md` — including its **Correction
of Record**, which settles the box question: the sweep's own
Stage-6 boxes give the parent's numbers exactly, and the sweep
receipt's printed 224 / 239 were text figures the boxes don't
support. Where any secondhand figure disagrees with that receipt,
the receipt wins; this program's check follows the receipt.

Fixtures are the filed frames themselves, copied untouched from
`gamem8c-sprites1/frames/`: `frame-nb-v16-anchor.png`,
`frame-nb-v17-anchor.png`, `frame-nb-v18-anchor.png` (640×576 RGB).

PNG decoding is written in-file on `node:zlib` (the dimentra-review
`tools/png.cjs` encoder was read first; it is encode-only, so the
decoder here is fresh code, calibrated by the filed numbers below).

## How to run

```text
node example.cjs   # the picture case as a worked example + JSON line
node check.cjs     # self-check: prints PASS <n> FAIL <m>, exit 1 on any failure
const { runCheck } = require('./check.cjs');
const P = require('./program.cjs');  // decodePNG, frameDiff, countValue, probe, assertions
```

## Worked example

`example.cjs` re-runs the picture case: v16 → v17 diff 546 px with
the single transition (0, 0, 0) → (0, 0, 8) and road grey unmoved
(223 → 223, 206 → 206); v17 → v18 diff 3,040 px and road grey
223 → 0, 206 → 0.

## Numbers reproduced (all filed, all exact)

From `RECEIPT-probe.md` (Correction of Record applied), boxes
topNPC (325,0,370,65) and rightNPC (500,325,565,395), value
(115,109,115):

| claim | filed | this check |
|---|---|---|
| v16 → v17 frame diff | 546 px | 546 |
| v16 → v17 transitions | all (0,0,0)→(0,0,8) | single transition, 546 |
| road grey, v16 | 223 / 206 | 223 / 206 |
| road grey, v17 | 223 / 206 | 223 / 206 |
| road grey, v18 | 0 / 0 | 0 / 0 |
| v17 → v18 frame diff | 3,040 px | 3,040 |
| v17 → v18 per-box remap | (115,109,115)→(66,60,66), 223 and 206 | exact |

Negative control: asserting diff == 546 against v17 → v18 fails
(got 3,040), as filed.

## Consumers

Every visual lane's pre-flight (a visual brief names its probe
result or it has not run the probe), classroom discipline (rule 38
as a runnable habit, not prose).

## Honest limits

- The probe measures *values in boxes*. It cannot name what a
  colour *is* — and a wrong box gives a true answer to a wrong
  question. Box coordinates are part of the claim; file them.
- The Python original also writes zoomed crop PNGs beside the
  numbers (the crop is what names the colour). This port ships the
  numbers and diffs only — no PNG encoder — so the crop half of the
  discipline still runs through `tools/frame_probe.py` until an
  encoder is added here. Stated plainly rather than stubbed.
- Decoder scope: non-interlaced PNGs, bit depth 8/16, colour types
  0/2/3/4/6. Interlaced (Adam7) frames are refused with an error,
  not silently misread. The house frames are 8-bit RGB, type 2.
- Transition ordering matches the source (count desc); tie order
  can differ from Python's — no filed claim turns on a tie.
