Make the compatibility claim testable instead of aspirational

Everyone runs a different ComfyUI, and Core's parameter ORDER has already moved
once -- master reorders MiniMaxH3ReferenceToVideo. Three things now stand
between that and a user's traceback.

**No positional Core call is left.** The two H3 nodes were converted when a
user hit "multiple values for argument 'ref_image_size'"; the other six were
not, and were the same failure waiting: MiniMaxH3SigmaShift, KSamplerSelect,
BasicScheduler, BasicGuider, RandomNoise, SamplerCustomAdvanced. All now go
through _core_call by keyword, so they also inherit its error message, which
names the node, the argument and what the installed Core actually takes.

**check_core_calls.py watches all nine nodes, not three.** It resolves each
one through the module that defines it, so nodes_custom_sampler is covered
alongside nodes_minimax_h3. Eleven call sites, every one order-independent and
name-checked against the Core on this machine.

**check_core_matrix.py checks the Core on everyone else's.** It reads the floor
from pyproject, enumerates every ComfyUI release at or above it plus today's
master, and binds all eleven call sites against each version's real signatures
-- node present, nothing positional, every keyword real, every required
parameter supplied. Signatures are read with ast, never imported: it downloads
code from the internet and parsing is not running.

Falsified by lowering the floor to 0.30.0, where it fails on v0.30.0, v0.31.0,
v0.32.0 and v0.33.1 with "MiniMaxH3AddGuide does not exist here" and passes on
v0.34.0 and master -- deriving the floor independently of the reasoning that
set it. Network-bound, so it is not in check_all.py.

Verified statically and by signature binding, not by a render.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PLXmbwfdXirQ5oFreXPcMi

.gitignore

@@ -20,3 +20,4 @@ htc_llm.json
 # dead ends and machine specifics, and one of them is always the live queue.
 # The root HANDOVER.md was already ignored; these are the same thing, dated.
 docs/HANDOVER_*.md
+.core_matrix_cache/

h3_ref_chain.py

@@ -2879,9 +2879,17 @@ class HandTieClips:
         sampler = base_sigmas = None
         sigma_cache = {}
         if not dry:
