rest: flush-chain integrity — composition test, FlushError convention guard, error-path fakes

[SyniRon]

Surfaced by the wave-1 review (#167, PR #171).

#167's acceptance criterion "flush succeeds from a handler" currently holds by composition of per-layer pins (sentry, metrics, cachecontrol, gzip each pinned individually); nothing pins the composed property. A wrapper inserted into rest.New tomorrow without FlushError/Flusher/Unwrap breaks handler flushes in production with every existing test green.

1. One internal test assembling the New-shaped stack (sentry → metrics → auth → sentryLabel → gzip → cacheControl → flushing probe handler) over a real server: flush succeeds, prefix streams.
2. Mechanical convention test (cf. types/: mechanical tag-lint test enforcing wire conventions #148/types: mechanical tag-lint test enforcing wire conventions (#148) #162 tag-lint): every ResponseWriter wrapper in the rest package implements FlushError() error or doesn't intercept flush at all — never bare Flush(), whose errors the controller's Flusher branch silently swallows.
3. Error-path fakes: a delegate whose FlushError returns a genuine I/O error (propagated verbatim through gzip's FlushError), and a write-failing base under gz.Flush() itself (early return, sticky gzip.Writer error, Close-path log backstop).
4. Comment fix: rest/metrics_internal_test.go:15-17 "(the recorder implements Flusher directly and would mask the gap)" — same false rationale family corrected in gzip_test.go on rest: gzipResponseWriter supports no flush and no Unwrap — ResponseController dead-ends on the gzip chain #167's branch; verified false here too (the walk dead-ends at statusWriter before any recorder is reached).

🤖 Generated with Claude Code

[SyniRon]

Two additions from the #165 review (same wrapper-convention-guard family as item 2):

1. Informational-predicate lint: every WriteHeader method on a ResponseWriter-embedding type in package rest must reference informational() — rest: 1xx WriteHeader burns the commit latch in all three writer wrappers #165's table test covers wrappers by voluntary enrollment; a fourth WriteHeader-stateful wrapper added without the guard or the table row reintroduces the exact rest: 1xx WriteHeader burns the commit latch in all three writer wrappers #165 bug class invisibly. Same AST-test shape as the FlushError convention guard.

2. statusWriter flush blind spot: statusWriter has no FlushError (flushes tunnel past via Unwrap), so a flush-committed implied 200 is invisible to the status capture — flush-then-panic meters 500 against a wire-committed 200. Pre-existing; option: give statusWriter the same FlushError treatment rest: commitWriter.FlushError leaves committed=true when the delegated flush fails #164/rest: gzipResponseWriter supports no flush and no Unwrap — ResponseController dead-ends on the gzip chain #167 gave the other two wrappers (capture the implied 200 before delegating).

🤖 Generated with Claude Code

[SyniRon]

This was generated by AI during triage.

Scope addition (triage ruling 2026-06-07, from #181's close-out): item 2's mechanical convention sweep gains a sibling guard —

5. Hijack tripwire: a convention test in the same types/: mechanical tag-lint test enforcing wire conventions #148/types: mechanical tag-lint test enforcing wire conventions (#148) #162/rest: mechanically guard route="" ⇔ never-routed against future direct registrations #173 mechanical family asserting no production code in the rest package hijacks (no Hijacker assertion, no ResponseController.Hijack call — today trivially true, grep finds only comments). Failure message must say: mount upgrade endpoints OUTSIDE GzipMiddleware, or implement the faithfulness spec preserved in .out-of-scope/gzip-hijack-faithfulness.md (PR triage: found .out-of-scope/ with the gzip hijack-faithfulness rejection (#181) #185, from rest: gzip close-log hijack faithfulness — distinguish clean takeover from abandoned-output corruption #181). Rationale: the gzip close-log's coarse ErrHijacked carve-out (rest: gzip WriteHeader commits stale Content-Length (verified silent corruption); ErrHijacked close-log carve-out #175) is only safe while no handler hijacks through the chain; this makes that precondition self-announcing instead of remembered.