[justinchuby]

Do not merge

Paused behind the design of record, PR #2010. This is the schema half; that PR
is the contract half. Coordinated against justinchuby/vision-batching-design
at 0ea8344a48d494b27740bf133ff0af57ecc50653, and docs/genai/ENCODER_BATCHING.md
at that SHA is authoritative wherever this branch and that doc disagree.

What this adds

A component may declare how many requests one invocation of it can absorb, and a
tensor may say which of its entries are real. Nothing here executes anything --
the runtime work is downstream. Every package that does not spell token_packed
parses unchanged, because absence of batch_capacity still means one request per
invocation; token_packed itself is reshaped and its old spelling is refused by
name, which the "Breaking change" section below states in full.

• WorkflowComponent.batch_capacity -- uniform_dimensions (shape symbols that
  must agree across the requests sharing an invocation) and budgets (bounds on
  what the invocation may materialize).
• TensorContract.padding -- a list of { dimension, valid_lengths } entries
  naming the value that says how much of a padded dimension is real.
• BatchLayout::TokenPacked { axis, levels } -- a flat payload plus a bounded
  chain of ownership levels, each { offsets, owner, extent }, innermost first.
• Vision content vocabulary for the companions themselves: pack_offsets,
  pack_owner, and the generic valid_lengths role.

Video is not a separate mechanism. A frame-to-clip-to-request chain is two
levels of the same ownership construct, and the fixtures cover both a temporally
padded encoder and a packed one.

Second review, resolved

1. extent is per level, not per layout. A chain may mix: the canonical
   video fixture produces its inner token-to-clip companions and preserves the
   caller's outer clip-to-row pair. An output level omitting extent is
   rejected; an input level declaring one is rejected too, since the runtime
   built those. preserved is checked positively -- the pair must belong to an
   input port of the same component and agree with it on both extent symbols.

2. A version gate that runs before typed deserialization. parse_metadata
   is a real entry point, and the loaders that used to call serde_yaml
   directly now call it -- schema_version.rs proves both the file path and the
   in-memory path go through it. Grammar is [v]major[.minor] with minor
   defaulting to 0, so absent, v1, 1, and 1.0 are one version. A document
   whose minor exceeds what the runtime supports is refused with its version as
   written, its normalized form, and the highest supported version.

   Deliberately stricter than crates/onnx-model-package/src/lib.rs:563-579,
   which parses a minor and then ignores it. §6.1 of the design justifies the
   divergence: without a gate, a v1.1 document meets deny_unknown_fields on an
   old core and fails with a message about a field name rather than a version.

3. uniform_dimensions names ordinary per-item symbols only -- never a
   port's flattened packed symbol, never an ownership level's unit count. Both
   of those are counts the scheduler chose, and pinning them would be a bound
   pretending to be a shape fact.

This revision

Corrections from the coordination round, each a rule that was right about the
wrong quantity.

• Budgets are group-rooted. The previous revision rejected a singleton
  budget only when its symbol was pinned. Pinning is not the property that makes
  a bound meaningless -- failing to reach the group is. patches alone counts
  patches per frame, the same number for one frame or a thousand, pinned or
  padded. dimensions is now a nesting path read outermost first, and its first
  symbol must be a count the scheduler chose. A per-item symbol may appear in
  later positions, where it multiplies a count into a footprint.
• A fixed frame count keeps the clip-to-row level. It drops the frame level
  only. FIXED_FRAME_VIDEO_ENCODER is [clips, frames, patches, features]
  packed over clips, frames an ordinary pinned dimension. A request-aligned
  alternative would pad the clip axis, which is the cost packing exists to avoid.
• SCHEMA_VERSION stays v1. Normalizing on read is what makes the
  spellings in the wild interchangeable; changing what writers stamp would
  rewrite bytes to say something no reader distinguishes. The comfyui golden
  document is byte-identical to main. v1.1 is what a batching document
  declares, 1.1 is an accepted synonym, and SchemaVersion displays with the
  v so an error names a version the way a document would write it. A present
  but non-string schema_version is refused by the gate rather than deferred.
