nbxtensor 0.0.1__py3-none-any.whl

nbxtensor/ops/autotune_bucket.py

@@ -0,0 +1,137 @@
+"""The bucket of a request-dependent dimension in an autotune key.
+
+The owner's decision (2026-09-21): request-dependent dimensions — a prefill's token count,
+a decode's key length, a convolution's spatial extents and batch — are BUCKETED in the
+launcher's key. The bucket selects the configuration; the kernel still runs the true size
+with its masks. Without it a census can only cover the requests it is shown, a 57-token
+prompt meets a key nobody certified, and zero miss at verification can never be true.
+
+The ladder is DATA, on the vendor profile (`autotune.buckets`), chosen by measurement the
+way the tile unit was (`tools/bucket_loss.py`, owed-proofs 2026-09-21): on Volta, both
+memory classes, matmul M and the SDPA scores' batched GEMM — exact under 64 (the batched
+GEMM's optimum moves with every size there: up to 16.7 % lost inside a 16-wide bucket),
+then 16-step to 256, 32-step to 1024, 128-step to 8192, 512-step beyond: 0.0 % median and
+maximum loss against the per-size optimum, where powers of two lost up to 26.9 %.
+
+A profile that is BOUND but declares no ladder is REFUSED, not quietly bucketed at step 1.
+Answering "exact" there is a silent degradation dressed as a default: it produces a key
+explosion with no error, and it hid for a day that the ladder had been added to
+nvidia/volta.yml alone while all twenty-six other profiles carried none (found 2026-09-22 by
+the schema gate, not by a run). An UNBOUND profile — `{}`, no target matched, the census
+behind its door before `install()` — is a different condition and still keys exact; that one
+is covered by binding the shadow to its profile, not by a refusal here.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+#: A ladder is a list of [upper_bound, step] rows in ascending bound order: a value v takes
+#: the smallest multiple of `step` >= v within the first row whose bound is >= v. A step of
+#: 1 is "exact". The last row's bound may be null (open).
+Ladder = Sequence[Tuple[Optional[int], int]]
+
+
+_PARSED: Dict[str, Ladder] = {}
+_BY_ID: Dict[int, Tuple[Any, Ladder]] = {}
+
+#: Dimensions that are NOT a tensor dimension and never take the profile's `default` ladder: an element-wise launch's
+#: element count is classed by the launch-overhead and bandwidth regimes (four classes on volta and apple_m4_pro), and
+#: answered by the dimension ladder it became 27 868 classes on apple_m4_pro (the Mac's census, 2026-10-24 12:26) —
+#: five days of certification for one launch tile. A profile without its own ladder for one of these is refused.
+NO_DEFAULT = frozenset({"elements"})
+
+
+def parse_ladder(rows: Any) -> Ladder:
+    """Parsed once per distinct row list: the key of every launch reads the ladder (32 616
+    parses in one chatterbox shadow, 2026-09-22)."""
+    # the profile hands the same row list on every call: answered by its identity first (the `repr` key below, built
+    # per call, was itself the cost — 2 of 40 decode-step samples of Qwen3-30B-A3B, 2026-10-28); the list is kept so
+    # its id is never reused by another
+    hit = _BY_ID.get(id(rows))
+    if hit is not None and hit[0] is rows:
+        return hit[1]
+    memo = repr(rows)
+    got = _PARSED.get(memo)
+    if got is None:
+        got = _PARSED[memo] = _parse_ladder(rows)
+    _BY_ID[id(rows)] = (rows, got)
+    return got
+
+
+def _parse_ladder(rows: Any) -> Ladder:
+    out: List[Tuple[Optional[int], int]] = []
+    for r in rows or []:
+        if isinstance(r, dict):
+            bound, step = r.get("up_to"), r.get("step")
+        else:
+            bound, step = r[0], r[1]
+        if step is None or int(step) < 1:
+            raise ValueError(f"ZERO FALLBACK: a bucket ladder row needs a step >= 1: {r!r}")
+        out.append((None if bound is None else int(bound), int(step)))
+    for i in range(1, len(out)):
+        if out[i - 1][0] is None or (out[i][0] is not None and out[i][0] <= out[i - 1][0]):
+            raise ValueError(f"ZERO FALLBACK: bucket ladder bounds must ascend and only the last may be open: {rows!r}")
+    return out
+
+
+def bucket(value: int, ladder: Ladder) -> int:
+    """The bucket's TOP for `value`: the smallest multiple of the row's step that is >= value."""
+    v = int(value)
+    if v <= 0:
+        return v
+    for bound, step in ladder:
+        if bound is None or v <= bound:
+            return -(-v // step) * step
+    bound, step = ladder[-1]
+    return -(-v // step) * step
+
+
+def ladder_for(dim: str, profile: Optional[Dict[str, Any]] = None) -> Ladder:
+    """The profile's ladder for `dim` ("M", "N", "batch", "height", "width"), else exact."""
+    if profile is None:
+        from nbxtensor.ops._configs import active_vendor_profile
+        profile = active_vendor_profile()
+    bound = bool(profile)
+    spec = ((profile or {}).get("autotune") or {}).get("buckets") or {}
+    rows = spec.get(dim) if isinstance(spec, dict) else None
+    if rows is None and dim in NO_DEFAULT and bound:
+        raise RuntimeError(
+            f"ZERO FALLBACK: the bound hardware profile {(profile or {}).get('architecture') or '<unnamed>'!r} declares "
+            f"no autotune.buckets.{dim} ladder, and {dim!r} never takes the `default` dimension ladder (an element "
+            f"count's classes are its launch-overhead and bandwidth regimes, not dimension steps). Add the measured "
+            f"ladder, with its source, to its vendor YAML (see nvidia/volta.yml).")
+    if rows is None:
+        rows = spec.get("default") if isinstance(spec, dict) else None
+    if rows:
+        return parse_ladder(rows)
+    if bound:
+        # ZERO FALLBACK: a real profile that forgot the ladder is a defect in the profile,
+        # and keying exact would hide it behind a plausible-looking answer.
+        raise RuntimeError(
+            "ZERO FALLBACK: the bound hardware profile "
+            f"{(profile or {}).get('architecture') or '<unnamed>'!r} declares no "
+            f"autotune.buckets ladder, so dimension {dim!r} has no bucket.\n"
+            "  Add `autotune.buckets.default` to its vendor YAML (see nvidia/volta.yml), "
+            "or the census keys this dimension EXACTLY and every request length becomes "
+            "its own key.\n"
+            "  A step of 1 is a legitimate ladder and must be written down as one."
+        )
+    return [(None, 1)]        # no target bound: the census's own door, unchanged
+
+
+def class_floor(dim: str, top: int, profile: Optional[Dict[str, Any]] = None) -> int:
+    """The fewest `dim` that form the class whose top is `top` (`bucket_of`'s inverse floor): the row holding `top`,
+    one past the class below it (its top minus the row's step) or past the previous row's bound."""
+    t = int(top)
+    if t <= 0:
+        return t
+    prev = 0
+    for bound, step in ladder_for(dim, profile):
+        if bound is None or t <= bound:
+            return max(prev + 1, t - step + 1)
+        prev = bound
+    return max(prev + 1, t - ladder_for(dim, profile)[-1][1] + 1)
+
+
+def bucket_of(dim: str, value: int, profile: Optional[Dict[str, Any]] = None) -> int:
+    return bucket(value, ladder_for(dim, profile))

