D2.3 /v1/shader/token-agreement handler (Phase 2 scaffold complete)

[AdaWorldAPI]

Summary

D2.3 — /v1/shader/token-agreement handler wiring. Closes the Phase 2 surface: Phase 0 Wire DTOs (D0.2 WireTokenAgreement) + Phase 2 harness (D2.1 TokenAgreementHarness) now round-trip end-to-end through HTTP.

117/117 tests pass (unchanged from D2.1 — handler's logic is a thin pass-through and the harness is already covered by 13 D2.1 tests).

End-to-end flow

WireTokenAgreement (JSON ingress)
    ↓ serde_json::from   ← Rule F: edge only
Handler: candidate: WireCodecParams → CodecParams via TryFrom
    ↓ precision-ladder + overfit guard fire at ingress
ReferenceModel::load(&req.model_path) when path exists
  OR ReferenceModel::stub(hash(model_path), 0) when it doesn't
    ↓ deterministic stub keyed on model_path for regression tests
TokenAgreementHarness::new(ref, baseline, candidate, n_tokens)
    ↓
.measure_stub() → WireTokenAgreementResult { stub:true, backend:"stub" }
    ↓ serde_json::to    ← Rule F: edge only
HTTP 200 Json response

Typed errors at handler boundary

• BAD_REQUEST + "invalid CodecParams: <CodecParamsError>" — precision-ladder / overfit-guard failures
• BAD_REQUEST + "model load: ModelPathMissing { path }" — explicit path specified but doesn't exist
• BAD_REQUEST + stringified TokenAgreementError — e.g., EmptyPromptSet when n_tokens = 0

Why the stub: true wall matters end-to-end

Client sends WireTokenAgreement over HTTP → handler returns 200 OK with WireTokenAgreementResult. Without the stub flag in the response, a client pipeline could silently treat 0.0 rates as real measurements — the #219 pattern at the HTTP boundary. With the flag, any assert!(!result.stub) in the client fails the pipeline loudly. The Phase 0 / D2.1 anti-#219 discipline extends through the HTTP surface unbroken.

Stub-fallback semantics

When req.model_path doesn't exist on the filesystem:

let mut h = DefaultHasher::new();
req.model_path.hash(&mut h);
ReferenceModel::stub(h.finish(), 0)

Deterministic: same path string → same stub fingerprint across calls. Test harnesses can POST synthetic model_path values ("stub://my-test-model") and get repeatable responses without needing a real safetensors file. D2.2 replaces this with strict path validation once the real loader lands.

Phase state after merge

Phase	Status
Phase 0	✅ Complete
Phase 1 scaffold (D1.1 / D1.2 / D1.3)	✅ Complete
Phase 1 D1.1b Cranelift	⏳ Queued
Phase 2 scaffold (D2.1 harness + D2.3 handler)	✅ Complete after merge
Phase 2 D2.2 real decode-and-compare	⏳ Queued
Phase 3-5	⏳ Queued

Rules honored

• Rule F — serde at the HTTP edge only (Json<WireTokenAgreement> ingress + Json<WireTokenAgreementResult> egress); CodecParams + ReferenceModel + TokenAgreementHarness are in-memory Rust objects, zero re-serialization between.
• Rule E — Wire surface preserves method-access (TokenAgreementHarness::measure_stub() is invoked by the handler; Wire DTOs carry the lane-aware WireCodecParams).

Board hygiene (same commit)

• STATUS_BOARD.md — D2.3 Queued → In PR.

https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh