docs(adr): Apple Silicon UMA acceleration lane roadmap (ADR-0235) (#905)

Define staged PR stack from #904 benchmark foundation through Rust baseline, scalar zero-copy cleanup, optional MLX/Metal experiments, Workbench evidence surfacing, and multimodal/AMR structured-evidence design — with parity gates, non-claims, and merge ordering. Documentation only; no runtime backend changes.
2026-06-24 12:47:14 -07:00 · 2026-06-24 12:47:14 -07:00 · 4183a675a5
commit 4183a675a5
parent 7132997511
1 changed files with 444 additions and 0 deletions
--- a/docs/adr/ADR-0235-apple-silicon-uma-acceleration-lanes.md
+++ b/docs/adr/ADR-0235-apple-silicon-uma-acceleration-lanes.md
@ -0,0 +1,444 @@
+# ADR-0235: Apple Silicon UMA Acceleration Lanes
+
+**Status:** Proposed
+
+**Date:** 2026-06-24
+
+**Scope:** Apple Silicon mechanical sympathy benchmark roadmap, native backend
+baseline, optional MLX/Metal exploratory lanes, Workbench evidence surfaces,
+multimodal/AMR structured-evidence benchmark design
+
+**Depends on:**
+
+- Merged PR #904 (`feat(bench): Apple Silicon UMA mechanical sympathy benchmark`)
+- `docs/outreach/apple-silicon-support-brief.md`
+- `benchmarks/apple_uma_mechanical_sympathy.py`
+- `algebra/backend.py` (Python semantic source of truth; Rust incumbent native path)
+- ADR-0054 vault recall indexing/batching doctrine (exact recall, no ANN)
+- ADR-0222 FrameVerdict closed-world proof surface
+
+## 1. Summary
+
+PR #904 established a **claim-safe, reproducible Apple Silicon UMA mechanical
+sympathy benchmark** for CORE.  That harness is the **foundation**, not the
+final Apple-engineering demo.  This ADR defines a **staged PR stack** that
+moves from measured evidence to optional acceleration experiments **without**
+violating CORE semantic, proof, replay, governance, or serving invariants.
+
+Python remains the **semantic source of truth**.  Rust remains the **incumbent
+native algebra backend**.  MLX and Metal are **exploratory acceleration lanes**
+until separate parity gates promote anything.  CoreML/ANE are **non-claims**
+unless implemented, parity-tested, and measured.
+
+Each lane is **benchmark-only or documentation-only** until explicitly
+authorized for serving.  No lane may mutate serving behavior, response
+governance, reliability gates, pack ratification, epistemic disclosure, or
+teaching/review behavior.
+
+## 2. Current State After #904
+
+### 2.1 What shipped
+
+| Artifact | Role |
+|---|---|
+| `benchmarks/apple_uma_mechanical_sympathy.py` | Deterministic benchmark harness (tracks A–F) |
+| `tests/test_apple_uma_mechanical_sympathy_benchmark.py` | Claim-safety and track contract tests |
+| `core/cli.py` (`core bench --suite apple-uma`) | CLI entry for JSON/report emission |
+| `evals/reports/apple_uma_mechanical_sympathy_latest.{json,md}` | Seed reproducible report |
+| `docs/outreach/apple-silicon-support-brief.md` | Engineering-first outreach brief |
+
+### 2.2 Tracks implemented in #904
+
+| Track ID | Workload | Backend today |
+|---|---|---|
+| `cl41_scalar_ops` | `geometric_product`, `versor_apply`, `cga_inner`, `versor_condition` | Python or Rust via `algebra.backend` |
+| `exact_cga_recall` | Exact top-k CGA recall on `(N, 32)` float32 matrices | Python vectorised scan or Rust `vault_recall` |
+| `diffusion_step` | One diffusion step on ring graph | Rust only; skipped when `core_rs` unavailable |
+| `frame_verdict_ttfv` | Closed-world FrameVerdict time-to-first-verifiable-verdict | Python `evaluate_frame_verdict` (off-serving) |
+| `array_codec_replay` | Deterministic encode/decode persistence replay | Python `core.array_codec` |
+| `claim_safety_audit` | Safe claims, non-claims, copy paths, future work | Static + dynamic from `using_rust()` |
+| `copy_zero_copy_truth_table` | Honest memory-boundary table | Static + dynamic from `using_rust()` |
+
+### 2.3 Known honest limits recorded by #904
+
+- Local seed report may use **Python backend** when `core_rs` is not installed.
+- Scalar Rust helpers **copy** inputs via `extract_f32_slice` list conversion.
+- `array_codec` copies through base64; not a zero-copy persistence path.
+- MLX, Metal, CoreML, and Neural Engine are listed as **future work** in the
+  claim safety audit — not measured claims.
+- No token-generation, ANN, HNSW, or approximate-recall benchmarks.
+
+### 2.4 Why #904 is foundation, not final demo
+
+#904 answers: *what is implemented, what is measured, what is skipped, what
+copy boundaries exist, and what must not be claimed*.  An Apple-engineering-grade
+demo additionally requires:
+
+1. Rust-enabled native baseline reports on arm64 CI or hardware with `core_rs`.
+2. Scalar copy-boundary cleanup where parity-safe.
+3. Optional MLX/Metal experiments with explicit parity oracles.
+4. Workbench read-only evidence surfacing (no fake defaults).
+5. Multimodal/AMR structured-evidence throughput design (not opaque model quality).
+6. Outreach packet that remains engineering-first and claim-safe.
+
+## 3. Lane Map Overview
+
+```mermaid
+flowchart TD
+  A["Lane 0: #904 benchmark foundation (merged)"]
+  B["Lane 1: Rust-enabled baseline report (PR B)"]
+  C["Lane 2: Scalar Rust zero-copy boundary (PR C)"]
+  D["Lane 3: MLX exact CGA recall experiment (PR D)"]
+  E["Lane 4: MLX/Metal field propagation experiment (PR E)"]
+  F["Lane 5: Workbench Apple UMA report card (PR F)"]
+  G["Lane 6: Multimodal/AMR structured evidence design (PR G)"]
+  H["Lane 7: Apple-facing demo packet (ongoing outreach)"]
+
+  A --> B --> C
+  B --> D
+  B --> E
+  A --> F
+  A --> G
+  B --> H
+  C --> H
+  D --> H
+  E --> H
+  F --> H
+  G --> H
+```
+
+**Merge ordering (separate PRs; do not squash stages):**
+
+| Order | Branch | ADR section |
+|---|---|---|
+| A (this ADR) | `feat/apple-uma-acceleration-roadmap` | §3–§12 |
+| B | `feat/apple-uma-rust-baseline-report` | Lane 1 |
+| C | `feat/rust-scalar-cl41-zero-copy-boundary` | Lane 2 |
+| D | `feat/apple-mlx-exact-cga-recall-experiment` | Lane 3 |
+| E | `feat/apple-mlx-field-propagation-experiment` | Lane 4 |
+| F | `feat/workbench-apple-uma-report-card` | Lane 5 |
+| G | `feat/multimodal-amr-structured-evidence-benchmark-design` | Lane 6 |
+
+Lanes D and E may proceed in parallel after B.  Lane C should precede or
+inform D/E copy-boundary reporting.  Lane F may start after A; it only reads
+reports.  Lane G is documentation/fixture design and does not require Rust or
+MLX.
+
+## 4. Lane Specifications
+
+Each lane table uses the same columns:
+
+- **SoT** — semantic source of truth
+- **Backend** — implementation backend under test
+- **Fixtures** — deterministic fixture requirements
+- **Parity oracle** — what proves correctness
+- **Copy boundary** — honest copy/zero-copy characterization
+- **Measurement** — what the benchmark reports
+- **Skipped mode** — fail-closed behavior when unavailable
+- **Serving** — whether serving-authorized (all lanes: **no** until separate ADR)
+- **Benchmark-only** — whether confined to benchmark/eval surfaces
+- **Risks** — primary hazards
+- **Tests** — required validation suite
+
+---
+
+### Lane 0 — Benchmark foundation (#904, merged)
+
+| Field | Value |
+|---|---|
+| **SoT** | Python `algebra/*`, `vault/store.py` recall semantics, `generate/frame_verdict/*`, `core/array_codec` |
+| **Backend** | `algebra.backend` dispatch (Python default; Rust when `CORE_BACKEND=rust` and `core_rs` installed) |
+| **Fixtures** | `synthetic_mv`, `synthetic_matrix`, `synthetic_ring_edges`, `deterministic_closed_frame` — fixed formulas, no unseeded RNG |
+| **Parity oracle** | Deterministic repeat checks per track; `versor_condition` invariant preserved by construction boundaries |
+| **Copy boundary** | `copy_zero_copy_truth_table` and per-track `memory_note` / `memory_behavior` |
+| **Measurement** | p50/p95/min/max/mean timing, ops/sec or rows/sec, skipped reasons, machine metadata |
+| **Skipped mode** | `diffusion_step` skipped with explicit reason when Rust unavailable; large-N recall probe skipped on time budget |
+| **Serving** | **No** — off-serving benchmark only |
+| **Benchmark-only** | **Yes** |
+| **Risks** | Over-claiming from Python-only reports; absolute paths in metadata (fixed in #904 patch) |
+| **Tests** | `tests/test_apple_uma_mechanical_sympathy_benchmark.py`, `core bench --suite apple-uma` |
+
+---
+
+### Lane 1 — Rust-enabled Apple UMA baseline report (PR B)
+
+| Field | Value |
+|---|---|
+| **SoT** | Python `algebra/backend.py` dispatch semantics unchanged |
+| **Backend** | Rust `core_rs` via `CORE_BACKEND=rust`; Python fallback retained |
+| **Fixtures** | Same as Lane 0; no new fixtures required |
+| **Parity oracle** | Existing Rust parity tests for `vault_recall`, `diffusion_step`; benchmark `result_deterministic` flags |
+| **Copy boundary** | Report must show `using_rust(): true`, unskipped `diffusion_step`, Rust zero-copy eligibility on recall |
+| **Measurement** | Regenerated `evals/reports/apple_uma_mechanical_sympathy_latest.{json,md}` on arm64 with `core_rs` |
+| **Skipped mode** | If `core_rs` unavailable locally, **do not fake** — document setup commands; CI arm64 job may publish report |
+| **Serving** | **No** |
+| **Benchmark-only** | **Yes** |
+| **Risks** | Publishing Python report labeled as native; missing `diffusion_step` conflated with "Apple Silicon limit" |
+| **Tests** | `tests/test_apple_uma_mechanical_sympathy_benchmark.py`; helper asserting clean Rust detection |
+
+**Deliverables:** setup documentation (env vars, `cargo`/maturin install path), optional CI note, clearer skipped/native status in report metadata.  **No scalar binding edits.**
+
+---
+
+### Lane 2 — Scalar Rust zero-copy boundary cleanup (PR C)
+
+| Field | Value |
+|---|---|
+| **SoT** | Python implementations in `algebra/` remain canonical semantics |
+| **Backend** | Rust bindings in `core-rs/src/lib.rs` for `geometric_product`, `cga_inner`, `versor_condition`; `versor_apply` only if closure-stable |
+| **Fixtures** | Exact 32-component `float32` contiguous inputs; wrong shape/dtype cases for failure tests |
+| **Parity oracle** | Byte-level or tight float tolerance parity vs Python backend on fixed fixtures; `versor_condition(F) < 1e-6` after `versor_apply` paths |
+| **Copy boundary** | `PyReadonlyArray1` zero-copy on eligible inputs; loud failure on wrong shape/dtype — no silent coercion |
+| **Measurement** | Updated `cl41_scalar_ops` timings and truth-table rows reflecting reduced copy tax |
+| **Skipped mode** | Python fallback unchanged when Rust unavailable or input ineligible |
+| **Serving** | **No** until separate serving authorization ADR |
+| **Benchmark-only** | **Yes** for promotion; backend change affects runtime dispatch only after explicit authorization |
+| **Risks** | Parity drift; silent dtype coercion; breaking `versor_apply` closure; hot-path repair outside `algebra/versor.py` |
+| **Tests** | Rust parity tests, wrong-shape/dtype tests, closure tests, fallback tests, `test_apple_uma_mechanical_sympathy_benchmark.py`, `cargo test` |
+
+**Stop rule:** if zero-copy work is non-trivial or closure-unstable, defer and document gap — do not weaken invariants.
+
+---
+
+### Lane 3 — MLX exact CGA recall experiment (PR D)
+
+| Field | Value |
+|---|---|
+| **SoT** | Python/Rust exact `vault_recall` / `cga_inner` ranking — MLX is **not** semantic backend |
+| **Backend** | Optional `mlx` array ops on Apple Silicon GPU/CPU; benchmark track `mlx_exact_cga_recall` |
+| **Fixtures** | Deterministic `(N, 32)` float32 matrices matching #904 `synthetic_matrix`; same `top_k` and query MV |
+| **Parity oracle** | Identical top-k index ordering vs Python/Rust exact recall on same fixtures |
+| **Copy boundary** | Explicit copy-in (NumPy→MLX) and copy-out (MLX→NumPy) reporting; no "zero-copy everywhere" claim |
+| **Measurement** | MLX import status, device/stream if observable, CPU/GPU mode, shape/dtype/contiguity, p50/p95, rows/sec, parity pass/fail |
+| **Skipped mode** | `skipped: true` with `reason` when `mlx` import fails or device unavailable; tests cover skip path |
+| **Serving** | **No** |
+| **Benchmark-only** | **Yes** |
+| **Risks** | Approximate ops smuggled as exact; hidden normalization; non-deterministic GPU scheduling; semantic backend confusion |
+| **Tests** | `tests/test_apple_uma_mechanical_sympathy_benchmark.py` with monkeypatched unavailable MLX; parity test when MLX present |
+
+**Non-claim:** MLX acceleration does not replace Python semantics or authorize serving recall.
+
+---
+
+### Lane 4 — MLX/Metal field propagation experiment (PR E)
+
+| Field | Value |
+|---|---|
+| **SoT** | Python/Rust `diffusion_step` semantics on deterministic ring (or fixed) graphs |
+| **Backend** | Optional MLX; Metal custom kernels only as isolated low-level follow-up after MLX learning |
+| **Fixtures** | `(N, 32)` fields, `(E, 2)` int32 edges, fixed damping — same generators as #904 |
+| **Parity oracle** | Numeric parity vs Rust `diffusion_step` where available; max abs delta reported |
+| **Copy boundary** | Input copy-in, owned output copy-out documented per run |
+| **Measurement** | nodes, edges, damping, input/output bytes, device/stream, p50/p95, parity error, skipped reason |
+| **Skipped mode** | Skip when MLX unavailable or Rust parity baseline unavailable for oracle |
+| **Serving** | **No** |
+| **Benchmark-only** | **Yes** |
+| **Risks** | Claiming full CORE runtime acceleration; drift from `field/propagate.py` serving path; numeric tolerance masking bugs |
+| **Tests** | Benchmark track tests, skip-path tests, parity test when MLX+Rust available |
+
+**Non-claim:** This is a CORE-*like* contiguous propagation workload experiment, not serving field propagation.
+
+---
+
+### Lane 5 — Workbench Apple UMA report card (PR F)
+
+| Field | Value |
+|---|---|
+| **SoT** | Read-only parse of `evals/reports/apple_uma_mechanical_sympathy_latest.json` |
+| **Backend** | Workbench UI (TypeScript/React); no rerun unless existing safe deterministic CLI hook |
+| **Fixtures** | Checked-in sample report JSON for component tests; live file read at runtime |
+| **Parity oracle** | UI fields match report JSON keys; missing file renders `missing_evidence` |
+| **Copy boundary** | N/A (read-only display) |
+| **Measurement** | Display only — machine/backend summary, tracks, recall highlights, TTFV, codec replay, truth table, audit |
+| **Skipped mode** | Missing report → honest empty state; no fabricated defaults |
+| **Serving** | **No** |
+| **Benchmark-only** | **Yes** (evidence cockpit) |
+| **Risks** | Marketing UI; implied rerun mutating reports; stale report presented as live serving metric |
+| **Tests** | `workbench-ui` component tests; `pnpm build` |
+
+---
+
+### Lane 6 — Multimodal/AMR structured-evidence benchmark design (PR G)
+
+| Field | Value |
+|---|---|
+| **SoT** | Sensorium compiler substrates (ADR-0181 audio, vision fixtures), deterministic evidence records |
+| **Backend** | Design-time only; optional tiny synthetic fixture generator |
+| **Fixtures** | Deterministic image/audio/text/sensor metadata → perceptual evidence record; no model downloads, no network, no LLM |
+| **Parity oracle** | Replay-stable trace hashes; structured graph equality; FrameVerdict/proof surface on closed fixtures |
+| **Copy boundary** | Document UMA-aligned contiguous buffers per modality compiler unit |
+| **Measurement** | Structured evidence transformation throughput and proof latency — **not** recognition quality |
+| **Skipped mode** | N/A at design stage; future benchmark lanes skip unavailable modalities with explicit reasons |
+| **Serving** | **No** |
+| **Benchmark-only** | **Yes** (future benchmark module) |
+| **Risks** | Opaque multimodal model claims; conflating perception quality with geometric proof throughput |
+| **Tests** | `tests/test_architectural_invariants.py`; future lane-specific tests when implemented |
+
+**Pipeline shape (target):**
+
+```text
+image/audio/text/sensor fixture
+  → deterministic perceptual evidence record
+  → AMR / scene graph / relation graph
+  → geometric binding matrix
+  → exact recall / residual search
+  → FrameVerdict / proof surface
+  → Workbench trace
+```
+
+---
+
+### Lane 7 — Apple-facing demo packet (outreach, ongoing)
+
+| Field | Value |
+|---|---|
+| **SoT** | Merged artifacts: benchmark harness, latest report, Workbench card, outreach brief |
+| **Backend** | Documentation and reproducible CLI commands only |
+| **Fixtures** | Public report JSON/MD under `evals/reports/` |
+| **Parity oracle** | Report checksum pinned in brief; reproduce commands documented |
+| **Copy boundary** | Brief cites truth table — no blanket zero-copy claim |
+| **Measurement** | Narrative ties evidence to lanes actually run on demo hardware |
+| **Skipped mode** | Brief states skipped tracks explicitly (e.g. Rust, MLX) |
+| **Serving** | **No** |
+| **Benchmark-only** | **Yes** |
+| **Risks** | Apple endorsement implication; Siri/product integration claim; sponsorship speedup multiplier |
+| **Tests** | Manual review checklist; `git diff --check` on brief updates |
+
+**Demo narrative (authorized framing):**
+
+> CORE is a deterministic Cl(4,1) reasoning and safety architecture.  Its workload
+> is not token generation.  It is exact geometric recall, replay-stable evidence,
+> closed-world proof verdicts, and structured field propagation.  Apple Silicon UMA
+> is relevant because these are contiguous-memory geometric workloads where native
+> copy boundaries matter.  This benchmark shows what is implemented, what is measured,
+> what is skipped, what is future work, and what larger Apple Silicon hardware would
+> unlock.
+
+## 5. Explicit Non-Goals and Non-Claims
+
+The acceleration stack **must not**:
+
+1. Replace Python as semantic source of truth with MLX, Metal, or CoreML.
+2. Wire MLX/Metal paths into serving, vault recall, or `field/propagate.py` hot paths without separate authorization ADR.
+3. Remove Python/Rust fallbacks in this roadmap tranche.
+4. Introduce approximate recall, ANN, HNSW, cosine shortcuts, or hidden normalization.
+5. Benchmark token generation or transformer throughput.
+6. Claim "zero-copy everywhere" or a fixed sponsorship speedup multiplier.
+7. Claim Apple endorsement, partnership, sponsorship, or product integration (Siri, etc.).
+8. Mutate GSM8K serving, reliability gates, teaching/review, pack ratification, or epistemic disclosure.
+9. Add stochastic sampling, unseeded RNG, or network/model dependencies to benchmark lanes.
+10. Present Workbench UI as a live serving dashboard.
+
+## 6. Required Parity Gates
+
+Any lane that introduces a new implementation backend must pass **all** applicable
+gates before its results appear in `safe_claims`:
+
+| Gate | Requirement |
+|---|---|
+| **G1 Semantic lock** | Python reference implementation unchanged; new backend is acceleration only |
+| **G2 Determinism** | Same fixtures → same outputs (indices, hashes, or bounded numeric tolerance documented) |
+| **G3 Fail-closed skip** | Unavailable backend → `skipped: true` + explicit `reason`; no silent fallback posing as accelerated |
+| **G4 Copy honesty** | Truth table and track metadata updated; no zero-copy claim without eligibility checks |
+| **G5 Invariant preservation** | `versor_condition(F) < 1e-6` on applicable paths; no hot-path repair |
+| **G6 Claim audit** | `claim_safety_audit.safe_claims` only lists what actually ran; `unsafe_claims_not_made` unchanged in spirit |
+| **G7 Serving firewall** | No import from benchmark modules into `chat/`, `core/cognition/`, `vault/store.py` serving paths |
+| **G8 Report reproducibility** | `uv run python -m benchmarks.apple_uma_mechanical_sympathy --write-report` reproduces structure |
+
+Numeric tolerance (Lane 4 only): must be documented per fixture with max abs delta;
+tolerance widening requires ADR amendment.
+
+## 7. Required Tests (per lane)
+
+| Lane | Minimum test command |
+|---|---|
+| 0 (#904) | `uv run python -m pytest -q tests/test_apple_uma_mechanical_sympathy_benchmark.py` |
+| 1 (PR B) | Above + Rust detection helper test |
+| 2 (PR C) | Above + `tests/test_*rust*` / algebra parity + `cargo test --manifest-path core-rs/Cargo.toml` |
+| 3 (PR D) | Above + MLX skip-path + optional MLX parity test |
+| 4 (PR E) | Above + MLX/Metal skip-path + optional numeric parity test |
+| 5 (PR F) | `cd workbench-ui && pnpm test -- <report card tests> && pnpm build` |
+| 6 (PR G) | `uv run python -m pytest -q tests/test_architectural_invariants.py` |
+| All doc PRs | `git diff --check` |
+
+**Architectural invariants** (`tests/test_architectural_invariants.py`) must remain green
+across every PR — especially INV-02 (no hot-path normalization) and recall exactness.
+
+## 8. MLX / Metal / CoreML Stance
+
+| Technology | Role | Authorization |
+|---|---|---|
+| **MLX** | Exploratory Apple Silicon GPU/CPU array acceleration for benchmark tracks | Benchmark-only until G1–G8 pass and serving ADR exists |
+| **Metal** | Lower-level kernel follow-up after MLX experiments inform parity and copy boundaries | Isolated experiment modules only |
+| **CoreML / ANE** | Future work | **Non-claim** until implemented, parity-tested, measured, and documented |
+
+MLX is **not** a replacement for the semantic source of truth.  Metal custom kernels
+are a **lower-level follow-up** only after MLX/parity learning.  Multimodal tracks
+benchmark **structured evidence throughput**, not opaque model output quality.
+
+## 9. Apple Silicon UMA Relevance (engineering, not marketing)
+
+CORE workloads relevant to UMA mechanical sympathy:
+
+- Contiguous `(N, 32)` float32 geometric matrices for exact recall.
+- Cl(4,1) scalar ops with predictable memory access patterns.
+- Field propagation on dense node buffers with explicit edge lists.
+- Deterministic persistence replay across unified memory without hidden copies.
+
+UMA advantage is **conditional** on measured copy boundaries — reported honestly in
+`copy_zero_copy_truth_table`, not assumed from hardware marketing materials.
+
+## 10. Validation For This ADR (PR A)
+
+This PR touches **documentation only**.  Required validation:
+
+```bash
+git diff --check
+uv run python -m pytest -q tests/test_architectural_invariants.py
+```
+
+## 11. Merge Blockers
+
+**PR A (this ADR)** must not merge if:
+
+- it edits runtime backend code, Rust bindings, MLX imports, or Workbench UI;
+- it claims MLX/Metal/CoreML as implemented acceleration;
+- it authorizes serving integration for any lane; or
+- validation commands in §10 fail.
+
+**Downstream implementation PRs** must not merge if:
+
+- parity gates in §6 are skipped;
+- benchmark modules are imported from serving hot paths;
+- `unsafe_claims_not_made` regressions appear in reports;
+- fallbacks are removed; or
+- lane-specific tests in §7 fail.
+
+## 12. Recommended Next PR
+
+**PR B — `feat/apple-uma-rust-baseline-report`**
+
+Make Rust-enabled report generation straightforward on arm64 with `core_rs`
+installed; improve skipped/native status visibility; document setup.  Do not
+edit scalar Rust bindings.  Regenerate report only when Rust is actually available.
+
+---
+
+## Appendix A — File touch matrix
+
+| Lane | Expected files (indicative) |
+|---|---|
+| 0 | `benchmarks/apple_uma_mechanical_sympathy.py`, `core/cli.py`, `evals/reports/*`, `docs/outreach/*` |
+| 1 | `benchmarks/*`, `docs/*` setup notes, optional CI workflow |
+| 2 | `core-rs/src/lib.rs`, `algebra/backend.py`, parity tests |
+| 3 | `benchmarks/apple_uma_mechanical_sympathy.py`, optional `benchmarks/mlx_*` helper |
+| 4 | same as 3, isolated propagation experiment module |
+| 5 | `workbench-ui/src/**` report card components |
+| 6 | `docs/adr/*` or `docs/architecture/*`, optional `evals/fixtures/*` synthetic multimodal metadata |
+
+## Appendix B — Report schema stability
+
+Downstream lanes should **extend** `tracks` with new keys (e.g. `mlx_exact_cga_recall`)
+rather than mutate existing track semantics.  `benchmark_version` bumps follow semver
+when track contracts change.  `claim_safety_audit` and `copy_zero_copy_truth_table` must
+be updated in the same PR as any new copy boundary or safe claim.