docs(metadata): design of record for generic component batching

[justinchuby]

Generic encoder batching — metadata design of record

Docs only. No code, no schema, no fixtures. Adds
docs/genai/ENCODER_BATCHING.md as the design
of record and mirrors the normative parts into
docs/genai/INFERENCE_METADATA_DECISIONS.md
(§10.4–§10.6, §15), docs/architecture/DESIGN.md, and the docs index.

Motivated by image and video encoders; nothing in the contracts is
modality-specific. Contracts carry shape symbols, bounds, lengths, and
ownership levels; a modality vocabulary only produces the semantic values those
contracts point at, so audio windows and text segments reach the same path with
no new concept and no model-family boolean.

Status: the metadata half of this design has shipped

#2009 merged as 0448f2bc6 while this PR was open, landing phases P1 and P2:
batch_capacity, padding, the levels ownership chain, the three content
roles, the schema_version gate, and the load-time validators for all of them
(crates/onnx-genai-metadata/tests/encoder_batching.rs, 104 tests). The latest
commit here rewrites the document's status framing so it stops describing shipped
fields as missing, and re-pins the citations the merge moved. The runtime half
is untouched — nothing groups, nothing packs, no program produces the
companions — so a package can now declare a batched encoder that no runtime
will honour. That asymmetry is what §6 already requires to be safe: declaring a
capacity is inert until something reads it, and a runtime that declines to group
is always correct.

Requirement keywords are therefore in force at load and describe runtime
behaviour that is not yet implemented. Still do not merge until the design is
accepted — this is the design of record, not a report on the implementation.

The gap this design was written against

The preprocessing tensor vocabulary existed, but component-level batching
capability and a usable TokenPacked runtime did not. BatchLayout::TokenPacked
named offsets/owner values that no declared program could produce;
WorkflowComponent had no capacity surface; validation of packed values was one
serving-emit rule; the interpreter honors only Shared and RequestAligned;
native batch > 1 vision is a reported crash. Video is expressible on the output
side and absent on the encoder input side. §2 preserves these observations in the
past tense with a Since #2009 note per subsection, because the reason a field
exists is not recoverable from the field.

The surface

Addition	What it says	Absent means
WorkflowComponent.batch_capacity	uniform_dimensions (symbols items must agree on) + budgets (materialized-footprint bounds, keyed by shape symbol)	one request row per invocation — today's behavior
TensorContract.padding	list of { dimension, valid_lengths } linking a padded dimension to its per-item length companion	value carries no padding; a runtime MUST NOT introduce any
TokenPacked.levels	ordered { offsets, owner } chain over one physically packed axis (axis: 0), innermost first, plus extent: preserved | produced per level on outputs	flat single-level packing
pack_offsets, pack_owner, valid_lengths content roles	level-agnostic producer roles so a declared program can emit the ownership chain and per-item lengths	no declared producer — today's gap

Ownership split is unchanged in shape: metadata describes, the preprocessor
produces, the scheduler groups, the interpreter executes and splits,
and ORT and native answer capability independently through one seam.
Fail-closed throughout: declining to group is always safe; grouping without
honoring a declared length or level is forbidden; a runtime never fabricates
padding, invents companions, or reconciles two items by changing them.

Phasing P0–P7 and a 28-row E2E acceptance matrix (non-batchable, padded,
variable size/count, packed ownership, nested video ownership, multi-request,
ORT/native parity, concurrency, and grouped-versus-sequential performance
reported for images and video separately) are in §8 and §9.

---

Second review (d8aac60c) — 3 blockers + notes, all resolved in 2daeb83f

#	Blocker	Resolution
BL1	packed_extent was value-wide	Moved onto each ownership level (levels: [{ offsets, owner, extent }]). Canonical media_tokens marks the inner token level produced and the outer clip→row level preserved; input levels carry no extent. Grammar, complete YAML, the worked-outputs table, §4 rule 5, decisions §10.6, and matrix row 24 all rewritten per level. A value-wide flag is shown to be unvalidatable for the mixed chain.
BL2	Version gate grammar unspecified	Grammar stated exactly: [v]major[.minor], minor defaults to 0, so absent / v1 / 1.0 all normalize to v1.0 (14 / 19 / 6 of the 39 in-tree inference_metadata.yaml files). New batching documents emit v1.1. The gate rejects pre-deserialization on major mismatch and on a minor above the runtime's — deliberately stricter than onnx-model-package, which parses <major>.<minor> and ignores the minor (lib.rs:563-579); the divergence is justified from deny_unknown_fields and recorded. Matrix row 23 now requires existing fixture bytes and version strings unchanged, and conditional emission requires v1.1 when new fields are present.
BL3	uniform_dimensions / budget rule incoherent	uniform_dimensions names true per-item ordinary dimensions only — never the flattened packed symbol, never a level's unit-count symbol (new rule 2, since both count the group the scheduler assembled). Fixed-frame video drops the frames→clips level and pins frames as an ordinary per-clip dimension (§3.4 variants table). "Pinned or budgeted, never both" is withdrawn: budgets are nesting paths read outermost-first and must be group-rooted, so a pinned symbol carries no singleton entry but does participate in composed footprint entries ([frames, patches]), because a pinned symbol is equal within a group and still varies between groups.

