ADR-010: dnl-core — generic supply/demand dynamic-network-loading foundation

Status: accepted (implemented in v1) Deciders: dnl-core design panel (3 competing designs, judged) → synthesizer Date: 2026-07-07 File: docs/design/adr-010-dnl-core.md

Context

TASKS.md Phase 2 opens with dnl-core: the time-expanded / cell infrastructure that five later sprints must share without rework — ctm (Daganzo 1994/95), ltm (Yperman 2007), newell-kw (Newell 1993), godunov (Lebacque 1996), and node-model (Tampère et al. 2011). The foundation has to anticipate all five link/node paradigms, emit a P1-certifiable artifact, and stay strictly additive — the static machinery is frozen and the golden Braess content hash cf00f411cdccec88019979e8cfbf3d8014ba590688b285a1db667315ac96762d must remain byte-identical.

Decision

  1. Generic sending/receiving (S/R) architecture. Every link model exposes sending(k) / receiving(k) in vehicles-per-step (dnl/link.py); node models allocate transfer flows from (S, R, turning fractions, capacities) under the Tampère first-order node axioms (dnl/node.py); time-indexed per-link cumulative curves n_in / n_out at grid edges are the canonical emitted output (dnl/output.py::DNLOutput). CTM, LTM, Newell and Godunov all become LinkModel subclasses with no interface change — Lebacque demand/supply on the FundamentalDiagram ABC (dnl/fd.py), whose envelope_params() triangular majorant keeps every certificate a necessary condition for any concave FD.

  2. New, domain-separated scenario construct. DynamicScenario (dnl/scenario.py) reuses the static Network topology read-only and adds LinkDynamics + piecewise-constant DynamicDemand + TimeGrid + optional TurningFractions. It hashes under a "tabench-dnl-scenario-v1;" domain prefix over exactly the scored content (topology, KW physics, demand, grid, turns) — the static BPR fields are ignored and unhashed (P2: hash exactly what is scored). core/scenario.py is never edited, so no static hash can move (re-asserted in the dnl tests).

  3. P1 certification in metrics/dnl_gaps.py. From (DynamicScenario, DNLOutput) alone the harness recomputes, censoring on any gating failure (dnl_feasible = 0, scored quantities NaN, residual columns populated — mirroring metrics/gaps.py):

    • C0 validity (finite, zero-start, monotone, matching grid, scenario-hash),

    • C1 conservation (per interior node + per step, per-origin coupling, global vehicle identity),

    • C2 capacity (both boundary fluxes ≤ q_max · dt),

    • C3 storage bounds (nonnegative; ≤ κ·L on finite-jam links),

    • C4 free-flow causality (grid-edge-relaxed Newell upper envelope),

    • C6 FIFO / travel-time consistency (level-matched curve inversion),

    • C7 demand coupling (release ≤ cumulative demand). C5 (backward-wave envelope) is a non-gating Tier-B residual with two-level flags: standard CTM at CFL = 1 under spillback provably violates the sharp bound via numerical hole diffusion, so gating it would falsely censor a correct convergent scheme; the raw residual is always reported so no threshold hides a real violation. Scored TSTT / delay / unserved / completed / in-network are recomputed from counts, never trusted.

  4. Sanctioned operating point = CFL = 1 on cell-aligned grids. The grid-edge relaxations (C4, and C6’s travel-time face) are exact when L/(vf·dt) is an integer and conservative by at most one step otherwise. Gating conformance is promised only at CFL = 1; the ctm/godunov sprints must ship congested-instance conformance regressions before leaderboard use. Unaligned (CFL < 1) schemes are answerable to the always-reported raw residuals, not the gate.

  5. Test-only reference link. dnl/_reference.py::PointQueueLink (Vickrey-lineage point queue; never registered as a benchmark model) exercises every interface without pre-empting the ctm sprint. Two analytic anchors are hand-derived AND machine-verified: single_link_dynamic_scenario (free-flow translation, TSTT = 5.0, zero delay) and bottleneck_dynamic_scenario (2-link corridor queue build/dissipate).

Alternatives considered

  • Cumulative-curve-native banks with path demand (design 1): rejected on minimality — path demand departs from the repo’s OD world and pre-loads FIFO machinery the five sprints don’t need. Its Tier-B semantics for the backward-wave bound was adopted (Decision 3).

  • Time-expanded vectorized engine with CSR commodity bookkeeping (design 2): rejected on foundation weight, but its envelope majorant, trapezoidal q_cap FD, node-capacity signature and PQ-spillback fixture were adopted.

  • Extending core.Scenario with optional dnl fields (the static house pattern): rejected — it edits a frozen file and drags BPR bytes into DNL identity.

Known limitations & deferred hardening

