ADR-029 — DTALite `assignment()`: the second external engine, and the identity-map static-UE row¶

Status: accepted (shipped in v0.2) File: docs/design/adr-029-dtalite-tap.md

Context — the second external simulator, and a cost law that maps EXACTLY¶

ADR-027 shipped sumo-marouter, the first external simulator: its hardcoded linear-in-flow class law forced a mapping floor (Braess RG ~1.7e-4) because the scenario’s BPR could only be approximated. This ADR is the second external engine, the named dtalite-adapter sprint (canon zhou2014dtalite, tier 1, docs/REFERENCES.md): the PyPI DTALite wheel (Fang Tang + Xuesong Zhou, 0.8.1, ~1.3 MB, no declared dependencies, ctypes-loads a compiled engine). Its assignment() entry is a static Frank-Wolfe user-equilibrium solver with a per-link BPR VDF — so unlike marouter the compile map is the identity on (free_flow_time, b, power, capacity), and Sioux Falls power-4 becomes the marquee anchor rather than an “unrepresentable” refusal.

Everything below was verified by executing the pip wheel in this repo’s python (pip install DTALite==0.8.1) against the repo’s own scenarios and certifying the emitted flows through the UNCHANGED harness (P1). Three engine hazards make the subprocess wrapper mandatory rather than merely hygienic (§4).

Decision 1 — dependency mechanics (the adr-025/027 optional-extra precedent)¶

Extra: dtalite = ["DTALite>=0.8"] in [project.optional-dependencies], a floor not a pin (a == in library metadata conflicts with user environments). The FW/VDF behavior lives in a bundled .so that can shift under the floor, so the CI workflow pins DTALite==0.8.1 (the tested engine) as the anchor tripwire.
Guard — one deliberate deviation from the sumo shape. import DTALite has two side effects the sumo guard never had to consider: it prints a version banner to stdout and ctypes-loads the engine .so + libgomp into the host process. So the adapter module NEVER imports DTALite at module scope; it probes availability with importlib.util.find_spec("DTALite") and raises ModuleNotFoundError(name="DTALite") when absent. models/adapters/__init__.py and models/__init__.py swallow that by exact name (exc.name != "DTALite" re-raises — note the case: the module is DTALite, not dtalite). Engine-version provenance comes from importlib.metadata.version("DTALite"), never an import. A regression asserts import tabench prints nothing to stdout when the model registers (the banner-suppression test unique to this adapter), and that blocking DTALite via a meta_path finder unregisters the model while the numpy core still imports.
CI: a FIFTH job dtalite, a clone of the sumo/torch job shape (py3.12, checkout, setup-python, data cache + prefetch + TABENCH_REQUIRE_DATA=1, pip install DTALite==0.8.1 before pip install -e ".[dev,dtalite]", then only pytest tests/test_dtalite.py). No pip-cache step (the 1.3 MB wheel does not warrant it — the cache overhead exceeds the download). Kept separate from the sumo job (not folded) so either dependency’s breakage cannot kill the other’s signal (the ADR-027 Decision-1 reasoning; here the cost asymmetry that might justify folding does not exist — the wheel is tiny). actionlint-clean.

Decision 2 — the model contract¶

DTALiteTapModel (dtalite-tap), registered with class-level capabilities, in src/tabench/models/adapters/dtalite_tap.py (one module — the mapping is a near-identity so no separate _io module clarifies anything).

