fix(promotion): refuse to call a candidate cheaper on dollars nobody measured

[drewstone]

Problem

BenchmarkCell (run-benchmark.ts:77) carries usd: number and usdKnown: boolean as required siblings. promotionGate read usd from both arms (:88-89) and never read usdKnown — zero occurrences in the file.

In non-inferiority mode a significant paired cost saving is a promotion criterion (:151): "(b) cost SAVINGS (incumbent − candidate, usd/task) significantly > 0". So a candidate whose dollars were a catalog estimate or an unreported floor could be promoted for being cheaper than a receipted incumbent — comparing a number no provider ever billed against one that was.

Spend.usdKnown states the rule this gate has to obey, in its own words: "A false value must not be treated as $0 when enforcing a dollar-denominated comparison or limit." Promotion on cost savings is that comparison. budget.ts already refuses unknown dollars under a dollar cap; this gate did not.

Measured: with one of 24 paired tasks marked usdKnown: false on the candidate arm, the gate returned promoted: true, reason: 'non-inferior-and-cheaper'.

Change

Non-inferiority mode collects the tasks where either arm reports usdKnown === false and refuses before running the cost bootstrap, with a new reason: 'cost-unknown' and a costUnknownTasks list naming them.

Why long-term right

This is the refusal the type was already asking for. The alternative — comparing anyway and hoping the estimate is close — is precisely the failure mode usdKnown exists to make impossible, and it fails in the expensive direction: a candidate looks cheaper because its cost went unmeasured. Naming the offending tasks makes the refusal actionable: it says which evidence to go and measure, rather than returning a bare no.

superiority mode is untouched, because it never reads dollars.

Cost

3 files. This is a consumer-visible behaviour change: a caller that exhaustively switches on PromotionVerdict.reason must handle 'cost-unknown', and a non-inferiority promotion built on unmeasured dollars now refuses. Version bumped 0.153.1 → 0.154.0 with a CHANGELOG entry and the docs/canonical-api.md pin.

Worth flagging: check:version-bump reported "consumer surface unchanged" both before and after the bump — it compares export names, not their shapes, so it does not see a union gaining a member. The bump here is a judgement call, not a gate result.

Proof

• pnpm run typecheck, pnpm run lint (613 files), pnpm run docs:check, pnpm run check:version-bump — clean.
• tests/kernel/strategy-suite.test.ts — 38 passed, including the existing four non-inferiority cases, which still promote/refuse exactly as before.
• New test verified to FAIL without the refusal: with the guard disabled the same fixture yields promoted: true (expected true to be false).
• src/improvement/improve.test.ts shows 4 failures; that file is first on the clean-origin/main baseline failing-file list (the documented macOS git-worktree class) and is untouched here.

Simplification

Simplification: none — this is a net addition, and the addition is irreducible. The measurement that found it was the usd/usdKnown flag-pair census (187 usdKnown occurrences over 30 files, 56 read sites guarding on it, and 10 files that read .usd without ever mentioning usdKnown); this is the one of those ten where the unguarded read decides a promotion. Collapsing the flag pair into a cost discriminated union would make the omission unrepresentable rather than caught by hand, but that migration touches 143 files and remains out of scope.
Net: +38 / -2 lines, 3 files, 0 copies removed.
Not done here: waterfall.ts:86 is the other consequential unguarded read — span.usd = p.spent?.usd ?? 0, rendered as $0.0000. That one is a display concern whose fix is to label the number unmeasured rather than to refuse, so it is a different change with a different test.
Tests: +1 (a candidate cannot be promoted as cheaper when an arm's dollars were never measured — the exact defect, promotes without this change), -0 deleted.

[tangletools]

✅ Auto-approved drewstone PR — 2784ddbb

This PR was opened by the trusted drewstone account.

This approval is provisional and was applied by the local stand-in because the pr-reviewer webhook host is unreachable (2026-08-21). CI on this head is fully green. The full PR reviewer audit re-runs via the resweep when the service returns and will publish findings if it detects issues.

[tangletools]

✅ Auto-approved drewstone PR — 9ab60645

This PR was opened by the trusted drewstone account.

This approval is provisional and was applied by the local stand-in because the pr-reviewer webhook host is unreachable (2026-08-21). CI on this head is fully green. The full PR reviewer audit re-runs via the resweep when the service returns and will publish findings if it detects issues.