ADR 0001 — HLO diagnostics feasibility (Phase A)

ADR 0001 — HLO diagnostics feasibility (Phase A)#

Status: Draft — Phase A metrics
Date: 2026-05-05
Context: Roadmap — Medium term, optional jaxlint.hlo analysers over StableHLO text.

Decision (pending)#

Phase B (HLO* rules, ≤5 in first drop) is blocked until Phase A metrics below are filled and kill criteria reviewed (oracle). Default CLI surface for IR-backed checks: jaxlint check with --select HLO*; the jaxlint hlo command remains an import/extra smoke hint until extended deliberately.

Fixture × metric matrix#

Maps spike fixtures under tests/fixtures/hlo/ to Phase A metrics. IDs align with planning docs (A1–A5).

ID

Fixture file

Metric recorded

A1

add_constant_kernel.mlir

Minimal StableHLO text parse success; operation_inventory keys present

A2

while_loop_detected.mlir

stablehlo.while path; get_operations / mapping coverage

A3

outfeed_side_effect.mlir

Side-effect / audit_exported violation detection vs golden

A4

multiply_reshape_kernel.mlir

Inventory counts vs get_source_mapping drift

A5

(CI harness / negative path — TBD)

Explicit failure or timeout budget signal for NO-GO

Kill criteria (K1–K4)#

ID

Condition

Mapped fixtures

Threshold

K1

Cannot obtain stable MLIR text from supported export API

A1

(binary)

K2

Semantic drift across JAX patch versions

A1–A4

TBD — owner assigns max allowed diff

K3

Parser/heuristic false-positive rate on fixtures

A2–A4

TBD — max X %

K4

Wall-clock per fixture on CI hardware

A5

TBD — max Y ms

X / Y require maintainer sign-off before Phase B.

Phase B preview (not active)#

  • Rule IDs: HLO + three digits, max 5 rules initially.

  • Non-goals: SymPy-backed math, shard_map UX, embedding HLO diagnostics in LSP (see Language server).

Contents