Paradigm: reuse "heuristic" (the aon/sumo-marouter precedent). The Evaluator branches on the scenario’s task fields, not the paradigm, so a heuristic-paradigm model earns the certified relative_gap/AEC/Beckmann on static scenarios exactly like aon. We do NOT declare static_ue: white-box status means “internals match the scenario’s declared costs”, and while the engine IS a genuine FW UE solver on the exactly-mapped BPR, the certified gap tells the truth either way. No capabilities.py change, no Evaluator branch, no scenario field, no hash change.
deterministic=True, provides_gap=False, seedable=False. The FW loop has no RNG: link_performance.csv is byte-identical across reruns at number_of_processors=1 (re-confirmed in-tree by md5). Unlike marouter there is no command line to pin a provenance seed on, so seedable=False (the RngBundle root seed still lands in the manifest via seed_info). provides_gap=False: the harness recomputes the gap; the engine’s self-reported gap is recorded as provenance only (§ Measured, it uses a different normalization).
Budget (P6). iterations → number_of_iterations (floored at 1); wall_seconds is threaded as a single deadline through all three phases (write inputs → engine subprocess → parse); sp_calls is unmappable (the engine hides its Dijkstra count): coords.sp_calls = 0, and an sp_calls-ONLY budget raises ValueError up front — never silently unbounded. target_relative_gap is ignored (the engine runs a fixed count, no gap-target hook) — disclosed. Unlike ADR-027, the executed iteration count IS recoverable from summary_log_file.txt, so coords.iterations reports the executed FW count and self_report carries the configured count.
Error surfaces, three distinct. (a) missing DTALite → absent from registry (guard); (b) nonzero exit, timeout, .so load failure in the child, missing/empty link_performance.csv, or a read-back mismatch → RuntimeError with command + stdout/stderr tails (an engine failure is infrastructure, NEVER laundered into feasible=0); (c) emitted-but-bad flows → the normal harness censor path, zero adapter logic. Zero off-diagonal demand → in-adapter exact-zero short-circuit before any subprocess.
Hygiene. Each solve runs in a tempfile dir prefixed tabench-dtalite- (cleanup guaranteed on raise via finally); the keep_files factor keeps it (last_workdir). The child’s CWD confinement means the engine’s ≥9 output CSVs never touch the repo/CWD.

Decision 3 — the compile map is the IDENTITY (the central content)¶

The engine’s per-link VDF, measured and source-confirmed, is t = vdf_fftt · (1 + vdf_alpha · (I/Link_Capacity)^vdf_beta) with I = V/lanes/period_hours/vdf_plf and Link_Capacity = lanes·capacity. Writing lanes = 1, a 1-hour demand period (07:00–08:00), vdf_plf = 1, and the repo values verbatim (vdf_fftt = free_flow_time, vdf_alpha = b, vdf_beta = power, capacity = capacity, toll = 0) collapses this to the repo BPR t = fft·(1 + b·(v/cap)^power) exactly. Five engine traps are neutralized:

Grouped-input requirement (the review CRITICAL). The engine builds its adjacency from contiguous FirstLinkFrom/LastLinkFrom node ranges, so link.csv must be written grouped/sorted by (from_node_id, to_node_id). An ungrouped file silently corrupts routing: a permuted Braess certifies feasible=1 at the WRONG flows (RG 0.208 vs the true 0.0118) and a permuted Sioux Falls sends the FW loop into an infinite loop (which, under an iterations-only budget with no wall, hangs solve() forever). The adapter now writes links sorted by node pair; the read-back matches by node pair, so the emitted order is transparent to it and the solve is permutation-invariant.
The capacity fmax(0.1, cap) clamp (the review MAJOR). The engine clamps capacity at fmax(0.1, cap) in the cost law only (Link_Travel_Time; the Beckmann integral is left unclamped — internally inconsistent below 0.1), so a capacity in (1e-4, 0.1) equilibrates under a DIFFERENT BPR while passing the echo read-back (measured A2 rel 0.93, certified feasible=1 RG 0.799 with false “pure FW truncation” provenance). The adapter refuses any capacity < 0.1, naming the clamp. The engine’s other fmax floors — lanes 0.01, period 0.001, plf 0.0001 — are all neutralized by our fixed lanes=1 / period=1 h / plf=1.
The lanes² trap (measured): for lanes = L the engine divides the ratio by L²·capacity while its own doc column divides by L·capacity — the two agree only at L = 1. The adapter ALWAYS writes lanes = 1 with capacity = the total link capacity, so the assignment-driving cost is the textbook BPR.
Case sensitivity (measured): the engine matches column names case-sensitively and silently ignores an uppercased column (VDF_Alpha → default 0.15). The adapter writes lowercase columns and the read-back (below) catches any that were ignored.
vdf_fftt override: writing vdf_fftt explicitly overrides the length/free_speed-derived free-flow time, so the abstract native cost units pass through verbatim (no mph/km conversion enters the cost). Confirmed: Sioux Falls fft = 6.0 echoes 6.0000 exactly.