nbxtensor/ops/autotune_cache.py

@@ -0,0 +1,430 @@
+"""E2-full — persistable autotune-config artifact (scoping §Phase 4a.4).
+
+Triton's own disk cache (`cache_results=True`) persists autotune
+selections keyed by SOURCE HASH — any kernel-file edit invalidates it
+and the next run re-benches (the battery kernel-edit false-RED class,
+and a run-to-run timing-variance surface). This module captures the
+SELECTED configs keyed by OUR fingerprint — (kernel qualname,
+autotune-key literal, arch) — and seeds them back into the Autotuner
+in-memory caches, immune to source-hash invalidation:
+
+  capture()  after a warmed pass (the replay recording pass), walk the
+             five sanctioned Autotuner kernels (mm/bmm/addmm/conv2d/
+             depthwise — the Phase 1.5 scope) and merge their selected
+             configs into the artifact.
+  seed()     before execution, insert stored configs into each
+             Autotuner's cache: a hit means run() never benches.
+
+R33: imports triton + stdlib only. The artifact is an optimization,
+never a failure source — every I/O error degrades to "no seed".
+Storage: ~/.neurobrix/replay_cache/autotune_configs_<arch>.json.
+"""
+
+import ast
+import json
+import os
+from typing import Dict, Iterator, Optional, Tuple
+
+# The machine's replay cache (the producer's accumulation across models, and
+# the correctness screen's exclusions). NEUROBRIX_REPLAY_CACHE relocates it —
+# a gate that needs a truly cold sweep per arm gives every arm its own, else
+# sweep mode seeds the autotuners from here and no arm sweeps (2026-09-06:
+# a screened arm reported "checked 0 key(s)" for exactly this reason).
+def _dir() -> str:
+    """Where the local replay cache lives, read WHEN USED.
+
+    This was a module global computed at import time. A value frozen at import
+    from an environment variable is the same class of defect as a literal
+    standing in for a runtime value: whoever imports the module first decides it
+    for the whole process. Measured 2026-09-17 — a test redirecting
+    NEUROBRIX_REPLAY_CACHE to a tmp path imported this module inside its own
+    body, froze the tmp path, and a later test in the same process asserting on
+    the real directory failed. monkeypatch restored the env; it could not
+    restore a constant already computed from it.
+    """
+    return (os.environ.get("NEUROBRIX_REPLAY_CACHE")
+            or os.path.join(os.path.expanduser("~"), ".neurobrix", "replay_cache"))
+
+
+#: The directory as it stood AT IMPORT. Kept as a real attribute because
+#: `importlib.reload` is how the relocation test observes it, and a module
+#: __getattr__ does not survive that cleanly. Everything INSIDE this module
+#: calls `_dir()` instead, so a process that changes the environment after
+#: import writes where the environment now says — which is what a test
+#: redirecting it to a tmp path needs, and what a later test reading the real
+#: directory needs too.
+_DIR = _dir()
+
+# The sanctioned autotune surface (Phase 1.5 doctrine: mm/bmm/addmm/
+# conv2d only) — explicit list, not a gc walk. A new autotuned kernel
+# is added here the day its autotune exception is granted. Supervisor
+# ruling 2026-08-16: NO autotuner lives outside this regime (the one
+# historical candidate outside it, the FlagGems kernels/utils remnant,
+# was dead code and was removed 2026-08-17). Since the owner directive of
+# 2026-09-06 the regime is the CERTIFIED DIRECTORY (`kernels/
+# autotune_certified.py`, `config/autotune/<vendor>/<profile>/`): a shape it
+# holds is applied at load; a shape it lacks sweeps at runtime with the
+# consensus screen and lands HERE, the machine's local replay cache.
+_KERNEL_SITES = (
+    ("nbxtensor.ops.matmul", "matmul_kernel"),
+    ("nbxtensor.ops.matmul", "addmm_kernel"),
+    ("nbxtensor.ops.baddbmm_op", "baddbmm_kernel"),
+    ("nbxtensor.ops.conv2d", "conv2d_forward_kernel"),
+    ("nbxtensor.ops.depthwise_conv2d", "depthwise_conv2d_kernel"),
+    # workstream 1: certified per key like the five above (the softmax's module is imported with the wrappers; the
+    # matrix-unit flash's only when an attention takes it — a certification before any attention found no tuner)
+    ("nbxtensor.ops.softmax", "softmax_forward_kernel"),
+    ("nbxtensor.ops.flash_attention_m8n8k4", "flash_attention_m8n8k4_kernel"),
+    # C3: the tl.dot flash's tile, certified where the profile declares no hand table (`sdpa_thresholds`)
+    ("nbxtensor.ops.flash_attention", "flash_attention_certified_kernel"),
+)
+
+
+def _arch_fingerprint() -> Optional[str]:
+    """None when the driver query fails — no fingerprint means NO
+    artifact (capture/seed no-op), never a shared cross-arch bucket
+    (an sm_80 config seeded onto sm_70 fails at compile inside a user
+    run)."""
+    try:
+        from nbxtensor.backend.launcher import target as _nbx_target  # engine data, no driver probe (R33)
+        target = _nbx_target()
+        return f"{target.backend}-{target.arch}"
+    except Exception:
+        return None
+
+
+def _running_generator() -> Optional[str]:
+    """The code generator about to run, as the certified directory's proofs record it
+    (`kernels.autotune_certified.running_generator`: the Triton distribution, the target, and the
+    out-of-tree backend's source hash where one generates the code). None when it cannot be named."""
+    try:
+        from nbxtensor.ops.autotune_certified import running_generator
+        return running_generator()
+    except Exception:
+        return None
+
+
+def _generator_tag() -> Optional[str]:
+    """A file-safe tag of the running generator: its backend hash's short id where the backend is
+    out of tree (`msl-v0.1-42e` -> `42e`), else the whole identity flattened."""
+    gen = _running_generator()
+    if not gen:
+        return None
+    import re as _re
+    m = _re.search(r"msl-v[\d.]+-([0-9a-f]{3,})", gen)   # the proof records the short id (`msl-v0.1-42e`)
+    tag = m.group(1) if m else _re.sub(r"[^0-9A-Za-z.]+", "_", gen).strip("_")
+    return tag[:40] or None
+
+
+def _artifact_path() -> Optional[str]:
+    """The replay artifact of THIS backend, arch AND code generator. A configuration is a property
+    of the compiler that produced it (the certified directory's generator door, 2026-09-06): a
+    sweep made under one generator is never seeded under another. Before 2026-09-28 the file was
+    named by arch alone, and on the Mac the two "served" gates of the triton-ext bump took 545 of
+    their 1 400 key uses from sweeps the retired compiler had made. No generator name, no artifact."""
+    arch = _arch_fingerprint()
+    if arch is None:
+        return None
+    gen = _generator_tag()
+    if gen is None:
+        return None
+    return os.path.join(_dir(), f"autotune_configs_{arch}-{gen}.json")
+
+
+def _autotuners() -> Iterator[Tuple[str, object]]:
+    """Every Autotuner the process has loaded from the kernel library — the
+    five sanctioned sites first (imported on demand), then every other
+    `neurobrix.kernels.ops.*` module already in sys.modules. Since 2026-09-05
+    the engine is the only persistence of a sweep (upstream's on-disk cache
+    keyed its files by a torch-importing driver probe and was dropped), so
+    every tuner's selections are captured, not only the matmul class's."""
+    import importlib
+    import sys
+    from triton.runtime.autotuner import Autotuner
+    seen = set()
+    for mod_name, attr in _KERNEL_SITES:
+        try:
+            obj = getattr(importlib.import_module(mod_name), attr, None)
+        except Exception:
+            continue
+        if isinstance(obj, Autotuner):
+            seen.add(id(obj))
+            yield f"{mod_name}.{attr}", obj
+    for mod_name, mod in list(sys.modules.items()):
+        # the kernel files: the library's (`nbxtensor.ops`) and the engine's still to move (`neurobrix.kernels.ops`)
+        if not mod_name.startswith(("nbxtensor.ops.", "neurobrix.kernels.ops.")) or mod is None:
+            continue
+        for attr, obj in list(vars(mod).items()):
+            if isinstance(obj, Autotuner) and id(obj) not in seen:
+                seen.add(id(obj))
+                yield f"{mod_name}.{attr}", obj
+
+
+def _config_to_dict(cfg) -> Dict:
+    return {"kwargs": dict(cfg.kwargs), "num_warps": cfg.num_warps,
+            "num_stages": cfg.num_stages, "num_ctas": cfg.num_ctas,
+            "maxnreg": cfg.maxnreg}
+
+
+def _config_from_dict(d):
+    import triton
+    return triton.Config(dict(d["kwargs"]), num_warps=d["num_warps"],
+                         num_stages=d["num_stages"], num_ctas=d["num_ctas"],
+                         maxnreg=d.get("maxnreg"))
+
+
+def _exclusions_path() -> Optional[str]:
+    """Where the correctness screen's exclusions are kept, beside the sweep."""
+    path = _artifact_path()
+    if path is None:
+        return None
+    return path.replace("autotune_configs_", "autotune_exclusions_")
+
+
+def record_screen_exclusions(entries) -> int:
+    """Persist configs the correctness screen refused, so a later sweep and its readers see them.
+
+    A config excluded for being WRONG and a config that merely lost on speed
+    are indistinguishable in a sweep that records only the winner — and they
+    are not the same fact at all. One is a tuning outcome; the other is a
+    backend defect with a shape attached.
+
+    Keyed by kernel, key and config so repeated runs merge instead of
+    accumulating duplicates. Best-effort: a sweep that cannot be written must
+    never fail a launch, and the exclusions are also printed as they happen.
+    """
+    path = _exclusions_path()
+    if path is None or not entries:
+        return 0
+    try:
+        os.makedirs(_dir(), exist_ok=True)
+        stored: Dict[str, Dict] = {}
+        try:
+            with open(path) as f:
+                stored = json.load(f)
+        except (OSError, ValueError):
+            stored = {}
+        added = 0
+        for entry in entries:
+            entry = dict(entry)
+            ident = f"{entry.get('kernel')}::{entry.get('key')!r}::{entry.get('config')}"
+            if ident not in stored:
+                stored[ident] = entry
+                added += 1
+        if added:
+            with open(path, "w") as f:
+                json.dump(stored, f, indent=1, default=str)
+        return added
+    except OSError:
+        return 0
+
+
+def screen_exclusions() -> Dict[str, Dict]:
+    """Everything the screen has refused on this machine."""
+    path = _exclusions_path()
+    if path is None:
+        return {}
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return {}
+
+
+#: Keys whose config was chosen WITHOUT measurement -- e.g. the bench was
+#: skipped because its arguments alone exceed the machine's available memory,
+#: so timing candidates would have measured the swap and not the kernels. A
+#: choice made without measurement must never be recorded as if measured:
+#: persisted, it would outlive the pressure that forced it and keep deciding
+#: on machines and days it knows nothing about.
+_UNMEASURED: set = set()
+
+
+def mark_unmeasured(at, key) -> None:
+    _UNMEASURED.add((id(at), tuple(key) if isinstance(key, (list, tuple)) else key))
+
+
+def is_unmeasured(at, key) -> bool:
+    return (id(at), tuple(key) if isinstance(key, (list, tuple)) else key) in _UNMEASURED
+
+
+def capture() -> int:
+    """Merge every selected config into the artifact. Returns the
+    number of NEW entries written (0 = artifact already covers this
+    process's selections)."""
+    path = _artifact_path()
+    if path is None:
+        return 0
+    # THE RECORD CARRIES WHAT IT IS. A configuration the screen seated without
+    # an oracle is the fastest among candidates nothing verified, and until the
+    # owner's ruling of 2026-09-12 it was written here exactly like one an fp64
+    # oracle had adjudicated. The engine still runs and the screen still ranks
+    # by speed; what it may no longer do is produce a record that reads as a
+    # validation. The certified directory is a different path entirely
+    # (`config/autotune/`, filled only by `neurobrix autotune certify`), so
+    # nothing here can reach it — this is the mention where it IS recorded.
+    try:
+        from nbxtensor.backend.launcher import adjudicated as _adjudicated, unscreened as _unscreened
+        unverified = {(u.kernel, repr(u.key)): u.reason for u in _unscreened()}
+        verified = _adjudicated()
+    except Exception:                       # never turn a record into a failure
+        unverified, verified = {}, {}
+
+    entries: Dict[str, Dict] = {}
+    skipped_unmeasured = 0
+    for qual, at in _autotuners():
+        short = qual.rsplit(".", 1)[-1]
+        for key, cfg in getattr(at, "cache", {}).items():
+            if is_unmeasured(at, key):
+                skipped_unmeasured += 1
+                continue
+            rec = _config_to_dict(cfg)
+            if (id(at), key) in _TIMINGS:
+                rec["timing"] = _TIMINGS[(id(at), key)]
+            adjudicator = verified.get((short, repr(key)))
+            if adjudicator is not None:
+                rec["screened"] = True
+                rec["screened_by"] = adjudicator
+            reason = unverified.get((short, repr(key)))
+            if reason is not None:
+                rec["screened"] = False
+                rec["unscreened_reason"] = reason
+                rec["provenance"] = ("fastest among candidates nothing "
+                                     "verified — NOT a validated setting")
+            # A shape over the screening budget is screened on ROW WINDOWS, and the proof
+            # names them: what was verified and what was not must always be readable
+            # (owner, 2026-09-23). Recorded for the key whether the windows were adjudicated
+            # by the fp64 oracle or, where no windowed oracle covers the kernel, by consensus.
+            try:
+                from nbxtensor.backend.launcher import screen_windows_of
+                win = screen_windows_of(key)
+            except Exception:                            # noqa: BLE001
+                win = None
+            if win is not None:
+                rec["screened"] = True
+                rec["screened_on_windows"] = win["windows"]
+                rec["screened_by"] = win["adjudicated_by"]
+                rec["screen_kept"] = f"{win['kept']} of {win['candidates']}"
+                rec["provenance"] = (
+                    f"verified on {win['windows']} by {win['adjudicated_by']}; the rest of "
+                    f"the output and the input buffers were NOT compared")
+            entries[f"{qual}::{key!r}"] = rec
+    if skipped_unmeasured:
+        print(f"[AUTOTUNE_CACHE] {skipped_unmeasured} choice(s) made without "
+              f"measurement were NOT persisted", flush=True)
+    if not entries:
+        return 0
+    try:
+        os.makedirs(_dir(), exist_ok=True)
+        stored: Dict[str, Dict] = {}
+        try:
+            with open(path) as f:
+                stored = json.load(f)
+        except (OSError, ValueError):
+            stored = {}
+        new = {k: v for k, v in entries.items() if k not in stored}
+        if new:
+            stored.update(new)
+            with open(path, "w") as f:
+                json.dump(stored, f)
+        return len(new)
+    except OSError:
+        return 0
+
+
+def seed() -> int:
+    """Insert stored configs into the Autotuner caches. Returns the
+    number of entries seeded.
+
+    MEMBERSHIP GATE (staleness safety): a stored config is seeded ONLY
+    if it is a member of the Autotuner's CURRENT declared config space
+    (kwargs + num_warps + num_stages equality against at.configs) — a
+    member is by definition a config a fresh bench could legally
+    select for the current kernel source and current policy. This
+    refuses resurrection of configs removed as buggy, refuses configs
+    whose constexpr names drifted with a source edit, and honors
+    NBX_DISABLE_AUTOTUNE's pinned single-config list (one member).
+    Non-members and non-literal keys are skipped: that shape simply
+    re-tunes, exactly the pre-E2 behavior."""
+    path = _artifact_path()
+    if path is None:
+        return 0
+    try:
+        with open(path) as f:
+            stored = json.load(f)
+    except (OSError, ValueError):
+        return 0
+    return _seed_entries(stored)
+
+
+def _seed_entries(stored: Dict[str, Dict]) -> int:
+    """Insert `stored` configs into the Autotuner caches under the
+    membership gate documented on `seed()`. Returns the number seeded."""
+    seeded = 0
+    for qual, at in _autotuners():
+        prefix = f"{qual}::"
+        space = {(tuple(sorted(c.kwargs.items())), c.num_warps,
+                  c.num_stages) for c in getattr(at, "configs", [])}
+        for k, d in stored.items():
+            if not k.startswith(prefix):
+                continue
+            member = (tuple(sorted(dict(d["kwargs"]).items())),
+                      d["num_warps"], d["num_stages"])
+            if member not in space:
+                continue
+            try:
+                key = ast.literal_eval(k[len(prefix):])
+            except (ValueError, SyntaxError):
+                continue
+            if key not in at.cache:
+                try:
+                    at.cache[key] = _config_from_dict(d)
+                    seeded += 1
+                except Exception:
+                    continue
+    return seeded
+
+
+# ---------------------------------------------------------------------------
+# The Autotuner's key, and the bench margin of a key this process measured
+# ---------------------------------------------------------------------------
+def key_of(at, args, kwargs) -> tuple:
+    """The Autotuner's cache key for a call, as `Autotuner.run` forms it."""
+    _args = {**dict(zip(at.arg_names, args)), **kwargs}
+    key = [_args[k] for k in at.keys if k in _args]
+    for _, arg in _args.items():
+        if hasattr(arg, "dtype"):
+            key.append(str(arg.dtype))
+    return tuple(key)
+
+
+def _qual_of(at) -> Optional[str]:
+    for qual, obj in _autotuners():
+        if obj is at:
+            return qual
+    return None
+
+
+_TIMINGS: Dict[Tuple[int, tuple], Dict] = {}     # (id(tuner), key) -> best/second/margin of a bench this process ran
+
+
+def note_timings(at, key: tuple, timings) -> None:
+    """Keep the bench of a key this process just measured: the best time, the
+    second-best, and the MARGIN between them. A cache that records only the
+    winner cannot say whether the winner was clear or a near-tie the timer
+    could flip on the next run — a gate comparing two sweeps needs exactly
+    that to tell a change of choice from noise. Written beside the config by
+    `capture()`."""
+    if not timings:
+        return
+    try:
+        times = sorted(float(t) for t in timings.values() if t is not None and float(t) == float(t))
+    except (TypeError, ValueError):
+        return
+    if not times:
+        return
+    best = times[0]
+    second = times[1] if len(times) > 1 else None
+    _TIMINGS[(id(at), key)] = {
+        "best_ms": best, "second_ms": second, "candidates": len(times),
+        "margin": (second / best - 1.0) if (second is not None and best > 0) else None}