Module Autotune

Parameters of one matmul-sketch seed candidate; see the implementation's field docs. 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.

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.

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 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.

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. 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 { 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.

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 and best_tensorization = None. 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.

The stable one-word name of an outcome state — "searched", "search-died", "cache-replay", "search-disabled", "pre-search-failure" — 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 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 for the site's storage-precision triple, 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.

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) 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; `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.

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.

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 200 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.

Pure sampling-policy seam used by calibration and the timed loop (gh-ocannl-855). Takes at least 16 samples, then tops up until their accumulated per_launch_ms reaches ~25 ms or 64 samples have been taken. 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.

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.

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 (at most 64 runs) 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 200 and floored at 1 — a routine slower than that target is measured identically in both modes. 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 64 batches on a fast candidate; max_timing_runs is its wall-cost bound.

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 — at most 65 under Isolated, against at most 12865 for a microsecond kernel (warmup, 64 calibration launches, then 64 batches at the cap) — so 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 dispatches 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 is zero for Isolated and the actual number of single-launch samples for Queued. 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.

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.