Module Autotune

Parameters of one matmul-sketch seed candidate; see Sketch_families.sketch_params for field documentation. Exposed for tests (the seeding pre-filter of gh-ocannl-479 and the mixed grid-outermost shape of gh-ocannl-473 are asserted on directly).

A recognized matmul accumulation site; see the implementation's field docs. Exposed for tests (gh-ocannl-683 asserts on the contraction nest directly).

Recognize a matmul accumulation nest: a perfectly nested all-serial accumulation whose contraction loops are the innermost suffix absent from the accumulator's index map, every other loop owning a distinct accumulator axis, with the 2-D tile roles assigned per classify_matmul's operand rules and everything else batch. Reads off the extracted access relations like detect_conv, with the same legality_crosscheck soak. Exposed for tests.

The matmul site every seeding and schedule-construction entry point uses (gh-ocannl-1183): the site, the enabling-interchange prefix every schedule built from it carries, and the code it was detected on. The prefix is empty, and the code the argument, for a site detect_matmul finds; otherwise it is an adjacent-Swap chain, each Op_legal, sinking the contraction loops of the first accumulation-of-a-product statement below its write loops (the backward contractions backprop lowers with the contraction loops outermost or interleaved), and the code is the interchanged one. None when the plain matcher fails and detect_conv succeeds: the conv family keeps its segments. Exposed for tests.

A recognized convolution accumulation site (gh-ocannl-493); see the implementation's field docs. Exposed for tests.

Recognize a convolution accumulation nest: the output written at plain distinct iterators, one operand carrying affine components that mix an output symbol with a kernel-window symbol (the projections carry the strides, dilations, and padding offsets), the other operand reading the kernel window, exactly one out-channel and one reduction-channel symbol, with the out-channel at the output's last axis and a conv axis at its second-to-last (the implicit-GEMM row). Reads off the extracted access relations (Ir.Low_level.affine_accesses — the gh-494 artifact the op-legality oracle also consumes); under config legality_crosscheck the retained procedural matcher runs alongside and any divergence raises. Exposed for tests.

Boundary (gh-ocannl-912): rank-generic — any number of batch axes and of spatial axes (1-D, 2-D, 3-D) beyond the row become outer loops — but it refuses every SINGLETON axis, because lowering drops extent-1 loops and indexes the axis at a literal Fixed_idx: a batch of one or an output spatial extent of one (the output is no longer written at plain iterators), a single input channel or a k-by-1 window (the kernel is no longer read at plain iterators; with one input channel no reduction-channel loop remains for Tensorize (row, oc, ic)). A channel row of several axes is refused too (exactly one reduction channel). An all-singleton window (1x1, any stride) is a plain GEMM: detect_matmul owns it. Refused sites get no matmul or conv sketch seeds (the preset and split-reduce candidates are unaffected); test/operations/conv_detection_boundary is the witness.

The launch geometry a GPU matmul seed will have, predicted from the parameters alone (gh-ocannl-709) — the grid's row-block .y extent and folded batch .z product, and the workgroup's register-split extents — so seeding can consult the same Ir.Schedule.launch_geometry_excess the pre-driver gate does and never propose a candidate the device would refuse. Ir.Schedule.unknown_launch_geometry for parameters that name no block geometry (every CPU pipeline: the C backends render annotated loops serially). Exposed for tests, which cross-check the prediction against an applied schedule's Ir.Low_level.launch_dims — a prediction that drifted from what the builders emit would withhold legal candidates.

The launch geometry a GPU convolution seed will have (gh-ocannl-739): the site's outer output loops followed by the blocked flavor's row-block loop in grid nest order, and the tensorization lane as the sole workgroup loop. This lets convolution seeding consult Ir.Schedule.launch_geometry_excess before compiling a candidate. The prediction is a lower bound on the applied schedule's geometry; tests derive a real conv site through Ir.Schedule.fission_scheduled and cross-check every GPU seed against Ir.Low_level.launch_dims. Ir.Schedule.unknown_launch_geometry for CPU parameters.

The (operand, operand, accumulator) format triples a site with these storage precisions resolves to, in preference order — the key the typed seeds look up in mma_format_tiles and mma_staged_layouts. Single-precision operands read as tf32 first only under Ir.Numerics.t.tf32_matmuls. Exposed for tests, which derive the storage precisions of an advertised triple from it rather than restating the format table.

The advertised intrinsic tile a site with these storage precisions seeds in this emission scope under the current policy, None where the descriptor withholds it (no advertised format triple, or a wide-accumulator lifetime the scope lists exclude). Exposed for tests: it is the descriptor's verdict as seeding reads it, which cuda_mma_cutoffs compares against the arm resolver's floors at every cutoff (gh-ocannl-1214).