Read-back (the house compile-check) — echo checks plus a LIVE A2 cost-match. link_performance.csv echoes vdf_fftt/vdf_alpha/vdf_beta/vdf_plf/link_capacity per link. The adapter verifies every repo link is matched exactly once by (from_node_id, to_node_id), the row count equals the link count (no phantom/dropped link), each echoed parameter equals the declared value within the engine’s float32/4-decimal precision, and the volume is finite. Because the echo check is vacuous below its atol = 1e-3 absolute floor (a doctored/ignored sub-1e-3 vdf_fftt is accepted — the review MINOR), the LIVE gate is a runtime A2 cost-match: the engine’s own travel_time column must equal network.link_cost(flows) on EVERY link (the identity map’s payoff), to relative 1e-3 (measured legit max ~2e-5 on the anchors, ~7.6e-4 on Barcelona’s power-16.83 links). This closes the echo blind spot AND catches the capacity clamp (rel 0.93) and an ignored vdf_fftt (rel 1). Every cell conversion and the file read are wrapped so a corrupt-but-parseable output raises the contract RuntimeError (with stdout+stderr tails), never a raw ValueError/TypeError that would collide with the ValueError refusal channel (the review MAJOR). A mismatch raises RuntimeError — this is what makes returncode == 0 untrustworthy safe: the engine exits 0 on missing files, dropped links, and zone_id != node_id with zero/garbage flows, so success is DEFINED as the read-back (echo + A2 + mass) matching, not the exit code.

BIG-M ceiling → per-origin mass gate (the review MAJOR). The engine’s ~1e7 generalized-cost ceiling silently ZEROES an OD whose congested cost exceeds it (measured: a single link cap=100, power=4 carries demand=9000 but emits 0.0 at demand=10000), producing a well-formed all-zero-flow row that passes the echo/A2 read-back and would otherwise launder to feasible=0. So after the read-back the adapter runs a per-origin mass gate: each origin zone’s emitted outflow must cover its routable demand (through traffic only ADDS, so a shortfall is always an engine drop, never a solution — measured deficit on clean inputs is 0, far below the 4-decimal rounding floor ~1e-4). A deficit raises RuntimeError with the engine diagnostics. The per-origin (not merely total) check covers the multi-OD partial-drop variant.

Wall deadline through the parse phase (the review MINOR). The single wall_seconds deadline is checked after the subprocess AND after the read-back, so a slow large-network parse cannot silently overrun the budget the ADR promises to enforce end-to-end.

Zone convention. Zones are nodes 1..n_zones with zone_id == node_id (the hard engine check); other nodes get zone_id = 0. settings.csv first_through_node_id carries the scenario’s TNTP first_thru_node verbatim — verified to route Sioux Falls (ftn = 1, all 24 nodes are zones) correctly, all 76 links matched.

Measured anchors (all certified by the UNCHANGED harness under the true BPR, P1)¶

Numbers are what the 0.8.1 wheel produced in-tree; bounds in the tests are loose ceilings calibrated to them (version-robust — the .so can shift under the floor).