-            model = _result(MiniMaxH3SigmaShift.execute(model, float(shift_video), float(shift_audio)))[0]
-            sampler = _result(KSamplerSelect.execute(sampler_name))[0]
-            base_sigmas = _result(BasicScheduler.execute(model, scheduler, int(steps), 1.0))[0]
+            model = _result(_core_call(
+                MiniMaxH3SigmaShift, "the sigma shift",
+                model=model, shift_video=float(shift_video),
+                shift_audio=float(shift_audio)))[0]
+            sampler = _result(_core_call(
+                KSamplerSelect, "the sampler",
+                sampler_name=sampler_name))[0]
+            base_sigmas = _result(_core_call(
+                BasicScheduler, "the sigma schedule",
+                model=model, scheduler=scheduler, steps=int(steps),
+                denoise=1.0))[0]
             sigma_cache = {int(steps): base_sigmas}
 
         print(
@@ -3587,23 +3595,30 @@ class HandTieClips:
 
                 _offload_text_encoder(clip, model)
 
-                guider = _result(BasicGuider.execute(model, cond))[0]
+                guider = _result(_core_call(
+                    BasicGuider, "the guider",
+                    model=model, conditioning=cond))[0]
                 if shot.get("seed") is not None:
                     shot_seed = int(shot["seed"])
                 else:
                     shot_seed = (int(seed) + i) if seed_per_shot else int(seed)
                 hop_steps = int(shot.get("steps") or steps)
                 if hop_steps not in sigma_cache:
-                    sigma_cache[hop_steps] = _result(
-                        BasicScheduler.execute(model, scheduler, hop_steps, 1.0))[0]
+                    sigma_cache[hop_steps] = _result(_core_call(
+                        BasicScheduler, "the sigma schedule",
+                        model=model, scheduler=scheduler, steps=hop_steps,
+                        denoise=1.0))[0]
                 hop_sigmas = sigma_cache[hop_steps]
                 if hop_steps != int(steps) or shot.get("seed") is not None:
                     print(f"[{TAG}] hop {i + 1} override: seed={shot_seed} "
                           f"steps={hop_steps}", flush=True)
-                noise = _result(RandomNoise.execute(shot_seed))[0]
-                sampled = _result(SamplerCustomAdvanced.execute(
-                    noise, guider, sampler, hop_sigmas, latent
-                ))[0]
+                noise = _result(_core_call(
+                    RandomNoise, "the noise source",
+                    noise_seed=shot_seed))[0]
+                sampled = _result(_core_call(
+                    SamplerCustomAdvanced, "the sampler",
+                    noise=noise, guider=guider, sampler=sampler,
+                    sigmas=hop_sigmas, latent_image=latent))[0]
 
                 imgs, audio = _decode_av(vae, audio_vae, sampled)
                 imgs = imgs.contiguous().cpu()

tools/check_core_calls.py

@@ -31,7 +31,20 @@ COMFY = os.path.dirname(os.path.dirname(HERE))
 sys.path.insert(0, COMFY)
 
 FAIL = []
-WATCHED = {"MiniMaxH3ReferenceToVideo", "MiniMaxH3AddGuide", "MiniMaxH3ImageToVideo"}
+# Every Core node this pack calls, and the module that defines it. The H3 three
+# are the ones whose order actually moved; the sampler five are the same failure
+# class waiting to happen, and cost nothing to watch.
+WATCHED = {
+    "MiniMaxH3ReferenceToVideo": "comfy_extras.nodes_minimax_h3",
+    "MiniMaxH3AddGuide": "comfy_extras.nodes_minimax_h3",
+    "MiniMaxH3ImageToVideo": "comfy_extras.nodes_minimax_h3",
+    "MiniMaxH3SigmaShift": "comfy_extras.nodes_minimax_h3",
+    "KSamplerSelect": "comfy_extras.nodes_custom_sampler",
+    "BasicScheduler": "comfy_extras.nodes_custom_sampler",
+    "BasicGuider": "comfy_extras.nodes_custom_sampler",
+    "RandomNoise": "comfy_extras.nodes_custom_sampler",
+    "SamplerCustomAdvanced": "comfy_extras.nodes_custom_sampler",
+}
 
 
 def ck(name, cond, detail=""):
@@ -41,7 +54,11 @@ def ck(name, cond, detail=""):
 
 
 def core_params(cls_name):
-    from comfy_extras import nodes_minimax_h3 as core
+    import importlib
+    try:
+        core = importlib.import_module(WATCHED[cls_name])
+    except (ImportError, KeyError):
+        return None
     cls = getattr(core, cls_name, None)
     if cls is None:
         return None

tools/check_core_matrix.py

@@ -0,0 +1,198 @@
+"""Prove every Core call works on EVERY ComfyUI in the range we advertise.
+
+check_core_calls.py checks the Core installed on this machine. That proves the
+pack does not depend on parameter order, which is what broke a user once, but it
+cannot prove the call works on the build somebody else is running -- and
+everybody is running something different. pyproject.toml claims
+`requires-comfyui = ">=0.34.0"` with no upper bound. This is what makes that
+claim testable rather than aspirational.
+
+For every ComfyUI release at or above the declared floor, plus today's master,
+it fetches the modules that define the nodes this pack calls, reads their
+`execute` signatures, and checks each call site against them:
+
+  * the node exists in that version at all
+  * nothing is passed positionally
+  * every keyword passed is a real parameter there
+  * every parameter that has no default there is one we supply
+
+Signatures are read with `ast`, never imported -- this downloads code from the
+internet, and parsing it is not the same as running it.
+
+Network, so it is not in check_all.py. Run it when Core moves, when the floor
+changes, or before a release.
+
+    D:\\ComfyUI\\venv\\Scripts\\python.exe tools\\check_core_matrix.py
+    ... --refresh     ignore the cache and re-fetch
+"""
+from __future__ import annotations
+
+import ast
+import io
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# comfyanonymous/ComfyUI redirected to Comfy-Org/ComfyUI; the numeric id is
+# stable across the rename and does not 301.
+REPO = "https://api.github.com/repositories/589831718"
+RAW = "https://raw.githubusercontent.com/Comfy-Org/ComfyUI/{ref}/{path}"
+CACHE = os.path.join(HERE, ".core_matrix_cache")
+
+MODULES = {
+    "comfy_extras.nodes_minimax_h3": "comfy_extras/nodes_minimax_h3.py",
+    "comfy_extras.nodes_custom_sampler": "comfy_extras/nodes_custom_sampler.py",
+}
+
+FAILS = []
+
+
+def ck(label, ok, detail=""):
+    print("  %-4s %-46s %s" % ("ok" if ok else "FAIL", label, detail))
+    if not ok:
+        FAILS.append(label)
+
+
+def fetch(url, cache_key, refresh=False):
+    path = os.path.join(CACHE, cache_key)
+    if not refresh and os.path.exists(path):
+        return io.open(path, encoding="utf-8").read()
+    with urllib.request.urlopen(url, timeout=60) as r:
+        body = r.read().decode("utf-8")
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    io.open(path, "w", encoding="utf-8", newline="").write(body)
+    return body
+
+
+def parse_version(tag):
+    m = re.match(r"^v?(\d+)\.(\d+)\.(\d+)", tag or "")
+    return tuple(int(x) for x in m.groups()) if m else None
+
+
+def floor_from_pyproject():
+    s = io.open(os.path.join(HERE, "pyproject.toml"), encoding="utf-8").read()
+    m = re.search(r'^requires-comfyui\s*=\s*"([^"]+)"', s, re.M)
+    if not m:
+        return None, ""
+    spec = m.group(1)
+    return parse_version(spec.lstrip(">=<!~ ")), spec
+
+
+def signatures(src):
+    """{name: (param_names, required_names)} read without importing."""
+    out = {}
+    tree = ast.parse(src)
+    for cls in [n for n in ast.walk(tree) if isinstance(n, ast.ClassDef)]:
+        for fn in cls.body:
+            if not (isinstance(fn, ast.FunctionDef) and fn.name == "execute"):
+                continue
+            a = fn.args
+            names = [x.arg for x in (a.posonlyargs + a.args)
+                     if x.arg not in ("cls", "self")]
+            ndef = len(a.defaults)
+            req = names[:len(names) - ndef] if ndef else list(names)
+            names += [x.arg for x in a.kwonlyargs]
+            req += [x.arg for x, d in zip(a.kwonlyargs, a.kw_defaults)
+                    if d is None]
+            # Indexed by the class name, because that is what this pack imports.
+            out[cls.name] = (names, req)
+    return out
+
+
+def call_sites():
+    """Every watched Core call in the pack, with the keywords it passes."""
+    import check_core_calls as C
+    src = io.open(os.path.join(HERE, "h3_ref_chain.py"), encoding="utf-8").read()
+    sites = []
+    for node in ast.walk(ast.parse(src)):
+        if not isinstance(node, ast.Call):
+            continue
+        f, owner, args = node.func, None, None
+        if (isinstance(f, ast.Attribute) and f.attr == "execute"
+                and isinstance(f.value, ast.Name)):
+            owner, args = f.value.id, node.args
+        elif isinstance(f, ast.Name) and f.id == "_core_call" and node.args:
+            first = node.args[0]
+            if isinstance(first, ast.Name):
+                # _core_call(Node, "what", **kw) -- the first two are the
+                # wrapper's own, everything after would be positional to Core.
+                owner, args = first.id, node.args[2:]
+        if owner in C.WATCHED:
+            sites.append((owner, node.lineno, len(args or []),
+                          [k.arg for k in node.keywords if k.arg]))
+    return sites
+
+
+def main():
+    refresh = "--refresh" in sys.argv
+    floor, spec = floor_from_pyproject()
+    if floor is None:
+        print("pyproject.toml declares no requires-comfyui; nothing to verify")
+        return 1
+    print("pyproject declares requires-comfyui = %r\n" % spec)
+
+    sites = call_sites()
+    print("%d call site(s) across %d node(s)"
+          % (len(sites), len({s[0] for s in sites})))
+
+    rels = json.loads(fetch(REPO + "/releases?per_page=100", "releases.json",
+                            refresh=True))
+    tags = sorted({r["tag_name"] for r in rels
+                   if parse_version(r["tag_name"])
+                   and parse_version(r["tag_name"]) >= floor},
+                  key=parse_version)
+    refs = tags + ["master"]
+    print("%d version(s) at or above the floor, plus master\n" % len(tags))
+
+    for ref in refs:
+        sigs, missing = {}, None
+        for path in MODULES.values():
+            try:
+                src = fetch(RAW.format(ref=ref, path=path),
+                            os.path.join(ref, path.replace("/", "_")),
+                            refresh=refresh or ref == "master")
+            except urllib.error.HTTPError as e:
+                missing = "%s (HTTP %d)" % (path, e.code)
+                continue
+            sigs.update(signatures(src))
+        if missing:
+            ck("%s: has the modules this pack imports" % ref, False, missing)
+            continue
+
+        bad = []
+        for owner, line, npos, kws in sites:
+            if owner not in sigs:
+                bad.append("%s @:%d does not exist here" % (owner, line))
+                continue
+            names, req = sigs[owner]
+            if npos:
+                bad.append("%s @:%d passes %d positionally" % (owner, line, npos))
+            unknown = [k for k in kws if k not in names]
+            if unknown:
+                bad.append("%s @:%d passes %s; this version takes %s"
+                           % (owner, line, unknown, names))
+            unfilled = [r for r in req if r not in kws]
+            if unfilled:
+                bad.append("%s @:%d omits required %s" % (owner, line, unfilled))
+        ck("%s: every call binds" % ref, not bad,
+           "%d site(s)" % len(sites) if not bad else "")
+        for b in bad:
+            print("       %s" % b)
+
+    if FAILS:
+        print("\nCORE MATRIX: %d version(s) this pack claims to support and "
+              "does not." % len(FAILS))
+        return 1
+    print("\nCORE MATRIX: every call site binds on every version at or above "
+          "the declared floor, and on master.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())