Rating fix pass: ratify quantize-then-multiply, sub-9dp guard, base_model plumbing (#14 battery + decisions)

[hhuuggoo]

Fix pass on PR #14 (the YAML-rater rework), implementing Hugo's E1–E4 decisions and the round-1 battery findings. Stacked on yaml-rater. Money-path; every behavioral change pairs with an invariant-named test, and the oracle/conformance discipline is preserved (proven-teeth on the new sub-nano residue fixture).

Contracts (read first — the load-bearing surface)

• New base_model event field + billing_event.base_model column. A fine-tune's HF base id rides on the metering event (E3, option a), stamped by Atlas at deploy. Atlas-side plumbing seam: atlas-auth must inject the base id on the X-Saturn-Base-Model header and add it to Traefik's authResponseHeaders allowlist (exactly as for X-Saturn-Auth-Id). Phoebe reads it defensively (absent = ""). An ft: model with an empty base_model fails loud (ErrNoPrice / UNPRICED), never silently $0.
• Ratified rounding spec: quantize-then-multiply. The per-token rate (premium applied to the exact base rate) is quantized to 9dp before multiplying token counts, so the applied rate stored on each rated_usage row × tokens exactly reconstructs the billed cost (E1 self-auditing). This differs from sum-then-round only on a sub-nano premium residue and is a forced consequence of storing the rate on the row.
• Sub-9dp price guard (fail closed). A per-token rate that is nonzero in the YAML but quantizes to $0 at 9dp is rejected at load (it would serve the model FREE). A literal 0 is still allowed.

The fixes (one commit each)

1. Ratify quantize-then-multiply; recalibrate oracle + prove teeth. Rewrote doc.go's ROUNDING / PRODUCTION-vs-ORACLE sections (they still documented sum-then-round); fixed the integration oracle to feed rate.Quantized() (it fed the un-quantized rate while production bills the quantized one — a latent miscalibration, since the existing fixture had no residue); corrected Rate()'s doc. Added TestConformance_OracleQuantizesBeforeMultiply_OnResidue — a 1-nano × 1.5 = 0.0000000015 → 0.000000002 fixture that bills 6 nano over 3 tokens and proves the guard has teeth (sum-then-round gives 5 nano; a revert flips it RED).
2. Fail-closed sub-9dp guard at price-file load (parseNonNegRate), naming the offending model/field/rate. TestLoad_SubNanoRateRoundsToZeroFailsClosed pins all arms (sub-nano rejected, half-up boundary loads, literal $0 loads, fine-tune own-rate covered).
3. Plumb base_model so ft:<checkpoint> ids price. metering.Event.BaseModel + billing_event.base_model column (0001 SQL + billing_event Alembic create, plus idempotent ADD COLUMN IF NOT EXISTS in the rating migration / 0002); X-Saturn-Base-Model identity header carried onto the Event in proxy.emit (completion AND pre-header-abort paths); drain store INSERT extended. Rater: PriceBook.ResolveEvent + a second TEMP rating_derived table (base_model → premium-applied, quantized) with a direct-over-derived COALESCE, deriving only for an ft: id that missed the direct join and carries a base_model. Tests: TestRater_FineTunePricesViaBaseModelOnEvent, TestRater_FineTuneWithoutBaseModelFailsLoud, TestResolveEvent_FineTuneViaBaseModel, live-PG TestIntegration_FineTunePricesViaBaseModel, and end-to-end TestE2E_FineTuneBillsAtBaseTimesPremium.
4. Mechanical findings (held back by the battery): event_count widened to BIGINT end to end (SQL cast, column in 0002/Alembic/integration schema, e2e scan); deleted dead ErrDerivationChain (one-hop is enforced at load); renamed the overclaiming TestConformance_SQLModelMatchesRateOracle → TestOracleModel_SelfConsistent (it runs no SQL); fixed TestLoad_MalformedYAMLFailsClosed's doc to enumerate the inconsistent-premium cases it tests; corrected the stale "pointer-not-copy" comment; fixed RateResult.TotalCost doc ("0", not "").

Gate

go build ./..., gofmt -l . (empty), go vet ./... and go vet -tags=integration ./..., go test -race ./..., golangci-lint v1.64.8 (default + integration tags) — all clean. Live-Postgres integration and the e2e pipeline test run green with -race -tags=integration.

Should land on #14's lineage. Once merged into yaml-rater, re-run the battery to dry.

[hhuuggoo]

🔋 Battery review — Round 1 (status: ESCALATE)

Tier-2 review of the fine-tune-pricing fix pass. 19 raw → 5 refuted → 14 confirmed + 5 persona. The base_model plumbing works, but the derived-rate path has correctness gaps the round-1 fixes didn't cover. Not merge-ready.

🔴 High-sev mechanical (will fix) — the round-to-zero guard misses the derived path

The sub-9dp guard added last pass only protects file-declared rates. A fine-tune premium that drives the derived rate to $0 (factor "0", a tiny fractional factor, a negative-rounding markup) is not rejected → every ft: event bills $0, silently, counted as rated not unpriced. Same bug class as the guard we just added, on the path it didn't cover. Battery proved it empirically. Fix: apply the round-to-zero fail-closed guard to the derived rate at load time too. (Mechanical — I'll fix it.)

