[feat]: dispatch trusted graph artifacts with native fallback

[aryan5v]

Fork-only — not for upstream. Stacked on agent/graph-executable-ir.

Runs a packaged optimization artifact in place of a repeated block's forward when — and only when — it provably matches. Otherwise the model runs natively.

Consumer half of aryan5v/motionkernel#11, which owns the manifest schema.

No model-specific code

Dispatch attaches to the same model-independent structure capture uses: children of an nn.ModuleList that share a class. There is no Wan-, LTX-, Cosmos- or Kandinsky-specific conditional anywhere in this path. A new model is supported by publishing an artifact, never by editing code.

Per stack and per observed input signature:

1. First call runs natively — that is what reveals the output signature, which is part of the artifact's identity.
2. Registry is pre-filtered on input layout. If nothing in the store is shaped like this call, no graph is ever traced.
3. The module is traced once to recompute its graph fingerprint, through the capture module, so the value matches what the producer recorded.
4. Compatibility is checked, the winning bundle is re-verified and imported, and the callable is cached for every later call with that signature.

The entry point is called as candidate(module, *args, **kwargs). Passing the module is what lets one artifact serve every block in a stack — the kernel reads the parameters it needs from the module it was handed.

Trust

• Executable code is loaded only from FASTVIDEO_OPTIMIZATION_ARTIFACT_DIR, and only from bundles that resolve inside it.
• Every declared file is re-hashed immediately before the import, not merely at discovery.
• Undeclared files in a bundle are a hard rejection.
• Bundles are imported under a private fastvideo._artifacts.* name; sys.path is never modified.

Fallback

A missing match, a bad manifest, a tampered file, an untraceable module, a failed import or an exception raised by the candidate all fall back to native execution with a structured reason (no_artifact_for_input_signature, no_compatible_artifact, graph_identity_unavailable:*, artifact_load_failed:*, candidate_runtime_error:*, …). A candidate that raised once is demoted, not retried thousands of times.

Zero effect when disabled

With FASTVIDEO_OPTIMIZATION_ARTIFACT_DIR unset, attach_graph_dispatch returns None: no forward is patched, no graph is traced, no artifact code is read. A test asserts no instance attribute shadows the class method and that outputs are identical.

Diagnostics

Optional structured report (FASTVIDEO_OPTIMIZATION_ARTIFACT_DIAGNOSTICS) recording each scope, shape key, decision reason, artifact id, rejection codes and call counts, plus registry and runtime identity. Metadata only — a test asserts no tensor- or prompt-shaped content appears in it.

Testing

• 28 new CPU tests (fastvideo/tests/optimization/test_dispatch.py) using fake kernels and fake modules only. They cover the exit criteria directly: compatible artifact selected; fingerprint, dtype, shape, output-signature, architecture, torch/CUDA/Triton version, execution-mode and distributed-mode mismatches rejected; tampered kernel rejected before import; candidate exception falls back to native output; no artifact directory behaves exactly like current FastVideo.
• 60 passed across fastvideo/tests/optimization/ and tests/local_tests/optimizations/.
• Verified end to end against a bundle produced by MotionKernel's packager: hash-verified, matched on fingerprint + signature, loaded and dispatched.

Review notes

• fastvideo/optimization/fx_capture.py is deliberately untouched. The helpers dispatch needs are re-exported through a new identity.py; importing them there rather than duplicating them keeps the runtime fingerprint from silently diverging from the exported one. (Running the yapf hook against fx_capture.py reformats 269 unrelated lines, so this also keeps the diff reviewable.)
• The pre-commit mypy hook fails with FastVideo-v1-dispatch is not a valid Python package name. That is the checkout directory name and reproduces on untouched files such as fastvideo/logger.py. yapf, ruff and codespell pass.

Greptile Summary

Adds a generic artifact dispatch layer that lets packaged optimization kernels replace a model block's forward call without any model-specific code. When FASTVIDEO_OPTIMIZATION_ARTIFACT_DIR is unset the feature is completely inert.

• fastvideo/optimization/artifact.py — new: manifest parsing, SHA-256 file verification, ArtifactRegistry, RuntimeProfile, check_compatibility, and load_entry_point with path-confinement checks.
• fastvideo/optimization/dispatch.py — new: GraphDispatchSession that wraps repeated block stacks, decides once per (scope, shape) key, demotes failed candidates permanently, and writes structured diagnostics.
• fastvideo/optimization/fx_capture.py — adds four thin public wrappers so identity.py can re-use the canonical fingerprint implementation without importing private symbols.
• fastvideo/pipelines/composed_pipeline_base.py — wires attach_graph_dispatch / detach_graph_dispatch into the pipeline setup and close path.

Confidence Score: 5/5

Safe to merge. With FASTVIDEO_OPTIMIZATION_ARTIFACT_DIR unset the change is completely inert, and every fallback path returns native execution without propagating exceptions to the caller.

The dispatch path wraps every failure in broad exception handlers and falls back to native execution. Hash verification runs both at registry build time and immediately before exec_module, path confinement is enforced with resolve/strict=True, and undeclared files in a bundle cause a hard rejection. The only issues found are minor manifest-parsing edge cases well outside normal MotionKernel producer output.

Files Needing Attention: No files require special attention. The security-sensitive load_entry_point path in artifact.py is well-hardened.

Important Files Changed

Filename	Overview
fastvideo/optimization/artifact.py	New file: manifest parsing, bundle hashing/verification, ArtifactRegistry, RuntimeProfile, and trusted load_entry_point. Security model is sound — path traversal blocked by _resolve_inside, hash re-verified immediately before exec_module, undeclared files are a hard rejection.
fastvideo/optimization/dispatch.py	New file: GraphDispatchSession with fail-safe forward patching, one-shot decision per (scope, shape_key), permanent candidate demotion on exception, and structured diagnostics. No blocking issues found.
fastvideo/optimization/fx_capture.py	Adds four public dispatch-facing wrappers and yapf-style reformatting. capture_invocation_identity correctly creates a one-off FXCaptureSession exercising the same _regions_for tracing path.
fastvideo/optimization/identity.py	New 30-line thin re-export. Imports only the four new public symbols from fx_capture.py, resolving the previous review concern about private API coupling.
fastvideo/pipelines/composed_pipeline_base.py	Minimal integration: _dispatch_session initialized to None in init, attached after trace manager setup, detached in close() using the same getattr-with-default pattern as _trace_mgr.
fastvideo/tests/optimization/test_dispatch.py	28 CPU-only tests covering selection, all rejection reasons, tampering, import failures, and diagnostics metadata guarantees.
fastvideo/envs.py	Adds 8 new FASTVIDEO_OPTIMIZATION_ARTIFACT_* env vars following the existing pattern. No issues.

_{Reviews (2): Last reviewed commit: "[bugfix]: harden generic artifact dispat..." | Re-trigger Greptile}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c889eb99-8585-437f-a9ad-c623b6903c2d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}