The matmul-sketch seeds proposed for the given lowering: parameterized instantiations of the composed pipelines with dividing tile sizes, pre-filtered against rules that statically imply a declined rendering (gh-ocannl-479) — on GPU backends: the (operand, operand, accumulator) format tile advertised by limits.mma.mma_format_tiles, including policy-enabled TF32 and excluding combinations the backend supports at one accumulator width but not the other (gh-ocannl-545: CUDA's bf16 has no wmma accumulator of its own); on the C backends: operand-precision uniformity (f32/f64), the fused accumulation form, micro-kernel column extent at least one vector of lanes (limits.simd_vector_bytes), and transposed-B storage for shapes that read B in place. Builder preconditions the schedule builders settle identically for every tile completion — the zero-expansion row-axis rule, and the GPU sketches' companion-coverage rule per fusion flavor — also pre-filter here, as the family tree's construction-time refutations (gh-ocannl-577): a seed list never proposes a candidate that statically must fail its build. For the matmul family this list is Ir.Schedule_space.leaves of matmul_sketch_tree, epilogue twins included. Exposed for tests.

See Sketch_families.coalesce_prefix (gh-ocannl-1165). Exposed for tests.

The coalesced tuner branch (gh-ocannl-1165), which tune seeds beside sketch_seed_params's candidates, whole-routine and per fission segment: see Sketch_families.coalesced_seed_params. Its winners persist as ordinary saved schedules whose leading Ir.Schedule.Coalesce ops name their loops structurally.

Why the backend and the configuration withhold the tensorized family from a matmul site with these operand and destination storage precisions, before any geometry or site structure is consulted — None when they do not (gh-ocannl-1115). matmul_sketch_tree refutes its tensorized branch with exactly this witness. On GPU: routine logging, an mma lane wider than the workgroup, no advertised format tile; on CPU, the register tiling's shape-independent rules: a usable vector file, two lanes at the compute precision, uniform vector-capable compute precisions, routine logging. Exposed so a test claims a tensorized seed's PRESENCE exactly where the seeder's own capability judgment admits it, never gating on the seed list under test.

The matmul sketch family as a refinement tree (gh-ocannl-514 phase 1): decision levels — epilogue fusion, pipeline, packing shape, geometry, twins — whose lazily-refined choices depend on earlier commitments, and whose Ir.Schedule_space.leaves are exactly the family's sketch_seed_params, in enumeration order. None when no matmul site is detected. The root level is the Fuse_epilogue flavor (gh-ocannl-613): unfused first, then fused — refuted with the fusion recognizer's reason (Schedule.fuse_epilogue_witness) when the site's output feeds no fusable tail — so the twins enumerate after every unfused leaf and each flavor's construction-time verdicts are its own (gh-ocannl-577: companion coverage can pass fused where it fails unfused). Statically-decidable builder preconditions refute at the pipeline level — above the geometry menus and the tile lattice, so a family whose every completion must fail its candidate build never expands (gh-ocannl-577). The conv family factors the same way as a follow-up. Exposed for tests and as the phase-4 search driver's entry into the family space.

The exclusion witness marking the tile-size lattice branches beyond the curated geometry menus (gh-ocannl-514 phase 5): binary interval refinements over the staged tile sizes — every intrinsic-tile multiple of the row block crossed with every staged depth block — whose boxes carry corner-judged verdicts (a workgroup-memory floor at the most favorable corner refutes the whole box pre-expansion). Ir.Schedule_space.leaves never enumerates an excluded branch, so the tuner's seed lists are unchanged by the lattice's existence.

Lift every geometry-lattice exclusion — the branches whose decision is Family_decision.Geometry Lattice, identified by that datum rather than by the exclusion's prose witness — preserving the laziness of everything else; lifted branches remain subject to legality (the box refutations), and other exclusions stay excluded. model_default's family search applies this under config model_default_geometry_lattice. Exposed for tests.

The certain-traffic increment (bytes) of a family-tree decision path (gh-ocannl-514 phase 5): traffic every completion below the path moves beyond the schedule-invariant Ir.Cost_model.completion_floor, read off the path's committed staging decisions as data (Family_decision, gh-ocannl-591; the decision also says which pipeline minted it, so the caller's backend kind is not needed alongside the path) — a committed staged geometry contributes its operand tiles' distinct-cell footprints exactly as Ir.Cost_model.analyze charges them on every leaf (in-kernel GPU stages read and write; CPU packed panels only under in-kernel serial packing — a hoisted panel replaces the original operand's reads rather than adding traffic), and a lattice box contributes its most favorable (smallest-tiles) corner priced at the same per-format intrinsic tile the lattice is built from, so the increment is monotone in refinement. 0 when no matmul site is detected or nothing is certain. Composed with the floor's legs, this is what makes the family bound non-uniform across the tree — the schedule-invariant floor differentiates only placements (phase 3), the increments differentiate the sketch-geometry subtrees. Detection runs once at partial application; the returned closure is cheap per path. Exposed for tests.

The composed pipeline a seed parameterizes, built against the given lowering (the site is re-detected). Raises Invalid_argument when no site is detected or the parameters do not fit the segment. accum_prec is the rendering backend's accumulator resolution ((Context.codegen_capabilities ctx).accum_prec): the scalar pipelines' Privatize mints its tile at it (Ir.Schedule.privatize, gh-ocannl-1116). Exposed for tests (the pad-composition seeding of gh-ocannl-485 is executed directly).

The privatized preset extension used by the fissioned candidates: appends a Schedule.privatize ~accum_prec ~target ~over for every materialized read-modify-write accumulator detected in the schedule's application to the segment — over being the outermost enclosing Serial loop whose symbol the access vector does not mention and whose subtree contains no hardware-typed loop. Each proposal is validated by try-applying the grown schedule against a hermetic copy of the segment (proposals violating the op's preconditions are dropped), so the result always applies cleanly where the input schedule does. Exposed for tests.

A reduction-dominated accumulation site eligible for Ir.Schedule.Split_reduce seeding (gh-ocannl-484 task 3); see the implementation's field docs. Exposed for tests.

