docs(architecture): PERFORMANCE-HARNESS-FRAMEWORK — turn performance covenants into evidence (Joel's 'proof + harness' directive)

[joelteply]

What

Adds `docs/architecture/PERFORMANCE-HARNESS-FRAMEWORK.md` (393 lines). The framework that turns the architecture docs' performance covenants into measurable evidence.

Doc-only PR. Step two of Joel's two-step directive ("ask for proof of performance concerns and then design harnesses"). Step one — airc broadcast asking the room for concrete perf data — is in flight; the framework's "Pending Evidence-Driven Additions" section will absorb the responses.

Why

The architecture docs name performance covenants throughout: RAG composition < 500ms, vector search < 50ms, voice response < 3s, persona tick < 1ms, recall hot-path < 5ms on Air, working-set page-in < 1ms, governor `current_policy()` < 50ns, and roughly 30 more per-Part budgets in `GENOME-FOUNDRY-SENTINEL.md`. They are claims until they are measured. This document specifies the harnesses that turn the claims into evidence.

Three Principles

1. Harnesses produce VDD records, not prose reports. The substrate's Standard VDD Record (CBAR-SUBSTRATE §"Standard VDD Record") is the output of every harness. JSONL for machines, markdown for humans.
2. Per-anchor scoping. Every harness runs against Air (UMA-16) + 5090 (discrete-32+64) at minimum. Intermediate anchors added as evidence accumulates.
3. Baseline-relative, not absolute. Pass/fail is relative to a committed baseline, not to wishful budgets. Budgets bound expectations; baselines are the regression line.

Harness Catalog (11)

Designed against substrate covenants:

Harness	What it proves	Cadence
cold-start-harness	Time to first usable substrate < 30s ceiling	per-PR + nightly
persona-tick-harness	< 1ms tick claim (validates RTOS rule)	per-PR (runtime) / weekly
rag-composition-harness	< 500ms RAG composition + cache hit < 100ms	per-PR (cognition/genome) / weekly
vector-search-harness	< 50ms vector search on 10k engrams	per-PR (genome/recall) / weekly
voice-response-harness	< 3s voice end-to-end (VAD → STT → cog → composer → TTS)	weekly
consolidation-phase-harness	Sleep phase fits 30min on Air; cascade stays ≤ 2	nightly
multi-persona-contention-harness	A1-A3 invariants under N=8 personas; prefix-share KV win	weekly
federation-gossip-harness	< 5s gossip round; conflict resolution correct	weekly
speculation-hit-rate-harness	Hit rate > 0.4 (Air) / 0.6 (5090); zero cascade oscillation	weekly
reprojection-confidence-harness	Correct transform variant + confidence ±0.05; no silent stale	per-PR (reprojection) / weekly
governor-cascade-harness	Hysteresis + restore-speculation-last; oscillation count == 0	per-PR (governor) / weekly
audit-recorder-roundtrip-harness	1200 entries land + sigs verify + mutations rejected (gates #1344)	per-PR

Each catalog entry specifies: scenario, key VDD fields, pass thresholds per anchor, cadence, baseline location.

Regression Detection

Two layers:

• Hard ceilings (substrate covenants) — failure blocks PR regardless of baseline.
• Baseline delta — ≤5% pass, 5-10% warn, 10-25% review-flag, >25% fail, ≥5% faster auto-suggests baseline update.

Baselines are committed JSON; updating is a separate reviewable action — never silent.

CI Integration

cargo continuum-vdd <harness> runs any harness. CI tags: per-pr / weekly / nightly / release. Per-PR Rust-touching changes hit a small focused subset; full weekly + nightly schedules cover the rest.

Output Bundle (Per Run)

Three artifacts under ~/.continuum/vdd/<sha>/<harness>/:

1. VDD record JSONL (for regression detection)
2. Reproducibility manifest TOML (git_sha + policy_version + cascade_step + env + seeds)
3. Human-readable summary markdown (reviewer-friendly)

Pending Evidence-Driven Additions

The catalog above is the design floor. The airc broadcast asked the room for: slowest wall-clock paths in canary, regressions noticed, resource pressure incidents, what can't currently be measured, what's budgeted but unverified, hardware-class gaps. Each concrete data point becomes either (a) a new harness, (b) a sharpened pass-threshold on an existing one, or (c) a new VDD schema extension field.

Connection To Other Docs

• CBAR-SUBSTRATE-ARCHITECTURE.md §"Standard VDD Record" + §"One-Line Instrumentation API" — the recordable substrate this framework sits on
• GENOME-FOUNDRY-SENTINEL.md Performance Budget tables per Part — the covenants harnessed
• PERSONA-COGNITION-CONTRACT.md §"Acceptance Criteria" — the invariants verified
• MODULE-CATALOG.md — the modules these harnesses validate
• ALPHA-GAP-ANALYSIS.md — Lane C VDD telemetry substrate is the foundation this framework lives on

Acceptance Criteria For The Framework Itself

Six checkpoints, including the framework's own performance budget: harness overhead (setup + measurement + compare, excluding scenario) < 50ms.

Open Questions (6)

Where harnesses live in workspace, hardware availability for CI, noisy harnesses (P50 vs P99.9), baseline update authority, cross-harness regression detection, per-persona-shape harnesses.