A1 — Braess (builtin, power=1, the fft=1e-6/alpha=1e7 sentinels). feasible = 1, node balance 0, certified RG 1.183e-2 at 100 iterations, frozen from ~iter 40 (the engine’s Armijo line search collapses to step 0 — the honest convergence ceiling, §”What it means”). The golden Braess content hash cf00f411… is re-asserted byte-identical. The sentinels survive the parse: vdf_fftt = 1e-6 echoes as 0.0 (4-decimal display rounding) but the internal cost still matches (A2 below); vdf_alpha = 1e7 echoes exactly. The representation survives the engine’s CSV float parse — no silent corruption, so the row ships.
A2 — cost-matched anchor (MANDATORY). The engine’s own travel_time column equals scenario.network.link_cost(v) at the emitted volume on every link (the identity map’s payoff — there is no mapping floor to separate out, unlike marouter): measured max relative error 7.1e-6 on Braess (the two sentinel links; the clean links match to ~1e-15) and 2.2e-5 on Sioux Falls power-4 (dominated by the engine’s 4-decimal travel_time column, not a cost-model error). The test pins < 1e-3. This proves the certified gap is pure FW truncation, not a cost mismatch — the row does not ship without it.
A3 — two-route deterministic UE. two_route_scenario(sue_theta=None): feasible = 1, RG = 0.0 (exact UE, flows (2.5, 2.5, 1.5, 1.5)). Needs no theta calibration at all (contrast marouter’s calibrated logit theta) — the engine solves deterministic UE natively, and on this well-conditioned instance exactly.
A4 — Sioux Falls power-4 (the marquee, marouter-impossible). feasible = 1, all 76 links matched, certified RG 5.034e-3 at 100 iterations (frozen from ~iter 100), flow NRMSE 1.58% vs the best-known TNTP UE flows, A2 max-rel 2.2e-5. The first external engine on the power-4 ladder — where marouter’s linear law refused, DTALite’s per-link vdf_beta maps it exactly. The ~5.0e-3 stall floor is a Braess/Sioux-Falls figure; larger nets converge tighter (below).
Big-net exposure (the review’s first large-network run). At the scenario budget (iterations=500), both mixed-power TNTP nets certify with the sort fix and pass the A2 / mass gates: Winnipeg (2836 links, powers 0–6.87) feasible=1, RG 1.176e-3, A2 max rel 5.2e-4, wall ~7 s; Barcelona (2522 links, powers up to 16.83) feasible=1, RG 5.48e-4, A2 max rel 7.6e-4 (the tightest legit A2 margin under the 1e-3 gate), wall ~5.2 s. On both, the engine self-gap equals RG/(1−RG) to 6 digits (the converged regime, below).
Negative controls + review regressions. iterations=1 runs the pure all-or-nothing load (0 FW line searches — measured: number_of_iterations = 1 executes zero loop iterations after the initial AON), certifying feasible = 1 with a much worse gap (Braess RG 1.9e-1) — an honest near-AON row that also pins the dial live: RG(1) > RG(100) (compared at iteration 1, not an intermediate — the gap freezes from ~iter 40, so 5 vs 100 is a plateau). Byte-determinism rerun. The refusal matrix (below). A tiny wall_seconds RAISES RuntimeError, and a slow parse RAISES too (the deadline covers the parse phase). Permuted link arrays reproduce the unpermuted solve (the sort fix). The capacity clamp refuses; the BIG-M drop raises; garbage engine cells and a wrong travel_time raise _ReadBackError (the A2 gate); a torn summary pair keeps the last complete (iter, gap). Read-back rejects a short/phantom output and an ignored VDF parameter. Temp-dir hygiene on the normal and raising paths.

The iterations off-by-one, resolved by measurement. number_of_iterations = N logs Frank-Wolfe iterations 1..N-1 in summary_log_file.txt (N−1 line searches after an initial AON) and labels the link_performance.csv row iteration_no = N. So DOSSIER B’s source read (N → N−1) is correct, not DOSSIER A’s “100 → 100”. N = 1 → 0 line searches = the pure AON (valid, non-empty); N = 0 → accessibility mode (empty output). So the floor is 1 (the AON is a legitimate near-AON row); coords.iterations reports the executed N−1, and self_report.engine_configured_iterations = N.

The self-reported gap definition, resolved by measurement. The engine’s printed gap is (TSTT − SPTT)/max(0.1, SPTT) in percent (a clamped SPTT/least-TT denominator), whereas the repo’s certified relative_gap normalizes by TSTT. On converged anchors it equals RG/(1−RG) to 6 digits (verified on Sioux Falls, Winnipeg and Barcelona; Braess engine 0.011978 vs RG/(1−RG) 0.011976), so it is NOT the repo gap. Off the converged regime it can be negative or frozen (a stalled instance emits a stale/SPTT>TSTT gap; the 0.1 denominator clamp distorts it further). It is recorded as self_report.engine_relative_gap (provenance only); the row is certified on the harness value alone, and the self-report is never gated on.

Refusals (naming the field)¶