Recorded honestly from the post-implementation adversarial reviews (2026-07-07, and the gated DNL review 2026-07-09 that landed the two items below):

  • C6 false-censor fixed; off-CFL completeness honestly scoped (landed 2026-07-09). C6 was reformulated as the per-entered-level (Newell travel-time) restatement of C4’s free-flow envelope: each count level’s exit-inverse time is checked against the entry curve at the grid edge at-or-after t_out(L) − L/vf — C4’s own one-step relaxation, over levels drawn from the union of both curves. This removes the old O(dt) false-censor off CFL = 1 (a correct emission now passes). The gated review’s key correction: C6 adds no coverage over C4 — an empirical fuzz (~2M trials) and a short monotonicity argument show C4-passing implies C6-passing — so it is a redundant, independently-derived restatement of C4 (belt-and-suspenders against an implementation bug in either check, plus the per-vehicle travel-time residual), not a gap-closer, and a genuine off-CFL sub-step violation still slips past both. So C6, exactly like C4/C5, is gating-complete only at CFL = 1; off it the raw fifo_residual is the science, not the flag. The earlier “sample the union … and it closes the false-accept” plan was retired as unsupported. No shipped scenario is unaligned, so the residual gap stays latent.

  • Turn-fraction fidelity gated at every diverge as C8 (landed 2026-07-09). scenario.turns is now read: at any node with ≥ 1 incoming and ≥ 2 outgoing links, d_in[out_j] == Σ_i frac[i, j] · d_out[in_i] is checked every step. Because each incoming link’s outflow d_out[in_i] is observed separately, this is decidable from aggregate single-commodity counts at multi-in nodes too — the original “underdetermined at a multi-in node” belief was wrong, and the gated review caught that the 1-in-only draft silently certified a gross merge-diverge violation. The check is node axiom N4 (Daganzo 1995 CTF), a necessary condition that holds per step even under a congested FIFO diverge (whole approach held back in ratio) and a supply-limited merge (each realized transfer already in d_out[in_i]), so it never false-censors a correct emission. It is sufficient at a 1-in diverge (aggregate ≡ the single row); at a multi-in node it is necessary but not sufficient — a wrong per-row split whose rows cross-cancel to the correct column totals is unobservable from per-link aggregate counts (the same aggregate-vs-per-commodity limit C6 FIFO carries; reserved for a per-commodity emission). No shipped scenario has a diverge, so the gate is inert until one ships.

  • Certificate test coverage. The review found four surviving mutations (tolerance magnitude, C2 inflow-side, C1 origin-coupling, C6 plateau convention). Regression tests pinning each were added in the hardening commit and this scope was documented in the module docstring.

  • Open questions carried for the implementing sprints: origins-first supply convention (R1), per-link Python objects at corridor scale (R3), OriginNode multi-out split placeholder (R4), Budget/Trace integration deferred to the DTA-runner sprint (R6), multi-commodity per-destination emission as a strict additive superset (R7), time-varying turning fractions as a v2 hash bump (R8).

Consequences

The five downstream sprints implement LinkModel / NodeModel subclasses only. All DNL work is additive; static golden hashes are provably untouched (re-asserted in tests/). Certificates are recomputable, censor-first, and honest about what aggregate single-commodity counts can and cannot falsify (within-link overtaking is not observable; spillback fidelity is reported, not gated; CFL < 1 and turn fidelity are scoped, not silently certified).

Sourcing

Paywalled primaries are attributed unread; equations are taken from open restatements and cross-verified; no DOIs or page-precise quotes.

  • Daganzo (1994) TR-B 28(4) + (1995) Part II TR-B 29(2) — CTM cell demand/supply mins and the (vf, w, kj, q_max) trapezoidal form, cross-verified from open restatements (Yperman thesis; mirrored lecture notes). Unread.

  • Yperman (2007) The Link Transmission Model for Dynamic Network Loading, PhD thesis, KU Leuven — open; primary source for LTM sending/receiving in cumulative form and per-step vehicle-count conventions.

  • Newell (1993) “A simplified theory of kinematic waves” Parts I–III, TR-B 27(4) — the two cumulative-curve envelopes (C4/C5) restated openly. Unread.

  • Lebacque (1996) “The Godunov scheme and what it means for first order traffic flow models” (ISTTT 13) — demand/supply Δ/Σ formalism; open restatements circulate.

  • Tampère, Corthout, Cattrysse, Immers (2011) “A generic class of first order node models” TR-B 45(1) — paywalled, unread; requirements N1–N6 restated from Yperman (open) and Lebacque & Khoshyaran (2005, invariance). The node-model sprint re-verifies its requirement list against whatever open restatement it implements.

  • Vickrey (1969) — point-queue lineage for the test-only reference link; attribution only.