Answer

BFS-027 — An uncacheable read is now a named, counted bypass

I cloned github.com/deployBunker/bunker, reproduced the defect, implemented the fix on branch wt/BFS-027 (commit 7bb1a00), and verified it. The full solution is also written to /workspace/BFS-027-solution.md and docs/evidence/BFS-027-uncacheable-census.md.

Symptom

BFS-009's uncacheable arm read bytes whose surface-declared hash differed from the body's real hash. The client correctly refused to cache them, but nothing moved — no blob, no index entry, no counter:

surface says  : sha256:1195d8cc…
body hashes to: sha256:de7c33de…
before : blobs_on_disk=1  target.txt_in_index=absent  … bypass=0 oversize=0 hits=0 misses=0
after  : blobs_on_disk=1  target.txt_in_index=absent  … bypass=0 oversize=0 hits=0 misses=0

BFS-005 §3.4 requires every read the client did not cache to be reported.

Root cause

The single content-identity refusal site is Cache.Insert in internal/fsclient/cache.go. The live FUSE read path (readHandle.load) calls Cache.AdmitRead → Cache.Insert. The cap/no-room/disabled refusals all count a bypass_reason; the identity-mismatch branch returned OutcomeBypass silently, and the refusal class was not even part of the closed BypassReasons() vocabulary. This is BFS-032's shape one site over.

Fix

// internal/fsclient/cache.go — closed vocabulary
BypassReasonContentMismatch = "content_mismatch"

func BypassReasons() []string {
    return []string{
        BypassReasonOverEntryCap,
        BypassReasonInsertOverEntryCap,
        BypassReasonNoRoom,
        BypassReasonDisabled,
        BypassReasonContentMismatch,   // new
    }
}

// Insert: hash first (never under the lock), then count under it
got := HashBytes(data)
c.mu.Lock()
defer c.mu.Unlock()
if got != hash {
    c.countBypassLocked(BypassReasonContentMismatch)   // new
    return OutcomeBypass, fmt.Errorf("fsclient: refusing to store %s under %s (content hashes to %s)", path, hash, got)
}

I also registered cache.bypass_reasons.content_mismatch in the BFS-045 census table (and drove it), and added TestContentIdentityMismatchRefusalIsCountedByReason to admitread_test.go with a faithful-read control.

BypassReasons() drives both the JSON census and the human bypassSummary, so the reason is visible everywhere. Cached reads are untouched — the branch is only entered when HashBytes(data) != hash.

Verification (all observed green)

go test ./internal/fsclient/ -run 'TestContentIdentityMismatchRefusalIsCountedByReason' -v -count=1
# --- PASS: TestContentIdentityMismatchRefusalIsCountedByReason (0.00s)

go test ./internal/fsclient/ -run TestEveryFigureInTheStatusRecordMovesOrIsExplained -v -count=1 | grep content_mismatch
# === RUN   …/figure/cache.bypass_reasons.content_mismatch
#   moved cache.bypass_reasons.content_mismatch          1
#   --- PASS

go vet ./internal/fsclient/ && go test ./internal/fsclient/ -count=1 && go test ./internal/fsmount/ -count=1 && go build ./...
# ok  github.com/deployBunker/bunker/internal/fsclient  41.888s
# ok  github.com/deployBunker/bunker/internal/fsmount   0.257s

internal/fsmount contains readHandle.load, the function a FUSE read actually calls, so the admission change is covered by the live-path package suite. This container has no /dev/fuse, so the FUSE-level probe from docs/evidence/BFS-009-probes/uncacheable-probe.sh cannot run here; §5.4 of the written solution gives the exact invocation for a FUSE-capable host, where the status document now carries "content_mismatch": 1.

Deliverables

• internal/fsclient/cache.go — new reason + counting at the refusal site
• internal/fsclient/admitread_test.go — acceptance arm + control
• internal/fsclient/status_census_test.go — census classification + workload driver
• /workspace/BFS-027-solution.md and docs/evidence/BFS-027-uncacheable-census.md — the full self-contained writeup (root cause, exact diff, why the name, acceptance mapping)

The complete markdown solution is at /workspace/BFS-027-solution.md.