Review notes:

• valid_lengths is a new generic role, not an existing audio one. The audio
  vocabulary is waveform, features, audio_features, valid_frames,
  valid_samples, sample_lengths, frame_lengths, validity_mask
  (schema/mod.rs:350-365) — there is no valid_lengths. The earlier claim is
  withdrawn, and a coexistence table states how the modality-specific spellings
  keep working (a padding entry references its length value by name).
• Cross-port consistency is keyed on companion-pair identity, not level
  index — { clip_offsets, clip_owner } is level 1 of pixel_values and level
  0 of clip_embeddings, and an index-keyed rule would reject that correct
  package (§4 rule 6).
• A declared owner output is internal: it must be declared so the workflow
  validates, and is never delivered; per-request owners are derived from the
  rebased offsets (§4 rule 8, decisions §10.6).
• Video table variants now separate padded-vs-pinned resolution and
  variable-vs-fixed frame count explicitly, with a matching matrix row 11.
• Generator count corrected: 26 scripts/build_tiny_*.py generators feeding
  19 workflow fixture directories (was "~40").
• Vocabulary citations re-pinned to their exact blocks (mod.rs:296-309
  image, 350-365 audio, 47-52 / 53-54 schema_version).

First review — 8 blockers + N1–N6, resolved in d8aac60c

One physically flattened packed axis with a bounded ownership chain (no two
physical packed axes); the real schema-version migration mechanism instead of an
ignore-unknown claim; symbol-keyed uniform_dimensions/budgets instead of
component-global integers; a declared output-side ragged producer; a serving
carve-out for referenced companions; request row axis separated from packed item
axis with compact(selection) lifted through owner maps; budgets bound to
materialized footprint; a native readiness gate that is per
(component, operator class, provider) and retains the real CNN crash guard.
N1–N6: lengths instead of a mask, exact companion shapes, level extents,
load-time versus invocation checks, axis: 0 for zero-copy aliasing, and no
hidden device→host validation transfer — plus request_expanded semantics and
zero-item behavior.

Verification

• Docs only: git diff --stat origin/main...HEAD touches four .md files.
• git diff --check clean; markdown tables column-checked.
• Every intra-repo link and heading anchor resolved by a checker script (no
  broken links in the changed files).
• Every path:line citation re-verified against the tree at this SHA.