• Padding names its length by name, not by role. An audio program points a
  padding entry at the frame_lengths it already emits. LENGTH_CONTENT_ROLES
  is informative only, and valid_frames / valid_samples left it -- those are
  counts a graph consumes, not statements about padding.
• Pair identity resolves both extents. Every port naming a companion pair
  must agree on the offsets extent and the owner extent, not merely name the
  same two values. Identity is the pair, never the level index: the video
  fixture names one pair at level 1 of the pixel port and level 0 of the pooled
  embedding port.
• The serving carve-out is narrow. A shared emitted value is admitted only
  when it is int64, carries the rank the reference demands, and is named as an
  offsets or owner of another emitted value's layout -- or as the
  valid_lengths of another emitted value's padding entry -- in the same
  workflow. The rank is read from the reference: offsets and owner maps are
  rank 1 by construction, while a length vector's rank is the number of axes
  outer to the padded one (rank == axis). No new BatchLayout variant.
  A declared owner is internal -- an input named as one may not be
  externally_suppliable, since invocation-global positions leak cross-request
  identity, while offsets stay suppliable because the runtime rebases them.

Code review, resolved

Three defects, each a rule reaching further than its reason.

• A shipped package did not expire. The rank-4 append rule refused the
  checked-in diffusion and diffusion_guided packages, which append a latent
  [batch, 4, height, width] along its final axis. They are correct and always
  were: the final axis is what the default meant, and they had no way to say so
  explicitly because nothing asked. The rule's reason is that a rank-4 media
  tensor makes that axis ambiguous, and a rank-4 media tensor is what v1.1
  introduced -- so the demand starts at BATCHING_SCHEMA_VERSION. An older
  document keeps the default it was written against; a document declaring v1.1
  names the axis; an axis outside the value's rank names nothing at any version
  and is still rejected.

  Version scoping means the validator has to be told the version, so
  validate_pipeline_spec now takes one. Deriving it from the document's fields
  would be the same fact stored twice, and defaulting it inside the validator
  would make strictness depend on which entry point a caller happened to use.
  Both fixtures are migrated to explicit axis: 3 regardless -- stating the axis
  the default already chose costs nothing and outlives the exemption.

  On attribution: the append-axis rule is a state-append rule of this crate, not
  an encoder-batching contract, and docs(metadata): design of record for generic component batching #2010 does not legislate it -- nothing here
  cites the design as its authority. What the design did adopt from this round
  is the general form of the split, now §6.1: a version may gate what a document
  must say, but it never gates what a document may say wrongly. A demand
  to state intent explicitly starts at the version that made the default
  ambiguous, because a document written earlier meant the default it was written
  against; range checks and every rule about a value a document did state stay
  unconditional, because relaxing those would let an older spelling assert
  something false rather than merely leave something unsaid. The two look alike
  in a validator and are opposites in effect, so validate_emit_axis now quotes
  the principle rather than restating the one rule.

• A padded output could hide the only account of its padding. The serving
  rule that every emitted rank>0 value declare a row correspondence admitted
  ownership offsets and owner maps, because those are shared by construction.
  A padded output's valid_lengths is shared for the same reason -- one entry
  per position outside the dimension it bounds -- and was rejected. The carve-out
  now names both and stays decidable from the declared outputs alone: an
  unrelated shared result is still a per-request answer with no way back to a
  request.

  The other half of that symmetry was missing too. validate_packed_emit_companions
  required a packed emit to publish the companions that split it; nothing
  required a padded emit to publish the lengths that read it. A caller holding
  trailing entries that mean nothing, with no way to learn how many, is the
  failure the padding contract exists to prevent -- and the schema deliberately
  refuses a payload-shaped validity mask as the alternative, so that vector is
  the only account there is. §4 rule 8 is now retitled for both halves -- a
  ragged emit publishes the account of its raggedness, and serving admits it --
  and matrix row 25 carried the four cases this branch tested at that round: a
  packed emit with its companions, a padded emit with its lengths, a padded emit
  withholding them (rejected), and an unrelated shared result (still
  rejected). Row 25 and this branch have both grown since; the round below
  records what the flat rank-1 reading cost and what replaced it.

  The three companions then differ on delivery, and the difference is now pinned
  by a test rather than left implicit. An owner map is invocation-global and is
  never delivered. Offsets are per-request but group-relative, so they are
  delivered rebased to the request's own start. A valid_lengths is already
  relative to the item it measures and means the same number in any group, so a
  request states its own and receives the slice indexing its own items -- nothing
  to rebase and no group position to leak. Only the owner rule constrains
  suppliability; the test exists so that a later attempt to unify the delivered
  companions with the internal one fails rather than passes quietly.