🛑 Decisions for Hugo

1. Same ft: id, different bases → one rollup or two? (the rollup-grain one-way door.) rated_usage's key is (auth_id, model_id, window_start) — it omits base_model. So two fine-tune deployments reporting the same ft: model_id but derived from different bases merge into one rollup at a single rate (and the applied-rate columns take MIN, so the cheaper base wins — under-billing). In practice ft:<checkpoint_artifact_id> is globally unique, so this likely can't happen — but it depends on that uniqueness being guaranteed. Decide: is ft: id globally unique (then this is impossible — add a comment + a uniqueness assertion and move on), or can two deployments share one (then base_model must join the rollup key + migration)? My read: checkpoint artifact ids are uuid4, so unique — but you own confirming the invariant.

2. Own-rate fine-tune as a derivation base → multi-hop pricing (the one-hop contract). A fine-tune with its own explicit rate is currently projected as a possible base for another fine-tune's premium → a fine-tune deriving from a fine-tune, which the one-hop rule was meant to forbid. The Go oracle mirrors this, so the conformance test can't catch it. Decide the intended one-hop contract: exclude own-rate fine-tunes from being derivation bases (my lean — matches "one hop only"), or accept fine-tune-of-fine-tune pricing. Then the filter + oracle get fixed together.

🟡 Smaller design/contract (I'll fix once #1–#2 land)

• Migration-chain ownership: the rating migration's downgrade() drops billing_event.base_model, but that column is now owned by the billing_event create migration — a partial downgrade leaves a diverged schema. Fix: rating's downgrade shouldn't drop a column it doesn't own.
• Prefix encoded twice: SQL hardcodes 'ft:%' while Go reads the fineTunePrefix constant — two sources of truth for a money-path contract. Single-source it.
• The base_model-absent fail-loud path (Capture X-Saturn-Auth-Id (token identity) into metering events #1 from escalations) — operational blast radius of the cross-repo header seam: if Traefik doesn't allowlist X-Saturn-Base-Model, all fine-tune traffic goes UNPRICED (fail-loud, not silent — correct, but it means fine-tune billing is dark until the header is wired). Worth knowing for the Atlas-side rollout.
• Plus: the deterministic rollup-id md5 separator collision, several overclaiming doc comments asserting invariants that don't hold, a missing e2e fail-closed assertion.

---

Battery wf_52b37bcb-f37. #15 needs the derived-rate guard (high-sev) + decisions 1–2, then a fix pass + re-battery. The base_model mechanism is sound; the derived-pricing edges are what need tightening.

[hhuuggoo]

Landed on main via the squashed rating merge (3b22908). Closing the stack.