Rebase onto d60e2072 (#2011)

#2011 landed docs/architecture/SESSION_CONCURRENCY.md and touched both shared
files this PR also edits. The branch is rebased linearly onto latest main;
docs/README.md auto-merged (the two index entries sit in different rows) and
the one conflict, in docs/architecture/DESIGN.md, was resolved semantically:
the encoder-grouping paragraph stays attached to the runtime-services list it
qualifies, upstream's ## Session concurrency section follows it, and its claim
is scoped from "the one significant gap" to "the gap in that list" now that a
second in-progress area is documented alongside it.

ENCODER_BATCHING.md and INFERENCE_METADATA_DECISIONS.md are otherwise
unchanged from reviewed head 2daeb83f6. The only edits are citation drift:
workflow.rs gained six lines above the invoke path and five above the image
preprocess adapter, and value.rs gained five above alias_with_offset, so the
ten citations into those two files are re-pinned. No prose, rule, example, or
matrix row changed — the interdiff over docs/genai/ is exactly ten line-number
substitutions.

Amendments from the schema implementation (#2009)

Two places where the schema PR was stricter than this document and right to be;
both adopted rather than narrowed, so the two do not diverge.

• axis == 0 applies to every packed value, not only one a batch_capacity
  component consumes or produces. The runtime splits a packed value per request
  whenever it hands one back — §4 rule 8's emit path rebases offsets and derives
  per-request owners with no capacity in sight — and that split wants the same
  contiguous span for the same aliasing reason. The old scope made a strided
  packed emit legal exactly where nothing had declared it could pay for one. No
  fixture declares a non-zero packed axis, so the wider rule rejects nothing.
• A level companion that is a declared preprocessing-program output must carry
  pack_offsets / pack_owner. §3.3 introduced the roles but used them only
  descriptively. §4 rule 4 now requires them, scoped to values whose declaration
  carries a content role at all — a component's graph outputs on an
  extent: produced level carry none and are explicitly out of reach. The
  asymmetry with §3.2, where a length value is resolved by name and its role is
  descriptive, is now explained rather than left as a wart: length vectors have
  established modality spellings that predate this design, while the companion
  roles are new and have nothing to accommodate.

Matrix row 17 gains both rejections; P2's negative-fixture list names both; the
phase box's stale "§3.1 rules 1-7" is corrected to 1-9 to match the body.

Follow-on contracts from the schema code review (#2009)

• §4 rule 8 generalized: a ragged emit publishes the account of its
  raggedness. The rule covered packed emits and said nothing about padded
  ones, which was an omission. §3.2 rejects a payload-shaped validity mask
  precisely so the length vector is the only account of the padding in
  existence, so an emitted padded value must declare each entry's
  valid_lengths as a workflow output, and the serving carve-out admits an
  int64 shared output named as another emitted value's valid_lengths on
  the same terms as an offsets/owner. Unlike offsets, a length needs no
  rebasing on delivery — a request receives the slice indexing its own items —
  and unlike owner, it is delivered rather than internal.
  Correction, recorded rather than quietly patched: this paragraph said
  "int64 rank-1" when it was written, which was the flat reading later found
  to be wrong for a length and fixed in 57b5f088f — the rank is the one the
  reference demands, rank 1 for an offsets or owner by construction and the
  number of axes outer to the padded one (rank == axis) for a valid_lengths.
  Row 25 grew to four cases at this round and has grown twice since; the current
  count lives in the matrix, which is the only place worth reading it.
  The stale summary is the point: the flat reading survived in four places —
  §4, decisions §10.6, the schema PR's validator, and both PR bodies — removed
  from each at a different time by whoever owned it, each of us then asserting
  the fix was complete. Nothing type-checks prose, so a claim restated in a
  summary is a copy that goes stale silently. Grep the artifacts you publish,
  not only the ones you compile.
• §6.1 gains the rule-gating distinction: a version may gate what a document
  must say, never what it may say wrongly. When a new field makes an
  existing default ambiguous, the demand to state intent explicitly starts at
  the version that introduced the ambiguity; range checks and every rule about
  a value a document did state stay unconditional at every version. The two
  look alike in a validator and are opposites in effect — one preserves
  packages that predate a question, the other would preserve their bugs.
  Packages under the exemption should still be migrated, so it stays a
  compatibility guarantee rather than a live path nothing exercises.

Delta-review cleanup: the flat token_packed spelling is migrated, not shimmed

levels replaces the flat TokenPacked { offsets, owner, axis } pair rather
than joining it, so a v1.0 document spelling the flat form is refused by a v1.1
runtime. §6.1 read as though every v1.0 document loaded unchanged and matrix
row 22 asserted it outright; both are corrected.

• The compatibility promise is narrowed to documents that do not use
  token_packed. The flat form is the one deliberate break in the v1.1 surface,
  and P1 owes its refusal an actionable message rather than a
  deny_unknown_fields serde error.
• Migration is mechanical and lossless: { offsets: X, owner: Y, axis: 0 } →
  { axis: 0, levels: [ { offsets: X, owner: Y } ] }.
• No compatibility shim. Two spellings of one fact (Rule 10) would be carried
  indefinitely, and every §4 rule written twice — once against each shape.
• The break is affordable because the blast radius is measured: no package under
  tests/fixtures/onnx_genai_workflows/ or examples/inference_metadata/
  declares token_packed at all, the only in-repo document spelling the flat
  form is one metadata test, and the layout has no runtime consumer, so no
  deployed behavior is preserved by keeping it.

Also corrected: the stale normative flat examples in decisions §8.2 and
§10.1; §2.1 now names the flat shape as the one being replaced; the fixture
count (17 workflow fixture directories, 19 entries counting README.md and
SOURCE_COMMIT); and the acceptance-matrix intro row range, 16–27.

Follow-up: the taxonomy behind the migration, and recognizer ordering (e9727f04b)

The previous revision recorded that the flat spelling is replaced; it did not
record what kind of change that is, or where its refusal belongs. Both are §6.1's
to answer, and the schema PR (#2009) asked directly. §6.1 now states:

• A retired spelling is a third kind of change, and a version number arbitrates
  none of it. An additive field is a version question: the document declares a
  higher minor and an older runtime refuses on the version. A rule demanding that
  a document state something newly ambiguous is the second, and is version-
  scoped. A retired spelling is neither — both spellings belong to the same
  version line, so the stale document is well-formed, declares a supported
  version, and says something the reader no longer has a meaning for. No
  comparison of version numbers can detect that, so the refusal MUST be shape
  recognition and cannot be folded into the gate. The "packages that use nothing
  new keep loading" claim is correspondingly scoped to additive fields, which is
  the only class it was ever true of.
• Shape recognition runs after the version gate, not before. A retired-shape
  message asserts what a spelling means, and that assertion is scoped to one
  vocabulary. A v2.0 document has not established that it belongs to the line in
  which the flat pair was retired, so telling its author to rewrite it into v1's
  levels claims knowledge of v2 this build does not have. It is refused on its
  version and told nothing further. Where an existing recognizer runs before the
  gate, aligning it is a separate change with its own evidence and is not this
  design's to make.
• The message is the deliverable. An unknown-field error naming offsets,
  with the path stopping at the contract rather than the layout, reads like a typo
  and sends a reader hunting for a misspelling that does not exist. The refusal
  MUST name the containing path down to the layout, give the exact
  replacement, and say that no document is converted. The published schema is
  generated from the same types and closes its objects, so producer-side
  validation reaches the same verdict as the loader — an agreement worth a test
  rather than a coincidence.

Acceptance row 22 gains the ordering: a 2.0 document carrying the flat pair is
refused on its version only and never receives the migration message.

Follow-up: companion rank is per reference, and declared is not published (57b5f088f)

Two corrections to §4 rule 8 and its mirrors in decisions §10.5/§10.6, raised by
#2009 after a review found the first as a live contradiction in its validator.

• The carve-out's flat "rank 1" was wrong for a length. offsets and owner
  are rank 1 by construction, so the phrasing was accurate for them and read as
  though it were general. §3.2 fixes a valid_lengths at the number of axes
  outer to the padded one, so a value padded on axis 2 publishes a rank-2
  length. Under the flat reading one rule requires that companion and another
  refuses it — and the refusal necessarily advises request_aligned, which is
  exactly what a companion MUST NOT declare. The condition is now per
  reference: collect what each declaration naming the value requires of it —
  role, and the rank that role implies at that site — and admit it if it satisfies
  any one. Expectations accumulate (one length may bound the same dimension of
  two outputs); conflicting ranks are a defect of the padding declaration and
  are reported there, not at the serving rule, which would name an innocent line;
  an unresolvable padded dimension carries no rank expectation, since that
  declaration is already being rejected. A value named as a companion but shaped
  like something else is refused as a malformed companion, naming role and
  expected rank.
• Declared is not published. Both halves of rule 8 now require the companion
  to be emitted — written by some declared step — not merely to appear in the
  output list. An output nothing writes hands the caller an empty vector beside a
  ragged payload: the rule's own failure case wearing the appearance of
  compliance. The check is whole-workflow, not path-sensitive, because
  "written by some declared step" is what is soundly decidable without evaluating
  branch predicates, and a path-sensitive rule would reject a correct package
  whose companion is written in a sibling branch of the emit.

Acceptance row 25 grows the cases that distinguish the two readings: doubly padded
values publishing rank-1 and rank-2 lengths together, a packed value padded on the
axes it does not pack publishing three companions at three ranks, a mis-ranked
length, and a companion declared but written by no step.

Follow-on (29ae4cbdf): both sides read "emitted". The obligation asks the
companion to be emitted and the carve-out already asked the value that names it
to be emitted, but the neighbouring decidability sentence still read "decidable
from the declared outputs alone", inviting the weaker reading. One emit and one
bare declaration is two answers to one question (Rule 10), and the weaker half is
exploitable: declare a padded output beside any shared vector, write neither, and
the vector walks past the serving rule on the strength of a payload that does not
exist. The decidability claim is corrected rather than dropped — the condition is
decided from the workflow's own declarations, its outputs and its steps, with
no runtime information.

Follow-on (2b70a8a9c): the length-rank rule is stated in its check form. The
rank clause was corrected above, but only definitionally — "the number of axes
outer to the padded one". That is not the check, and the reader has to derive one
from the other; that derivation is exactly where the flat "rank 1" survived review
on both sides. §3.2, §4 rule 8 and decisions §10.6 now give rank == axis — the
padded dimension's axis index — alongside the definition. No rule changed.

Pre-merge: an emit may not trim a padded output (b46991675, corrected in 9e5bdc996)

The last ambiguity a reviewer found: what an Emit carrying valid_length means
when its output contract also declares padding.

WorkflowNode::Emit.valid_length limits the emitted prefix on the value's growth
axis (crates/onnx-genai-metadata/src/schema/ir.rs:900-916), and the interpreter
honours it by slicing the payload — slice_workflow_prefix for a whole tensor
(workflow.rs:2215-2226, defined at 4696-4747) and slice_workflow_row per
request row (4852-4882). padding links a dimension to a valid_lengths
companion that §3.2 makes the sole account of the padding and §4 rule 8
requires an emit to publish. Both describe one raggedness, so both cannot be
right: the trim publishes a shorter tensor and the companion then measures a
tensor that was never delivered — the caller either holds lengths that overrun its
payload, or receives a value the runtime rewrote behind the metadata describing
it.

• Exclusion, not reconciliation. An Emit whose output declares padding
  MUST NOT carry valid_length.
• The refusal MUST say which account is authoritative. "These two disagree" is
  not actionable until the reader knows which one to delete. It is
  padding.valid_lengths, and the asymmetry is structural rather than a
  preference: valid_length truncates what the step writes and is invisible in
  the contract, while a padding entry is part of what the caller reads and
  names the vector rule 8 requires the workflow to publish. A trim also destroys
  the padded extent; only padding survives a group, where rows share an extent
  that just one of them fills.
• The exclusion is flat: it does not ask which axis the trim is about. An
  emit's growth axis is stated only by default — Emit.axis "defaults to the
  final axis" (ir.rs:909-915) — while a padded value's lengths are indexed by
  the axes outer to the padded one. A trim at or outside the padded axis
  invalidates the vector; a trim strictly inside it leaves a declared shape the
  tensor no longer has. Narrowing to the growth axis would have to decide which
  axis an emit-level length is about, to buy an admission nobody needs, and it
  would guess in the direction of admitting the ambiguous case.
• token_packed needs no separate rule, and the reason is stronger than the one
  b46991675 gave. That commit routed the packed case through request_axis()
  and appealed to §4 rule 7. 9e5bdc996 corrects it: an emit carrying
  valid_length into an output whose layout declares no request axis is
  already refused at load, by a rule that predates this design — ragged
  emission needs a declared row axis so the runtime can associate result rows with
  requests (crates/onnx-genai-metadata/src/validation.rs:3288-3302). Since
  request_axis() is None for TokenPacked (ir.rs:67-72), a packed output
  refuses the combination whatever its padding says, with no appeal to rule 7,
  which needs a declared padding entry on the packed dimension to bite at all. A
  packed and padded output hears from both rules, which is correct rather than
  redundant: they answer different questions, and suppressing either would leave a
  document whose only remaining message explains the wrong defect.
• No version gate, deliberately. The rule judges a pair of things a document
  did state, which §6.1 keeps unconditional at every version. A gate would also
  be inert: padding is itself a v1.1 field, so a document able to express the
  contradiction has already been forced to declare v1.1 — the gate would be a
  second, weaker copy of one already in force, and a weaker copy is the kind that
  later disagrees with the original.
• P2 owns the validator and five fixtures: the per-row and whole-tensor trims
  of a padded output; the two positives that must keep working — a valid_length
  emit into an output with no padding, and a padded output emitted with
  no valid_length, both guarded against becoming vacuous — and one pinning
  the interaction: a packed and padded output emitted with a valid_length
  must still be refused by the pre-existing no-row-axis rule, so that adding this
  exclusion is shown not to have shadowed it. Acceptance row 25 gains the negative
  case and its packed variant.

Audit prompted by a stale summary in the schema PR (d069fd9da, 9d7f4b834)

The schema PR found the retired flat "rank 1" reading still live in its own PR
body's summary, after it had been fixed in its code. The same audit run against
this branch's published artifacts found two more instances of the class:

• This body's own §4-rule-8 paragraph described the carve-out as int64
  rank-1, omitting valid_lengths — the flat reading, still being published
  in the artifact a reviewer reads first, after four places in the documents had
  been corrected. Fixed above, in the past tense with the correction recorded
  rather than quietly patched, because the stale copy is the evidence.
• §9's own partition of its matrix named rows 1–9, 10–15 and 16–27 and then
  stopped, leaving row 28 — performance versus sequential direct execution —
  outside every band. d069fd9da gives it its own clause: every other row asks
  whether grouping is correct, row 28 asks whether it was worth doing.

Audited rather than spot-fixed. The fixture counts (17 directories, 19 entries)
hold. The PR-DAG box's "§3.1 rules 1-9, §4 rules 1-8" is not stale despite §4
having nine rules — rule 9 states invocation-time preconditions, which load-time
validation cannot check, and it is attributed to P4 where it belongs. One
unrelated pre-existing citation surfaced and is fixed in 9d7f4b834: the
adapter-compat row pointed at tests/adapter_artifact_compat.rs, which resolves
from no directory in the tree.

The generalizable finding, which cost two agents four rounds: the flat reading
survived in four places — §4, decisions §10.6, the schema PR's validator, and
both PR bodies — and was removed from each at a different time by whoever owned
it, each then asserting the fix complete. Nothing type-checks prose. Grep the
artifacts you publish, not only the ones you compile.

Rebased onto latest main, which also required re-pinning six engine citations
that drifted when the workflow runtime's state gained named owners: the three
request_axis() call sites, the image adapter and its one-element
preprocess_encoded call, the node runner and invoke_onnx_component, and the
per-invocation symbol binding.

Citation verification was checking the wrong property (8512195dc)

Every check on this branch asserted that a citation is in range — a property
of the file's length, not of its content. A citation can therefore point at
unrelated code and pass. Two did, both added by me in f2b3adb6e:

citation	claimed	actually at
mod.rs:452	audio's valid_lengths	line 452 is "validity_mask"; valid_lengths is 451
mod.rs:452-454	the three added roles	range starts one line after valid_lengths, excluding the role the sentence is about

Both are hand-counting errors from tightening a correct wider range into a wrong
narrow one, and both stayed plausible because the neighbouring lines are other
roles from the same vocabulary. Now mod.rs:451 and mod.rs:440-456 — the whole
AudioOutputContent block, parallel to the 349-363 already used for vision. A
block citation cannot be off by one.

The check that finds this asserts the cited range contains a distinctive string
from the surrounding claim. Run over all 97 ranged citations in these four
documents it flags 29: 27 are the heuristic failing to see an anchor one line
outside the range — a struct name above the deny_unknown_fields attribute the
sentence actually cites — and 2 were these. All 27 were read and confirmed,
including Scheduler::schedule(), the multi-row prompt refusal in
ContinuousBatchManager::submit, the per-row trim path gated on
request_axis().is_some(), and the onnx-model-package minor-ignoring precedent
this design deliberately departs from.

Raised by the implementation agent (#2009), whose framing is the right one: a
check that cannot fail on the defect it is meant to catch is the kind that later
disagrees with the thing it was meant to verify.

Correction: the emit-trim exclusion binds on packed outputs too (7a158756d)

§3.2 closed with "the new exclusion is therefore load-bearing only where a
request axis exists — request_aligned and request_expanded outputs". That
contradicted the sentence three lines above it and would have licensed a
narrower validator than this design requires.

The premise is false: a packed value may legally pad. §4 rule 7 forbids a
padding entry only on the dimension the layout packs, and calls an entry on
any other dimension the normal composition of the three kinds of raggedness. Row
25 already requires such a value — token_packed on axis 0, padded on two
further dimensions — and it is the case with the most extents an emit-level
trim can misdescribe. Scoping the exclusion to layouts with a request axis would
exempt exactly that value: still refused, because the no-row-axis rule fires, but
refused with a message about a missing row axis when the defect is a trim
contradicting two published length vectors. §3.2's own reasoning says neither
refusal may suppress the other "since suppressing either would leave a document
whose only remaining message explains the wrong defect". The closing clause said
the opposite.

The scoping was unfalsifiable by the fixtures this document demanded, which
is the part worth generalizing. §8's P2 obligation asked only that the packed
variant "still be refused by the pre-existing no-row-axis rule", and row 25 said
it was rejected "but by" that rule. Both pass against a validator that scoped the
exclusion away, because the outcome is preserved and only the message is
lost. Both now require the fixture to assert both messages. An acceptance row
that checks a rejection without checking which rule rejected cannot detect a rule
being narrowed out of existence underneath it.

P2 also drops a redundancy it could not justify: its two negatives differ only in
the valid_length's rank, which the interpreter dispatches on and the load-time
predicate does not, so one fixture MAY cover both.

Found by the implementation agent (#2009), which mutation-verified it by
inserting the scoping this document implied and watching its doubly-padded packed
test fail. The clause is withdrawn in the past tense rather than deleted, because
it is the reason the correction was needed.

Post-merge status rewrite (f2b3adb6e)

The design was still written as if none of it existed, which made its status
line, its evidence section, and 57 of its citations false. Corrected:

• Status line and §2. partly implemented, naming which phases landed. §2
  gains a two-layer note and per-subsection Since #2009 markers; §2.3
  (token_packed has no runtime), §2.4 (single-item adapter), and §2.5 (no
  scheduler work item) are untouched because nothing closed them.
• Claims that inverted, not merely moved. §3.3 and the valid_lengths
  argument said the companion roles were absent from the content-role
  vocabulary. They are now in it, and nothing produces them — a different and
  still-open gap, so the claim is rewritten rather than re-pinned. §2.8 and
  §6.1's schema_version doc-comment defect are recorded as corrected, in the
  narrow form this design argued for: compatibility comes from a field being
  absent by default, which buys nothing for a field that was reshaped.
• §8 keeps its full obligation text with P1 and P2 marked shipped. A phase
  list that mutates into a changelog stops being reviewable against the design,
  so the checklist stays and the marker goes on top of it.
• Decisions doc. §10.4 becomes "What §10.1 did not have"; §10.5 and §10.6
  drop proposed for a status note separating the load-time half now in force
  from the runtime half that is not. DESIGN.md and the docs index follow.
• 57 citations re-pinned, 39 mechanically via a difflib old→new line map and
  16 by hand where the merge moved the claim rather than the line. Several
  were in range and semantically wrong after the Image* → Vision*
  rename — mod.rs:330-363 still resolved, but to a vocabulary that now
  contains the very roles the sentence said were missing. Line-number repair
  alone would have preserved a false statement behind a valid citation, which is
  the failure mode a mechanical re-pin invites.

Two pre-existing defects surfaced while checking and are fixed: a link to a §6
anchor renamed in an earlier round, and a short-form redesign_invariants.rs:158
citation appearing before its first full path, which resolves from no
directory.

Verified at this head: every intra-doc link and anchor resolves, every citation
is in range and reads as claimed, 28 acceptance rows with uniform columns,
git diff --check clean, lines within 88 columns, diff touches docs/ only.

---

Post-merge re-pin, verified by content (766bff06b)

Rebased onto origin/main 46478fc0f, which contains #2009 as 0448f2bc6.
The point of this round is not the three fixes below — it is that the check
that was guarding the citations could not have found them.

The defect in the method. The previous gate asked whether a cited line
number fell inside the file. That is a property of the file's length, not of
its content. A citation can survive a refactor, land on unrelated code that
reads plausibly, and report green. #2009 added ~2000 lines to validation.rs
and ~270 to ir.rs; a checker that cannot fail on drift is not evidence that
drift did not happen.

The replacement. For each of the 97 ranged citations (57 distinct
ranges, 80 of them into the 24 files #2009 touched), a hand-reviewed
manifest records two anchors read from the document's claim, not derived from
the file:

• the head anchor must appear on the range's first line — the symbol or
  comment the surrounding sentence names;
• a body anchor must appear somewhere in the range.

Head-anchoring is what makes the check position-sensitive. A body-only anchor
survives a shift; a head anchor cannot.

Three references were in range and wrong at the head. All three are
narrowings of a previously correct wider range — the same failure as the audio
off-by-one in 8512195dc, which is now twice enough to be a pattern rather than
a slip:

citation	claimed	line 1 actually held	re-pinned
schema/package.rs:158-174	batch_invariance	the unrelated decoding field	162-174
ort/value.rs:1543-1551	alias_with_offset	the closing line of the previous doc comment	1544-1551
ort/value.rs:1526-1542 (×2 docs)	the no-copy-view doc comment	a blank ///	1524-1543 — the whole block, since a block citation cannot be off by one

The other 54 ranges verify unchanged against the merged tree.

Evidence the checker can fail. Two mutations, both run against the shipped
docs:

1. Line drift. Shifting citations by ±1 and ±2 lines: 97/97 citations fail
   at every offset. Per-range, shifting one citation in isolation:
   57/57 detected at −1, 57/57 at +1. No range survives a one-line move.
2. In-range-but-wrong. Replaying the three defects above: the line-in-range
   check reports PASS on all three (package.rs has 563 lines, value.rs
   has 3092); the content-aware check reports FAIL on all three, naming the
   line-1 text it found instead. This is the exact class the old gate admitted.

Recorded in the document, not only in this PR. The header now states the
convention — cite so that line 1 carries the claim, cite whole blocks for
block-level claims, and re-pin by locating the named symbol rather than by
adjusting the number until it lands inside the file. A verification habit that
lives only in a PR description is lost at merge.

Docs only. No code, schema, or fixture changes; design contracts are unchanged
by this round.

---

Citations now name their symbol (d92ac677b)

Rebased onto origin/main f66e84251. None of the 31 cited .rs files
changed between 46478fc0f — where the content-aware check last passed on all
97 citations — and f66e84251, and this round adds, removes, and alters zero
citation ranges (the before/after range multisets are byte-identical). So the
previous verification transfers by argument rather than by re-running it.

The gap this closes is in the header's own instruction. It tells an editor to
re-pin a drifted citation "by locating the named symbol". Seven citations into
validation.rs named no symbol — just path:line — so that instruction was
unfollowable exactly where it was most needed. The document asked for a repair it
did not equip anyone to make.

And the drift is scheduled, not hypothetical. #2074 rewrites the stale
call-site comment at validation.rs:4851 — the one this branch reported, where
the comment claimed the companion carve-out was "decidable from the declared
outputs alone" while output_companions walks the step tree. Its hunk is
@@ -4848,7 +4848,12 @@, a net +5 lines, which moves three ranges this
document cites:

cited range	after #2074
validation.rs:4858-4862 (3 doc sites)	4863-4867
validation.rs:5059-5091	5064-5096
validation.rs:5102-5130	5107-5135

4811-4825 sits above the hunk and is unaffected. A comment-only change moves
coordinates exactly as far as a behavioural one, so "no behaviour changed" is
not a reason to expect citations to hold — which is the argument for not chasing
numbers at all.

All seven now read (in validate_compaction_derivability, …/validation.rs:4858-4862)
or name validate_packed_emit_companions / validate_emit_length_authority.
The name is the durable half: a line number is a coordinate into a tree the
reader may not have checked out, while a symbol survives every edit that does
not rename it, and one grep recovers the range after any drift. A stale bare
number leaves a reader nothing to search for.

On #2074 itself: nothing in this document changes. The corrected comment now
reads "decided from the workflow's own declarations — its outputs and its
steps", which is the phrase ENCODER_BATCHING.md §4 and
INFERENCE_METADATA_DECISIONS.md §10.6 already used verbatim. The document was the correct copy and the comment was the stale
one; the fix converges on the doc rather than requiring it to move.

Docs only. No code, schema, or fixture changes; design contracts unchanged.

---

The acceptance criteria certified the bug they were written against (e7af18384)

Rebased onto bc715c329. Prompted by #2074's second hunk — a shipped test that
asserted !errors(&document).is_empty(), that something rejected, never which
rule — I audited this matrix for the same shape and found six clauses with it.

The sharp form of the problem. Row 25 and the P2 fifth fixture did not merely
fail to catch the scoping error corrected in 7a158756d; they were satisfied
by it. Both demanded the packed-and-padded trimmed emit be refused by the
pre-existing no-row-axis rule — which is exactly what a validator narrowing the
exclusion to layouts with a request axis delivers. A criterion a defective
implementation passes as cleanly as the correct one is worse than an absent
criterion, because it converts review into evidence.

Six repairs:

row	was	now
11	frames→clips level + pinned frames "is rejected by rule 2"	asserts rule 2's own message
17	"the axis rejection does not depend on the component declaring a capacity"	asserts the axis message — the old wording also passed against an implementation that refused the fixture for having no capacity, the opposite of the claim
22	"2.0 is refused on major"	names the major it read, so a minor-version refusal cannot satisfy it
25	withheld lengths and declared-but-unwritten companion "both rejected for not publishing"	each asserts the reason it was not admitted, and that neither receives the generic "declare a row axis" advice — precisely what a companion must not do
27	request-expanded and packed on one axis "is rejected at load"	asserts the message naming that pair; such a declaration trips other rules incidentally, so an outcome-only case survives this one being narrowed away

Generalized rather than left as five repairs. §9's preamble now makes it
normative: every row requiring a rejection is satisfied only by asserting the
message that names the rule. A fixture built to violate one rule usually violates
others too, so an outcome-only case is precise by accident and nothing holds
that. And the failure is one-directional, which is why it is invisible in review:
the outcome survives the narrowing and only the message is lost.

Zero bare rejection clauses remain across all 28 rows (mechanically checked);
columns stay uniform. No citation range is added, removed, or altered and no
cited file changed between f66e84251 and bc715c329, so the content-aware
citation verification continues to transfer.

Docs only. No code, schema, or fixture changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.45%. Comparing base (c1e395f) to head (2daeb83).
⚠️ Report is 19 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2010      +/-   ##
==========================================
- Coverage   80.79%   80.45%   -0.35%     
==========================================
  Files         425      425              
  Lines      208150   208790     +640     
  Branches   208150   208790     +640     
==========================================
- Hits       168174   167977     -197     
- Misses      34336    35153     +817     
- Partials     5640     5660      +20     

Flag	Coverage Δ
cli-ort-linux	?
cli-ort-windows	72.10% <ø> (+0.09%)	⬆️
mlas	85.20% <ø> (-0.14%)	⬇️
offline	80.59% <ø> (-0.35%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 32 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.