2.6.7

Summary

This pull request continues the characterize-first refactoring of the TensorFlow-free flatbuffer_direct backend. It restructures late shape, layout, topology, fallback, and terminal-cleanup orchestration without changing public conversion policy or using newly recorded evidence to alter graph-rewrite control flow.

The main outcome is a smaller and more reviewable central lowerer whose phase boundaries are explicit, whose repeated orchestration sequences have focused owners, and whose observation-only results are retained in a bounded conversion-session store under stable phase IDs.

The branch also includes the full sequential Tier 0–4 TFLite/native-PyTorch regression evidence for the final checkpoint and updates the package version metadata to 2.6.7.

Why this change is needed

The direct FlatBuffer path has accumulated many interacting shape, layout, topology, compatibility, and model-recovery rules. Even when each rule is locally correct, several structural properties made maintenance difficult:

• adjacent pass calls were coordinated directly inside the central lowerer;
• repeated sort/layout-refresh and shape/reconciliation sequences had multiple owners;
• useful mutation and validation results were sometimes discarded or kept in unconsumed local dictionaries;
• phase identity was implicit in source position rather than represented by a stable ID;
• guard-skipped work was difficult to distinguish from work that ran and produced no mutation;
• terminal invariants and fallback recovery boundaries were spread across a very large function;
• changing ownership could easily invalidate structural assumptions in distant tests.

This branch makes those contracts explicit before attempting more aggressive scan elimination or control-flow optimization.

Architecture changes

Bounded phase-result storage

ConversionSession now owns a bounded, conversion-local phase-result store.

• Results are recorded under 128 stable phase IDs.
• Each phase has one deterministic owner expression.
• Stored values are compact counters or bounded summaries rather than graph-sized snapshots.
• The store copies mappings so later caller mutation cannot silently change recorded evidence.
• "not invoked" remains distinct from "invoked with zero mutations".
• No recorded counter is consumed to skip or reorder production work in this PR.

This removes observation-only lowerer locals while giving future optimization work a stable basis for differential testing.

Shared topology and shape owners

Repeated multi-step sequences now have focused pass-module owners, including:

• topology sort followed by logical-layout refresh;
• complete static-shape reconciliation followed by topology restoration;
• terminal topology sort and logical-layout validation;
• bounded primary and fallback topology checkpoints;
• safe transpose reduction, dynamic reshape resolution, and terminal expand/squeeze reconciliation evidence.

The owners preserve the original arguments, guards, ordering, cycle behavior, metadata updates, and temporary-state lifetime.

Explicit late and terminal orchestration

Large groups of previously adjacent lowerer calls were extracted into narrowly scoped orchestration owners. The extracted families include:

• QLinear and quantized layout recovery;
• attention/QKV, BatchMatMul, window, and reshape-layout recovery;
• binary adapter and broadcast convergence;
• pre-Concat, Slice/Concat, channel-slice, and terminal bridge cleanup;
• late Conv1D/decoder and Pad/InstanceNorm recovery;
• fallback norm, precision, unbound-input, and recurrent-alias repair;
• SiNet CSP attention, residual, HardSwish/SE, and terminal recovery;
• final-input dynamic-shape, final boundary, and terminal stabilization cleanup;
• prune-aware summaries for PRELU, Conv-input, affine, hard-activation, SPP, and normalization clusters.

These owners return the same child mappings or strict summaries in the same source order. Existing lowerer compatibility wrappers are retained where instrumentation or callback injection depends on them.

Central lowerer simplification

The central lower_from_onnx2tf.py no longer manually coordinates each extracted cluster. It delegates orchestration while retaining the existing phase order and records only the bounded result required by the conversion session.

The refactoring deliberately preserves:

• graph mutations and ModelIR serialization inputs;
• logical/physical layout decisions;
• producer/consumer and graph-index behavior;
• diagnostics and failure propagation;
• public compatibility wrappers;
• option guards and per-pass evaluation counts.

Compatibility guarantees

• Public CLI and Python APIs are unchanged.
• flatbuffer_direct remains the default backend.
• Artifact names, report formats, return behavior, and exception behavior are unchanged.
• Normal direct TFLite conversion and -cotof do not import TensorFlow.
• Optional TensorFlow exporters remain behind the existing optional boundary.
• No dependency was added.
• No multiprocessing or parallel inference path was introduced.
• TFLite and native PyTorch exporters continue to consume the same validated conversion state.

Characterize-first workflow

Each extraction was split into two checkpoints:

1. characterization tests fixed the owner boundary, call order, arguments, no-op behavior, result schema, graph effects, and neighboring phase position;
2. production code was then moved behind the characterized owner, followed by focused and affected sequential test gates.