sue_theta, elastic_demand, combined_demand, br_epsilon, side_capacities, link_interaction, multiclass each raise ValueError naming the field (the engine’s static assignment() cannot represent them in a certifiable form). Nonzero fixed_cost (toll_weight·toll + distance_weight·length) is refused: the engine HAS a toll column, but its toll/vot time-conversion is unvalidated and a negative toll KILLS the host process, so tolls are refused now (the possible lift is recorded here, not silently run — unlike marouter, where a toll model is impossible). A link capacity < 0.1 is refused up front (the engine’s fmax(0.1, cap) cost-law clamp would equilibrate it under a different BPR; a capacity ≤ 1e-4 is also silently dropped). An sp_calls-only budget is refused (no Dijkstra count is exposed); sp_calls = 0 is disclosed. multiclass is the natural sprint-2 extension (the engine does native multiclass via mode_type.csv), refused here pending a per-class-flow certificate.

What the certified row MEANS (headline discipline, adr-025/027)¶

The row is the honest engine Frank-Wolfe convergence under an exactly-represented cost law. Because the compile map is the identity and A2 proves every link’s cost matches, the certified RG at budget B is FW truncation error — and here that truncation is the engine’s own line-search stall: the Armijo backtracking collapses to step 0 within a few iterations (measured: gap frozen from ~iter 40 on Braess, ~iter 100 on Sioux Falls) and never recovers, so the certified gap floors at ~1e-2…1e-3, far above a converged bfw’s ~1e-16 (pinned: bfw beats it by orders of magnitude on Braess). The headline names WHOSE equilibrium and WHICH axis: “DTALite’s static assignment certifies RG X at N iterations on the same BPR the white-box solvers optimize — the first external engine scored on the power-4 ladder; bfw/algb beat it on the convergence axis, as expected.” The ceiling is the wheel-engine-as-shipped’s line-search stall, not the mapping (there is none) and not the benchmark.

Alternatives considered¶

path4gmns (the sounder engine) — the sibling PyPI package (Peiheng Li + Xuesong Zhou) exposes an in-process find_ue/find_ue_fw with iteration AND target-gap parameters and a returned gap (a cleaner P6 map than a zero-argument CWD-coupled ctypes call), real license text, and active maintenance. It was NOT chosen for sprint 1 only because dtalite-adapter is the named sprint target with the journal anchor (zhou2014dtalite); path4gmns has no journal tool paper of its own (a GitHub citation only). Recorded as a possible future row — same GMNS dialect and datasets, the same honest-sourcing caveat (validate the adapter+engine artifact, not paper numerics).
simulation() (mesoscopic DTA) — the engine’s separate DTA_SimulationAPI is the Zhou & Taylor (2014) queue-based within-day simulator (agent/trajectory outputs). None of the repo’s dynamic certifiers (dta/, dnl/, estimation_dynamic.py) accepts an external simulator’s trajectories on a static TNTP scenario; wiring one needs a new dynamic scenario family + certificate ADR — a named non-goal here (the follow-up on the DTA/DNL ladder, where the 2014 paper is genuinely on-point).
The engine’s built-in ODME (odme_mode, Lu/Zhou/Zhang lineage) — a named future T2 guarded estimator, the spsa-sumo (adr-028) analog: the same adapter reused inside the estimation track, certified by the unchanged pinned-bfw certifier. Not in sprint 1.
In-process ctypes — disqualified (§4): ExitMessage = getchar() + exit() in-process would hang or kill the harness, assignment() reads/writes CWD (needing process-global chdir), and a second call in one process doubles the flows.
A new external/static_ue paradigm token or an Evaluator branch — none built; the heuristic paradigm + the existing certificate already score the row honestly, and the golden Braess hash is re-asserted byte-identical.

Honest sourcing (the central section)¶