• A user-facing error was malformed. The unquoted-schema_version message
  was missing its line continuations and reached a reader with fourteen-space
  runs in the middle of two sentences.

Two extensions this branch proposed, since adopted

Both were carried past the doc deliberately, recorded here rather than assumed,
and both are now rules in the design of record at 0ea8344a4. They are stated
as rules with their own tests, not left as coverage that happens to exist.

1. The packed axis is 0 wherever token_packed appears, not only in a
   component that declares batch_capacity. The doc originally scoped the rule
   to capacity components; the scope was the bug. The justification it gives --
   a no-copy view is a contiguous element window
   (crates/onnx-genai-ort/src/value.rs:1526-1542) -- holds whenever a runtime
   splits a packed result per request, and the emit path rebases offsets and
   derives per-request owners with no capacity in sight. Under the old scope a
   strided packed emit was legal exactly where nothing had declared it could pay
   for one. Now §4 rule 2, decisions §10.5 / §10.6, matrix row 17.

2. A preprocessing-program companion carries the pack_offsets or
   pack_owner content role. Now §4 rule 4, with the scope made explicit:
   the requirement reaches only declarations that have a role. A program says
   what each of its outputs is, so one wiring some other plausible int64 rank-1
   vector into a levels entry is caught at load rather than at the first
   split; a companion the graph produces is an ONNX output port and has nowhere
   to carry a role, so an extent: produced level is not asked for something
   its half of the schema does not have. The validator was already scoped this
   way and a test now pins it.

   §3.3 records why padding deliberately does not get the same treatment, so
   the two are not read as an inconsistency: length vectors already have
   established modality spellings (frame_lengths, sample_lengths) that
   programs legitimately emit, so no single role could be demanded without
   breaking a program that predates the generic name, while the two ownership
   roles are new and reject nothing that exists. Both rules resolve the
   reference by name; only this one constrains what the referenced
   declaration may claim to be.

Code review, round two: companions are not all rank one

The serving carve-out asked whether an emitted shared value was named as some
declared output's companion and whether it was int64 rank 1. That is right
for an ownership offsets or owner map, which are rank 1 by construction, and
wrong for a validity length. A length has one entry per position of the axes
outer to the dimension it bounds, so its rank is that dimension's axis index:
rank 1 for a padded axis 1, rank 2 for a padded axis 2. A correct rank-2 length
was refused as "a per-request value without a declared batch_layout" -- advice
that, if followed, would have made it wrong.

The bare name set is now a map from companion name to what the declarations
naming it require: the role, and the rank that role implies at that site. The
carve-out stays narrow -- int64, referenced by a declared output contract, and
at the exact rank that reference demands.

The design doc adopted the correction rather than the code working around it.
#2010 now words the carve-out as int64 at the rank that reference demands,
and records why the flat form was wrong: a refusal under it necessarily advised
request_aligned, which is the one layout a companion MUST NOT declare, so
following the doc would have made a correct package wrong. The three judgement
calls below are normative there now.