When an ownership move intentionally invalidated a structural source assertion, the initial failure was captured first. Tests were then updated to assert the new owner boundary while preserving runtime behavior. This avoids masking behavioral regressions as mechanical test maintenance.

The branch contains detailed implementation and checkpoint records in:

• docs/fb_refactor8_improvements.md
• docs/flatbuffer_direct_handoff_fb_refactor8.md
• docs/fb_refactor8_pull_request_description.md

Full Tier 0–4 regression audit

The final branch checkpoint was validated against every eligible root-level ONNX model in Tiers 0–4.

Fixed scope

• 456 root ONNX files were inventoried.
• 420 loadable models contained 1–1,999 ONNX nodes.
• 29 managed timeout models and 12 explicit user exclusions were omitted.
• 379 models were executed in the fixed profile order.
• Each model had a 600-second timeout.
• The entire descendant process tree was monitored for VmSwap.
• Inference concurrency remained exactly one.
• Each invocation generated and checked TFLite plus native PyTorch output only.

Result

• 379/379 eligible models completed.
• 0 timeouts.
• 0 models reached ten minutes.
• 0 SWAP detections.
• 0 combined-classification differences from fb-refactor7.
• 0 TFLite component-state differences.
• 0 native-PyTorch component-state differences.
• 0 normalized failure-signature differences.
• 0 confirmed regressions attributable to this branch.

Raw component counts remained exactly equal to the previous branch:

| Component | Pass | Fail | Missing report | Conversion error | | --- | ---: | ---: | ---: | ---: | | TFLite | 347 | 20 | 10 | 2 | | Native PyTorch | 138 | 46 | 193 | 2 |

The strict runner intentionally retains inherited missing reports and accuracy failures. Those entries were compared model-by-model rather than counted as new regressions.

The only numeric difference was randnlike4.onnx, whose native-PyTorch output is intentionally nondeterministic. Its classification was unchanged. The two DEIM models retain the user-approved near-tied TopK-index disposition. The two DPT-LeViT conversion errors are inherited and unchanged.

Timing

Total per-model conversion time decreased from 7,689.33 seconds to 7,376.09 seconds (-4.07%). Every Tier 0–4 aggregate total and median was below the fb-refactor7 observation. The slowest model completed in 208.95 seconds, well below the 600-second boundary.

Pass-efficiency metrics were exactly equal between the two branches:

• 377 models with pass metrics;
• 196,325 pass events;
• 24,535,648 preflight operator visits;
• 22,321 state builds;
• 5,419 snapshots;
• 0 fingerprints.

Full evidence is recorded in:

• docs/flatbuffer_direct_tier0_4_full_regression_2026-07-20.md
• docs/baselines/flatbuffer_direct_tier0_4_tflite_native_pytorch_fb8_b35c36a0.json

Test coverage

All inference and conversion tests were run sequentially under uv.

The branch includes focused contracts for:

• pass match/guard/rewrite/no-op behavior;
• owner call order and argument identity;
• graph and layout-state identity preservation;
• topology cycles and stale validation metadata;
• dynamic/static shape reconciliation;
• quantized and QLinear layout recovery;
• terminal, fallback, attention, SiNet, and Conv1D composite owners;
• deterministic phase ordering and bounded result storage;
• public compatibility wrappers and instrumentation callbacks;
• TensorFlow/tf-keras import blocking for direct conversion;
• lowerer architecture boundaries.

The final bulk-runner and corpus-manifest gate reports 44 passed tests. Numerous focused and affected suites were run at each characterize/extract checkpoint; their commands and exact counts are preserved in the branch documentation.

Temporary-storage handling

The full corpus run retained logs, JSON reports, pass metrics, and text diagnostics while deleting only reproducible artifacts after their model entry was atomically persisted. It reclaimed 51,216,397,607 bytes (47.70 GiB), then removed the uniquely named temporary run directory after condensed evidence validation.

Package metadata

The package version, lockfile entry, and documented container tags are updated consistently from 2.6.6 to 2.6.7. uv lock --check and an import-time metadata consistency assertion both pass.

Intentionally deferred work

This PR does not use the new phase evidence to eliminate graph scans or skip passes. Such optimization should be a separate change with mutation-positive and stable-path differential evidence for operator order, layout state, cycle handling, ModelIR digest, serialized artifacts, and numerical output.

The broader flatbuffer_direct refactor is therefore not declared complete by this PR. This checkpoint provides explicit ownership, bounded evidence, strong regression characterization, and a safer foundation for subsequent optimization without changing current public behavior.

What's Changed

• Refactor flatbuffer_direct phase orchestration with bounded evidence by @PINTO0309 in https://github.com/PINTO0309/onnx2tf/pull/958

Full Changelog: https://github.com/PINTO0309/onnx2tf/compare/2.6.6...2.6.7