A hash written without a review reads as green: the backfill loophole #23

Split out of #20, which documents it as a side-finding of the Intan port. It needs to outlive that issue: the loophole is general, it is how a whole MATLAB feature went missing here, and it very likely exists in NDI-python and DID-python too.

The gap

matlab_last_sync_hash is meant to record "I examined this version of this file." Nothing enforces that it means anything of the kind. Three failure modes, and after #22 only two are covered:

The third is the worst of the three, because the other two are self-correcting: a red build gets fixed. This one asserts "reviewed and current" and nothing can contradict it.

It is not a "bump" — it is a first-time backfill

I assumed someone had bumped a stale hash to clear a red build. That is not what happened, and the real mechanism matters for choosing a fix.

Commit 6377973 "Make the bridge contract complete and change-detectable" (2026-08-28):

20 files changed, 1148 insertions(+), 0 deletions(-)
  → every file is a bridge YAML or PORT_STATUS.md
  → zero Python files touched
  → zero deletions: no hash was overwritten

It added matlab_last_sync_hash to entries that had none, recording what MATLAB's HEAD looked like for each file at that moment — not the commit whose content had actually been ported. Those are different claims, and the field only supports the first.

For read_Intan_RHD2000_header.m and Intan_RHD2000_blockinfo.m, MATLAB's then-current commit was a938988 — the commit that added multi-file recording support. So the backfill wrote "examined as of a938988" onto entries whose Python had never seen that change. Everything went green, and stayed green, and the feature is still absent today:

$ grep -rn "fileMode\|multiFile\|multifile" src/ndr/format/intan/ src/ndr/reader/intan_rhd.py
(no matches)

The near-miss makes it sharper. A later commit, a14513c, recorded the two new helpers from a938988 correctly, with a decision_log that even names the commit: "Landed in NDR-matlab a938988." So a938988 was read — and the two brand-new files got honest entries — while the three already-ported files it also changed kept their backfilled hashes and said nothing. Being already recorded is what hid them.

Why a backfill is the dangerous shape

A stale hash is one entry going wrong at a time. A backfill writes the same unverified claim across every entry at once — here, 1148 lines in a single commit — and it does it at exactly the moment the bridge looks most complete. #211's 147 hashless NDI entries are candidates for precisely this treatment, so whoever closes that gap could reproduce this at scale unless the rule lands first.

Proposed check

Preferred — diff-scoped, catches the real case. In CI, if a PR adds or changes matlab_last_sync_hash on an entry while touching no Python file for that entry, require the entry's decision_log to say why the MATLAB change is a no-op on the Python side. 6377973 touched zero Python files, so this would have flagged all 1148 lines of it.

Cheap to implement — it reads the PR diff and the YAML, needs no NDR-matlab checkout, and so can live in tests/test_matlab_bridge_conventions.py and run in every job (same placement argument as #211 decision 2). The awkward part is getting the diff in a test; a small git diff origin/main...HEAD helper is probably enough, with the check skipping when there is no merge-base.

Rejected — require a decision_log on every hashed entry. Would catch it, but demands 105 boilerplate justifications here and ~98 more in NDI, and directly contradicts #211 decision 4 (a regular port carries no decision_log obligation). Boilerplate would devalue the logs that carry real reasoning, which is the same argument that won decision 4.

Also worth considering, process not mechanism. Document in spec § 5 that a hash records an examination, not a snapshot — so a bulk backfill is only legitimate when someone actually read each diff. Cheap, and it names the mistake for the next person even if the mechanical check lands later.

Cross-repo

This is a candidate for NDI-python#211 rather than a purely local concern: the field, the drift rule and the decision_log convention are shared, so the guard should be too. Flagging here because NDR-python is where the evidence is. NDI-python and DID-python should check whether their own hashes arrived by backfill — the signature is a commit touching many bridge YAMLs and no source files.

Not blocking

#22 is green and merges independently; it narrows this gap without closing it. No urgency — the Intan divergence has been present since 2026-05-06 — but the rule is worth landing before anyone backfills NDI's 147.