• A name may be claimed by several declarations, so expectations are collected
  rather than overwritten and a value satisfies the carve-out by matching any one
  of them. Two declarations demanding different ranks of one value is a
  contradiction, but it is validate_padding's to report against the declaration
  that is wrong -- not this rule's to report as a missing row axis.
• Where a padded dimension does not resolve to an axis the expectation carries no
  rank, because a second complaint about a rank nothing could compute sends a
  reader to the wrong line.
• A value named as a companion but shaped like something else now gets that as
  its error, naming the role and rank expected of it. The generic message told
  its author to declare a row axis, which is precisely what a companion must not
  do.

Both companion obligations now require the companion to be emitted, not merely
declared. Declaring an output and writing it are different facts and only the
second delivers anything: a workflow that declares its lengths and never emits
them satisfies the letter of "publishes them" while handing the caller a padded
tensor and an empty vector, which is the failure the obligation exists to
prevent. The same hole existed on the packing side and is closed with it -- one
rule, two spellings. The check is whole-workflow rather than path-sensitive,
deliberately: whether two emits reach a caller together depends on a branch
predicate, and this crate does not evaluate predicates, so a path-sensitive rule
would either reject correct packages whose companion is written in a sibling
branch or claim a precision it does not have. "Somewhere in the declared steps"
is what can be decided soundly, and it catches the case that occurs.

One narrowing found while aligning with the design's wording. The carve-out
asked that the naming output be declared; the companion obligation asks that a
companion be emitted. Those are two answers to one question, and the gap is
exploitable -- a package could carry any shared vector past the serving rule by
declaring a padded output beside it and never emitting one. An expectation now
carries the output that claims it and whether any step writes that output, and
only a written claim admits anything. This is also what the design says: a
companion is admitted when named by another emitted value's layout or padding
entry. A value left out by this is told so, rather than told to declare a row
axis -- the defect is the payload's missing emit, not the companion.

Seven tests over two new fixtures -- a request_aligned and a token_packed
serving output, each padded on two dimensions with a rank-1 length for axis 1 and
a rank-2 length for axis 2: valid publication of both shapes; a packed result
padded on the axes it does not pack, publishing ownership and lengths together at
three different ranks; a length declared at rank 1 for a padded axis 2, rejected
by role and rank; a declared-but-never-emitted length; a declared-but-never-
emitted owner map; and an unrelated shared rank-2 result, still rejected.

Breaking change: the flat token_packed spelling

token_packed on main carries offsets and owner directly on the layout,
which can say only that items sit in request rows. This PR replaces that with
levels, an ownership chain, because an item can itself be a group -- frames in
clips in rows -- and one pair cannot say that. A document written against the
flat spelling does not load, at any declared version.

This is deliberate and unshimmed. A one-level chain is exactly what the flat
pair meant, so a translation would be expressible; it is refused instead because
the schema is pre-release and rule 3 is to reshape completely rather
than keep a second spelling alive, and because no in-tree package uses
token_packed at all -- nothing ships that a translation would rescue.

What a clean break owes is the error, and that debt was unpaid until now. serde
alone reported unknown field offsets, expected axisorlevels``, which
reads like a typo and stops at the contract rather than the layout, so a reader
goes hunting for a misspelling instead of finding a migration.
parser::reject_flat_token_packed recognizes the retired shape in the preparse
-- the same place and the same discipline as `reject_retired_model_io`, which
never produces a value and only ever produces a refusal -- and reports the
containing path, the replacement to write, and that nothing will convert the
document for it:

the `token_packed` batch layout at
`pipeline.workflow.inputs.image_pixels.contract.batch_layout` declares `offsets`
and `owner` directly, which is the retired flat spelling of ownership. A packed
axis now declares `levels`, an ownership chain innermost first, because an item
can itself be a group. The flat pair is the one-level case: replace `offsets:
<o>, owner: <w>` with `levels: [{ offsets: <o>, owner: <w> }]`, and add an outer
entry if the items are themselves grouped. An emitted level also states
`extent`. This spelling is not read, and no document is converted for you.

