Lab 02 — Portability Strategy ADR + Conformance Harness

Phase: 09 — Hardware Abstraction (Keystone) | Difficulty: ⭐⭐⭐⭐☆ | Time: 4–6 hours Language: Markdown (ADR) + Python (conformance) | Hardware: none

Concept primer: ../WARMUP.md Ch. 7–9, and Phase 03 WARMUP Ch. 9–10.

Run

python conformance.py          # runs the capability/correctness matrix

0. The mission

Two deliverables a real platform needs:

  1. An Architecture Decision Record (ADR) choosing the portability posture (HAL-over-vendor-libs vs Triton/MLIR vs full compiler) with costs — the document you'd actually present to leadership. STRATEGY-ADR.md is a worked example; you fill in a decision matrix and write your own for a scenario.
  2. A conformance harness (conformance.py) that runs one test matrix against multiple mock backends and prints a support matrix + pass/fail — the mechanism that makes the abstraction trustworthy (WARMUP Ch. 7).

1. What the conformance harness shows

== capability support matrix ==
backend     F32   F16   FP8   matmul  attention
cuda_like   yes   yes   yes   yes     yes
rocm_like   yes   yes   no    yes     yes
cpu_ref     yes   no    no    yes     no
startup     yes   yes   yes   yes     no       <- declares attention, lacks it!

== correctness conformance (one test matrix, all backends) ==
cuda_like  : matmul PASS   attention PASS
rocm_like  : matmul PASS   attention PASS
cpu_ref    : matmul PASS   attention SKIP (not supported)
startup    : matmul PASS   attention FAIL  <- declared but produces wrong result

CONFORMANCE: startup is NON-CONFORMANT (declared attention, failed it)

The lesson (WARMUP Ch. 7): declarations are tested, not trusted. A backend that claims a capability must prove it on the conformance suite, or it's flagged non-conformant — which is what protects applications from having to special-case backends.

2. Reading order

  1. STRATEGY-ADR.md — study the ADR structure (context, options, costs, decision, consequences). Fill its decision matrix.
  2. conformance.py — the capability matrix + the correctness tests; note how a declared-but-broken capability is caught.

3. The ADR exercise (the real deliverable)

Write MY-ADR.md for this scenario:

"We must support NVIDIA (today), AMD MI300X (6 months), and a startup accelerator (12 months) behind one platform, with near-native performance on NVIDIA and AMD."

Use the rubric in STRATEGY-ADR.md: state the options (vendor-library backends behind a HAL / Triton-MLIR kernel layer / full compiler / blend), the costs (eng-months, time-to-market, performance ceiling, maintenance, the AMD no-PTX-equivalent tax from Phase 03), a phased rollout, and the conformance gate. End with a recommendation and its consequences.

4. Extensions

  1. Performance conformance tier: backends must hit X% of a reference throughput, not just pass correctness; add a RECOMMENDED/SUPPORTED/FAIL status (WARMUP Ch. 7).
  2. Rollout dependency plan: model the 12-month multi-vendor rollout as a dependency graph (HAL ABI freeze → AMD backend → conformance → GA).
  3. Capability-gated fast paths: extend the matrix to record which ops have a native fast path per backend (WARMUP Ch. 5).

5. What this lab proves about you

You can produce the strategy artifact, not just the code: a costed, defensible portability decision and the conformance mechanism that enforces it. This is exactly the Head-of-Engineering deliverable the JD asks for — and the backbone of the Phase 12 capstone's platform.