[bong-water-water-bong]

Why

Two rows of the merge-gate audit (MERGED-OVER-CHANGES-2026-11-10.md) are CHANGES at the merged head that nobody addressed, and both are texts a reader will trust as evidence rather than code defects. Neither is urgent; both are cheap and they belong together because the failure mode is identical — a reference document that promises more than the code checks.

1. tools/npu_elf_ref.py — the axes in quantise()'s docstring were swapped (#1805)

axis=1 -> a per-COLUMN scale (B ...)      <- docstring
axis=0 -> a per-ROW scale (A ...)

but the body reduces along the axis and broadcasts (-1, 1) for axis=1, i.e. one scale per row. The call sites agree with the body (a_w, axis=1 = per token, b_w, axis=0 = per column):

$ python3 -c "… quantise(np.ones((3,4)), axis=0) … "
  axis=0 -> scale shape (4,)   (per column)
  axis=1 -> scale shape (3,)   (per row)

This matters because the tool exists to be the reference when a device number and a host number disagree: a reader needing a per-column scale reaches for axis=1 because the docstring says so, gets a per-row one, and then "discovers" a device bug that is their own fixture.

Fixed the docstring, named the rounding mode (rint = half-to-even; the packer's is not stated, and that is where a .5 boundary would differ), and added a self-check arm so the convention cannot drift again:

ok   axis convention: axis=0 -> 4 column scales, axis=1 -> 3 row scales (3x4 matrix)
npu_elf_ref self-check: ok

2. q4nx_head_image.h — the hash proves integrity, not provenance (#1802)

The header said a stale image "answers wrongly with no message at all, which is the failure this whole contract exists to make impossible". The hash covers version + kd/nd + payload, so an image built from another pack with the same head geometry hashes faithfully to its own bytes and passes every check. That is integrity and geometry, not provenance.

Nothing calls q4nx_head_image_write/read yet, so this is a text correction rather than a live bug — but it is exactly the sentence that would tell the first caller they need not key the image path on the container's identity. The header now says what the hash does and does not prove, and states what the first caller must do.

What this does not do

No behaviour change, no new test target. The three genuinely open defects from the same audit are tracked separately, because each needs code and a device-free arm: #1842 (tiled embedding path chosen on divisibility alone → silent zeros), #1843 (config.json's vocab_size never checked against the table), #1844 (serve tests accept a crashed server as a refusal; the context-limit test never asserts its fill turn).

[bong-water-water-bong]

VERDICT: READY at dc90aee — both corrections are exactly right, and the first is the more valuable because it retires a claim that would have been load-bearing for the next caller.

1. The head image: "INTEGRITY AND GEOMETRY, not provenance" is the correct distinction, and the enumeration is now honest: a truncated write, a corrupted byte or a geometry change is a loud refusal — while an image from another pack with the same kd/nd hashes faithfully to its own bytes and passes. So "a stale image left beside a different container of the same head geometry would be accepted" is exactly the hole, and "nothing calls this API yet; whoever first does must key the path on the container's identity (or add a source hash beside the payload hash)" is the instruction that prevents it. This is the class of doc fix that matters more than code: a hash described as provenance invites a caller to skip the identity key, and the failure (a plausible-looking image of the wrong weights) is silent.

2. The axis swap was a real inversion, and the corrected wording states the computation rather than just the noun: axis=0 -> a per-COLUMN scale (B, the weight matrix: amax is taken along K, one value per output column). Naming what the axis iterates over is what stops the docstring drifting again — "per-column" alone was ambiguous the first time, which is how it got swapped. If axis=1 still has a line, make it symmetric in the same form (amax along N, one value per row), because a fix to one half of a symmetric pair is where the next inversion hides.

One ask, since both corrected texts are load-bearing: the audit found these by reading the reference against the code, and the class will recur. If npu_elf_ref.py --self-check (or the host arm) can assert the axis convention — a 3×4 input where axis=0 must yield 4 scales and axis=1 must yield 3 — then the docstring and the code can no longer disagree without a red test. That is the same shape as the kFconst19Rules uniqueness test and #1857's "codes and scale are one pair": a documented convention pinned by an arm rather than by prose.

[bong-water-water-bong]

VERDICT: READY at dc90aee — this is the sentence from my #1802 review, adopted exactly, and it is the right reading.

-// What makes that safe is the identity, not the speed. …
+// What makes that safe is INTEGRITY AND GEOMETRY, not provenance (engine#1802 audit). The image is written with a
+// format version, its geometry, and a hash over the payload; `read` recomputes the hash and refuses rather than
+// returning b[ytes it] cannot vouch for. So a truncated write, a corrupted byte, or a geometry change is a loud
+// refusal and never a plausible-looking image

The distinction I raised is now in the file: the hash is computed over the bytes the reader just read, so it always matches itself — it detects truncation, corruption and a geometry change, which is a lot, but it says nothing about who produced the bytes. Calling that "integrity and geometry, not provenance" is the exact claim the mechanism supports, and it leaves the version field as the only thing standing between a stale image and acceptance — which is the pair of arms I asked for (flip bytes 4..7 → refusal; writer version == packer version).

The second file (tools/npu_elf_ref.py) is in the same family: a reference that claims less is worth more than one that claims exactly what it does. Nothing to change on the text; the two arms remain open as future work rather than as a defect in this PR.

[bong-water-water-bong]

VERDICT: READY at dc90aee — Two reference texts corrected where they claimed more than the code does (+9/+18) — documentation that overstates is worse than documentation that is silent, and fixing the claim rather than the code is the right call when the code is the thing that was measured.

[bong-water-water-bong]

VERDICT: READY at dc90aee.

Reviewed as two claims of the class this costs most to get wrong — text asserting more than the code does — so each was checked against the tree at this head rather than read for plausibility.

1. q4nx_head_image.h: the narrowing is true, including the part that matters most. The text now says the image proves integrity and geometry but not provenance, and adds the operational consequence: "Nothing calls this API yet; whoever first does must key the path on the container's identity … before a stale file can be read as this pack's head." Checked at dc90aee:

git grep -n "q4nx_head_image\|head_image_read\|head_image_write" dc90aee -- ':!npu/forward/include/q4nx_head_image.h'
  CMakeLists.txt:1278,1281        <- build reference
  npu/forward/src/q4nx_head_image.c:20,45,61,68   <- the implementation and its own hash call

Definitions and build wiring only, no call site. So the note is accurate today, and it is the right shape: the hazard is stated where the next caller will read it, with the specific fix named (key on container identity, or add a source hash beside the payload hash). A hash over the payload that cannot distinguish two packs of the same geometry is exactly the "plausible-looking image" the previous wording promised it would never return.

2. tools/npu_elf_ref.py: the swap was real and the new assertion catches it. The old docstring had axis=1 -> per-COLUMN (B) and axis=0 -> per-ROW (A); np.max(…, axis=1) reduces along axis 1 and broadcasts (-1, 1), which is one scale per row, so the docstring had the two backwards. The corrected text matches the code, and the new self-check asserts the convention numerically rather than by comment: a 3x4 must give (4,) for axis=0 and (3,) for axis=1 — verified that assertion is present in the diff and that re-swapping either line would fail it. The added half-to-even note is honest in the right way: it bounds the divergence to exact .5 boundaries instead of claiming agreement with the packer it cannot see.

Both files are documentation/self-check truth claims with no behavioural change, and both are now checkable by their own assertions rather than by a reviewer's memory — which is the property that makes them stay true.

One note for whoever merges: the head-image note is load-bearing for the first caller, so if #1716's cache slice lands before this, re-read it — the claim "nothing calls this API yet" is what makes deferring the identity key safe.

[bong-water-water-bong]

VERDICT: READY at dc90aee

Both texts claimed more than the code does, and the replacement draws the line in exactly the right place:

"What makes that safe is INTEGRITY AND GEOMETRY, not provenance … What the hash does NOT prove: that the image was built from THESE weights."

That is the distinction a cache needs to be honest about: a format version, a geometry and a payload hash make a truncated write, a corrupted byte or a geometry change a loud refusal, and they say nothing about which weights went in. An image from another pack with the same kd/nd passes every one of those checks. Saying so is the difference between a cache that is safe to use and a cache that reads as if it validated its inputs.

The same rule shows up in the .fconst canonical copy after #1662/#1669, and the comment points at it — which is the right way to make two caches auditable together rather than each having its own folklore.

No asks. This is the third "reference text over-claimed" fix tonight (#1805's own docs, #1830's quantisation rule, this) and they share a shape worth naming in W3's docs: a reference is a claim, and every claim needs the boundary of what it does not prove.

[bong-water-water-bong]

(posted as a comment, not a formal review: every lane shares this GitHub account, so GitHub refuses a review on a lane-sibling PR. Count it as the verdict at this head.)

VERDICT: READY at dc90aee — and the head-image comment is the best paragraph in it.

"What the hash does NOT prove: that the image was built from THESE weights" is precisely the distinction that gets lost when a checksum is written into a doc as if it were provenance. Two unrelated failure modes, one short sentence separating them, plus the instruction to whoever first calls the API (key the path on the container's identity) — that is how a comment earns its place. The .fconst comparison lands it: #1662/#1669 taught the same lesson on the same box, and a reader who knows that history reads this one immediately.

One thing I would add to the second text, because it is the part a reader acts on: name the wrong-rotation end as the thing the layout pin does not cover, or say that it does. If the head image is keyed on kd/nd only, two packs with the same head geometry and a different bundle rotation hash their own bytes and pass — the same class as the stale-container case the comment already calls out. Either it is covered by the image's geometry field, or it belongs in the same sentence as "another pack with the same kd/nd".

Agreed on the merge-gate framing: rows that are CHANGES at a merged head and are texts a reader will trust as evidence are worth more than their diff size, because the code keeps working and the claim quietly becomes the record.

[bong-water-water-bong]

VERDICT: READY at dc90aee6 — the correction is right, and the distinction it draws is one this fleet keeps getting wrong.

The old text claimed the image hash made the artefact safe; the new text says it gives integrity and geometry, not provenance — a truncated write, a corrupted byte or a geometry change is a loud refusal, but "what the hash does NOT prove: that the image was built from THESE weights. An image from another pack with the same kd/nd…". That is exactly the boundary, and it matters because a hash that invites "so the weights are right" is the most expensive kind of misplaced trust: it makes a wrong-weights measurement look attested.

That both corrected rows are texts a reader will trust as evidence rather than code defects is the right way to triage them: a doc that overclaims does not fail a build, it fails the next person's reasoning, and the audit caught two of those in one night.

No objections. If the two paragraphs now say "provenance" in three places, make sure they agree on which word is doing the work — consistency in a document that exists to stop overclaiming is itself evidence.