Simplify composite ONNX GenAI metadata

.github/workflows/main.yml

@@ -15,6 +15,68 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  onnx-genai-metadata:
+    name: ONNX GenAI metadata
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v7
+    - uses: actions/checkout@v7
+      with:
+        repository: justinchuby/onnx-genai
+        # Pinned by SHA so the producer/runtime contract under test is
+        # reproducible. PR #828 is maintained by merging main rather than
+        # rebasing, so this commit remains reachable from its branch history.
+        # When bumping, verify reachability with `git merge-base --is-ancestor
+        # <sha> <branch-tip>`.
+        ref: 509cd4e9c4471f4cbc59fe44b47168f0ae128fe3
+        path: validation/onnx-genai
+    - uses: actions/setup-python@v7
+      with:
+        python-version: "3.12"
+    - name: Install dependencies
+      run: |
+        pip install torch --index-url https://download.pytorch.org/whl/cpu
+        pip install -r requirements/ci/requirements.txt
+        pip install onnxruntime==1.28.0
+        pip install -e '.[testing]'
+    - name: Generate representative packages
+      run: |
+        PYTHONPATH=src python tests/generate_onnx_genai_validation_packages.py \
+          validation/generated
+        PYTHONPATH=src python tests/compare_onnx_genai_validation_packages.py \
+          tests/fixtures/onnx_genai_workflows validation/generated
+    - name: Validate package semantics
+      run: |
+        # Report every invalid package, not just the first: the job runs under
+        # `bash -e`, so an unguarded failure inside the loop would abort it and
+        # hide the remaining results.
+        failed=""
+        # The generated tree, not the committed one: validation resolves each
+        # component's artifact from disk, and the graphs are generated rather
+        # than committed.  The step above has already proven the two trees
+        # carry the same metadata.
+        for package in validation/generated/*; do
+          [ -f "$package/inference_metadata.yaml" ] || continue
+          cargo run --quiet \
+            --manifest-path validation/onnx-genai/Cargo.toml \
+            -p onnx-genai-metadata --bin validate_metadata -- "$package" \
+            || failed="$failed $package"
+        done
+        if [ -n "$failed" ]; then
+          echo "Invalid packages:$failed"
+          exit 1
+        fi
+    - name: Execute all workflow packages
+      run: |
+        cp tests/onnx_genai_workflow_conformance.rs \
+          validation/onnx-genai/crates/onnx-genai-engine/tests/mobius_workflow_conformance.rs
+        ORT_LIB="$(python -c \
+          'import onnxruntime, pathlib; print(next((pathlib.Path(onnxruntime.__file__).parent / "capi").glob("libonnxruntime.so*")))')"
+        MOBIUS_WORKFLOW_CONFORMANCE_DIR="$PWD/validation/generated" \
+          ONNX_GENAI_ORT_LIB="$ORT_LIB" \
+          cargo test --manifest-path validation/onnx-genai/Cargo.toml \
+            -p onnx-genai-engine --test mobius_workflow_conformance -- --nocapture
+
   lint:
     name: Lint
     runs-on: ubuntu-latest

.gitignore

@@ -213,6 +213,19 @@ __marimo__/
 *.onnx.data
 *.gguf
 
+# Generated conformance-package artifacts.  The metadata beside them is the
+# contract under review and is committed; the graphs and adapter weights are a
+# deterministic function of
+# tests/generate_onnx_genai_validation_packages.py, so committing them would
+# store megabytes of bytes no reviewer reads.  CI regenerates and validates
+# them; tests get them from the materialized_workflow_packages fixture.
+tests/fixtures/onnx_genai_workflows/**/*.safetensors
+
+# Where CI and the test fixture materialize those packages in full.  Nothing
+# here is reviewable input: it is the regenerated output the validate and
+# conformance steps consume.
+validation/
+
 # Common test dirs
 output/**
 cache_dir/**

CHANGELOG.md

@@ -7,6 +7,144 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- An exported graph is no longer transcribed into its own workflow component.
+  A component backed by a shipped `.onnx` file now declares only `ports.roles`;
+  the artifact answers every question about which ports exist and what shape
+  they have, and the runtime resolves them against the live session. The
+  removed block was a second statement of the same ABI with nothing keeping the
+  two in agreement — the same defect as `model.io`, one level down. Package
+  validation and runtime conformance both stay at 11/11 against the pinned ONNX
+  GenAI branch, and the contract tests now resolve every role, invocation
+  binding and state pair against the graph itself rather than against the
+  metadata's agreement with a copy of itself, which is a strictly stronger
+  check.
+
+  Policy graphs keep their contracts, and that boundary was measured rather
+  than assumed: a workflow value inherits its dtype, rank and request axis from
+  the port that produced it, so dropping them left row-wise emits untyped and
+  made 4 of the 11 packages invalid. Those contracts type the workflow's own
+  dataflow; they do not describe an external interface.
+
+- Deep decoders are now covered where the cache layer annotation actually
+  matters. Every metadata package built in the test suite had two layers, and
+  below ten a cell label sorts identically whether ordered lexicographically,
+  numerically or by insertion — so a `layer` derived from a cell's position
+  rather than parsed from its port name would have passed every assertion while
+  transposing caches on any real model. `canonical_workflow_contract_test` now
+  builds twelve-layer dynamic, static-cache and hybrid decoders and pins that
+  the declared layer restates the port name, that ordering by it recovers the
+  buffer lists, and that a hybrid's alternating groups own layers their cells'
+  positions never equal. A producer that dropped the parse leaves the 101
+  pre-existing assertions green and fails seven of these.
+
+- Every component a task builds now declares an optimization role. Qwen3-TTS's
+  four loop-wiring graphs (`code_predictor_prefill`,
+  `code_predictor_step_embedder`, `code_predictor_indices`, `talker_text_step`)
+  were absent from `TTSTask.model_roles`, so `build_from_module` fell back to
+  the `"decoder"` role and offered them the GQA / QKV-packing passes meant for
+  attention stacks, and `inspect_components` under-reported the package by four
+  components. They now declare a `"glue"` role: a parameter-free graph that
+  reads every tensor it uses from a graph input. `arch_validation_test` fails
+  any task that builds a component it does not declare, and a network-free unit
+  test pins the same invariant for Qwen3-TTS.
+
+### One canonical serialized representation
+
+#### Changed
+
+- **`pipeline.workflow` is now the only place a package describes its graph
+  ABI.** No export emits `model.io`, including a bare single-file decoder: that
+  case is a one-component workflow, not a different kind of document. `model`
+  keeps package-wide geometry and capabilities and nothing else. Two writable
+  statements of one fact are a defect whatever they contain — nothing forces
+  them to agree, and a reader of either never learns the other exists — so a
+  runtime that wants an optimized single-graph path derives it by lowering the
+  workflow instead. Verified end to end: the ONNX GenAI runtime executes the
+  fixed-capacity decode path from the workflow alone, with no `model.io` in the
+  package.
+
+#### Added
+
+- An ONNX component that ships an artifact declares no port contracts. The
+  `.onnx` file travels inside the package and is authoritative for which ports
+  exist and what each one's dtype, rank and shape is, so transcribing that into
+  YAML would be a second writable statement of one fact — the very thing this
+  section removes — sitting one level below `model.io` rather than beside it.
+  The runtime resolves ports against the live session, which catches a name the
+  graph does not expose instead of agreeing with a stale echo of it. A
+  producer-synthesized policy graph is the exception and states its contracts,
+  because a workflow value takes its dtype, rank and request axis from the port
+  that produced it: those contracts are the dataflow's type annotations, not a
+  description of an external interface.
+- Every ONNX component declares `ports.roles`: what it *does* with a value bound
+  to a port. An invocation records which SSA value reaches a port, not whether
+  that port is tokens, a mask or logits. Mobius mints these port names in its own
+  task builders, so it states the mapping (`input_ids`→`token_ids`,
+  `inputs_embeds`, `attention_mask`, `position_ids`, `logits`,
+  `last_hidden_state`→`hidden_states`, `encoder_hidden_states`,
+  `audio_features`) rather than inferring it. A port outside that vocabulary
+  carries no role.
+- State port aliases declare `role` (`key`/`value`) and `layer`. A layer's key
+  and value buffers are the same dtype and shape, and a cell's label sorts
+  lexicographically so `cache_10` precedes `cache_2` — pairing per-layer buffers
+  positionally would silently transpose two layers' caches. Both fields are
+  emitted together or not at all, so a recurrent or convolution cache is never
+  given a fabricated index.
+- `IndexedScatter.kv_length_ports` names the port carrying the graph-visible
+  valid length, beside the existing `write_indices_ports`. The two control
+  vectors are both rank-1 integers and are therefore indistinguishable by shape;
+  with both named, the whole fixed-capacity ABI is recoverable from the workflow.
+- `tests/canonical_workflow_contract_test.py` pins the invariant. It asks one
+  set of shape-agnostic questions of dynamic, static-cache, FP8, heterogeneous
+  and composite packages — and of all 11 checked-in fixtures — so a future
+  feature cannot grow its own top-level block while every feature-specific test
+  keeps passing.
+
+### Fixed-capacity (static) KV cache and FP8 KV cache metadata
+
+#### Added
+
+- `--features static-cache` now produces onnx-genai metadata instead of being
+  refused. The producer publishes the write cursor (`write_indices`), the valid
+  length (`nonpad_kv_seqlen`), the fixed-capacity buffer contracts, the
+  per-layer input/output pairs, and an `indexed_scatter` state-service update
+  discipline naming the cursor, the capacity and the per-component port that
+  carries it. The buffers are declared as `recurrence: {kind: invariant}` loop
+  cells and the capacity as a `package.cache_capacity` literal workflow input.
+  Nothing dispatches on model name; the ports are read from the graph.
+- Heterogeneous caches keep their own disciplines. Gemma 4's sliding layers stay
+  on a growing rank-4 BNSH cache while its full-attention layers use rank-3
+  fixed-capacity buffers, and only the layers that own a buffer bind ports in a
+  state group — its KV-shared suffix owns none.
+- A `static_cache` package joined the checked-in onnx-genai conformance
+  fixtures, so the engine exercises the fixed-capacity carry and the write
+  cursor rather than only the growing-tensor path.
+
+#### Fixed
+
+- Gemma 4's shared-KV fallback pinned a 4-D BNSH shape onto *any* borrowed KV
+  tensor whose rank was not 4. A static-cache source hands over a fully known
+  rank-3 `[batch, capacity, kv_hidden]` buffer, so this overwrote a correct
+  shape with a wrong one — corrupting the declared shape of
+  `updated_key_cache.N` and defeating the rank-3 static-source test further
+  down, which would then have transposed a rank-3 tensor as BNSH. The fallback
+  now only supplies a shape when there is none.
+- Gemma 4's vision-language decoder dropped `attention_mask` whenever the export
+  was static, but a Gemma 4 decoder is only *partly* static: its sliding layers
+  keep a dynamic cache and build their bias from that mask. The hybrid decoder
+  therefore lost all padding information. Both builders now apply one rule — a
+  mask exists exactly when some layer still has a dynamic cache — so a fully
+  static decoder carries no unused port and a hybrid one keeps its mask.
+- `--features fp8-kv-cache` no longer silently produces a float16 cache. The
+  gate only tested whether GQA fusion was *expected*; the pass now reports how
+  many caches it converted and the build fails when the answer is zero, naming
+  the reason: FP8 KV storage needs an attention operator with `k_scale`/
+  `v_scale` inputs, which a `TensorScatter` + `ai.onnx` `Attention` static-cache
+  graph does not have.
+
+
 ### Qwen3.5/3.6-MoE mixed float/quantized decoder (Olive checkpoints)
 
 #### Fixed

benchmarks/README.md

@@ -0,0 +1,36 @@
+# Muse workflow benchmark
+
+`muse_workflow_h200.json` is the shared workload for a paired native and
+metadata-workflow benchmark of the published Muse Glimmer INT4 package. Both
+paths use the exact 68 token IDs in `muse_prompt_ids.json`, greedy parameters,
+token budget, warmups, and steady-decode window. Passing token IDs avoids a
+tokenizer adding another beginning-of-text token to the already rendered prompt.
+Both runners set `ORT_ENABLE_CUDNN_FLASH_ATTENTION=0`; this matches the native
+baseline and avoids comparing different GQA attention kernels.
+`request_max_length` is prompt tokens plus new tokens (68 + 128 = 196);
+`model_max_context` is the independent 131072-token artifact admission ceiling.
+For the text-only VLM path, omit `request.image`. The runtime initializes
+`request.image_present=false`, and the false branch supplies empty image features.
+
+Run the native ORT GenAI path:
+
+```bash
+python scripts/benchmark_muse_native.py \
+  --model artifacts/muse-int4-package \
+  --output artifacts/muse-int4-package/native-benchmark.json
+```
+
+Run the ONNX GenAI workflow path with the `profile_native` binary built from
+the schema/runtime revision named in the JSON config:
+
+```bash
+python scripts/benchmark_muse_workflow.py \
+  --model artifacts/muse-int4-package \
+  --runner path/to/profile_native \
+  --output artifacts/muse-int4-package/workflow-benchmark.json
+```
+
+The workflow runner must support `--pipeline --backend ort --ep cuda`,
+`--prompt-ids`, and an optional `--image` request binding. The text-only workload
+intentionally leaves the image unset so results remain comparable to the
+published 61.76 tok/s baseline.

benchmarks/muse_568457_release_evidence.json

@@ -0,0 +1,58 @@
+{
+  "kind": "workflow_release_diagnostic",
+  "producer_commit": "80acfc069f0959f9e6580785fad3172bcc4cc0aa",
+  "runtime_source_head": "568457045ea003e787816995a380bcd9d7443169",
+  "runner_sha256": "fad10c7c8735c56e42acdfc092c4c6c327090c50de823efc45d4f3309b2d4aa9",
+  "overlay_manifest_sha256": "fd77589ffb9333d69efe78909b7f4a489da1071a35affb49b243e87a76330c6a",
+  "metadata_sha256": "8727cb6ab44ff65a4e74b6281c5af9eadba336483f5fa1e6033996c3b99fcced",
+  "decoder_state_initializer_sha256": "77e4eae0e35cc618214476e0776af3c1b7930862924f431edb62724cadb97af7",
+  "workload": {
+    "prompt_tokens": 68,
+    "generated_tokens": 128,
+    "warmups": 1,
+    "runs": 3,
+    "decode_skip": 8,
+    "stop_on_eos": false,
+    "image": null
+  },
+  "metrics": {
+    "ttft_ms": 67.512,
+    "decode_ms_per_token": 29.168,
+    "throughput_tok_s": 34.28,
+    "native_ttft_ms": 49.02172100264579,
+    "native_throughput_tok_s": 63.36527373646786,
+    "throughput_ratio": 0.5409903244885887
+  },
+  "diagnostics": {
+    "captures": 1,
+    "replays": 510,
+    "synchronizations": 2580,
+    "h2d_calls": 1556,
+    "h2d_bytes": 413802656,
+    "d2h_calls": 512,
+    "d2h_bytes": 4096,
+    "d2d_calls": 3068,
+    "d2d_bytes": 17376,
+    "island_elapsed_ms": 2974.922
+  },
+  "token_parity": {
+    "exact": false,
+    "first_difference": {
+      "index": 38,
+      "runtime": 4243,
+      "native": 33386
+    },
+    "runtime_count": 128,
+    "native_count": 128
+  },
+  "gate": {
+    "required_throughput_ratio": 0.99,
+    "correctness": false,
+    "paired_performance": false,
+    "upload_allowed": false
+  },
+  "notes": [
+    "The decoder remained outside the captured policy island.",
+    "This exact prompt-ID runtime still materialized decoder logits through host memory."
+  ]
+}