zhou2014dtalite anchors the software LINEAGE, not the formulation (tool-paper discipline, exactly as ADR-027 did for lopez2018microscopic). The Cogent Engineering 2014 paper (read in full: CC-BY 3.0, DOI 10.1080/23311916.2014.961345) describes a mesoscopic queue-based simulator + ODME and contains no BPR/VDF anywhere — its “assignment” is gradient-projection path-flow adjustment toward a gap-function DUE, specified only by citation (Lu, Mahmassani & Zhou 2009). It reports no equilibrium benchmark numerics (the Triangle Regional case study is proprietary and un-shipped), so like lopez2018microscopic it is a tool-paper anchor: the row validates adapter + engine fidelity, never the paper’s numbers.
What assignment() actually is. The wheel’s only C++ is TAPLite.cpp, whose header states it is “built based on … Bar-Gera’s FW.zip”. DTALite.assignment() → DTA_AssignmentAPI() is therefore a classic static link-based Frank-Wolfe TAP loop on BPR costs, derived from Bar-Gera’s FW.zip — the 2014 paper’s mesoscopic DUE machinery is NOT exercised (that is the separate simulation() entry). The model card says so explicitly. Wheel↔source identity was cross-checked two ways (nm -D exports exactly DTA_AssignmentAPI/DTA_SimulationAPI; the .so’s format strings match TAPLite.cpp), but the wheel binary is not provably built from the public source — the behaviors here are the executed wheel’s, version-scoped to 0.8.1.
Artifact provenance. PyPI DTALite 0.8.1 (2025-04-08), authors Fang Tang + Xuesong Zhou, home github.com/itsfangtang/DTALite_release; the release’s own citation line is “Tang, F., Zheng, H., and Zhou, X. (2025)”. A young package (4 releases). The PyPI metadata asserts Apache 2.0, but the LICENSE file in the source repo is empty (0 bytes) — GitHub reports SPDX NOASSERTION. For CI consumption (pip install, run the artifact) this is acceptable (the metadata grant is the authors’ declaration, nothing is copyleft), but the repo vendors no engine code and commits no sample data (the TNTP-derived data_sets/ are academic-use-only with no license metadata; the harness generates its own Braess/two-route GMNS and downloads Sioux Falls checksummed on demand, P9). The empty-LICENSE state is recorded here.

Wall math¶

One wall_seconds deadline is computed once from solve() start and threaded through input-writing → the single engine subprocess → output parsing (only one subprocess phase, unlike marouter’s two). With OMP_NUM_THREADS = 1 (belt-and-braces with number_of_processors = 1 — the engine’s default OpenMP thread count is all cores, pure spin: measured Sioux Falls 8.5 s wall by default vs 0.1 s at OMP_NUM_THREADS=1), a solve is python startup + import DTALite (banner + .so load) + assignment() + output write ≈ 0.5 s (Braess/two-route trivially; Sioux Falls 100 FW iterations ~0.1 s CPU). The CI job: setup ~40 s, install ~20 s (1.3 MB wheel), data prefetch cached, anchors seconds → ~1.5–3 min.

Consequences¶

New: DTALiteTapModel (dtalite-tap, registered when DTALite present); src/tabench/models/adapters/dtalite_tap.py; the dtalite optional extra; one CI job (the fifth); tests/test_dtalite.py (26 tests — A1–A4, the near-AON/monotonicity/ determinism controls, the refusal + sp_calls-only + wall-timeout gates, the read-back gate, temp-dir hygiene, the banner-suppression + core-install guard unique to this adapter, and the review regressions: the permuted-links sort, the capacity-clamp refusal, the BIG-M mass-gate raise, the garbage-cell + wrong-travel_time A2 read-back, the parse-phase deadline, and the summary torn-pair). No new certificate, scenario field, Evaluator branch, or paradigm; no change to capabilities.py, gaps.py, or any hash.
Unchanged: the Evaluator, the fairness gate, every hash (the golden Braess content hash is re-asserted byte-identical in the new test file), and the numpy-only core (import tabench and the full suite pass without the wheel — the dtalite-free matrix legs are the live regression).
Follow-ups: the mesoscopic simulation() DTA row (a different equilibrium concept, the DTA/DNL track); the built-in ODME as a T2 guarded estimator (the spsa-sumo analog); a path4gmns static row (the sounder API, no journal anchor); the toll/vot lift of the fixed_cost refusal (once the time-conversion is validated); multiclass via mode_type.csv — note the read-back/mass gate consume the pce-weighted volume column, which equals mod_vol_auto at pce = 1 (the single-mode case); a multiclass lift must switch to the per-mode mod_vol_<mode> columns and needs a per-class-flow certificate.

Adversarial review¶

