feat(perf): infra perf-benchmark substrate — journeys, integrity contracts, percentile ratchet (0.90.0)

[drewstone]

Problem

Infra performance benchmarking (provision latency, TTFT, stream reliability) has no substrate primitive. The existing BenchmarkRunner (root) scores QUALITY via judge panels over scenarios; consumers measuring LATENCY / RELIABILITY over flat metric records keep hand-rolling three things: a scenario matrix (journeys × drivers × regions), "is this passing record actually carrying its measurements" checks, and a percentile regression gate against a committed baseline.

Solution

New domain-agnostic src/perf/ module, exported from the root barrel and a new ./perf subpath (tsup entry + package.json exports, matching the existing subpath convention):

• journey.ts — JourneySpec (id, requiredFields, minimums, phaseFields, requiresLLM), ScenarioAxes, PerfScenario, expandMatrix (cartesian expansion with a combo filter), scenarioKey (journeyId|dim=value|…, dims sorted, so keys are stable across axes-object insertion order).
• integrity.ts — checkRecordIntegrity / assertRecordIntegrity: a record claiming pass === true must carry its journey's required fields and clear its numeric minimums (null-required-field / below-minimum violations); failed records are exempt — an errored run legitimately has nulls. resolveJourney returning null skips a record.
• ratchet.ts — summarizeRecords (per-scenario PerfStat p50/p90/n, nearest-rank on sorted values; null/non-numeric metric values excluded from n, zero-sample fields omitted — no fake zeros) and gatePerf (trips when p50 OR p90 exceed tolerancePct (default 10) over baseline; strict improvements reported with negative overBy; n < minSamples (default 3) scenarios surfaced in missingScenarios and never gated; key drift in missingScenarios / newScenarios).

Version 0.90.0 across npm + PyPI (version-locked trio) + CHANGELOG entry.

Testing

• tests/perf.test.ts: 25 cases, each naming the bug it catches (cartesian size, sorted-key stability, filter inversion, pass=true with nulls, failed-record exemption, minimums, phase fields, nearest-rank correctness on even/odd n, tolerance boundary, p90-only regressions, missing/new scenarios, minSamples boundary, null-metric exclusion, zero-baseline division).
• Mutation-verified: 7 hand-applied mutants (unsorted keys, integrity checking failed records, floor-based rank, minSamples off-by-one, null coercion, loosened minimum, AND-ed gate condition) — 7/7 killed.
• Full suite: 222 files / 2255 tests pass. tsc --noEmit clean, biome check src clean, pnpm build (tsup + dts + openapi) green; dist/perf/index.js and root exports verified by import.

[tangletools]

✅ Auto-approved PR — a310acd1

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-10T13:34:11Z}