It runs after the version gate. The flat pair is a reshape inside the v1
line, so refusing it presumes the document belongs to that line; a document
declaring a version this build cannot read is refused for that instead, because a
reader that has never seen v2 has no standing to say what a spelling means there.
A test pins the order rather than the outcome: both orders reject a v2.0
document carrying the flat pair, and only the message distinguishes them, so
a_document_from_a_version_this_build_cannot_read_is_refused_for_that asserts
the migration text is absent and the version is named.

A noted inconsistency, deliberately not fixed here. reject_retired_model_io
runs before the gate; this one runs after. I am not aligning them in this PR.
Whether pre-gate is wrong for that recognizer depends on what its message
asserts -- if the shape it refuses was retired across the major boundary rather
than inside a line, running first may be correct for it -- and that is a fact to
be established by reading it, not inherited from this one. Reordering a shipped
refusal path is a behavioural change that deserves a PR whose evidence is about
that path, rather than arriving as a side effect of adding a second recognizer.

Two compatibility claims were overstated and are corrected rather than left to
be discovered. "A package that uses nothing new keeps loading" is a statement
about fields that were added; it was written as though it covered everything,
and a flat-token_packed document uses nothing new and no longer loads. The
schema_version field doc and the schema_version.rs module doc now say so and
point at the refusal. The published schema needed no change -- token_packed
already requires levels and sets additionalProperties: false, so a producer
validating against the schema alone is told the same thing the loader tells it --
but that agreement now has a test rather than holding by accident, mirroring the
existing model.io requirement that the two readers not disagree about what is
loadable.

Seven tests in encoder_batching.rs, one in schema_sync.rs: the refusal names
the shape, the path, and the finality; it fires at v1, "1.0", v1.0 and
v1.1 alike; a half-migrated layout keeping one of the two keys is still
explained rather than dropped back to the unknown-field error; the migrated
document the error prints actually loads; a value merely named offsets is not
mistaken for a retired layout; a v2.0 document is refused for its version and
not lectured about a v1 migration; and the published schema publishes neither
retired key.

A padded output has one account of how much of it is real

An emit may carry a valid_length, and an output contract may declare
padding. Both say how much of a result is real. Nothing reconciles them, and
a document setting both on the same value is now refused at load.

They are not two views of one fact. valid_length truncates what a step writes
and is invisible in the contract -- a caller reading the metadata cannot see it.
A padding entry is part of what the caller reads and names a length vector
that rule 8 requires the workflow to publish. So a document that sets both can
ship a tensor whose published lengths describe a shape the emit did not
produce, and the caller holds the account the emit is free to contradict. Two
answers to one question, which is the same defect RULES.md rule 10 names.

padding.valid_lengths is authoritative, and the error says so, because
"these two disagree" is not actionable until the reader knows which one to
delete. It names the emit's valid_length, the output, and every padded
dimension with the length vector bounding it:

<step path> emits 'image_features' into output 'features' with valid_length
'accepted_len', but 'features' declares padding whose valid_lengths
'tile_lengths' on dimension 'max_tiles' already says how much of it is real; a
padded output has one account of its raggedness and it is the declared padding,
which is the only one the caller receives, so drop the emit's valid_length

token_packed needs no case of its own and gets none. A packed layout declares
no request axis, so an emit-level length into one is already refused by the
existing rule -- ragged emission with no row axis to be ragged along. The two
rules answer different questions, so a packed and padded output hears from
both, which is correct rather than redundant.

Nor is this version-scoped, and it does not need to be. padding is itself a
1.1 field, so any document able to express the contradiction has already been
required to declare v1.1 by the existing feature detector; a v1 document
cannot reach this rule. And it is a rule about what a document did state, not
a demand that it state something new -- the half of the validate_emit_axis
split that stays unconditional at every version.

