pgw#1424: Trellis2 and Hunyuan3d — the two 3D roots, declaring OPPOSITE lane facts

[PaulFidika]

pgw#1424: Trellis2 and Hunyuan3d — the two 3D roots, declaring OPPOSITE lane facts

MODEL_TYPES goes 9 -> 11 for se#769's 3D family lane. The two families are
interesting together precisely because they disagree about whether a lane
document can exist at all, and each answer is measured rather than asserted.

Trellis2 — ONE root for all five DiT checkpoints, canonical_contract
trellis2.dit-bf16@1 (tensorfs#132). ss_flow_img_dit_1_3B_64,
slat_flow_img2shape_dit_1_3B_{512,1024} and
slat_flow_imgshape2tex_dit_1_3B_{512,1024} have identical tensor name sets —
640 each, frozenset equality asserted across all five real safetensors headers
at microsoft/TRELLIS.2-4B revision af44b45f2e35a493886929c6d786e563ec68364d —
differing only in input_layer/out_layer channel counts. An I/O fact, the
Flux2Klein 4B/9B case.

Hunyuan3d — NAME + FINGERPRINT + DEFAULTS ONLY. No canonical lane, and
deliberately NOT a MissingContract sentinel either. This is the Rife shape
reached by a stronger route: Rife declined to GUESS a contract name, whereas
Hunyuan3D's absence is an IMPOSSIBILITY that was measured. The complete file
listing of tencent/Hunyuan3D-2.1 carries exactly one .safetensors — an image
encoder, i.e. the shared family-plural class tensorfs#122 forbids — and every
core model is a pickle, the 7,366,389,768 B shape DiT among them. The endpoint
said so first: hunyuan3d-2.1/main.py:208-212 already ships
layouts_undeclarable="pickle .ckpt — unclassifiable by the header-reading
derivation, and reading one to find out is the banned act".

A sentinel would have been worse than absence, not safer. MissingContract's own
refusal text instructs the reader to "author '.v.json' in tensorfs
spec/v1/contracts" — it ASSERTS a document is owed. Since none can ever exist,
that is a standing lie with a to-do attached. Absent is honest. (Ratified by
the se#769 umbrella.)

VALUES ARE SOURCED, NOT INVENTED, and the PR body cites file:line for each.
Trellis2Defaults.steps=12 is sourced TWICE and the two agree: the family
owner's own pipeline.json sets params.steps=12 on all three samplers, and
trellis-3d/main.py:56 declares 12 with bounds ge=1/le=50.
Hunyuan3dDefaults transcribes hunyuan3d-2.1/main.py:72-73 verbatim (50 / 5.0),
keeping the WIRE field names because that endpoint's
RuntimeFormula("a + b*num_shape_steps") resolves terms by same-named lookup —
normalizing to steps would silently break its runtime estimate.

TRELLIS'S GUIDANCE IS ABSENT AND THE ABSENCE IS EVIDENCE. pipeline.json carries
THREE different guidance strengths for the three stages — 7.5 sparse-structure,
7.5 shape SLAT, and 1.0 (i.e. off) for texture SLAT — with three different
guidance_rescale values and two different guidance_intervals. One platform
scalar cannot be the default for all three, and no endpoint exposes any of them
on the wire, so there is nothing to clamp. cfg=True IS declared, because
FlowEulerGuidanceIntervalSampler at strength 7.5 is real classifier-free
guidance and the resulting batch-2 is a residency fact the placer needs.

Both canonical_scheduler_config stay {} and both are CORRECT BY ABSENCE rather
than conceded: TRELLIS.2-4B ships no scheduler/ directory at all (22 files,
complete listing checked), and Hunyuan3D's shape DiT is flow-matching with no
diffusers scheduler — main.py:13-17 says so and its tests assert it. The one
scheduler_config.json in the Hunyuan repo belongs to the PAINT UNet, a
different model; borrowing it would be a category error.

Registered in MODEL_TYPES, defaults_vocabularies() and BOTH lazy re-export
sites in models/init.py (the TYPE_CHECKING block and the runtime map,
pgw#1331).

TESTS ARE RED/GREEN VERIFIED, not merely green. Two new tests, each proven able
to fail on exactly the defect it exists to catch:

• giving Hunyuan3d a MissingContract sentinel FAILS
  test_the_two_3d_roots_declare_their_lanes_by_evidence (it asserts the
  contract is absent AND is not a sentinel that merely reads as falsy);
• adding "dit.blocks-fused-qkv*" to Trellis2's fingerprint FAILS
  test_the_3d_fingerprints_do_not_claim_the_shared_dit_fragment.
  Both restored green. 64 passed across test_model_defaults{,_export,_typing}.

KNOWN AND DELIBERATE: TRELLIS2_DIT_BF16 is a live MissingContract sentinel
until the document is re-vendored under _vendor/tensorfs/_contracts/. That is
the designed behaviour — inert at import, loud on use — and clearing it takes
no code change here, exactly as pgw#1391 built it to. The endpoint migration is
gated on the re-vendor, not on this commit.

---

Sourcing table — every value, with its file:line

field	value	source
Trellis2Defaults.steps default	12	microsoft/TRELLIS.2-4B pipeline.json @ af44b45f, params.steps on all three samplers; and trellis-3d/src/trellis_3d/main.py:56 ("Upstream default 12")
Trellis2Defaults.steps bounds	1..50	trellis-3d/main.py:56 msgspec.Meta(ge=1, le=50) — the only trellis2 envelope any endpoint declares, so trivially the widest
Trellis2Defaults.cfg	True	pipeline.json: all three samplers are FlowEulerGuidanceIntervalSampler; guidance_strength 7.5 on sparse-structure and shape-SLAT
Trellis2.canonical_scheduler_config	{}	correct by absence — TRELLIS.2-4B ships no scheduler/ dir (22 files, complete listing checked)
Hunyuan3dDefaults.num_shape_steps	50, 1..100	hunyuan3d-2.1/src/hunyuan3d_2_1/main.py:72 (value), :83 (wire bounds)
Hunyuan3dDefaults.guidance_scale	5.0, 1.0..15.0	hunyuan3d-2.1/main.py:73 (value), :84 (wire bounds)
Hunyuan3d.canonical_scheduler_config	{}	correct by absence — the shape DiT is flow-matching, main.py:13-17, asserted by that endpoint's tests
Hunyuan3d.canonical_contract	absent	tencent/Hunyuan3D-2.1 has one .safetensors (an image encoder); all core models are pickles. main.py:208-212 already declares layouts_undeclarable=

What is deliberately NOT declared

Trellis2Defaults has no guidance. pipeline.json carries three
different guidance strengths for the three stages — 7.5 / 7.5 / 1.0 (off,
for texture) — with three guidance_rescale values (0.7 / 0.5 / 0.0) and two
different guidance_intervals. One platform scalar cannot be the default for
all three, and no endpoint exposes any of them on the wire, so there is nothing
for the platform to clamp. A per-stage vocabulary is a real design question and
would be invention today.

Neither type declares resolution/texture_size/octree_resolution — those
are endpoint PAYLOAD presets under the ie#345 shape discipline.

Test evidence

64 passed across test_model_defaults.py, test_model_defaults_export.py,
test_model_defaults_typing.py.

The two new tests are red/green verified — each was made to fail on exactly
the defect it exists to catch, then restored:

arm	injected defect	result
test_the_two_3d_roots_declare_their_lanes_by_evidence	gave Hunyuan3d a MissingContract('hunyuan3d.diffusers-bf16', 1)	FAILED as intended
test_the_3d_fingerprints_do_not_claim_the_shared_dit_fragment	added "dit.blocks-fused-qkv*" to Trellis2.contracts	FAILED as intended

Both restored → green. An assertion that has never failed is not known to be
able to fail, so both were made to.

Sequencing

• tensorfs#132 / PR gw#421: generation smoke runs independently of suite outcome #133 authors trellis2.dit-bf16@1. Until that merges
  and is re-vendored, TRELLIS2_DIT_BF16 is a live MissingContract — inert at
  import, loud on use, and clearing it takes no code change here.
• pgw#1423 (a lane-less PRIMARY has nowhere to declare its VRAM floor) and
  pgw#1431 (self-loading endpoints refuse at discovery) both gate the
  ENDPOINT migrations, not this vocabulary commit.

Refs pgw#1424, se#769, se#775, tensorfs#132.