The split-reduce seeding sites of the given lowering: rmw accumulations (and gh-466 Set_dynamic scatters) whose target has at most a few thousand cells while a serial reduction loop of substantial extent feeds it — little output parallelism, lots of splittable reduction work. Per site the largest-extent enclosing serial loop that passes the hermetic Ir.Schedule.op_legality probe of the corresponding Split_reduce is chosen (the op's own recognizer decides the pinning discipline), so every returned site is seedable as proposed.

Every detected site is returned, ranked by descending estimated segment cost (sr_cost, the accumulation's trip count) — gh-ocannl-541: the earlier sr_red / sr_out integer-division ratio zeroed every large-output site, and the in-detection cap then silently excluded (and, once gh-537 made more sites reachable, evicted) exactly the sites carrying the most serial work. The candidate-volume cap now lives in tune (max_split_reduce_sites / config autotune_split_reduce_max_sites), which records evicted sites in the decline census.

A candidate rejected only because the accumulation cell's loops sit inside the reduction loop — how OCANNL lowers conv bias/weight gradients, where nothing else in the schedule space reaches the dominant segment — is re-probed after the enabling loop interchange (Ir.Schedule.split_reduce_hoist names the loops, each Swap confirmed Op_legal on the code it acts on); the chain is recorded in sr_swaps and replayed by the candidate's prelude. static_indices only reaches the interchange probe's Sched.apply. Exposed for tests.

gh-ocannl-685: spend a cap round-robin across named categories instead of as a prefix over their concatenation, returning the survivors (in the original category order, so an under-cap input comes back unchanged) and the per-category drop counts. One proposal per category per round, a category that runs out stops taking turns: every non-empty category is represented before any gets a second, and unused share spills to the others without imposing a ranking. Used for menu's per-unit action cap, whose list is a category-ordered concatenation and NOT ranked -- a plain prefix there starved every category after the first outright. Exposed for tests.

The beam-round action menu over one unit's transformed code — registry must resolve its loop binders, including symbols minted by the schedule applied so far (the search harness builds it with Ir.Schedule_cache.to_saved over that schedule): dividing serial Splits, Swaps of perfect serial pairs, Unrolls, Retype-Vectorized on innermost loops, and Tensorize role permutations, each proposal vetted by Ir.Schedule.op_legality (proven-illegal ones are pruned before they cost a candidate compile; Op_unknown proceeds to compile-and-time). The loop enumeration descends into accumulation-minted Local_scope bodies and treats binder-sharing mint copies as one decision (gh-ocannl-666). It descends virtualization's inlined computations too, but a loop reached through one draws the Retype-Vectorized proposal ALONE (Ir.Low_level.scope_mint, gh-ocannl-687): that is the one category with a renderer built for the shape (an inlined reduction's Set_local accumulation is what C_syntax.try_vectorize_reduce recognizes, and the enclosing loop -- whose body holds a Local_scope -- cannot be explicitly vectorized at all), while Splits, Swaps and Unrolls there are up to eight descriptors per loop that nothing proposed before gh-666 and that displace proposals for the main nest.

The per-unit action cap is shared across the categories by share_cap rather than spent in category order (gh-ocannl-685). admits filters proposals BEFORE that cap, so the budget is shared over moves the caller can use rather than over moves it is about to discard -- the beam passes its GPU dispatchability rule here, since an incumbent binding no hardware dimension can only be expanded through a move that binds one. It may record its refusals. Exposed for tests.

Aggregate of candidate declines sharing one stable key. Details retain at most the first three distinct diagnostics and are never part of the key.

Why a search was abandoned by its caller's ?abandon rule (gh-ocannl-1110).

What the call did about searching (gh-ocannl-677). The states are mutually exclusive and each carries exactly its own data, so a consumer matches instead of re-deriving: "it searched" is Searched | Search_died _ and nothing else — in particular it is not not cache_hit, the reading that costs a benchmark harness every tuned cell under the reproducible profile, where a call reports having neither searched nor replayed. Spelled as four independent booleans until gh-ocannl-677, where two consumers mis-derived the state in one PR.

Note the arithmetic: five constructors for what reads as four outcomes, because "nothing searched" is two — a deliberate no-search that ships the untuned default and returns, and a failure before the search that reports and then raises. The old encoding could not tell them apart either, it just did not say so.

The shared admission gate for the consumers that RANK: candidate selection, the calibration rows, the roofline consistency check, cache attribution. Returns a positive finite ms only for an uncontended result; a refused or degenerate result is None. Deliberately NOT the gate for queued_batch_depth, which chooses a scale rather than consuming a measurement (gh-ocannl-888).

The report of a tune call that never searched (config autotune_search=false, gh-ocannl-559, and no cache entry to replay): outcome = Search_disabled, every counter zero, every time infinity, best_label empty, best_tensorization = None and source_digest = "". The caller gets the untuned default compile. Also the base the pre-search failure reports are built on, with outcome replaced and whatever census the call had reached filled in.

timing is the objective the call resolved, which is all that distinguishes one of these from another: it names what the (absent) times would have been measured under, and keeps report.timing a plain field rather than an option every consumer of a real report would have to unwrap. A caller synthesizing a report — a test building a search outcome to feed family_profit_of_reports, say — passes whichever objective its scenario is about.

Whether the progress lines are on in this domain: the ?progress of the innermost enclosing tune or Train.tune_placements call that passed one, else config autotune_progress.

Whether the autotune: diagnostics (and the untuned-default control they gate) are on in this domain: the ?log of the innermost enclosing tune or Train.tune_placements call that passed one, else config autotune_log.

with_streams ?log ?progress f runs f with log_enabled and progress_enabled overridden by whichever of the two is given, in the calling domain only, restoring the enclosing settings on return or exception. It is how tune and Train.tune_placements scope their arguments; an omitted argument leaves the enclosing setting in place.

Writes one progress line (prefix and wall_s added) when progress_enabled; the format supplies event=... and the rest.

A time in milliseconds as progress lines print it: %.4f, or none when not finite.

Starts a clock; the returned function reads the seconds since.

The stable one-word name of an outcome state — "searched", "search-died", "cache-replay", "search-disabled", "pre-search-failure", "abandoned" — for logs, JSON records and test goldens.

The fatal failure that ended the call, from whichever of the two failing states carried it; None otherwise. A projection over outcome, not a re-derivation of it: "did this call fail" spans two states, and every caller that ranks or attributes arms asks exactly that — an arm carrying one is never the shipped arm, whatever its pre-failure best_ms says (gh-ocannl-550). The failure's phase is the one it carries — where the call actually died (at link, at launch, at sync), not where the report was assembled.

tune reports exactly once per call, on every path that does any work. Argument validation is the exception, and deliberately so: an incompatible timing_ctx is a precondition violation detected before anything happens, not an outcome of a search, and reporting it would attribute a phase to a call that never reached one.

The analytic cost model's ranking score of a candidate schedule (gh-ocannl-491, the selection half): Ir.Schedule.apply on a hermetic copy, Ir.Cost_model.analyze, then the roofline lower-bound seconds under the envelope constants — limits' advisory peak_flops / peak_memory_bandwidth, each overridable by config model_peak_flops / model_peak_memory_bandwidth (calibrated per-machine values beat the class constants). None — no model coverage — when the schedule fails to apply, the code is opaque to the extraction (its counts may under-estimate, so ranking on them could prune the true winner), or no envelope constant is present. A ranking score, not a runtime prediction. Exposed for tests.

The envelope constants model_score scores against — (peak_flops, peak_memory_bandwidth), FLOP/s and bytes/s — each with where it came from: `Config for a model_peak_flops / model_peak_memory_bandwidth override, `Backend for limits' advisory class constant. None for a leg neither provides (the C backends carry no class constant). Exposed so that a report scoring a measured kernel against the envelope reads the very constants the model ranks with, and can say whose they are (gh-ocannl-1006).

The order-preserving pre-filter over model-scored candidates: keeps every unscored (None) candidate — the no-coverage exemption: never dropped, only measured — plus the best ceil (keep_fraction * n) of the n scored ones (at least one; ties at the cutoff are all kept, so the outcome is independent of enumeration order). The identity when keep_fraction >= 1. Exposed for tests.

The enablement prior of the placement levels (gh-ocannl-514, the gh-ocannl-558 lesson): given the default-policy lowering and its all-materialized specialization, classify the flip candidates by whether their placement decides a sketch family's expressibility — computable from the seeders' own site classification, before any compile. Returns (enablement, disablement):

• enablement: operand/destination nodes of an mma-eligible matmul site (the backend advertises a format tile and the wide-f16 policy's required scope for the site's unstaged form, whole-routine or per-fission-segment — the granularity the seeders detect at) that exists in the all-materialized lowering but has no eligible counterpart under default placements. Materializing such a node is what makes the tensorized family expressible — the flip changes the feasible set, not just the objective, which the per-node recompute-cost bound has no term for (on gh-558's mlp_wide/hip/bf16, cost ranking buried the family-unlocking cast twins below four no-op `Inline flips and a budget-5 chain found nothing).
• disablement: operand/destination nodes of sites already eligible under default placements. An `Inline flip of a node in either set can only move away from an eligible site — rank_flip_candidates demotes those.

Empty on backends without an mma capability. A classified fission failure degrades to whole-routine detection; the classification is a ranking prior, never a legality fact.

Parse config tune_flip_profit_margin (gh-ocannl-579): a ratio of at least 1.0. Anything else — unparseable, non-finite, or below 1.0, which would demote a family that WON — raises Utils.User_error rather than falling back to the default, since a run that asked for a profitability policy it also made impossible should not quietly get a different one. Exposed for tests.

Raised by tune when its ?abandon rule decides, including from cached evidence. Its report (Abandoned or Abandonment_replay) has already been delivered, and every candidate this call compiled released.

best_after steps k: the best after the first k admitted timings of the search whose report.best_steps is steps — its final best when it timed fewer than k, infinity when it timed nothing.

Some exactly when best_after steps k exceeds trailing_ratio times the incumbent's best_after at the same k — strictly, so a flip trailing by exactly the ratio keeps searching — and the incumbent timed something by then. tune decides once, as soon as it has k = beam_width admitted timings (the depth at which its first beam is full), before its next attempt. Exposed for tests.

The trailing ratio the flip chain abandons at: config tune_flip_profit_margin, squared (1.5625 at the default 1.25). The margin is the gap the chain already calls a measured loss for a family; squared, a flip must trail by that much once more than the rest of its search could be granted to catch up. That separates gh-719's hopeless flips (2.0x, 1.7x at equal depth) from arm B's 1.07x with room on both sides. margin overrides the configured one; a malformed configured value raises Utils.User_error as flip_profit_margin_of_string does.

What completed searches measured about the tensorized family's profitability on this device (gh-ocannl-579): mma_best_ms against best_ms, compared to config tune_flip_profit_margin. A report with any timings_contended contributes Unmeasured: its admitted minima cover an incomplete candidate set and cannot safely price the family. Over several reports the most favourable evidence wins — the expressibility prior is deleted only by evidence that contradicts it, never by the absence of a confirmation. A failing arm's report counts: its timings are measurements of the family even though its best_ms is not shippable. Exposed for tests and for Train.tune_placements, which derives it from the placement A/B's two arm reports.

A log-line phrase naming the evidence and its ratio.

The ordering `Profitable resolves to under the given evidence: `Enablement when the family is unmeasured or competitive, `Cost when it is measured to lose here. Both of the prior's classes go at once, because the promotion of family-unlocking flips and the demotion of family-breaking ones are the same bet on the same family. Exposed for tests.

Deduplicate (by Tn.uid, keep-first), drop refused alternatives (Ir.Low_level.fa_refused, gh-ocannl-1093: each replays to the materialized placement) and the nodes left with none, and rank the decision surface. `Cost is the legacy recompute-cost-descending order (the gh-555 chain's, kept as the evaluation baseline); `Enablement sorts family-unlocking `Materialize flips (enablement members) first and family-breaking `Inline flips (members of either set) last, cost-descending within each class. The unit ranked is the candidate (gh-ocannl-1017): each node's alternatives are sorted by that order and the node ranks where its best-ranked alternative does, so a top-N prefix is N nodes. `Profitable (gh-ocannl-579) is `Enablement weighed against profit per effective_flip_ordering — the prior models expressibility, and on a device where the family it unlocks is measured hopeless, promotion is pure opportunity cost that displaces the winning flip out of a small budget. profit defaults to Unmeasured (so a caller with no measurements, such as model_default, gets the prior). Config tune_flip_ordering selects the default ordering. Exposed for tests.

Whether placement_surface withholds ps_floor_ms over these candidates: when one of them is not materialized by default (fc_default) and offers no `Materialize alternative — a node an earlier routine of the lineage left virtual and this routine footprint-scoped, which nothing here writes (gh-ocannl-616). The all-materialized specialization the floor is read from keeps that node's scratch, so the floor would not lower-bound its inline completion. Decided by the default reading (gh-ocannl-1017), not by which alternatives exist: a cap-materialized node with no smaller footprint offers the same lone `Inline and leaves the floor sound. Exposed for tests.

The placement decision surface prepared for search (gh-ocannl-514): the per-node inline/materialize levels of the joint placement x sketch x fission space.

Read and rank the decision surface from ctx (analyze-only — two hermetic lowerings via Context.lowered_for_decisions, sharing the gh-560 analysis cache; no backend codegen, no effect on ctx). name names the computation for those lowerings exactly as Context.compile's does, and is what makes this work for a comp carrying no Ir.Assignments.t.Block_comment (gh-ocannl-669). ordering defaults from config tune_flip_ordering (profitable). evidence is the completed searches `Profitable weighs the enablement prior against (family_profit_of_reports, reported as ps_profit): Train.tune_placements' flip refinement passes the placement A/B arms' reports, while model_default's placement search (config model_default_placements) passes none — it measures nothing, so the prior stands there. Under an unconditional ordering the evidence is not derived at all, so such a run never reads tune_flip_profit_margin.

Config model_default_schedule: recipe-level untuned compiles (Train.to_routine, Train.run_once, the benchmark runners) route through model_default instead of Context.compile.

Context.compile_outcome with advisory provenance and the given lowered_transform, falling back to a plain Context.compile — the ordinary default pipeline — for a classified compiler rejection, including validation in backend codegen. Fatal failures propagate without retrying. on_fallback is called with the public rendering of the cause when fallback fires. fallback_if (default: always) is consulted first, for transforms that may themselves have degraded to the default pipeline — false re-raises the original exception, backtrace included, instead of duplicating a compile that has nothing to fall back to. For advisory transforms only: a failure of the default pipeline itself propagates. name names the routine, exactly as Context.compile's does, and reaches the fallback compile too. See model_default (gh-ocannl-519).

A drop-in for Context.compile that raises the untuned floor (gh-ocannl-491 task 3): inside the compile's own transform seam, the untuned default pipeline and the sketch families (whole-routine, and per-fission-segment substitutions when the default fissions) are scored with the roofline model, and the model-argmin schedule is applied — zero measurement, one backend compile. Advisory by construction: a candidate without model coverage is never picked over the default, ties go to the default, and missing envelope constants, a disabled default annotator (Ir.Schedule.automatic_schedule_active), or any classified scoring, application, backend validation, or compilation failure fall back to the ordinary default pipeline — the reported model_choice then says "default". Fatal failures propagate without retrying. Once the compile is on that pipeline there is nothing left to fall back to, so its failures propagate as they would from Context.compile, without a duplicate attempt. Unlike tune, nothing is executed and no cache is involved — results depend only on the computation, backend, and envelope constants.

Being a drop-in for Context.compile includes its name (gh-ocannl-669): it names the routine and every artifact of this compile — the model pick's, the fallback's, and the hermetic lowerings of the placement search alike — and, as there, a comp carrying no Ir.Assignments.t.Block_comment requires it.

Binds representative values for timing runs: ranged static indices at range / 2, and gh-490 symbolic extents at their upper bound range (the schedule-cache identity is extent-value-independent, so the single tuned entry is measured at the maximum). Unranged bindings are left at their current values. Exposed for tests and custom timing harnesses.

The wall time, in milliseconds, one Queued batch aims for (10 ms). Exposed so a test can state a batch-wall bound against the policy's own target rather than a copy of it.

The wall budget, in milliseconds, on one CUDA/HIP queued calibration's batch probes (gh-ocannl-1098): eight target-sized twelve-minimum probes. Once the probes' summed wall reaches it, no further validation, confirmation or retry starts and the calibration ends unresolved, for the wall-bounded fallback to decide from what was measured; only the one rescue probe may follow. Exposed so a test states the budget against the policy's own value.

The minima one queued calibration batch probe takes when its wall stays within twice the target (12); an over-target probe may stop at three. Exposed so a dispatch bound is stated against the policy's own count.

The most batch probes one CUDA/HIP queued calibration dispatches (9): the provisional probe, four validations, a confirmation, its stall retry, a sampled shallower crossing, and the rescue. Enforced alongside queue_calibration_wall_ms: once all but the last have started, only the rescue may follow. Exposed so time_routine's dispatch maximum is stated against it.

The maximum number of queued depth validations (4), including measured doublings toward an unmeasured cap. Exposed so synthetic timing fixtures hold convergence against its probe budget.

How far past the deepest batch it probed a CUDA/HIP queued calibration may settle, as a multiple of that depth (2, one doubling; gh-ocannl-1100). An affine projection or a linear scale can land far past every measured batch, where a queue cost may jump unseen; the settled depth is capped here after calibration ends. A projection to an unmeasured cap in depth validation uses its remaining probes to walk toward it by this factor (gh-ocannl-1144). Exposed so a test states the bound against the policy's own factor.

Queue-memory bound selected by canonical backend name: 2048 for CUDA/HIP, and the historical 200 for cc/Metal. Exposed with the neighboring pure calibration seams so the backend scoping of gh-ocannl-892 is pinned without running a full search.

How many launches Queued puts in one batch, given an estimate of what one launch plus one synchronization costs. Aims at ~10 ms of wall time per batch, capped at 2048 launches and floored at 1 — so a routine at or above the target is batched at depth 1 and measured exactly as Isolated measures it, and a microsecond routine cannot mint an unbounded batch. A non-positive or NaN estimate is a clock that resolved nothing rather than a zero-cost kernel and batches at the cap; an infinite one floors at 1, the far end of the scale the policy is for. Total, over every float and every verdict: a positive subnormal estimate saturates rather than raising. Exposed because those two boundaries are what a regression would cross silently: a depth stuck at 1 turns a queued search back into an isolated one.

contended is deliberately unread (gh-ocannl-888). The 2x-majority rule judges a ~10 ms batch, while this estimate is one dispatch plus one synchronization, whose dispersion on a GPU is the round trip's own tail; refusing on it starved every search on both GPU backends. A depth is not a measurement — an overestimate only shortens the batch, an underestimate is capped — and a deeper batch is the remedy for that dispersion, so the refusal belongs downstream in the timed loop, where the window judged IS a batch.

Refines a provisional queued depth from the synchronized single-launch minimum and the wall minimum of a batch at probe_depth. Returns the final depth and its estimated whole-batch wall. The two observations separate fixed synchronization cost from marginal launch cost, so even a shallow provisional batch reaches the ~10 ms contention scale rather than counting a fraction of the fixed cost against every launch. A probe exactly at the target keeps its depth; one that overshoots is interpolated back inside the measured bracket. An unresolved pair requests a doubled retry and returns nan for the wall rather than jumping to the cap or labeling the shallow probe as a cap-wall estimate; repeated unresolved batch pairs eventually reach the 2048-launch memory cap, which calibrate_and_time then bounds by the deepest depth measured within the target (gh-ocannl-1096). Exposed as the deterministic policy seam for tests.

The same affine refinement between two batch observations. An already-target-sized base_ms is retained only when the pair's inferred fixed component is below the target and no more negative than a quarter of the larger of the target and base_ms (the noise tolerance matching the 25% confirmation step, relative to the base's wall since gh-ocannl-1098 so that a slow candidate's slightly superlinear pair still fits), and only when the base is the fit's first target crossing; a resolved base further over the target projects to that crossing instead, shallower than the base. This is the depth-separated confirmation that keeps a shared fixed stall or a physically invalid fit from selecting a shallow final depth while preserving legitimate submit/sync overhead. Otherwise an unresolved pair requests a deeper retry and reports a nan wall. Exposed as the deterministic validation-policy seam for tests.

The depth of the one rescue probe a CUDA/HIP calibration makes before refusing a candidate whose single launch owed it a batch but whose calibration settled at depth 1 (gh-ocannl-1098), from every (depth, minimum wall) it measured: the shallowest batch over the target, projected linearly down to the target, at least 2 and strictly shallower than that batch; None when no depth lies between. Exposed so a test can tell the rescue from the probes before it.

Pure sampling-policy seam used by calibration and the timed loop (gh-ocannl-855). Takes at least max 16 repeats samples; after that floor is met, tops up until their accumulated per_launch_ms reaches ~25 ms or 64 samples have been taken. Thus repeats > 64 deliberately overrides the top-up limit. Reports contended when at least half the raw contention_ms samples exceed their minimum by 2x — dispersion only; a minimum that is non-positive or non-finite is refused by admitted_timing_ms instead. Exposed so tests can inject a deterministic clock. Equal to window_result (sample_window ~repeats ~sample ()).

sample_min's loop, returning the window itself, oldest first. prior (default empty) is a window already taken, which the loop resumes under the same stopping rule rather than restarting (gh-ocannl-1074): a resumed window stops exactly where one uninterrupted window over the same samples would, so it takes no fresh sample when prior already meets the floor and the top-up budget.

A window's reading: its minimum per_launch_ms, its sample count, and the dispersion-only contended verdict sample_min documents.

Pure cache-policy seam (gh-ocannl-855). A search result is cacheable only when at least one candidate was timed and no timing window was refused as unusable. The current call may still ship its best usable candidate, but an incomplete measurement set must be retried by a later cache-cold search.

The mode's canonical spelling (isolated / queued) — what a cache key's "timing" component carries, what a report's mode is rendered as, and the round trip of timing_of_setting.

Parses the autotune_timing spelling (isolated / queued, case- and space-insensitive); raises Invalid_argument on anything else.

on_retry defaults to a no-op and observes each fresh contention retry as it starts. The tuner's own instrument, exposed so a harness can rank candidates by exactly what a search ranks them by (gh-ocannl-755) rather than by a re-derivation of it. Binds test values (set_test_bindings) and restores the routine's bindings afterwards, runs one warmup, then minimizes the per-launch time over at least 16 and repeats timed runs, topping up until ~25 ms of per-launch samples has accumulated (up to 64 runs unless the repeats floor is larger) so that a host stall cannot collapse the min-of-N. Under ~timing:Queued a "run" is a whole batch of dispatches whose depth is calibrated per candidate to ~10 ms of wall, capped at 2048 on CUDA/HIP and at the historical 200 on cc/Metal, and floored at 1. cc/Metal retain the historical synchronized-single estimate. On CUDA/HIP that estimate instead seeds a provisional depth; when that is above 1, a provisional queued probe separates fixed synchronization from marginal launch cost and selects the depth whose affine wall estimate reaches the target. The batch probes take the minimum of twelve runs: unlike ranked timing, they only choose scale and are already milliseconds long. Since gh-ocannl-1098 both are wall-budgeted: a probe stops at three minima once its own wall passes two target-sized probes', and once the probes' summed wall reaches queue_calibration_wall_ms no further probe starts and the calibration ends unresolved. Up to four further probes validate the depth; a resolved crossing shallower than the batches it was fitted from is sampled and checked like an interpolation. The first target-sized batch is confirmed at a 25% deeper depth (clamped to and measured at the cap) and retained only when the pair's inferred fixed component is below the target. A confirmation over 2x its supported base is retried once before an unresolved pair selects the cap. Such a no-verdict fallback is then wall-bounded (gh-ocannl-1096): it never goes deeper than the deepest depth any calibration batch was measured at within the ~10 ms target, and is depth 1 when none was -- the only bound sound for any cost that grows with depth, since the readings that left the fits unresolved cannot tell a host stall from a queue threshold. So a slow candidate whose fits never resolve is timed at depth 1, not in 2048-launch batches, while a fast one whose deeper probes stalled still batches; one that measured no batch within the target at all first takes one rescue probe below its shallowest over-target batch, projected linearly to the target (gh-ocannl-1098) -- where a queue-threshold or superlinear cost reads within the target -- and is refused as unbatched only when that also reads over it, rather than timed as an isolated depth-1 reading. An unresolved single/probe pair retries at double depth, and the next affine fit uses the two batch observations so an inflated single window cannot force the cap. If the bounded loop first reaches the target on its last probe, the interpolated target depth is still sampled and checked against the measured overshoot. A non-monotone confirmation scales from the deeper measured batch, never the earlier suspect crossing. When a clean pair's fixed component already fills the target, its marginal slope selects a depth carrying ~10 ms of launch work instead of accepting a shallow stalled window or jumping to the cap. After four noisy but resolved underestimates, calibration keeps the latest affine projection rather than jumping to a 20--30 ms cap batch that would blunt the 2x contention threshold. None of these projections settles deeper than queue_depth_projection_factor times the deepest batch the calibration probed (gh-ocannl-1100): past it a queue cost can jump where nothing measured. A CUDA/HIP routine slower than the target is confirmed by a depth-2 probe, stays at depth 1, and is measured identically in both modes. When singles below the target owe batching, a resolved pair starting at depth 2 whose marginal launch cost fits the target and whose fixed term is below it retains that measured batch even if its fixed term puts the fitted depth-1 wall above the target (gh-ocannl-1184). It neither returns to the isolated singles nor refuses an ordinary integer-depth boundary; unresolved or over-target marginal fits keep their refusal. Whenever a queued call settles at depth 1 its timed window resumes the calibration's synchronized singles (sample_window's prior) rather than timing a fresh one (gh-ocannl-1074): at depth 1 they are samples of the very quantity the window measures, taken under the same stopping rule, so the loop dispatches only what the caller's repeats floor asks beyond the calibration's sixteen. The calibration always yields a depth; the result of the timed loop reports when most of ITS samples were stalled, and the tuner refuses such a candidate measurement rather than ranking and caching it (gh-ocannl-888). Since the budget is per-launch rather than batch wall, queued timing can spend up to max 64 repeats batches on a fast candidate; max_timing_runs bounds the top-up beyond the caller's requested floor. Metal queued timing retries a contention-refused window once at the same depth with fresh samples (gh-ocannl-1060). The retry faces the same admission rule; only its outcome reaches the search's refusal accounting. Other backends and isolated timing take no retry.

phase labels the call's on_batch_decision (gh-ocannl-1199); none by default.

With ~tag_failures:true the pre-dispatch validation, the launches and the synchronization are wrapped in their Ir.Schedule_outcome phases, which is what lets a caller's Ir.Schedule_outcome.protect attribute a failure to the phase it happened in; without it they propagate raw. Timing dispatches the routine repeatedly against live buffers, so an accumulating routine must be timed on a scratch lineage (see tune's ?timing_ctx) if its inputs matter afterwards. Queued raises how many such dispatches happen. For repeats <= 64, the maxima are 65 under Isolated and, under Queued, 352321 on CUDA/HIP, 12865 on cc or 25665 on Metal. The CUDA/HIP bound includes warmup, 64 single-launch calibration runs, at most queue_calibration_max_probes (nine) queue_batch_probe_runs-sample calibration probes (the provisional probe, four validations, a confirmation, its stall retry, a sampled shallower crossing, and the rescue) and 64 timed batches at the cap; cc/Metal have no batch probes. In general the queued bounds are 65 + 2048 * (108 + max 64 repeats) on CUDA/HIP and 65 + 200 * max 64 repeats on cc, twice the timed part on Metal for its one retry. Thus a routine whose values grow per run reaches larger ones. That is a fact about the scratch buffers, not about the measurement: the cap bounds each in-memory queue while the ~25 ms budget accumulates per-launch samples, and a candidate's time is not what it accumulated.

Observation seam for the timing tests (gh-ocannl-851), called by each time_routine call with the batch depth it settled on — after calibration, before the timed loop; Isolated always reports 1. The negative control for a twice-divided queued reading needs the depth the call ACTUALLY used: the call recalibrates independently, so re-applying queued_batch_depth to an estimate taken outside it guesses wrong exactly on the busy runners the control must survive. calibration_samples retains its historical label for source compatibility; its value is zero for Isolated and the actual number of launches spent on single-launch, provisional-batch and depth-validation calibration for Queued. The default is a no-op and no configuration selects it.

time_routine after its warmup — the calibration and the timed loop, seams included — with the device reduced to batch depth, which must dispatch depth launches back to back, synchronize once and return the wall in milliseconds. queue_depth_cap is queue_depth_cap_for_backend's value for the backend being modelled; it also selects between the CUDA/HIP affine calibration and the historical cc/Metal single estimate. Exposed so a test can drive the whole timing policy on an injected clock and count its launches exactly (gh-ocannl-1074). retry_contended is retry_contended_window_for_backend's value for the backend being modelled; it enables one retry only under Queued, never Isolated.

calibrate_and_time with the per-call observer that drives search accounting. on_retry runs once when a fresh contention retry starts, before on_timing_retry and before any retry dispatch. phase is reported as batch_decision's. The original helper remains a no-op-observer, phase-less wrapper for source compatibility.

The backend whose contended queued windows get one immediate retry: Metal only.

A discarded contention window, immediately before its one fresh retry. Counts the batches sampled and those reused from calibration, so extra dispatches can be accounted for. on_timed_window describes only the returned window; a recovered first window is not a candidate refusal. Default no-op, no configuration key selects it.

Observation seam for the timing tests (gh-ocannl-994), called by each time_routine call once its timed loop has finished, with the number of batches that loop ran — counted by the loop rather than restated from its result, so a test can hold the two against each other — and their summed wall. It is the window the returned minimum was taken over, and so the window a bound on that minimum belongs against: the whole call's wall also holds the warmup and the calibration's synchronized singles, which on a backend whose host round trip is two orders of magnitude above an amortized launch are a comparable share of the call to every timed dispatch put together. A mean over the whole call is therefore diluted by construction, and a host stall in the untimed part moves it without moving the reading. median_wall_ms is the median of the same batch walls, reported alongside the sum because this window's mean is still a stalled minority's to move: sample_min declares contended on a majority of the window exceeding twice its floor, so a bound that must hold whenever the claim is not bypassed belongs on a statistic a minority cannot move — which the median is over exactly the regime the contention rule leaves to it. reused is how many of the window's samples the loop did not dispatch itself: a Queued call that settles at depth 1 resumes the calibration's synchronized singles as its window (gh-ocannl-1074), and those launches are already counted in on_batch_depth's calibration_samples, so the loop's own launches are depth * (samples - reused); it is 0 at every other depth and under Isolated. The default is a no-op and no configuration selects it.

The branch of a CUDA/HIP Queued calibration that started a batch probe. The longest path queue_calibration_max_probes counts is one provisional probe, four validations, a confirmation, its stall retry, a sampled shallower crossing and the rescue.

One batch probe of a calibration, as it ended.

Observation seam for the timing tests (gh-ocannl-1119), called once per CUDA/HIP calibration batch probe, in dispatch order, as the probe ends. A test that sees only the batch calls of calibrate_and_time can reconstruct probes only from runs of same-depth batches, which merges a stall retry into the confirmation it repeats and counts probes as a lower bound; this reports each probe with the branch that started it. The cc/Metal calibration has no batch probes, and Isolated no calibration. The default is a no-op and no configuration selects it.

What one affine fit of a CUDA/HIP Queued calibration concluded about its pair of batch minima: which branch of the refinement produced the depth it returned.

One affine fit of a calibration, as the refinement computed it.

Which exit of the calibration chose the depth, before the post-calibration bounds (batch_decision's bounded_from, fallback_from, rescue) adjusted it.

The call's admission verdict, in admitted_timing_ms's terms; a refusal names the first of unbatched, contended, an unreadable reading that holds.

One timing call's depth decision and admission verdict, from the policy's own metadata.

Trace-only seam (gh-ocannl-1199), called once per time_routine / calibrate_and_time call that returns, after its on_timed_window, with the decision the call took: the fitted fixed and marginal costs, the exit that chose the depth, the bounds that moved it, the probe budget left and the admission verdict, so a consumer such as the benchmarks' BENCH_TIMING_TRACE never re-derives the calibration policy. Observing it changes nothing measured or ranked. The default is a no-op and no configuration selects it.

Fault-injection seam for the containment tests (gh-ocannl-550), called with each candidate's label just before its compile — including the baseline's, which is a candidate (gh-ocannl-533); that one is called inside the base compile's transform, so a fault injected there is classified like any other and surfaces as the pre-search failure of a search that never started. The default is a no-op and no configuration selects it; raising from it terminates the search the way an uncontainable failure does — the Search_died report (carrying its failure) is emitted to ?report and the exception propagates out of tune, which is what Train.tune_placements must survive without losing the other arm's winner. Not a production seam: candidate failures that a backend can attribute are contained without it (see declines).

Fault-injection seam for the pre-dispatch containment tests (gh-ocannl-564), called with a routine's name inside the Ir.Schedule_outcome.phase.Preflight region of its timing run, just before Context.check_launch_bindings. Raising from it classifies exactly as a real per-candidate validation failure does: for a candidate a contained decline under Unclassified_key (Preflight, _); for the baseline the propagating pre-search failure a baseline timing failure always is.

It exists because even the per-candidate trigger — an out-of-range static binding — needs a candidate whose static ranges differ from its siblings' to arise naturally, which the preset families do not supply. The lineage-wide triggers cannot be reached through it at all any more: Context.check_lineage_runnable runs outside this region (gh-ocannl-569), so injecting one of their exceptions here exercises the containment machinery with a realistic payload but does not mirror where a real one is now raised. Default a no-op; no configuration selects it.

Observation seam for the containment tests (gh-ocannl-898), called with a routine's name each time a timing run's window yields an admitted measurement — the moment the search's candidates_timed accounting grows, for the dispatched baseline and candidates alike. timed_so_far is that accounting's own value after this admission — what a report cut at this instant would state as candidates_timed — passed so a precondition of the form "the arm under injection has timed N candidates" pins the tuner's number rather than maintaining a second counter that can drift from it. on_candidate_preflight is upstream of the window's verdict and not a substitute: under the Queued objective a preflighted run can still be refused (a contended window, a degenerate clock reading; gh-ocannl-855) and then times nothing, so counted in preflights such a precondition fires, on a loaded device, on an arm whose report says it timed nothing. Default a no-op; no configuration selects it.

Config autotune_search (default true): what tune searches under when its caller passes no ?search.

The schedule cache directory a tuning call uses, or "" for none: cache_dir when given, else config autotune_cache_dir — except that with the search off only a CHOSEN directory (passed, or set at some config source) counts, the built-in default being treated as no cache (gh-ocannl-559). tune resolves its directory through this, and so does Train.tune_placements for the placement-decision store it keeps in the same directory (gh-ocannl-786), so the two open the same directory under the same rule.

Like Context.compile, but returns the empirically fastest of the searched schedule candidates. The returned context/routine come from an ordinary sibling compile of ctx, so execution-dependency tracking behaves as if the winning compile were the only one. Raises like Context.run would (e.g. uninitialized inputs) — tune in the same state you would run in.

"Like Context.compile" includes its name (gh-ocannl-669) — without which a comp that carries no Ir.Assignments.t.Block_comment but that Context.compile can name (as Parallel's collective routines are named) could be compiled but not tuned. The schedule cache deliberately does not see it: a cache key is Ir.Schedule_cache.cache_key over the canonical lowering, the backend, the numerics and codegen tags, and the worker pool — and the name reaches only codegen's artifact and kernel naming, never the lowering. Two identical computations under different names therefore share one tuned entry, which is what the cache is for; naming a routine neither invalidates a crown nor mints a private one.

Memory (gh-ocannl-550): every candidate this searches is Context.released as soon as it stops being a beam survivor, so the search's live working pools and contexts are bounded by beam_width rather than by candidates attempted. The bound holds across contained failures and across dedups — a deduplicated candidate has still paid for a compile and a link — and the returned routine is the only artifact left when tune returns. Nothing about the returned value changes: it is the same live context and routine as before, from the same lineage.

The bound is on working pools, and that qualifier is load-bearing: Context.release cannot free per-device constants, and a hoisted Stage candidate mints a fresh packed constant per application. A search that seeds those (the CPU hoist sketches) therefore still grows one constant pool per such candidate — measured on cc at 1 -> 109 constant pools over 181 candidates, against working pools held within 2-6. Bounding it needs an eviction rule inside the shared constant cache, which is gh-ocannl-565's subject; pinned as far as it can be by test/operations/autotune_candidate_release.

Default-no-op fault-injection seam immediately before each post-admission callback. The times are the admitted measurements the search ranks, after on_candidate_measured; a strictly larger candidate_ms selects a nonwinner while an already measured incumbent exists.

Measurement seam (gh-ocannl-1027), called once per ADMITTED timing window — the dispatched baseline's (label "baseline") and each candidate's — with the candidate's label, its schedule digest and the admitted time in milliseconds. The returned time replaces the reading before the admission gate, so it is what the search ranks, records and reports: the beam, the best-so-far incumbent, on_candidate_callback, report.best_ms/baseline_ms, the calibration rows and the schedule cache's stored times. A refused window (contended, or a degenerate clock reading) never reaches it unless the test explicitly opts into with_uncontended_test_windows; degenerate readings still never reach it. A returned time that is not finite and positive refuses the window the way a degenerate reading does. It must return rather than raise: it runs outside the search's containment boundaries. It exists so a test about the nonwinner paths can pin the ranking — make the first admitted window the fastest and every later one slower — instead of depending on the machine's timings. The default is the identity and no configuration selects it.

Explicit test-only scope (gh-ocannl-1156) for scripted measurements: clear the physical window's contention flag before candidate admission and on_candidate_measured. Invalid physical or scripted readings and unresolved queued batching still refuse admission. Calibration and dispatch remain real. Restores the previous mode on return or exception, including for nested scopes. No configuration selects it; normal searches retain production contention refusal. Like the other process-wide test hooks, scopes must not run concurrently.

Candidate-window admission and scripted measurement, shared by real searches and deterministic opposing controls. Production refuses contended windows before calling on_candidate_measured; with_uncontended_test_windows explicitly opts a scripted fixture out of that refusal only.

The label on_candidate_measured receives for the candidate a search on backend_name attributes as the untuned default — the one whose refused window sets report.default_refused and whose time is report.default_ms. Some "baseline" with automatic scheduling inactive, where the default is the serial form — None there on a GPU backend, which never dispatches it (gh-ocannl-532); the default-reproducing config_thresholds seed's label with it active and fissioning; None when it is active without fission, where no candidate reproduces the default. tune's own attribution reads this, so the two cannot disagree. One case it cannot foresee: a default seed whose code equals the serial baseline's dedups against it, and is timed only under the label "baseline".