Three tests, one fixture pair: the rejection, the same workflow with the
emit-level length removed accepted as its control (guarded so it cannot pass
vacuously), and the packed case still refused for the older reason (guarded with
assert_ne! so a non-matching edit cannot make it vacuous either). The
rejection was verified by mutation -- disabling the rule fails it.

Not in scope

Runtime execution, scheduling, and admission. Load-time validation checks the
graph and the contracts; whether a particular tensor's offsets are monotonic is
an invocation-time check on the device that holds them, and this branch does not
force a copy to look.

Verification

• cargo test -p onnx-genai-metadata -- 342 across 25 binaries (encoder_batching 102, schema_version 13, schema_sync 3).
• cargo test -p onnx-genai-engine --test onnx_genai_workflow_conformance -- 15/15,
  including mobius_euler_diffusion_workflow_executes_complete_path,
  mobius_euler_diffusion_workflow_executes_batched,
  mobius_guided_diffusion_workflow_executes_complete_path, and
  mobius_video_diffusion_workflow_publishes_causal_temporal_chunks.
• validate_metadata binary on tests/fixtures/onnx_genai_workflows/{diffusion,diffusion_guided,video} -- all valid.
• cargo test -p onnx-genai-genai-config -p onnx-genai-preprocess -p onnx-genai-comfyui-config, cargo test -p onnx-genai-engine --lib (494), cargo check -p onnx-genai-server --all-targets.
• schema/inference_metadata.schema.json regenerated and in sync.
• cargo fmt --all --check, cargo clippy -p onnx-genai-metadata --all-targets -- -D warnings.

[codecov]

Codecov Report

❌ Patch coverage is 87.92453% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.27%. Comparing base (54625db) to head (9151a37).
⚠️ Report is 32 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/onnx-genai-metadata/src/parser.rs	85.39%	8 Missing and 5 partials ⚠️
crates/onnx-genai-metadata/src/schema/ir.rs	75.00%	10 Missing ⚠️
crates/onnx-genai-preprocess/src/image/program.rs	0.00%	6 Missing ⚠️
crates/onnx-genai-comfyui-config/src/lib.rs	50.00%	0 Missing and 1 partial ⚠️
...rates/onnx-genai-genai-config/src/compatibility.rs	0.00%	1 Missing ⚠️
crates/onnx-genai-metadata/src/version.rs	99.05%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2009      +/-   ##
==========================================
+ Coverage   80.31%   81.27%   +0.96%     
==========================================
  Files         409      426      +17     
  Lines      190562   211589   +21027     
  Branches   190562   211589   +21027     
==========================================
+ Hits       153046   171969   +18923     
- Misses      32082    33940    +1858     
- Partials     5434     5680     +246     

Flag	Coverage Δ
cli-ort-linux	72.51% <ø> (?)
cli-ort-windows	72.01% <ø> (?)
mlas	85.33% <ø> (?)
offline	81.43% <87.92%> (+1.12%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
crates/onnx-genai-comfyui-config/src/lower.rs	98.78% <100.00%> (+<0.01%)	⬆️
crates/onnx-genai-metadata/src/decoder_workflow.rs	95.27% <100.00%> (+0.04%)	⬆️
crates/onnx-genai-metadata/src/lib.rs	95.23% <ø> (ø)
crates/onnx-genai-metadata/src/schema/mod.rs	81.39% <100.00%> (ø)
crates/onnx-genai-metadata/src/validation.rs	78.35% <ø> (+7.22%)	⬆️
crates/onnx-genai-comfyui-config/src/lib.rs	92.74% <50.00%> (+0.05%)	⬆️
...rates/onnx-genai-genai-config/src/compatibility.rs	60.00% <0.00%> (-0.12%)	⬇️
crates/onnx-genai-metadata/src/version.rs	99.05% <99.05%> (ø)
crates/onnx-genai-preprocess/src/image/program.rs	71.88% <0.00%> (ø)
crates/onnx-genai-metadata/src/schema/ir.rs	86.41% <75.00%> (-11.15%)	⬇️
... and 1 more

... and 66 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.