Three independent lenses (soundness, formulation, numerics), each executing Python/pytest against the running 0.8.1 wheel; every finding CONFIRMED by a runnable repro and fixed with a per-finding regression (streak: 18/18 sprints with at least one material defect; 26 dtalite tests after the fixes, from 19).

CRITICAL (soundness): an ungrouped link.csv corrupts the engine’s adjacency. The engine builds routing from contiguous FirstLinkFrom/LastLinkFrom node ranges, so a link.csv NOT grouped by from-node silently mis-routes: a permuted Braess certified feasible=1 at the WRONG flows (RG 0.208 vs 0.0118), and a permuted Sioux Falls sent the Frank-Wolfe loop into an infinite loop — which, under an iterations-only budget (timeout=None), hangs solve() forever. FIXED: _write_gmns writes links sorted by (from_node_id, to_node_id); the read-back matches by node pair, so the solve is now permutation-invariant (pinned by a permuted-Braess-reproduces-the-solve regression).

MAJORs, all fixed + pinned: (a) the engine clamps capacity at fmax(0.1, cap) in the cost law only (the Beckmann integral unclamped), so a capacity in (1e-4, 0.1) equilibrated under a DIFFERENT BPR with a passing echo read-back (measured A2 rel 0.93, false “pure FW truncation” provenance) — the refusal threshold is raised to < 0.1, naming the clamp; (b) the ~1e7 BIG-M cost ceiling silently ZEROES an OD whose congested cost exceeds it (single link cap=100 power=4: demand=9000 → 9000, demand=10000 → 0), laundering to feasible=0 — a per-origin mass gate now RAISES on any origin whose outflow fails to cover its demand; (c) a corrupt-but-parseable engine output raised a raw ValueError/TypeError that escaped solve() and collided with the ValueError refusal channel — every cell conversion and the file read are now wrapped to _ReadBackError → the contract RuntimeError with stdout+stderr tails.

MINORs, fixed: the echo read-back was vacuous below its atol=1e-3 (a doctored/ignored sub-1e-3 vdf_fftt was accepted) — a runtime A2 cost-match (engine travel_time == repo BPR at emitted flows on every link, rel 1e-3) is now the live gate, catching both the fftt drift and the capacity clamp; the wall deadline did not cover the parse phase (a slow parse overran a 1.5 s budget to 3 s) — one deadline now bounds the read-back too; the summary parser could pair an iter from one line with a stale gap from another under format drift (now commits the two together); the zero-demand path omitted engine_configured_iterations (now emits both keys); the self-gap docstring overstated the 1/(1−RG) relation (scoped to the converged regime — it can be negative/frozen off it).

Survived (highlights): Anaheim ftn=39 end-to-end — the explicit first_through_node_id semantics match TNTP exactly on grouped input (feasible=1, RG 5.94e-5, ZERO through-centroid traffic against a bfw detector control); illegal- shortcut flows cannot certify a negative gap (the Evaluator’s nonnegative-excess audit censors them); the identity compile map re-verified by the A2 cost-match on every link across Braess, Sioux Falls, a 60-net random adversarial parameter sweep (fft 1e-6..1e3, b 0..1e7, power {0, 1, 2.5, 4, 6.87}, zero law mismatches), Winnipeg (2836 links, powers 0–6.87, RG 1.176e-3) and Barcelona (2522 links, powers to 16.83, RG 5.48e-4) — the first big-net exposure, both feasible=1 and A2 ≤ 7.6e-4 under the 1e-3 gate; byte-determinism across reruns and under a hostile parent OMP_NUM_THREADS=64 (the child override wins); 8-way parallel solves with no cross-talk; the mid-engine wall kill (no leaked tempdirs, no zombie children); the banner-suppression + core-install guard (blocked-DTALite unregisters the model, import tabench stdout empty); the ValueError-refusal vs RuntimeError-crash separation; CI install-order simulation in fresh venvs (pin-first, no re-resolution; the core leg collects 731 tests without the wheel); temp-dir hygiene across the normal/refusal/raise/timeout paths; the golden Braess content hash re-asserted byte-identical.

ADR-029 — DTALite assignment(): the second external engine, and the identity-map static-UE row¶