tt-model push diffusion-planner-p150 (container)

.gitattributes

@@ -33,3 +33,27 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/069395655fd57335d9426528f7f49731be6cf7ed963ca649e4ff7c9697d37e0a filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/0936b6c31255cfe6d029dab00fc251d8771f5e3d228ac7da23e395e1161c6992 filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/3ac9de4540f40bdf99f054641b2fb36a38f49253d1727fb08a73272d4208ce1b filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/46f21edbef18d35cb9e2f400eeb6d8f8fac5873f8620e8d96829a9c01447ed52 filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/98c4455a98982b35380ec62f90d5cf0edff02eeb4b3bb18595d871fdeb0c0c67 filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/a15921f6aeba449853d8dfc7215c466ad00cff30329183f8b839522d33bc6552 filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/be04a2af1cfe08908467229c0dd35fc629cb65ba98a497e7b627499f0c76821b filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/c006f8f8bd1ac6c419a231b5d94521d87d03b141b76873d7a4d7fb68a933e57a filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/c74a07e1fb0aaf18cdccf3f41385a21dd137109c155363830e2ac2c565d7ac43 filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/ca0cef561ac457e6f5fe6e064c167bfc523b6e975437121969a8f39630a0a424 filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/d447e3306f087f0a9b594fb8a92f46880560372c42349c9fc8c10e5bb634aadd filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/e1ff664083a6df132a0751cb98c17c425fd5908c3434270f38e2de56763f06ba filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/e324ba29d9a1eb6f52840139e2d929d488845bcadb738439b521f7900e1e22a3 filter=lfs diff=lfs merge=lfs -text
+image/blobs/sha256/fc48d390b577ea739097ee841cf6e598acbbe40f0f42571c6cb450d57d7a09f2 filter=lfs diff=lfs merge=lfs -text
+media/dp_kashiwanoha_dense_tt_vs_cpu.png filter=lfs diff=lfs merge=lfs -text
+media/dp_nuscenes_scene-0061_bev_tt_NC.gif filter=lfs diff=lfs merge=lfs -text
+media/dp_nuscenes_scene-0061_kf06_bev_tt_NC.png filter=lfs diff=lfs merge=lfs -text
+media/dp_nuscenes_scene-0061_kf18_bev_tt_NC.png filter=lfs diff=lfs merge=lfs -text
+media/dp_nuscenes_scene-0061_kf18_cam_front_tt_NC.jpg filter=lfs diff=lfs merge=lfs -text
+media/dp_nuscenes_scene-0103_kf12_bev_tt_NC.png filter=lfs diff=lfs merge=lfs -text
+media/dp_nuscenes_scene-0103_kf12_cam_front_tt_NC.jpg filter=lfs diff=lfs merge=lfs -text
+media/dp_nuscenes_scene-0757_kf11_bev_tt_NC.png filter=lfs diff=lfs merge=lfs -text
+media/dp_nuscenes_scene-0916_kf11_bev_tt_NC.png filter=lfs diff=lfs merge=lfs -text
+media/dp_straight_road_tt_vs_cpu.png filter=lfs diff=lfs merge=lfs -text

OPT_BASELINE.md

@@ -0,0 +1,535 @@
+# diffusion-planner-p150 baseline on the p150 (before optimization)
+
+Date 2026-10-08. Code is the baseline commit `5541833` (first correct port, no optimization): the port's last commit
+`34b6049` plus ttaw re-vendored to 0.17.1 and two measurement scripts, `code/scripts/bench.py` (rewritten: the full
+stage table) and `code/scripts/profile_ops.py` (new). `git diff 34b6049 5541833` touches no model code (`tt/`,
+`host/`, `reference/`, `api.py`, `device.py`, `io.py`, `server/` are unchanged).
+tt-metal `44d66500520` (v0.80.0-dev20261006-78) + the ETH-dispatch patch (workspace `patches/tt-metal-eth-dispatch.patch`,
+sha256 `08d0ddf6…45cc`, 4 files; `eth_patch: true` in every log). ttaw 0.17.1 @ common `290f22b`
+(`code/tt_diffusion_planner/ttaw/VENDORED.json`; `vendor.py --check`: 0 differences). Weights
+`AutowareFoundation/diffusion_planner` @ `423efde67f5` (tag `v5.0`). Input: `code/tt_diffusion_planner/samples/kashiwanoha_dense.npz`
+(one planning instant on the kashiwanoha test map: 88 neighbours, 123 lanes, 17 route lanes, 60 line strings, ego at
+6 m/s), batch 1. The stage bench also runs `straight_road.npz` (shipped) and one public-data instant, nuScenes
+v1.0-mini `scene-0103_kf14` (42 neighbours, 103 lanes, 7 route lanes, 10 polygons, 26 line strings; CC BY-NC-SA 4.0,
+used locally, never shipped).
+
+Configuration of every number unless a row says otherwise: ETH dispatch, 1 CQ, 12×10 grid
+(`device.compute_with_storage_grid_size()` printed in each log), one p150b (KMD 2.10.0, firmware bundle 19.13.1.0).
+AICLK 1350 MHz: sysfs `tt_aiclk` was sampled every 50 ms during every bench, median 1350 MHz and min 1343 MHz. Board
+power had a median of 76 W and a max of 86 W, at 63-68 °C. The profiler CSV header also gives 1350 MHz. The host is
+shared (AMD EPYC-Rome, 8 vCPUs, up to 8 other agents, load average 8-12 during these runs), so host-side stages are
+quoted as p50 / p99 (min).
+
+## Summary
+
+| | baseline |
+|---|---|
+| device latency per plan (one trace replay + sync) | **102.13 ms** p50, 104.81 p99, 102.05 min |
+| back-to-back replays (device time per plan) | **102.04 ms** = 9.80 plans/s; the same on all three scenes (dense capacities) |
+| `model(inputs=arrays)` end to end | **117.90 ms** p50, 134.56 p99, 112.87 min (`.npz` path: 124.76 ms) |
+| programs per plan (device profiler, traced replay) | **6,282** (309 unique programs; the fake-ttnn count was 6,408) |
+| device kernel sum / op-to-op gaps / span (profiled replay) | 99.27 / 4.39 / 103.66 ms. Kernel-bound, not gap-bound: the median program runs 5.76 µs, and 4,126 programs under 10 µs add up to 19.2 ms |
+| largest single sink | the encoder's channel-MLP and pre-projection matmuls on 4-D `[1, E, T, C]` activations, which run on **4-8 cores**: 90 programs, **25.8 ms** (the 10 slowest programs of the plan are all neighbour-mixer channel matmuls, ~970 µs each) |
+| cost of the numerics defaults (PORT_LOG decision 11), re-measured | **+33.4 ms** over the round-1 defaults (68.64 ms b2b) and **+58.3 ms** over the fastest graph (43.74 ms, which fails the gates). Per knob: decoder split matmuls 20.2, fp32 LayerNorm 18.1, fp32 matmul attention 15.5, encoder split matmuls 6.0 ms |
+| dispatch / CQ (D14) | ETH-1CQ stays. WORKER is equal (−0.17 ms on 11×10). 2 CQs cost +9.8 ms on ETH (±0 on WORKER) |
+| accuracy | 44 device tests, every gate value and all 99 per-scene e2e numbers identical to the port's final run |
+
+## How to run
+
+```bash
+ROOT=/home/ubuntu/experiments/tt-models; cd $ROOT/bundles/diffusion-planner-p150; source $ROOT/bin/tt-env.sh
+export PYTHONPATH=$PWD/code:$PYTHONPATH HF_HUB_OFFLINE=1   # weights: $DIFFUSION_PLANNER_WEIGHTS_DIR > workspace assets > HF cache
+# accuracy gates (per-module PCC + end-to-end agreement vs the fp32 CPU reference; 99 scenes with the workspace goldens)
+$ROOT/bin/devrun -t 1800 -- env TTAW_GATES_READONLY=1 python -m pytest -q -s \
+    code/tt_diffusion_planner/tests/test_pcc_device.py code/tt_diffusion_planner/tests/test_e2e_device.py
+# stage breakdown (load / host_pre / pack / host_in / H2D / trace / D2H / host_post / e2e / b2b: p50, p99, min; AICLK)
+$ROOT/bin/devrun -t 900 -- python code/scripts/bench.py --iters 100 --json /tmp/bench.json \
+    --input code/tt_diffusion_planner/samples/kashiwanoha_dense.npz --input code/tt_diffusion_planner/samples/straight_road.npz \
+    --input $ROOT/research/diffusion-planner/public_data/inputs/nuscenes/scene-0103_kf14.npz
+# dispatch / CQ matrix: the same per configuration, one process each: --dispatch eth|worker --num-cqs 1|2
+# numerics cost: the same with DIFFUSION_PLANNER_SPLIT_MATMUL / _LN_FP32 / _ATTN_MATMUL set (timing only, see below)
+# device profile: one eager plan (stage + layer-kind signposts) and one traced replay, between signposts
+$ROOT/bin/devrun -t 3600 -- python -m tracy -r -p -v --op-support-count 16000 --no-web-server \
+    -o $ROOT/generated/profiler/diffusion-planner_baseline code/scripts/profile_ops.py
+tt-perf-report <ops_perf_results_*.csv> --start-signpost trace --end-signpost trace_end --arch p150
+python $ROOT/logs/diffusion-planner/baseline/scripts/analyze_profile.py <the same csv> out.json --md out.md
+```
+
+The job scripts of this baseline are in `logs/diffusion-planner/baseline/scripts/` (workspace):
+
+- `windowA.sh` (one devrun window, 04:35-04:58 UTC): job 1, the device suite and the alloc-tracking run; then job 2,
+  the bench and the dispatch / CQ matrix.
+- `windowB.sh` (05:54-06:15 UTC): job 3, the numerics ablation; job 4, the Tracy profile; job 5, the
+  ttnn-visualizer captures.
+- `host_suite.sh`, `analyze_profile.py`, `profile_breakdown.py`, `tables.py`, `fake_flops.py`, `visualizer_*.py`.
+
+The plan issues 6,282 programs, more than the profiler's default 1,000-program buffer. So the profile runs with
+`--op-support-count 16000`: 48 B per program per RISC, about 77 MB of DRAM per channel. `ttnn.ReadDeviceProfiler` is
+called before and after each section, and nothing was dropped (no full-buffer warning).
+
+## Accuracy (baseline)
+
+Re-run on this commit after re-vendoring ttaw 0.11.0 -> 0.17.1, with the gates read-only:
+
+- device suite: **44 passed** in 48.6 s, and 44 passed again under `TT_METAL_TRACE_ALLOC_TRACKING=1`;
+- every gate value and every per-scene number of the 99 scenes is identical to the port's final run (job 19, ttaw
+  0.11.0);
+- host suite on the fake ttnn: 105 passed, 46 skipped (the 44 device tests, the ORT module, one dead test).
+
+Logs: `logs/diffusion-planner/baseline/device_suite.log`, `alloc_tracking.log`, `e2e_device.json`, `host_suite.log`.
+
+| check | gate | baseline |
+|---|---|---|
+| `enc.ego` / `enc.neighbor` / `enc.lane` / `enc.route` / `enc.polygon` / `enc.line_string` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 0.999972 / 0.999952 / 0.999992 / 0.999998 / 0.999994 / 0.999998 |
+| `enc.goal` / `enc.ego_shape` / `enc.turn` PCC | ≥ 0.999 | 0.999991 / 1.000000 / 0.999995 |
+| `enc.encoding` PCC (valid tokens) | ≥ 0.999 | 0.999978 |
+| `dec.eval` PCC (teacher-forced decoder, min over the 11 evaluations x 2 samples) | ≥ 0.999 | ≥ 0.9999995 (prints 1) |
+| end-to-end ego trajectory vs the reference, max over 99 scenes (2 samples, 5 research scenes, 92 nuScenes-mini instants): max / mean displacement | ≤ 1.0 m / ≤ 0.3 m | 0.313 m / 0.143 m (both on nuScenes scene-0103_kf14) |
+| turn-indicator command identical | = 1.0 | 99 / 99 |
+| neighbours: median per-agent max displacement, max over scenes | ≤ 1.5 m | 0.086 m |
+| CPU reference vs ONNX Runtime on the shipped ONNX (checks the reference itself; research venv, PORT_LOG 5.1) | ≥ 0.9999 | final x0 PCC ≥ 0.9999999999982 (7 scenes), ≥ 0.99999999983 (92 nuScenes instants); 48 tests passed |
+
+## Performance (warm, batch 1, 100 iterations per stage)
+
+`code/scripts/bench.py --iters 100` (job 2, `matrix_eth-1cq.{log,json}`):
+
+- `trace` is one replay of the whole plan plus a device sync, as served;
+- `b2b` is the device time per plan over 50 back-to-back replays (3 rounds);
+- `e2e` is `model(inputs=<decoded arrays>)`, and `e2e_path` is `model(inputs=<.npz path>)`.
+
+Values are ms, p50 / p99 (min).
+
+| stage | kashiwanoha_dense (shipped default) | straight_road (shipped) | nuScenes scene-0103_kf14 (public data) |
+|---|---:|---:|---:|
+| `load`: `.npz` decode + schema check (path inputs only) | 7.02 / 18.20 (5.79) | 6.75 / 16.81 (5.86) | |
+| `host_pre`: the node's pre-processing | 4.76 / 12.55 (3.84) | 4.32 / 12.58 (3.57) | 4.25 / 6.16 (3.74) |
+| `pack`: the 19 persistent trace inputs | 0.45 / 4.52 (0.36) | 0.44 / 1.06 (0.38) | 0.43 / 0.69 (0.34) |
+| `host_in`: TILE host tensors | 2.41 / 6.80 (2.02) | 2.41 / 6.79 (2.00) | 2.31 / 3.35 (1.92) |
+| H2D (19 tensors, 3.6 MB) + sync | 1.14 / 6.32 (0.90) | 1.09 / 5.43 (0.91) | 1.03 / 2.72 (0.90) |
+| **device trace, one blocking plan** | **102.13 / 104.81 (102.05)** | 102.14 / 104.32 (102.07) | 102.13 / 102.19 (102.05) |
+| **back-to-back trace replays, per plan** | **102.04** (rounds 102.09, 102.04, 102.04) = 9.80 plans/s | 102.04 | 102.04 |
+| D2H (one packed read, 460 KB) | 0.58 / 4.24 (0.31) | 0.59 / 1.50 (0.36) | 0.56 / 0.75 (0.30) |
+| `host_post`: the node's post-processing | 4.32 / 11.54 (3.57) | 3.91 / 9.47 (3.29) | 3.93 / 6.96 (3.50) |
+| **e2e `model(inputs=arrays)`** | **117.90 / 134.56 (112.87)** | 126.58 / 144.70 (114.23) | 114.52 / 122.91 (113.05) |
+| e2e `model(inputs=path)` | 124.76 / 147.74 (118.99) | 121.92 / 143.29 (118.41) | |
+
+- **Timing breakdown.** `model(...).timing_ms` p50 (kashiwanoha):
+  - preprocess 4.77 ms;
+  - device 106.83 ms (`host_in` + H2D + replay + D2H + unpack);
+  - postprocess 4.36 ms;
+  - total 117.35 ms.
+- **Start-up.** The first call after `from_pretrained` takes 118.2 ms (1.0x). `from_pretrained` takes 11.6 s with a
+  warm kernel cache: ~5.1 s to open the device, 0.75 s to build (read the ONNX weights and upload them), 5.8 s to warm
+  up and capture.
+- **The device time does not depend on the scene.** All three scenes take 102.13-102.14 ms. Every plan computes the
+  full capacities whatever the scene holds (no compaction):
+  - 320 neighbours, 140 lanes, 25 route lanes, 10 polygons and 60 line strings in the encoder;
+  - 352 decoder rows (321 agents);
+  - 576 tokens (564 real).
+- **Host overhead.** Around the trace the host adds ~15.8 ms per in-process request: pre 4.8 + pack 0.5 +
+  host_in 2.4 + H2D 1.1 + D2H 0.6 + post 4.3 ms, plus the schema check. Handing over an `.npz` path adds 7 ms.
+- **Noise.** The p99 / mean spread of every host stage (and of `e2e`) comes from the shared host. Straight_road's
+  e2e p50 is higher than kashiwanoha's only because other agents loaded the CPU during that loop. The device numbers
+  (`trace` min, `b2b`) are stable to ±0.05 ms.
+- **Memory.** 309 unique programs; the trace buffers hold 74.6 MB of DRAM; 48.1 MB of weights and constants are
+  uploaded.
+
+## Dispatch / CQ matrix (D14)
+
+One process per configuration, all in one lock window (job 2, `matrix_<tag>.{log,json}`); default sample, 100
+iterations.
+
+| config | grid | trace p50 / p99 (min) | b2b per plan | e2e p50 / p99 (min) | H2D p50 | D2H p50 | load (JIT cache) | first call |
+|---|---|---:|---:|---:|---:|---:|---:|---:|
+| **ETH-1CQ (default)** | 12x10 | **102.13** / 104.81 (102.05) | **102.04** | **117.90** / 134.56 (112.87) | 1.14 | 0.58 | 11.6 s (warm) | 118.2 |
+| ETH-2CQ | 12x10 | 112.02 / 112.96 (111.94) | 111.87 | 125.64 / 141.03 (123.65) | 1.02 | 0.50 | 11.0 s (warm) | 125.0 |
+| WORKER-2CQ | 11x10 | 102.03 / 106.28 (101.90) | 101.88 | 126.63 / 142.67 (114.26) | 0.94 | 0.52 | 417.6 s (cold) | 114.7 |
+| WORKER-1CQ | 11x10 | 101.97 / 104.53 (101.89) | 101.87 | 116.10 / 135.84 (112.62) | 0.98 | 0.58 | 446.1 s (cold) | 113.6 |
+| ETH-1CQ, repeated last | 12x10 | 102.14 / 102.37 (102.07) | 102.04 | 117.35 / 124.73 (114.13) | 1.14 | 0.63 | 9.4 s (warm) | 117.8 |
+
+- **WORKER vs ETH: equal, so ETH stays the default.** WORKER dispatch is 0.17 ms (0.17 %) faster per plan, on 110
+  cores instead of 120. Two effects cancel:
+  - The 12th column hardly matters to this graph (Grid usage below). The 3,775 programs that do use all 120 cores
+    are short element-wise programs, bound by a fixed cost per program, not by the core count. The 25.8 ms of 4-8-core
+    matmuls do not use the grid at all.
+  - WORKER saves ~0.5 µs of dispatch per program (probe P1).
+
+  That is not "clearly better", so ETH stays the default (D14, `serve.env`). Re-measure once the op count drops,
+  when the 12th column should start to pay (DISPATCH.md).
+- **CQ count: 1.**
+  - On ETH, a second CQ makes the replay itself +9.8 ms (+9.6 %) per plan, about +1.6 µs per program.
+  - On WORKER it costs nothing (101.88 vs 101.87 ms). So the penalty belongs to the patched ETH 2-CQ dispatch
+    topology. It was not profiled here; `--profile-dispatch-cores` would show it.
+  - What 2 CQs could hide is the upload of the next plan while the trace runs: ~1.1 ms of H2D per 117 ms request,
+    and only when requests are pipelined.
+
+  Decision: **1 CQ** (the D14 default); `DIFFUSION_PLANNER_NUM_CQS=1` stays pinned.
+- A WORKER open recompiles every kernel: 7 min here, for both CQ counts. The served configuration never pays this.
+- No drift over the 21-minute window: ETH-1CQ measured 102.13 ms first and 102.14 ms last (trace p50), and 102.04 /
+  102.04 ms (b2b).
+
+## What the numerics defaults cost (precision ablation)
+
+Job 3 (`precision_<tag>.{log,json}`) ran one process per configuration on ETH-1CQ with the default sample: 30
+iterations, and b2b over 3 x 30 replays. The configurations differ only by the `DIFFUSION_PLANNER_*` knobs. **This
+is timing only: no gate was run here, and only `shipped` is gate-clean.** The PORT_LOG evidence for three of the
+others:
+
+- the round-1 defaults fail `ego.mean_err_m` on nuScenes scene-0103_kf14 (0.347 m > 0.3, job 11);
+- bf16 SDPA instead of the fp32 matmul attention (PORT_LOG's "decoder split alone", the same knobs) gives 0.74 /
+  0.33 m (max / mean) on scene-0103_kf14, over the 0.3 m mean gate (job 13, `logs/diffusion-planner/split_error_decsplit.json`);
+- the fastest graph (fused LN, no split, SDPA) fails `enc.ego` (0.99856 / 0.99261, job 4).
+
+The decoder-split, encoder-split and fused-LN removals were never gated.
+
+| config | `SPLIT_MATMUL` | `LN_FP32` | `ATTN_MATMUL` | trace p50 | b2b | vs shipped | unique programs | trace buffers |
+|---|---|---|---|---:|---:|---:|---:|---:|
+| **shipped** (decision 11) | `enc.island.*,enc.pre.*,dec.*` | `enc.mixer.*,dec.*` | `enc.fusion.attn,dec.*` | 102.11 | 102.04 | | 309 | 74.6 MB |
+| bf16 SDPA instead of fp32 matmul attention | same | same | none | 86.64 | 86.57 | −15.47 | 305 | 69.9 MB |
+| no split matmuls in the decoder | `enc.island.*,enc.pre.*` | same | same | 81.93 | 81.85 | −20.19 | 283 | 50.4 MB |
+| no split matmuls in the encoder | `dec.*` | same | same | 96.08 | 96.02 | −6.02 | 209 | 72.9 MB |
+| fused `ttnn.layer_norm` everywhere | same | none | same | 84.03 | 83.94 | −18.10 | 304 | 43.9 MB |
+| round-1 defaults (PORT_LOG job 11: 68.7 ms) | `enc.island.*,enc.pre.*,dec.preproj.*` | `enc.mixer.*,dec.*` | none | 68.72 | 68.64 | **−33.40** | 287 | 50.4 MB |
+| fastest graph (PORT_LOG job 4: 43.7 ms) | none | none | none | 43.79 | 43.74 | −58.30 | 173 | 16.2 MB |
+
+- **Precision cost of the shipped defaults.** It is **33.4 ms** over round 1, which reproduces PORT_LOG's 102.1 vs
+  68.7 ms. Over the fastest graph it is 58.3 ms.
+- **The knobs add up almost exactly.** The four single-knob removals sum to 59.8 ms, against 58.3 ms with all of
+  them off.
+- **On the card this cost is the first optimization target:** it is the price of the accuracy the nuScenes e2e gate
+  needs. Items 2-4 below recover it with fused kernels that keep the fp32-level accuracy. They do not relax precision:
+  precision policy §9.3, and every numerics change re-checked on all 99 scenes. Item 1 is a separate sink of similar
+  size that this profile found, unrelated to precision.
+
+## Host vs device, and every host<->device transfer per plan
+
+Host, per plan: numpy, the node's own pre- and post-processing (the PLAN.md 2.12 host rows). There is no host
+fallback inside the plan.
+
+- `load`: decodes the `.npz` and checks the 15 raw tensors against `INPUT_SCHEMA` (names, shapes, finite values).
+  Only `model(inputs=<path>)` does this; the server decodes its JSON / base64 body instead.
+- `host_pre` (`host.prepare`):
+  - normalization (all-zero rows kept) and the speed masks;
+  - the encoder's pre-matmul input plumbing: history truncation, velocity zeroing, validity masks, position features
+    with the ONNX `atan2` decomposition and the pseudo-heading quirk, point deltas;
+  - the decoder masks and `x_T`.
+- `pack` (`tt.inputs.plan_inputs`) builds the 19 persistent trace inputs: the input columns of the exact affine
+  rewrites, the 576-token arrays, the key-bias rows, and `cs` / `y0` on 352 rows.
+- `host_in`: converts them to ttnn host tensors (TILE layout, host tilization).
+- `host_post` (`host.make_output`): denormalization, trajectory velocity / force-stop / acceleration, the predicted
+  paths of the non-empty neighbour rows, the turn-indicator decision.
+
+Device: everything else, as ONE metal trace (`plan`):
+
+- the encoder: 6 mixer trunks, entity heads, small encoders, token assembly, 6 fusion blocks;
+- the hoisted cross K / V;
+- 11 x (DiT evaluation + fp32 DPM-Solver++(2M) update + prefix constraint);
+- the turn head and the output pack.
+
+**H2D per plan: 19 `copy_host_to_device_tensor` into the persistent inputs** (CQ0; with 2 CQs, CQ1 + events): 1.19 MB
+logical, 3.60 MB as TILE-padded fp32 / bf16.
+
+| input | shape | dtype | logical B | TILE-padded B |
+|---|---|---|---:|---:|
+| `neighbor_x` | [1, 320, 6, 9] | fp32 | 69,120 | 1,310,720 |
+| `lane_x` | [1, 140, 20, 8] | fp32 | 89,600 | 573,440 |
+| `cs` (current states in the t = 0 columns) | [1, 1, 352, 324] | fp32 | 456,192 | 495,616 |
+| `y0` (`x_T * mask0`; zeros at temperature 0) | [1, 1, 352, 324] | fp32 | 456,192 | 495,616 |
+| `line_string_x` | [1, 60, 20, 6] | fp32 | 28,800 | 245,760 |
+| `route_x` | [1, 25, 20, 8] | fp32 | 16,000 | 102,400 |
+| `polygon_x` | [1, 10, 40, 5] | fp32 | 8,000 | 81,920 |
+| `token_valid` | [1, 1, 576, 1] | fp32 | 2,304 | 73,728 |
+| `pos_aug` | [1, 1, 576, 15] | fp32 | 34,560 | 73,728 |
+| `neighbor_aux` | [1, 1, 320, 4] | fp32 | 5,120 | 40,960 |
+| `fusion_key_row` | [1, 1, 1, 576] | bf16 | 1,152 | 36,864 |
+| `agent_key_row` | [1, 1, 1, 352] | bf16 | 704 | 22,528 |
+| `lane_aux` | [1, 1, 140, 29] | fp32 | 16,240 | 20,480 |
+| `ego_x`, `static_x`, `route_aux`, `goal_x`, `ego_shape_x`, `turn_x` | small | fp32 | 3,344 | 6 x 4,096 |
+
+**D2H per plan: 1 packed read** (`pack_outputs`), 117,664 fp32 = 470,656 B in one row:
+
+- `final_x0` [352, 324];
+- the turn logits [5];
+- the ego rows of the 11 published iterates [11, 324].
+
+There is no mid-graph host round trip and no host fallback op.
+
+## Grid usage
+
+`tt/` sets no core grid or program config on any op. The only grid consumer, C20's SDPA config, reads
+`device.compute_with_storage_grid_size()`, and the default fp32 matmul attention does not use it. So every op picks
+its own core count:
+
+| core count per program (traced replay) | programs | kernel ms | what |
+|---|---:|---:|---|
+| 120 | 3,775 | 39.4 | element-wise / typecast / reduce programs, spread over all cores whatever their size |
+| 64-119 | 1,050 | 14.1 | decoder matmuls on 66-72 cores, softmax on 88, token-mixing matmuls on 100-117 |
+| 16-63 | 708 | 11.9 | decoder matmuls on 48 cores (561 programs, 9.7 ms) |
+| **2-15** | **712** | **33.6** | **matmuls on 4 / 8 cores: 148 programs, 26.0 ms, of which the encoder's batched `[1, E, T, C] @ [C, 128]` channel matmuls are 90 programs, 25.8 ms**; the attention P·V matmuls on 11 cores (66 programs, 4.6 ms); decoder LN reductions on 11 cores |
+| 1 | 37 | 0.2 | slices, small reshapes |
+
+Matmul efficiency is low everywhere. tt-perf-report gives a weighted mean of 7.2 % of the FLOP roofline over the
+1,365 matmuls (max 12.9 %), and 6.8 % of the DRAM roofline (35 GB/s) over the modelled ops.
+
+## What is already fused / traced
+
+- **The whole plan is one trace:** encoder + 11 DiT evaluations + 10 solver updates + turn head + pack, replayed
+  with persistent inputs. Replay == eager bit for bit (`test_plan_replay_equals_eager`, and the profile run). The
+  device suite is green under `TT_METAL_TRACE_ALLOC_TRACKING=1`.
+- **Exact rewrites already in the graph** (`tt/params.py`, proven on the host):
+  - the cross-attention K / V of the 3 DiT blocks is hoisted out of the solver loop (once per plan, not 11 times);
+  - the per-step adaLN is folded into the LayerNorm affine rows (no adaLN MLP on the device);
+  - the solver update is folded into `y' = A y - B m_k + Cm m_(k-1)`, with the prefix constraint as `x = y + cs` and
+    the t = 0 output columns zeroed in the last projection's weights;
+  - the ego / neighbour pre-projection runs as a pad-relative fp32 island;
+  - the small embeddings (neighbour type, lane speed / attributes, position) are one matmul over host-built columns;
+  - the turn head is `W_sel` / `W_pool / 564`, and the agent embedding is folded into bias rows.
+- **Fused in stock ops:**
+  - bias + GELU / tanh-GELU in `ttnn.linear` (2-D inputs);
+  - Q | K | V in one linear and one `nlp_create_qkv_heads` (DiT self-attention);
+  - K | V in one linear + `split_q_kv` (fusion);
+  - one packed readback.
+- **Not fused: the numerics defaults** (PORT_LOG decision 11), counted in programs per call:
+  - each split hi / lo matmul is **8.3 programs** on average instead of 1: typecast, typecast, subtract, 3
+    matmuls / linears, 2 adds, then GELU / typecast as needed;
+  - each fp32 LayerNorm is **9 programs** instead of 1: mean, subtract, multiply, mean, add, rsqrt, multiply, then
+    multiply / add for the affine;
+  - each fp32 attention is **5 programs** (matmul, scale, mask add, softmax, matmul), plus the head split / merge.
+- **Not fused: glue.** Residual adds, adaLN gate multiplies, the mixer token-mixing transposes, the solver update
+  (3-5 element-wise programs per step) and the ego-row slices.
+- **Not done at all:**
+  - every activation is DRAM-interleaved: no sharding, no L1 residency;
+  - no custom kernel, no `generic_op`, no megakernel;
+  - no compaction: all 321 agent rows and 564 tokens are computed whatever the scene holds.
+
+## Device profile (traced replay)
+
+The profile (job 4, `profile_ops.py`) has two sections:
+
+- one eager plan with stage (`m:`) and layer-kind (`c:`) signposts: 778.6 ms, dispatch-bound at a median of 101 µs
+  per eager op;
+- one traced replay of the same 6,282 programs. The op codes match the eager run one by one, so every replayed program
+  inherits its stage and kind.
+
+The replay with the profiler on took 105.13 ms on the host, against 102.1 ms without it. The eager run after the
+capture logs tt-metal's "allocating device buffers ... active trace" warning once; `run_eager` frees its buffers
+before the replay, and the replay equals the eager plan bit for bit.
+
+| | traced replay |
+|---|---|
+| programs per plan | **6,282** |
+| device kernel sum | **99.27 ms** |
+| op-to-op gaps (sum / median / p90 / max) | **4.39 ms** / 0.56 µs / 0.65 µs / 7.97 µs |
+| span (first FW start to last FW end, 1350 MHz) | **103.66 ms** |
+| kernel time per program, p10 / p50 / p90 / p99 / max | 2.7 / 5.76 / 32.2 / 96.6 / 984 µs |
+| programs under 5 µs / under 10 µs | 2,673 / 4,126 (19.2 ms together) |
+| math fidelity | HiFi4 on all 6,106 compute programs |
+
+The plan is **kernel-bound**: gaps are 4 % of the span. The time goes to a few slow, badly parallelised programs and
+to thousands of small ones, each costing ~5-8 µs whatever its size. The FLOPs are minor: the device graph does 165
+GFLOP of matmul per plan with every split pass counted (132 GFLOP of it in the decoder; `fake_flops.log`). That is
+~1 ms at the 120-core HiFi4 peak (~162 TFLOPS, TT_PLATFORM.md).
+
+**By stage** (kernel + gaps, ms):
+
+| stage | programs | ms | share |
+|---|---:|---:|---:|
+| encoder: 6 mixer trunks (pre-projection 8.8, 6 x 6 MixerBlocks 39.2, pool + heads 0.3) | 1,274 | 48.35 | 46.6 % |
+| encoder: fusion (6 blocks + final LN), small encoders, tokens, masks | 149 | 3.23 | 3.1 % |
+| decoder: 11 evaluations, 4.67 ms each incl. its solver update (433-443 programs each; e00-e09 4.38-4.40 ms kernel, e10 4.45) | 4,791 | 51.42 | 49.6 % |
+| cross K / V hoist, turn head, output pack | 68 | 0.66 | 0.6 % |
+
+**By layer kind and part** (kernel + gaps, ms; `kind_by_group.md`):
+
+| part | split matmul | plain linear | fp32 LN | fp32 attention | glue | heads / mask / fused LN | total |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| encoder mixer trunks | 8.31 (24 calls, 346 µs each) | **23.27** (159 calls) | 12.96 (72 calls, 180 µs each) | | 3.77 | 0.04 | 48.35 |
+| encoder fusion + small | | 0.72 | | 1.96 (6 calls) | 0.21 | 0.33 | 3.23 |
+| decoder x11 + solver | **26.09** (308 calls, 85 µs each) | | 8.59 (165 calls, 52 µs each) | **14.47** (66 calls, 219 µs each) | 1.34 | 0.93 | 51.42 |
+| cross K / V, turn, pack | 0.38 | 0.01 | | | 0.24 | 0.02 | 0.66 |
+| **all** | **34.78** | **24.00** | **21.56** | **16.43** | **5.56** | 1.33 | **103.66** |
+
+**One DiT evaluation** (e5, 4.67 ms):
+
+| | ms | share |
+|---|---:|---:|
+| split matmuls (pre-projection, self Q / K / V + out, cross Q + out, 2 MLPs, final) | 2.37 | 50.8 % |
+| self- and cross-attention as fp32 matmuls (3 x 0.20 + 3 x 0.24) | 1.32 | 28.2 % |
+| fp32 LayerNorms (12 x 48.5 µs + the final layer's 3 LNs 197 µs) | 0.78 | 16.7 % |
+| glue, head split / merge, solver update | 0.20 | 4.3 % |
+
+**By op code:**
+
+| op | programs | kernel ms | share |
+|---|---:|---:|---:|
+| Matmul | 1,365 | 52.34 | 52.7 % |
+| BinaryNg (element-wise binary) | 2,948 | 31.48 | 31.7 % |
+| Reduce (LN means) | 480 | 3.69 | 3.7 % |
+| Softmax | 72 | 3.47 | 3.5 % |
+| Unary (GELU, rsqrt) | 428 | 2.81 | 2.8 % |
+| Typecast | 676 | 2.41 | 2.4 % |
+| Transpose (mixer token mixing) | 84 | 1.34 | 1.4 % |
+| NlpCreateHeads / NLPConcatHeads | 150 | 1.00 | 1.0 % |
+| other (reshape, untilize, LayerNorm, repeat, tilize, concat, slice, pad) | 79 | 0.73 | 0.7 % |
+
+**Top-10 device programs** (traced replay, single programs). All ten are the neighbour mixer's channel-MLP matmuls
+`[1, 320, 64, 128] @ [128, 128]` (6 MixerBlocks x 2 linears), each on **8 cores**:
+
+| # | op | stage | in0 @ in1 | dtypes in0 / in1 / out | cores | kernel µs |
+|---:|---|---|---|---|---:|---:|
+| 1 | Matmul (`ch2`) | `enc.neighbor.mix` | [1,320,64,128] @ [1,1,128,128] | bf16 / bf16 / fp32 | 8 | 984.1 |
+| 2 | Matmul (`ch2`) | `enc.neighbor.mix` | same | bf16 / bf16 / fp32 | 8 | 977.6 |
+| 3 | Matmul (`ch2`) | `enc.neighbor.mix` | same | bf16 / bf16 / fp32 | 8 | 972.8 |
+| 4 | Matmul (`ch2`) | `enc.neighbor.mix` | same | bf16 / bf16 / fp32 | 8 | 971.8 |
+| 5 | Matmul (`ch2`) | `enc.neighbor.mix` | same | bf16 / bf16 / fp32 | 8 | 971.2 |
+| 6 | Matmul (`ch2`) | `enc.neighbor.mix` | same | bf16 / bf16 / fp32 | 8 | 970.1 |
+| 7 | Matmul (`ch1`, + GELU) | `enc.neighbor.mix` | [1,320,64,128] @ [1,1,128,128] | fp32 / bf16 / bf16 | 8 | 966.4 |
+| 8 | Matmul (`ch1`) | `enc.neighbor.mix` | same | fp32 / bf16 / bf16 | 8 | 965.2 |
+| 9 | Matmul (`ch1`) | `enc.neighbor.mix` | same | fp32 / bf16 / bf16 | 8 | 965.2 |
+| 10 | Matmul (`ch1`) | `enc.neighbor.mix` | same | fp32 / bf16 / bf16 | 8 | 965.0 |
+
+**Top op signatures by total time** (`profile_breakdown.md`). Only matmul shapes are shown: element-wise programs are
+shared across shapes, and the profiler's op-info cache reports the first call's shapes for them.
+
+| op | where | kind | in0 @ in1 | cores | programs | ms | mean µs |
+|---|---|---|---|---:|---:|---:|---:|
+| Matmul | `enc.neighbor.mix` channel MLP | linear | [1,320,64,128] @ [128,128] | 8 | 12 | 11.64 | 970 |
+| BinaryNg | mixer blocks | fp32 LN | | 120 | 360 | 9.92 | 27.6 |
+| Matmul | decoder MLP fc2 (mlp1 + mlp2, 3 split passes each) | split | [1,1,352,1024] @ [1024,256] | 48 | 198 | 5.71 | 28.8 |
+| Matmul | `enc.lane.mix` channel MLP | linear | [1,140,64,128] @ [128,128] | 8 | 12 | 5.09 | 425 |
+| BinaryNg | decoder attention scale / mask add | fp32 attention | | 120 | 132 | 4.72 | 35.8 |
+| Matmul | decoder MLP fc1 (mlp1 + mlp2, 3 split passes each) | split | [1,1,352,256] @ [256,1024] | 66 | 198 | 3.39 | 17.1 |
+| Matmul | `enc.neighbor.pre` (pad-relative island) | split | [1,320,6,128] @ [128,128], [1,320,6,9] @ [9,128] | 4 | 6 | 3.15 | 525 |
+| Matmul | decoder self-attention P·V | fp32 attention | [1,8,352,352] @ [1,8,352,32] | 11 | 33 | 2.33 | 70.7 |
+| Matmul | decoder cross-attention P·V | fp32 attention | [1,8,352,576] @ [1,8,576,32] | 11 | 33 | 2.26 | 68.4 |
+| Matmul | `enc.line_string.mix` channel MLP | linear | [1,60,64,128] @ [128,128] | 8 | 12 | 2.19 | 183 |
+| Softmax | decoder cross-attention | fp32 attention | | 88 | 33 | 1.83 | 55.4 |
+| BinaryNg | mixer residual adds | glue | | 120 | 72 | 1.75 | 24.3 |
+| Reduce | mixer LN means | fp32 LN | | 120 | 72 | 1.39 | 19.3 |
+
+Compare the 2-D token-mixing matmul of the same trunk: `[1,1,40960,64] @ [64,64]` runs on 117 cores in 69 µs. The
+4-D channel MLP with twice the FLOPs takes 970 µs on 8 cores: 14x the time, about 7x slower per FLOP.
+
+Artifacts:
+
+- **Profile:** `generated/profiler/diffusion-planner_baseline/reports/2026_10_08_06_13_03/`, holding
+  `ops_perf_results_*.csv`, the Tracy file and `profile_log_device.csv.zst` (7.3 GB raw; `zstd -d` it before loading
+  the folder in ttnn-visualizer), plus `.logs/cpp_device_perf_report.csv`.
+- **ttnn-visualizer memory / graph reports** (not for timing): `generated/ttnn_visualizer/diffusion-planner_baseline/{decode_once,encoder_taps}/`:
+  - one decoder evaluation: 508 ops, 20.9 MB `db.sqlite`;
+  - the encoder: 1,483 ops, 63.5 MB.
+  - No whole-plan capture was made. At the measured ~1.3k buffer rows per op it would be ~8M rows (a ~2.5 GB capture
+    JSON) for 11 repeats of the same evaluation. The two captures cover every distinct layer of the plan except the
+    solver update, the turn head and the output pack.
+  - Open them with `ttnn-visualizer --profiler-path <that dir> --performance-path <the profile folder>`.
+  - Capture: `logs/diffusion-planner/baseline/scripts/visualizer_capture.py` (job 5). Import:
+    `visualizer_import.py`, on the CPU.
+
+## Ranked optimization opportunities
+
+Gains are estimated on the 102.0 ms replay and come from the profile above. They are **not additive**: each one
+shrinks the base of the next. Every item must keep the frozen gates, re-checked on all 99 e2e scenes (PORT_LOG 8:
+the plan's sensitivity to device numerics is chaotic per scene). The precision cost of decision 11 (33.4 ms over round
+1) is recovered by items 2-4, not by relaxing precision.
+
+1. **Run the encoder's channel MLPs on 2-D activations (≈ −20 to −22 ms; exact rewrite, low effort).**
+   - *What is slow.* The mixer `channels_mlp` (`ch1` / `ch2`) and the channel pre-projections run `ttnn.linear` on
+     4-D `[1, E, T, C]` activations. That is a batched matmul on **4-8 cores**: 90 programs, 25.8 ms.
+   - *MixerBlocks.* `[1, E, 64, 128]` -> `[1, 1, E·64, 128]` is a free view (64 rows = 2 whole tiles per entity).
+     Then the matmul can spread over the grid, as the token-mixing matmuls already do (69 µs on 117 cores for the
+     neighbours).
+   - *Pre-projections.* T = 6 / 20 / 40 rows do not fill a tile, so the view is not free. Two options:
+     - have `pack` lay the inputs out as `[1, 1, E·T, C]` and re-tile once before the token transpose;
+     - or give the 4-D matmul an explicit multi-core program config, with the HiFi4 compute config passed too (a
+       `program_config` alone falls back to LoFi, PLAN 0.2).
+   - *Estimate.* The channel matmul at 2x the measured token-MLP time of its trunk saves ~17 ms on the MixerBlocks
+     and ~5 ms on the pre-projections. The math is unchanged (the K = 128 reduction per output). The gates must still
+     be re-run, because accumulation order may differ.
+   - *Generalisation.* No `[1, E, ...]`-batched `ttnn.linear` anywhere (the PR:P12 rule extended from token mixing
+     to channel mixing).
+2. **A fused split (bf16x3) matmul, one program per linear (≈ −17 to −19 ms).**
+   - *Today.* 338 split linears, 2,802 programs, 34.8 ms: decoder 26.1, encoder 8.3, cross K/V 0.4.
+   - *The kernel.* A `generic_op` matmul that reads the fp32 activation once, splits hi / lo on the fly (SFPU), and
+     accumulates `x_hi W_hi + x_hi W_lo + x_lo W_hi` in fp32 DEST.
+   - *What it removes.* All typecast / subtract / add programs and their gaps, 9.3 ms in the decoder. The three
+     passes also share operand reads: estimated at 1.5x one pass, 8 instead of 16 ms of decoder matmul.
+   - *Accuracy.* The same ~1e-5 relative error as today's 3-matmul form.
+   - *Cheaper first step.* Explicit program configs for the 352-row decoder matmuls, which run on 48-72 cores at
+     ~7 % FLOP utilisation. Pass the compute config with them: a `program_config` without one silently falls back to
+     LoFi (PLAN 0.2).
+3. **A fused fp32 LayerNorm, one program per LN (≈ −15 to −16 ms).**
+   - *Today.* 237 LNs, 2,133 programs, 21.6 ms: mixers 72 x 180 µs on `[E, 64, 128]`; decoder 165 x 52 µs on
+     `[352, 256]`.
+   - *The kernel.* One program per LN (mean / variance in fp32 by Welford or two passes in L1, rsqrt, affine with
+     the folded adaLN rows), at ~2 element-wise passes: ~45 µs in the mixers and ~12 µs in the decoder.
+   - *Limit.* The fused `ttnn.layer_norm` would save 18.1 ms (ablation), but it is ~2.5e-3 relative (PR:P10). On the
+     offset-dominated mixer rows it reaches rel-L2 0.03, and the teacher-forced neighbour mixer drops to PCC 0.9978
+     (PORT_LOG job 5).
+4. **Attention (≈ −5.5 ms with stock ops, ≈ −12 to −13 ms with a fused kernel).**
+   - *Today.* 72 fp32 matmul attentions, 16.4 ms, ~228 µs per call. The bf16 SDPA would cost ~13 µs per call
+     (ablation: −15.5 ms), but fails the e2e mean gate.
+   - *(a) Stock ops.* Fold the 1/√32 scale into `W_q` / `b_q`: fp64 fold, then the hi / lo split; gate it. Use a
+     fused scale-mask-softmax for the mask add. Together this removes the 132 decoder (+ 12 fusion) scale / mask
+     programs: 4.7 + 0.7 ms.
+   - *Parallelism.* The P·V matmuls (`[1, 8, 352, Sk] @ [1, 8, Sk, 32]`) run on 11 cores (66 programs, 4.6 ms); a
+     head-parallel program config would spread them.
+   - *(b) A fused fp32-accurate flash-attention kernel* (`generic_op`): scores stay in L1 / DEST, `Q·Kᵀ` and `P·V`
+     use hi / lo operands, and the mask comes from the key-bias row. At ~3-4x the bf16 SDPA's cost (~50 µs per call)
+     it saves ~12.8 ms and supersedes (a).
+5. **Glue (≈ −3 to −4 ms).**
+   - *Mixers: 3.8 ms.* Token-mixing transposes (84 programs, 1.3 ms) and residual adds (72 programs, 1.8 ms). The
+     entity-parallel mixer kernel of PLAN 5.3 (no transposes) or residual adds in the matmul epilogue remove them.
+   - *Decoder.* Fold the per-step adaLN gates exactly into per-step copies of the gated weights (`attn.out`,
+     `mlp1.fc2`): this removes 66 gate multiplies, at ~65 MB of extra DRAM for the 11 x 3 copies with hi / lo parts.
+   - *Solver.* The update `A y - B m_k + Cm m_(k-1)` becomes one ternary / `generic_op` program instead of 3-5 (83
+     programs, 0.45 ms).
+6. **Megakernels (D19; after 1-4, gains measured against what is left).**
+   - **MK-D, the persistent DiT-evaluation kernel.**
+     - *Today.* One evaluation is 4.67 ms in ~435 programs. Its matmul work is 12.0 GFLOP, split passes included
+       (74 µs at the HiFi4 peak).
+     - *Fits in L1.* Its weights are 8.7 MB (DiT blocks) + 1.8 MB (pre-projection, final layer) as bf16 hi parts, plus
+       the fp32 lo parts; the activations are `[352, 256]` fp32 (360 KB); the hoisted cross K / V is 3.5 MB.
+     - *Parameters.* Compile-time: agent bucket (352), heads 8 x 32, MLP 1024, depth 3, NFE 11. The folded adaLN
+       rows and the solver coefficients move from 11 unrolled trace copies into an L1 table (RT-dev constants per
+       steps value).
+     - *Target.* 0.5-1 ms per evaluation would cut the decoder from 51 to ~6-11 ms.
+   - **MK-E (one mixer trunk) and MK-F (one fusion block)** for the encoder.
+   - **The single persistent megakernel for the whole plan** (PLAN 5.3) is plausible. The 48 MB of uploaded weights /
+     constants and the largest activation (neighbour mixer `[320, 64, 128]` fp32, 10.5 MB) fit the ~175 MB of
+     aggregate L1. The compute floor is ~1 ms.
+   - It ships only if it is faster with the gates intact; the attempt is recorded either way (D19).
+7. **Compaction (LOAD-time buckets; 20-40 % of what remains after 1-4, to be measured).**
+   - The device time is scene-independent: kashiwanoha uses 88 / 320 neighbours, 123 / 140 lanes and 89 / 352
+     decoder rows.
+   - Valid-entity buckets need one trace per bucket and the exact compaction rewrites of PLAN 5.3:
+     - they shrink the bandwidth-bound encoder work in proportion;
+     - they shrink the attention scores quadratically (`[8, 352, 352]` -> `[8, 96, 96]` at 89 agents);
+     - they help the latency-bound decoder matmuls little.
+8. **Host side, e2e only (≈ −4 to −6 ms per request).** 15.8 ms of host work and transfers surround the 102 ms replay.
+   - Pack `neighbor_x` as a 2-D `[1, 1, 1920, 9]` input: 1.31 MB of TILE padding becomes 245 KB, which also feeds
+     item 1.
+   - Skip the `y0` upload while `x_T` is unchanged (zeros at temperature 0, the node's default) and send `cs` as its
+     4 columns. Together: H2D 3.6 -> ~1.6 MB, and less host tilization (`host_in` 2.4 ms).
+   - Vectorise the per-entity loops of `host_pre` (4.8 ms) and `host_post` (4.3 ms: the predicted paths of up to 320
+     agents).
+   - The 7 ms `.npz` decode is the caller's choice (pass arrays).
+9. **Dispatch configuration: no gain today; re-measure after 1-5.**
+   - Gaps are only 4.4 ms (0.56 µs median). What pays is removing programs: each removed short program saves its
+     ~5-8 µs kernel plus ~0.6 µs.
+   - Re-run the ETH / WORKER and 1 / 2 CQ matrix once the op count drops below ~2,000. ETH's 12th column matters only
+     once ops become throughput-bound.
+   - The ETH-2CQ penalty (+1.6 µs per program) needs a dispatch-core profile before 2 CQs are reconsidered.
+
+## Raw logs and CSVs
+
+Under `logs/diffusion-planner/baseline/` (workspace) unless absolute:
+
+| what | files |
+|---|---|
+| re-vendoring + suites | `host_suite.log` (105 passed / 46 skipped; again on the final tree with the new scripts: `host_suite_final.log`), `device_suite.log` (44 passed), `alloc_tracking.log` (44 passed), `e2e_device.json` (99 scenes), `windowA.log` |
+| stage bench + dispatch / CQ matrix | `matrix_{eth-1cq,eth-2cq,worker-2cq,worker-1cq,eth-1cq-repeat}.{log,json}`, `matrix.rcs`, `tables.md` |
+| numerics ablation | `precision_{shipped,no_attnmm,no_decsplit,no_encsplit,no_ln32,round1,fastest}.{log,json}`, `precision.rcs`, `windowB.log` |
+| device profile | `profile_tracy.log`, `profile_run.json`; ops CSV `/home/ubuntu/experiments/tt-models/generated/profiler/diffusion-planner_baseline/reports/2026_10_08_06_13_03/ops_perf_results_2026_10_08_06_13_03.csv`; summaries `profile_summary.{json,md}` (`analyze_profile.py`), `profile_breakdown.md`, `kind_by_group.md`; tt-perf-report `tt_perf_report_trace.{txt,csv}`, `tt_perf_report_trace_summary.{csv,png}` |
+| ttnn-visualizer | `visualizer_capture.log`, `visualizer_import.log`; reports in `/home/ubuntu/experiments/tt-models/generated/ttnn_visualizer/diffusion-planner_baseline/` |
+| op counts / FLOPs on the fake ttnn (CPU) | `fake_signposts.log` (6,408 fake ops by stage / kind), `fake_flops.log` (165 GFLOP per plan); the port's per-configuration counts: `logs/diffusion-planner/opcount_fake_r2.log` |
+| scripts | `scripts/` (`windowA.sh`, `windowB.sh`, `job{1..5}_*.sh`, `chain.sh`, `analyze_profile.py`, `profile_breakdown.py`, `tables.py`, `fake_*.py`, `visualizer_*.py`) |

OPT_REPORT.md

@@ -0,0 +1,142 @@
+# diffusion-planner-p150 optimization report (p150, ETH dispatch, 12×10 grid)
+
+**Status: baseline port; optimization pending.** This is the first public release: the functional port, measured
+once (`OPT_BASELINE.md`, baseline commit `5541833`, 2026-10-08) and not optimized yet. No optimization round has run,
+so there is no step, no rejected attempt and no hang to report, and every number below is the baseline. The whole
+plan (encoder, the 11 DiT evaluations with the DPM-Solver++(2M) updates, the turn-indicator head) runs as one metal
+trace of 6,282 programs: 102.04 ms per back-to-back replay (9.80 plans/s of device throughput), 117.9 ms per
+synchronous `model()` call on the shipped sample. The trace is kernel-bound (op-to-op gaps 4.4 ms of a 103.7 ms span).
+Two sinks of similar size come first: the **numerics defaults** that the end-to-end gates need (split hi / lo matmuls,
+fp32 LayerNorm, fp32 matmul attention) cost **33.4 ms** over the first device round, and the encoder's channel-MLP and
+pre-projection matmuls run on only 4-8 cores (**25.8 ms**, unrelated to precision).
+
+All numbers: `code/scripts/bench.py` (median of 100 warm iterations, batch 1,
+`code/tt_diffusion_planner/samples/kashiwanoha_dense.npz`), ETH dispatch, 1 CQ, 12×10 grid, the pinned numerics
+(`DIFFUSION_PLANNER_SPLIT_MATMUL=enc.island.*,enc.pre.*,dec.*`, `_LN_FP32=enc.mixer.*,dec.*`,
+`_ATTN_MATMUL=enc.fusion.attn,dec.*`), unless marked otherwise. Device profile: `code/scripts/profile_ops.py` under the
+device profiler (one traced replay between signposts). Accuracy gates: `OPT_BASELINE.md` "How to run".
+
+## Summary
+
+| | baseline `5541833` (2026-10-08) | **final (= baseline: no round yet)** |
+|---|---|---|
+| device trace, one blocking plan | 102.13 ms (p99 104.81) | same |
+| back-to-back traces | 102.04 ms (9.80 plans/s) | same |
+| e2e `model(inputs=arrays)` p50 / p99 | 117.90 / 134.56 ms | same |
+| e2e `model(inputs=<.npz path>)` p50 | 124.76 ms | same |
+| host pre-processing / pack / host tensors / H2D / D2H / post-processing | 4.76 / 0.45 / 2.41 / 1.14 / 0.58 / 4.32 ms | same |
+| device programs per plan (unique programs) | 6,282 (309) | same |
+| kernel sum / op-to-op gaps / span (profile) | 99.27 / 4.39 / 103.66 ms | same |
+| encoder / 11 decoder evaluations (+ solver updates) | 51.6 / 51.4 ms (4.67 ms per evaluation) | same |
+| accuracy gates (PCC / agreement vs the fp32 CPU reference) | 44 / 44 device tests: module PCC ≥ 0.999952, encoding 0.999978, decoder evaluation ≥ 0.9999995; 99 scenes: ego max 0.313 m / mean 0.143 m (gates 1.0 / 0.3 m), turn command 99 / 99, neighbours ≤ 0.086 m (gate 1.5 m) | same |
+| served `/predict` `timing_ms.total`, median of 50 (uvicorn on the host, the shipped sample) | 123.1 ms, measured on `c0d84f9` (same device code; the release verification) | same |
+| `from_pretrained` load: empty JIT cache / warm cache | 315 s / 8.6 s (`c0d84f9`) | same |
+
+The host is shared with other agents' jobs, so the host-side rows move with its load (several ms); the device rows
+repeat to ±0.05 ms. AICLK 1350 MHz (min 1343) during the stage bench. The release re-check on `c0d84f9`
+(`VERIFICATION_2026-10-08.md`) reproduced the device rows: back-to-back replay 102.03 vs 102.04 ms, one plan 102.10 vs 102.13 ms; the host-bound end to end 115.6 vs 117.9 ms p50 moves with the host load.
+
+## Steps (chronological; each row is one commit)
+
+| step | commit | what | trace / b2b ms | e2e ms | accuracy | revert switch |
+|---|---|---|---|---|---|---|
+| baseline | `5541833` | first correct port: the whole plan in one trace, ETH 1CQ 12×10, the numerics defaults of PORT_LOG decision 11, host pre- and post-processing | 102.13 / 102.04 | 117.90 | all gates (above) | – |
+
+Later commits up to the first release changed no model numerics and no device code: the baseline documentation
+(`a6e5bbf`), the ttaw 0.19.0 re-vendor with the `serve.env` pins of the numerics knobs, the quickstart picture and two
+test changes (`d521981`), the ttaw 0.20.0 re-vendor (`c0d84f9`), and the release docs and demo media. After the re-vendor the device suite was re-run with
+identical gate values and per-scene numbers (`VERIFICATION_2026-10-08.md`).
+
+## Round 1
+
+Not started. The optimization phase follows the publication of every model of the collection (`research/PLAN.md`
+§4.1, §5): each step is one commit with one `DIFFUSION_PLANNER_*` A/B knob, keeps the frozen gates and is re-checked on
+all 99 end-to-end scenes (the plan's sensitivity to device numerics is chaotic per scene: PORT_LOG known issues). The
+precision policy (PLAN.md §9.3) may be relaxed per module only with gate evidence; the precision cost is to be
+recovered with fused kernels that keep fp32-level accuracy, not by dropping precision.
+
+### Findings (measured)
+
+The baseline profile (`OPT_BASELINE.md` "Device profile") is the starting point:
+
+- The trace is **kernel-bound, not dispatch-bound**: op-to-op gaps total 4.39 ms of a 103.66 ms span (median gap
+  0.56 µs). Removing a short program saves its ~5-8 µs of kernel time plus ~0.6 µs.
+- The plan does 165 GFLOP of matmul (split passes counted), ~1 ms at the 120-core HiFi4 peak: the time goes to badly
+  parallelised matmuls and thousands of small element-wise programs. Matmul efficiency is 7.2 % of the FLOP roofline
+  on average.
+- By layer kind: split matmuls 34.8 ms, plain linears 24.0 ms (23.3 of them in the encoder's mixer trunks), fp32
+  LayerNorm 21.6 ms, fp32 matmul attention 16.4 ms, glue 5.6 ms.
+- What each numerics default costs (device time per plan, timing only; only the shipped configuration is gate-clean):
+  decoder split matmuls 20.2 ms, fp32 LayerNorm 18.1 ms, fp32 matmul attention 15.5 ms, encoder split matmuls 6.0 ms;
+  all four together 58.3 ms (the fastest graph, 43.74 ms, fails `enc.ego`), the decision-11 additions over the first
+  device round 33.4 ms (round-1 defaults: 68.64 ms, which fail `ego.mean_err_m` on nuScenes scene-0103_kf14).
+- Dispatch / CQ matrix (back-to-back): ETH-1CQ 102.04, ETH-2CQ 111.87, WORKER-2CQ 101.88, WORKER-1CQ 101.87 ms. WORKER
+  is equal (the 12th column hardly matters to this graph yet), so ETH stays the default (D14); 2 CQs cost +9.8 ms on ETH,
+  so 1 CQ stays pinned.
+
+### Megakernel / fusion work
+
+None yet. The candidates (D19) are in the backlog (item 6): the persistent DiT-evaluation kernel first.
+
+## Known hangs (all rounds)
+
+| when (UTC) | command | cause | status |
+|---|---|---|---|
+| – | – | none: no hang, timeout, reset or FAULT marker in any device job of the port, the baseline or the release docs | – |
+
+## Rejected / not kept
+
+None yet. Configurations that were measured and are **not** the default, for accuracy (PORT_LOG decision 11,
+`OPT_BASELINE.md` "What the numerics defaults cost"):
+
+- the first device round's defaults (split only for the mixer inputs and the decoder pre-projection, bf16 SDPA):
+  68.7 ms, but ego mean 0.347 m > 0.3 m on nuScenes scene-0103_kf14 (job 11);
+- configuration B (A + split and fp32 LayerNorm in the whole encoder): 109 ms, worst ego 0.35 / 0.15 m;
+- configuration C (split and fp32 LayerNorm everywhere): 169 ms, worst ego 0.22 / 0.10 m: about a third less error
+  than the shipped configuration A (0.31 / 0.14 m, 105 ms in the same job 15) at +61 % device time (PORT_LOG open
+  question 8);
+- the fastest graph (fused LayerNorm, no split, bf16 SDPA): 43.7 ms, fails the encoder PCC gate (`enc.ego` 0.99856 /
+  0.99261).
+
+## Profile at the end (trace replay)
+
+The baseline profile (`OPT_BASELINE.md`): 6,282 programs, kernel sum 99.27 ms, span 103.66 ms; by op code Matmul
+52.3 ms (1,365 programs), BinaryNg 31.5 ms (2,948), Reduce 3.7 ms, Softmax 3.5 ms, Unary 2.8 ms, Typecast 2.4 ms. The
+ten slowest programs are the neighbour mixer's channel matmuls `[1, 320, 64, 128] @ [128, 128]`, ~970 µs each on 8
+cores.
+
+## Remaining backlog (gains on the 102.0 ms replay unless marked e2e; estimates, not measurements)
+
+From `OPT_BASELINE.md` "Ranked optimization opportunities". The gains are not additive: each item shrinks the base of
+the next.
+
+1. **Encoder channel MLPs on 2-D activations (≈ −20 to −22 ms; exact rewrite, low effort).** The mixer `channels_mlp`
+   and the channel pre-projections run `ttnn.linear` on 4-D `[1, E, T, C]` activations, a batched matmul on 4-8 cores
+   (90 programs, 25.8 ms). A free `[1, 1, E·64, 128]` view for the MixerBlocks (as the token-mixing matmuls already do:
+   69 µs on 117 cores) and a re-tiled 2-D layout or an explicit multi-core program config (with the HiFi4 compute
+   config: a `program_config` alone falls back to LoFi) for the pre-projections.
+2. **A fused split (bf16x3) matmul, one program per linear (≈ −17 to −19 ms).** 338 split linears are 2,802 programs
+   and 34.8 ms today; a `generic_op` matmul that splits hi / lo on the fly and accumulates the three products in fp32
+   DEST removes the typecast / subtract / add programs (9.3 ms in the decoder) and shares the operand reads.
+3. **A fused fp32 LayerNorm, one program per LN (≈ −15 to −16 ms).** 237 LNs are 2,133 programs and 21.6 ms; the fused
+   `ttnn.layer_norm` is ~2.5e-3 relative and fails the mixers (PORT_LOG job 5), so the kernel must keep fp32
+   statistics.
+4. **Attention (≈ −5.5 ms with stock ops, ≈ −12 to −13 ms with a fused kernel).** 72 fp32 matmul attentions, 16.4 ms:
+   fold the 1/√32 scale into the Q weights and fuse the mask into the softmax (stock ops), spread the P·V matmuls over
+   heads, or one fp32-accurate flash-attention `generic_op` (scores in L1, hi / lo operands).
+5. **Glue (≈ −3 to −4 ms).** Mixer transposes and residual adds, the adaLN gate multiplies (exact fold into per-step
+   weight copies), the solver update as one program instead of 3-5.
+6. **Megakernels (D19; after 1-4).** MK-D, the persistent DiT-evaluation kernel (today 4.67 ms in ~435 programs for
+   12.0 GFLOP; its weights fit in L1; target 0.5-1 ms per evaluation, the decoder from 51 to ~6-11 ms); MK-E / MK-F for
+   a mixer trunk / a fusion block; a single persistent megakernel for the whole plan is plausible (48 MB of weights and
+   constants, the largest activation 10.5 MB, ~175 MB of aggregate L1). It ships only if faster with the gates intact;
+   the attempt is recorded either way.
+7. **Compaction (LOAD-time buckets; 20-40 % of what remains after 1-4, to be measured).** The device time is
+   scene-independent: kashiwanoha uses 88 / 320 neighbours and 89 / 352 decoder rows. Valid-entity buckets (one trace
+   per bucket, exact compaction rewrites) shrink the encoder in proportion and the attention scores quadratically.
+8. **Host side (e2e ≈ −4 to −6 ms per request).** 15.8 ms of host work and transfers surround the replay: a 2-D
+   `neighbor_x` upload (1.31 MB of TILE padding -> 245 KB), skipping the `y0` upload while `x_T` is zero and sending
+   `cs` as its 4 columns (H2D 3.6 -> ~1.6 MB), vectorised per-entity loops in the pre- and post-processing.
+9. **Dispatch configuration: no gain today; re-measure after 1-5.** Re-run the ETH / WORKER and 1 / 2 CQ matrix once
+   the program count drops below ~2,000; the ETH-2CQ penalty (+1.6 µs per program) needs a dispatch-core profile
+   first.

PYTHON.md

@@ -0,0 +1,179 @@
+# Python API: Diffusion Planner v5.0 (Autoware diffusion_planner) on Blackhole
+
+Use this API from Python code (a pipeline, a notebook, a ROS 2 node wrapper). You do not need the HTTP server: the
+API and the server share the decoders, the device trace and the post-processing, so the outputs and the speed are
+the same.
+
+## Install
+
+Install the package on top of an environment that already has `ttnn` (a tt-metal `python_env` at `44d66500520`
+with `patches/tt-metal-eth-dispatch.patch`, or the tt-model container). From the root of the model repository (the
+directory that holds `pyproject.toml`, `README.md` and `code/`):
+
+```bash
+pip install -e .                        # the Python API (numpy<2, pillow, pyyaml, onnx, huggingface_hub)
+pip install -e ".[server,test]"         # + the HTTP server and the tests
+```
+
+The pip project is the repository's top-level `pyproject.toml`; it installs the package from
+`code/tt_diffusion_planner` (there is no `pyproject.toml` inside `code/`, because the container build copies `code/`
+over the tt-metal tree). ttnn and torch come from tt-metal and are not declared.
+
+The package carries `tt_diffusion_planner.ttaw`, the shared code of the Autoware ports to Blackhole (device open, trace
+runner, decoders, model base class, HTTP app), vendored at the version recorded in
+`code/tt_diffusion_planner/ttaw/VENDORED.json`.
+
+| You want to run | Extras |
+|---|---|
+| the Python API | none |
+| the HTTP server (`tt_diffusion_planner.server.app`, see `SERVING.md`) | `server` |
+| host tests (no device; device tests are skipped): `TT_VISIBLE_DEVICES=none python -m pytest -q code/tt_diffusion_planner/tests` | `server,test` |
+| device tests: `python -m pytest -q -s code/tt_diffusion_planner/tests/test_pcc_device.py code/tt_diffusion_planner/tests/test_e2e_device.py` | `test` |
+
+## Quickstart
+
+```python
+from tt_diffusion_planner import DiffusionPlanner
+
+with DiffusionPlanner.from_pretrained(device_id=0) as model:
+    out = model(inputs="code/tt_diffusion_planner/samples/kashiwanoha_dense.npz")
+print(out.to_dict())   # the POST /predict body
+```
+
+`examples/quickstart.py` runs the same snippet, writes `quickstart.json` and a bird's-eye view of the input and the
+plan (`quickstart_bev.png`).
+
+## `DiffusionPlanner.from_pretrained(...)`
+
+```python
+DiffusionPlanner.from_pretrained(
+    model_id=None,          # HF repo or a local directory with the weights files; default AutowareFoundation/diffusion_planner
+    *,
+    revision=None,          # default for the default repo: the validated commit 423efde67f5 (tag v5.0)
+    variant=None,           # "default" (the only v5.0 graph); default $DIFFUSION_PLANNER_VARIANT or "default"
+    device_id=None,         # chip to open; default $TT_DEVICE_ID or 0
+    device=None,            # an already-opened ttnn device (tt_diffusion_planner.device.open_device); close() does not close it
+    dispatch=None,          # "eth" (p150 target, 12x10 grid) | "worker" (A/B only, 11x10) | "auto"; default $DIFFUSION_PLANNER_DISPATCH or "eth"
+    num_command_queues=None,  # default $DIFFUSION_PLANNER_NUM_CQS or 1
+    weights_dir=None,       # explicit local weights directory; no Hub access
+    warmup_variants="default",  # trace variants to capture now; see "Warm-up"
+    verbose=False,
+    precision=None,         # the only compile parameter: extra precision-policy rules, e.g. "dec.*=HiFi2+fp32" (experiments only)
+) -> DiffusionPlanner
+```
+
+What it does: resolves the weights first, so a Hub problem never claims the chip (`weights_dir` >
+`$DIFFUSION_PLANNER_WEIGHTS_DIR` > a local `model_id` directory > the HF snapshot at the pinned revision, restricted to
+the three v5.0 ONNX files and `diffusion_planner.param.json`, with an offline fallback to the cache; the sha256 of every
+file and the weights' `major_version == 5` are checked), opens the chip (ETH dispatch, 12×10, 1 CQ; the other open
+parameters are `DEVICE_DEFAULTS` in `tt_diffusion_planner/device.py`, overridable with `DIFFUSION_PLANNER_*`), reads the
+ONNX initializers as data, uploads the weights and constants (48.1 MB), builds the graph, then compiles and captures
+the metal trace. If ETH dispatch cannot open (tt-metal without the patch), it warns and falls back to WORKER dispatch
+(`model.info["device"]["fallback"]` names it). Any other keyword argument is a `TypeError`.
+
+The numerics are not arguments: the published configuration is the default of the `DIFFUSION_PLANNER_LN_FP32`,
+`_SPLIT_MATMUL`, `_ATTN_MATMUL`, `_HIDDEN_FP32` and `_ATTN_FP32_ACC` knobs (`tt_diffusion_planner.tt.config.KNOBS`,
+pinned in `tt-model.yaml` `serve.env`). Setting one of them in the environment changes the graph and invalidates the
+accuracy figures of the card until the gates are re-run.
+
+## Warm-up
+
+`from_pretrained` returns a warm model: it builds the graph, runs the plan once eagerly (this first run compiles every kernel into the JIT cache), then captures the whole plan as one metal trace (`warmup_variants="default"`: the variant `plan`) with program-cache misses forbidden, so no later call compiles anything. `model.warmup()` is idempotent; `warmup_variants="none"` defers the capture to `model.warmup()`.
+
+Measured on the shipped sample (`model.info["warmup_ms"]`, 2026-10-09): the load takes 315 s with an empty JIT cache and 8.6 s with a warm one (build 0.53 s: the ONNX initializers read and 48.1 MB of weights and constants uploaded; warm-up and capture 3.7 s; the rest is the device open). The first call then takes 120 ms and the second 120 ms (the stage bench's steady state: 118 ms p50 for decoded arrays, 125 ms for an `.npz` path). The trace holds 74.6 MB of DRAM (`trace_region_size` 192 MiB).
+
+## Call: `model(...)`
+
+| Argument | Type | Description |
+|---|---|---|
+| `inputs` | mapping / `.npz` path / bytes / JSON envelope | the 15 raw planner tensors (see "Input types") |
+| `velocity_smoothing_window` | int, 1..79, default 8 | forward moving average of the trajectory velocity, in points |
+| `stopping_threshold` | float >= 0, default 0.3 | force stop below this smoothed speed (m/s), when the ego moves |
+| `turn_indicator_keep_offset` | float, default -1.25 | added to the KEEP logit before the turn-indicator decision |
+| `return_denoising_steps` | bool, default False | add the ego row of the 11 solver iterates (`out.meta["denoising_steps"]`, `[11, 81, 4]`, the node's `~/debug/denoising_steps`) |
+
+### Input types
+
+- `inputs=`: the 15 raw tensors of the Autoware node's `DiffusionPlannerCore::create_input_data()` (batch 1,
+  float32, ego `base_link` frame, BEFORE normalization; names and shapes in `tt_diffusion_planner.INPUT_SCHEMA`):
+  a `{name: array}` mapping (numpy or torch), an `.npz` path or its bytes, or the `/predict` envelope
+  `{"format": "npz", "data": <base64>}` / `{"format": "json", "arrays": {...}}`. Names, shapes and finite values are
+  checked (`InputError`). `tt_diffusion_planner.load_inputs(source)` is the same decoder.
+- Any other input (`points`, `images`, `calibration`, ...) is refused (`InputError`).
+
+### What the caller keeps (the API is stateless)
+
+One call is one independent plan. The Autoware node keeps state between plans; to reproduce it over a sequence of
+plans, the caller keeps the same state (SERVING.md 3.5 has the details):
+
+- **The tensors.** The node's pre-processing from ROS messages and the Lanelet2 map (per-UUID agent buffers and their
+  0.1 s resampling, the ego history, lane / route / polygon / line-string selection and encoding, traffic lights,
+  speed limits, goal, turn-indicator report history) is not part of the bundle.
+- **The turn-indicator hold window** (`turn_indicator_hold_duration`, 1.0 s in the node's YAML). Each call decides
+  with a fresh manager; apply the node's hold across calls with the node's own manager:
+
+  ```python
+  from tt_diffusion_planner.host.postprocess import TurnIndicatorManager
+
+  manager = TurnIndicatorManager()                     # hold 1.0 s, KEEP offset -1.25 (the node's YAML)
+  out = model(inputs=tensors)
+  decision = manager.evaluate(out.turn_indicator["logits"], stamp_s=now_s, prev_report=int(tensors["turn_indicators"][0, 30]))
+  command = decision.command                           # the held command while less than 1.0 s has passed
+  ```
+
+- **The initial solver state** `sampled_trajectories` (`x_T`, normalised space): zeros is the node's default
+  (`temperature: [0.0]`); for a temperature > 0 send N(0, 1) x temperature; for the RTC prefix (`delay_step` > 0) put
+  the previous plan into the ego row, slots t = 0 .. delay_step (x as (x - 10) / 20, y as y / 20, cos / sin as they are,
+  in the current ego frame). `delay` is accepted and ignored (the node's multi-step mode never reads it).
+- **The map frame.** Outputs are in `base_link`; the node transforms them with the current ego pose to `map`.
+
+## Output
+
+`model(...)` returns a `tt_diffusion_planner.Output` (= `ttaw.outputs.Trajectory`); `out.to_dict()` is exactly the `POST /predict` body (SERVING.md section 3.2).
+
+| field | type | meaning |
+|---|---|---|
+| `poses` | float32 `[80, 7]` | the ego trajectory at 0.1-8.0 s in `base_link`: x, y, yaw, cos, sin, velocity, acceleration (`out.columns`), post-processed like the node's `~/output/trajectory` |
+| `turn_indicator` | dict | `command` (0 NO_COMMAND, 1 DISABLE, 2 ENABLE_LEFT, 3 ENABLE_RIGHT), `command_name`, `keep_selected`, `held` (always false: no hold window), the 5 raw `logits` (NONE, DISABLE, LEFT, RIGHT, KEEP), the decision's `probabilities` |
+| `predicted_agents` | float32 `[N, 80, 5]` | x, y, yaw, cos, sin of each non-empty neighbour row, in input order |
+| `meta` | dict | `predicted_agent_rows` (the rows of `predicted_agents`), `predicted_agent_columns`, `force_stop`, `time_from_start_s`, `valid_counts` (the entities the encoder saw), and with `return_denoising_steps` the encoded `denoising_steps` |
+| `timing_ms` | dict | `preprocess`, `device` (host tensors + H2D + replay + D2H), `postprocess`, `total` |
+
+`out.to_dicts()` gives one `{x, y, yaw, cos, sin, velocity, acceleration}` dict per trajectory point; `out.to_dict("npz")` adds the poses as a lossless base64 NPZ array.
+
+## Lifetime and information
+
+- `model.close()` releases the trace and the persistent device tensors and closes the chip if the model opened it;
+  idempotent. `with` calls it for you; an unclosed model is closed when Python exits.
+- `model.info`: weights (repo, tag, revision, path), device (dispatch, grid, CQs, fallback), variant, warm variants,
+  warm-up times, runtime parameter defaults, the input schema, the numerics options and precision policy in effect, the
+  trace (variants, persistent inputs, trace buffers in MB).
+- Calls from several threads are safe: the device calls are serialised. One model per process per chip.
+
+## Speed
+
+Warm calls, batch 1, ETH dispatch, 1 CQ, 12×10, the pinned numerics (`code/scripts/bench.py`, 100 iterations; the numbers of `OPT_BASELINE.md`, 2026-10-08, on a shared host; p50, with p99 in brackets):
+
+| stage | shipped sample `kashiwanoha_dense` |
+|---|---:|
+| `.npz` decode + schema check (path inputs only) | 7.02 (18.20) ms |
+| host pre-processing (the node's normalization, the encoder's host features, masks, `x_T`) | 4.75 (12.55) ms |
+| packing the 19 persistent trace inputs · ttnn host tensors · H2D | 0.45 · 2.41 · 1.14 ms |
+| **device trace, one blocking plan** | **102.13** (104.81) ms |
+| D2H (one packed read, 460 KB) | 0.58 ms |
+| host post-processing (trajectory, predicted paths, turn decision) | 4.32 (11.54) ms |
+| **`model(inputs=arrays)` end to end** | **117.90** (134.56) ms |
+| `model(inputs=<.npz path>)` | 124.76 (147.74) ms |
+| back-to-back replays (device time per plan) | 102.04 ms = 9.80 plans/s |
+
+The device time does not depend on the scene: every plan computes the full capacities (re-checked on c0d84f9: kashiwanoha_dense 102.10, straight_road 102.11, a nuScenes instant 102.09 ms). Throughput above one plan per ~118 ms needs pipelining of the host work of neighbouring requests (not implemented); 2 CQs do not help a synchronous request (`OPT_BASELINE.md`). Where the time goes and what comes next: `OPT_REPORT.md`.
+
+## Limits
+
+- Batch 1 on the chip; one model per process.
+- Fixed shapes of the v5.0 export (320 neighbours, 140 lanes, 25 route lanes, 10 polygons, 60 line strings, 31 history
+  and 80 future steps) and 10 DPM-Solver steps (11 decoder evaluations) are compiled into the trace; every plan computes
+  the full capacities, so the device time does not depend on the scene.
+- The node's guidance services (start / stop / centerline guidance) are not available (the node's default is off).
+- Accuracy is agreement with the fp32 CPU reference of the same network (README "Demo & Performances"); the planner's
+  driving quality is the weights' (trained by TIER IV on data that is not public).

README.md

@@ -0,0 +1,195 @@
+---
+tags:
+- blackhole
+- p150
+- tt-dit-server
+- tt-model-cache
+- tt-model-container
+- tenstorrent
+- ttnn
+- tt-metal
+- tt-nn
+- autoware
+- autonomous-driving
+- planning
+- trajectory-generation
+- motion-prediction
+- diffusion
+- diffusion-planner
+- tt-model-catalog
+pipeline_tag: robotics
+license: apache-2.0
+license_link: https://huggingface.co/AutowareFoundation/diffusion_planner
+base_model:
+- AutowareFoundation/diffusion_planner
+---
+
+# diffusion-planner-p150
+
+Diffusion Planner v5.0 (Autoware diffusion_planner): the network Autoware deploys in `autoware_diffusion_planner`, ported to one Tenstorrent Blackhole p150 with tt-nn. The whole plan runs on the chip as one metal trace: the scene encoder, the 11 DiT decoder evaluations of the DPM-Solver++(2M) loop with their solver updates, and the turn-indicator head. The Autoware planner tensors in (ego and neighbour histories, lanes, route, polygons, line strings, goal, ego shape, turn-indicator history); an 8 s ego trajectory, the predicted 8 s paths of the neighbours and a turn-indicator command out, with the node's exact pre- and post-processing.
+Weights: [AutowareFoundation/diffusion_planner `v5.0`](https://huggingface.co/AutowareFoundation/diffusion_planner/tree/423efde67f5414734da43a7ad856c17ceb8b51aa) · Paper: [arXiv:2501.15564](https://arxiv.org/abs/2501.15564) · Autoware package: [autoware_diffusion_planner](https://github.com/autowarefoundation/autoware_universe/tree/9ceaccf026c31ffc5319bc9eeb4bd7bede0af3fd/planning/autoware_diffusion_planner) · Training code: [tier4/Diffusion-Planner (TIER IV training fork)](https://github.com/tier4/Diffusion-Planner) · Port: [`code/`](https://huggingface.co/changh95/diffusion-planner-p150/tree/main/code)
+
+Runs on **p150** (mesh `P150`). Configuration: dispatch on the ETH cores, 1 command queue, 12×10 compute grid. Numerics (the default and the `serve.env` pins): fp32 residual streams and solver state, HiFi4 with fp32 accumulation, split hi / lo matmuls for the mixer inputs and every decoder linear, fp32 LayerNorm in the mixers and the decoder, fp32 matmul attention in the fusion encoder and the decoder: the configuration the end-to-end accuracy gates need (Caveats). All numbers on this card were measured in this configuration.
+
+Packaged and published with [tt-model-manager](https://github.com/tenstorrent/tt-model-manager) 0.1.0 (manifest schema 5.1).
+
+## Quickstart (Python)
+
+Prerequisite: a tt-metal / ttnn environment at tt-metal [`44d66500520`](https://github.com/tenstorrent/tt-metal/commit/44d66500520fda9f2c7060c0f6b41ec48f7ab37e) with [`patches/tt-metal-eth-dispatch.patch`](patches/tt-metal-eth-dispatch.patch) applied. ttnn is not on PyPI.
+
+```bash
+hf download changh95/diffusion-planner-p150 --exclude "image/*" --local-dir diffusion-planner-p150 && cd diffusion-planner-p150
+pip install -e .                        # adds numpy<2, pillow, pyyaml, onnx, huggingface_hub; ttnn and torch come from tt-metal
+pip install -e ".[server,test]"         # optional: the HTTP server and the tests
+```
+
+Run the snippet from the model repo root: `code/tt_diffusion_planner/samples/kashiwanoha_dense.npz` is a path relative to it.
+
+```python
+from tt_diffusion_planner import DiffusionPlanner
+
+with DiffusionPlanner.from_pretrained(device_id=0) as model:      # weights -> your HF cache, trace captured
+    out = model(inputs="code/tt_diffusion_planner/samples/kashiwanoha_dense.npz")   # the 15 raw planner tensors: .npz path, its bytes, or {name: array}
+
+print(out.columns)            # x, y, yaw, cos, sin, velocity, acceleration (base_link, 0.1-8.0 s)
+print(out.poses[:5])
+print(out.turn_indicator["command_name"], out.predicted_agents.shape)
+```
+
+- `from_pretrained` downloads the three v5.0 ONNX files and `diffusion_planner.param.json` (58.9 MB) of [`AutowareFoundation/diffusion_planner`](https://huggingface.co/AutowareFoundation/diffusion_planner) at the pinned commit `423efde67f5` (tag `v5.0`) to your HF cache (no token needed), checks their sha256, opens the chip, builds the graph and captures the metal trace. The first load compiles the kernels (315 s with an empty JIT cache, firmware and every kernel compiled); later loads take about 9 s (device open, reading and uploading the weights, warm-up and trace capture).
+- The trace is captured during the load, so the first call is as fast as the later calls and no call compiles anything.
+- The `with` block releases the trace and closes the chip. Without `with`, call `model.close()`.
+
+| | |
+|---|---|
+| **Input** | `inputs=`: the 15 raw tensors of the node's `create_input_data()` (ego frame, before normalization; batch 1): an `.npz` path or its bytes, a `{name: array}` mapping, or the `/predict` JSON envelope. Checked against `DiffusionPlanner.INPUT_SCHEMA` (names, shapes, finite values). Converting ROS messages and the Lanelet2 map into these tensors stays with the client. |
+| **Options** | `velocity_smoothing_window=8`, `stopping_threshold=0.3`, `turn_indicator_keep_offset=-1.25`, `return_denoising_steps=False`. `from_pretrained(device_id=0, dispatch="eth", weights_dir=None, device=None)`. |
+| **Output** | `Trajectory`: `poses` float32 [80, 7] (x, y, yaw, cos, sin, velocity, acceleration; base_link), `turn_indicator` (command, logits, probabilities), `predicted_agents` float32 [N, 80, 5], `timing_ms`, `meta` (the neighbour rows, force stop, the solver iterates on request). |
+| **Methods** | `out.to_dict()` gives the `/predict` JSON. `out.to_dicts()` gives one dict per trajectory point. |
+
+- The API gives the same output as the HTTP server `/predict`: both share the decoders, the device trace and the host post-processing (checked on the device by `test_api_equals_server`).
+- The API is stateless: one call is one plan. What the Autoware node keeps between plans stays with the caller: the turn-indicator hold window (1.0 s; the node's manager ships as `tt_diffusion_planner.host.postprocess.TurnIndicatorManager`), the initial solver state `sampled_trajectories` (zeros = the node's default temperature 0; noise for a temperature > 0; the previous plan for the RTC prefix) and the agent and ego histories. Details: [`code/PYTHON.md`](code/PYTHON.md) "What the caller keeps".
+- One model uses one chip; calls from several threads are serialised.
+- Full reference: [`code/PYTHON.md`](code/PYTHON.md). Runnable example: [`examples/quickstart.py`](examples/quickstart.py) (also writes `quickstart_bev.png`, the input tensors and the plan from above).
+
+## Serving (HTTP)
+
+```bash
+tt-model pull  changh95/diffusion-planner-p150 --with-weights
+tt-model serve changh95/diffusion-planner-p150       # or with tt-cli: tt serve changh95/diffusion-planner-p150
+python3 code/tt_diffusion_planner/server/client.py --inputs code/tt_diffusion_planner/samples/kashiwanoha_dense.npz --out req.json
+curl -s localhost:20000/predict -H 'Content-Type: application/json' -d @req.json
+tt model stop changh95/diffusion-planner-p150
+```
+
+- The image does not contain the weights. `--with-weights` puts them in your HF cache.
+- The server uses port 20000 (or the next free port). It is ready when the log shows `Application startup complete`.
+- One serve profile, the default (`tt-model profiles changh95/diffusion-planner-p150`). `serve.env` pins ETH dispatch, 1 CQ and the numerics knobs.
+- Run the request lines from the model repo root (the `hf download` of the Quickstart): the client and the sample are files of this repo. `code/tt_diffusion_planner/server/client.py` needs only the Python standard library (no numpy); add `--url http://127.0.0.1:20000` to send the request.
+- `POST /predict`: `inputs` (the 15 raw tensors of the Autoware node's `create_input_data()` in the ego frame, before normalization: a base64 `.npz` or `{"format": "json", "arrays": {...}}`); optional `params` (`velocity_smoothing_window` 8, `stopping_threshold` 0.3, `turn_indicator_keep_offset` -1.25, `return_denoising_steps` false), `output_format`. Also `GET /health`, `GET /info`, `GET /v1/models` (stub). Contract: [`SERVING.md`](SERVING.md) section 3.
+
+The response for the shipped sample (served on the p150; trajectory cut to 3 of 80 rows):
+
+```json
+{
+ "model": "diffusion-planner-p150",
+ "frame_id": "base_link",
+ "meta": {"predicted_agent_columns": ["x", "y", "yaw", "cos", "sin"], "predicted_agent_rows": [0, 1, 2, "... 85 more"], "force_stop": false, "time_from_start_s": [0.1, 0.2, 0.3, "... 77 more"], "valid_counts": {"ego": 1, "neighbor": 88, "static": 0, "lane": 123, "route": 17, "polygon": 0, "line_string": 60, "goal": 1, "ego_shape": 1, "turn": 1}},
+ "timing_ms": {"preprocess": 3.8, "device": 105.3, "postprocess": 3.2, "total": 122.8, "decode": 8.5, "model_call": 112.5},
+ "num_poses": 80,
+ "columns": ["x", "y", "yaw", "cos", "sin", "velocity", "acceleration"],
+ "trajectory": [[0.365, 0.01, -0.017, 0.9962, -0.0169, 3.8059, -0.0431], [0.7631, -0.0022, -0.0414, 0.9966, -0.0413, 3.8016, -0.5485], [1.1524, -0.0282, -0.0675, 0.9942, -0.0674, 3.7468, -0.4708], "... 77 more rows"],
+ "turn_indicator": {"command": 1, "command_name": "DISABLE", "keep_selected": true, "held": false, "logits": [-15.960084915161133, -5.125061511993408, -5.230083465576172, -0.7658059597015381, 5.504596710205078], "probabilities": [1.651601411190029e-09, 8.38487030705437e-05, 7.548934809165075e-05, 0.006556871347129345, 0.993184506893158]},
+ "predicted_agents": {"format": "npz", "key": "predicted_agents", "dtype": "float32", "shape": [88, 80, 5], "data": "<base64 npz>"}
+}
+```
+
+- `trajectory`: 80 points at 0.1-8.0 s in `base_link` (the ego frame of the input tensors), post-processed like the node's `~/output/trajectory`: velocity from consecutive points, forward moving average over `velocity_smoothing_window` points, force stop (poses frozen once the smoothed speed falls below `stopping_threshold` while the ego moves), acceleration by finite difference. `yaw` is what `tf2::getYaw` reads from the node's (unnormalised) quaternion; `cos` / `sin` are the raw network outputs.
+- `turn_indicator.command`: 0 NO_COMMAND, 1 DISABLE, 2 ENABLE_LEFT, 3 ENABLE_RIGHT (KEEP repeats the last input report); the node's 1 s hold window needs state across calls and is not applied (see above).
+- `predicted_agents`: one 80-point path (x, y, yaw, cos, sin) per non-empty neighbour row, in input order (`meta.predicted_agent_rows`).
+
+## Demo
+
+| Shipped sample `kashiwanoha_dense.npz`: the p150 plan next to the fp32 CPU reference | The 11 solver iterates of the same plan (ego row), p150 and CPU |
+|:---:|:---:|
+| ![](media/dp_kashiwanoha_dense_tt_vs_cpu.png) | ![](media/dp_kashiwanoha_dense_denoising_steps_tt.png) |
+| **Shipped sample `straight_road.npz`** | **Agreement with the fp32 CPU reference on all 99 gated scenes** |
+| ![](media/dp_straight_road_tt_vs_cpu.png) | ![](media/dp_tt_vs_cpu_agreement_99_scenes.png) |
+
+On nuScenes v1.0-mini planning instants (p150 outputs; the scenes are converted from the dataset into the planner tensors and are not in this repository). **Non-commercial, CC BY-NC-SA 4.0.** The grey path with hollow dots is the logged drive; the model never saw nuScenes (see Caveats).
+
+| scene-0061, 2 Hz sequence (33 plans): following a van, then a left turn | scene-0061 key-frame 18, in the turn: CAM_FRONT with the plan as a vehicle-width ribbon |
+|:---:|:---:|
+| ![](media/dp_nuscenes_scene-0061_bev_tt_NC.gif) | ![](media/dp_nuscenes_scene-0061_kf18_cam_front_tt_NC.jpg) |
+| **scene-0757 key-frame 11: the turn head commands RIGHT before the driver's blinker** | **scene-0757 key-frame 11, CAM_FRONT** |
+| ![](media/dp_nuscenes_scene-0757_kf11_bev_tt_NC.png) | ![](media/dp_nuscenes_scene-0757_kf11_cam_front_tt_NC.jpg) |
+| **scene-0103 key-frame 12 (mini_val, Boston)** | **scene-0103 key-frame 12, CAM_FRONT** |
+| ![](media/dp_nuscenes_scene-0103_kf12_bev_tt_NC.png) | ![](media/dp_nuscenes_scene-0103_kf12_cam_front_tt_NC.jpg) |
+| **scene-0061 key-frame 6: approach behind the van** | **scene-0916 key-frame 11 (mini_val): parking-lot right turn** |
+| ![](media/dp_nuscenes_scene-0061_kf06_bev_tt_NC.png) | ![](media/dp_nuscenes_scene-0916_kf11_bev_tt_NC.png) |
+
+nuScenes renders: rendered from the nuScenes dataset (v1.0-mini, CAN bus expansion and map expansion v1.3), © Motional AD Inc., CC BY-NC-SA 4.0 and the nuScenes Terms of Use; non-commercial use only; Motional does not endorse this work. The kashiwanoha sample is derived from the Apache-2.0 map AutowareFoundation/map-carla-kashiwanoha. Sources, changes and the full attributions: [`media/ATTRIBUTION.md`](media/ATTRIBUTION.md).
+
+## Demo & Performances
+
+Warm, batch 1; the stage bench 2026-10-08, the served rows, load times and the re-check 2026-10-09. Latency: the stage bench of [`OPT_BASELINE.md`](OPT_BASELINE.md) (`code/scripts/bench.py`, 100 iterations per stage) on the shipped sample `kashiwanoha_dense.npz` (88 neighbours, 123 lanes, 17 route lanes, 60 line strings; the device time is the same for every scene: every plan computes the full capacities); the served rows from uvicorn on the host (the app the container runs, with its serve pins) and a loopback client, 50 requests of the shipped sample. The host is shared with other jobs, so the host stages move with its load by several ms; the device rows repeat to ±0.05 ms. Accuracy: the p150 output against the fp32 CPU reference of the same network on 99 scenes: the 2 shipped samples, 5 research scenes and 92 nuScenes v1.0-mini planning instants (the frozen end-to-end gates), and against the research pipeline's ONNX Runtime outputs as an independent oracle.
+
+| Metric | Performance |
+|---|---:|
+| Agreement with the fp32 CPU reference, shipped sample `kashiwanoha_dense` (8 s ego plan, 88 neighbours) | ego max **2.3 cm** / mean 1.1 cm; turn command identical; neighbours: median per-agent max 8.6 cm |
+| Agreement, shipped sample `straight_road` | ego max 4.9 cm / mean 1.8 cm; turn command identical; neighbours 6.3 cm |
+| Agreement, all 99 gated scenes (2 samples, 5 research scenes, 92 nuScenes-mini instants) | worst ego max **0.313 m** / mean **0.143 m** (gates 1.0 / 0.3 m; nuscenes/scene-0103_kf14); ego mean: median 1.3 cm, 95th percentile 6.2 cm; turn command identical **99 / 99**; neighbours: median per-agent max ≤ 0.086 m (gate 1.5 m) |
+| Agreement with an independent oracle: the research pipeline's ONNX Runtime outputs (raw x0), 92 nuScenes instants + the 33-plan scene-0061 sequence | worst ego max 0.313 m / mean 0.143 m, turn command identical 92 / 92; sequence: worst ego max 0.118 m / mean 0.049 m, turn 33 / 33; every instant within the gates |
+| Module PCC vs the fp32 reference (encoder categories, encoding, teacher-forced decoder evaluation; gate 0.999) | ≥ 0.999952 / 0.999978 / ≥ 0.9999995 |
+| Open-loop vs the nuScenes log, 92 instants (a sanity check against one human driver, not a planning metric) | p150 ADE / FDE at 8 s 4.75 / 11.87 m (CPU reference 4.74 / 11.87; constant velocity 4.99 / 13.06); turn command = logged blinker 88 / 92 (CPU 88 / 92) |
+| Python `model()` call, shipped sample (host pre-processing, H2D, trace, D2H, host post-processing) | **117.9 ms p50** (p99 134.6) · 8.5 plans/s |
+| Served `/predict` `timing_ms.total` (uvicorn on the host, the shipped sample) | **123.1 ms median** (min 122.5; of which decode 8.6) |
+| Served client round trip, loopback (base64 `.npz` request, 0.15 MB) | 127.5 ms median |
+| Device trace, one blocking plan (encoder + 11 DiT evaluations + 10 solver updates + turn head) | **102.13 ms** |
+| Back-to-back trace replays | **102.04 ms per plan** · 9.80 plans/s |
+| Host pre-processing · pack · host tensors · H2D · D2H · host post-processing | 4.75 · 0.45 · 2.41 · 1.14 · 0.58 · 4.32 ms |
+| `from_pretrained` load: empty JIT cache / warm cache | 315 s / 8.6 s |
+
+All numbers in this table were measured with dispatch on the ETH cores, 1 command queue and a 12×10 compute grid on one p150, with the pinned numerics of `serve.env`. Accuracy is agreement with the fp32 CPU reference of the same Autoware network (same weights, same pre- and post-processing); no dataset-level accuracy is claimed: the paper's benchmark is nuPlan closed loop (an account-gated dataset and simulator, not run here), and the deployed v5.0 weights were trained by TIER IV on data that is not public, so no public benchmark is in-domain. Details: [`VERIFICATION_2026-10-08.md`](VERIFICATION_2026-10-08.md), [`OPT_BASELINE.md`](OPT_BASELINE.md), [`OPT_REPORT.md`](OPT_REPORT.md).
+
+No GPU comparison: no GPU was available on the host where this port was built and measured, so this card makes no GPU speed claim. The reference rows are the port's own fp32 CPU reference on the same host (a correctness baseline, not a speed target). Autoware's CHANGELOG quotes 5.13 ms mean (300 runs) for an older single-step engine of this planner on an RTX PRO 6000 Blackwell with TensorRT (precision not stated); it is not like-for-like with this v5.0 multi-step port. p150 power was not measured, so no efficiency comparison is made.
+
+## Caveats
+
+- First release: **baseline port, optimization pending.** The plan is one metal trace and kernel-bound (6,282 programs; op-to-op gaps 4.4 ms of a 103.7 ms span). The **first optimization target is the precision cost**: the numerics defaults that the end-to-end gates need (split hi / lo matmuls, fp32 LayerNorm, fp32 matmul attention) cost 33.4 ms per plan (102.0 ms vs 68.6 ms with the first device round's defaults, which fail the gates); fused kernels are to recover it without dropping precision. A second sink of similar size is unrelated to precision: the encoder's channel-MLP and pre-projection matmuls run on 4-8 cores (25.8 ms). [`OPT_REPORT.md`](OPT_REPORT.md) ranks what comes next.
+- Deployment status in Autoware: `autoware_diffusion_planner` is an alternative to the default rule-based planning stack, selected with `planning_setting:=diffusion_planner` (package README); it is aimed at Autoware's proposed new planning framework. This bundle is not a ROS 2 node (Python API and HTTP) and not a certified Autoware component; do not use it for safety-critical driving decisions or closed-loop vehicle control.
+- Stateless API: the node's state between plans (the turn-indicator hold window, the RTC prefix and temperature of the initial solver state, the agent buffers and the ego history) is the client's ("What the caller keeps" in [`code/PYTHON.md`](code/PYTHON.md)). The node's guidance services (start / stop / centerline guidance) are off, as in the node's default.
+- Precision policy of this release: fp32 residual streams and solver state; HiFi4 with fp32 accumulation for every matmul; the ego / neighbour pre-projection as a pad-relative fp32 island; split hi / lo matmuls (bf16 hi + fp32 lo parts, ~1e-5 relative, because a device fp32 matmul rounds its operands like TF32) for the mixer inputs and every decoder linear; an fp32 LayerNorm decomposition in the mixers and the decoder (the fused `ttnn.layer_norm` loses the per-entity signal on the mixers' offset-dominated rows); fp32 matmul attention in the fusion encoder and the decoder; the turn head in fp32; the other weights and the hidden MLP activations of the mixers and the fusion encoder in bf16. The plan's sensitivity to these choices is chaotic per scene: with the first device round's numerics, one nuScenes instant (scene-0103_kf14) moved 0.35 m on average while the module PCCs differed only in the 5th decimal. So every numerics change is re-checked on all 99 scenes.
+- Validation scope: the p150 output agrees with the fp32 CPU reference on 99 scenes (above). The two shipped samples and the five research scenes are synthetic-but-faithful scenes built with a Python port of the node's tensor construction; the 92 nuScenes instants are converted from nuScenes v1.0-mini, a domain the model never saw (Singapore and Boston, right-hand traffic in Boston, oracle tracks from 2 Hz annotations, no traffic-light states, no speed limits, stop areas instead of stop lines). On them the plans are plausible but conservative (moving plans about 17 % shorter than the logged drive); the open-loop numbers above are a sanity check against one human driver, not a planning metric.
+- Neighbour predictions: the gate is the median over agents of each agent's max displacement, so single agents can differ more. On the shipped sample `kashiwanoha_dense` (container smoke, served p150 output vs the stored CPU reference) the per-agent max displacement is 8.6 cm median and 0.26 m at the 90th percentile; the worst of the 88 agents differs by 4.31 m. The ego plan is gated on its max and mean; neighbour paths only on that median.
+- Documented deviations from the node: the output stays in `base_link` (the node transforms it to `map` with the ego pose); `yaw` is what `tf2::getYaw` reads from the node's quaternion of the unnormalised cos / sin rotation (it differs from atan2(sin, cos) when |(cos, sin)| ≠ 1, as in the node); the speed masks follow the node's TensorRT path (`> FLT_EPSILON`); the turn indicator is decided without the hold window; `delay` is accepted and ignored (the node's multi-step mode never reads it).
+- Does not scale to multiple p150 in a mesh configuration. The build uses a 12×10 compute grid of Tensix cores: the dispatch functions move from one Tensix column to the ETH cores (`patches/tt-metal-eth-dispatch.patch`), so this build assumes that you do not need chip-to-chip ethernet communication.
+- `dispatch="worker"` (server: `DIFFUSION_PLANNER_DISPATCH=worker`) is an A/B opt-in. On a p150 it gives an 11×10 grid (101.87 ms per replay, the same as ETH within 0.2 %); if ETH dispatch is not available (tt-metal without the patch), the model falls back to it with a warning. The numbers on this card do not apply to that mode.
+- Batch 1, one plan per request; requests are serialised on the chip. The shapes of the v5.0 export (320 neighbours, 140 lanes, 25 route lanes, 10 polygons, 60 line strings, 31 history and 80 future steps) and 10 DPM-Solver steps are compiled into the trace, and every plan computes them in full, so the device time does not depend on the scene.
+- Not an OpenAI-compatible API; `GET /v1/models` is a stub so the tt-model ready card does not 404.
+- p150 power was not measured, so no efficiency comparison is made.
+
+## Licensing
+
+- Weights: [AutowareFoundation/diffusion_planner](https://huggingface.co/AutowareFoundation/diffusion_planner) at tag `v5.0` (commit `423efde67f5414734da43a7ad856c17ceb8b51aa`), Apache-2.0 per its model card. Not redistributed here: the package only points to them. The upstream card states that TIER IV trained the models on TIER IV synthetic and real driving data; the dataset composition is not publicly documented.
+- Pre- and post-processing ported from autoware_universe [`planning/autoware_diffusion_planner`](https://github.com/autowarefoundation/autoware_universe/tree/9ceaccf026c31ffc5319bc9eeb4bd7bede0af3fd/planning/autoware_diffusion_planner) (Apache-2.0).
+- Port and serving code (`code/`): Apache-2.0. `patches/tt-metal-eth-dispatch.patch` modifies tt-metal (Apache-2.0).
+- Sample data: `code/tt_diffusion_planner/samples/kashiwanoha_dense.npz` is derived from the Apache-2.0 Lanelet2 map [AutowareFoundation/map-carla-kashiwanoha](https://huggingface.co/datasets/AutowareFoundation/map-carla-kashiwanoha) (0.2.0) with a scripted ego, route and agents; `straight_road.npz` is a procedural scene generated by this repo. Both Apache-2.0, each with its stored CPU-reference output (`*.reference.json`). Only these redistributable samples ship; the nuScenes-derived planning instants of the accuracy tables are not in this repository.
+- Demo media (`media/`, sources and changes in [`media/ATTRIBUTION.md`](media/ATTRIBUTION.md)):
+  - nuScenes renders (`media/*_NC.*`), **non-commercial, CC BY-NC-SA 4.0**: Rendered from the nuScenes dataset (v1.0-mini, CAN bus expansion and map expansion v1.3), © Motional AD Inc., CC BY-NC-SA 4.0 and the nuScenes Terms of Use (https://www.nuscenes.org/terms-of-use). Non-commercial use only; adaptations under the same license. Motional does not endorse this work. Cite: H. Caesar et al., *nuScenes: A Multimodal Dataset for Autonomous Driving*, CVPR 2020.
+  - Renders of the shipped samples: Apache-2.0 (kashiwanoha map: AutowareFoundation/map-carla-kashiwanoha@0.2.0, Apache-2.0).
+
+## Provenance
+
+These are the exact sources the container image was built from:
+
+| component | built from |
+| --- | --- |
+| tt-metal | [`44d66500520fda9f2c7060c0f6b41ec48f7ab37e`](https://github.com/tenstorrent/tt-metal/commit/44d66500520fda9f2c7060c0f6b41ec48f7ab37e) + [`patches/tt-metal-eth-dispatch.patch`](patches/tt-metal-eth-dispatch.patch) (sha256 `08d0ddf6…45cc`, 4 files; dirty tree: the image includes the patch) |
+| weights | [`AutowareFoundation/diffusion_planner@423efde67f5414734da43a7ad856c17ceb8b51aa`](https://huggingface.co/AutowareFoundation/diffusion_planner/tree/423efde67f5414734da43a7ad856c17ceb8b51aa) (tag `v5.0`), files `diffusion_planner_encoder.onnx, diffusion_planner_decoder.onnx, diffusion_planner_turn_indicator.onnx, diffusion_planner.param.json` (sha256 `2856886a…ca49`, `eb30c0c0…57ca`, `07acfb58…a732`, `ee3145b6…a268`, checked at load) |
+| Autoware reference | autoware_universe [`9ceaccf026c31ffc5319bc9eeb4bd7bede0af3fd`](https://github.com/autowarefoundation/autoware_universe/tree/9ceaccf026c31ffc5319bc9eeb4bd7bede0af3fd) (`planning/autoware_diffusion_planner`, package 0.53.0, `multi_step` mode) |
+| shared package | `ttaw` 0.20.0, vendored as `code/tt_diffusion_planner/ttaw` from the Autoware ports' shared `common` repository at commit `89dec49` (`code/tt_diffusion_planner/ttaw/VENDORED.json`: version, commit and per-file sha256) |
+| `code/` digest (image) | `c0e7abb7888098a9` (sha256, first 16 hex digits; `built.code_sha256` of `tt_kernel_manifest.json`) |
+| image | `tt-model/diffusion-planner-p150:3b96d8ea7190` (`sha256:3b96d8ea71902fe6a00f1792dd41290839b7758070431464cd613cde3f6bf909`) |
+| base images | build stage `ghcr.io/tenstorrent/tt-metal/tt-metalium/ubuntu-22.04-dev-amd64:latest` @ `sha256:df9d279c7f85c17c6fad982d196802682d669cca1b7ced9cbaad8181339cd5fc`; runtime stage `docker.io/library/ubuntu:22.04` @ `sha256:5ec03bb3441e8b0bf3b4f9cd4629a1ae763010dc3035bb8da3ae6cf026486401` (tt-model's `FROM` tags float; these are the digests this build resolved, see [`build_info.json`](build_info.json)) |
+| built | 2026-10-09T04:37:19+00:00 by tt-model 0.1.0 |

SERVING.md

@@ -0,0 +1,242 @@
+# Serving Diffusion Planner v5.0 (Autoware diffusion_planner) on Blackhole with tt-model-manager
+
+This repo is the authoring source of the **tt-model container package** `changh95/diffusion-planner-p150`
+(`kind: tt-dit-server`, schema 5.1): `tt-model.yaml` is the manifest, `code/` the port, and
+`code/tt_diffusion_planner/server/app.py` the ASGI app uvicorn runs. Weights are a pinned pointer, never baked into the
+image. The device open, the decoders, the Python-API contract and the HTTP contract come from
+`code/tt_diffusion_planner/ttaw/`, the shared package of the Autoware ports vendored into this repo
+(`ttaw/VENDORED.json` records its version, source commit and file hashes; it is not edited here).
+
+| item | value |
+|---|---|
+| tt-metal tree | `/home/ubuntu/experiments/tt-models/tt-metal` (main `44d66500520`, `v0.80.0-dev20261006-78-g44d6650052`, + `patches/tt-metal-eth-dispatch.patch`; torch 2.11.0+cpu) |
+| weights | `AutowareFoundation/diffusion_planner` @ `423efde67f5414734da43a7ad856c17ceb8b51aa` (tag `v5.0`; files `diffusion_planner_encoder.onnx`, `diffusion_planner_decoder.onnx`, `diffusion_planner_turn_indicator.onnx`, `diffusion_planner.param.json`; 58.9 MB; Apache-2.0; public, ungated; sha256 of every file checked at load) |
+| Autoware reference | `planning/autoware_diffusion_planner` @ autoware_universe `9ceaccf026c31ffc5319bc9eeb4bd7bede0af3fd` (package 0.53.0), the node's `multi_step` mode |
+| shared package | `ttaw` 0.20.0 (`common` @ `89dec49`) |
+| app | `tt_diffusion_planner.server.app:app` (uvicorn; the ASGI lifespan does weights -> device -> graph -> trace capture) |
+| device recipe | `ttnn.open_device(device_id, dispatch_core_config=DispatchCoreConfig(ETH), l1_small_size=32768, trace_region_size=192 MiB, num_command_queues=1)` (`DEVICE_DEFAULTS` in `code/tt_diffusion_planner/device.py`; the plan's trace holds 74.6 MB) |
+| graph | ONE metal trace per plan: the encoder (6 MLP-Mixer trunks, small encoders, 6 fusion blocks), the cross-attention K / V hoisted once, 11 DiT evaluations with the 10 fp32 DPM-Solver++(2M) updates and the prefix constraint, the turn-indicator head, one packed readback; 6,282 device programs |
+| hardware | one Blackhole p150 (`hardware: p150`, `mesh_device: P150`, `TT_MESH_SHAPE=1x1`), 12×10 compute grid |
+
+## 1. Run on the HOST (hardware validation, no Docker)
+
+The tt-metal `python_env` has ttnn and torch; `bin/tt-env.sh` puts the workspace's dev overlay (fastapi, uvicorn, onnx)
+on `PYTHONPATH` instead of installing into it. On the shared workspace box every command that opens the chip goes
+through the device lock (`bin/devrun`).
+
+```bash
+ROOT=/home/ubuntu/experiments/tt-models
+source $ROOT/bin/tt-env.sh                     # TT_METAL_HOME, PYTHONPATH (+ the dev overlay: fastapi, uvicorn, onnx), python_env
+cd $ROOT/bundles/diffusion-planner-p150
+export PYTHONPATH=$PWD/code:$PYTHONPATH
+export HF_MODEL=AutowareFoundation/diffusion_planner TT_MODEL_WEIGHTS_REVISION=423efde67f5414734da43a7ad856c17ceb8b51aa TT_MESH_SHAPE=1x1
+
+# host tests (no device; the device tests are skipped; ttnn is the fake of common/tests/host: a real ttnn host
+# tensor opens the chip, so only devrun jobs may build one)
+PYTHONPATH=$ROOT/research/packaging/scripts:$PYTHONPATH TT_VISIBLE_DEVICES=none \
+    python -m pytest -q -p no:cacheprovider -p fake_ttnn_plugin code/tt_diffusion_planner/tests
+# device tests (per-module PCC + end-to-end agreement; 99 scenes with the workspace goldens, the 2 shipped samples elsewhere)
+$ROOT/bin/devrun -t 1800 -- python -m pytest -q -s code/tt_diffusion_planner/tests/test_pcc_device.py code/tt_diffusion_planner/tests/test_e2e_device.py
+# the server, with the serve pins of tt-model.yaml, and the container smoke test against it
+$ROOT/bin/devrun -t 1800 -- bash -c 'env DIFFUSION_PLANNER_DISPATCH=eth DIFFUSION_PLANNER_NUM_CQS=1 \
+    python -m uvicorn --host 127.0.0.1 --port 20000 --lifespan on tt_diffusion_planner.server.app:app & \
+    S=$!; python3 code/tt_diffusion_planner/server/smoke_test.py --url http://127.0.0.1:20000 --wait 1200; R=$?; kill -TERM $S; wait $S; exit $R'
+```
+
+Boot log landmarks (they drive `tt-model serve`'s progress view, `boot_progress.py` TT_DIT_PHASES):
+`Loading weights` -> `Opening device` -> `Warming up: capturing trace ...` -> `Warmup complete` -> uvicorn
+`Application startup complete`. A cold JIT cache compiles every kernel first (315 s measured for
+`from_pretrained`); later boots take about 10 s to READY (measured on the host, warm JIT cache). Startup failures raise and uvicorn exits non-zero (no CPU
+fallback). SIGTERM: the lifespan releases the trace and closes the chip (within `tt-model stop`'s 120 s budget).
+
+Offline override (no Hub): `DIFFUSION_PLANNER_WEIGHTS_DIR=<dir holding diffusion_planner_encoder.onnx, diffusion_planner_decoder.onnx, diffusion_planner_turn_indicator.onnx, diffusion_planner.param.json>`.
+
+## 2. Package, serve, push (Docker)
+
+Docker 29 on this box is **rootful** (`/var/lib/docker`), and the user's session may not carry the `docker` group:
+wrap every docker-using command in `sg docker -c "..."` (no `docker-env.sh` is needed here; the reference bundles'
+`docker-env.sh` was the authors' rootless-Docker box). Run every `tt-model` command **from this directory**
+(`source.tt_metal` and `extra_code[].root: code` are CWD-relative) and point `--out` outside it.
+
+```bash
+ROOT=/home/ubuntu/experiments/tt-models; cd $ROOT/bundles/diffusion-planner-p150
+TTM=$HOME/.local/share/uv/tools/tt-model/bin/python
+
+# offline validation (seconds; no docker, no device) -- must print VALID
+$TTM -c "from tt_kernel.container_manifest import load_container_manifest as L; m=L('tt-model.yaml', check_sources=True); p=m.resolve_profile(); print('VALID', m.name, m.kind, p.hardware, p.mesh_device, m.weights_ref)"
+python3 $ROOT/research/packaging/scripts/check_bundle.py .            # conventions (add --stage publish before a push)
+
+# build (one at a time on the box: the absolute lock file): ~35 min cold, ~12 min after a code/ change (the C++
+# build re-runs, ccache-warm, whenever code/ changes), ~1 min for a manifest- or lock-only change
+flock $ROOT/.package.lock sg docker -c "tt-model package --container tt-model.yaml --out $ROOT/build"   # log: ~/.cache/tt-model/build/diffusion-planner-p150.log
+# provenance: the base-image digests this build resolved (tt-model's FROM tags float) -> build_info.json (published)
+sg docker -c "python3 $ROOT/research/packaging/scripts/record_build_info.py --staged $ROOT/build/diffusion-planner-p150 --bundle ."
+
+# serve + smoke + stop, all inside ONE device-lock window (there is one serve profile, the default; serve returns
+# once READY and leaves the container running; the script's trap saves the container log and always runs
+# `tt-model stop`, also when devrun's timeout fires: -k 150 > the 120 s grace). No token reaches the public weights
+# download. Evidence: logs/smoke/ (--log-dir).
+$ROOT/bin/devrun -t 3600 -k 150 -- env -u HF_TOKEN -u HUGGING_FACE_HUB_TOKEN \
+    sg docker -c "bash code/scripts/container_smoke.sh $ROOT/build/diffusion-planner-p150 20000"
+
+# publish: fill the provenance from the staged manifest, run the publish gate, overlay the hand-written docs, the pip
+# project and the build record onto the staged dir, then push (HF_TOKEN only from the environment)
+python3 $ROOT/research/packaging/scripts/instantiate_bundle.py --values $ROOT/research/diffusion-planner/bundle_values.json \
+    --fill . --manifest $ROOT/build/diffusion-planner-p150/tt_kernel_manifest.json
+python3 $ROOT/research/packaging/scripts/check_bundle.py . --stage publish
+rsync -a README.md SERVING.md OPT_BASELINE.md OPT_REPORT.md VERIFICATION_*.md tt-model.yaml pyproject.toml build_info.json \
+    examples media patches $ROOT/build/diffusion-planner-p150/
+cp code/PYTHON.md $ROOT/build/diffusion-planner-p150/PYTHON.md
+tt-model push $ROOT/build/diffusion-planner-p150 --publish
+```
+
+The smoke test fails unless `/info` reports ETH dispatch, the 12x10 grid and what the staged package pins
+(`DIFFUSION_PLANNER_DISPATCH`, `DIFFUSION_PLANNER_NUM_CQS`, `DIFFUSION_PLANNER_VARIANT`, the weights revision), and it
+compares the served trajectory of the shipped sample with the stored CPU-reference output
+(`code/tt_diffusion_planner/samples/kashiwanoha_dense.reference.json`: average displacement <= 0.3 m, final
+displacement <= 1.0 m). On the host, the same smoke test against uvicorn with the serve pins passed:
+`PASS diffusion-planner-p150: profile=- variant=default dispatch=eth grid=12x10 cqs=1 n=80 turn=DISABLE reference=kashiwanoha_dense.reference.json (trajectory ade=0.0109 fde=0.0173; predicted_agents max_abs=6.283) device_ms=109.402 total_ms=133.384 rtt_ms=139.0`
+
+(`predicted_agents max_abs` is reported, not gated. Here it is the yaw column at ±π: -3.1413 vs +3.1415
+rad, the same heading. The neighbour paths are gated in the end-to-end tests, on the per-agent maximum displacement.)
+
+`serve` publishes the first free port from 20000 and exports into the container: `HF_MODEL=AutowareFoundation/diffusion_planner`,
+`MESH_DEVICE=P150`, `TT_MESH_SHAPE=1x1`, `TT_MODEL_WEIGHTS_REVISION=423efde67f5414734da43a7ad856c17ceb8b51aa`, then `serve.env`. The HF cache is
+mounted at `/hf` (rw), the JIT cache at `/cache` (host `~/.cache/tt-model/diffusion-planner-p150/cache`), and the container
+sees only its own chip (`--device /dev/tenstorrent/<n>`). tt-cli users: `tt serve changh95/diffusion-planner-p150` /
+`tt model stop changh95/diffusion-planner-p150` (point tt at this tt-model with
+`tt config set tools.override.tt-model ~/.local/bin/tt-model` or `TT_TOOL_BIN_TT_MODEL`).
+
+What `push` does to the repo: `code/` and `image/` on the Hub become exactly the staged trees (`extra_code.paths` +
+`models/common/lightweightmodule.py`); every top-level file of the staged dir is uploaded (the overlaid README
+replaces the generated card; `pyproject.toml`, `PYTHON.md` and `build_info.json` arrive the same way, never through
+`code/`); top-level files already on the Hub and not in the staged dir are kept.
+
+## 3. The request / response contract
+
+| route | purpose |
+|---|---|
+| `GET /health` | `{"status": "ok" \| "starting" \| "error", "model", "device": {"dispatch", "grid", "cores", "device_id"}, "error"}`, always 200; `ok` only after warm-up |
+| `GET /v1/health` | same as `/health` (tt-model's hint for non-chat packages points here) |
+| `GET /info` | model, task, io, Autoware package + commit, weights {repo, tag, revision, path, license}, device (dispatch, grid, CQs, fallback), the input schema (the 15 tensors with shapes and dtypes), labels (turn-indicator logit order), variant, warm variants, runtime params + defaults, the numerics options and precision policy in effect, the trace (variants, persistent inputs, trace buffers), warm-up and boot times |
+| `GET /v1/models` | `{"object": "list", "data": [{"id": "AutowareFoundation/diffusion_planner", "object": "model", "owned_by": "changh95"}]}` -- a stub so OpenAI-shaped probes do not 404; NOT a chat API |
+| `POST /predict` | one plan -> the model output (below) |
+
+### 3.1 Request (`application/json`; unknown fields are a 422)
+
+| field | type | meaning |
+|---|---|---|
+| `inputs` | object | the planner tensors: `{"format": "npz", "data": <base64 .npz>}` or `{"format": "json", "arrays": {name: nested list}}` with exactly the 15 raw tensors of the node's `create_input_data()`: `sampled_trajectories` [1,321,81,4], `ego_agent_past` [1,31,4], `ego_current_state` [1,10], `neighbor_agents_past` [1,320,31,11], `static_objects` [1,5,10], `lanes` [1,140,20,33], `lanes_speed_limit` [1,140,1], `route_lanes` [1,25,20,33], `route_lanes_speed_limit` [1,25,1], `polygons` [1,10,40,3], `line_strings` [1,60,20,4], `goal_pose` [1,4], `ego_shape` [1,3], `turn_indicators` [1,31], `delay` [1,1]; float32, ego (`base_link`) frame, BEFORE normalization; names, shapes and finite values are checked (400) |
+| `params` | object | per-request knobs (host post-processing only): `velocity_smoothing_window` (8, 1..79), `stopping_threshold` (0.3 m/s), `turn_indicator_keep_offset` (-1.25), `return_denoising_steps` (false) |
+| `output_format` | str | `json` (default) or `npz` (adds the poses as a lossless base64 NPZ array) |
+
+Base64 may be standard or URL-safe, wrapped, with or without a `data:` prefix. `python3
+code/tt_diffusion_planner/server/client.py --inputs <scene.npz> [--param name=value] --out req.json` builds the request
+with the standard library only (no numpy); `--url http://127.0.0.1:20000` sends it.
+
+### 3.2 Response (200)
+
+The served body of the shipped sample (uvicorn on the host with the serve pins; trajectory cut to 3 of 80 rows and
+the predicted-agents array to its header):
+
+```json
+{
+ "model": "diffusion-planner-p150",
+ "frame_id": "base_link",
+ "meta": {"predicted_agent_columns": ["x", "y", "yaw", "cos", "sin"], "predicted_agent_rows": [0, 1, 2, "... 85 more"], "force_stop": false, "time_from_start_s": [0.1, 0.2, 0.3, "... 77 more"], "valid_counts": {"ego": 1, "neighbor": 88, "static": 0, "lane": 123, "route": 17, "polygon": 0, "line_string": 60, "goal": 1, "ego_shape": 1, "turn": 1}},
+ "timing_ms": {"preprocess": 3.8, "device": 105.3, "postprocess": 3.2, "total": 122.8, "decode": 8.5, "model_call": 112.5},
+ "num_poses": 80,
+ "columns": ["x", "y", "yaw", "cos", "sin", "velocity", "acceleration"],
+ "trajectory": [[0.365, 0.01, -0.017, 0.9962, -0.0169, 3.8059, -0.0431], [0.7631, -0.0022, -0.0414, 0.9966, -0.0413, 3.8016, -0.5485], [1.1524, -0.0282, -0.0675, 0.9942, -0.0674, 3.7468, -0.4708], "... 77 more rows"],
+ "turn_indicator": {"command": 1, "command_name": "DISABLE", "keep_selected": true, "held": false, "logits": [-15.960084915161133, -5.125061511993408, -5.230083465576172, -0.7658059597015381, 5.504596710205078], "probabilities": [1.651601411190029e-09, 8.38487030705437e-05, 7.548934809165075e-05, 0.006556871347129345, 0.993184506893158]},
+ "predicted_agents": {"format": "npz", "key": "predicted_agents", "dtype": "float32", "shape": [88, 80, 5], "data": "<base64 npz>"}
+}
+```
+
+- `trajectory`: 80 points at 0.1-8.0 s in `base_link` (the ego frame of the input tensors), post-processed like the
+  node's `~/output/trajectory`: velocity from consecutive 3-D points / 0.1 s, forward moving average over
+  `velocity_smoothing_window` points, force stop (poses frozen once the smoothed speed falls below `stopping_threshold`
+  while the ego moves), acceleration by finite difference. `yaw` is what `tf2::getYaw` reads from the node's
+  (unnormalised) quaternion of the raw network `cos` / `sin`, which are returned as they are.
+- `turn_indicator`: `command` 0 NO_COMMAND, 1 DISABLE, 2 ENABLE_LEFT, 3 ENABLE_RIGHT (when the head selects KEEP, the
+  command repeats the last input report `turn_indicators[0, 30]`); the 5 raw `logits` (NONE, DISABLE, LEFT, RIGHT, KEEP)
+  and the decision's `probabilities`. No hold window is applied (see 3.5).
+- `predicted_agents`: one 80-point path (x, y, yaw, cos, sin) per non-empty neighbour row, in input order
+  (`meta.predicted_agent_rows` gives the rows).
+- `meta`: `force_stop`, `time_from_start_s`, `valid_counts` (entities the encoder saw), and with
+  `return_denoising_steps` the ego row of the 11 solver iterates (`denoising_steps`, `[11, 81, 4]`, the node's
+  `~/debug/denoising_steps`).
+
+`timing_ms`: `decode` (base64 + npz parsing + the schema check), `preprocess` (the node's normalization and the encoder's
+host features), `device` (host tensors + H2D + one trace replay + D2H), `postprocess`, `model_call`, `total` (server
+side, after the body arrived).
+
+### 3.3 Errors
+
+**400** undecodable or malformed input (bad base64, a missing or unknown tensor, a wrong shape, a non-finite value,
+unknown or out-of-range `params`), **422** schema violation (unknown field, wrong type), **503** while starting (or
+when the boot failed), **500** `inference failed: <ExceptionType>: <message>` if the device call raises.
+
+### 3.4 Environment the app reads (lifespan only, never at import)
+
+| var | set by | meaning / default |
+|---|---|---|
+| `HF_MODEL` | launcher (`weights.repo`) | weights repo id; default `AutowareFoundation/diffusion_planner` |
+| `TT_MODEL_WEIGHTS_REVISION` | launcher (`weights.revision`) | pinned commit; `TT_WEIGHTS_REVISION` (`serve.env`) is the same for older tt-model |
+| `DIFFUSION_PLANNER_WEIGHTS_DIR` | you (offline) | local weights directory; overrides the Hub |
+| `TT_MESH_SHAPE` | launcher (`runtime.mesh_shape_env`) | `1x1`; anything else -> RuntimeError at startup |
+| `TT_DEVICE_ID` | you | chip to open, default 0 |
+| `DIFFUSION_PLANNER_DISPATCH` | `serve.env` | `eth` (default) \| `worker` (A/B only, 11×10) \| `auto` (ETH if the patch is present) |
+| `DIFFUSION_PLANNER_NUM_CQS` | `serve.env` | `1` (2 CQs replay ~10 % slower on ETH, OPT_BASELINE.md) |
+| `DIFFUSION_PLANNER_VARIANT` | `serve.env` | `default` (the only v5.0 graph) |
+| `DIFFUSION_PLANNER_LN_FP32`, `_SPLIT_MATMUL`, `_ATTN_MATMUL`, `_HIDDEN_FP32`, `_ATTN_FP32_ACC` | `serve.env` | the numerics knobs, pinned at their gated defaults (`enc.mixer.*,dec.*`; `enc.island.*,enc.pre.*,dec.*`; `enc.fusion.attn,dec.*`; empty; empty: `tt/config.py` `KNOBS`); changing one changes the numerics and needs the gates re-run |
+| `DIFFUSION_PLANNER_PRECISION` | `serve.env` | empty: the precision policy `DEFAULT_PRECISION` of `tt/config.py` (HiFi4 + fp32 accumulation everywhere); extra rules such as `dec.*=HiFi2+fp32` are for experiments |
+| `DIFFUSION_PLANNER_WARMUP` | you | JSON list of warm-up variants, `default` or `none` |
+| `DIFFUSION_PLANNER_TRACE_REGION`, `DIFFUSION_PLANNER_L1_SMALL`, `DIFFUSION_PLANNER_WORKER_L1_SIZE` | you | device-open overrides (validated values: `DEVICE_DEFAULTS` in `device.py`) |
+| `DIFFUSION_PLANNER_MAX_BODY_MB` | you | request size guard, default 256 (the shipped sample's request is 0.15 MB of base64 npz) |
+| `TT_METAL_VISIBLE_DEVICES`, `MESH_DEVICE`, `HF_HUB_DISABLE_IMPLICIT_TOKEN` | `serve.env` / launcher | `0`, `P150`, `1` (the weights are public: no token is ever sent) |
+
+Server-side pipeline: JSON -> `tt_diffusion_planner.io` decoders (schema check) -> `DiffusionPlanner.__call__` (the node's
+host pre-processing ported from `planning/autoware_diffusion_planner` -> H2D into 19 persistent device inputs ->
+`execute_trace` of the whole plan -> one D2H -> the node's host post-processing) under one lock -> `Output.to_dict()`.
+
+### 3.5 What the client keeps (the API is stateless)
+
+Every request is one independent plan. The node keeps state between plans; a client that wants its behaviour over a
+sequence of plans keeps the same state and puts it into the request or applies it to the response:
+
+- **The input tensors.** Converting ROS messages and the Lanelet2 map into the 15 tensors is the client's: the per-UUID
+  agent buffers with their 0.1 s resampling, the ego history, lane / route / polygon / line-string selection and
+  encoding, traffic-light states, speed limits, the goal and the turn-indicator report history.
+- **The turn-indicator hold window.** The node holds its last non-KEEP command for `turn_indicator_hold_duration`
+  (1.0 s in its YAML). The server evaluates every request with a fresh manager (no held command). To reproduce the node,
+  keep the last non-KEEP command and its time, and return it instead while less than 1.0 s has passed; the node's
+  manager ships in the package (`tt_diffusion_planner.host.postprocess.TurnIndicatorManager`, fed with
+  `turn_indicator.logits`, the plan time and the last report).
+- **The initial solver state `x_T` (`sampled_trajectories`, normalised space).** Zeros is the node's default
+  (`temperature: [0.0]`). With a temperature > 0 the node draws N(0, 1) x temperature for every element (a fresh
+  `std::random_device` seed per call); send that noise in `sampled_trajectories`. With the RTC prefix (`delay_step` > 0,
+  at most 40) the node also writes its previous plan into the ego row, slots t = 0 .. delay_step: the previous poses
+  re-expressed in the current ego frame, `x` as (x - 10) / 20, `y` as y / 20, `cos` / `sin` as they are. Non-zero
+  `x_T` was checked on the device against ONNX Runtime (noise of scale 0.5 and 1.0, an RTC prefix: within the gates,
+  `VERIFICATION_2026-10-08.md`).
+- **`delay`** is accepted and ignored, as in the node's multi-step mode.
+- **The map frame.** The output is in `base_link` (the ego frame of the inputs); the node transforms it to `map` with the
+  current ego pose before publishing.
+
+## 4. Caveats
+
+- Batch 1, one plan per request; concurrent clients queue on the lock.
+- Fixed shapes of the v5.0 export (320 neighbours, 140 lanes, 25 route lanes, 10 polygons, 60 line strings, 31 history
+  and 80 future steps) and 10 DPM-Solver steps (11 decoder evaluations) are compiled into the trace; every plan computes
+  the full capacities whatever the scene holds, so the device time does not depend on the scene.
+- The node's guidance services (start / stop / centerline guidance) are off (the node's default too); a guided mode
+  would need the host in the solver loop.
+- Warm-up captures the trace inside the lifespan, so READY means warm; the first cold boot pays the ttnn JIT.
+- Weights are pinned by sha in `weights.revision`, exported by the launcher and repeated in `serve.env`;
+  `snapshot_download(..., revision=<sha>)` is a cache hit after `serve`'s pre-download and falls back to
+  `local_files_only=True` if the Hub is unreachable. The sha256 of the four files and `major_version == 5` are checked
+  at load.
+- The runtime image has no host C/C++ compiler: device kernels JIT-compile (sfpi ships in the image); the host code is
+  numpy.
+- `tt-model curl` and the ready card's `/v1/models` hint are OpenAI-shaped and are not this API; use the routes above.

VERIFICATION_2026-10-08.md

@@ -0,0 +1,210 @@
+# diffusion-planner-p150: independent verification, 2026-10-08
+
+## Verdict
+
+**PASS.** This is the light verification pass of the first publish (`research/PLAN.md` §6.3): the frozen gates re-run,
+the baseline numbers re-checked, and every device-open path audited for ETH dispatch. It was made by the agent that
+wrote the release docs, which is neither the porter nor the baseline agent, on commit `c0d84f9` (the `code/` of this
+repo: ttaw 0.20.0 vendored, the numerics knobs pinned in `serve.env`). Against the baseline commit `5541833`:
+
+- **Accuracy:** the device suite passes (44 passed; again under alloc tracking), every gate value and all 99 per-scene end-to-end numbers identical to the baseline run and to the port's final run: worst ego 0.313 / 0.143 m (max / mean; gates 1.0 / 0.3 m), turn command 99 / 99, neighbours ≤ 0.086 m (gate 1.5 m).
+- **Independent oracle:** against the research pipeline's ONNX Runtime goldens, which the bundle's reference did not produce, all 92 / 92 nuScenes instants and 33 / 33 instants of the scene-0061 sequence pass the same gates (worst ego max 0.313 m).
+- **Speed:** the stage bench reproduces `OPT_BASELINE.md`: back-to-back replay 102.03 vs 102.04 ms, one plan 102.10 vs 102.13 ms; the host-bound end to end 115.6 vs 117.9 ms p50.
+- **Audit:** ETH dispatch, 1 CQ and the 12×10 grid on every device-open path; no fallback in any run.
+- **No numerics change** since the port: the diff `5541833..c0d84f9` is the ttaw re-vendor (0.17.1 -> 0.19.0 -> 0.20.0: on this
+  bundle's path only `trace.py`'s `pack_outputs`, whose single-row layout for the planner's 117,664-element readback is
+  unchanged), the `serve.env` pins of the numerics knobs (equal to the code defaults), two host-test changes, the
+  quickstart picture and documentation. No gate threshold moved.
+
+The full adversarial verification of the port is `VERIFY_PORT.md` of the porting workspace (round 1, 2026-10-08, PASS
+with 9 low findings; not part of this repository): it re-ran every suite from a clean shell, audited the request path,
+the gates, the oracle chain and the Autoware fidelity line by line, compared the device with ONNX Runtime goldens that
+the bundle's own reference did not produce, and ran five adversarial scenes. Its results that this card relies on are
+quoted below, and its findings are resolved as listed in "Review findings".
+
+## Setup
+
+| item | value |
+|---|---|
+| Hardware | one Blackhole p150b, ETH dispatch, 1 CQ, 12×10 compute grid (120 cores), as printed by every run (`dispatch eth`, `fallback null`, `eth_patch true`) |
+| tt-metal | `44d66500520` with `patches/tt-metal-eth-dispatch.patch` (sha256 `08d0ddf6…45cc`; the tree's `git diff` against `44d6650` is byte-identical to the patch: 4 files) |
+| Weights | `AutowareFoundation/diffusion_planner` @ `423efde67f5414734da43a7ad856c17ceb8b51aa` (tag `v5.0`): the Python API, the quickstart and the server read them from the HF cache at the pinned revision (downloaded without a token, sha256 equal to the workspace copy, checked again at every load); the device tests from the workspace copy |
+| Verified commit | `c0d84f9` (ttaw 0.20.0, `common` `89dec49`, vendored from the committed tree; `vendor.py --check`: 0 differences) |
+| Baseline commit | `5541833` (`OPT_BASELINE.md`) |
+| Workload | `code/tt_diffusion_planner/samples/kashiwanoha_dense.npz` (+ `straight_road.npz` and nuScenes scene-0103_kf14 for the stage bench), batch 1, warm; 99 scenes for the accuracy gates and 125 nuScenes instants for the oracle check (local only) |
+| Bench method | `code/scripts/bench.py --iters 100 --warmup 5 --b2b-iters 50 --b2b-rounds 3`, one run, the three scenes of the baseline |
+| Served method | uvicorn on the host with every `serve.env` pin of `tt-model.yaml` (the container's app and environment), 5 warm-up + 50 requests of the shipped sample from a loopback client |
+| Accuracy reference | the fp32 CPU reference (`code/tt_diffusion_planner/reference/`), itself equal to ONNX Runtime on the shipped ONNX (48 tests, PORT_LOG 5.1); independently, the research pipeline's ONNX Runtime goldens |
+| Host | AMD EPYC VM, 8 vCPUs, shared with other agents' jobs (load average 5.42, 7.45 during the runs); host-side stages move with it |
+| Logs | `logs/diffusion-planner/docs/` of the workspace (job scripts in `scripts/`) |
+
+## Measured baseline vs re-check
+
+| measurement (shipped sample `kashiwanoha_dense` unless noted) | baseline `5541833` (`OPT_BASELINE.md`) | re-check `c0d84f9` | change |
+|---|---:|---:|---:|
+| back-to-back trace replays, per plan (p50) | 102.04 ms | 102.03 ms | -0.01 ms |
+| device trace, one blocking plan (p50) | 102.13 ms | 102.10 ms | -0.04 ms |
+| device trace, one blocking plan (min) | 102.05 ms | 102.03 ms | -0.02 ms |
+| e2e `model(inputs=arrays)` p50 | 117.90 ms | 115.61 ms | -1.9 % |
+| e2e `model(inputs=arrays)` p99 | 134.56 ms | 121.79 ms | -9.5 % |
+| e2e `model(inputs=<.npz path>)` p50 | 124.76 ms | 118.77 ms | -4.8 % |
+| host pre-processing | 4.75 ms | 3.91 ms | -17.8 % |
+| pack (19 persistent inputs) | 0.45 ms | 0.40 ms | -11.8 % |
+| host tensors (TILE) | 2.41 ms | 2.05 ms | -14.9 % |
+| H2D | 1.14 ms | 0.94 ms | -17.1 % |
+| D2H (one packed read) | 0.58 ms | 0.37 ms | -36.3 % |
+| host post-processing | 4.32 ms | 3.60 ms | -16.7 % |
+| back-to-back replays, `straight_road` | 102.04 ms | 102.04 ms | -0.00 ms |
+| back-to-back replays, nuScenes scene-0103_kf14 | 102.04 ms | 102.04 ms | -0.00 ms |
+| first call after `from_pretrained` | 118.20 ms | 114.79 ms | -2.9 % |
+| `from_pretrained` load (warm JIT cache) | 11.64 s | 10.38 s | -10.8 % |
+
+AICLK during the re-check: median 1350 MHz (min 1343, max 1350; 760 sysfs samples, sampled during the timed loops); the device rows reproduce the baseline to the 0.05 ms the baseline quotes, the host rows move with the load of the shared host.
+
+Not in the baseline, measured for the card on `c0d84f9`:
+
+| measurement | value |
+|---|---:|
+| `from_pretrained` load with an EMPTY JIT cache (firmware + every kernel compiled); first / second call | 314.6 s; 121 / 119 ms |
+| `from_pretrained` load with that cache warm (new process); first / second call | 8.6 s; 120 / 120 ms |
+| served `/predict` `timing_ms`, median of 50: decode · preprocess · device · postprocess · total | 8.6 · 3.8 · 105.3 · 3.3 · **123.1 ms** (min total 122.5) |
+| served client round trip, loopback (median / min; request 0.15 MB) | 127.5 / 127.0 ms |
+| server boot to ready (uvicorn, warm JIT cache) | 10.0 s |
+| the bundle's `server/smoke_test.py` against it (the container smoke's check) | `PASS diffusion-planner-p150: profile=- variant=default dispatch=eth grid=12x10 cqs=1 n=80 turn=DISABLE reference=kashiwanoha_dense.reference.json (trajectory ade=0.0109 fde=0.0173; predicted_agents max_abs=6.283) device_ms=109.402 total_ms=133.384 rtt_ms=139.0` |
+| served body vs the stored CPU reference (the smoke gates) | PASS ({"trajectory": {"n": 80, "ade": 0.01089988605897666, "fde": 0.017330320250936008}, "predicted_agents": {"max_abs_err": 6.282742738723755, "n": 35200}}); `predicted_agents` is reported, not gated: its largest difference is the yaw column at ±π (-3.1413 vs +3.1415 rad, the same heading) |
+| the README's request recipe (`client.py --out req.json` + `curl`) | HTTP body with 80 poses, turn DISABLE; same trajectory as the client: True, same predicted agents: True |
+| `examples/quickstart.py` as a user runs it (weights from the HF cache, offline, no token) | rc 0; turn DISABLE; `quickstart.json` and `quickstart_bev.png` written |
+
+## Accuracy gate results
+
+`test_pcc_device.py` + `test_e2e_device.py` on `c0d84f9`, one devrun job, `TTAW_GATES_READONLY=1`: 44 passed in 42.29s.
+Every value equals the baseline run (`OPT_BASELINE.md`, ttaw 0.17.1) and the port's final run (PORT_LOG job 19, ttaw
+0.11.0) to the printed precision, and all 99 per-scene end-to-end numbers are identical to both
+(`logs/diffusion-planner/docs/compare_runs.json`).
+
+| gate (PLAN §2.12; `tests/*.gates.json`) | threshold | value |
+|---|---:|---:|
+| `enc.ego` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 0.999972 |
+| `enc.neighbor` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 0.999952 |
+| `enc.lane` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 0.999992 |
+| `enc.route` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 0.999998 |
+| `enc.polygon` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 0.999994 |
+| `enc.line_string` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 0.999998 |
+| `enc.goal` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 0.999991 |
+| `enc.ego_shape` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 1 |
+| `enc.turn` PCC vs the fp32 reference (valid rows, 2 samples) | ≥ 0.999 | 0.999995 |
+| `enc.encoding` PCC (valid tokens) | ≥ 0.999 | 0.999978 |
+| `dec.eval` PCC (teacher-forced decoder, min over 11 evaluations x 2 samples) | ≥ 0.999 | 1 (≥ 0.9999995) |
+| `ego.max_err_m`, max over 99 scenes | ≤ 1.0 m | 0.313 m (nuscenes/scene-0103_kf14) |
+| `ego.mean_err_m`, max over scenes | ≤ 0.3 m | 0.143 m (nuscenes/scene-0103_kf14) |
+| `turn.command_agreement` | = 1.0 | 1.000 (99 / 99) |
+| `neighbors.median_max_err_m`, max over scenes | ≤ 1.5 m | 0.086 m (kashiwanoha_dense) |
+| diagnostics, .kashiwanoha_dense: `final_x0` valid-agent PCC; turn logits max abs | reported | 0.999994; 0.0398 |
+| diagnostics, straight_road: `final_x0` valid-agent PCC; turn logits max abs | reported | 1.000000; 0.0372 |
+| replay == eager (bit for bit); prefix constraint exact; API == `/predict` | equal | equal |
+
+Distribution over the 99 scenes: ego mean displacement median 1.3 cm, 95th percentile 6.2 cm. Under `TT_METAL_TRACE_ALLOC_TRACKING=1` (no program compiled after the first capture): 44 passed in 40.50s.
+
+Also re-run, CPU only: the host suite on the fake ttnn, 107 passed and 45 skipped (the 44 device tests and the ONNX
+Runtime module, which runs in the research venv), after the re-vendor and the test changes of `d521981` (0.20.0 re-vendored in `c0d84f9`).
+
+### Against an independent oracle
+
+The p150 outputs of the 92 nuScenes v1.0-mini planning instants and of the 33-plan scene-0061 sequence (2 Hz), produced
+through the public API (`model(inputs=...)`), compared with the research pipeline's ONNX Runtime goldens
+(`research/diffusion-planner/public_data/goldens/`: ORT 1.30 on the shipped ONNX files with an independent host
+normalization and solver port), with the PLAN §2.12 gates on the raw denormalised x0
+(`research/diffusion-planner/public_data/scripts/dp_public_metrics.py gates`):
+
+| set | instants | all four gates pass | worst ego max | worst ego mean | worst neighbour median-max | turn command identical | logits max abs |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| nuScenes v1.0-mini planning instants (1 Hz, all 10 scenes) | 92 | 92 / 92 | 0.313 m (scene-0103_kf14) | 0.143 m (scene-0103_kf14) | 0.082 m | 92 / 92 | 0.095 |
+| scene-0061 sequence (2 Hz, the demo GIF) | 33 | 33 / 33 | 0.118 m (scene-0061_kf36) | 0.049 m (scene-0061_kf09) | 0.027 m | 33 / 33 | 0.074 |
+
+`VERIFY_PORT.md` (round 1) also ran five adversarial scenes on the device against ONNX Runtime, which the stored goldens
+do not cover (every golden has `x_T = 0` and at most 88 agents): full capacity (320 neighbours, 140 lanes, 25 route
+lanes, 10 polygons): ego 0.042 / 0.025 m (max / mean); ego only (every neighbour removed): 0.062 / 0.031 m; `x_T` = 0.5
+N(0, 1): 0.022 / 0.007 m; `x_T` = 1.0 N(0, 1): 0.067 / 0.031 m; an RTC prefix in the ego row of `x_T`: 0.024 / 0.012
+m; turn command equal and outputs finite on all five.
+
+### Open-loop sanity metrics (not a planning metric)
+
+The p150 plans of the 92 nuScenes instants against the logged drive, with the research metric script
+(`dp_public_metrics.py eval`), next to the CPU reference's numbers (`public_data/metrics/open_loop_cpu_fp32.json`). The
+model never saw nuScenes and the inputs have known gaps (no traffic-light states, no speed limits), so this is a sanity
+check against one human driver, not a paper metric:
+
+| group (instants) | ADE@3s p150 / CPU | FDE@3s | ADE@8s | FDE@8s | constant velocity ADE@8s / FDE@8s | plan / logged length (m), p150 / CPU |
+|---|---:|---:|---:|---:|---:|---:|
+| all (92) | 1.12 / 1.12 | 2.60 / 2.59 | 4.75 / 4.74 | 11.87 / 11.87 | 4.99 / 13.06 | 37.5 / 37.5 vs 44.2 |
+| moving (v0 >= 1 m/s) (69) | 1.42 / 1.41 | 3.27 / 3.26 | 5.88 / 5.88 | 14.50 / 14.51 | 6.56 / 17.21 | 48.5 / 48.5 vs 58.8 |
+| mini_val (18) | 1.44 / 1.44 | 3.42 / 3.42 | 6.42 / 6.43 | 15.86 / 15.89 | 9.47 / 24.11 | 35.6 / 35.6 vs 38.0 |
+| mini_train (74) | 1.04 / 1.04 | 2.40 / 2.39 | 4.34 / 4.33 | 10.90 / 10.89 | 3.90 / 10.37 | 38.0 / 38.0 vs 45.7 |
+
+Turn-indicator command equal to the logged (debounced) blinker: p150 88 / 92, CPU 88 / 92. Moving plans (v0 ≥ 1 m/s) are 17 % shorter than the logged drive.
+
+## Disclosed numerics changes
+
+- None since the port. The configuration is decision 11 of `PORT_LOG.md`: fp32 residual streams and solver state;
+  HiFi4 + fp32 accumulation for every matmul; the ego / neighbour pre-projection as a pad-relative fp32 island; split
+  hi / lo matmuls (`DIFFUSION_PLANNER_SPLIT_MATMUL=enc.island.*,enc.pre.*,dec.*`); the fp32 LayerNorm decomposition
+  (`_LN_FP32=enc.mixer.*,dec.*`); fp32 matmul attention (`_ATTN_MATMUL=enc.fusion.attn,dec.*`); the turn head in fp32;
+  the other weights and the mixer / fusion hidden activations in bf16. This is the precision policy of PLAN.md §9.3
+  (HiFi4, fp32 accumulation, two-term or fp32 weights where the gates need them).
+- What the configuration costs (timing only, `OPT_BASELINE.md`): 33.4 ms per plan over the first device round's
+  defaults, which fail `ego.mean_err_m` (0.347 m on nuScenes scene-0103_kf14, PORT_LOG job 11); 58.3 ms over the
+  fastest graph, which fails `enc.ego`. The card names this cost as the first optimization target.
+- The knobs are now pinned in `serve.env` at these values, and a host test (`test_serve_env_pins_the_numerics`) checks
+  the pins against `KNOBS.serve_env()`; the served `/info` reported the same options (null).
+
+## Review findings
+
+- **No gate loosened.** `tests/test_pcc_device.gates.json` and `tests/test_e2e_device.gates.json` are unchanged since
+  `3223604` (the port's job 18 freeze); the thresholds equal PLAN §2.12; `GateRegistry` refuses a looser declaration and
+  the runs used `TTAW_GATES_READONLY=1`.
+- **No cached or replayed outputs.** The gates compare trace replays with the fp32 CPU reference's goldens, the oracle
+  check with ONNX Runtime goldens written by another pipeline; the only TT-vs-TT check is replay == eager (a trace
+  correctness check, not an accuracy gate).
+- **The diff `5541833..c0d84f9`** touches no file of `tt_diffusion_planner/tt/`, `host/`, `reference/`, `api.py`,
+  `device.py`, `io.py` or `server/`: the ttaw re-vendor, `tt-model.yaml` (`serve.env` pins), `examples/quickstart.py`
+  and two host tests (`test_api_host.py`: the dead `test_build_says_what_is_missing` replaced by
+  `test_build_refuses_unknown_compile_params`; `test_bundle_host.py`: `test_serve_env_pins_the_numerics`). The docs
+  commit on top changes only documentation, media and `tt-model.yaml` comments, card text and one `verify:` line.
+- **No hang, timeout, reset or FAULT marker** in the device jobs of this pass.
+
+Status of the `VERIFY_PORT.md` findings:
+
+| # | finding | status |
+|---|---|---|
+| L1 | vendored ttaw outdated (0.11.0 vs common 0.15.1) | resolved: re-vendored 0.17.1 at the baseline step (`5541833`) then 0.19.0 (`d521981`) and 0.20.0 (`c0d84f9`) in this pass; the device suite after the first and the last gave identical gate values and per-scene numbers |
+| L2 | numerics knobs not pinned in `serve.env`, no host test | resolved (`d521981`): the five knobs and an empty `DIFFUSION_PLANNER_PRECISION` pinned; `test_serve_env_pins_the_numerics` |
+| L3 | publish documents outstanding; template text wrong for a planner | resolved: README, SERVING, PYTHON, OPT_BASELINE, OPT_REPORT, this file, the patch copy and the demo media; the card's risks rewritten; packaging, the container smoke, `build_info.json` and the push remain for the packaging step |
+| L4 | dead test `test_build_says_what_is_missing` | resolved (`d521981`): replaced by a check that `_build` refuses unknown compile parameters |
+| L5 | "6,408 programs" was a fake-ttnn op count | resolved: `OPT_BASELINE.md` quotes 6,282 programs per plan from the device profiler |
+| L6 | op-count evidence only in a session scratchpad | resolved: `logs/diffusion-planner/opcount_fake_r2.log` |
+| L7 | stateless API: hold window and `x_T` handling left to the client | resolved by documentation: README "Quickstart", `code/PYTHON.md` "What the caller keeps" (with the node's `TurnIndicatorManager` applied across calls), `SERVING.md` 3.5 |
+| L8 | the bf16 SDPA path (`DIFFUSION_PLANNER_ATTN_MATMUL=none`) has no gate run since decision 11 | unchanged: it is not a shipped option (`serve.env` pins the matmul attention); PORT_LOG job 13 shows it fails the mean gate on scene-0103_kf14 together with the decoder split (0.74 / 0.33 m), and `OPT_BASELINE.md` times it only |
+| L9 | C20 PCC range quoted as 0.99966-0.99983 | resolved in `PORT_LOG.md` (0.99961-0.99983 over all suite shapes, 0.99972-0.99983 at the planner's shapes); `ttaw/API.md` section 17 (common) keeps the old text until the next functional C20 change, as PORT_LOG section 9 says; the gate (0.9995) is unaffected |
+
+## p150 ETH-dispatch compliance
+
+| path | dispatch / CQs / grid |
+|---|---|
+| Python API `DiffusionPlanner.from_pretrained()` (`ttaw.api_base` → `tt_diffusion_planner.device.open_device`) | **ETH / 1 / 12×10** by default (`DeviceConfig.dispatch = "eth"`, `DEVICE_DEFAULTS["num_command_queues"] = 1`; `DIFFUSION_PLANNER_DISPATCH` / `_NUM_CQS` override). A failing ETH open falls back to WORKER with a `RuntimeWarning`, and `model.info["device"]["fallback"]` names it. Measured in this pass (quickstart, load times, demo runs): `dispatch eth`, `grid 12x10`, `fallback null` |
+| HTTP server (`tt_diffusion_planner.server.app`, `config_from_env`) | ETH unless `DIFFUSION_PLANNER_DISPATCH` says otherwise; `/health` and `/info` report the device actually opened. Measured (served bench): `/info` `dispatch eth`, `grid 12x10`, `num_command_queues 1`, `fallback None` |
+| `tt-model.yaml` serve env (one serve profile, the default) | `DIFFUSION_PLANNER_DISPATCH=eth`, `_NUM_CQS=1`, `_VARIANT=default` and the numerics pins; `check_bundle.py` refuses a profile whose `*_DISPATCH` is not `eth`; host tests check the pins against `device.py` and `tt/config.py` |
+| image `verify:` | asserts the ETH-patch marker `single_chip_arch_1cq_no_dispatch_s` in `/opt/tt-metal/tt_metal/impl/dispatch/topology.cpp` and that ttaw sees the patch (`eth_dispatch_patch_present`) |
+| container smoke (the one serve profile) | `server/smoke_test.py` asserts `/info` = `eth` / `12x10` (constants, not options) and the profile's pins (dispatch, CQs, variant, weights revision), and compares the served plan with the stored CPU reference; run against uvicorn on the host in this pass (`PASS diffusion-planner-p150: profile=- variant=default dispatch=eth grid=12x10 cqs=1 n=80 turn=DISABLE reference=kashiwanoha_dense.reference.json (trajectory ade=0.0109 fde=0.0173; predicted_agents max_abs=6.283) device_ms=109.402 total_ms=133.384 rtt_ms=139.0`); to be run on the built image by the packaging step |
+| gate tests (`code/conftest.py`) | `open_device(..., allow_fallback=False)`: an ETH open that fails is an error, never a silent WORKER run |
+| `code/scripts/bench.py`, `profile_ops.py` | `from_pretrained(dispatch=--dispatch or DIFFUSION_PLANNER_DISPATCH or eth)`; the JSON records the device actually opened (`fallback null` in every run); the WORKER rows of `OPT_BASELINE.md` were explicit A/B runs |
+| `code/scripts/bringup_device.py`, `precision_exp.py`, `split_error.py` | `open_device(allow_fallback=False)` (ETH) |
+| `examples/quickstart.py` | `from_pretrained(device_id=...)`: ETH / 1 / 12×10 (run in this pass) |
+| vendored `ttaw` | 0.20.0 @ `89dec49`, `source_dirty: false`; `common/tools/vendor.py --check`: 0 differences; `check_bundle.py`: no drift warning |
+| hard-coded grids | none: `tt/` sets no core grid or program config; the only grid consumer, C20's SDPA program config, reads `compute_with_storage_grid_size()` and is not on the default path (matmul attention) |
+
+## Not covered by this pass
+
+The container build, its smoke test on the built image, `build_info.json`, the HF pre-flight and the push (the
+packaging step); the Python install through `pip install -e .` (the quickstart ran with `code/` on `PYTHONPATH`, the
+same import path as the device tests); the dispatch / CQ matrix and the device profile (taken once, in
+`OPT_BASELINE.md`, on the same device code).

build_info.json

@@ -0,0 +1,48 @@
+{
+ "schema": "ttaw-build-info/1",
+ "bundle": "diffusion-planner-p150",
+ "recorded_at": "2026-10-09T04:48:03Z",
+ "image": {
+  "tag": "tt-model/diffusion-planner-p150:3b96d8ea7190",
+  "digest": "sha256:3b96d8ea71902fe6a00f1792dd41290839b7758070431464cd613cde3f6bf909",
+  "built_at": "2026-10-09T04:37:19+00:00",
+  "code_sha256": "c0e7abb7888098a9319ab5c66a10c4fd4009fc1542326b26507554c04f05a481",
+  "size_bytes": 4069025450,
+  "layers": 23
+ },
+ "base_images": {
+  "build": {
+   "stage": "prep",
+   "ref": "ghcr.io/tenstorrent/tt-metal/tt-metalium/ubuntu-22.04-dev-amd64:latest",
+   "digest": "sha256:df9d279c7f85c17c6fad982d196802682d669cca1b7ced9cbaad8181339cd5fc",
+   "source": "docker build log",
+   "local_tag_matches": false,
+   "local_id": "sha256:3fd1e6013e658c65df1bc6b084543e7174d854c15af97373e493df0c1787c393",
+   "created": "2026-10-07T01:17:29.186036377Z",
+   "note": "the local tag moved after this build; the digest above is the one the image was built from"
+  },
+  "runtime": {
+   "stage": "runtime",
+   "ref": "docker.io/library/ubuntu:22.04",
+   "digest": "sha256:5ec03bb3441e8b0bf3b4f9cd4629a1ae763010dc3035bb8da3ae6cf026486401",
+   "source": "docker build log",
+   "local_tag_matches": null,
+   "note": "not in the local image store (BuildKit pulled it into its cache)"
+  }
+ },
+ "tt_metal": {
+  "sha": "44d66500520fda9f2c7060c0f6b41ec48f7ab37e",
+  "describe": "v0.80.0-dev20261006-78-g44d6650052-dirty",
+  "dirty": true,
+  "scm_version": "0.65.2.dev11169+g44d66500520",
+  "mode": "local",
+  "remote": "https://github.com/tenstorrent/tt-metal.git",
+  "branch": "main",
+  "pushed": true
+ },
+ "tools": {
+  "tt_model": "0.1.0",
+  "docker": "29.8.2"
+ },
+ "notes": "tt-model's FROM tags float (build: tt-metalium dev image :latest, runtime: ubuntu:<version>); these are the digests this image was built from. A moved build base costs a cold C++ build."
+}

code/PYTHON.md

@@ -0,0 +1,179 @@
+# Python API: Diffusion Planner v5.0 (Autoware diffusion_planner) on Blackhole
+
+Use this API from Python code (a pipeline, a notebook, a ROS 2 node wrapper). You do not need the HTTP server: the
+API and the server share the decoders, the device trace and the post-processing, so the outputs and the speed are
+the same.
+
+## Install
+
+Install the package on top of an environment that already has `ttnn` (a tt-metal `python_env` at `44d66500520`
+with `patches/tt-metal-eth-dispatch.patch`, or the tt-model container). From the root of the model repository (the
+directory that holds `pyproject.toml`, `README.md` and `code/`):
+
+```bash
+pip install -e .                        # the Python API (numpy<2, pillow, pyyaml, onnx, huggingface_hub)
+pip install -e ".[server,test]"         # + the HTTP server and the tests
+```
+
+The pip project is the repository's top-level `pyproject.toml`; it installs the package from
+`code/tt_diffusion_planner` (there is no `pyproject.toml` inside `code/`, because the container build copies `code/`
+over the tt-metal tree). ttnn and torch come from tt-metal and are not declared.
+
+The package carries `tt_diffusion_planner.ttaw`, the shared code of the Autoware ports to Blackhole (device open, trace
+runner, decoders, model base class, HTTP app), vendored at the version recorded in
+`code/tt_diffusion_planner/ttaw/VENDORED.json`.
+
+| You want to run | Extras |
+|---|---|
+| the Python API | none |
+| the HTTP server (`tt_diffusion_planner.server.app`, see `SERVING.md`) | `server` |
+| host tests (no device; device tests are skipped): `TT_VISIBLE_DEVICES=none python -m pytest -q code/tt_diffusion_planner/tests` | `server,test` |
+| device tests: `python -m pytest -q -s code/tt_diffusion_planner/tests/test_pcc_device.py code/tt_diffusion_planner/tests/test_e2e_device.py` | `test` |
+
+## Quickstart
+
+```python
+from tt_diffusion_planner import DiffusionPlanner
+
+with DiffusionPlanner.from_pretrained(device_id=0) as model:
+    out = model(inputs="code/tt_diffusion_planner/samples/kashiwanoha_dense.npz")
+print(out.to_dict())   # the POST /predict body
+```
+
+`examples/quickstart.py` runs the same snippet, writes `quickstart.json` and a bird's-eye view of the input and the
+plan (`quickstart_bev.png`).
+
+## `DiffusionPlanner.from_pretrained(...)`
+
+```python
+DiffusionPlanner.from_pretrained(
+    model_id=None,          # HF repo or a local directory with the weights files; default AutowareFoundation/diffusion_planner
+    *,
+    revision=None,          # default for the default repo: the validated commit 423efde67f5 (tag v5.0)
+    variant=None,           # "default" (the only v5.0 graph); default $DIFFUSION_PLANNER_VARIANT or "default"
+    device_id=None,         # chip to open; default $TT_DEVICE_ID or 0
+    device=None,            # an already-opened ttnn device (tt_diffusion_planner.device.open_device); close() does not close it
+    dispatch=None,          # "eth" (p150 target, 12x10 grid) | "worker" (A/B only, 11x10) | "auto"; default $DIFFUSION_PLANNER_DISPATCH or "eth"
+    num_command_queues=None,  # default $DIFFUSION_PLANNER_NUM_CQS or 1
+    weights_dir=None,       # explicit local weights directory; no Hub access
+    warmup_variants="default",  # trace variants to capture now; see "Warm-up"
+    verbose=False,
+    precision=None,         # the only compile parameter: extra precision-policy rules, e.g. "dec.*=HiFi2+fp32" (experiments only)
+) -> DiffusionPlanner
+```
+
+What it does: resolves the weights first, so a Hub problem never claims the chip (`weights_dir` >
+`$DIFFUSION_PLANNER_WEIGHTS_DIR` > a local `model_id` directory > the HF snapshot at the pinned revision, restricted to
+the three v5.0 ONNX files and `diffusion_planner.param.json`, with an offline fallback to the cache; the sha256 of every
+file and the weights' `major_version == 5` are checked), opens the chip (ETH dispatch, 12×10, 1 CQ; the other open
+parameters are `DEVICE_DEFAULTS` in `tt_diffusion_planner/device.py`, overridable with `DIFFUSION_PLANNER_*`), reads the
+ONNX initializers as data, uploads the weights and constants (48.1 MB), builds the graph, then compiles and captures
+the metal trace. If ETH dispatch cannot open (tt-metal without the patch), it warns and falls back to WORKER dispatch
+(`model.info["device"]["fallback"]` names it). Any other keyword argument is a `TypeError`.
+
+The numerics are not arguments: the published configuration is the default of the `DIFFUSION_PLANNER_LN_FP32`,
+`_SPLIT_MATMUL`, `_ATTN_MATMUL`, `_HIDDEN_FP32` and `_ATTN_FP32_ACC` knobs (`tt_diffusion_planner.tt.config.KNOBS`,
+pinned in `tt-model.yaml` `serve.env`). Setting one of them in the environment changes the graph and invalidates the
+accuracy figures of the card until the gates are re-run.
+
+## Warm-up
+
+`from_pretrained` returns a warm model: it builds the graph, runs the plan once eagerly (this first run compiles every kernel into the JIT cache), then captures the whole plan as one metal trace (`warmup_variants="default"`: the variant `plan`) with program-cache misses forbidden, so no later call compiles anything. `model.warmup()` is idempotent; `warmup_variants="none"` defers the capture to `model.warmup()`.
+
+Measured on the shipped sample (`model.info["warmup_ms"]`, 2026-10-09): the load takes 315 s with an empty JIT cache and 8.6 s with a warm one (build 0.53 s: the ONNX initializers read and 48.1 MB of weights and constants uploaded; warm-up and capture 3.7 s; the rest is the device open). The first call then takes 120 ms and the second 120 ms (the stage bench's steady state: 118 ms p50 for decoded arrays, 125 ms for an `.npz` path). The trace holds 74.6 MB of DRAM (`trace_region_size` 192 MiB).
+
+## Call: `model(...)`
+
+| Argument | Type | Description |
+|---|---|---|
+| `inputs` | mapping / `.npz` path / bytes / JSON envelope | the 15 raw planner tensors (see "Input types") |
+| `velocity_smoothing_window` | int, 1..79, default 8 | forward moving average of the trajectory velocity, in points |
+| `stopping_threshold` | float >= 0, default 0.3 | force stop below this smoothed speed (m/s), when the ego moves |
+| `turn_indicator_keep_offset` | float, default -1.25 | added to the KEEP logit before the turn-indicator decision |
+| `return_denoising_steps` | bool, default False | add the ego row of the 11 solver iterates (`out.meta["denoising_steps"]`, `[11, 81, 4]`, the node's `~/debug/denoising_steps`) |
+
+### Input types
+
+- `inputs=`: the 15 raw tensors of the Autoware node's `DiffusionPlannerCore::create_input_data()` (batch 1,
+  float32, ego `base_link` frame, BEFORE normalization; names and shapes in `tt_diffusion_planner.INPUT_SCHEMA`):
+  a `{name: array}` mapping (numpy or torch), an `.npz` path or its bytes, or the `/predict` envelope
+  `{"format": "npz", "data": <base64>}` / `{"format": "json", "arrays": {...}}`. Names, shapes and finite values are
+  checked (`InputError`). `tt_diffusion_planner.load_inputs(source)` is the same decoder.
+- Any other input (`points`, `images`, `calibration`, ...) is refused (`InputError`).
+
+### What the caller keeps (the API is stateless)
+
+One call is one independent plan. The Autoware node keeps state between plans; to reproduce it over a sequence of
+plans, the caller keeps the same state (SERVING.md 3.5 has the details):
+
+- **The tensors.** The node's pre-processing from ROS messages and the Lanelet2 map (per-UUID agent buffers and their
+  0.1 s resampling, the ego history, lane / route / polygon / line-string selection and encoding, traffic lights,
+  speed limits, goal, turn-indicator report history) is not part of the bundle.
+- **The turn-indicator hold window** (`turn_indicator_hold_duration`, 1.0 s in the node's YAML). Each call decides
+  with a fresh manager; apply the node's hold across calls with the node's own manager:
+
+  ```python
+  from tt_diffusion_planner.host.postprocess import TurnIndicatorManager
+
+  manager = TurnIndicatorManager()                     # hold 1.0 s, KEEP offset -1.25 (the node's YAML)
+  out = model(inputs=tensors)
+  decision = manager.evaluate(out.turn_indicator["logits"], stamp_s=now_s, prev_report=int(tensors["turn_indicators"][0, 30]))
+  command = decision.command                           # the held command while less than 1.0 s has passed
+  ```
+
+- **The initial solver state** `sampled_trajectories` (`x_T`, normalised space): zeros is the node's default
+  (`temperature: [0.0]`); for a temperature > 0 send N(0, 1) x temperature; for the RTC prefix (`delay_step` > 0) put
+  the previous plan into the ego row, slots t = 0 .. delay_step (x as (x - 10) / 20, y as y / 20, cos / sin as they are,
+  in the current ego frame). `delay` is accepted and ignored (the node's multi-step mode never reads it).
+- **The map frame.** Outputs are in `base_link`; the node transforms them with the current ego pose to `map`.
+
+## Output
+
+`model(...)` returns a `tt_diffusion_planner.Output` (= `ttaw.outputs.Trajectory`); `out.to_dict()` is exactly the `POST /predict` body (SERVING.md section 3.2).
+
+| field | type | meaning |
+|---|---|---|
+| `poses` | float32 `[80, 7]` | the ego trajectory at 0.1-8.0 s in `base_link`: x, y, yaw, cos, sin, velocity, acceleration (`out.columns`), post-processed like the node's `~/output/trajectory` |
+| `turn_indicator` | dict | `command` (0 NO_COMMAND, 1 DISABLE, 2 ENABLE_LEFT, 3 ENABLE_RIGHT), `command_name`, `keep_selected`, `held` (always false: no hold window), the 5 raw `logits` (NONE, DISABLE, LEFT, RIGHT, KEEP), the decision's `probabilities` |
+| `predicted_agents` | float32 `[N, 80, 5]` | x, y, yaw, cos, sin of each non-empty neighbour row, in input order |
+| `meta` | dict | `predicted_agent_rows` (the rows of `predicted_agents`), `predicted_agent_columns`, `force_stop`, `time_from_start_s`, `valid_counts` (the entities the encoder saw), and with `return_denoising_steps` the encoded `denoising_steps` |
+| `timing_ms` | dict | `preprocess`, `device` (host tensors + H2D + replay + D2H), `postprocess`, `total` |
+
+`out.to_dicts()` gives one `{x, y, yaw, cos, sin, velocity, acceleration}` dict per trajectory point; `out.to_dict("npz")` adds the poses as a lossless base64 NPZ array.
+
+## Lifetime and information
+
+- `model.close()` releases the trace and the persistent device tensors and closes the chip if the model opened it;
+  idempotent. `with` calls it for you; an unclosed model is closed when Python exits.
+- `model.info`: weights (repo, tag, revision, path), device (dispatch, grid, CQs, fallback), variant, warm variants,
+  warm-up times, runtime parameter defaults, the input schema, the numerics options and precision policy in effect, the
+  trace (variants, persistent inputs, trace buffers in MB).
+- Calls from several threads are safe: the device calls are serialised. One model per process per chip.
+
+## Speed
+
+Warm calls, batch 1, ETH dispatch, 1 CQ, 12×10, the pinned numerics (`code/scripts/bench.py`, 100 iterations; the numbers of `OPT_BASELINE.md`, 2026-10-08, on a shared host; p50, with p99 in brackets):
+
+| stage | shipped sample `kashiwanoha_dense` |
+|---|---:|
+| `.npz` decode + schema check (path inputs only) | 7.02 (18.20) ms |
+| host pre-processing (the node's normalization, the encoder's host features, masks, `x_T`) | 4.75 (12.55) ms |
+| packing the 19 persistent trace inputs · ttnn host tensors · H2D | 0.45 · 2.41 · 1.14 ms |
+| **device trace, one blocking plan** | **102.13** (104.81) ms |
+| D2H (one packed read, 460 KB) | 0.58 ms |
+| host post-processing (trajectory, predicted paths, turn decision) | 4.32 (11.54) ms |
+| **`model(inputs=arrays)` end to end** | **117.90** (134.56) ms |
+| `model(inputs=<.npz path>)` | 124.76 (147.74) ms |
+| back-to-back replays (device time per plan) | 102.04 ms = 9.80 plans/s |
+
+The device time does not depend on the scene: every plan computes the full capacities (re-checked on c0d84f9: kashiwanoha_dense 102.10, straight_road 102.11, a nuScenes instant 102.09 ms). Throughput above one plan per ~118 ms needs pipelining of the host work of neighbouring requests (not implemented); 2 CQs do not help a synchronous request (`OPT_BASELINE.md`). Where the time goes and what comes next: `OPT_REPORT.md`.
+
+## Limits
+
+- Batch 1 on the chip; one model per process.
+- Fixed shapes of the v5.0 export (320 neighbours, 140 lanes, 25 route lanes, 10 polygons, 60 line strings, 31 history
+  and 80 future steps) and 10 DPM-Solver steps (11 decoder evaluations) are compiled into the trace; every plan computes
+  the full capacities, so the device time does not depend on the scene.
+- The node's guidance services (start / stop / centerline guidance) are not available (the node's default is off).
+- Accuracy is agreement with the fp32 CPU reference of the same network (README "Demo & Performances"); the planner's
+  driving quality is the weights' (trained by TIER IV on data that is not public).

code/conftest.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+"""pytest fixtures of diffusion-planner-p150 (no dependency on tt-metal's own conftest).
+
+- ``device`` (session): one chip opened like the published numbers (``tt_diffusion_planner.device.open_device``:
+  ETH dispatch, 12x10 grid, the port's validated sizes and CQs). ``--device-id N`` or ``TT_DEVICE_ID`` selects
+  the chip (default 0); ``DIFFUSION_PLANNER_DISPATCH=worker`` is the A/B opt-in, and the other ``DIFFUSION_PLANNER_*``
+  variables apply as for the server. A failing ETH open is an error here, never a silent WORKER fallback: gates
+  are only valid on the published setup.
+- Tests marked ``device`` are skipped when ttnn is missing or ``TT_VISIBLE_DEVICES=none`` (host-only runs).
+  On the shared workspace box run them through the lock and name the test files:
+  ``bin/devrun -t 1800 -- python -m pytest -q -s code/tt_diffusion_planner/tests/test_pcc_device.py``.
+"""
+from __future__ import annotations
+
+import gc
+import importlib.util
+import os
+
+import pytest
+
+
+def pytest_addoption(parser):
+    parser.addoption("--device-id", action="store", default=None, help="chip id (default $TT_DEVICE_ID or 0)")
+
+
+def pytest_configure(config):
+    config.addinivalue_line("markers", "device: needs a Tenstorrent chip (skipped on host-only runs)")
+
+
+def _no_device_reason():
+    if os.environ.get("TT_VISIBLE_DEVICES", "").lower() == "none":
+        return "TT_VISIBLE_DEVICES=none (host-only run)"
+    if importlib.util.find_spec("ttnn") is None:
+        return "ttnn is not installed"
+    return None
+
+
+def pytest_collection_modifyitems(config, items):
+    reason = _no_device_reason()
+    if reason:
+        skip = pytest.mark.skip(reason=reason)
+        for item in items:
+            if "device" in item.keywords:
+                item.add_marker(skip)
+
+
+@pytest.fixture(autouse=True)
+def _gc_between_tests():
+    gc.collect()
+
+
+@pytest.fixture(scope="session")
+def device(request):
+    from tt_diffusion_planner.device import close_device, open_device
+
+    cli = request.config.getoption("--device-id")
+    dev = open_device(int(cli) if cli is not None else None, allow_fallback=False)
+    yield dev
+    close_device(dev)

code/models/common/lightweightmodule.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: © 2023 Tenstorrent USA, Inc.
+
+# SPDX-License-Identifier: Apache-2.0
+
+
+class LightweightModule:
+    """Torch modules add a surprising amount of host overhead for attribute
+    access and method calls. This class is a lightweight alternative that
+    just wraps a forward function for now."""
+
+    def __call__(self, *args, **kwargs):
+        return self.forward(*args, **kwargs)

code/scripts/README.md

@@ -0,0 +1,16 @@
+# code/scripts
+
+| script | purpose | device |
+|---|---|---|
+| `bench.py` | stage breakdown of warm plans (load / host_pre / pack / host_in / H2D / trace / D2H / host_post / e2e / b2b, p50 / p99 / min, AICLK) on one or more scene `.npz` files, `--dispatch` / `--num-cqs` for the dispatch / CQ matrix (the card and `OPT_BASELINE.md` numbers) | yes, via `bin/devrun` |
+| `profile_ops.py` | one eager plan (stage `m:` and layer-kind `c:` signposts) + one traced replay between signposts under the device profiler (`python -m tracy -r -p -v --op-support-count 16000 ...`: a plan is 6,282 programs, over the default 1,000-program buffer) | yes |
+| `bringup_device.py`, `precision_exp.py`, `split_error.py` | the port's numerics experiments (module PCC per configuration, LayerNorm / split-matmul / attention variants, where the plan error of a scene comes from: device encoder vs device decoder); their logs and findings are in `PORT_LOG.md` (workspace) | yes |
+| `ref_golden.py` | goldens of the fp32 CPU reference (per-module taps, final outputs, the stored `/predict` references next to the samples) for the device tests; research venv (onnxruntime): `tools/research-venv/bin/python code/scripts/ref_golden.py` | no |
+| `container_smoke.sh` | serve ONE serve profile of the built package (`--profile NAME`; default profile otherwise), run `server/smoke_test.py` against it (asserts ETH dispatch, the 12x10 grid and the profile's pins; compares with the stored CPU reference), keep the evidence (container log, `/info`, the `/predict` output and the result, in `logs/smoke/` of the repo or `--log-dir DIR`), always stop it; one `bin/devrun -t 3600 -k 150` window per profile | yes |
+| `fetch_samples.sh` | downloads public sample data that may not be redistributed (sha256-checked); diffusion-planner-p150 has none to fetch: both shipped samples are Apache-2.0, and the nuScenes-derived planning instants of the accuracy tables live in the tt-models workspace only | no |
+
+Everything here ships in `code/` on the Hub and inside the image (`source.extra_code` lists `scripts`).
+
+The card's demo media (`media/`) were rendered from p150 outputs by workspace scripts that are not shipped, because
+most of the data they read (nuScenes) may not be redistributed (`media/ATTRIBUTION.md`). `examples/quickstart.py`
+writes a simple render (`quickstart_bev.png`: the input tensors and the plan, bird's-eye view) for any scene `.npz`.

code/scripts/bench.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Stage breakdown of warm plans -- the numbers OPT_BASELINE.md / OPT_REPORT.md / the card quote.
+
+    bin/devrun -t 900 -- python code/scripts/bench.py --iters 100 --json out.json
+    bin/devrun -t 900 -- python code/scripts/bench.py --dispatch worker --num-cqs 2 --iters 100 --json out.json
+    bin/devrun -t 900 -- python code/scripts/bench.py --input <a.npz> --input <b.npz> ...
+
+``--input`` takes the planner tensors as an ``.npz`` with the 15 ``INPUT_SCHEMA`` names (the shipped samples) or with
+``raw/<name>`` keys (the research / public-data scene files); default: the shipped ``kashiwanoha_dense.npz``.
+Per input, ``ttaw.profiling.StageBench`` collects ``--iters`` warm iterations of each stage (p50 / p99 / mean / min):
+
+- ``load``: decoding the ``.npz`` + the ``INPUT_SCHEMA`` check (``model(inputs=<path>)`` does it outside timing_ms);
+- ``host_pre``: the node's pre-processing (``host.prepare``: normalization, speed masks, encoder host features,
+  decoder masks, the solver's initial state);
+- ``pack``: the 19 persistent trace inputs (``tt.inputs.plan_inputs``);
+- ``host_in``: their ttnn host tensors (fp32 / bf16 TILE, ``ttaw.tensors.to_host_tensor``);
+- ``h2d``: the upload into the persistent device inputs + device sync;
+- ``trace``: one replay of the ``plan`` trace + device sync (the device latency of one plan);
+- ``d2h``: the one packed readback (``final_x0`` + logits + the ego rows of the 11 iterates);
+- ``host_post``: the node's post-processing (``host.make_output``);
+- ``e2e``: ``model(inputs=<decoded arrays>)``, the in-process API call (schema check included);
+- ``e2e_path``: ``model(inputs=<path>)`` (adds ``load``; schema-named ``.npz`` files only);
+- ``b2b``: back-to-back replays with no host work in between (device time per plan), ``--b2b-rounds`` rounds of
+  ``--b2b-iters`` replays; ``plans_per_s`` = 1000 / median b2b.
+
+Also: ``model(...).timing_ms`` (preprocess / device / postprocess / total), the first call after ``from_pretrained``
+and the load time (weights, build, warm-up + capture), AICLK / power / temperature sampled from sysfs during the
+timed loops (``ttaw.profiling.AiclkSampler``), the staged path checked bit for bit against ``model()``, the device
+configuration (dispatch, CQs, grid) and the numerics options in effect (``DIFFUSION_PLANNER_*`` knobs). Always quote
+the configuration line with the numbers.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from tt_diffusion_planner import DiffusionPlanner
+
+SAMPLE = Path(__file__).resolve().parents[1] / "tt_diffusion_planner" / "samples" / "kashiwanoha_dense.npz"
+
+
+def load_scene(path: str) -> Dict[str, Any]:
+    """``{"name", "path", "arrays", "schema_npz"}``: the 15 raw tensors of a schema-named or ``raw/``-prefixed npz."""
+    from tt_diffusion_planner.reference import config as C
+
+    p = Path(path)
+    with np.load(p, allow_pickle=False) as z:
+        files = set(z.files)
+        if all(k in files for k in C.INPUT_NAMES):
+            arrays, schema_npz = {k: np.array(z[k]) for k in C.INPUT_NAMES}, True
+        elif all(f"raw/{k}" in files for k in C.INPUT_NAMES):
+            arrays, schema_npz = {k: np.array(z[f"raw/{k}"]) for k in C.INPUT_NAMES}, False
+        else:
+            raise SystemExit(f"{p}: neither the INPUT_SCHEMA names nor raw/<name> keys")
+    name = p.stem[len("golden_"):] if p.stem.startswith("golden_") else p.stem
+    if p.parent.name not in ("samples", "ort"):
+        name = f"{p.parent.name}/{name}"
+    return {"name": name, "path": str(p), "arrays": arrays, "schema_npz": schema_npz}
+
+
+def counts(arrays: Dict[str, np.ndarray]) -> Dict[str, int]:
+    """Valid entities of a scene (non-empty rows), for the report."""
+    def rows(a, axis):
+        return int(np.any(np.abs(a) > 0, axis=axis).sum())
+    return {"neighbors": rows(arrays["neighbor_agents_past"][0], (1, 2)), "lanes": rows(arrays["lanes"][0], (1, 2)),
+            "route_lanes": rows(arrays["route_lanes"][0], (1, 2)), "polygons": rows(arrays["polygons"][0], (1, 2)),
+            "line_strings": rows(arrays["line_strings"][0], (1, 2))}
+
+
+def unpack(out: Dict[str, np.ndarray]) -> Dict[str, Any]:
+    """The packed readback -> the raw outputs of ``TtDiffusionPlanner.forward`` (same reshapes)."""
+    from tt_diffusion_planner.reference import config as C
+    from tt_diffusion_planner.tt import config as T
+
+    final = out["final_x0"].reshape(T.AGENTS, T.STATE_COLS)[:C.MAX_NUM_AGENTS]
+    steps = out["ego_steps"].reshape(-1, T.STATE_COLS)
+    return {"final_x0": final.reshape(C.MAX_NUM_AGENTS, C.OUTPUT_T + 1, C.POSE_DIM).astype(np.float32),
+            "logit": out["logit"].reshape(-1)[:C.TURN_INDICATOR_OUTPUT_DIM].astype(np.float32),
+            "denoising_steps": [s.reshape(1, C.OUTPUT_T + 1, C.POSE_DIM).astype(np.float32) for s in steps]}
+
+
+def bench_scene(model, scene: Dict[str, Any], a: argparse.Namespace) -> Dict[str, Any]:
+    import ttnn
+
+    from tt_diffusion_planner.host import pipeline as hp
+    from tt_diffusion_planner.reference import config as C
+    from tt_diffusion_planner.tt import inputs as I
+    from tt_diffusion_planner.ttaw.io import load_named_arrays
+    from tt_diffusion_planner.ttaw.profiling import AiclkSampler, StageBench, time_b2b
+    from tt_diffusion_planner.ttaw.tensors import to_host_tensor
+
+    runner, dev = model.runner, model.device
+    arrays, params = scene["arrays"], model.validate_params({})
+    obs = model.normalization.observation
+    bench = StageBench(f"diffusion-planner {scene['name']}")
+    timing: Dict[str, list] = {}
+    sync = lambda: ttnn.synchronize_device(dev)                     # noqa: E731
+    for _ in range(a.warmup):
+        ref = model(inputs=arrays)
+    with AiclkSampler(chip=a.chip, interval_s=0.05) as clk:
+        for _ in range(a.iters):                                     # the in-process API call
+            with bench.stage("e2e"):
+                ref = model(inputs=arrays)
+            for k, v in ref.timing_ms.items():
+                timing.setdefault(k, []).append(v)
+        slots = {k: runner._slot(k, "input") for k in I.INPUT_SPECS}
+        for _ in range(a.iters):                                     # the same path, stage by stage
+            if scene["schema_npz"]:
+                with bench.stage("load"):
+                    raw = load_named_arrays(scene["path"], C.INPUT_SCHEMA)
+            else:
+                raw = load_named_arrays(arrays, C.INPUT_SCHEMA)
+            with bench.stage("host_pre"):
+                prep = hp.prepare(raw, obs)
+            with bench.stage("pack"):
+                packed = I.plan_inputs(prep)
+            with bench.stage("host_in"):
+                host = {k: to_host_tensor(v, slots[k].dtype, slots[k].layout, shape=slots[k].shape)
+                        for k, v in packed.items()}
+            with bench.stage("h2d"):
+                runner.upload(host)
+                sync()
+            with bench.stage("trace"):
+                runner.replay("plan")
+                sync()
+            with bench.stage("d2h"):
+                out = runner.read("plan")
+            with bench.stage("host_post"):
+                res = model._postprocess(unpack(out), prep, params)
+        if scene["schema_npz"]:
+            for _ in range(a.iters):
+                with bench.stage("e2e_path"):
+                    model(inputs=scene["path"])
+        rounds = [time_b2b(lambda: runner.replay("plan"), sync, n=a.b2b_iters, warmup=3)
+                  for _ in range(a.b2b_rounds)]
+        for r in rounds:
+            bench.add("b2b", r)
+    same = bool(np.array_equal(res.poses, ref.poses) and np.array_equal(res.predicted_agents, ref.predicted_agents)
+                and res.turn_indicator["command"] == ref.turn_indicator["command"])
+    summary = bench.summary()
+    b2b = statistics.median(rounds)
+    return {"name": scene["name"], "path": scene["path"], "valid": counts(arrays), "stages_ms": summary,
+            "timing_ms": {k: {"p50": float(np.percentile(v, 50)), "p99": float(np.percentile(v, 99)),
+                              "min": float(min(v))} for k, v in timing.items()},
+            "b2b_rounds_ms": rounds, "plans_per_s_b2b": 1000.0 / b2b, "aiclk": clk.summary(),
+            "staged_equals_model": same, "turn_command": int(ref.turn_indicator["command"]),
+            "table": bench.table()}
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("--iters", type=int, default=100)
+    ap.add_argument("--warmup", type=int, default=5)
+    ap.add_argument("--b2b-iters", type=int, default=50)
+    ap.add_argument("--b2b-rounds", type=int, default=3)
+    ap.add_argument("--input", action="append", default=None, help="scene .npz (repeatable)")
+    ap.add_argument("--dispatch", default=None, choices=["eth", "worker"])
+    ap.add_argument("--num-cqs", type=int, default=None, choices=[1, 2])
+    ap.add_argument("--chip", type=int, default=0, help="sysfs chip index for the AICLK sampler")
+    ap.add_argument("--tag", default="")
+    ap.add_argument("--json")
+    a = ap.parse_args()
+    from tt_diffusion_planner.reference.weights import find_weights_dir
+
+    scenes = [load_scene(p) for p in (a.input or [str(SAMPLE)])]
+    wd = find_weights_dir()                     # None: from_pretrained resolves the pinned HF snapshot
+    t0 = time.perf_counter()
+    with DiffusionPlanner.from_pretrained(dispatch=a.dispatch, num_command_queues=a.num_cqs,
+                                          weights_dir=str(wd) if wd else None) as model:
+        load_s = time.perf_counter() - t0
+        t1 = time.perf_counter()
+        model(inputs=scenes[0]["arrays"])                         # first call after from_pretrained (traces captured)
+        first_ms = (time.perf_counter() - t1) * 1e3
+        info = model.tt.describe()
+        res: Dict[str, Any] = {
+            "tag": a.tag, "config": model.device_info, "iters": a.iters, "load_s": round(load_s, 2),
+            "warmup_ms": {k: round(v, 1) for k, v in model.warmup_ms.items()}, "first_call_ms": round(first_ms, 2),
+            "options": info["options"], "precision": info["precision"], "uploaded_mb": info["uploaded_mb"],
+            "trace_buffers_mb": info["trace_buffers_mb"],
+            "program_cache_entries": info["trace"].get("program_cache_entries"),
+            "num_command_queues": info["trace"]["num_command_queues"], "scenes": {}}
+        for scene in scenes:
+            r = bench_scene(model, scene, a)
+            res["scenes"][r["name"]] = r
+            cfg = model.device_info
+            print(f"\n## {r['name']}  [{cfg.get('dispatch')} {res['num_command_queues']}CQ {cfg.get('grid')}] "
+                  f"valid {r['valid']}")
+            print(r["table"])
+            print("timing_ms p50:", {k: round(v["p50"], 3) for k, v in r["timing_ms"].items()},
+                  f"| b2b rounds {[round(x, 3) for x in r['b2b_rounds_ms']]} ms -> {r['plans_per_s_b2b']:.2f} plans/s",
+                  f"| aiclk {r['aiclk'].get('aiclk_mhz')}", f"| check: staged == model() {r['staged_equals_model']}",
+                  flush=True)
+    print(json.dumps({k: v for k, v in res.items() if k != "scenes"}, default=str))
+    if a.json:
+        Path(a.json).parent.mkdir(parents=True, exist_ok=True)
+        Path(a.json).write_text(json.dumps(res, indent=1, default=str) + "\n")
+
+
+if __name__ == "__main__":
+    main()

code/scripts/bringup_device.py

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Device bring-up of the planner graph (development tool; needs the p150, run through ``bin/devrun``).
+
+    bin/devrun -t 1800 -- python code/scripts/bringup_device.py [--scenes kashiwanoha_dense straight_road]
+        [--no-capture] [--precision "dec.*=HiFi2+fp32"] [--json logs/diffusion-planner/bringup.json]
+
+Protocol (PLAN.md 4.4): build ``TtDiffusionPlanner(debug=True)``; per scene run every variant EAGERLY twice
+(``encoder_taps``, ``decode_once`` at evaluations 0 / 5 / 10, ``plan``), check the two eager runs are bit-identical and
+compare them with the research goldens (``research/diffusion-planner/goldens/<scene>.npz``, the fp32 CPU reference:
+PCC on valid rows, max abs; final x0 on valid agents; logits); then capture all variants (strict, no program
+compiled after the capture) and check replay == eager bit for bit on the same inputs. Prints a table and writes a
+JSON report. This is a diagnostic: the frozen gates live in ``tests/test_pcc_device.py`` / ``test_e2e_device.py``.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+
+HERE = Path(__file__).resolve()
+sys.path.insert(0, str(HERE.parents[1]))
+
+from tt_diffusion_planner.host import pipeline as hp  # noqa: E402
+from tt_diffusion_planner.reference import config as C  # noqa: E402
+from tt_diffusion_planner.ttaw.metrics import error_stats  # noqa: E402
+
+GOLDENS = HERE.parents[4] / "research" / "diffusion-planner" / "goldens"
+
+
+def stats(dev, ref):
+    s = error_stats(np.asarray(dev, np.float64), np.asarray(ref, np.float64))
+    return {"pcc": round(s["pcc"], 7), "max_abs": float(f"{s['max_abs']:.4g}"), "rel_l2": float(f"{s['rel_l2']:.4g}")}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("--scenes", nargs="+", default=["kashiwanoha_dense", "straight_road"])
+    ap.add_argument("--no-capture", action="store_true")
+    ap.add_argument("--precision", default=None)
+    ap.add_argument("--ln-fp32", default=None, help="module globs (comma-separated) for the fp32 LayerNorm")
+    ap.add_argument("--hidden-fp32", default=None, help="module globs (comma-separated) for fp32 hidden activations")
+    ap.add_argument("--split", default=None, help="module globs (comma-separated) for split (hi/lo) fp32 matmuls")
+    ap.add_argument("--attn-fp32-acc", default=None, help="module globs for SDPA with fp32 accumulation")
+    ap.add_argument("--attn-matmul", default=None, help="module globs for the fp32 matmul attention")
+    ap.add_argument("--plan-only", action="store_true", help="skip the encoder taps and decoder evaluations")
+    ap.add_argument("--evals", nargs="+", type=int, default=[0, 5, 10])
+    ap.add_argument("--json", default=None)
+    args = ap.parse_args()
+
+    import torch
+
+    torch.set_num_threads(4)
+    from tt_diffusion_planner.device import close_device, open_device
+    from tt_diffusion_planner.reference.weights import find_weights_dir, load_weights
+    from tt_diffusion_planner.tt.model import TtDiffusionPlanner
+
+    weights = load_weights(find_weights_dir())
+    dev = open_device(allow_fallback=False)
+    g = dev.compute_with_storage_grid_size()
+    report = {"grid": f"{g.x}x{g.y}", "precision": args.precision, "scenes": {}}
+    t0 = time.perf_counter()
+    from tt_diffusion_planner.tt.config import globs
+
+    opts = {k: globs(v) for k, v in (("ln_fp32", args.ln_fp32), ("hidden_fp32", args.hidden_fp32),
+                                     ("split", args.split), ("attn_fp32_acc", args.attn_fp32_acc),
+                                     ("attn_matmul", args.attn_matmul)) if v is not None}
+    tt = TtDiffusionPlanner(dev, weights, debug=True, precision=args.precision, **opts)
+    report["options"] = tt.build.options()
+    report["build_s"] = round(time.perf_counter() - t0, 2)
+    print(f"build {report['build_s']} s, uploaded {tt.build.uploaded_bytes / 2**20:.1f} MiB", flush=True)
+    runner = tt.runner
+    from tt_diffusion_planner.tt import inputs as I
+
+    eager_cache = {}
+    try:
+        for scene in args.scenes:
+            with np.load(GOLDENS / f"{scene}.npz", allow_pickle=False) as z:
+                gold = {k: z[k] for k in z.files if k != "__meta__"}
+            raw = {k: gold[f"in.{k}"] for k in C.INPUT_NAMES}
+            prep = hp.prepare(raw, weights.normalization.observation)
+            res = {}
+            if args.plan_only:
+                args.evals = []
+            # encoder taps (eager x2)
+            t1 = time.perf_counter()
+            taps = tt.encoder_taps(prep, eager=True)
+            taps2 = taps if args.plan_only else tt.encoder_taps(prep, eager=True)
+            res["encoder_eager_s"] = round(time.perf_counter() - t1, 2)
+            res["encoder_deterministic"] = all(np.array_equal(taps[k], taps2[k]) for k in taps)
+            for name, _ in C.TOKEN_LAYOUT:
+                rows = np.flatnonzero(gold[f"host.valid.{name}"])
+                if rows.size:
+                    res[f"enc.{name}"] = stats(taps[f"enc.{name}"][rows], gold[f"enc.{name}"][rows])
+            for c in ("ego", "neighbor", "lane", "route", "polygon", "line_string"):
+                rows = gold[f"enc.{c}.pre.rows"]
+                if rows.size:
+                    for part in ("pre", "mixer"):
+                        res[f"enc.{c}.{part}"] = stats(taps[f"enc.{c}.{part}"][rows], gold[f"enc.{c}.{part}"])
+            tok = np.flatnonzero(gold["host.token_valid"])
+            for name in ["enc.tokens"] + [f"enc.fusion.{i}" for i in range(6)] + ["enc.encoding"]:
+                res[name] = stats(taps[name][tok], gold[name][tok])
+            # decode_once, teacher forced
+            arows = gold["dec.rows"]
+            for k in args.evals:
+                outs = [tt_decode(tt, runner, prep, gold, k) for _ in range(2)]
+                res[f"dec.eval{k}.deterministic"] = bool(np.array_equal(outs[0], outs[1]))
+                res[f"dec.eval{k}"] = stats(outs[0][arows][:, 1:], gold["dec.out"][k][:, 1:])
+            # plan (eager x2)
+            t1 = time.perf_counter()
+            p1 = runner.run_eager("plan", inputs=I.plan_inputs(prep))
+            p2 = runner.run_eager("plan", inputs=I.plan_inputs(prep))
+            res["plan_eager_s"] = round(time.perf_counter() - t1, 2)
+            res["plan_deterministic"] = all(np.array_equal(p1[k], p2[k]) for k in p1)
+            eager_cache[scene] = (prep, p1)
+            final = p1["final_x0"].reshape(352, 324)[:321].reshape(321, 81, 4)
+            res["plan.final_x0"] = stats(final[arows], gold["final_x0"][arows])
+            res["plan.logit"] = {"dev": [round(float(v), 4) for v in p1["logit"].reshape(-1)[:5]],
+                                 "ref": [round(float(v), 4) for v in gold["turn.logit"]]}
+            out = hp.make_output(final, p1["logit"].reshape(-1)[:5], prep, weights.normalization,
+                                 {k: v[3] for k, v in hp.RUNTIME_PARAMS.items()})
+            dpos = np.hypot(*(out.poses[:, :2] - gold["out.trajectory"][:, :2]).T)
+            res["plan.ego_max_m"], res["plan.ego_mean_m"] = round(float(dpos.max()), 4), round(float(dpos.mean()), 4)
+            res["plan.turn_equal"] = int(out.turn_indicator["command"]) == int(gold["out.turn_command"])
+            if gold["out.predicted_agents"].shape[0]:
+                dxy = out.predicted_agents[..., :2] - gold["out.predicted_agents"][..., :2]
+                per = np.hypot(*dxy.transpose(2, 0, 1))
+                res["plan.nb_median_max_m"] = round(float(np.median(per.max(axis=1))), 4)
+            report["scenes"][scene] = res
+            print(json.dumps({scene: res}, indent=1), flush=True)
+        if not args.no_capture:
+            t1 = time.perf_counter()
+            runner.capture()
+            report["capture_s"] = round(time.perf_counter() - t1, 2)
+            report["timings_ms"] = runner.timings_ms
+            for scene, (prep, p1) in eager_cache.items():
+                rep = runner("plan", inputs=I.plan_inputs(prep))
+                report["scenes"][scene]["plan_replay_equals_eager"] = all(np.array_equal(rep[k], p1[k]) for k in p1)
+                import ttnn
+
+                ttnn.synchronize_device(dev)
+                t2 = time.perf_counter()
+                runner.replay("plan", 5)
+                ttnn.synchronize_device(dev)
+                report["scenes"][scene]["plan_replay_ms"] = round((time.perf_counter() - t2) / 5 * 1e3, 3)
+            print(json.dumps({k: v for k, v in report.items() if k != "scenes"}, indent=1, default=str), flush=True)
+            print(json.dumps({s: {k: v for k, v in r.items() if k.startswith("plan_")}
+                              for s, r in report["scenes"].items()}, indent=1), flush=True)
+    finally:
+        tt.release()
+        close_device(dev)
+    if args.json:
+        Path(args.json).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.json).write_text(json.dumps(report, indent=1, default=str) + "\n")
+    return 0
+
+
+def tt_decode(tt, runner, prep, gold, k):
+    return tt.decode_once(prep, gold["dec.x_in"][k], float(gold["dec.t"][k]), encoding=gold["enc.encoding"],
+                          eager=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code/scripts/container_smoke.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Serve ONE serve profile of the BUILT container package, run the smoke test against it, keep the evidence, and always
+# stop it -- in one device-lock window. Run it once per serve profile (`tt-model profiles
+# <staged dir>/tt_kernel_manifest.json` lists them; without --profile the package's default profile is served):
+#
+#   ROOT=/home/ubuntu/experiments/tt-models
+#   $ROOT/bin/devrun -t 3600 -k 150 -- env -u HF_TOKEN -u HUGGING_FACE_HUB_TOKEN sg docker -c \
+#       "bash code/scripts/container_smoke.sh $ROOT/build/diffusion-planner-p150 [port] [--profile NAME] [--log-dir DIR]"
+#
+# The smoke test FAILS unless /info reports ETH dispatch and the 12x10 grid and runs what the package pins for the
+# profile (dispatch, CQs, variant, weights revision); it also compares the output with the stored CPU reference of the
+# sample when one exists (code/tt_diffusion_planner/server/smoke_test.py). Exit code: the smoke test's (0 = PASS); 1 when
+# serve fails, 2 on a usage error.
+#
+# Evidence, kept whatever the outcome (--log-dir, default: logs/smoke/ of this repo, next to code/), named
+# <name>[-<profile>]-<UTC time>.*:
+#   .container.log  the container's whole log (boot, requests, shutdown), followed while the container stops
+#   .info.json      GET /info as soon as the server is READY (device: dispatch, grid, cores; pins; versions)
+#   .smoke.json     the smoke test's /predict output (the SMOKE_OUT environment variable overrides this path)
+#   .result.json    profile, port, exit code, start / end times
+#
+# `tt-model serve` returns once the server is READY and leaves the container running, so the stop must happen before
+# the lock is released, also when devrun's timeout TERMs this script: the EXIT trap saves the log, then stops the
+# container cleanly with SIGTERM (120 s grace, hence devrun -k 150), never `docker kill`, which would leave the chip
+# dirty. Needs docker access (sg docker) and python3.
+set -u
+usage() { echo "usage: container_smoke.sh <staged package dir> [port] [--profile NAME] [--log-dir DIR]" >&2; }
+PROFILE=""
+LOG_DIR=""
+POSITIONAL=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --profile) [ $# -ge 2 ] || { usage; exit 2; }; PROFILE="$2"; shift 2 ;;
+    --profile=*) PROFILE="${1#--profile=}"; shift ;;
+    --log-dir) [ $# -ge 2 ] || { usage; exit 2; }; LOG_DIR="$2"; shift 2 ;;
+    --log-dir=*) LOG_DIR="${1#--log-dir=}"; shift ;;
+    -h|--help) usage; exit 0 ;;
+    -*) echo "container_smoke.sh: unknown option $1" >&2; usage; exit 2 ;;
+    *) POSITIONAL+=("$1"); shift ;;
+  esac
+done
+[ ${#POSITIONAL[@]} -ge 1 ] && [ ${#POSITIONAL[@]} -le 2 ] || { usage; exit 2; }
+STAGED="${POSITIONAL[0]}"
+PORT="${POSITIONAL[1]:-20000}"
+MANIFEST="$STAGED/tt_kernel_manifest.json"
+[ -f "$MANIFEST" ] || { echo "container_smoke.sh: $MANIFEST not found (run tt-model package first)" >&2; exit 2; }
+HERE="$(cd "$(dirname "$0")" && pwd)"
+PROFILE_ARGS=()
+[ -n "$PROFILE" ] && PROFILE_ARGS=(--profile "$PROFILE")
+
+# The package name and the served profile (tt-model's rule: --profile, else default_profile, else the first serve
+# profile), hence the container name tt-model gives it: tt-model-<name>-<profile> (tt_kernel/container.py).
+read -r NAME PROFILE_NAME < <(python3 - "$MANIFEST" "$PROFILE" <<'EOF'
+import json, sys
+m = json.load(open(sys.argv[1]))
+c = m.get("container") or {}
+profiles = c.get("serve_profiles") or [{}]
+print(m.get("name") or "model", sys.argv[2] or c.get("default_profile") or profiles[0].get("name") or "default")
+EOF
+)
+[ -n "${NAME:-}" ] || { echo "container_smoke.sh: cannot read the package name from $MANIFEST" >&2; exit 2; }
+CONTAINER="tt-model-$NAME-$PROFILE_NAME"
+
+[ -n "$LOG_DIR" ] || LOG_DIR="$(cd "$HERE/../.." && pwd)/logs/smoke"
+if ! mkdir -p "$LOG_DIR" 2>/dev/null || [ ! -w "$LOG_DIR" ]; then
+  echo "container_smoke.sh: cannot write $LOG_DIR; keeping the evidence in ${TMPDIR:-/tmp}" >&2
+  LOG_DIR="${TMPDIR:-/tmp}"
+fi
+LOG_DIR="$(cd "$LOG_DIR" && pwd)"
+STARTED="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+STEM="$LOG_DIR/$NAME${PROFILE:+-$PROFILE}-$(date -u +%Y%m%dT%H%M%SZ)"
+SMOKE_JSON="${SMOKE_OUT:-$STEM.smoke.json}"
+
+fetch() {  # fetch URL FILE: one GET with a 30 s timeout; the body goes to FILE
+  python3 - "$1" "$2" <<'EOF'
+import sys, urllib.request
+try:
+    with urllib.request.urlopen(sys.argv[1], timeout=30) as r:
+        body = r.read()
+except Exception as e:  # noqa: BLE001 -- best effort: the smoke test reports the server's state
+    sys.exit(f"container_smoke.sh: GET {sys.argv[1]} failed: {e}")
+open(sys.argv[2], "wb").write(body)
+EOF
+}
+
+CHILD=""
+STOPPED=0
+cleanup() {
+  local rc=$?
+  [ "$STOPPED" = 1 ] && return
+  STOPPED=1
+  if [ -n "$CHILD" ]; then kill -TERM "$CHILD" 2>/dev/null; wait "$CHILD" 2>/dev/null; fi
+  # The log is lost with the container: follow it (whole history, then the shutdown lines) while it stops.
+  local logger=""
+  if docker inspect "$CONTAINER" >/dev/null 2>&1; then
+    docker logs --follow "$CONTAINER" > "$STEM.container.log" 2>&1 &
+    logger=$!
+  else
+    tt-model logs "${PROFILE_ARGS[@]}" "$MANIFEST" > "$STEM.container.log" 2>&1 || true
+  fi
+  tt-model stop "${PROFILE_ARGS[@]}" "$MANIFEST" || true
+  if [ -n "$logger" ]; then
+    for _ in $(seq 1 30); do kill -0 "$logger" 2>/dev/null || break; sleep 1; done
+    kill "$logger" 2>/dev/null
+    wait "$logger" 2>/dev/null
+  fi
+  python3 - "$STEM.result.json" "$NAME" "$PROFILE_NAME" "$PORT" "$rc" "$STARTED" "$CONTAINER" "$MANIFEST" <<'EOF'
+import datetime, json, sys
+out, name, profile, port, rc, started, container, manifest = sys.argv[1:]
+ended = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+json.dump({"bundle": name, "profile": profile, "port": int(port) if port.isdigit() else port, "rc": int(rc),
+           "result": "PASS" if rc == "0" else "FAIL",
+           "started": started, "ended": ended, "container": container, "manifest": manifest}, open(out, "w"), indent=1)
+EOF
+  echo "container_smoke.sh: rc=$rc; evidence in $STEM.*"
+}
+trap cleanup EXIT
+trap 'exit 143' TERM
+trap 'exit 130' INT
+
+# Each step runs in the background and is waited for: bash defers a trap while a FOREGROUND command runs, so a TERM
+# sent to this script alone (devrun's timeout signals the whole process group) would otherwise wait for the step.
+step() {
+  "$@" &
+  CHILD=$!
+  wait "$CHILD"
+  local rc=$?
+  CHILD=""
+  return "$rc"
+}
+
+# --port and --profile BEFORE the target: options after it are passed through to the container (tt-model cli rule)
+step tt-model serve --port "$PORT" "${PROFILE_ARGS[@]}" "$MANIFEST" || exit 1
+step fetch "http://127.0.0.1:$PORT/info" "$STEM.info.json"
+step python3 "$HERE/../tt_diffusion_planner/server/smoke_test.py" --url "http://127.0.0.1:$PORT" --wait 600 \
+    --manifest "$MANIFEST" "${PROFILE_ARGS[@]}" --out "$SMOKE_JSON"

code/scripts/fetch_samples.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Download the public sample data that diffusion-planner-p150 may NOT redistribute (license unstated or non-commercial)
+# into ${DIFFUSION_PLANNER_SAMPLES:-$HOME/.cache/tt_diffusion_planner/samples}, sha256-checked. Tests and benchmarks read it from there.
+# Nothing downloaded here is executed; parse it with numpy / sqlite3 only.
+set -euo pipefail
+DEST="${DIFFUSION_PLANNER_SAMPLES:-$HOME/.cache/tt_diffusion_planner/samples}"
+mkdir -p "$DEST"
+
+fetch() {  # fetch <url> <sha256> <file name>
+  local url="$1" sum="$2" name="$3"
+  if [ -f "$DEST/$name" ] && echo "$sum  $DEST/$name" | sha256sum -c --status; then
+    echo "ok      $name"; return
+  fi
+  curl -fL --retry 3 -o "$DEST/$name.part" "$url"
+  echo "$sum  $DEST/$name.part" | sha256sum -c --status || { echo "sha256 mismatch: $name" >&2; exit 1; }
+  mv "$DEST/$name.part" "$DEST/$name"; echo "fetched $name"
+}
+
+# Example (Autoware demo rosbag; pinned in autoware/ansible/roles/demo_artifacts/tasks/main.yaml:48-53):
+# fetch https://autoware-files.s3.us-west-2.amazonaws.com/recordings/bags/demos/sample-rosbag.zip \
+#       5f9d36353393b3d249212153c19049822b1298db56512aa045b4f7f6fc37cf88 sample-rosbag.zip
+# nothing to fetch: both shipped samples are redistributable (Apache-2.0)
+echo "samples in $DEST"

code/scripts/precision_exp.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Precision experiment for the MLP-Mixer blocks on the device (development tool; run under ``bin/devrun``).
+
+    bin/devrun -t 1200 -- python code/scripts/precision_exp.py [--json logs/diffusion-planner/precision_exp.json]
+
+Part A: ``ttnn.layer_norm`` vs :func:`tt.layers.layer_norm_fp32` on the real offset-dominated mixer rows (the
+reference ``enc.neighbor.pre`` of the samples, block 0 ``norm1``) against float64. Part B: the 6 mixer blocks of ego /
+neighbour / lane run alone on the reference's own block input (``enc.<cat>.pre``, teacher forcing) under several
+option sets, compared with the reference ``enc.<cat>.mixer`` on the valid entities. Eager (no trace).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+
+HERE = Path(__file__).resolve()
+sys.path.insert(0, str(HERE.parents[1]))
+
+from tt_diffusion_planner.reference import config as C  # noqa: E402
+from tt_diffusion_planner.ttaw.metrics import error_stats  # noqa: E402
+
+GOLDENS = HERE.parents[4] / "research" / "diffusion-planner" / "goldens"
+CONFIGS = {
+    "default": dict(),
+    "ln_fp32": dict(ln_fp32=("enc.mixer.*",)),
+    "hidden_fp32": dict(hidden_fp32=("enc.mixer.*",)),
+    "ln_hidden_fp32": dict(ln_fp32=("enc.mixer.*",), hidden_fp32=("enc.mixer.*",)),
+    "all_fp32_w": dict(ln_fp32=("enc.mixer.*",), hidden_fp32=("enc.mixer.*",),
+                       precision="enc.mixer.*=HiFi4+fp32:w=fp32:a=fp32"),
+    "stream_bf16": dict(precision="enc.mixer.*=HiFi4+fp32:w=bf16:a=bf16"),
+}
+
+
+def st(dev, ref):
+    s = error_stats(np.asarray(dev, np.float64), np.asarray(ref, np.float64))
+    return {"pcc": round(s["pcc"], 7), "rel_l2": float(f"{s['rel_l2']:.4g}"), "max_abs": float(f"{s['max_abs']:.4g}")}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--scenes", nargs="+", default=["kashiwanoha_dense", "straight_road"])
+    ap.add_argument("--cats", nargs="+", default=["ego", "neighbor", "lane"])
+    ap.add_argument("--configs", nargs="*", default=list(CONFIGS))
+    ap.add_argument("--json", default=None)
+    args = ap.parse_args()
+    import torch
+    import ttnn
+
+    torch.set_num_threads(4)
+    from tt_diffusion_planner.device import close_device, open_device
+    from tt_diffusion_planner.reference.weights import find_weights_dir, load_weights
+    from tt_diffusion_planner.tt.encoder import ENTITIES, MixerTrunk
+    from tt_diffusion_planner.tt.layers import Build, layer_norm_fp32, policy
+    from tt_diffusion_planner.ttaw.precision import compute_kernel_config
+    from tt_diffusion_planner.ttaw.tensors import to_device, to_numpy
+
+    p = load_weights(find_weights_dir()).params
+    gold = {}
+    for s in args.scenes:
+        with np.load(GOLDENS / f"{s}.npz", allow_pickle=False) as z:
+            gold[s] = {k: z[k] for k in z.files if k.startswith(("enc.", "host.valid"))}
+    dev = open_device(allow_fallback=False)
+    report = {"ln": {}, "mixer": {}}
+    try:
+        # ---- A: LayerNorm accuracy on real rows
+        g = p["encoder.neighbor_encoder.blocks.0.norm1.gamma"]
+        b = p["encoder.neighbor_encoder.blocks.0.norm1.beta"]
+        gd, bd = (to_device(v.reshape(1, 1, 1, -1), dev, "float32") for v in (g, b))
+        for s in args.scenes:
+            x = gold[s]["enc.neighbor.pre"].reshape(1, 1, -1, C.MIXER_CHANNELS).astype(np.float32)
+            xx = x.astype(np.float64)
+            ref = (xx - xx.mean(-1, keepdims=True)) / np.sqrt(xx.var(-1, keepdims=True) + 1e-5) * g + b
+            tx = to_device(x, dev, "float32")
+            fused = to_numpy(ttnn.layer_norm(tx, epsilon=1e-5, weight=gd, bias=bd,
+                                             compute_kernel_config=compute_kernel_config("HiFi4", fp32_acc=True)))
+            dec = to_numpy(layer_norm_fp32(tx, gd, bd))
+            report["ln"][s] = {"fused_fp32": st(fused, ref), "decomposed_fp32": st(dec, ref),
+                               "row_offset_ratio": float(np.abs(xx.mean(-1)).mean() / xx.std(-1).mean())}
+            print("LN", s, json.dumps(report["ln"][s]), flush=True)
+        # ---- B: mixer blocks alone, teacher-forced
+        for name in args.configs:
+            cfg = dict(CONFIGS[name])
+            build = Build(dev, policy(spec=cfg.pop("precision", None)), **cfg)
+            for cat in args.cats:
+                trunk = MixerTrunk(build, p, cat)
+                for s in args.scenes:
+                    rows = gold[s][f"enc.{cat}.pre.rows"]
+                    if rows.size == 0:
+                        continue
+                    x0 = np.zeros((1, ENTITIES[cat], C.MIXER_TOKENS, C.MIXER_CHANNELS), np.float32)
+                    x0[0, rows] = gold[s][f"enc.{cat}.pre"]
+                    out = to_numpy(trunk.mix(to_device(x0, dev, trunk.stream)))[0, rows]
+                    r = st(out, gold[s][f"enc.{cat}.mixer"])
+                    report["mixer"].setdefault(name, {}).setdefault(cat, {})[s] = r
+                    print(f"MIX {name:15s} {cat:9s} {s:18s} {json.dumps(r)}", flush=True)
+                del trunk
+        # ---- C: the island on the device (TF32-like vs split matmuls) -> pre error, and the float64 CPU mixer on
+        # the device pre (separates the input error from the device mixer)
+        from tt_diffusion_planner.host import pipeline as hp
+        from tt_diffusion_planner.reference.model import Encoder, torch_params
+        from tt_diffusion_planner.tt import inputs as I
+
+        ref_enc = Encoder(torch_params(p, torch.float64))
+        weights = load_weights(find_weights_dir())
+
+        def cpu_mix(x, cat):
+            N = f"encoder.{cat}_encoder"
+            x = torch.from_numpy(np.asarray(x, np.float64))
+            for i in range(C.MIXER_DEPTH):
+                B = f"{N}.blocks.{i}"
+                x = x + ref_enc.mlp(ref_enc.ln(x, f"{B}.norm1").transpose(1, 2), f"{B}.tokens_mlp").transpose(1, 2)
+                x = x + ref_enc.mlp(ref_enc.ln(x, f"{B}.norm2"), f"{B}.channels_mlp")
+            return x.numpy()
+
+        preps = {}
+        for s in args.scenes:
+            with np.load(GOLDENS / f"{s}.npz", allow_pickle=False) as z:
+                raw = {k: z[f"in.{k}"] for k in C.INPUT_NAMES}
+            preps[s] = I.plan_inputs(hp.prepare(raw, weights.normalization.observation))
+        for mode, split in (("tf32", ()), ("split", ("enc.island.*",))):
+            build = Build(dev, policy(), ln_fp32=("enc.mixer.*",), split=split)
+            for cat in ("ego", "neighbor"):
+                trunk = MixerTrunk(build, p, cat)
+                for s in args.scenes:
+                    rows = gold[s][f"enc.{cat}.pre.rows"]
+                    pre_t = trunk.pre(to_device(preps[s][f"{cat}_x"], dev, "float32"))
+                    pre = to_numpy(pre_t)[0, rows]
+                    mix = to_numpy(trunk.mix(pre_t))[0, rows]
+                    r = {"pre": st(pre, gold[s][f"enc.{cat}.pre"]),
+                         "mix_device": st(mix, gold[s][f"enc.{cat}.mixer"]),
+                         "mix_cpu64_on_device_pre": st(cpu_mix(pre, cat), gold[s][f"enc.{cat}.mixer"])}
+                    report.setdefault("island", {}).setdefault(mode, {}).setdefault(cat, {})[s] = r
+                    print(f"ISL {mode:6s} {cat:9s} {s:18s} {json.dumps(r)}", flush=True)
+                del trunk
+    finally:
+        close_device(dev)
+    if args.json:
+        Path(args.json).write_text(json.dumps(report, indent=1) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code/scripts/profile_ops.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Device profile of diffusion-planner-p150: one eager plan and one traced replay between Tracy signposts.
+
+    ROOT=/home/ubuntu/experiments/tt-models
+    $ROOT/bin/devrun -t 3600 -- python -m tracy -r -p -v --op-support-count 16000 --no-web-server \\
+        -o $ROOT/generated/profiler/diffusion-planner_baseline code/scripts/profile_ops.py
+    tt-perf-report <ops_perf_results_*.csv> --start-signpost trace --end-signpost trace_end
+    python -m tt_diffusion_planner.ttaw.profiling <the same csv or its directory> --start trace --end trace_end
+
+Sections (signposts): ``eager`` .. ``eager_end``, one eager run of the ``plan`` variant after the warm-up
+(``TraceRunner.run_eager``: the same graph and programs as the trace, nothing compiled), and ``trace`` ..
+``trace_end``, ``--replays`` replays of the captured ``plan`` trace (the served device path) on the uploaded sample.
+The device profiler buffer is flushed (``ttnn.ReadDeviceProfiler``) before and after each section.
+
+Inside the eager section two levels of signposts attribute every op (and, through the identical op order, every
+replayed op):
+
+- ``m:<stage>``: the stage of the plan: ``enc.<category>.pre`` / ``.mix`` / ``.head`` (the six mixer trunks, then
+  pool + entity head), ``enc.static``, ``enc.<goal|ego_shape|turn>``, ``enc.tokens`` (concat, validity, position
+  embedding), ``mask`` (key-bias expansion), ``enc.fusion<i>.attn`` / ``.mlp``, ``enc.final_ln``, ``dec.cross_kv``
+  (hoisted cross K / V), ``dec.e<k>.preproj``, ``dec.e<k>.b<i>.attn`` / ``.mlp1`` / ``.cross`` / ``.mlp2``,
+  ``dec.e<k>.final`` (evaluation k = 0..10, DiT block i), ``dec.e<k>.solver`` (the DPM-Solver++(2M) update, the
+  prefix constraint and the ego-row slice of the next iterate), ``turn``, ``pack``;
+- ``c:<kind>``: the layer kind: ``split`` (split hi / lo matmul, ``SplitLinear``), ``linear`` (one ``ttnn.linear``),
+  ``ln32`` (fp32 LayerNorm decomposition), ``ln`` (``ttnn.layer_norm``), ``attn_mm`` (fp32 matmul attention),
+  ``sdpa``, ``heads`` (head split / merge), ``mask``, and ``glue`` for every op outside a layer (residual adds,
+  adaLN gates, mixer transposes, solver updates, slices, concats).
+
+``--no-layer-signposts`` turns both levels off. One plan issues several thousand programs, more than the profiler's
+default 1000-program buffer, so run it with ``--op-support-count`` above the program count of the largest section
+(the warm-up before the first flush included). The output folder must be absolute and outside the bundle
+(PLAN.md 5.1).
+"""
+from __future__ import annotations
+
+import argparse
+import functools
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, List
+
+import numpy as np
+
+from tt_diffusion_planner import DiffusionPlanner
+from tt_diffusion_planner.ttaw.profiling import read_device_profiler, signpost, signposted
+
+SAMPLE = Path(__file__).resolve().parents[1] / "tt_diffusion_planner" / "samples" / "kashiwanoha_dense.npz"
+
+
+class _Proxy:
+    """A callable stand-in for a layer object that emits a signpost (``label()``), then calls the layer."""
+
+    def __init__(self, inner: Any, label: Callable[[], str]):
+        self.inner, self._label = inner, label
+
+    def __call__(self, *args, **kwargs):
+        signpost(self._label())
+        return self.inner(*args, **kwargs)
+
+    def __getattr__(self, name: str):
+        return getattr(self.inner, name)
+
+
+def install_signposts(tt) -> Callable[[], None]:
+    """Signposts on a ``tt.model.TtDiffusionPlanner`` (instance attributes, layer classes and the attention
+    helpers); returns the function that removes them again."""
+    from tt_diffusion_planner.tt import layers as L
+    from tt_diffusion_planner.tt import model as M
+    from tt_diffusion_planner.ttaw.ops import attention as A
+
+    undo: List[Callable[[], None]] = []
+    state = {"k": -1, "ln": {}}
+    stack: List[str] = []
+
+    def set_attr(obj, name, value):
+        had = name in vars(obj)
+        old = vars(obj).get(name)
+        setattr(obj, name, value)
+        undo.append(lambda: setattr(obj, name, old) if had else delattr(obj, name))
+
+    def set_item(d, key, value):
+        old = d[key]
+        d[key] = value
+        undo.append(lambda: d.__setitem__(key, old))
+
+    # ---- layer kinds (class level, with a stack so nested layers restore the outer kind) ---------------------
+    def kind_wrap(owner, name, kind_of):
+        fn = getattr(owner, name)
+
+        @functools.wraps(fn)
+        def inner(*args, **kwargs):
+            kind = kind_of(*args)
+            stack.append(kind)
+            signpost(f"c:{kind}")
+            try:
+                return fn(*args, **kwargs)
+            finally:
+                stack.pop()
+                signpost(f"c:{stack[-1] if stack else 'glue'}")
+
+        setattr(owner, name, inner)
+        undo.append(lambda: setattr(owner, name, fn))
+
+    kind_wrap(L.Linear, "__call__", lambda *a: "linear")
+    kind_wrap(L.SplitLinear, "__call__", lambda *a: "split")
+    kind_wrap(L.LayerNorm, "__call__", lambda self, *a: "ln32" if self.mode == "fp32" else "ln")
+    kind_wrap(A, "attention_matmul", lambda *a: "attn_mm")
+    kind_wrap(A, "sdpa", lambda *a: "sdpa")
+    for name in ("split_qkv", "split_q_kv", "split_heads", "merge_heads"):
+        kind_wrap(A, name, lambda *a: "heads")
+    kind_wrap(A, "expand_key_bias", lambda *a: "mask")
+
+    # ---- stages ------------------------------------------------------------------------------------------------
+    def method_wrap(obj, name, before=None, after=None):
+        fn = getattr(obj, name)
+
+        @functools.wraps(fn)
+        def inner(*args, **kwargs):
+            if before:
+                signpost(before())
+            out = fn(*args, **kwargs)
+            if after:
+                signpost(after())
+            return out
+
+        set_attr(obj, name, inner)
+
+    enc, dec = tt.encoder, tt.decoder
+    for cat, trunk in enc.trunks.items():
+        method_wrap(trunk, "pre", before=lambda c=cat: f"m:enc.{c}.pre")
+        method_wrap(trunk, "mix", before=lambda c=cat: f"m:enc.{c}.mix")
+        method_wrap(trunk, "pool", before=lambda c=cat: f"m:enc.{c}.head")
+    set_attr(enc, "static1", _Proxy(enc.static1, lambda: "m:enc.static"))
+    for cat in list(enc.small):
+        set_item(enc.small, cat, _Proxy(enc.small[cat], lambda c=cat: f"m:enc.{c}"))
+    set_attr(enc, "pad_tokens", _Proxy(enc.pad_tokens, lambda: "m:enc.tokens"))
+    for i, blk in enumerate(enc.blocks):
+        set_item(blk, "kv", _Proxy(blk["kv"], lambda i=i: f"m:enc.fusion{i}.attn"))
+        set_item(blk, "n2", _Proxy(blk["n2"], lambda i=i: f"m:enc.fusion{i}.mlp"))
+    set_attr(enc, "final_norm", _Proxy(enc.final_norm, lambda: "m:enc.final_ln"))
+    method_wrap(dec, "cross_kv", before=lambda: "m:dec.cross_kv")
+    method_wrap(dec, "solve", before=lambda: "m:dec.solve")
+
+    def next_eval():
+        state["k"] += 1
+        state["ln"] = {}
+        return f"m:dec.e{state['k']}.preproj"
+
+    method_wrap(dec, "evaluate", before=next_eval, after=lambda: f"m:dec.e{state['k']}.solver")
+    for i, blk in enumerate(dec.blocks):
+        def ln_label(i=i):
+            n = state["ln"][i] = state["ln"].get(i, 0) + 1
+            return f"m:dec.e{state['k']}.b{i}.{'attn' if n % 2 else 'mlp1'}"
+
+        set_item(blk, "ln", _Proxy(blk["ln"], ln_label))
+        set_item(blk, "n3", _Proxy(blk["n3"], lambda i=i: f"m:dec.e{state['k']}.b{i}.cross"))
+        set_item(blk, "n4", _Proxy(blk["n4"], lambda i=i: f"m:dec.e{state['k']}.b{i}.mlp2"))
+    set_attr(dec, "fin_ln", _Proxy(dec.fin_ln, lambda: f"m:dec.e{state['k']}.final"))
+    set_attr(tt, "turn", _Proxy(tt.turn, lambda: "m:turn"))
+    pack = M.pack_outputs
+
+    def pack_wrap(*args, **kwargs):
+        signpost("m:pack")
+        return pack(*args, **kwargs)
+
+    M.pack_outputs = pack_wrap
+    undo.append(lambda: setattr(M, "pack_outputs", pack))
+    # the mask expansion is attributed to its own stage (encoder fusion mask, decoder self-attention mask)
+    expand = A.expand_key_bias
+
+    def expand_wrap(*args, **kwargs):
+        signpost("m:mask")
+        return expand(*args, **kwargs)
+
+    A.expand_key_bias = expand_wrap
+    undo.append(lambda: setattr(A, "expand_key_bias", expand))
+
+    def remove() -> None:
+        for fn in reversed(undo):
+            fn()
+
+    return remove
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("--input", default=str(SAMPLE))
+    ap.add_argument("--dispatch", default=None, choices=["eth", "worker"])
+    ap.add_argument("--num-cqs", type=int, default=None, choices=[1, 2])
+    ap.add_argument("--replays", type=int, default=1, help="replays inside the trace section")
+    ap.add_argument("--no-eager", dest="eager", action="store_false")
+    ap.add_argument("--no-layer-signposts", dest="layers", action="store_false")
+    ap.add_argument("--json", default=None, help="write the run description (device, trace, timings) here")
+    a = ap.parse_args()
+    import ttnn
+
+    from tt_diffusion_planner.host import pipeline as hp
+    from tt_diffusion_planner.reference import config as C
+    from tt_diffusion_planner.reference.weights import find_weights_dir
+    from tt_diffusion_planner.tt import inputs as I
+    from tt_diffusion_planner.ttaw.io import load_named_arrays
+
+    wd = find_weights_dir()
+    t0 = time.perf_counter()
+    with DiffusionPlanner.from_pretrained(dispatch=a.dispatch, num_command_queues=a.num_cqs,
+                                          weights_dir=str(wd) if wd else None) as model:
+        tt, runner, dev = model.tt, model.runner, model.device
+        print("loaded in %.1f s:" % (time.perf_counter() - t0), json.dumps(model.device_info), flush=True)
+        raw = load_named_arrays(a.input, C.INPUT_SCHEMA)
+        inputs = I.plan_inputs(hp.prepare(raw, model.normalization.observation))
+        served = model(inputs=raw)                     # one served plan: upload + replay + readback
+        ttnn.synchronize_device(dev)
+        read_device_profiler(dev)                      # warm-up / capture / first plan out of the buffer
+        timings: Dict[str, float] = {}
+        if a.eager:
+            remove = install_signposts(tt) if a.layers else (lambda: None)
+            try:
+                t1 = time.perf_counter()
+                with signposted("eager"):
+                    eager = runner.run_eager("plan", inputs=inputs)
+                    ttnn.synchronize_device(dev)
+                timings["eager_ms"] = (time.perf_counter() - t1) * 1e3
+            finally:
+                remove()
+            read_device_profiler(dev)
+            final = np.asarray(eager["final_x0"], np.float32)
+            print("eager final_x0 finite:", bool(np.isfinite(final).all()), flush=True)
+        runner.upload(inputs)
+        ttnn.synchronize_device(dev)
+        read_device_profiler(dev)
+        t1 = time.perf_counter()
+        with signposted("trace"):
+            runner.replay("plan", n=a.replays)
+            ttnn.synchronize_device(dev)
+        timings["trace_ms"] = (time.perf_counter() - t1) * 1e3 / a.replays
+        read_device_profiler(dev)
+        out = runner.read("plan")
+        same = bool(np.array_equal(out["final_x0"], eager["final_x0"])) if a.eager else None
+        desc = {"device": model.device_info, "timings_ms": timings, "replays": a.replays,
+                "replay_equals_eager": same, "turn_command": int(served.turn_indicator["command"]),
+                "options": tt.build.options(), "trace": runner.describe()}
+        print("profile run:", json.dumps(desc, default=str), flush=True)
+        if a.json:
+            Path(a.json).write_text(json.dumps(desc, indent=1, default=str) + "\n")
+
+
+if __name__ == "__main__":
+    main()

code/scripts/ref_golden.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Goldens of the fp32 CPU reference (no device): per-module taps and final outputs per scene.
+
+    # research venv (torch + onnx; onnxruntime only for --ort), from the bundle root:
+    PYTHONPATH=code python code/scripts/ref_golden.py --threads 4 [--ort] \
+        [--full-dir ../../research/diffusion-planner/goldens] [--scenes kashiwanoha_dense straight_road ...]
+
+Scenes: the shipped samples (``code/tt_diffusion_planner/samples/*.npz``: small goldens -> ``tests/goldens``, and the
+stored ``/predict`` body of the reference -> ``samples/<stem>.reference.json``) and, when the workspace research
+directory is present, the seven ORT golden scenes of ``research/diffusion-planner/ort/golden_<scene>.npz`` and any
+public-dataset scene in ``research/diffusion-planner/public_data/*.npz`` (full goldens only). ``--ort`` also runs ONNX
+Runtime on every scene and writes ``<full-dir>/<scene>.ort_agreement.json`` (reference vs ORT on the deployed ONNX).
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+
+CODE = Path(__file__).resolve().parents[1]
+if str(CODE) not in sys.path:
+    sys.path.insert(0, str(CODE))
+
+from tt_diffusion_planner.reference import config as C  # noqa: E402
+from tt_diffusion_planner.reference.goldens import write_scene  # noqa: E402
+from tt_diffusion_planner.reference.pipeline import ReferencePlanner  # noqa: E402
+from tt_diffusion_planner.ttaw.metrics import pcc  # noqa: E402
+
+PKG = CODE / "tt_diffusion_planner"
+SAMPLES = PKG / "samples"
+SMALL_DIR = PKG / "tests" / "goldens"
+RESEARCH = CODE.parents[2] / "research" / "diffusion-planner"
+
+
+def public_ids(dataset: str, which: str):
+    """Instant ids of ``public_data/inputs/<dataset>``: ``all``, or ``core`` (the ids the public-data goldens keep
+    solver iterates for: ``public_data/goldens/<dataset>/core_ids.json``)."""
+    root = RESEARCH / "public_data"
+    ids = sorted(p.stem for p in (root / "inputs" / dataset).glob("*.npz"))
+    if which == "core":
+        core = root / "goldens" / dataset / "core_ids.json"
+        keep = set(json.loads(core.read_text()).get("core_ids_with_denoising_steps", [])) if core.is_file() else set()
+        ids = [i for i in ids if i in keep]
+    return ids
+
+
+def scene_sources(selected, public=None, public_which="core"):
+    """``{scene: (raw source, kind)}``: shipped samples first, then research ORT scenes, then (``--public``) the
+    public-data instants of one dataset (nuScenes-derived: CC BY-NC-SA, local goldens only)."""
+    out = {}
+    if public is None:
+        for p in sorted(SAMPLES.glob("*.npz")):
+            out[p.stem] = (p, "sample")
+        for p in sorted((RESEARCH / "ort").glob("golden_*.npz")):
+            out.setdefault(p.stem[len("golden_"):], (p, "research"))
+    else:
+        for i in public_ids(public, public_which):
+            out[f"public/{public}/{i}"] = (RESEARCH / "public_data" / "inputs" / public / f"{i}.npz", "public")
+    if selected:
+        missing = sorted(set(selected) - set(out))
+        if missing:
+            raise SystemExit(f"unknown scenes {missing}; have {sorted(out)}")
+        out = {k: v for k, v in out.items() if k in selected}
+    return out
+
+
+def load_raw(path: Path, kind: str):
+    with np.load(path, allow_pickle=False) as z:
+        if kind in ("research", "public"):  # dp_reference.py / nuscenes_dp.py layout: raw/<name>
+            return {k: np.asarray(z["raw/" + k], np.float32) for k in C.INPUT_NAMES}
+        return {k: np.asarray(z[k], np.float32) for k in C.INPUT_NAMES}
+
+
+def ort_agreement(weights_dir: Path, raw, g, threads: int):
+    from tt_diffusion_planner.reference.ort import OrtPlanner
+
+    o = OrtPlanner(weights_dir, threads=threads).run(raw)
+    rows = g["dec.rows"]
+    enc_rows = np.flatnonzero(g["host.token_valid"])
+    return {"encoding_pcc_valid": pcc(g["enc.encoding"][enc_rows], o.encoding[0][enc_rows]),
+            "encoding_max_abs": float(np.abs(g["enc.encoding"] - o.encoding[0]).max()),
+            "final_x0_pcc_valid": pcc(g["final_x0"][rows], o.final_x0[0][rows]),
+            "final_x0_max_abs_valid": float(np.abs(g["final_x0"][rows] - o.final_x0[0][rows]).max()),
+            "logit_max_abs": float(np.abs(g["turn.logit"] - o.logit[0]).max()),
+            "turn_logit_ref": g["turn.logit"].tolist(), "turn_logit_ort": o.logit[0].tolist()}
+
+
+def stored_ort_agreement(g, golden: Path):
+    """Reference vs a stored ORT golden in the ``dp_reference.py`` layout (``encoding``, ``final_x_normalized``,
+    ``logit_multi``): the public-data goldens of ``research/diffusion-planner/public_data/goldens/<dataset>``."""
+    with np.load(golden, allow_pickle=False) as z:
+        enc, fx, lg = z["encoding"][0], z["final_x_normalized"][0], z["logit_multi"][0]
+    rows = g["dec.rows"]
+    tok = np.flatnonzero(g["host.token_valid"])
+    return {"ort_golden": str(golden),
+            "encoding_pcc_valid": pcc(g["enc.encoding"][tok], enc[tok]),
+            "encoding_max_abs": float(np.abs(g["enc.encoding"][tok] - enc[tok]).max()),
+            "final_x0_pcc_valid": pcc(g["final_x0"][rows], fx[rows]),
+            "final_x0_max_abs_valid": float(np.abs(g["final_x0"][rows] - fx[rows]).max()),
+            "logit_max_abs": float(np.abs(g["turn.logit"] - lg).max())}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--weights-dir", default=None)
+    ap.add_argument("--full-dir", type=Path, default=RESEARCH / "goldens",
+                    help="where the large per-scene goldens go (never inside the bundle)")
+    ap.add_argument("--scenes", nargs="*", default=None)
+    ap.add_argument("--threads", type=int, default=4)
+    ap.add_argument("--ort", action="store_true", help="also compare with ONNX Runtime (research venv)")
+    ap.add_argument("--no-reference-json", action="store_true")
+    ap.add_argument("--public", default=None, help="a public_data/inputs/<dataset> (e.g. nuscenes): its instants "
+                    "instead of the samples / research scenes, as lite goldens")
+    ap.add_argument("--public-ids", default="core", choices=["core", "all"])
+    a = ap.parse_args(argv)
+    if a.full_dir.resolve().is_relative_to(CODE.parent.resolve()):
+        raise SystemExit("--full-dir must be outside the bundle: the full goldens are 10-25 MB per scene")
+    ref = ReferencePlanner(a.weights_dir, threads=a.threads)
+    report, seen = {}, {}
+    for scene, (path, kind) in scene_sources(a.scenes, a.public, a.public_ids).items():
+        t0 = time.perf_counter()
+        raw = load_raw(path, kind)
+        digest = hashlib.sha256(b"".join(raw[k].tobytes() for k in C.INPUT_NAMES)).hexdigest()
+        if digest in seen:  # e.g. research golden_straight == the shipped straight_road sample
+            report[scene] = {"same_inputs_as": seen[digest]}
+            print(scene, "skipped: same inputs as", seen[digest], flush=True)
+            continue
+        seen[digest] = scene
+        small = SMALL_DIR if kind == "sample" else None
+        r = write_scene(ref, raw, scene, a.full_dir, small, meta={"source": str(path), "kind": kind},
+                        lite=(kind == "public"))
+        entry = {"paths": r["paths"], "valid_counts": r["info"]["valid_counts"]}
+        if kind == "sample" and not a.no_reference_json:
+            body = ref(inputs=raw).to_dict()
+            body["timing_ms"] = {}
+            ref_path = SAMPLES / f"{scene}.reference.json"
+            ref_path.write_text(json.dumps(body, indent=1) + "\n")
+            entry["reference_json"] = str(ref_path)
+        stored = None
+        if kind == "public":
+            stored = RESEARCH / "public_data" / "goldens" / a.public / f"golden_{path.stem}.npz"
+        if stored is not None and stored.is_file():  # the dataset work already ran ORT on this instant
+            agree = stored_ort_agreement(r["goldens"], stored)
+            (a.full_dir / f"{scene}.ort_agreement.json").write_text(json.dumps(agree, indent=1) + "\n")
+            entry["ort"] = {k: v for k, v in agree.items() if k != "ort_golden"}
+        elif a.ort:
+            agree = ort_agreement(ref.weights.path, raw, r["goldens"], a.threads)
+            a.full_dir.mkdir(parents=True, exist_ok=True)
+            (a.full_dir / f"{scene}.ort_agreement.json").write_text(json.dumps(agree, indent=1) + "\n")
+            entry["ort"] = {k: v for k, v in agree.items() if not k.startswith("turn_logit")}
+        entry["seconds"] = round(time.perf_counter() - t0, 1)
+        report[scene] = entry
+        print(scene, json.dumps(entry), flush=True)
+    a.full_dir.mkdir(parents=True, exist_ok=True)
+    index = a.full_dir / "index.json"
+    merged = json.loads(index.read_text()) if index.is_file() else {}
+    merged.update(report)
+    index.write_text(json.dumps(merged, indent=1, sort_keys=True) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code/scripts/split_error.py

@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Where does the end-to-end error of a scene come from? (development tool; device, run under ``bin/devrun``)
+
+    bin/devrun -t 1200 -- python code/scripts/split_error.py --public scene-0103_kf14 --scenes straight_road
+
+For each scene the ego / neighbour displacement vs the fp32 CPU reference of:
+
+- ``device``: the full device plan;
+- ``enc_only``: the device encoding (``encoder_taps``) + the CPU fp32 decoder and solver (encoder error alone);
+- ``dec_only``: the CPU encoding + the device decoder (``decode_once`` replays) driven by the host solver (decoder
+  error alone, including its compounding over the 11 evaluations).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+
+HERE = Path(__file__).resolve()
+sys.path.insert(0, str(HERE.parents[1]))
+
+from tt_diffusion_planner.host import pipeline as hp  # noqa: E402
+from tt_diffusion_planner.host.solver import apply_prefix_constraint, dpm_solver_sample  # noqa: E402
+from tt_diffusion_planner.reference import config as C  # noqa: E402
+
+RES = HERE.parents[4] / "research" / "diffusion-planner"
+
+
+def load_raw(scene: str, public: bool):
+    if public:
+        with np.load(RES / "public_data" / "inputs" / "nuscenes" / f"{scene}.npz", allow_pickle=False) as z:
+            return {k: np.array(z[f"raw/{k}"]) for k in C.INPUT_NAMES}
+    with np.load(RES / "goldens" / f"{scene}.npz", allow_pickle=False) as z:
+        return {k: np.array(z[f"in.{k}"]) for k in C.INPUT_NAMES}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--public", nargs="*", default=[])
+    ap.add_argument("--scenes", nargs="*", default=[])
+    ap.add_argument("--json", default=None)
+    for opt in ("ln-fp32", "hidden-fp32", "split", "attn-fp32-acc", "attn-matmul"):
+        ap.add_argument(f"--{opt}", default=None, help="module globs (comma-separated); default: the knob")
+    args = ap.parse_args()
+    from tt_diffusion_planner.tt.config import globs
+
+    opts = {k: globs(getattr(args, k)) for k in ("ln_fp32", "hidden_fp32", "split", "attn_fp32_acc", "attn_matmul")
+            if getattr(args, k) is not None}
+    import torch
+
+    torch.set_num_threads(4)
+    from tt_diffusion_planner.device import close_device, open_device
+    from tt_diffusion_planner.reference.model import Decoder, Encoder, torch_params
+    from tt_diffusion_planner.reference.weights import find_weights_dir, load_weights
+    from tt_diffusion_planner.tt.model import TtDiffusionPlanner
+
+    w = load_weights(find_weights_dir())
+    params = {k: v[3] for k, v in hp.RUNTIME_PARAMS.items()}
+    P = torch_params(w.params)
+    enc_ref, dec_ref = Encoder(P), Decoder(P)
+    dev = open_device(allow_fallback=False)
+    report = {}
+    try:
+        tt = TtDiffusionPlanner(dev, w, debug=True, **opts)
+        report["options"] = tt.build.options()
+        tt.capture()
+        for scene, public in [(s, True) for s in args.public] + [(s, False) for s in args.scenes]:
+            prep = hp.prepare(load_raw(scene, public), w.normalization.observation)
+            cs = prep.decoder.current_states
+
+            def solve(model_fn):
+                res = dpm_solver_sample(prep.x_T, model_fn, lambda x: apply_prefix_constraint(x, cs))
+                return res.final_x
+
+            def cpu_plan(encoding):
+                kv = dec_ref.cross_kv(torch.from_numpy(np.asarray(encoding, np.float32)))
+                with torch.no_grad():
+                    return solve(lambda x, t: dec_ref.forward(x, t, kv, prep.decoder.agent_valid).numpy())
+
+            def out(final_x0):
+                o = hp.make_output(final_x0, np.zeros(5, np.float32), prep, w.normalization, params)
+                return o.poses[:, :2], o.predicted_agents[..., :2]
+
+            with torch.no_grad():
+                enc = enc_ref.forward(prep.features).numpy()
+            ref_ego, ref_nb = out(cpu_plan(enc))
+            dev_enc = tt.encoder_taps(prep)["enc.encoding"]
+            cases = {
+                "device": tt.forward(prep)["final_x0"],
+                "enc_only": cpu_plan(dev_enc),
+                "dec_only": solve(lambda x, t: _decode(tt, prep, x, t, enc)),
+            }
+            res = {}
+            for name, fx in cases.items():
+                ego, nb = out(fx)
+                d = np.hypot(*(ego - ref_ego).T)
+                r = {"ego_max_m": round(float(d.max()), 4), "ego_mean_m": round(float(d.mean()), 4)}
+                if nb.shape[0]:
+                    per_agent = np.hypot(*(nb - ref_nb).transpose(2, 0, 1)).max(1)
+                    r["nb_median_max_m"] = round(float(np.median(per_agent)), 4)
+                res[name] = r
+            res["encoding_pcc"] = float(np.corrcoef(dev_enc[prep.features.token_valid].ravel(),
+                                                    enc[prep.features.token_valid].ravel())[0, 1])
+            report[scene] = res
+            print(scene, json.dumps(res), flush=True)
+        tt.release()
+    finally:
+        close_device(dev)
+    if args.json:
+        Path(args.json).write_text(json.dumps(report, indent=1) + "\n")
+    return 0
+
+
+def _decode(tt, prep, x, t, enc):
+    out = tt.decode_once(prep, x, float(t), encoding=enc)
+    out[:, 0] = 0.0     # the t = 0 slot (masked on the device) is overwritten by the prefix constraint anyway
+    return out
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code/tt_diffusion_planner/__init__.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Diffusion Planner v5.0 (Autoware diffusion_planner) on a Tenstorrent Blackhole p150 (tt-nn), packaged as
+changh95/diffusion-planner-p150.
+
+Python API (see PYTHON.md)::
+
+    from tt_diffusion_planner import DiffusionPlanner
+
+    with DiffusionPlanner.from_pretrained(device_id=0) as model:
+        out = model(inputs="code/tt_diffusion_planner/samples/kashiwanoha_dense.npz")
+
+Importing the package has no side effects (no device, no ttnn / torch import, no network); the names below load
+on first use. The HTTP server is ``tt_diffusion_planner.server.app:app`` (SERVING.md). ``tt_diffusion_planner.ttaw``
+is the vendored shared package of the Autoware ports (``ttaw/VENDORED.json`` records its version and file hashes;
+never edit it here). ``tt_diffusion_planner.reference`` is the fp32 CPU reference (torch) and
+``tt_diffusion_planner.host`` the node's pre- and post-processing (numpy).
+"""
+
+__version__ = "0.1.0"
+__all__ = ["DiffusionPlanner", "Output", "open_device", "load_inputs", "INPUT_SCHEMA", "__version__"]
+
+_LAZY = {
+    "DiffusionPlanner": (".api", "DiffusionPlanner"),
+    "Output": (".api", "Output"),
+    "open_device": (".device", "open_device"),
+    "load_inputs": (".io", "load_inputs"),
+    "INPUT_SCHEMA": (".reference.config", "INPUT_SCHEMA"),
+}
+
+
+def __getattr__(name):
+    if name in _LAZY:
+        import importlib
+
+        module, attr = _LAZY[name]
+        return getattr(importlib.import_module(module, __name__), attr)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(list(globals()) + __all__)

code/tt_diffusion_planner/api.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Python API: Diffusion Planner v5.0 (Autoware diffusion_planner) on one Tenstorrent Blackhole p150.
+
+    from tt_diffusion_planner import DiffusionPlanner
+
+    with DiffusionPlanner.from_pretrained(device_id=0) as model:  # weights -> HF cache, device open, traces captured
+        out = model(inputs="code/tt_diffusion_planner/samples/kashiwanoha_dense.npz")
+    print(out.to_dict())  # the same JSON as POST /predict
+
+The contract shared by every bundle of the Autoware collection is the vendored ``ttaw.api_base.ModelBase``
+(BUNDLE_CONVENTIONS.md section 8): ``from_pretrained`` resolves the pinned weights before it claims the chip, opens it
+(ETH dispatch, 12x10), builds the graph and captures every trace variant in ``warmup_variants``, so the first call is
+as fast as the later ones; calls are serialised by a lock (one chip, batch 1) and fill ``timing_ms``; ``close()`` is
+idempotent, also runs at interpreter exit, and closes the chip only if the model opened it. The HTTP server
+(``tt_diffusion_planner.server.app``) calls this class, so ``/predict`` and ``model(...)`` agree bit for bit.
+
+Input: ``inputs=`` holds the 15 raw tensors of the node's ``DiffusionPlannerCore::create_input_data`` (ego frame,
+before normalization, batch 1; ``INPUT_SCHEMA``). Converting ROS messages and the Lanelet2 map into them, and the
+node's temporal state (agent buffers, ego history, RTC prefix of ``sampled_trajectories``), stay with the client.
+The hooks delegate to ``tt_diffusion_planner.host`` (the node's pre- and post-processing, numpy) around
+``tt_diffusion_planner.tt`` (the ttnn graph: encoder + 11 DiT evaluations with the DPM-Solver++(2M) update + turn head,
+run by a ``ttaw.trace.TraceRunner``). Importing this module has no side effects (ttnn / torch only inside hooks).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from . import io as tio
+from .device import DEVICE_DEFAULTS
+from .host import pipeline as hp
+from .reference import config as C
+from .ttaw.api_base import ModelBase
+from .ttaw.outputs import Trajectory
+
+__all__ = ["DiffusionPlanner", "Output"]
+
+# The result class of this model (ttaw.outputs: Detections3D, Detections2D, Segmentation3D, Mask2D, Trajectory).
+Output = Trajectory
+
+
+class DiffusionPlanner(ModelBase):
+    """Diffusion Planner v5.0 (Autoware diffusion_planner) on one Blackhole p150. Create it with
+    :meth:`from_pretrained`."""
+
+    MODEL_NAME = "diffusion-planner-p150"
+    ENV_PREFIX = "DIFFUSION_PLANNER"  # prefix of the environment knobs (SERVING.md section 3.4)
+    DEFAULT_REPO = "AutowareFoundation/diffusion_planner"
+    DEFAULT_TAG = "v5.0"  # the Autoware ansible artifacts pin; the node loads only major version 5
+    # the commit DEFAULT_TAG points to (pinned: tags can move)
+    DEFAULT_REVISION = "423efde67f5414734da43a7ad856c17ceb8b51aa"
+    ALLOW_PATTERNS = ["diffusion_planner_encoder.onnx", "diffusion_planner_decoder.onnx",
+                      "diffusion_planner_turn_indicator.onnx", "diffusion_planner.param.json"]
+    VARIANTS = ["default"]  # load-time: the multi-step graph with dpm_solver_steps = 10
+    DEFAULT_VARIANT = "default"
+    INPUT_KIND = "planner"  # lidar | camera | multicam | lidar+multicam | planner
+    CAMERA_ORDER = ()
+    POINT_FIELDS = tio.DEFAULT_POINT_FIELDS  # () : no point cloud
+    # turn-indicator logit order (dimensions.hpp:74-79); the published command is the index for 0..3
+    LABELS = C.TURN_INDICATOR_LABELS
+    # Per-request knobs: name -> (type, min, max, default); host-side post-processing only (the node's YAML defaults).
+    RUNTIME_PARAMS = hp.RUNTIME_PARAMS
+    EXTRA_INPUTS = ()
+    # the ONNX-named raw tensors (name -> (shape, dtype)), decoded and checked on every call (API and server alike)
+    INPUT_SCHEMA = C.INPUT_SCHEMA
+    DEVICE_DEFAULTS = DEVICE_DEFAULTS  # validated open parameters (device.py)
+
+    # ---- port-specific hooks (called by ModelBase; keep host work out of _forward) ---------------------------
+    def _build(self) -> None:
+        """Weights (the three ONNX files + param JSON, read as data by ``reference.weights``) -> the ttnn graph of
+        ``tt_diffusion_planner.tt`` registered as the variants of a ``ttaw.trace.TraceRunner`` (persistent inputs,
+        RT-dev solver / adaLN tables and states allocated here, before any capture). No capture here."""
+        from .reference.weights import load_weights
+        from .tt.model import TtDiffusionPlanner
+
+        unknown = sorted(set(self.compile_params) - {"precision"})
+        if unknown:
+            raise TypeError(f"unknown compile parameter(s) {unknown}; allowed: precision (extra precision rules, "
+                            "e.g. 'dec.*=HiFi2+fp32'); the LN_FP32 / HIDDEN_FP32 options are DIFFUSION_PLANNER_* knobs")
+        self.planner_weights = load_weights(self.weights_path)
+        self.normalization = self.planner_weights.normalization
+        self.tt = TtDiffusionPlanner(self.device, self.planner_weights, precision=self.compile_params.get("precision"))
+        self.runner = self.tt.runner
+
+    def _warm_one(self, variant: Dict[str, Any]) -> None:
+        """``TraceRunner.capture`` warms every pending variant eagerly (kernel JIT, program cache) before any capture,
+        then captures with program-cache misses forbidden; idempotent."""
+        self.runner.capture()
+
+    def _prepare(self, points: Any = None, inputs: Any = None, **other: Any) -> hp.Prepared:
+        """The node's host pre-processing (``host.prepare``): normalization (all-zero rows kept), speed masks, the
+        encoder's host features, the decoder masks and the solver's initial state."""
+        given = sorted(k for k, v in {"points": points, **other}.items() if v is not None)
+        if given:
+            raise tio.InputError(f"this model takes only `inputs` (the planner tensors), not {given}")
+        if inputs is None:
+            raise tio.InputError("this model needs `inputs`: the 15 planner tensors of INPUT_SCHEMA")
+        return hp.prepare(inputs, self.normalization.observation)
+
+    def _forward(self, prepared: hp.Prepared) -> Dict[str, Any]:
+        """Upload the host features into the persistent device inputs, replay the plan's trace(s) and read back
+        ``final_x0`` (normalised [321, 81, 4]), the turn logits and, when asked, the solver iterates."""
+        return self.tt.forward(prepared)
+
+    def _postprocess(self, raw: Dict[str, Any], prepared: hp.Prepared, params: Dict[str, Any]) -> Output:
+        """The node's post-processing (``host.make_output``): denormalisation, trajectory velocity / force-stop /
+        acceleration, predicted neighbour paths, turn-indicator decision."""
+        return hp.make_output(raw["final_x0"], raw["logit"], prepared, self.normalization, params,
+                              model=self.MODEL_NAME, denoising_steps=raw.get("denoising_steps"))
+
+    def _release(self) -> None:
+        """Release the traces and persistent device tensors; also called when ``from_pretrained`` fails half-way."""
+        runner = getattr(self, "runner", None)
+        if runner is not None:
+            runner.release()
+
+    def extra_info(self) -> Dict[str, Any]:
+        """Additions to ``model.info`` and ``/info``: the trace variants, CQs and persistent tensors of the runner."""
+        runner = getattr(self, "runner", None)
+        info: Dict[str, Any] = {"dpm_solver_steps": C.DPM_SOLVER_STEPS, "input_names": list(C.INPUT_NAMES)}
+        tt = getattr(self, "tt", None)
+        if tt is not None:
+            info.update(tt.describe())
+        elif runner is not None:
+            info["trace"] = runner.describe()
+        return info

code/tt_diffusion_planner/calib/README.md

@@ -0,0 +1,6 @@
+# Calibration presets
+
+None: the planner takes no calibration. Its inputs are tensors in the ego (`base_link`) frame that the client builds
+from ROS messages and the Lanelet2 map (README "Quickstart", SERVING.md 3.1), so there is no camera or LiDAR extrinsic to
+send. The directory exists because the shared server of the Autoware ports lists `*.json` presets from it in `/info`
+(`calibration_presets`, empty here); a request that carries `calibration` is refused (HTTP 400).

code/tt_diffusion_planner/device.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Opening the Blackhole p150 the way every published number of diffusion-planner-p150 was measured.
+
+The implementation is the vendored ``ttaw.device`` (C01): dispatch on the idle ETH cores
+(``ttnn.DispatchCoreConfig(ttnn.DispatchCoreType.ETH)``), which gives a 12x10 = 120-core compute grid on a p150
+(11x10 with WORKER dispatch, the A/B switch). ETH dispatch needs ``patches/tt-metal-eth-dispatch.patch`` on tt-metal
+44d6650 (the container image is built from a patched tree); if the ETH open fails, a ``RuntimeWarning`` is issued and
+WORKER dispatch is used, unless ``allow_fallback=False``. Never hard-code the grid: use :func:`compute_grid` or
+``device.compute_with_storage_grid_size()``.
+
+This module binds it to the validated open parameters of this port, :data:`DEVICE_DEFAULTS` (the model class uses
+the same dict), which the ``DIFFUSION_PLANNER_DISPATCH``, ``_NUM_CQS``, ``_L1_SMALL``, ``_TRACE_REGION`` and
+``_WORKER_L1_SIZE`` variables and ``TT_DEVICE_ID`` override per process (SERVING.md section 3.4). Importing it has
+no side effects (``ttnn`` is imported when a device is opened).
+"""
+from __future__ import annotations
+
+import contextlib
+import dataclasses
+from typing import Any, Dict, Iterator, Optional
+
+from .ttaw.device import DeviceConfig, close_device, compute_grid, core_grid, describe_device, full_core_range_set
+
+__all__ = ["ENV_PREFIX", "DEVICE_DEFAULTS", "DeviceConfig", "device_config", "open_device", "device_session",
+           "close_device", "describe_device", "compute_grid", "core_grid", "full_core_range_set"]
+
+ENV_PREFIX = "DIFFUSION_PLANNER"
+
+# Validated device-open parameters of this port (fill per model; the card's numbers are measured with them).
+DEVICE_DEFAULTS: Dict[str, Any] = {
+    "num_command_queues": 1,  # 1, or 2 when the input upload (CQ1) overlaps the trace (CQ0)
+    "l1_small_size": 32768,  # L1_SMALL bytes per core (conv / pool config tensors)
+    # DRAM bytes for the traces: measured 74.6 MB for the plan, 96.9 MB with the tests' debug variants (PORT_LOG 5.3)
+    "trace_region_size": 192 << 20,
+}
+
+
+def device_config(**overrides: Any) -> DeviceConfig:
+    """:data:`DEVICE_DEFAULTS` < the ``DIFFUSION_PLANNER_*`` / ``TT_DEVICE_ID`` environment < explicit non-None
+    ``overrides``
+    (``device_id``, ``dispatch``, ``num_command_queues``, ``l1_small_size``, ``trace_region_size``,
+    ``worker_l1_size``, ``allow_fallback``): the same resolution as ``DiffusionPlanner.from_pretrained``."""
+    config = DeviceConfig.from_env(ENV_PREFIX, **DEVICE_DEFAULTS)
+    return dataclasses.replace(config, **{k: v for k, v in overrides.items() if v is not None})
+
+
+def open_device(device_id: Optional[int] = None, *, dispatch: Optional[str] = None, **overrides: Any):
+    """Open one chip like the published numbers: ETH dispatch (``dispatch="worker"`` is the A/B opt-in) and this
+    port's sizes. Close it with :func:`close_device`, or use :func:`device_session`."""
+    return device_config(device_id=device_id, dispatch=dispatch, **overrides).open()
+
+
+@contextlib.contextmanager
+def device_session(device_id: Optional[int] = None, **overrides: Any) -> Iterator[Any]:
+    """``with device_session() as dev:`` opens with :func:`open_device` and always closes, also when the body
+    raises."""
+    device = open_device(device_id, **overrides)
+    try:
+        yield device
+    finally:
+        close_device(device)

code/tt_diffusion_planner/host/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Host pre- and post-processing of the Autoware Diffusion Planner (numpy only, no ttnn, no torch).
+
+Exact ports of the node's host code (autoware_universe @ 9ceaccf ``planning/autoware_diffusion_planner``) and of
+the in-graph pre-processing of the encoder that the TT port moves to the host (PLAN.md section 2.12 "Host fallbacks":
+normalization, position features, masks, post-processing):
+
+- :mod:`.normalize`   input normalization that keeps all-zero rows at zero, speed-limit masks
+  (``preprocessing_utils.cpp:34-84``, ``inference/utils.hpp:112-123``);
+- :mod:`.features`    what the encoder graph computes before its first matmul: history truncation, validity masks,
+  the neighbour velocity zeroing and valid-step flag, lane attributes and speed selection, polygon / line-string
+  deltas, the 14-dim position features (ONNX ``atan2`` decomposition and the polygon / line-string pseudo-heading
+  quirk), the fusion key mask; decoder agent mask and current states (SPEC 3.8, 4.3);
+- :mod:`.solver`      DPM-Solver++(2M) with denoise-to-zero, its float32 scalar schedule computed with the C library
+  like ``dpm_solver.cpp``, the prefix constraint (``multi_step_inference.cpp:300-340``);
+- :mod:`.postprocess` denormalization, poses with Eigen's quaternion of the unnormalised rotation, the trajectory
+  velocity / force-stop / acceleration rules, predicted neighbour paths, the turn-indicator decision
+  (``postprocessing_utils.cpp``, ``turn_indicator_manager.cpp``);
+- :mod:`.pipeline`    ``prepare(raw) -> Prepared`` and ``make_output(...) -> Trajectory``: the two halves the Python
+  API, the HTTP server and the CPU reference share around the network.
+
+Importing this package has no side effects.
+"""
+from .normalize import normalize_inputs, speed_masks  # noqa: F401
+from .pipeline import Prepared, make_output, prepare  # noqa: F401
+
+__all__ = ["normalize_inputs", "speed_masks", "Prepared", "prepare", "make_output"]

code/tt_diffusion_planner/host/features.py

@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The encoder's in-graph pre-processing and the decoder's masks, computed on the host from normalised inputs.
+
+Everything the v5.0 encoder graph does before its first matmul is tensor plumbing (slices, ``!= 0`` tests, OneHot,
+``Atan`` with quadrant ``Where`` s): the TT port computes it here once per plan and uploads the results (PLAN.md 2.12;
+SPEC 3.8, 8.2.6: padded lanes produce ``0/0`` headings that only a ``Where`` discards, which an arithmetic device
+``where`` would propagate). The CPU reference consumes the same arrays, so the reference-vs-ONNX Runtime test also
+proves this module against the graph (``/encoder/*/Where*``, ``/encoder/Concat_4`` / ``Concat_5`` taps).
+
+Semantics (T4M ``model/module/encoder.py``; checked against the exported graph):
+
+- ego: only the 6 OLDEST history rows are kept (rows 6..30 zeroed); the ego token is always valid and its position
+  feature is the last row of the truncated history, i.e. zeros;
+- neighbours: rows 0..24 zeroed; a step is valid if any of dims 0..7 is non-zero, an agent if any step is; the type
+  one-hot (dims 8..10) and the position feature come from the last step; velocities (dims 4, 5) are zeroed AFTER the
+  validity test and a valid-step flag is appended (9 channels); invalid agents are zeroed;
+- static objects: valid if any of the 10 values is non-zero (always zeros in Autoware, so never valid);
+- lanes / route: dims 0..7 per point (zeroed for invalid lanes), attributes = dims 8..32 of point 0, speed limit and
+  its mask, position feature = point 10 with heading ``atan2(dy, dx)`` exported as ``Atan(dy / dx)`` plus quadrant
+  ``Where`` s;
+- polygons / line strings: ``[x, y, type one-hot..., dx, dy]`` with dx, dy = next point minus point (0 for the last
+  point), valid if any of the first FOUR columns is non-zero, position feature = point 20 / 10 with the NON-geometric
+  heading ``atan2(col3, col2)``: atan2(dx, is_intersection_area) for polygons, atan2(is_road_border, is_stop_line)
+  for line strings (SPEC 3.8: port the quirk exactly);
+- goal / ego shape / turn indicators: always valid; positions (goal) and (0, 0, 1, 0); turn indicators drop the
+  current report (``[:, :-1]``, 30 values); the turn token reuses the ego-shape class id 8;
+- fusion key mask: invalid tokens are masked with -inf, the ego key is forced valid (``encoder.py:833``);
+- decoder: a neighbour is a valid attention key if its current state (``neighbor_agents_past[:, 30, :4]``) is not
+  all zero; current states = (ego_current_state[:4], neighbour current states) for the prefix constraint.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Mapping
+
+import numpy as np
+
+from ..reference import config as C
+
+__all__ = ["EncoderFeatures", "DecoderMasks", "encoder_features", "decoder_masks", "atan2_onnx", "line_features"]
+
+PI_F32 = np.float32(3.1415927)  # the ONNX constant of the exported atan2 (``/encoder/lane_encoder/Constant_13``)
+
+
+def atan2_onnx(y: np.ndarray, x: np.ndarray) -> np.ndarray:
+    """``torch.atan2`` as exported to ONNX opset 20: ``a = Atan(y / x)``; ``Where(x < 0, Where(y > 0, a + pi, a - pi),
+    a)`` (float32). Differs from IEEE atan2 only on signed zeros (x = -0, y = 0 -> -pi) and 0/0 (NaN, masked later)."""
+    y = np.asarray(y, np.float32)
+    x = np.asarray(x, np.float32)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        a = np.arctan((y / x).astype(np.float32)).astype(np.float32)
+    alt = np.where(y > 0, a + PI_F32, a - PI_F32).astype(np.float32)
+    return np.where(x < 0, alt, a).astype(np.float32)
+
+
+def _heading_pos(xy: np.ndarray, y_col: np.ndarray, x_col: np.ndarray) -> np.ndarray:
+    """``[x, y, cos(h), sin(h)]`` with ``h = atan2_onnx(y_col, x_col)`` (float32)."""
+    h = atan2_onnx(y_col, x_col)
+    with np.errstate(invalid="ignore"):
+        return np.stack([xy[..., 0], xy[..., 1], np.cos(h), np.sin(h)], axis=-1).astype(np.float32)
+
+
+def _onehot_pos(pos4: np.ndarray, cls: int) -> np.ndarray:
+    """Append the 10-way class one-hot (``add_class_type``)."""
+    onehot = np.zeros(pos4.shape[:-1] + (C.POS_CLASS_NUM,), np.float32)
+    onehot[..., cls] = 1.0
+    return np.concatenate([pos4.astype(np.float32), onehot], axis=-1)
+
+
+def line_features(x: np.ndarray) -> np.ndarray:
+    """``LineEncoder``: ``[points..., dx, dy]`` with dx / dy = next point minus point (0 at the last point)."""
+    x = np.asarray(x, np.float32)
+    d = np.zeros(x.shape[:-1] + (2,), np.float32)
+    d[..., :-1, 0] = x[..., 1:, 0] - x[..., :-1, 0]
+    d[..., :-1, 1] = x[..., 1:, 1] - x[..., :-1, 1]
+    return np.concatenate([x, d], axis=-1)
+
+
+@dataclass
+class EncoderFeatures:
+    """Host-side inputs of the encoder network (batch 1, no batch dim). ``valid[cat]`` is True for valid entities;
+    ``token_valid`` (564) gates the positional embedding, ``key_valid`` (564) is the fusion key mask (ego forced
+    valid); ``pos`` (564 x 14) are the position features, with invalid rows set to 0 (the graph's NaN rows there are
+    discarded by a ``Where``)."""
+
+    ego: np.ndarray            # [31, 4]   truncated ego history
+    neighbor: np.ndarray       # [320, 31, 9]
+    neighbor_type: np.ndarray  # [320, 3]
+    static: np.ndarray         # [5, 10]
+    lane: np.ndarray           # [140, 20, 8]
+    lane_attr: np.ndarray      # [140, 25]
+    lane_speed: np.ndarray     # [140, 1]
+    lane_has_speed: np.ndarray  # [140, 1] bool
+    route: np.ndarray          # [25, 20, 8]
+    route_attr: np.ndarray     # [25, 25]
+    route_speed: np.ndarray    # [25, 1]
+    route_has_speed: np.ndarray  # [25, 1] bool
+    polygon: np.ndarray        # [10, 40, 5]
+    line_string: np.ndarray    # [60, 20, 6]
+    goal: np.ndarray           # [4]
+    ego_shape: np.ndarray      # [3]
+    turn: np.ndarray           # [30]
+    valid: Dict[str, np.ndarray]
+    token_valid: np.ndarray    # [564] bool
+    key_valid: np.ndarray      # [564] bool
+    pos: np.ndarray            # [564, 14]
+
+    def counts(self) -> Dict[str, int]:
+        return {k: int(v.sum()) for k, v in self.valid.items()}
+
+
+@dataclass
+class DecoderMasks:
+    agent_valid: np.ndarray     # [321] bool: ego + neighbours with a non-zero current state (self-attention keys)
+    current_states: np.ndarray  # [321, 4] normalised (prefix constraint)
+
+
+def _any_nonzero(a: np.ndarray, axes) -> np.ndarray:
+    return np.any(a != 0, axis=axes)
+
+
+def encoder_features(norm: Mapping[str, np.ndarray], masks: Mapping[str, np.ndarray]) -> EncoderFeatures:
+    """From the normalised inputs (``normalize_inputs``) and the speed masks (``speed_masks``), batch 1."""
+    f32 = lambda k: np.asarray(norm[k], np.float32)[0]  # noqa: E731  (drop the batch dim)
+    # ego: keep the 6 oldest rows (encoder.py:170-175); the token is always valid, its position row is all zero
+    ego = np.zeros((C.INPUT_T + 1, C.POSE_DIM), np.float32)
+    ego[C.EGO_HISTORY_KEEP] = f32("ego_agent_past")[C.EGO_HISTORY_KEEP]
+    pos = {"ego": _onehot_pos(ego[-1:], C.POS_CLASS["ego"])}
+
+    # neighbours: keep the 6 newest rows (encoder.py:176-181, 441-451)
+    nb_raw = f32("neighbor_agents_past")
+    nb = np.zeros_like(nb_raw)
+    nb[:, C.NEIGHBOR_HISTORY_KEEP] = nb_raw[:, C.NEIGHBOR_HISTORY_KEEP]
+    nb_type = nb[:, -1, 8:11].copy()
+    x8 = nb[..., :8]
+    step_valid = _any_nonzero(x8, -1)                      # [320, 31]
+    nb_valid = step_valid.any(axis=-1)                     # [320]
+    feat = np.concatenate([x8, step_valid[..., None].astype(np.float32)], axis=-1)
+    feat[..., 4:6] = 0.0                                   # velocities zeroed after the validity test
+    feat[~nb_valid] = 0.0
+    pos["neighbor"] = _onehot_pos(x8[:, -1, :4], C.POS_CLASS["neighbor"])
+
+    static = f32("static_objects")
+    st_valid = _any_nonzero(static[..., :10], -1)
+    static = np.where(st_valid[:, None], static, 0.0).astype(np.float32)
+    pos["static"] = _onehot_pos(f32("static_objects")[:, :4], C.POS_CLASS["static"])
+
+    def lanes(key: str, speed_key: str, mask_key: str, cat: str):
+        x = f32(key)
+        attr = x[:, 0, C.LANE_FEATURE_DIM:].copy()
+        x8 = x[..., :C.LANE_FEATURE_DIM]
+        valid = _any_nonzero(x8, (-1, -2))
+        p = x8[:, C.LANE_POS_INDEX, :4]
+        pos[cat] = _onehot_pos(_heading_pos(p, p[:, 3], p[:, 2]), C.POS_CLASS[cat])
+        x8 = np.where(valid[:, None, None], x8, 0.0).astype(np.float32)
+        speed = f32(speed_key).reshape(-1, 1)
+        has = np.asarray(masks[mask_key])[0].reshape(-1, 1).astype(bool)
+        return x8, attr, speed, has, valid
+
+    lane, lane_attr, lane_speed, lane_has, lane_valid = lanes("lanes", "lanes_speed_limit",
+                                                              "lanes_has_speed_limit", "lane")
+    route, route_attr, route_speed, route_has, route_valid = lanes("route_lanes", "route_lanes_speed_limit",
+                                                                   "route_lanes_has_speed_limit", "route")
+
+    def lines(key: str, cat: str, pos_index: int):
+        x = line_features(f32(key))
+        valid = _any_nonzero(x[..., :4], (-1, -2))
+        p = x[:, pos_index, :4]
+        pos[cat] = _onehot_pos(_heading_pos(p, p[:, 3], p[:, 2]), C.POS_CLASS[cat])
+        return np.where(valid[:, None, None], x, 0.0).astype(np.float32), valid
+
+    polygon, poly_valid = lines("polygons", "polygon", C.POLYGON_POS_INDEX)
+    line_string, ls_valid = lines("line_strings", "line_string", C.LINE_STRING_POS_INDEX)
+
+    goal = f32("goal_pose").reshape(-1)
+    pos["goal"] = _onehot_pos(goal[None], C.POS_CLASS["goal"])
+    unit = np.array([[0.0, 0.0, 1.0, 0.0]], np.float32)
+    pos["ego_shape"] = _onehot_pos(unit, C.POS_CLASS["ego_shape"])
+    pos["turn"] = _onehot_pos(unit, C.POS_CLASS["turn"])
+    turn = np.asarray(norm["turn_indicators"], np.float32)[0, :C.TURN_INDICATOR_HISTORY].copy()
+
+    one = np.ones(1, bool)
+    valid = {"ego": one, "neighbor": nb_valid, "static": st_valid, "lane": lane_valid, "route": route_valid,
+             "polygon": poly_valid, "line_string": ls_valid, "goal": one, "ego_shape": one.copy(), "turn": one.copy()}
+    token_valid = np.concatenate([valid[name] for name, _ in C.TOKEN_LAYOUT])
+    key_valid = token_valid.copy()
+    key_valid[0] = True
+    pos_all = np.concatenate([pos[name] for name, _ in C.TOKEN_LAYOUT], axis=0).astype(np.float32)
+    pos_all[~token_valid] = 0.0
+    return EncoderFeatures(ego, feat.astype(np.float32), nb_type, static, lane, lane_attr, lane_speed, lane_has,
+                           route, route_attr, route_speed, route_has, polygon, line_string, goal,
+                           f32("ego_shape").reshape(-1).copy(), turn, valid, token_valid, key_valid, pos_all)
+
+
+def decoder_masks(norm: Mapping[str, np.ndarray]) -> DecoderMasks:
+    """Agent key mask of the DiT self-attention (``dit.py:155-156``; the ego is always valid) and the current states
+    of the prefix constraint (``multi_step_inference.cpp:300-325``), from the normalised inputs."""
+    nb_now = np.asarray(norm["neighbor_agents_past"], np.float32)[0, :, C.INPUT_T, :C.POSE_DIM]
+    agent_valid = np.concatenate([np.ones(1, bool), np.any(nb_now != 0, axis=-1)])
+    cs = np.zeros((C.MAX_NUM_AGENTS, C.POSE_DIM), np.float32)
+    cs[0] = np.asarray(norm["ego_current_state"], np.float32)[0, :C.POSE_DIM]
+    cs[1:] = nb_now
+    return DecoderMasks(agent_valid, cs)

code/tt_diffusion_planner/host/normalize.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Input normalization of the Autoware node (``preprocessing_utils.cpp:34-84``) and the speed-limit masks.
+
+The rule cannot be folded into the first-layer weights (SPEC 9.1, PLAN 2.12): each row of the last dimension is
+normalised as ``(v - mean) / std`` in float32 unless every value of the row satisfies ``|v| < FLT_EPSILON``, in which
+case the row is left untouched (padding stays zero while ``x`` has mean 10 m). ``ego_shape``,
+``sampled_trajectories``, ``turn_indicators`` and ``delay`` are never normalised.
+"""
+from __future__ import annotations
+
+from typing import Dict, Mapping, Tuple
+
+import numpy as np
+
+from ..reference import config as C
+
+__all__ = ["FLT_EPSILON", "normalize_inputs", "normalize_array", "speed_masks"]
+
+FLT_EPSILON = np.float32(np.finfo(np.float32).eps)  # std::numeric_limits<float>::epsilon()
+
+
+def normalize_array(value: np.ndarray, mean: np.ndarray, std: np.ndarray) -> np.ndarray:
+    """``normalize_vector`` of ``preprocessing_utils.cpp:36-63`` on one tensor (a new float32 array).
+
+    Rows have ``std.size`` columns; a single-value mean / std broadcasts over the columns (the C++ ``mean.size() == 1``
+    branch); a zero standard deviation raises like the C++."""
+    data = np.array(value, dtype=np.float32, copy=True)
+    mean = np.asarray(mean, np.float32).reshape(-1)
+    std = np.asarray(std, np.float32).reshape(-1)
+    if mean.size != std.size:
+        raise ValueError("Mean and std must be same size")
+    cols = std.size
+    if cols == 0 or data.size % cols:
+        raise ValueError(f"data size {data.size} is not divisible by the normalizer size {cols}")
+    if np.any(np.abs(std) < FLT_EPSILON):
+        raise ValueError("Standard deviation is zero, cannot normalize data")
+    rows = data.reshape(-1, cols)
+    zero_row = np.all(np.abs(rows) < FLT_EPSILON, axis=1)
+    m = np.broadcast_to(mean if mean.size > 1 else mean[:1], (cols,))
+    s = np.broadcast_to(std if std.size > 1 else std[:1], (cols,))
+    normed = ((rows - m) / s).astype(np.float32)  # float32 subtract then divide, element by element
+    rows[~zero_row] = normed[~zero_row]
+    return rows.reshape(data.shape)
+
+
+def normalize_inputs(raw: Mapping[str, np.ndarray],
+                     observation: Mapping[str, Tuple[np.ndarray, np.ndarray]]) -> Dict[str, np.ndarray]:
+    """``normalize_input_data(input_data_map, normalization_map)``: every key except the four skipped ones must have
+    a normalizer (``Missing key ... from normalization map`` otherwise)."""
+    out: Dict[str, np.ndarray] = {}
+    for key, value in raw.items():
+        if key in C.SKIP_NORMALIZATION:
+            out[key] = np.array(value, dtype=np.float32, copy=True)
+            continue
+        if key not in observation:
+            raise KeyError(f"Missing key {key} from normalization map")
+        mean, std = observation[key]
+        out[key] = normalize_array(value, mean, std)
+    return out
+
+
+def speed_masks(norm_inputs: Mapping[str, np.ndarray]) -> Dict[str, np.ndarray]:
+    """``lanes_has_speed_limit`` / ``route_lanes_has_speed_limit`` of the TensorRT path: normalised speed limit
+    ``> FLT_EPSILON`` (``inference/utils.hpp:112-123``; the ORT backend uses ``> 0``,
+    ``onnxruntime_inference.cpp:41-48``; Autoware's default backend is TensorRT)."""
+    return {"lanes_has_speed_limit": np.asarray(norm_inputs["lanes_speed_limit"]) > FLT_EPSILON,
+            "route_lanes_has_speed_limit": np.asarray(norm_inputs["route_lanes_speed_limit"]) > FLT_EPSILON}

code/tt_diffusion_planner/host/pipeline.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The host halves of one plan, shared by the Python API, the HTTP server and the CPU reference.
+
+``prepare(raw, normalization)`` -> :class:`Prepared`: the raw ONNX-named tensors (already checked against
+``config.INPUT_SCHEMA``) normalised like the node, the speed masks, the encoder's host features, the decoder masks
+and the solver's initial ``x``. The network (device trace or CPU reference) turns it into ``final_x0`` (normalised
+``[321, 81, 4]``, prefix constraint applied) and the turn-indicator logits; ``make_output(...)`` applies the node's
+post-processing and returns the ``ttaw.outputs.Trajectory`` that ``model(...)`` and ``POST /predict`` return.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional, Sequence
+
+import numpy as np
+
+from ..reference import config as C
+from ..ttaw.io import InputError, encode_array
+from ..ttaw.outputs import Trajectory
+from .features import DecoderMasks, EncoderFeatures, decoder_masks, encoder_features
+from .normalize import normalize_inputs, speed_masks
+from .postprocess import (TurnIndicatorManager, denoising_steps_ego, denormalize, predicted_paths,
+                          trajectory_from_poses)
+
+__all__ = ["Prepared", "prepare", "make_output", "TRAJECTORY_COLUMNS", "PREDICTED_AGENT_COLUMNS", "RUNTIME_PARAMS"]
+
+TRAJECTORY_COLUMNS = ("x", "y", "yaw", "cos", "sin", "velocity", "acceleration")
+PREDICTED_AGENT_COLUMNS = ("x", "y", "yaw", "cos", "sin")
+# RT-host parameters (request params / call kwargs): name -> (type, min, max, default); the node's YAML defaults
+RUNTIME_PARAMS = {
+    "velocity_smoothing_window": (int, 1, C.OUTPUT_T - 1, C.VELOCITY_SMOOTHING_WINDOW),
+    "stopping_threshold": (float, 0.0, None, C.STOPPING_THRESHOLD),
+    "turn_indicator_keep_offset": (float, None, None, C.TURN_INDICATOR_KEEP_OFFSET),
+    "return_denoising_steps": (bool, None, None, False),
+}
+
+
+@dataclass
+class Prepared:
+    """Host state of one plan."""
+
+    raw: Dict[str, np.ndarray]            # the validated raw tensors (batch 1)
+    norm: Dict[str, np.ndarray]           # normalised tensors + the two speed masks
+    features: EncoderFeatures
+    decoder: DecoderMasks
+    x_T: np.ndarray                       # [321, 81, 4] initial solver state (normalised; correction not yet applied)
+    neighbor_rows: np.ndarray             # indices of the non-empty neighbour rows (the node's emitted agents)
+    enable_force_stop: bool               # ego vx > DBL_EPSILON (diffusion_planner_core.cpp:628-629)
+    prev_report: int                      # the latest TurnIndicatorsReport (turn_indicators[30])
+
+
+def prepare(raw: Mapping[str, np.ndarray], observation: Mapping[str, Any]) -> Prepared:
+    """``raw``: the 15 tensors of ``config.INPUT_SCHEMA`` (float32, batch 1, ego frame, before normalization);
+    ``observation``: ``Normalization.observation``."""
+    missing = sorted(set(C.INPUT_NAMES) - set(raw))
+    if missing:
+        raise InputError(f"inputs: missing {missing}")
+    raw = {k: np.ascontiguousarray(np.asarray(raw[k], np.float32)) for k in C.INPUT_NAMES}
+    for k, shape in C.INPUT_SHAPES.items():
+        if raw[k].shape != shape:
+            raise InputError(f"inputs[{k!r}] has shape {raw[k].shape}, expected {shape}")
+    try:
+        norm = normalize_inputs(raw, observation)
+    except (KeyError, ValueError) as e:  # a normalizer problem is a weights-file problem, not a client mistake
+        raise RuntimeError(f"normalization failed: {e}") from e
+    norm.update(speed_masks(norm))
+    feats = encoder_features(norm, norm)
+    dec = decoder_masks(norm)
+    nb = raw["neighbor_agents_past"][0].reshape(C.MAX_NUM_NEIGHBORS, -1)
+    rows = np.flatnonzero(np.any(nb != 0, axis=1))
+    vx = float(raw["ego_current_state"][0, 4])
+    prev_report = int(round(float(raw["turn_indicators"][0, C.INPUT_T])))
+    x_T = norm["sampled_trajectories"][0].copy()
+    return Prepared(raw, norm, feats, dec, x_T, rows, vx > np.finfo(np.float64).eps, prev_report)
+
+
+def make_output(final_x0: np.ndarray, logit: np.ndarray, prepared: Prepared, normalization: Any,
+                params: Mapping[str, Any], *, model: str = "", denoising_steps: Optional[Sequence[np.ndarray]] = None,
+                timing_ms: Optional[Dict[str, float]] = None, meta: Optional[Dict[str, Any]] = None) -> Trajectory:
+    """The node's post-processing of one plan -> ``Trajectory`` (base_link).
+
+    ``final_x0``: ``[321, 81, 4]`` normalised (t = 0 = current state); ``logit``: ``[5]``; ``params``: the validated
+    ``RUNTIME_PARAMS``; ``denoising_steps``: the 11 iterates ``[321, 81, 4]`` when ``return_denoising_steps``."""
+    x0 = np.asarray(final_x0, np.float32).reshape(C.MAX_NUM_AGENTS, C.OUTPUT_T + 1, C.POSE_DIM)
+    mean, std = normalization.state()
+    denorm = denormalize(x0, mean, std)  # [321, 80, 4]
+    traj = trajectory_from_poses(denorm[0], (0.0, 0.0, 0.0),
+                                 velocity_smoothing_window=int(params["velocity_smoothing_window"]),
+                                 enable_force_stop=prepared.enable_force_stop,
+                                 stopping_threshold=float(params["stopping_threshold"]))
+    manager = TurnIndicatorManager(keep_offset=float(params["turn_indicator_keep_offset"]))
+    decision = manager.evaluate(np.asarray(logit, np.float32).reshape(-1), 0.0, prepared.prev_report)
+    rows = prepared.neighbor_rows
+    paths = predicted_paths(denorm, C.MAX_NUM_NEIGHBORS)[rows] if rows.size else np.zeros(
+        (0, C.OUTPUT_T, len(PREDICTED_AGENT_COLUMNS)), np.float32)
+    out_meta: Dict[str, Any] = {"predicted_agent_columns": list(PREDICTED_AGENT_COLUMNS),
+                                "predicted_agent_rows": [int(r) for r in rows],
+                                "force_stop": bool(traj.force_stop),
+                                "time_from_start_s": [round(float(t), 3) for t in traj.time_from_start],
+                                "valid_counts": prepared.features.counts()}
+    if params.get("return_denoising_steps") and denoising_steps is not None:
+        ego_steps = denoising_steps_ego(np.stack(denoising_steps), mean, std)
+        out_meta["denoising_steps"] = encode_array(ego_steps, key="denoising_steps")
+    out_meta.update(meta or {})
+    return Trajectory(traj.as_columns(), columns=TRAJECTORY_COLUMNS, turn_indicator=decision.to_dict(),
+                      predicted_agents=paths, model=model, frame_id="base_link", timing_ms=dict(timing_ms or {}),
+                      meta=out_meta)

code/tt_diffusion_planner/host/postprocess.py

@@ -0,0 +1,222 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Post-processing of the Autoware node (``postprocessing_utils.cpp``, ``turn_indicator_manager.cpp``,
+``diffusion_planner_core.cpp:605-694``), in the ego frame of the input tensors.
+
+The node transforms every predicted pose to the map frame before building messages; the bundle has no map pose, so
+it applies the same rules with an identity ego-to-map transform (``base_link`` output). Distances, velocities and
+accelerations are invariant to that rigid transform; the published orientation is not exactly (see below).
+
+Rules reproduced, with their numeric types:
+
+- denormalisation: drop t = 0 (unless kept), ``v * std + mean`` per agent and pose dim, float32;
+- poses: 4x4 matrices in double from the RAW (unnormalised) network cos / sin; the quaternion is Eigen's conversion
+  of that 3x3 block, which does not normalise, so for ``|(cos, sin)| != 1`` (0.84-1.09 in the goldens, SPEC 4.6.6)
+  the heading a consumer reads with ``tf2::getYaw`` differs from ``atan2(sin, cos)``; ``yaw`` here is that
+  ``tf2::getYaw`` value of the identity-transform quaternion;
+- ego trajectory (``get_trajectory_from_poses``): ``time_from_start = 0.1 (i + 1)``; velocity = 3-D distance to the
+  previous point (the first point to the ego position) / 0.1, stored as float; forward moving average over
+  ``velocity_smoothing_window`` points summed in double; force stop (only when the ego moves: ``vx > DBL_EPSILON``)
+  once the smoothed velocity crosses below ``stopping_threshold``: velocity 0 and the pose frozen to the previous
+  pose; the last ``window - 1`` points keep the last smoothed velocity; acceleration = forward difference / 0.1 in
+  double stored as float, 0 for the last point;
+- predicted objects: one 80-point path per emitted neighbour (the first ``n`` rows of the neighbour tensor, sorted
+  by distance), window 1, no force stop (only the poses are published);
+- turn indicator (``TurnIndicatorManager::evaluate``): hold the last non-KEEP command for ``hold_duration`` (state
+  across calls), else add ``keep_offset`` to the KEEP logit, ``p_i = expf(l_i - max)``, ``p_i /= (1e-4f + sum)``,
+  argmax (first maximum); KEEP repeats the previous TurnIndicatorsReport, otherwise the command is the index;
+- ``~/debug/denoising_steps``: the ego row of every solver iterate, denormalised with t = 0 kept.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Tuple
+
+import numpy as np
+
+from ..reference import config as C
+from .solver import SCALAR_MATH
+
+__all__ = ["denormalize", "quaternion_from_cos_sin", "tf2_yaw", "EgoTrajectory", "trajectory_from_poses",
+           "predicted_paths", "TurnIndicatorManager", "TurnDecision", "denoising_steps_ego"]
+
+DBL_EPSILON = float(np.finfo(np.float64).eps)
+
+
+def denormalize(x: np.ndarray, state_mean: np.ndarray, state_std: np.ndarray, *,
+                keep_current_state: bool = False) -> np.ndarray:
+    """``denormalize_prediction``: ``x`` ``[321, 81, 4]`` (normalised, t = 0 = current state) -> ``[321, 80, 4]``
+    metres (``[321, 81, 4]`` with ``keep_current_state``). ``state_mean`` / ``state_std`` broadcast as
+    ``[321 or 1, 1, 4]``."""
+    x = np.asarray(x, np.float32)
+    if x.shape[-3:] != (C.MAX_NUM_AGENTS, C.OUTPUT_T + 1, C.POSE_DIM):
+        raise ValueError(f"unsupported prediction shape {x.shape}")
+    p = x if keep_current_state else x[..., 1:, :]
+    return (p * np.asarray(state_std, np.float32) + np.asarray(state_mean, np.float32)).astype(np.float32)
+
+
+def quaternion_from_cos_sin(cos_yaw: np.ndarray, sin_yaw: np.ndarray) -> np.ndarray:
+    """Eigen ``Quaterniond(rotation_matrix)`` of ``[[c, -s, 0], [s, c, 0], [0, 0, 1]]`` (no normalisation), in double:
+    ``[..., 4]`` = (x, y, z, w). Eigen's branch: trace = 2c + 1 > 0 -> w = sqrt(trace + 1) / 2, z = (m10 - m01) / (4 w);
+    else the largest diagonal is m22 -> z = sqrt(m22 - m00 - m11 + 1) / 2, w = (m10 - m01) / (4 z)."""
+    c = np.asarray(cos_yaw, np.float64)
+    s = np.asarray(sin_yaw, np.float64)
+    q = np.zeros(c.shape + (4,), np.float64)
+    trace = c + c + 1.0
+    pos = trace > 0.0
+    with np.errstate(divide="ignore", invalid="ignore"):
+        t = np.sqrt(trace + 1.0)
+        w_pos, z_pos = 0.5 * t, (s - (-s)) * (0.5 / t)
+        # trace <= 0: i = 2 (m22 = 1 > m00 = c, since c <= -0.5), j = 0, k = 1
+        t2 = np.sqrt(1.0 - c - c + 1.0)
+        z_neg, w_neg = 0.5 * t2, (s - (-s)) * (0.5 / t2)
+    q[..., 2] = np.where(pos, z_pos, z_neg)
+    q[..., 3] = np.where(pos, w_pos, w_neg)
+    return q
+
+
+def tf2_yaw(q: np.ndarray) -> np.ndarray:
+    """``tf2::getYaw`` (scale-invariant): ``atan2(2 (x y + w z), w^2 + x^2 - y^2 - z^2)``."""
+    x, y, z, w = (q[..., i] for i in range(4))
+    return np.arctan2(2.0 * (x * y + w * z), w * w + x * x - y * y - z * z)
+
+
+@dataclass
+class EgoTrajectory:
+    """One trajectory as the node publishes it (in the ego frame here): positions [N, 3] (double), the raw cos / sin
+    of each pose [N, 2] (after force-stop freezing), quaternions [N, 4] (x, y, z, w), yaw [N] (``tf2::getYaw``),
+    ``velocity`` / ``acceleration`` [N] float32, ``time_from_start`` [N] seconds, and whether force stop fired."""
+
+    position: np.ndarray
+    cos_sin: np.ndarray
+    quaternion: np.ndarray
+    yaw: np.ndarray
+    velocity: np.ndarray
+    acceleration: np.ndarray
+    time_from_start: np.ndarray
+    force_stop: bool
+
+    def as_columns(self) -> np.ndarray:
+        """``[N, 7]`` float32: x, y, yaw, cos, sin, velocity, acceleration (the ``Trajectory.poses`` layout)."""
+        return np.stack([self.position[:, 0], self.position[:, 1], self.yaw, self.cos_sin[:, 0], self.cos_sin[:, 1],
+                         self.velocity, self.acceleration], axis=-1).astype(np.float32)
+
+
+def trajectory_from_poses(poses_xycs: np.ndarray, base_position: Tuple[float, float, float] = (0.0, 0.0, 0.0), *,
+                          velocity_smoothing_window: int = C.VELOCITY_SMOOTHING_WINDOW,
+                          enable_force_stop: bool = True,
+                          stopping_threshold: float = C.STOPPING_THRESHOLD) -> EgoTrajectory:
+    """``get_trajectory_from_poses`` (``postprocessing_utils.cpp:362-455``) for poses ``[N, 4]`` = denormalised
+    (x, y, cos, sin) float32 of one agent, positions at z = ``base_position[2]`` (identity transform)."""
+    p = np.asarray(poses_xycs, np.float32)
+    n = p.shape[0]
+    dt = C.TRAJECTORY_DT
+    pos = np.zeros((n, 3), np.float64)
+    pos[:, 0] = p[:, 0].astype(np.float64)
+    pos[:, 1] = p[:, 1].astype(np.float64)
+    pos[:, 2] = float(base_position[2])
+    cs = p[:, 2:4].astype(np.float64).copy()
+    quat = quaternion_from_cos_sin(cs[:, 0], cs[:, 1])
+    vel = np.zeros(n, np.float32)
+    prev = np.asarray(base_position, np.float64)
+    for i in range(n):
+        d = math.hypot(pos[i, 0] - prev[0], pos[i, 1] - prev[1], pos[i, 2] - prev[2])
+        vel[i] = np.float32(d / dt)
+        prev = pos[i]
+    w = int(velocity_smoothing_window)
+    if n <= w:
+        raise ValueError("velocity_smoothing_window must be smaller than number of points")
+    thr = np.float32(stopping_threshold)
+    force_stop = False
+    for i in range(0, n - w + 1):
+        acc = 0.0
+        for k in range(w):
+            acc += float(vel[i + k])
+        vel[i] = np.float32(acc / float(w))
+        if enable_force_stop and i > 0 and abs(vel[i - 1]) > thr and abs(vel[i]) < thr:
+            force_stop = True
+        if i > 0 and force_stop:
+            vel[i] = np.float32(0.0)
+            pos[i], cs[i], quat[i] = pos[i - 1], cs[i - 1], quat[i - 1]
+    last = vel[n - w]
+    for i in range(n - w + 1, n):
+        vel[i] = last
+        if force_stop:
+            vel[i] = np.float32(0.0)
+            pos[i], cs[i], quat[i] = pos[i - 1], cs[i - 1], quat[i - 1]
+    accel = np.zeros(n, np.float32)
+    for i in range(n - 1):
+        accel[i] = np.float32((float(vel[i + 1]) - float(vel[i])) / dt)
+    tfs = dt * (np.arange(n, dtype=np.float64) + 1.0)
+    return EgoTrajectory(pos, cs, quat, tf2_yaw(quat), vel, accel, tfs, force_stop)
+
+
+def predicted_paths(denorm: np.ndarray, n_neighbors: int) -> np.ndarray:
+    """``create_predicted_objects`` poses for the first ``n_neighbors`` neighbours: ``[n, 80, 5]`` float32 =
+    x, y, yaw (``tf2::getYaw``), cos, sin. ``denorm`` is ``[321, 80, 4]`` (agent 0 = ego)."""
+    nb = np.asarray(denorm, np.float32)[1:1 + int(n_neighbors)]
+    q = quaternion_from_cos_sin(nb[..., 2], nb[..., 3])
+    return np.stack([nb[..., 0], nb[..., 1], tf2_yaw(q).astype(np.float32), nb[..., 2], nb[..., 3]],
+                    axis=-1).astype(np.float32)
+
+
+def denoising_steps_ego(iterates: np.ndarray, state_mean: np.ndarray, state_std: np.ndarray) -> np.ndarray:
+    """``create_denoising_steps_message`` (batch 1): the ego row of each iterate, denormalised with t = 0 kept:
+    ``[steps, 81, 4]``. ``iterates`` is ``[steps, 321, 81, 4]`` or just the ego rows ``[steps, 1, 81, 4]`` (what the
+    device plan reads back); the float32 arithmetic is the same element by element (``x * std + mean``)."""
+    it = np.asarray(iterates, np.float32)
+    if it.ndim != 4 or it.shape[1] not in (1, C.MAX_NUM_AGENTS) or it.shape[2:] != (C.OUTPUT_T + 1, C.POSE_DIM):
+        raise ValueError(f"unsupported iterates shape {it.shape}")
+    shape = (C.MAX_NUM_AGENTS, 1, C.POSE_DIM)
+    mean0 = np.broadcast_to(np.asarray(state_mean, np.float32), shape)[0]
+    std0 = np.broadcast_to(np.asarray(state_std, np.float32), shape)[0]
+    return (it[:, 0] * std0 + mean0).astype(np.float32)
+
+
+@dataclass
+class TurnDecision:
+    command: int
+    logits: Tuple[float, ...]
+    probabilities: Tuple[float, ...]
+    keep_selected: bool
+    held: bool = False
+
+    def to_dict(self) -> Dict[str, object]:
+        name = C.TURN_INDICATOR_COMMAND_NAMES.get(self.command, str(self.command))
+        return {"command": int(self.command), "command_name": name, "keep_selected": bool(self.keep_selected),
+                "held": bool(self.held), "logits": [float(v) for v in self.logits],
+                "probabilities": [float(v) for v in self.probabilities]}
+
+
+@dataclass
+class TurnIndicatorManager:
+    """``TurnIndicatorManager`` (stateful: the last non-KEEP command and its stamp). A fresh manager has no held
+    command, which is what a single stateless request sees."""
+
+    hold_duration_s: float = C.TURN_INDICATOR_HOLD_DURATION_S
+    keep_offset: float = C.TURN_INDICATOR_KEEP_OFFSET
+    _last_command: int = field(default=0, repr=False)
+    _last_stamp_s: Optional[float] = field(default=None, repr=False)
+
+    def evaluate(self, logit: np.ndarray, stamp_s: float = 0.0,
+                 prev_report: int = C.TURN_INDICATORS_REPORT_DISABLE) -> TurnDecision:
+        lg = np.asarray(logit, np.float32).reshape(-1).copy()
+        raw = tuple(float(v) for v in lg)
+        if lg.size == 0:
+            return TurnDecision(1, raw, (), False)  # TurnIndicatorsCommand::DISABLE
+        if self._last_stamp_s is not None and self._last_stamp_s > 0 and stamp_s <= self._last_stamp_s + float(
+                self.hold_duration_s):
+            return TurnDecision(self._last_command, raw, (), False, held=True)
+        lg[C.TURN_INDICATOR_OUTPUT_KEEP] = np.float32(lg[C.TURN_INDICATOR_OUTPUT_KEEP] + np.float32(self.keep_offset))
+        mx = lg.max()
+        prob = np.array([SCALAR_MATH.exp(np.float32(v - mx)) for v in lg], np.float32)
+        total = np.float32(0.0001)
+        for v in prob:
+            total = np.float32(total + v)
+        prob = (prob / total).astype(np.float32)
+        idx = int(np.argmax(prob))  # std::max_element: the first maximum
+        keep = idx == C.TURN_INDICATOR_OUTPUT_KEEP
+        command = (int(prev_report) & 0xFF) if keep else idx
+        if not keep:
+            self._last_command, self._last_stamp_s = command, float(stamp_s)
+        return TurnDecision(command, raw, tuple(float(v) for v in prob), keep)

code/tt_diffusion_planner/host/solver.py

@@ -0,0 +1,273 @@
+# SPDX-License-Identifier: Apache-2.0
+"""DPM-Solver++(2M) with denoise-to-zero, as Autoware runs it around the decoder (multi_step mode).
+
+Port of ``PKG/src/inference/solver/dpm_solver.cpp`` (guidance disabled, Autoware's default and decision D11) and of
+the prefix constraint of ``PKG/src/inference/multi_step_inference.cpp:300-340``. The scalar schedule is float32 math
+evaluated with the C library's ``expf`` / ``logf`` / ``expm1f`` / ``sqrtf`` (what ``std::exp(float)`` etc. call in
+the node) in the C++ operation order, so the timesteps and update coefficients are the node's bit for bit; numpy's
+own float32 transcendentals differ from glibc in the last bit for many arguments. Without a loadable libm the module
+falls back to numpy (``SCALAR_MATH`` says which).
+
+For ``steps = 10``: 11 decoder evaluations at ``timesteps[0..9]`` and ``1/N = 0.001`` (denoise-to-zero); the 11
+published iterates (``denoising_steps``) are the corrected ``x`` after each update and after the final evaluation.
+The update formulas, with ``x`` and the model outputs float32 arrays and every scalar a float32::
+
+    first  (step 1):     x = (sigma_t / sigma_s) * x - (alpha_t * phi_1) * m
+    second (steps 2..):  d = (m0 - m1) / r0
+                         x = (sigma_t / sigma_0) * x - (alpha_t * phi_1) * m0 - (0.5 * (alpha_t * phi_1)) * d
+
+:class:`SolverPlan` lists these scalars per update (the RT-dev coefficient tables of the on-device loop).
+"""
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional, Tuple
+
+import numpy as np
+
+from ..reference import config as C
+
+__all__ = ["SCALAR_MATH", "marginal_log_mean_coeff", "marginal_alpha", "marginal_std", "marginal_lambda",
+           "inverse_lambda", "log_snr_timesteps", "SolverUpdate", "SolverPlan", "solver_plan", "first_update",
+           "second_update", "dpm_solver_sample", "apply_prefix_constraint", "SampleResult"]
+
+f32 = np.float32
+_T, _N = C.NOISE_SCHEDULE_T, C.NOISE_SCHEDULE_TOTAL_N
+_B0, _B1 = C.NOISE_SCHEDULE_BETA0, C.NOISE_SCHEDULE_BETA1
+
+
+class _ScalarMath:
+    """float32 ``exp`` / ``log`` / ``expm1`` / ``sqrt`` of the C library, loaded on first use (numpy fallback)."""
+
+    def __init__(self) -> None:
+        self._fns = None
+        self.source = "unloaded"
+
+    def _load(self) -> None:
+        fns = None
+        try:
+            name = ctypes.util.find_library("m") or "libm.so.6"
+            libm = ctypes.CDLL(name)
+            fns = {}
+            for fn in ("expf", "logf", "expm1f", "sqrtf"):
+                f = getattr(libm, fn)
+                f.restype, f.argtypes = ctypes.c_float, [ctypes.c_float]
+                fns[fn] = f
+            self.source = f"libm ({name})"
+        except (OSError, AttributeError):
+            fns = None
+            self.source = "numpy (no C math library found)"
+        self._fns = fns or {}
+
+    def _call(self, fn: str, x: float, fallback: Callable) -> np.float32:
+        if self._fns is None:
+            self._load()
+        if fn in self._fns:
+            return f32(self._fns[fn](float(f32(x))))
+        return f32(fallback(f32(x)))
+
+    def exp(self, x):
+        return self._call("expf", x, np.exp)
+
+    def log(self, x):
+        return self._call("logf", x, np.log)
+
+    def expm1(self, x):
+        return self._call("expm1f", x, np.expm1)
+
+    def sqrt(self, x):
+        return self._call("sqrtf", x, np.sqrt)
+
+
+SCALAR_MATH = _ScalarMath()
+_m = SCALAR_MATH
+
+
+# ---- noise schedule (dpm_solver.cpp:49-94), float32 in the C++ operation order ---------------------------------------
+def marginal_log_mean_coeff(t) -> np.float32:
+    """``-0.25f * t * t * (beta1 - beta0) - 0.5f * t * beta0``."""
+    t = f32(t)
+    return f32(f32(f32(f32(-0.25) * t) * t) * f32(_B1 - _B0)) - f32(f32(f32(0.5) * t) * _B0)
+
+
+def marginal_alpha(t) -> np.float32:
+    return _m.exp(marginal_log_mean_coeff(t))
+
+
+def marginal_std(t) -> np.float32:
+    return _m.sqrt(f32(f32(1.0) - _m.exp(f32(f32(2.0) * marginal_log_mean_coeff(t)))))
+
+
+def marginal_lambda(t) -> np.float32:
+    lmc = marginal_log_mean_coeff(t)
+    log_std = f32(f32(0.5) * _m.log(f32(f32(1.0) - _m.exp(f32(f32(2.0) * lmc)))))
+    return f32(lmc - log_std)
+
+
+def _log_add_exp(a, b) -> np.float32:
+    m = max(f32(a), f32(b))
+    return f32(m + _m.log(f32(_m.exp(f32(f32(a) - m)) + _m.exp(f32(f32(b) - m)))))
+
+
+def inverse_lambda(lam) -> np.float32:
+    beta_delta = f32(_B1 - _B0)
+    tmp = f32(f32(f32(2.0) * beta_delta) * _log_add_exp(f32(f32(-2.0) * f32(lam)), f32(0.0)))
+    delta = f32(f32(_B0 * _B0) + tmp)
+    return f32(f32(tmp / f32(_m.sqrt(delta) + _B0)) / beta_delta)
+
+
+def log_snr_timesteps(steps: int) -> List[np.float32]:
+    """``steps + 1`` times uniform in log-SNR between t = 1 and t = 1/N (``dpm_solver.cpp:80-94``)."""
+    t0 = f32(f32(1.0) / _N)
+    lam_t, lam_0 = marginal_lambda(_T), marginal_lambda(t0)
+    out = []
+    for i in range(steps + 1):
+        ratio = f32(f32(i) / f32(steps))
+        out.append(inverse_lambda(f32(lam_t + f32(f32(lam_0 - lam_t) * ratio))))
+    return out
+
+
+# ---- updates (dpm_solver.cpp:96-136) ------------------------------------------------------------------------------
+def first_update(x_s: np.ndarray, model_s: np.ndarray, s, t) -> np.ndarray:
+    h = f32(marginal_lambda(t) - marginal_lambda(s))
+    sigma_s, sigma_t, alpha_t = marginal_std(s), marginal_std(t), marginal_alpha(t)
+    phi_1 = _m.expm1(f32(-h))
+    a, b = f32(sigma_t / sigma_s), f32(alpha_t * phi_1)
+    return (a * x_s.astype(np.float32) - b * model_s.astype(np.float32)).astype(np.float32)
+
+
+def second_update(x_s: np.ndarray, model_prev: Tuple[np.ndarray, np.ndarray], t_prev: Tuple[float, float],
+                  t) -> np.ndarray:
+    m1, m0 = model_prev  # model_prev_list[0] (older), model_prev_list[1] (newer)
+    t1, t0 = t_prev
+    lam1, lam0, lam_t = marginal_lambda(t1), marginal_lambda(t0), marginal_lambda(t)
+    sigma0, sigma_t, alpha_t = marginal_std(t0), marginal_std(t), marginal_alpha(t)
+    h0, h = f32(lam0 - lam1), f32(lam_t - lam0)
+    r0 = f32(h0 / h)
+    phi_1 = _m.expm1(f32(-h))
+    a, b = f32(sigma_t / sigma0), f32(alpha_t * phi_1)
+    c = f32(f32(0.5) * b)
+    d1_0 = ((m0.astype(np.float32) - m1.astype(np.float32)) / r0).astype(np.float32)
+    return (a * x_s.astype(np.float32) - b * m0.astype(np.float32) - c * d1_0).astype(np.float32)
+
+
+@dataclass(frozen=True)
+class SolverUpdate:
+    """One solver update to time ``t``: ``x = a * x - b * m0 - c * (m0 - m1) / r0`` (``c = 0`` for the first-order
+    update, which has no ``m1``)."""
+
+    order: int
+    t: float
+    a: float
+    b: float
+    c: float
+    r0: float
+
+
+@dataclass(frozen=True)
+class SolverPlan:
+    """Everything the on-device loop needs for ``steps`` (the RT-dev tables of PLAN.md 2.12): the decoder evaluation
+    times (``eval_times[k]`` feeds evaluation ``k``; the t-embedding / adaLN tables are built for these values), the
+    update after each of the first ``steps`` evaluations, and the published iterate times."""
+
+    steps: int
+    timesteps: Tuple[float, ...]
+    eval_times: Tuple[float, ...]
+    updates: Tuple[SolverUpdate, ...]
+    denoising_timesteps: Tuple[float, ...]
+    scalar_math: str = field(default="")
+
+
+def solver_plan(steps: int = C.DPM_SOLVER_STEPS) -> SolverPlan:
+    if steps < C.DPM_SOLVER_ORDER:
+        raise ValueError("DpmSolver steps must be greater than or equal to solver order.")
+    ts = log_snr_timesteps(steps)
+    updates = []
+    for step in range(1, steps + 1):
+        t = ts[step]
+        if step < C.DPM_SOLVER_ORDER:
+            s = _T if step == 1 else ts[step - 1]
+            h = f32(marginal_lambda(t) - marginal_lambda(s))
+            a = f32(marginal_std(t) / marginal_std(s))
+            b = f32(marginal_alpha(t) * _m.expm1(f32(-h)))
+            updates.append(SolverUpdate(1, float(t), float(a), float(b), 0.0, 1.0))
+        else:
+            t1 = _T if step - 2 == 0 else ts[step - 2]
+            t0 = ts[step - 1]
+            lam1, lam0, lam_t = marginal_lambda(t1), marginal_lambda(t0), marginal_lambda(t)
+            h0, h = f32(lam0 - lam1), f32(lam_t - lam0)
+            b = f32(marginal_alpha(t) * _m.expm1(f32(-h)))
+            updates.append(SolverUpdate(2, float(t), float(f32(marginal_std(t) / marginal_std(t0))), float(b),
+                                        float(f32(f32(0.5) * b)), float(f32(h0 / h))))
+    final_t = f32(f32(1.0) / _N)
+    return SolverPlan(steps, tuple(float(t) for t in ts), tuple(float(t) for t in ts[:steps]) + (float(final_t),),
+                      tuple(updates), tuple(float(t) for t in ts[1:]) + (float(final_t),), SCALAR_MATH.source)
+
+
+# ---- the loop (dpm_solver.cpp:138-234) ---------------------------------------------------------------------------
+@dataclass
+class SampleResult:
+    final_x: np.ndarray
+    denoising_steps: List[np.ndarray]
+    denoising_timesteps: List[float]
+    eval_times: List[float]
+    nfe: int
+
+
+def apply_prefix_constraint(x: np.ndarray, current_states: np.ndarray) -> np.ndarray:
+    """``x[agent, 0, :] = current_states[agent]`` in place (``multi_step_inference.cpp:327-340``); ``x`` is
+    ``[321, 81, 4]`` (or with a leading batch dim)."""
+    x[..., 0, :] = current_states
+    return x
+
+
+def dpm_solver_sample(initial_x: np.ndarray, model_fn: Callable[[np.ndarray, np.float32], np.ndarray],
+                      correcting_fn: Callable[[np.ndarray], None], steps: int = C.DPM_SOLVER_STEPS,
+                      on_iterate: Optional[Callable[[int, np.ndarray], None]] = None) -> SampleResult:
+    """``DpmSolver::sample`` without guidance. ``model_fn(x, t)`` is one decoder evaluation (x0 prediction),
+    ``correcting_fn(x)`` the in-place prefix constraint."""
+    if steps < C.DPM_SOLVER_ORDER:
+        raise ValueError("DpmSolver steps must be greater than or equal to solver order.")
+    x = np.array(initial_x, dtype=np.float32, copy=True)
+    correcting_fn(x)
+    ts = log_snr_timesteps(steps)
+    steps_out: List[np.ndarray] = []
+    step_ts: List[float] = []
+    eval_times: List[float] = []
+
+    def evaluate(xx: np.ndarray, t) -> np.ndarray:
+        eval_times.append(float(t))
+        return np.asarray(model_fn(xx, f32(t)), np.float32)
+
+    def record(xx: np.ndarray, t) -> None:
+        steps_out.append(xx.copy())
+        step_ts.append(float(t))
+        if on_iterate is not None:
+            on_iterate(len(steps_out) - 1, xx)
+
+    t_prev = [_T]
+    m_prev = [evaluate(x, ts[0])]
+    for step in range(1, C.DPM_SOLVER_ORDER):
+        t = ts[step]
+        x = first_update(x, m_prev[-1], t_prev[-1], t)
+        correcting_fn(x)
+        record(x, t)
+        t_prev.append(t)
+        m_prev.append(evaluate(x, t))
+    for step in range(C.DPM_SOLVER_ORDER, steps + 1):
+        t = ts[step]
+        x = second_update(x, (m_prev[0], m_prev[1]), (t_prev[0], t_prev[1]), t)
+        correcting_fn(x)
+        record(x, t)
+        t_prev = [t_prev[1], t]
+        m_prev = [m_prev[1], None]
+        if step < steps:
+            m_prev[1] = evaluate(x, t)
+    final_t = f32(f32(1.0) / _N)
+    x = evaluate(x, final_t)  # denoise to zero: the model output itself, no guidance on the last step
+    x = np.array(x, dtype=np.float32, copy=True)
+    correcting_fn(x)
+    record(x, final_t)
+    return SampleResult(x, steps_out, step_ts, eval_times, len(eval_times))

code/tt_diffusion_planner/io.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Input decoding and output encoding shared by the Python API and the HTTP server of diffusion-planner-p150.
+
+The implementation is the vendored ``ttaw.io`` (C08); numpy only, data parsing only, and every client mistake raises
+:class:`InputError`, which the server maps to HTTP 400. This model's only input is ``inputs``: the 15 ONNX-named
+planner tensors of the node's ``create_input_data()`` (``reference.config.INPUT_SCHEMA``), as a ``{name: array}``
+mapping, an ``.npz`` path or its bytes, or the JSON envelope ``{"format": "npz", "data": <base64>}`` /
+``{"format": "json", "arrays": {...}}``. :func:`load_inputs` / :func:`decode_inputs` bind the schema, so
+``model(inputs=...)`` and ``POST /predict`` accept and refuse the same inputs (names, shapes, finite values).
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from .reference.config import INPUT_SCHEMA
+from .ttaw import io as _io
+from .ttaw.io import *  # noqa: F401,F403  (the decoders and encoders: ttaw/API.md section 9)
+
+__all__ = list(_io.__all__) + ["DEFAULT_POINT_FIELDS", "INPUT_SCHEMA", "load_inputs", "decode_inputs"]
+
+DEFAULT_POINT_FIELDS = ()  # no point cloud input
+
+
+def load_inputs(source: Any) -> dict:
+    """Python-API planner input (mapping, ``.npz`` path or bytes, JSON envelope) -> ``{name: float32 array}``
+    checked against ``INPUT_SCHEMA``."""
+    return _io.load_named_arrays(source, INPUT_SCHEMA)
+
+
+def decode_inputs(spec: Mapping[str, Any], *, max_bytes: Optional[int] = None) -> dict:
+    """The ``inputs`` envelope of ``/predict`` -> ``{name: float32 array}`` checked against ``INPUT_SCHEMA``."""
+    return _io.decode_named_arrays(spec, INPUT_SCHEMA, max_bytes=max_bytes)

code/tt_diffusion_planner/reference/__init__.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CPU reference of Diffusion Planner v5.0 (Autoware diffusion_planner) -- the ground truth every PCC /
+output-agreement gate of the TT port compares against. Importable without ttnn (torch, numpy, onnx only).
+
+- ``config.py``    dimensions, token layout, constants and node parameters, each with its Autoware / ONNX source.
+- ``weights.py``   the three ONNX files and ``diffusion_planner.param.json`` read as DATA with the vendored
+                   ``ttaw.weights.OnnxWeights``, every tensor addressed through its consuming node, into one canonical
+                   ``{name: float32}`` dict that the reference and the ttnn graph share (no BatchNorm to fold).
+- ``model.py``     pure-PyTorch fp32 encoder / DiT decoder / turn head with per-module taps.
+- ``rewrites.py``  the exact graph rewrites the TT port applies (per-step adaLN tables folded into the LayerNorm
+                   affine, hoisted cross-attention K/V, the pad-relative fp32 pre-projection island) as float64-built
+                   constants plus CPU forwards that use them, tested against ``model.py``.
+- ``pipeline.py``  ``ReferencePlanner``: host pre-processing (``..host``) -> encoder -> DPM-Solver++(2M) loop over 11
+                   decoder evaluations -> turn head -> host post-processing; ``run()`` records taps for goldens.
+- ``ort.py``       ONNX Runtime on the shipped ONNX (the reference's oracle; research venv and tests only).
+- ``goldens.py``   golden generation (taps + outputs per scene) and the small goldens kept in ``tests/goldens``.
+
+The ``to_dict()`` of ``ReferencePlanner()(inputs=sample)`` is stored as ``samples/<stem>.reference.json``:
+``server/smoke_test.py`` compares the served output with it.
+"""
+
+__all__ = ["ReferencePlanner", "load_weights", "find_weights_dir"]
+
+
+def __getattr__(name):
+    if name == "ReferencePlanner":
+        from .pipeline import ReferencePlanner
+
+        return ReferencePlanner
+    if name in ("load_weights", "find_weights_dir"):
+        from . import weights
+
+        return getattr(weights, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

code/tt_diffusion_planner/reference/config.py

@@ -0,0 +1,175 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Constants of the Autoware Diffusion Planner v5.0 contract, each with its source.
+
+Shared by the host pre/post-processing (``tt_diffusion_planner.host``), the CPU reference (``reference``) and the
+ttnn graph (``tt``). Every value that changes a device shape is a COMPILE parameter (PLAN.md section 0.4): a change
+means a new trace and a new image.
+
+Source abbreviations: ``PKG`` = autoware_universe @ 9ceaccf ``planning/autoware_diffusion_planner``; ``HFD`` = the
+weights ``AutowareFoundation/diffusion_planner@v5.0`` (423efde6); ``SPEC`` = ``research/diffusion-planner/SPEC.md`` of
+the porting workspace; ``T4M`` = tier4/Diffusion-Planner @ 40114a8 ``diffusion_planner/diffusion_planner`` (read
+for semantics only, never imported).
+"""
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+import numpy as np
+
+# ---- dimensions (PKG/include/autoware/diffusion_planner/dimensions.hpp:26-105) --------------------------------------
+NUM_SEGMENTS_IN_LANE = 140
+NUM_SEGMENTS_IN_ROUTE = 25
+NUM_POLYGONS = 10
+NUM_LINE_STRINGS = 60
+NUM_STATIC_OBJECTS = 5
+MAX_NUM_NEIGHBORS = 320
+MAX_NUM_AGENTS = MAX_NUM_NEIGHBORS + 1  # ego + neighbours
+HIDDEN_DIM = 256
+POINTS_PER_SEGMENT = 20
+POINTS_PER_POLYGON = 40
+POINTS_PER_LINE_STRING = 20
+LINE_TYPE_NUM = 10
+POLYGON_TYPE_NUM = 1  # intersection_area
+LINE_STRING_TYPE_NUM = 2  # stop_line, road_border
+SEGMENT_POINT_DIM = 13 + 2 * LINE_TYPE_NUM  # 33
+INPUT_T = 30  # history steps before the current one (31 samples with the current)
+OUTPUT_T = 80  # future steps (8 s at 0.1 s)
+POSE_DIM = 4  # x, y, cos(yaw), sin(yaw)
+AGENT_STATE_DIM = 11  # x, y, cos, sin, vx, vy, width, length, is_vehicle, is_pedestrian, is_bicycle
+EGO_CURRENT_STATE_DIM = 10
+STATIC_OBJECT_DIM = 10
+EGO_SHAPE_DIM = 3  # wheel_base, length, width
+TURN_INDICATOR_OUTPUT_DIM = 5
+# logit order (dimensions.hpp:74-79); the published command is the index for 0..3 (TurnIndicatorsCommand)
+TURN_INDICATOR_LABELS = ("NONE", "DISABLE", "ENABLE_LEFT", "ENABLE_RIGHT", "KEEP")
+TURN_INDICATOR_OUTPUT_KEEP = 4
+TURN_INDICATOR_COMMAND_NAMES = {0: "NO_COMMAND", 1: "DISABLE", 2: "ENABLE_LEFT", 3: "ENABLE_RIGHT"}
+TURN_INDICATORS_REPORT_DISABLE = 1  # TurnIndicatorsReport::DISABLE, the prev_report default (core.cpp:635-637)
+
+# ---- the encoder's 564 scene tokens, in concatenation order (T4M/model/module/encoder.py:251-265; SPEC 2.5) -------
+TOKEN_LAYOUT: Tuple[Tuple[str, int], ...] = (
+    ("ego", 1),
+    ("neighbor", MAX_NUM_NEIGHBORS),
+    ("static", NUM_STATIC_OBJECTS),
+    ("lane", NUM_SEGMENTS_IN_LANE),
+    ("route", NUM_SEGMENTS_IN_ROUTE),
+    ("polygon", NUM_POLYGONS),
+    ("line_string", NUM_LINE_STRINGS),
+    ("goal", 1),
+    ("ego_shape", 1),
+    ("turn", 1),
+)
+ENCODING_TOKEN_NUM = sum(n for _, n in TOKEN_LAYOUT)  # 564 (dimensions.hpp:33-35)
+
+
+def token_slices() -> Dict[str, slice]:
+    """``{category: slice of the 564 tokens}``."""
+    out, start = {}, 0
+    for name, n in TOKEN_LAYOUT:
+        out[name] = slice(start, start + n)
+        start += n
+    return out
+
+
+TOKEN_SLICES = token_slices()
+
+# class ids of the 14-dim positional feature (T4M encoder.py:10-21). The turn-indicator token reuses the ego-shape
+# id 8 (FloatsEncoder hard-codes CLASS_TYPE_EGO_SHAPE, encoder.py:808; confirmed by the ONNX ConstantOfShape values).
+POS_CLASS = {"ego": 0, "neighbor": 1, "static": 2, "lane": 3, "route": 4, "polygon": 5, "line_string": 6,
+             "goal": 7, "ego_shape": 8, "turn": 8}
+POS_CLASS_NUM = 10
+POS_FEATURE_DIM = 4 + POS_CLASS_NUM  # 14
+
+# ---- in-graph pre-processing of the encoder (SPEC 3.8; T4M encoder.py) ------------------------------------------
+EGO_HISTORY_KEEP = slice(0, 6)  # the 6 OLDEST ego samples are kept, rows 6..30 zeroed (encoder.py:170-175)
+NEIGHBOR_HISTORY_KEEP = slice(INPUT_T + 1 - 6, INPUT_T + 1)  # the 6 newest neighbour samples (rows 25..30)
+TURN_INDICATOR_HISTORY = INPUT_T  # turn_indicators[:, :-1]: the 30 values before the current report (encoder.py:209)
+LANE_POS_INDEX = POINTS_PER_SEGMENT // 2  # 10: point used for the lane / route position feature (encoder.py:592)
+POLYGON_POS_INDEX = POINTS_PER_POLYGON // 2  # 20 (LineEncoder, encoder.py:685)
+LINE_STRING_POS_INDEX = POINTS_PER_LINE_STRING // 2  # 10
+LANE_FEATURE_DIM = 8  # x, y, dx, dy, left - centre (x, y), right - centre (x, y)
+LANE_ATTRIBUTE_DIM = SEGMENT_POINT_DIM - LANE_FEATURE_DIM  # 25: traffic light (5) + line types (2 x 10) of point 0
+NEIGHBOR_FEATURE_DIM = 9  # x, y, cos, sin, 0, 0 (velocities zeroed), width, length, valid-step flag
+POLYGON_FEATURE_DIM = 2 + POLYGON_TYPE_NUM + 2  # x, y, type, dx, dy
+LINE_STRING_FEATURE_DIM = 2 + LINE_STRING_TYPE_NUM + 2  # x, y, stop_line, road_border, dx, dy
+
+# ---- network constants (ONNX, SPEC 4.1-4.4) ------------------------------------------------------------------------
+LN_EPS = 1e-5  # every LayerNormalization of the three graphs (109 nodes; ttnn's default is 1e-12: pass it explicitly)
+NUM_HEADS = 8
+HEAD_DIM = HIDDEN_DIM // NUM_HEADS  # 32
+ATTN_SCALE = np.float32(0.17677669)  # ONNX constant Mul_3 / Mul_2 = 1/sqrt(32) (applied to Q before Q.K^T)
+MIXER_TOKENS = 64  # token_pre_project out, tokens_mlp width
+MIXER_CHANNELS = 128  # channel_pre_project out, channels_mlp width
+MIXER_DEPTH = 6  # encoder_mixer_depth (HFD param.json)
+FUSION_DEPTH = 6  # encoder_fusion_depth
+FUSION_MLP_DIM = 4 * HIDDEN_DIM
+DIT_DEPTH = 3  # decoder_depth
+DIT_MLP_DIM = 4 * HIDDEN_DIM
+DIT_INPUT_DIM = (OUTPUT_T + 1) * POSE_DIM  # 324 = preproj input / final projection output
+DIT_TIME_DIM = OUTPUT_T + 1  # 81 = t_embedder input (one diffusion time per trajectory point)
+TURN_HEAD_STEPS = tuple(range(1, OUTPUT_T, 10))  # final_x0[0, 1::10, :2] -> 8 points, 16 values (SPEC 4.4)
+
+# ---- DPM-Solver++(2M) (PKG/src/inference/solver/dpm_solver.cpp:29-33; PKG/config/diffusion_planner.param.yaml) -----
+# yaml l.17 model.multi_step_model.dpm_solver_steps: NFE = steps + 1 (COMPILE: the loop length of the trace)
+DPM_SOLVER_STEPS = 10
+DPM_SOLVER_ORDER = 2
+NOISE_SCHEDULE_T = np.float32(1.0)
+NOISE_SCHEDULE_TOTAL_N = np.float32(1000.0)
+NOISE_SCHEDULE_BETA0 = np.float32(0.1)
+NOISE_SCHEDULE_BETA1 = np.float32(20.0)
+# SPEC 5.1 (recomputed from dpm_solver.cpp:80-94): the 11 solver timesteps for steps = 10, float32
+DPM_TIMESTEPS_STEPS10 = (1.0, 0.89912426, 0.78557116, 0.65344393, 0.49344844, 0.30464348, 0.14064588, 0.05360911,
+                         0.01809745, 0.00499264, 0.00100062)
+
+# ---- node parameters this port reproduces (PKG/config/diffusion_planner.param.yaml, effective YAML defaults) -------
+VELOCITY_SMOOTHING_WINDOW = 8  # yaml l.32
+STOPPING_THRESHOLD = 0.3  # yaml l.33, m/s
+TURN_INDICATOR_KEEP_OFFSET = -1.25  # yaml l.34
+TURN_INDICATOR_HOLD_DURATION_S = 1.0  # yaml l.35 (stateful; see host.postprocess.TurnIndicatorManager)
+TRAJECTORY_DT = 0.1  # postprocessing_utils.cpp:370 (constexpr double dt)
+DELAY_STEP_MAX = OUTPUT_T // 2  # core.cpp:437 clamps delay_step to [0, 40]
+
+# ---- raw input tensors: the InputDataMap of DiffusionPlannerCore::create_input_data (core.cpp:414-595), batch 1 ----
+# All float32 and in the ego (base_link) frame, BEFORE normalization. ``sampled_trajectories`` is already in the
+# normalised state space (x_T: zeros with the default temperature 0), ``delay`` is only read by the single-step graph.
+# The speed-limit masks (lanes_has_speed_limit, route_lanes_has_speed_limit) are not inputs: the inference backend
+# derives them from the normalised speed limits (PKG/include/.../inference/utils.hpp:112-123).
+INPUT_SHAPES: Dict[str, Tuple[int, ...]] = {
+    "sampled_trajectories": (1, MAX_NUM_AGENTS, OUTPUT_T + 1, POSE_DIM),
+    "ego_agent_past": (1, INPUT_T + 1, POSE_DIM),
+    "ego_current_state": (1, EGO_CURRENT_STATE_DIM),
+    "neighbor_agents_past": (1, MAX_NUM_NEIGHBORS, INPUT_T + 1, AGENT_STATE_DIM),
+    "static_objects": (1, NUM_STATIC_OBJECTS, STATIC_OBJECT_DIM),
+    "lanes": (1, NUM_SEGMENTS_IN_LANE, POINTS_PER_SEGMENT, SEGMENT_POINT_DIM),
+    "lanes_speed_limit": (1, NUM_SEGMENTS_IN_LANE, 1),
+    "route_lanes": (1, NUM_SEGMENTS_IN_ROUTE, POINTS_PER_SEGMENT, SEGMENT_POINT_DIM),
+    "route_lanes_speed_limit": (1, NUM_SEGMENTS_IN_ROUTE, 1),
+    "polygons": (1, NUM_POLYGONS, POINTS_PER_POLYGON, 2 + POLYGON_TYPE_NUM),
+    "line_strings": (1, NUM_LINE_STRINGS, POINTS_PER_LINE_STRING, 2 + LINE_STRING_TYPE_NUM),
+    "goal_pose": (1, POSE_DIM),
+    "ego_shape": (1, EGO_SHAPE_DIM),
+    "turn_indicators": (1, INPUT_T + 1),
+    "delay": (1, 1),
+}
+INPUT_NAMES = tuple(INPUT_SHAPES)
+# name -> (shape, dtype): the ModelBase.INPUT_SCHEMA of the API and the server (ttaw API.md section 10)
+INPUT_SCHEMA = {name: (shape, np.float32) for name, shape in INPUT_SHAPES.items()}
+# preprocessing_utils.cpp:34-84 normalises every tensor except these (core.cpp / node.cpp:633-634)
+SKIP_NORMALIZATION = ("ego_shape", "sampled_trajectories", "turn_indicators", "delay")
+# the inputs of the encoder graph, in its input order (HFD diffusion_planner_encoder.onnx)
+ENCODER_INPUTS = ("ego_agent_past", "neighbor_agents_past", "static_objects", "lanes", "lanes_speed_limit",
+                  "lanes_has_speed_limit", "route_lanes", "route_lanes_speed_limit", "route_lanes_has_speed_limit",
+                  "polygons", "line_strings", "goal_pose", "ego_shape", "turn_indicators")
+
+# ---- weight files (HFD; BUNDLE_CONVENTIONS.md section 12) -----------------------------------------------------------
+ENCODER_ONNX = "diffusion_planner_encoder.onnx"
+DECODER_ONNX = "diffusion_planner_decoder.onnx"
+TURN_INDICATOR_ONNX = "diffusion_planner_turn_indicator.onnx"
+PARAM_JSON = "diffusion_planner.param.json"
+WEIGHT_MAJOR_VERSION = 5  # PKG/include/autoware/diffusion_planner/constants.hpp:22 (arg_reader.hpp:54-78)
+FILE_SHA256 = {  # SPEC 1.4
+    ENCODER_ONNX: "2856886a3ed63b963cb18b457876d0bbd8916d345549ee5f199ceb49e3fcca49",
+    DECODER_ONNX: "eb30c0c0c8e80b8460d293d600c7b8c9e21f615ff6ce8de5ed01670c3d1057ca",
+    TURN_INDICATOR_ONNX: "07acfb58a5de1f25587fa86deb39a6de5605f8d93518e97f960ee27145f4a732",
+    PARAM_JSON: "ee3145b68fd1e1e44e532933dfe66cfee4384fbd637382c87ab5190c66a8e268",
+}

code/tt_diffusion_planner/reference/goldens.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Golden tensors of the CPU reference: per-module taps and final outputs of one planning scene.
+
+Two products per scene (``code/scripts/ref_golden.py`` writes both):
+
+- the **full goldens** (``<dir>/<scene>.npz``, 10-25 MB, kept OUT of the bundle, by default under
+  ``research/diffusion-planner/goldens``): the raw inputs, the host features, every encoder tap (mixer taps compacted
+  to the valid entities, with their row indices), the encoding, for each of the 11 decoder evaluations its input
+  ``x`` (all 321 agents, for teacher forcing), its time, its block taps and output (valid agents), the solver
+  iterates, ``final_x0``, the turn pool and logits, the post-processed outputs, and the port's rewrite constants
+  (adaLN tables, pad-relative island constants);
+- the **small goldens** (``tests/goldens/<stem>.outputs.npz``, ~0.1 MB, shipped): ``final_x0`` of the valid agents,
+  the logits, the ego trajectory columns, the turn command and the ego row of every solver iterate.
+
+Tap names follow ``reference.model.TAP_NAMES``; arrays of valid entities carry ``<name>.rows`` (indices into the full
+tensor). Device tests compare TT replay outputs against these, never TT against TT.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from . import config as C
+from ..host import pipeline as hp
+from ..host.postprocess import denoising_steps_ego
+from ..host.solver import solver_plan
+from ..ttaw.golden import TapRegistry, save_goldens
+from . import rewrites as R
+from .pipeline import ReferencePlanner
+
+__all__ = ["scene_goldens", "small_goldens", "lite_goldens", "write_scene", "SMALL_KEYS"]
+
+SMALL_KEYS = ("final_x0", "final_x0.rows", "logit", "trajectory", "turn_command", "denoising_ego")
+MIXER_CATS = ("ego", "neighbor", "lane", "route", "polygon", "line_string")
+
+
+def _rows(valid: np.ndarray) -> np.ndarray:
+    return np.flatnonzero(np.asarray(valid, bool)).astype(np.int32)
+
+
+def scene_goldens(ref: ReferencePlanner, raw: Any, *, params: Optional[Dict[str, Any]] = None) -> Dict[str, np.ndarray]:
+    """Run the reference on one scene and return the full golden dict (numpy)."""
+    taps = TapRegistry()
+    res = ref.run(raw, taps=taps, keep_eval_io=True)
+    prep = res.prepared
+    f = prep.features
+    g: Dict[str, np.ndarray] = {}
+    for k, v in prep.raw.items():
+        g[f"in.{k}"] = v
+    # host features (what the device consumes)
+    for name in ("ego", "neighbor", "neighbor_type", "static", "lane", "lane_attr", "lane_speed", "lane_has_speed",
+                 "route", "route_attr", "route_speed", "route_has_speed", "polygon", "line_string", "goal",
+                 "ego_shape", "turn", "token_valid", "key_valid", "pos"):
+        g[f"host.{name}"] = np.asarray(getattr(f, name))
+    for cat, v in f.valid.items():
+        g[f"host.valid.{cat}"] = np.asarray(v, bool)
+    g["host.agent_valid"] = prep.decoder.agent_valid
+    g["host.current_states"] = prep.decoder.current_states
+    t = taps.to_dict()
+    # encoder taps: mixer internals compacted to the valid entities
+    for cat in MIXER_CATS:
+        rows = _rows(f.valid[cat])
+        for suffix in ("pre", "mixer"):
+            g[f"enc.{cat}.{suffix}"] = t[f"enc.{cat}.{suffix}"][rows]
+            g[f"enc.{cat}.{suffix}.rows"] = rows
+    for name, _ in C.TOKEN_LAYOUT:
+        g[f"enc.{name}"] = t[f"enc.{name}"]
+    g["enc.tokens"] = t["enc.tokens"]
+    for i in range(C.FUSION_DEPTH):
+        g[f"enc.fusion.{i}"] = t[f"enc.fusion.{i}"]
+    g["enc.encoding"] = res.encoding
+    # decoder evaluations: inputs for teacher forcing, outputs and block taps on the valid agents
+    arows = _rows(prep.decoder.agent_valid)
+    g["dec.rows"] = arows
+    g["dec.t"] = np.asarray(res.eval_times, np.float32)
+    g["dec.x_in"] = np.stack(res.eval_inputs).astype(np.float32)          # [11, 321, 81, 4]
+    g["dec.out"] = np.stack(res.eval_outputs)[:, arows].astype(np.float32)
+    for k in range(len(res.eval_times)):
+        g[f"dec.{k}.temb"] = t[f"dec.{k}.temb"][0]
+        g[f"dec.{k}.x"] = t[f"dec.{k}.x"][arows]
+        for i in range(C.DIT_DEPTH):
+            g[f"dec.{k}.block{i}"] = t[f"dec.{k}.block{i}"][arows]
+    g["solver.iterates"] = np.stack(res.denoising_steps).astype(np.float32)[:, arows]
+    g["solver.timesteps"] = np.asarray(res.denoising_timesteps, np.float32)
+    g["final_x0"] = res.final_x0
+    g["turn.pool"] = t["turn.pool"]
+    g["turn.logit"] = res.logit
+    # post-processed outputs (the API's Trajectory)
+    p = {k: spec[3] for k, spec in hp.RUNTIME_PARAMS.items()}
+    p.update(params or {})
+    out = hp.make_output(res.final_x0, res.logit, prep, ref.normalization, p, denoising_steps=res.denoising_steps)
+    g["out.trajectory"] = out.poses
+    g["out.predicted_agents"] = out.predicted_agents
+    g["out.turn_command"] = np.asarray(out.turn_indicator["command"], np.int32)
+    g["out.denoising_ego"] = denoising_steps_ego(np.stack(res.denoising_steps), *ref.normalization.state())
+    # the port's rewrite constants (built in float64, rounded once)
+    plan = solver_plan(C.DPM_SOLVER_STEPS)
+    tab = R.adaln_tables(ref.weights.params, plan.eval_times)
+    g["port.adaln.temb"] = tab.temb
+    for i, blk in enumerate(tab.blocks):
+        for k, v in blk.items():
+            g[f"port.adaln.block{i}.{k}"] = v
+    g["port.adaln.final_gamma"], g["port.adaln.final_beta"] = tab.final_gamma, tab.final_beta
+    for cat in ("ego", "neighbor"):
+        cst = R.island_constants(ref.weights.params, cat)
+        for k in ("gelu_b1", "c0", "t1_pad", "g_pad", "t2_pad", "w_t1_valid"):
+            g[f"port.island.{cat}.{k}"] = getattr(cst, k)
+    g["port.solver"] = np.asarray([[u.order, u.t, u.a, u.b, u.c, u.r0] for u in plan.updates], np.float64)
+    return g
+
+
+LITE_PREFIXES = ("host.valid.", "host.token_valid", "host.agent_valid", "enc.", "dec.rows", "dec.t", "final_x0",
+                 "turn.", "out.", "solver.timesteps")
+
+
+def lite_goldens(g: Dict[str, np.ndarray]) -> Dict[str, np.ndarray]:
+    """The compact per-scene goldens of the public-data instants (~1 MB): validity, the encoder category outputs and
+    the encoding on valid rows, final x0 of the valid agents, logits and the post-processed outputs (no inputs: they
+    stay in ``public_data/inputs``; no mixer or per-evaluation decoder taps)."""
+    out: Dict[str, np.ndarray] = {}
+    tok = np.flatnonzero(g["host.token_valid"])
+    for k, v in g.items():
+        if not k.startswith(LITE_PREFIXES) or k.startswith(("enc.fusion.", "enc.tokens")):
+            continue
+        if k.endswith((".pre", ".mixer", ".pre.rows", ".mixer.rows")):
+            continue
+        out[k] = v
+    for name, _ in C.TOKEN_LAYOUT:
+        rows = np.flatnonzero(g[f"host.valid.{name}"])
+        out[f"enc.{name}"], out[f"enc.{name}.rows"] = g[f"enc.{name}"][rows], rows.astype(np.int32)
+    out["enc.encoding"], out["enc.encoding.rows"] = g["enc.encoding"][tok], tok.astype(np.int32)
+    out["final_x0"] = g["final_x0"][g["dec.rows"]]
+    return out
+
+
+def small_goldens(g: Dict[str, np.ndarray]) -> Dict[str, np.ndarray]:
+    """The shipped subset of a full golden dict (see the module docstring)."""
+    rows = g["dec.rows"]
+    return {"final_x0": g["final_x0"][rows], "final_x0.rows": rows, "logit": g["turn.logit"],
+            "trajectory": g["out.trajectory"], "turn_command": g["out.turn_command"],
+            "denoising_ego": g["out.denoising_ego"]}
+
+
+def write_scene(ref: ReferencePlanner, raw: Any, scene: str, full_dir: Optional[Path], small_dir: Optional[Path],
+                meta: Optional[Dict[str, Any]] = None, *, lite: bool = False) -> Dict[str, Any]:
+    g = scene_goldens(ref, raw)
+    info = {"scene": scene, "created": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"),
+            "weights_sha256": ref.weights.sha256, "solver_steps": C.DPM_SOLVER_STEPS,
+            "valid_counts": {k: int(np.asarray(v).sum()) for k, v in g.items() if k.startswith("host.valid.")},
+            "producer": "tt_diffusion_planner.reference (fp32 CPU, torch)", **(meta or {})}
+    paths = {}
+    if full_dir is not None:
+        tensors = lite_goldens(g) if lite else g
+        info["lite"] = bool(lite)
+        paths["full"] = str(save_goldens(Path(full_dir) / f"{scene}.npz", tensors, info, compress=True))
+    if small_dir is not None:
+        paths["small"] = str(save_goldens(Path(small_dir) / f"{scene}.outputs.npz", small_goldens(g), info,
+                                          compress=True))
+    return {"info": info, "paths": paths, "goldens": g}

code/tt_diffusion_planner/reference/model.py

@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure-PyTorch fp32 re-implementation of the deployed v5.0 graphs (encoder, DiT decoder, turn-indicator head).
+
+Semantics follow the exported ONNX (SPEC 4.2-4.4; tier4/Diffusion-Planner ``encoder.py`` / ``mixer.py`` / ``dit.py``
+/ ``decoder.py`` read for reference, never imported), operation by operation where the order matters for float32:
+attention scales Q before ``Q.K^T`` and adds the ``-inf`` key bias before the softmax; the fusion takes Q from
+``LN1(x)`` but K and V from the un-normalised ``x``; SiLU is ``x * sigmoid(x)``; GELU is exact (erf) everywhere in
+the encoder and in the decoder's ``preproj`` / ``t_embedder``, tanh-approximate in the six DiT MLPs and the final
+projection; every LayerNorm uses epsilon 1e-5.
+
+Inputs are the host features of :mod:`tt_diffusion_planner.host.features` (computed from normalised inputs), so
+this module holds only the network. Weights are the canonical dict of :mod:`.weights` (``w`` is ``[in, out]``).
+Every module output can be recorded with a ``ttaw.golden.TapRegistry`` (names in :data:`TAP_NAMES`); valid-row
+compaction of the taps is left to the caller.
+"""
+from __future__ import annotations
+
+from typing import Dict, Mapping, Optional, Tuple
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+
+from . import config as C
+from ..ttaw.golden import NULL_TAPS, TapRegistry
+
+__all__ = ["Encoder", "Decoder", "TurnHead", "torch_params", "TAP_NAMES"]
+
+Tensor = torch.Tensor
+
+TAP_NAMES = {
+    "enc.<cat>.pre": "mixer categories: token_pre_project output transposed back to [E, 64, 128]",
+    "enc.<cat>.mixer": "mixer categories: output of the 6 MixerBlocks [E, 64, 128]",
+    "enc.<cat>": "category output [E, 256] (masked; route with its position embedding), the fusion input rows",
+    "enc.tokens": "fusion input [564, 256] (category outputs + masked positional embedding)",
+    "enc.fusion.<i>": "fusion block i output [564, 256]",
+    "enc.encoding": "final LayerNorm [564, 256] (the ``encoding`` graph output)",
+    "dec.<k>.temb": "t_embedder output [321, 256] of evaluation k",
+    "dec.<k>.x": "preproj + agent embedding [321, 256]",
+    "dec.<k>.block<i>": "DiT block i output [321, 256]",
+    "dec.<k>.out": "model_output [321, 81, 4]",
+    "turn.pool": "mean of the encoding over the 564 tokens [256]",
+    "turn.logit": "turn_indicator_logit [5]",
+}
+
+
+def torch_params(params: Mapping[str, np.ndarray], dtype: torch.dtype = torch.float32) -> Dict[str, Tensor]:
+    """``{name: tensor}`` copies (the ONNX-backed arrays are read-only)."""
+    return {k: torch.from_numpy(np.array(v, copy=True)).to(dtype) for k, v in params.items()}
+
+
+def _t(a, dtype=torch.float32) -> Tensor:
+    if isinstance(a, torch.Tensor):
+        return a.to(dtype)
+    return torch.from_numpy(np.ascontiguousarray(a)).to(dtype)
+
+
+class _Ops:
+    """Shared building blocks over the canonical parameter dict."""
+
+    def __init__(self, p: Mapping[str, Tensor]):
+        self.p = p
+
+    def linear(self, x: Tensor, name: str) -> Tensor:
+        return torch.matmul(x, self.p[f"{name}.w"]) + self.p[f"{name}.b"]
+
+    def ln(self, x: Tensor, name: str) -> Tensor:
+        return F.layer_norm(x, x.shape[-1:], self.p[f"{name}.gamma"], self.p[f"{name}.beta"], eps=C.LN_EPS)
+
+    def mlp(self, x: Tensor, name: str, approximate: str = "none") -> Tensor:
+        return self.linear(F.gelu(self.linear(x, f"{name}.fc1"), approximate=approximate), f"{name}.fc2")
+
+    def attention(self, q_in: Tensor, kv: Tensor, name_q: str, key_bias: Optional[Tensor]) -> Tensor:
+        """Multi-head attention with 8 heads of 32: ``q_in`` [Sq, 256] -> Q (``name_q`` linear); ``kv`` [Sk, 512] is
+        the already projected K|V; ``key_bias`` [Sk] is 0 / -inf. Returns the heads concatenated [Sq, 256]
+        (before the output projection)."""
+        q = self.linear(q_in, name_q)
+        return self.attend(q, kv[:, :C.HIDDEN_DIM], kv[:, C.HIDDEN_DIM:], key_bias)
+
+    @staticmethod
+    def attend(q: Tensor, k: Tensor, v: Tensor, key_bias: Optional[Tensor]) -> Tensor:
+        sq, sk = q.shape[0], k.shape[0]
+        qh = q.reshape(sq, C.NUM_HEADS, C.HEAD_DIM).transpose(0, 1) * float(C.ATTN_SCALE)  # [H, Sq, 32]
+        kh = k.reshape(sk, C.NUM_HEADS, C.HEAD_DIM).permute(1, 2, 0)                       # [H, 32, Sk]
+        vh = v.reshape(sk, C.NUM_HEADS, C.HEAD_DIM).transpose(0, 1)                        # [H, Sk, 32]
+        scores = torch.matmul(qh, kh)
+        if key_bias is not None:
+            scores = scores + key_bias.reshape(1, 1, sk)
+        o = torch.matmul(torch.softmax(scores, dim=-1), vh)                                 # [H, Sq, 32]
+        return o.transpose(0, 1).reshape(sq, C.HIDDEN_DIM)
+
+
+def _key_bias(valid: np.ndarray) -> Tensor:
+    b = np.where(np.asarray(valid, bool), np.float32(0.0), np.float32(-np.inf)).astype(np.float32)
+    return torch.from_numpy(b)
+
+
+class Encoder(_Ops):
+    """``diffusion_planner_encoder.onnx`` on host features -> ``encoding`` [564, 256]."""
+
+    def mixer_trunk(self, x: Tensor, mod: str, taps: TapRegistry, cat: str) -> Tensor:
+        """channel_pre (C_in -> 128 -> 128), token_pre over the time / point axis (T -> 64 -> 64), 6 MixerBlocks,
+        mean over the 64 tokens -> [E, 128]."""
+        N = f"encoder.{mod}"
+        x = self.mlp(x, f"{N}.channel_pre_project")                                   # [E, T, 128]
+        x = self.mlp(x.transpose(1, 2), f"{N}.token_pre_project").transpose(1, 2)     # [E, 64, 128]
+        taps.tap(f"enc.{cat}.pre", x)
+        for i in range(C.MIXER_DEPTH):
+            B = f"{N}.blocks.{i}"
+            y = self.mlp(self.ln(x, f"{B}.norm1").transpose(1, 2), f"{B}.tokens_mlp").transpose(1, 2)
+            x = x + y
+            x = x + self.mlp(self.ln(x, f"{B}.norm2"), f"{B}.channels_mlp")
+        taps.tap(f"enc.{cat}.mixer", x)
+        return x.mean(dim=1)
+
+    def head(self, x: Tensor, mod: str) -> Tensor:
+        """LayerNorm(128) + emb_project (128 -> 256 -> 256)."""
+        return self.mlp(self.ln(x, f"encoder.{mod}.norm"), f"encoder.{mod}.emb_project")
+
+    def lanes(self, x: Tensor, attr: Tensor, speed: Tensor, has_speed: Tensor, valid: Tensor, mod: str,
+              taps: TapRegistry, cat: str) -> Tensor:
+        N = f"encoder.{mod}"
+        h = self.mixer_trunk(x, mod, taps, cat)
+        speed_emb = torch.where(has_speed, self.linear(speed, f"{N}.speed_limit_emb"),
+                                self.p[f"{N}.unknown_speed_emb"].reshape(1, -1))
+        h = h + speed_emb + self.linear(attr, f"{N}.attribute_emb")
+        return self.head(h, mod) * valid
+
+    def small(self, x: Tensor, mod: str) -> Tensor:
+        """goal / ego-shape / turn-indicator encoders: channel MLP -> LayerNorm -> projection."""
+        return self.head(self.mlp(x, f"encoder.{mod}.channel_pre_project"), mod)
+
+    def forward(self, f, taps: TapRegistry = NULL_TAPS) -> Tensor:
+        valid = {k: _t(v.astype(np.float32)).reshape(-1, 1) for k, v in f.valid.items()}
+        out: Dict[str, Tensor] = {}
+        e = self.mixer_trunk(_t(f.ego)[None], "ego_encoder", taps, "ego")
+        out["ego"] = self.head(e, "ego_encoder")
+        n = self.mixer_trunk(_t(f.neighbor), "neighbor_encoder", taps, "neighbor")
+        n = n + self.linear(_t(f.neighbor_type), "encoder.neighbor_encoder.type_emb")
+        out["neighbor"] = self.head(n, "neighbor_encoder") * valid["neighbor"]
+        out["static"] = self.mlp(_t(f.static), "encoder.static_encoder.projection") * valid["static"]
+        out["lane"] = self.lanes(_t(f.lane), _t(f.lane_attr), _t(f.lane_speed), torch.from_numpy(f.lane_has_speed),
+                                 valid["lane"], "lane_encoder", taps, "lane")
+        route = self.lanes(_t(f.route), _t(f.route_attr), _t(f.route_speed), torch.from_numpy(f.route_has_speed),
+                           valid["route"], "route_encoder", taps, "route")
+        out["route"] = route + self.p["encoder.route_position_embedding"] * valid["route"]
+        poly = self.mixer_trunk(_t(f.polygon), "polygon_encoder", taps, "polygon")
+        out["polygon"] = self.head(poly, "polygon_encoder") * valid["polygon"]
+        ls = self.mixer_trunk(_t(f.line_string), "line_string_encoder", taps, "line_string")
+        out["line_string"] = self.head(ls, "line_string_encoder") * valid["line_string"]
+        out["goal"] = self.small(_t(f.goal)[None], "goal_pose_encoder")
+        out["ego_shape"] = self.small(_t(f.ego_shape)[None], "ego_shape_encoder")
+        out["turn"] = self.small(_t(f.turn)[None], "turn_indicator_encoder")
+        for name, _ in C.TOKEN_LAYOUT:
+            taps.tap(f"enc.{name}", out[name])
+        x = torch.cat([out[name] for name, _ in C.TOKEN_LAYOUT], dim=0)              # [564, 256]
+        pos = self.linear(_t(f.pos), "encoder.pos_emb") * _t(f.token_valid.astype(np.float32)).reshape(-1, 1)
+        x = taps.tap("enc.tokens", x + pos)
+        key_bias = _key_bias(f.key_valid)
+        for i in range(C.FUSION_DEPTH):
+            B = f"encoder.fusion.blocks.{i}"
+            kv = self.linear(x, f"{B}.attn.kv")                       # K and V from the un-normalised x
+            heads = self.attention(self.ln(x, f"{B}.norm1"), kv, f"{B}.attn.q", key_bias)
+            x = x + self.linear(heads, f"{B}.attn.out")
+            x = x + self.mlp(self.ln(x, f"{B}.norm2"), f"{B}.mlp")
+            taps.tap(f"enc.fusion.{i}", x)
+        return taps.tap("enc.encoding", self.ln(x, "encoder.fusion.norm"))
+
+
+class Decoder(_Ops):
+    """``diffusion_planner_decoder.onnx``: one DiT evaluation (x0 prediction) per call.
+
+    ``cross_kv(encoding)`` computes the K|V of the three cross-attention blocks once per plan (the decoder graph
+    recomputes the same product at every call; hoisting it is exact, SPEC 4.6.1)."""
+
+    def cross_kv(self, encoding: Tensor) -> Tuple[Tensor, ...]:
+        return tuple(self.linear(encoding, f"decoder.dit.blocks.{i}.cross_attn.kv") for i in range(C.DIT_DEPTH))
+
+    def time_embedding(self, t, agents: int = C.MAX_NUM_AGENTS) -> Tensor:
+        """t_embedder of the 81 per-point diffusion times [P, 81] (uniform in the multi-step mode) -> [P, 256]."""
+        tt = torch.full((agents, C.DIT_TIME_DIM), float(np.float32(t))) if np.ndim(t) == 0 else _t(t)
+        return self.mlp(tt, "decoder.dit.t_embedder")
+
+    def forward(self, x_t: np.ndarray, t, kv: Tuple[Tensor, ...], agent_valid: np.ndarray,
+                taps: TapRegistry = NULL_TAPS, prefix: str = "dec") -> Tensor:
+        """``x_t`` [P, 81, 4] with P = 321 as exported, or any agent bucket ``P >= 1 + valid neighbours`` (ego first;
+        exact for the agents present, SPEC 4.6.4); ``agent_valid`` [P]; ``t`` a scalar time (or [P, 81])."""
+        P = int(np.shape(x_t)[0])
+        x = self.mlp(_t(x_t).reshape(P, C.DIT_INPUT_DIM), "decoder.dit.preproj")
+        c = taps.tap(f"{prefix}.temb", self.time_embedding(t, P))
+        emb = self.p["decoder.dit.agent_embedding"]
+        x = x + torch.cat([emb[0:1], emb[1:2].expand(P - 1, -1)], dim=0)
+        x = taps.tap(f"{prefix}.x", x)
+        silu_c = c * torch.sigmoid(c)
+        key_bias = _key_bias(agent_valid)
+        for i in range(C.DIT_DEPTH):
+            B = f"decoder.dit.blocks.{i}"
+            mod = self.linear(silu_c, f"{B}.adaLN_modulation")
+            shift_msa, scale_msa, gate_msa, shift_mlp, scale_mlp, gate_mlp = torch.split(mod, C.HIDDEN_DIM, dim=-1)
+            h = self.ln(x, f"{B}.norm1") * (scale_msa + 1.0) + shift_msa
+            qkv = self.linear(h, f"{B}.attn.qkv")
+            q, k, v = torch.split(qkv, C.HIDDEN_DIM, dim=-1)
+            x = x + gate_msa * self.linear(self.attend(q, k, v, key_bias), f"{B}.attn.out")
+            h = self.ln(x, f"{B}.norm2") * (scale_mlp + 1.0) + shift_mlp
+            x = x + gate_mlp * self.mlp(h, f"{B}.mlp1", "tanh")
+            heads = self.attention(self.ln(x, f"{B}.norm3"), kv[i], f"{B}.cross_attn.q", None)  # no key mask
+            x = x + self.linear(heads, f"{B}.cross_attn.out")
+            x = x + self.mlp(self.ln(x, f"{B}.norm4"), f"{B}.mlp2", "tanh")
+            taps.tap(f"{prefix}.block{i}", x)
+        Fn = "decoder.dit.final_layer"
+        shift, scale = torch.split(self.linear(silu_c, f"{Fn}.adaLN_modulation"), C.HIDDEN_DIM, dim=-1)
+        h = self.ln(x, f"{Fn}.norm_final") * (scale + 1.0) + shift
+        h = F.gelu(self.linear(self.ln(h, f"{Fn}.proj.0"), f"{Fn}.proj.1"), approximate="tanh")
+        out = self.linear(self.ln(h, f"{Fn}.proj.3"), f"{Fn}.proj.4").reshape(P, C.OUTPUT_T + 1, C.POSE_DIM)
+        return taps.tap(f"{prefix}.out", out)
+
+
+class TurnHead(_Ops):
+    """``diffusion_planner_turn_indicator.onnx``: ``W [272 -> 5]`` over ``final_x0[0, 1::10, :2]`` (16 values) and the
+    token mean of the encoding (256)."""
+
+    def forward(self, encoding: Tensor, final_x0: np.ndarray, taps: TapRegistry = NULL_TAPS) -> Tensor:
+        pool = taps.tap("turn.pool", encoding.mean(dim=0))
+        ego = _t(final_x0)[0, 1::10, :2].reshape(-1)
+        feat = torch.cat([ego, pool], dim=0)[None]
+        return taps.tap("turn.logit", self.linear(feat, "decoder.turn_indicator_predictor")[0])

code/tt_diffusion_planner/reference/ort.py

@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: Apache-2.0
+"""ONNX Runtime on the shipped v5.0 ONNX files: the oracle of the CPU reference (research and tests only;
+onnxruntime is not a runtime dependency of the bundle or the image).
+
+``OrtPlanner.run(raw)`` is the Autoware ``multi_step`` pipeline with ORT as the backend (a port of the verified
+research script ``research/diffusion-planner/scripts/dp_reference.py``): the node's normalization and speed masks,
+encoder.onnx, the DPM-Solver++(2M) loop of :mod:`tt_diffusion_planner.host.solver` calling decoder.onnx 11 times,
+then turn_indicator.onnx. ``taps=[...]`` exposes intermediate tensors of the encoder / decoder graphs by ONNX tensor
+name (the decoder taps are recorded per evaluation), for the per-module PCC test of the reference.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Sequence
+
+import numpy as np
+
+from . import config as C
+from ..host.normalize import normalize_inputs, speed_masks
+from ..host.solver import apply_prefix_constraint, dpm_solver_sample
+from ..host.features import decoder_masks
+from ..ttaw import io as tio
+from .weights import load_param_json
+
+__all__ = ["OrtPlanner", "OrtResult", "available"]
+
+
+def available() -> bool:
+    import importlib.util
+
+    return importlib.util.find_spec("onnxruntime") is not None
+
+
+def _session(model: Any, threads: int, optimize: bool = True):
+    import onnxruntime as ort
+
+    so = ort.SessionOptions()
+    so.graph_optimization_level = (ort.GraphOptimizationLevel.ORT_ENABLE_ALL if optimize
+                                   else ort.GraphOptimizationLevel.ORT_DISABLE_ALL)
+    so.intra_op_num_threads = threads
+    so.inter_op_num_threads = 1
+    so.log_severity_level = 3
+    src = model.SerializeToString() if hasattr(model, "SerializeToString") else str(model)
+    return ort.InferenceSession(src, so, providers=["CPUExecutionProvider"])
+
+
+def _with_outputs(path: Path, names: Sequence[str]):
+    """The model with extra graph outputs (intermediate tensors by name)."""
+    import onnx
+
+    m = onnx.load(str(path))
+    have = {o.name for o in m.graph.output}
+    m.graph.output.extend([onnx.ValueInfoProto(name=n) for n in names if n not in have])
+    return m
+
+
+@dataclass
+class OrtResult:
+    norm: Dict[str, np.ndarray]
+    encoding: np.ndarray                 # [1, 564, 256]
+    final_x0: np.ndarray                 # [1, 321, 81, 4]
+    logit: np.ndarray                    # [1, 5]
+    denoising_steps: List[np.ndarray]
+    denoising_timesteps: List[float]
+    eval_times: List[float]
+    eval_inputs: List[np.ndarray] = field(default_factory=list)
+    eval_outputs: List[np.ndarray] = field(default_factory=list)
+    taps: Dict[str, np.ndarray] = field(default_factory=dict)
+
+
+class OrtPlanner:
+    """``OrtPlanner(weights_dir, threads=4, encoder_taps=(...), decoder_taps=(...))``. With taps the sessions run
+    without graph optimizations (every intermediate kept as computed); without, ``ORT_ENABLE_ALL`` like
+    ``onnxruntime_inference.cpp:172``."""
+
+    def __init__(self, weights_dir: Path, *, threads: int = 4, encoder_taps: Sequence[str] = (),
+                 decoder_taps: Sequence[str] = (), turn_taps: Sequence[str] = ()):
+        wd = Path(weights_dir)
+        self.normalization = load_param_json(wd / C.PARAM_JSON)
+        self.encoder_taps, self.decoder_taps, self.turn_taps = list(encoder_taps), list(decoder_taps), list(turn_taps)
+        opt = not (encoder_taps or decoder_taps or turn_taps)
+        self.enc = _session(_with_outputs(wd / C.ENCODER_ONNX, self.encoder_taps), threads, opt)
+        self.dec = _session(_with_outputs(wd / C.DECODER_ONNX, self.decoder_taps), threads, opt)
+        self.turn = _session(_with_outputs(wd / C.TURN_INDICATOR_ONNX, self.turn_taps), threads, opt)
+
+    def normalize(self, raw: Any) -> Dict[str, np.ndarray]:
+        arrays = tio.load_named_arrays(raw, C.INPUT_SCHEMA)
+        norm = normalize_inputs(arrays, self.normalization.observation)
+        norm.update(speed_masks(norm))
+        return norm
+
+    def encode(self, norm: Dict[str, np.ndarray]) -> Dict[str, np.ndarray]:
+        feed = {k: norm[k] for k in C.ENCODER_INPUTS}
+        outs = self.enc.run(["encoding"] + self.encoder_taps, feed)
+        return dict(zip(["encoding"] + self.encoder_taps, outs))
+
+    def decode(self, encoding: np.ndarray, x: np.ndarray, t, neighbor_agents_past: np.ndarray) -> Dict[str, Any]:
+        dt = np.full((1, C.MAX_NUM_AGENTS, C.OUTPUT_T + 1, 1), np.float32(t), np.float32)
+        feed = {"encoding": encoding, "sampled_trajectories": np.asarray(x, np.float32).reshape(
+            1, C.MAX_NUM_AGENTS, C.OUTPUT_T + 1, C.POSE_DIM), "diffusion_time": dt,
+            "neighbor_agents_past": neighbor_agents_past}
+        outs = self.dec.run(["model_output"] + self.decoder_taps, feed)
+        return dict(zip(["model_output"] + self.decoder_taps, outs))
+
+    def turn_logit(self, encoding: np.ndarray, final_x0: np.ndarray) -> Dict[str, np.ndarray]:
+        outs = self.turn.run(["turn_indicator_logit"] + self.turn_taps,
+                             {"encoding": encoding, "final_x0": np.asarray(final_x0, np.float32)})
+        return dict(zip(["turn_indicator_logit"] + self.turn_taps, outs))
+
+    def run(self, raw: Any, *, steps: int = C.DPM_SOLVER_STEPS, keep_eval_io: bool = False) -> OrtResult:
+        norm = self.normalize(raw)
+        enc = self.encode(norm)
+        encoding = enc["encoding"]
+        taps: Dict[str, np.ndarray] = {f"enc:{k}": v for k, v in enc.items() if k != "encoding"}
+        cs = decoder_masks(norm).current_states
+        nb = norm["neighbor_agents_past"]
+        eval_in: List[np.ndarray] = []
+        eval_out: List[np.ndarray] = []
+
+        def model_fn(x: np.ndarray, t) -> np.ndarray:
+            k = len(eval_out)
+            out = self.decode(encoding, x, t, nb)
+            for name in self.decoder_taps:
+                taps[f"dec{k}:{name}"] = out[name]
+            y = out["model_output"][0]
+            eval_out.append(y if keep_eval_io else np.empty(0))
+            if keep_eval_io:
+                eval_in.append(np.array(x, np.float32, copy=True))
+            return y
+
+        res = dpm_solver_sample(norm["sampled_trajectories"][0], model_fn,
+                                lambda x: apply_prefix_constraint(x, cs), steps)
+        tl = self.turn_logit(encoding, res.final_x[None])
+        taps.update({f"turn:{k}": v for k, v in tl.items() if k != "turn_indicator_logit"})
+        return OrtResult(norm, encoding, res.final_x[None], tl["turn_indicator_logit"], res.denoising_steps,
+                         res.denoising_timesteps, res.eval_times, eval_in, eval_out if keep_eval_io else [], taps)

code/tt_diffusion_planner/reference/pipeline.py

@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The fp32 CPU reference planner: host pre-processing -> encoder -> DPM-Solver++(2M) over the DiT decoder (11
+evaluations) -> turn head -> host post-processing, i.e. the Autoware ``multi_step`` mode with guidance off.
+
+    from tt_diffusion_planner.reference import ReferencePlanner
+    ref = ReferencePlanner()                                   # weights: find_weights_dir() or weights_dir=...
+    out = ref(inputs="code/tt_diffusion_planner/samples/kashiwanoha_dense.npz")    # ttaw.outputs.Trajectory
+    res = ref.run(raw_inputs, taps=TapRegistry())              # every intermediate (golden generation)
+
+``__call__`` returns exactly what the device model returns (same ``host.prepare`` / ``host.make_output``), so the
+stored ``samples/<stem>.reference.json`` is this class's ``to_dict()``.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+import torch
+
+from . import config as C
+from ..host import pipeline as hp
+from ..host.solver import apply_prefix_constraint, dpm_solver_sample
+from ..ttaw import io as tio
+from ..ttaw.golden import NULL_TAPS, TapRegistry
+from .model import Decoder, Encoder, TurnHead, torch_params
+from .weights import PlannerWeights, find_weights_dir, load_weights
+
+__all__ = ["ReferencePlanner", "ReferenceResult"]
+
+MODEL_NAME = "diffusion-planner-p150"
+
+
+@dataclass
+class ReferenceResult:
+    prepared: hp.Prepared
+    encoding: np.ndarray            # [564, 256]
+    final_x0: np.ndarray            # [321, 81, 4] normalised
+    logit: np.ndarray               # [5]
+    denoising_steps: List[np.ndarray]
+    denoising_timesteps: List[float]
+    eval_times: List[float]
+    eval_inputs: List[np.ndarray] = field(default_factory=list)   # x fed to each decoder evaluation
+    eval_outputs: List[np.ndarray] = field(default_factory=list)  # model_output of each evaluation
+    timing_ms: Dict[str, float] = field(default_factory=dict)
+
+
+class ReferencePlanner:
+    """CPU fp32 reference of the deployed network plus the shared host code. ``threads`` bounds torch's intra-op
+    threads (the workspace rule is <= 4)."""
+
+    def __init__(self, weights_dir: Optional[str] = None, *, weights: Optional[PlannerWeights] = None,
+                 threads: Optional[int] = 4, steps: int = C.DPM_SOLVER_STEPS):
+        if weights is None:
+            wd = find_weights_dir(weights_dir)
+            if wd is None:
+                raise FileNotFoundError("Diffusion Planner v5.0 weights not found: pass weights_dir= or set "
+                                        "DIFFUSION_PLANNER_WEIGHTS_DIR")
+            weights = load_weights(wd)
+        self.weights = weights
+        self.normalization = weights.normalization
+        if threads:
+            torch.set_num_threads(int(threads))
+        p = torch_params(weights.params)
+        self.encoder, self.decoder, self.turn = Encoder(p), Decoder(p), TurnHead(p)
+        self.steps = steps
+
+    # ---- network ---------------------------------------------------------------------------------------------
+    @torch.no_grad()
+    def run(self, raw: Any, *, taps: TapRegistry = NULL_TAPS, keep_eval_io: bool = False) -> ReferenceResult:
+        """One plan on raw ONNX-named inputs (mapping, ``.npz`` path / bytes or the JSON envelope)."""
+        arrays = tio.load_named_arrays(raw, C.INPUT_SCHEMA)
+        t0 = time.perf_counter()
+        prep = hp.prepare(arrays, self.normalization.observation)
+        t1 = time.perf_counter()
+        encoding = self.encoder.forward(prep.features, taps)
+        t2 = time.perf_counter()
+        kv = self.decoder.cross_kv(encoding)
+        cs = prep.decoder.current_states
+        eval_in: List[np.ndarray] = []
+        eval_out: List[np.ndarray] = []
+
+        def model_fn(x: np.ndarray, t) -> np.ndarray:
+            k = len(eval_out)
+            y = self.decoder.forward(x, t, kv, prep.decoder.agent_valid, taps, prefix=f"dec.{k}").numpy()
+            if keep_eval_io:
+                eval_in.append(x.copy())
+            eval_out.append(y if keep_eval_io else np.empty(0))
+            return y
+
+        res = dpm_solver_sample(prep.x_T, model_fn, lambda x: apply_prefix_constraint(x, cs), self.steps)
+        t3 = time.perf_counter()
+        logit = self.turn.forward(encoding, res.final_x, taps).numpy()
+        t4 = time.perf_counter()
+        for k, x in enumerate(res.denoising_steps):
+            taps.tap(f"solver.x{k}", x)
+        taps.tap("final_x0", res.final_x)
+        return ReferenceResult(prep, encoding.numpy(), res.final_x, logit, res.denoising_steps,
+                               res.denoising_timesteps, res.eval_times, eval_in, eval_out if keep_eval_io else [],
+                               {"preprocess": (t1 - t0) * 1e3, "encoder": (t2 - t1) * 1e3, "solver": (t3 - t2) * 1e3,
+                                "turn": (t4 - t3) * 1e3})
+
+    # ---- the API-shaped call ----------------------------------------------------------------------------------
+    def __call__(self, inputs: Any, **params: Any):
+        """``model(inputs=...)`` of the CPU reference: the same host pre / post-processing as the device model."""
+        p = {k: spec[3] for k, spec in hp.RUNTIME_PARAMS.items()}
+        unknown = sorted(set(params) - set(p))
+        if unknown:
+            raise tio.InputError(f"unknown parameter(s) {unknown}; allowed: {sorted(p)}")
+        p.update(params)
+        t0 = time.perf_counter()
+        res = self.run(inputs)
+        total = (time.perf_counter() - t0) * 1e3
+        steps = res.denoising_steps if p.get("return_denoising_steps") else None
+        return hp.make_output(res.final_x0, res.logit, res.prepared, self.normalization, p, model=MODEL_NAME,
+                              denoising_steps=steps, timing_ms={**res.timing_ms, "total": total},
+                              meta={"reference": "fp32 CPU (torch)"})
+
+    @staticmethod
+    def sample_path(name: str = "kashiwanoha_dense.npz") -> Path:
+        return Path(__file__).resolve().parents[1] / "samples" / name

code/tt_diffusion_planner/reference/rewrites.py

@@ -0,0 +1,183 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Exact rewrites of the deployed graph that the TT port applies, as constants and CPU forwards (SPEC 4.6, PLAN 2.12).
+
+Each rewrite is exact in real arithmetic; its constants are computed in float64 from the float32 weights and rounded
+once to float32 (the "fold in fp64, round once" rule of ``ttaw.weights``). The CPU forwards here use them and are
+tested against the as-exported :mod:`.model` (``tests/test_reference_host.py``), so the device port has a CPU oracle in
+its own parameterisation.
+
+1. **Per-step adaLN tables folded into the LayerNorm affine** (SPEC 4.6.2, 8.1). With a uniform diffusion time (the
+   multi-step mode) the t-embedding and every adaLN output are the same for all 321 agents and depend only on t, so
+   for the 11 evaluation times ``modulate(LN(x; g, b), shift, scale) = LN(x; g (1 + scale), b (1 + scale) + shift)``
+   and the gates are per-step ``[256]`` rows. :func:`adaln_tables` builds them for ``SolverPlan.eval_times``.
+2. **Cross-attention K/V hoisted** (SPEC 4.6.1): ``encoding @ W_kv + b_kv`` of the three blocks once per plan
+   (the decoder graph recomputes it at each of the 11 calls).
+3. **Pad-relative fp32 pre-projection island** (SPEC 4.6.7, probe P12): after the in-graph history truncation the
+   ego (rows 6..30) and neighbour (rows 0..24) inputs of ``channel_pre_project`` are zero rows, which all map to
+   ``c0 = fc2(gelu(b1)) + b2``. With the all-zero ("pad") agent's outputs ``t1_pad = b_t1 + c0 (x) sum_t W_t1[t]``,
+   ``g_pad = gelu(t1_pad)``, ``t2_pad = g_pad @ W_t2 + b_t2`` the island becomes
+   ``t1 = t1_pad + (z_valid - c0)^T @ W_t1[valid rows]`` and ``t2 = t2_pad + (gelu(t1) - g_pad) @ W_t2``, so the
+   device's TF32-like fp32 matmuls only see deviations from the pad agent (P12: deviation PCC 0.995706 -> 0.999991
+   on ``straight``). ``gelu_b1 = gelu(b_c1)`` also lets ``channel_pre`` itself run pad-relative:
+   ``z - c0 = (gelu(x @ W_c1 + b_c1) - gelu_b1) @ W_c2``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Mapping, Sequence, Tuple
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+
+from . import config as C
+from .model import Decoder, _t
+
+__all__ = ["AdaLNTables", "adaln_tables", "decoder_forward_folded", "IslandConstants", "island_constants",
+           "island_forward_pad_relative", "island_forward_exported", "cross_kv"]
+
+
+# ---- 1. adaLN tables ---------------------------------------------------------------------------------------------
+@dataclass
+class AdaLNTables:
+    """float32 tables for K evaluation times: ``temb [K, 256]``; per DiT block ``i``: ``norm1_gamma``,
+    ``norm1_beta``, ``gate_msa``, ``norm2_gamma``, ``norm2_beta``, ``gate_mlp`` ``[K, 256]``; the final layer's
+    ``final_gamma`` / ``final_beta`` ``[K, 256]``."""
+
+    eval_times: Tuple[float, ...]
+    temb: np.ndarray
+    blocks: Tuple[Dict[str, np.ndarray], ...]
+    final_gamma: np.ndarray
+    final_beta: np.ndarray
+
+
+def adaln_tables(params: Mapping[str, np.ndarray], eval_times: Sequence[float]) -> AdaLNTables:
+    p = {k: torch.from_numpy(np.array(v, np.float64)) for k, v in params.items() if k.startswith("decoder.dit")}
+
+    def lin(x, n):
+        return x @ p[f"{n}.w"] + p[f"{n}.b"]
+
+    t = torch.tensor([[float(np.float32(v))] * C.DIT_TIME_DIM for v in eval_times], dtype=torch.float64)
+    c = lin(F.gelu(lin(t, "decoder.dit.t_embedder.fc1")), "decoder.dit.t_embedder.fc2")      # [K, 256]
+    silu = c * torch.sigmoid(c)
+    blocks = []
+    for i in range(C.DIT_DEPTH):
+        B = f"decoder.dit.blocks.{i}"
+        sh_msa, sc_msa, g_msa, sh_mlp, sc_mlp, g_mlp = torch.split(lin(silu, f"{B}.adaLN_modulation"), C.HIDDEN_DIM, -1)
+        g1, b1 = p[f"{B}.norm1.gamma"], p[f"{B}.norm1.beta"]
+        g2, b2 = p[f"{B}.norm2.gamma"], p[f"{B}.norm2.beta"]
+        blocks.append({k: v.to(torch.float32).numpy() for k, v in {
+            "norm1_gamma": g1 * (1 + sc_msa), "norm1_beta": b1 * (1 + sc_msa) + sh_msa, "gate_msa": g_msa,
+            "norm2_gamma": g2 * (1 + sc_mlp), "norm2_beta": b2 * (1 + sc_mlp) + sh_mlp, "gate_mlp": g_mlp}.items()})
+    Fn = "decoder.dit.final_layer"
+    sh, sc = torch.split(lin(silu, f"{Fn}.adaLN_modulation"), C.HIDDEN_DIM, -1)
+    gf, bf = p[f"{Fn}.norm_final.gamma"], p[f"{Fn}.norm_final.beta"]
+    return AdaLNTables(tuple(float(v) for v in eval_times), c.to(torch.float32).numpy(), tuple(blocks),
+                       (gf * (1 + sc)).to(torch.float32).numpy(), (bf * (1 + sc) + sh).to(torch.float32).numpy())
+
+
+def cross_kv(params: Mapping[str, np.ndarray], encoding: np.ndarray) -> Tuple[np.ndarray, ...]:
+    """Hoisted cross-attention K|V ``[564, 512]`` of each DiT block (float32 matmul, as the exported graph)."""
+    enc = np.asarray(encoding, np.float32)
+    return tuple((enc @ params[f"decoder.dit.blocks.{i}.cross_attn.kv.w"]
+                  + params[f"decoder.dit.blocks.{i}.cross_attn.kv.b"]).astype(np.float32) for i in range(C.DIT_DEPTH))
+
+
+@torch.no_grad()
+def decoder_forward_folded(dec: Decoder, tables: AdaLNTables, k: int, x_t: np.ndarray, kv: Sequence[torch.Tensor],
+                           agent_valid: np.ndarray) -> torch.Tensor:
+    """One decoder evaluation with the step-``k`` tables: LayerNorms with folded affine (no SiLU / adaLN matmuls),
+    gates as constant rows. Same result as ``Decoder.forward`` up to float32 rounding."""
+    from .model import _key_bias
+
+    P = int(np.shape(x_t)[0])
+    x = dec.mlp(_t(x_t).reshape(P, C.DIT_INPUT_DIM), "decoder.dit.preproj")
+    emb = dec.p["decoder.dit.agent_embedding"]
+    x = x + torch.cat([emb[0:1], emb[1:2].expand(P - 1, -1)], dim=0)
+    key_bias = _key_bias(agent_valid)
+
+    def ln_folded(h, gamma, beta):
+        return F.layer_norm(h, h.shape[-1:], _t(gamma), _t(beta), eps=C.LN_EPS)
+
+    for i in range(C.DIT_DEPTH):
+        B, T = f"decoder.dit.blocks.{i}", tables.blocks[i]
+        h = ln_folded(x, T["norm1_gamma"][k], T["norm1_beta"][k])
+        q, kk, v = torch.split(dec.linear(h, f"{B}.attn.qkv"), C.HIDDEN_DIM, dim=-1)
+        x = x + _t(T["gate_msa"][k]) * dec.linear(dec.attend(q, kk, v, key_bias), f"{B}.attn.out")
+        h = ln_folded(x, T["norm2_gamma"][k], T["norm2_beta"][k])
+        x = x + _t(T["gate_mlp"][k]) * dec.mlp(h, f"{B}.mlp1", "tanh")
+        heads = dec.attention(dec.ln(x, f"{B}.norm3"), kv[i], f"{B}.cross_attn.q", None)
+        x = x + dec.linear(heads, f"{B}.cross_attn.out")
+        x = x + dec.mlp(dec.ln(x, f"{B}.norm4"), f"{B}.mlp2", "tanh")
+    Fn = "decoder.dit.final_layer"
+    h = ln_folded(x, tables.final_gamma[k], tables.final_beta[k])
+    h = F.gelu(dec.linear(dec.ln(h, f"{Fn}.proj.0"), f"{Fn}.proj.1"), approximate="tanh")
+    return dec.linear(dec.ln(h, f"{Fn}.proj.3"), f"{Fn}.proj.4").reshape(P, C.OUTPUT_T + 1, C.POSE_DIM)
+
+
+# ---- 3. pad-relative island ---------------------------------------------------------------------------------------
+@dataclass
+class IslandConstants:
+    """Pad-agent constants of one pre-projection island (float32, built in float64). ``valid_rows`` are the time
+    rows that can be non-zero after the truncation (ego 0..5, neighbours 25..30); ``w_t1_valid`` is
+    ``W_t1[valid_rows]`` ``[6, 64]``."""
+
+    category: str
+    valid_rows: Tuple[int, ...]
+    gelu_b1: np.ndarray    # [128]   gelu(b_c1): channel_pre's first activation of a zero row
+    c0: np.ndarray         # [128]   channel_pre of a zero row
+    t1_pad: np.ndarray     # [128, 64]
+    g_pad: np.ndarray      # [128, 64]
+    t2_pad: np.ndarray     # [128, 64]
+    w_t1_valid: np.ndarray  # [6, 64]
+
+
+ISLAND_ROWS = {"neighbor": tuple(range(C.NEIGHBOR_HISTORY_KEEP.start, C.NEIGHBOR_HISTORY_KEEP.stop)),
+               "ego": tuple(range(C.EGO_HISTORY_KEEP.start, C.EGO_HISTORY_KEEP.stop))}
+ISLAND_MODULE = {"neighbor": "encoder.neighbor_encoder", "ego": "encoder.ego_encoder"}
+
+
+def island_constants(params: Mapping[str, np.ndarray], category: str) -> IslandConstants:
+    N = ISLAND_MODULE[category]
+    w = {k: torch.from_numpy(np.array(v, np.float64)) for k, v in params.items() if k.startswith(N + ".")}
+    gelu_b1 = F.gelu(w[f"{N}.channel_pre_project.fc1.b"])
+    c0 = gelu_b1 @ w[f"{N}.channel_pre_project.fc2.w"] + w[f"{N}.channel_pre_project.fc2.b"]
+    w_t1 = w[f"{N}.token_pre_project.fc1.w"]                                       # [31, 64]
+    t1_pad = w[f"{N}.token_pre_project.fc1.b"][None, :] + c0[:, None] * w_t1.sum(0)[None, :]
+    g_pad = F.gelu(t1_pad)
+    t2_pad = g_pad @ w[f"{N}.token_pre_project.fc2.w"] + w[f"{N}.token_pre_project.fc2.b"]
+    rows = ISLAND_ROWS[category]
+    f32 = lambda t: t.to(torch.float32).numpy()  # noqa: E731
+    return IslandConstants(category, rows, f32(gelu_b1), f32(c0), f32(t1_pad), f32(g_pad), f32(t2_pad),
+                           f32(w_t1[list(rows)]))
+
+
+def island_forward_exported(params: Mapping[str, np.ndarray], category: str, x: np.ndarray,
+                            dtype: torch.dtype = torch.float64) -> Tuple[torch.Tensor, torch.Tensor]:
+    """The island as exported: ``x`` ``[E, 31, C_in]`` -> ``t1``, ``t2`` ``[E, 128, 64]`` (``dtype`` math)."""
+    N = ISLAND_MODULE[category]
+    w = {k: torch.from_numpy(np.array(v, np.float64)).to(dtype) for k, v in params.items() if k.startswith(N + ".")}
+
+    def lin(h, n):
+        return h @ w[f"{N}.{n}.w"] + w[f"{N}.{n}.b"]
+
+    z = lin(F.gelu(lin(torch.from_numpy(np.asarray(x, np.float64)).to(dtype), "channel_pre_project.fc1")),
+            "channel_pre_project.fc2")
+    t1 = lin(z.transpose(1, 2), "token_pre_project.fc1")
+    return t1, lin(F.gelu(t1), "token_pre_project.fc2")
+
+
+def island_forward_pad_relative(params: Mapping[str, np.ndarray], consts: IslandConstants, x: np.ndarray,
+                                dtype: torch.dtype = torch.float64) -> Tuple[torch.Tensor, torch.Tensor]:
+    """The pad-relative island on the valid rows only (``x`` ``[E, 31, C_in]``; rows outside ``valid_rows`` must be
+    zero, which the truncation guarantees). Matmuls see deviations from the pad agent only."""
+    N = ISLAND_MODULE[consts.category]
+    w = {k: torch.from_numpy(np.array(v, np.float64)).to(dtype) for k, v in params.items() if k.startswith(N + ".")}
+    cst = {k: torch.from_numpy(np.array(getattr(consts, k), np.float64)).to(dtype)
+           for k in ("gelu_b1", "c0", "t1_pad", "g_pad", "t2_pad", "w_t1_valid")}
+    xv = torch.from_numpy(np.asarray(x, np.float64)[:, list(consts.valid_rows)]).to(dtype)     # [E, 6, C_in]
+    h = F.gelu(xv @ w[f"{N}.channel_pre_project.fc1.w"] + w[f"{N}.channel_pre_project.fc1.b"]) - cst["gelu_b1"]
+    dz = h @ w[f"{N}.channel_pre_project.fc2.w"]                                               # z - c0, [E, 6, 128]
+    t1 = cst["t1_pad"] + dz.transpose(1, 2) @ cst["w_t1_valid"]                                # [E, 128, 64]
+    t2 = cst["t2_pad"] + (F.gelu(t1) - cst["g_pad"]) @ w[f"{N}.token_pre_project.fc2.w"]
+    return t1, t2

code/tt_diffusion_planner/reference/weights.py

@@ -0,0 +1,442 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Weights of the Diffusion Planner v5.0 export, read as DATA from the three ONNX files and the param JSON.
+
+Every tensor is addressed through the graph node that consumes it (``ttaw.weights.OnnxWeights``), never by
+initializer name: most MatMul weights are anonymous (``onnx::MatMul_4039``), several biases are deduplicated across
+modules (``static_encoder/projection/fc2`` reads ``...fc1.bias``; ``route_encoder/attribute_emb`` reads
+``...speed_limit_emb.bias``), the decoder cross-attention K/V of all three blocks is one unnamed ``[256, 1536]``
+MatMul followed by a Split, and the fusion / cross-attention Q-K-V biases and weights are constant-folded tensors
+(SPEC 6.2). The result is one flat ``{canonical name: float32 array}`` dict that the CPU reference and the ttnn
+graph both consume:
+
+- linear layers: ``<module>.w`` ``[in, out]`` (``y = x @ w + b``) and ``<module>.b`` ``[out]``;
+- LayerNorms: ``<module>.gamma`` / ``<module>.beta``;
+- attention: ``...attn.q`` / ``.kv`` (fusion: Q from LN(x), K|V from x), ``...attn.qkv`` (DiT self-attention),
+  ``...cross_attn.q`` / ``.kv`` (K|V of one block, a column block of the fused cross K/V MatMul), ``...out``;
+- embeddings: ``decoder.dit.agent_embedding`` ``[2, 256]`` (ego, neighbour), ``encoder.route_position_embedding``
+  ``[25, 256]``, ``encoder.<lane|route>_encoder.unknown_speed_emb`` ``[128]``.
+
+There is no BatchNorm in this network, so nothing is folded here. The exact rewrites the TT port applies on top of
+these tensors (per-step adaLN tables folded into the LayerNorm affine, hoisted cross K/V, the pad-relative fp32
+pre-projection island) are in :mod:`.rewrites`, computed from this dict in float64 with one final rounding.
+
+The loader also checks the invariants the reference and the port rely on (LayerNorm epsilon 1e-5 everywhere, exact
+GELU in the encoder and the decoder pre-projection / t-embedder, tanh GELU in the DiT MLPs and the final projection,
+attention scale 1/sqrt(32), the ``-inf`` key mask), so a different export fails loudly instead of silently.
+"""
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+
+import numpy as np
+
+from . import config as C
+from ..ttaw.weights import OnnxWeights, file_sha256
+
+__all__ = ["PlannerWeights", "load_weights", "load_param_json", "Normalization", "find_weights_dir",
+           "MIXER_ENCODERS", "SMALL_ENCODERS"]
+
+# categories with an MLP-Mixer trunk -> ONNX module prefix
+MIXER_ENCODERS = {"ego": "ego_encoder", "neighbor": "neighbor_encoder", "lane": "lane_encoder",
+                  "route": "route_encoder", "polygon": "polygon_encoder", "line_string": "line_string_encoder"}
+# categories encoded by a channel MLP + LayerNorm + projection (goal pose, ego shape, turn indicators)
+SMALL_ENCODERS = {"goal": "goal_pose_encoder", "ego_shape": "ego_shape_encoder", "turn": "turn_indicator_encoder"}
+
+
+# ------------------------------------------------------------------------------------------------ param JSON
+
+@dataclass(frozen=True)
+class Normalization:
+    """``observation_normalizer`` (per input tensor: mean / std over the last dim) and ``state_normalizer``
+    (per agent and pose dim) of ``diffusion_planner.param.json`` (PKG/include/.../utils/arg_reader.hpp:80-140)."""
+
+    observation: Dict[str, Tuple[np.ndarray, np.ndarray]]
+    state_mean: np.ndarray  # [321, 4] (or [4])
+    state_std: np.ndarray
+    major_version: int
+    args: Dict[str, Any] = field(default_factory=dict)
+
+    def state(self) -> Tuple[np.ndarray, np.ndarray]:
+        """``(mean, std)`` broadcastable to ``[321, T, 4]``."""
+        return _per_agent(self.state_mean), _per_agent(self.state_std)
+
+
+def _per_agent(v: np.ndarray) -> np.ndarray:
+    v = np.asarray(v, np.float32).reshape(-1)
+    if v.size == C.POSE_DIM:
+        return v.reshape(1, 1, C.POSE_DIM)
+    if v.size == C.MAX_NUM_AGENTS * C.POSE_DIM:
+        return v.reshape(C.MAX_NUM_AGENTS, 1, C.POSE_DIM)
+    raise ValueError(f"unsupported state normalizer size {v.size}")
+
+
+def load_param_json(path: Path) -> Normalization:
+    """Parse ``diffusion_planner.param.json`` like ``arg_reader.hpp``; refuses a major version other than 5."""
+    with open(path) as f:
+        j = json.load(f)
+    major = int(j.get("major_version", -1))
+    if major != C.WEIGHT_MAJOR_VERSION:
+        raise ValueError(f"{path}: major_version {major}, this port needs {C.WEIGHT_MAJOR_VERSION} (constants.hpp:22)")
+    obs = {}
+    for key, v in j["observation_normalizer"].items():
+        mean = np.asarray(v.get("mean", []), np.float32).reshape(-1)
+        std = np.asarray(v.get("std", []), np.float32).reshape(-1)
+        if mean.shape != std.shape:
+            raise ValueError(f"{path}: normalizer {key!r} mean / std sizes differ")
+        obs[key] = (mean, std)
+    sn = j["state_normalizer"]
+    args = {k: v for k, v in j.items() if k not in ("observation_normalizer", "state_normalizer")}
+    return Normalization(obs, np.asarray(sn["mean"], np.float32), np.asarray(sn["std"], np.float32), major, args)
+
+
+# ------------------------------------------------------------------------------------------------ ONNX weights
+
+@dataclass
+class PlannerWeights:
+    """The flat canonical parameter dict plus provenance (file sha256) and the export facts checked at load."""
+
+    params: Dict[str, np.ndarray]
+    normalization: Normalization
+    sha256: Dict[str, str]
+    facts: Dict[str, Any]
+    path: Path
+
+    def __getitem__(self, name: str) -> np.ndarray:
+        return self.params[name]
+
+    def linear(self, name: str) -> Tuple[np.ndarray, np.ndarray]:
+        return self.params[f"{name}.w"], self.params[f"{name}.b"]
+
+    def num_parameters(self) -> int:
+        return int(sum(v.size for v in self.params.values()))
+
+    def to_torch(self, dtype: Any = None) -> Dict[str, Any]:
+        """``{name: torch.Tensor}`` (float32 by default; float64 for the fp64 rewrites)."""
+        import torch
+
+        dt = dtype or torch.float32
+        return {k: torch.from_numpy(np.ascontiguousarray(v)).to(dt) for k, v in self.params.items()}
+
+
+class _Reader:
+    """Node-addressed access to one ONNX file with the conventions of this export."""
+
+    def __init__(self, path: Path):
+        self.w = OnnxWeights(path)
+        self.facts: Dict[str, Any] = {"gelu": {}, "ln_eps": set()}
+
+    def has_node(self, name: str) -> bool:
+        try:
+            self.w.node(name)
+            return True
+        except KeyError:
+            return False
+
+    def const_input(self, node_name: str) -> np.ndarray:
+        """The single constant input of a binary node (the bias of a MatMul + Add pair)."""
+        node = self.w.node(node_name)
+        consts = [t for t in node.inputs if t and self.w.has(t)]
+        if len(consts) != 1:
+            raise ValueError(f"{node_name}: expected one constant input, found {len(consts)}")
+        return np.asarray(self.w.array(consts[0]), np.float32)
+
+    def bias_after(self, matmul_name: str) -> np.ndarray:
+        add = self.w.consumer_of(self.w.node(matmul_name).outputs[0], "Add")
+        return self.const_input(add.name)
+
+    def linear(self, path: str) -> Tuple[np.ndarray, np.ndarray]:
+        """``(w [in, out], b [out])`` of the torch ``nn.Linear`` exported under ``<path>``: either ``<path>/MatMul``
+        followed by an ``Add`` (3-D inputs) or ``<path>/Gemm`` (2-D inputs); exactly one of the two must exist."""
+        has_mm, has_gemm = self.has_node(f"{path}/MatMul"), self.has_node(f"{path}/Gemm")
+        if has_mm == has_gemm:
+            raise KeyError(f"{path}: expected exactly one of MatMul / Gemm, found {has_mm=} {has_gemm=}")
+        if has_mm:
+            w = np.asarray(self.w.matmul_weight(f"{path}/MatMul"), np.float32)
+            return w, self.bias_after(f"{path}/MatMul")
+        return self.gemm(f"{path}/Gemm")
+
+    def gemm(self, node_name: str) -> Tuple[np.ndarray, np.ndarray]:
+        """``(w [in, out], b [out])`` of a ``Gemm`` node (``y = x @ W^T + b`` with ``transB = 1``)."""
+        g = self.w.gemm(node_name)
+        if g.trans_a or g.alpha != 1.0 or g.beta != 1.0 or g.bias is None:
+            raise ValueError(f"{node_name}: unexpected attributes {g.trans_a=} {g.alpha=} {g.beta=}")
+        w = np.asarray(g.weight, np.float32)
+        return (w.T if g.trans_b else w).copy(), np.asarray(g.bias, np.float32).reshape(-1)
+
+    def layer_norm(self, path: str) -> Tuple[np.ndarray, np.ndarray]:
+        node = self.w.node(f"{path}/LayerNormalization")
+        self.facts["ln_eps"].add(float(node.attrs.get("epsilon", 1e-5)))
+        if int(node.attrs.get("axis", -1)) != -1:
+            raise ValueError(f"{path}: LayerNormalization over axis {node.attrs.get('axis')}")
+        return (np.asarray(self.w.param(node.name, 1), np.float32),
+                np.asarray(self.w.param(node.name, 2), np.float32))
+
+    def gelu(self, path: str) -> str:
+        node = self.w.node(f"{path}/Gelu")
+        mode = str(node.attrs.get("approximate", "none"))
+        self.facts["gelu"][path] = mode
+        return mode
+
+    def scalar(self, node_name: str) -> float:
+        return float(np.asarray(self.const_input(node_name)).reshape(-1)[0])
+
+
+def _put_linear(params: Dict[str, np.ndarray], name: str, wb: Tuple[np.ndarray, np.ndarray]) -> None:
+    params[f"{name}.w"], params[f"{name}.b"] = wb
+
+
+def _put_ln(params: Dict[str, np.ndarray], name: str, gb: Tuple[np.ndarray, np.ndarray]) -> None:
+    params[f"{name}.gamma"], params[f"{name}.beta"] = gb
+
+
+def _mlp(r: _Reader, params: Dict[str, np.ndarray], onnx_path: str, name: str, gelu: str) -> None:
+    _put_linear(params, f"{name}.fc1", r.linear(f"{onnx_path}/fc1"))
+    _put_linear(params, f"{name}.fc2", r.linear(f"{onnx_path}/fc2"))
+    mode = r.gelu(f"{onnx_path}/act")
+    if mode != gelu:
+        raise ValueError(f"{onnx_path}: GELU approximate={mode!r}, expected {gelu!r}")
+
+
+def _read_encoder(path: Path, params: Dict[str, np.ndarray]) -> Dict[str, Any]:
+    r = _Reader(path)
+    for cat, mod in {**MIXER_ENCODERS, **SMALL_ENCODERS}.items():
+        P, N = f"/encoder/{mod}", f"encoder.{mod}"
+        _mlp(r, params, f"{P}/channel_pre_project", f"{N}.channel_pre_project", "none")
+        if cat in MIXER_ENCODERS:
+            _mlp(r, params, f"{P}/token_pre_project", f"{N}.token_pre_project", "none")
+            for i in range(C.MIXER_DEPTH):
+                B, BN = f"{P}/blocks.{i}", f"{N}.blocks.{i}"
+                _put_ln(params, f"{BN}.norm1", r.layer_norm(f"{B}/norm1"))
+                _mlp(r, params, f"{B}/tokens_mlp", f"{BN}.tokens_mlp", "none")
+                _put_ln(params, f"{BN}.norm2", r.layer_norm(f"{B}/norm2"))
+                _mlp(r, params, f"{B}/channels_mlp", f"{BN}.channels_mlp", "none")
+        _put_ln(params, f"{N}.norm", r.layer_norm(f"{P}/norm"))
+        _mlp(r, params, f"{P}/emb_project", f"{N}.emb_project", "none")
+    _put_linear(params, "encoder.neighbor_encoder.type_emb", r.linear("/encoder/neighbor_encoder/type_emb"))
+    for mod in ("lane_encoder", "route_encoder"):
+        _put_linear(params, f"encoder.{mod}.speed_limit_emb", r.linear(f"/encoder/{mod}/speed_limit_emb"))
+        _put_linear(params, f"encoder.{mod}.attribute_emb", r.linear(f"/encoder/{mod}/attribute_emb"))
+        unk = r.w.param(f"/encoder/{mod}/unknown_speed_emb/Gather", 0)
+        params[f"encoder.{mod}.unknown_speed_emb"] = np.asarray(unk, np.float32).reshape(-1)
+    _mlp(r, params, "/encoder/static_encoder/projection", "encoder.static_encoder.projection", "none")
+    _put_linear(params, "encoder.pos_emb", r.linear("/encoder/pos_emb"))
+    rpe = np.asarray(r.w.param("/encoder/Slice_5", 0), np.float32)
+    params["encoder.route_position_embedding"] = rpe.reshape(C.NUM_SEGMENTS_IN_ROUTE, C.HIDDEN_DIM)
+    scales, fills = set(), set()
+    for i in range(C.FUSION_DEPTH):
+        B, BN = f"/encoder/fusion/blocks.{i}", f"encoder.fusion.blocks.{i}"
+        _put_ln(params, f"{BN}.norm1", r.layer_norm(f"{B}/norm1"))
+        q_w = np.asarray(r.w.matmul_weight(f"{B}/attn/MatMul"), np.float32)
+        _put_linear(params, f"{BN}.attn.q", (q_w, r.bias_after(f"{B}/attn/MatMul")))
+        kv_w = np.asarray(r.w.matmul_weight(f"{B}/attn/MatMul_1"), np.float32)
+        _put_linear(params, f"{BN}.attn.kv", (kv_w, r.bias_after(f"{B}/attn/MatMul_1")))
+        _put_linear(params, f"{BN}.attn.out", r.gemm(f"{B}/attn/Gemm"))
+        _put_ln(params, f"{BN}.norm2", r.layer_norm(f"{B}/norm2"))
+        _mlp(r, params, f"{B}/mlp", f"{BN}.mlp", "none")
+        scales.add(r.scalar(f"{B}/attn/Mul_3"))
+    # the key-padding bias Where(mask, -inf, 0) is built once in block 0 and shared by the six blocks
+    fills.add(float(np.asarray(r.w.param("/encoder/fusion/blocks.0/attn/Where", 1)).reshape(-1)[0]))
+    _put_ln(params, "encoder.fusion.norm", r.layer_norm("/encoder/fusion/norm"))
+    return {"gelu": r.facts["gelu"], "ln_eps": r.facts["ln_eps"], "attn_scale": scales, "mask_fill": fills,
+            "sha256": r.w.sha256, "nodes": len(r.w.nodes())}
+
+
+def _read_decoder(path: Path, params: Dict[str, np.ndarray]) -> Dict[str, Any]:
+    r = _Reader(path)
+    _mlp(r, params, "/dit/preproj", "decoder.dit.preproj", "none")
+    _mlp(r, params, "/dit/t_embedder", "decoder.dit.t_embedder", "none")
+    ego_row = np.asarray(r.w.param("/dit/Concat_3", 0), np.float32).reshape(-1)
+    expand = r.w.producer(r.w.node("/dit/Concat_3").inputs[1])
+    nb_row = np.asarray(r.w.param(expand.name, 0), np.float32).reshape(-1)
+    params["decoder.dit.agent_embedding"] = np.stack([ego_row, nb_row])
+    scales, fills = set(), set()
+    for i in range(C.DIT_DEPTH):
+        B, BN = f"/dit/blocks.{i}", f"decoder.dit.blocks.{i}"
+        _put_linear(params, f"{BN}.adaLN_modulation", r.linear(f"{B}/adaLN_modulation/adaLN_modulation.1"))
+        for n in ("norm1", "norm2", "norm3", "norm4"):
+            _put_ln(params, f"{BN}.{n}", r.layer_norm(f"{B}/{n}"))
+        qkv_w = np.asarray(r.w.matmul_weight(f"{B}/attn/MatMul"), np.float32)
+        _put_linear(params, f"{BN}.attn.qkv", (qkv_w, r.bias_after(f"{B}/attn/MatMul")))
+        _put_linear(params, f"{BN}.attn.out", r.gemm(f"{B}/attn/Gemm"))
+        _mlp(r, params, f"{B}/mlp1", f"{BN}.mlp1", "tanh")
+        q_w = np.asarray(r.w.matmul_weight(f"{B}/cross_attn/MatMul"), np.float32)
+        _put_linear(params, f"{BN}.cross_attn.q", (q_w, r.bias_after(f"{B}/cross_attn/MatMul")))
+        # K|V of this block: the bias is the constant input of cross_attn/Add_5, the weight a column block of the
+        # unnamed [256, 1536] MatMul whose output is split three ways (one 512-wide K|V slice per block)
+        add5 = r.w.node(f"{B}/cross_attn/Add_5")
+        kv_b = r.const_input(add5.name)
+        (kv_in,) = [t for t in add5.inputs if t and not r.w.has(t)]
+        split = r.w.producer(kv_in)
+        if split is None or split.op_type != "Split":
+            raise ValueError(f"{B}/cross_attn/Add_5: K|V does not come from a Split")
+        part = list(split.outputs).index(kv_in)
+        sizes = [int(s) for s in np.asarray(r.w.array(split.inputs[1])).reshape(-1)]
+        fused = r.w.producer(split.inputs[0])
+        fused_w = np.asarray(r.w.matmul_weight(fused.name), np.float32)
+        start = int(sum(sizes[:part]))
+        _put_linear(params, f"{BN}.cross_attn.kv", (fused_w[:, start:start + sizes[part]].copy(), kv_b))
+        _put_linear(params, f"{BN}.cross_attn.out", r.gemm(f"{B}/cross_attn/Gemm"))
+        _mlp(r, params, f"{B}/mlp2", f"{BN}.mlp2", "tanh")
+        scales.add(r.scalar(f"{B}/attn/Mul_2"))
+        scales.add(r.scalar(f"{B}/cross_attn/Mul_2"))
+    fills.add(float(np.asarray(r.w.param("/dit/blocks.0/attn/Where", 1)).reshape(-1)[0]))  # shared by the blocks
+    F = "/dit/final_layer"
+    _put_linear(params, "decoder.dit.final_layer.adaLN_modulation",
+                r.linear(f"{F}/adaLN_modulation/adaLN_modulation.1"))
+    _put_ln(params, "decoder.dit.final_layer.norm_final", r.layer_norm(f"{F}/norm_final"))
+    _put_ln(params, "decoder.dit.final_layer.proj.0", r.layer_norm(f"{F}/proj/proj.0"))
+    _put_linear(params, "decoder.dit.final_layer.proj.1", r.linear(f"{F}/proj/proj.1"))
+    gelu = r.gelu(f"{F}/proj/proj.2")
+    if gelu != "tanh":
+        raise ValueError(f"{F}/proj/proj.2: GELU approximate={gelu!r}, expected 'tanh'")
+    _put_ln(params, "decoder.dit.final_layer.proj.3", r.layer_norm(f"{F}/proj/proj.3"))
+    _put_linear(params, "decoder.dit.final_layer.proj.4", r.linear(f"{F}/proj/proj.4"))
+    return {"gelu": r.facts["gelu"], "ln_eps": r.facts["ln_eps"], "attn_scale": scales, "mask_fill": fills,
+            "sha256": r.w.sha256, "nodes": len(r.w.nodes())}
+
+
+def _read_turn(path: Path, params: Dict[str, np.ndarray]) -> Dict[str, Any]:
+    r = _Reader(path)
+    _put_linear(params, "decoder.turn_indicator_predictor", r.linear("/turn_indicator_predictor"))
+    return {"sha256": r.w.sha256, "nodes": len(r.w.nodes())}
+
+
+EXPECTED_SHAPES = {  # spot checks of the canonical layout (SPEC 4.2-4.4)
+    "encoder.neighbor_encoder.channel_pre_project.fc1.w": (C.NEIGHBOR_FEATURE_DIM, C.MIXER_CHANNELS),
+    "encoder.neighbor_encoder.token_pre_project.fc1.w": (C.INPUT_T + 1, C.MIXER_TOKENS),
+    "encoder.lane_encoder.token_pre_project.fc1.w": (C.POINTS_PER_SEGMENT, C.MIXER_TOKENS),
+    "encoder.polygon_encoder.channel_pre_project.fc1.w": (C.POLYGON_FEATURE_DIM, C.MIXER_CHANNELS),
+    "encoder.polygon_encoder.token_pre_project.fc1.w": (C.POINTS_PER_POLYGON, C.MIXER_TOKENS),
+    "encoder.line_string_encoder.channel_pre_project.fc1.w": (C.LINE_STRING_FEATURE_DIM, C.MIXER_CHANNELS),
+    "encoder.lane_encoder.attribute_emb.w": (C.LANE_ATTRIBUTE_DIM, C.MIXER_CHANNELS),
+    "encoder.turn_indicator_encoder.channel_pre_project.fc1.w": (C.TURN_INDICATOR_HISTORY, C.MIXER_CHANNELS),
+    "encoder.pos_emb.w": (C.POS_FEATURE_DIM, C.HIDDEN_DIM),
+    "encoder.fusion.blocks.0.attn.kv.w": (C.HIDDEN_DIM, 2 * C.HIDDEN_DIM),
+    "decoder.dit.preproj.fc1.w": (C.DIT_INPUT_DIM, 512),
+    "decoder.dit.t_embedder.fc1.w": (C.DIT_TIME_DIM, 512),
+    "decoder.dit.blocks.0.adaLN_modulation.w": (C.HIDDEN_DIM, 6 * C.HIDDEN_DIM),
+    "decoder.dit.blocks.0.attn.qkv.w": (C.HIDDEN_DIM, 3 * C.HIDDEN_DIM),
+    "decoder.dit.blocks.2.cross_attn.kv.w": (C.HIDDEN_DIM, 2 * C.HIDDEN_DIM),
+    "decoder.dit.final_layer.proj.4.w": (C.DIT_MLP_DIM, C.DIT_INPUT_DIM),
+    "decoder.turn_indicator_predictor.w": (2 * len(C.TURN_HEAD_STEPS) + C.HIDDEN_DIM, C.TURN_INDICATOR_OUTPUT_DIM),
+}
+
+
+def _check_facts(facts: Dict[str, Any]) -> None:
+    eps = facts["encoder"]["ln_eps"] | facts["decoder"]["ln_eps"]
+    if eps != {C.LN_EPS} and not all(math.isclose(e, C.LN_EPS, rel_tol=1e-6) for e in eps):
+        raise ValueError(f"LayerNorm epsilons {sorted(eps)}, expected {C.LN_EPS}")
+    scales = facts["encoder"]["attn_scale"] | facts["decoder"]["attn_scale"]
+    if len(scales) != 1 or not math.isclose(scales.pop(), 1.0 / math.sqrt(C.HEAD_DIM), rel_tol=1e-6):
+        raise ValueError(f"attention scales {facts['encoder']['attn_scale'] | facts['decoder']['attn_scale']}")
+    fills = facts["encoder"]["mask_fill"] | facts["decoder"]["mask_fill"]
+    if fills != {float("-inf")}:
+        raise ValueError(f"attention mask fill values {fills}, expected -inf")
+
+
+def find_weights_dir(explicit: Optional[str] = None) -> Optional[Path]:
+    """A local directory holding the v5.0 files, or None: ``explicit`` > ``$DIFFUSION_PLANNER_WEIGHTS_DIR`` > the
+    workspace download (``assets/diffusion-planner/hf_diffusion_planner``) > the HF cache snapshot of the pinned
+    revision (``local_files_only``; never a network access)."""
+    import os
+
+    names = (C.ENCODER_ONNX, C.DECODER_ONNX, C.TURN_INDICATOR_ONNX, C.PARAM_JSON)
+    cands: List[Path] = []
+    for c in (explicit, os.environ.get("DIFFUSION_PLANNER_WEIGHTS_DIR")):
+        if c:
+            cands.append(Path(c).expanduser())
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        cands.append(parent / "assets" / "diffusion-planner" / "hf_diffusion_planner")
+    for c in cands:
+        if all((c / n).is_file() for n in names):
+            return c
+    try:  # the HF cache of `from_pretrained` (offline lookup only)
+        from huggingface_hub import snapshot_download
+
+        p = Path(snapshot_download("AutowareFoundation/diffusion_planner",
+                                   revision="423efde67f5414734da43a7ad856c17ceb8b51aa",
+                                   allow_patterns=list(names), local_files_only=True))
+        if all((p / n).is_file() for n in names):
+            return p
+    except Exception:  # noqa: BLE001 -- not cached / no huggingface_hub: no weights
+        pass
+    return None
+
+
+def load_weights(weights_dir: Path, *, verify_sha256: bool = True) -> PlannerWeights:
+    """Read the encoder / decoder / turn-indicator ONNX files and the param JSON of ``weights_dir``."""
+    weights_dir = Path(weights_dir)
+    sha = {n: file_sha256(weights_dir / n) for n in C.FILE_SHA256}
+    if verify_sha256:
+        bad = {n: s for n, s in sha.items() if s != C.FILE_SHA256[n]}
+        if bad:
+            raise ValueError(f"{weights_dir}: files differ from AutowareFoundation/diffusion_planner@v5.0: "
+                             f"{sorted(bad)} (pass verify_sha256=False to load another export)")
+    params: Dict[str, np.ndarray] = {}
+    facts = {"encoder": _read_encoder(weights_dir / C.ENCODER_ONNX, params),
+             "decoder": _read_decoder(weights_dir / C.DECODER_ONNX, params),
+             "turn": _read_turn(weights_dir / C.TURN_INDICATOR_ONNX, params)}
+    _check_facts(facts)
+    for name, shape in EXPECTED_SHAPES.items():
+        if tuple(params[name].shape) != shape:
+            raise ValueError(f"{name}: shape {params[name].shape}, expected {shape}")
+    for name, arr in params.items():
+        if arr.dtype != np.float32 or not np.isfinite(arr).all():
+            raise ValueError(f"{name}: not finite float32")
+    norm = load_param_json(weights_dir / C.PARAM_JSON)
+    return PlannerWeights(params, norm, sha, facts, weights_dir)
+
+
+def param_count(params: Mapping[str, np.ndarray]) -> int:
+    return int(sum(v.size for v in params.values()))
+
+
+def coverage(weights: PlannerWeights) -> Dict[str, Any]:
+    """Proof that the canonical dict is a re-labelling of the export: every float initializer (size > 1) of the three
+    files equals one canonical tensor (or the concatenation it was split from: the fused cross K/V MatMul, the two
+    agent-embedding rows), and no canonical tensor holds the same data twice except the biases the export itself
+    deduplicated. Returns ``{"unused": [...], "duplicates": [...], "initializers": n}`` (tests require both lists
+    to be empty / the known pair)."""
+    import hashlib
+
+    import onnx
+    from onnx import numpy_helper
+
+    def h(a: np.ndarray) -> str:
+        a = np.ascontiguousarray(np.asarray(a, np.float32))
+        return hashlib.sha1(a.tobytes() + str(a.shape).encode()).hexdigest()
+
+    p = weights.params
+    known = {h(v): k for k, v in p.items()}
+    kv = np.concatenate([p[f"decoder.dit.blocks.{i}.cross_attn.kv.w"] for i in range(C.DIT_DEPTH)], axis=1)
+    known[h(kv)] = "decoder.dit.blocks.*.cross_attn.kv.w (fused)"
+    emb = p["decoder.dit.agent_embedding"]
+    known[h(emb[0:1])] = "decoder.dit.agent_embedding[0]"
+    known[h(emb[1:2])] = "decoder.dit.agent_embedding[1]"
+    rpe = p["encoder.route_position_embedding"]
+    known[h(rpe.reshape(1, *rpe.shape))] = "encoder.route_position_embedding"
+    for mod in ("lane_encoder", "route_encoder"):
+        unk = p[f"encoder.{mod}.unknown_speed_emb"]
+        known[h(unk.reshape(1, -1))] = f"encoder.{mod}.unknown_speed_emb"
+    for k, v in p.items():  # Gemm weights are stored [out, in]
+        if k.endswith(".w"):
+            known.setdefault(h(v.T), k)
+    unused, total = [], 0
+    for f in (C.ENCODER_ONNX, C.DECODER_ONNX, C.TURN_INDICATOR_ONNX):
+        for init in onnx.load(str(weights.path / f)).graph.initializer:
+            a = numpy_helper.to_array(init)
+            if a.dtype != np.float32 or a.size <= 1:
+                continue
+            total += 1
+            if h(a) not in known:
+                unused.append(f"{f}:{init.name}{list(a.shape)}")
+    seen: Dict[str, List[str]] = {}
+    for k, v in p.items():
+        seen.setdefault(h(v), []).append(k)
+    dups = sorted(tuple(sorted(ks)) for ks in seen.values() if len(ks) > 1)
+    return {"unused": unused, "duplicates": dups, "initializers": total}

code/tt_diffusion_planner/samples/README.md

@@ -0,0 +1,23 @@
+# Sample inputs shipped with diffusion-planner-p150
+
+Only REDISTRIBUTABLE data goes here (Apache-2.0 / MIT / CC-BY with attribution). Data whose license is unstated or
+non-commercial (the Autoware demo rosbag, nuScenes, Argoverse 2, ...) is NOT shipped; the nuScenes-derived planner
+instants used for local agreement tests live in the porting workspace only (`research/diffusion-planner/public_data`).
+
+Never use the `.bin` suffix here (or `.pt`, `.pth`, `.ckpt`, `.safetensors`): tt-model's staging silently drops
+those suffixes from `code/` (`CODE_IGNORE`, tt-model-manager `src/tt_kernel/build.py:328-332`).
+
+Each sample is one `.npz` holding exactly the 15 raw (pre-normalization, ego-frame, batch-1, float32) tensors of the
+node's `DiffusionPlannerCore::create_input_data()` (`reference/config.py` `INPUT_SCHEMA`): pass it as
+`model(inputs="<file>.npz")` or as the `/predict` field `inputs` (`server/client.py --inputs <file>.npz`).
+
+Next to each sample, `<stem>.reference.json` is the `/predict` body of the fp32 CPU reference
+(`tt_diffusion_planner.reference.ReferencePlanner`, `Output.to_dict()`, timing removed) on it;
+`server/smoke_test.py` compares the served trajectory with it (ADE / FDE gates). Regenerate both the reference bodies
+and `tests/goldens/` with `code/scripts/ref_golden.py` whenever the reference, the weights or the post-processing
+changes.
+
+| file | content | source | license |
+|---|---|---|---|
+| `kashiwanoha_dense.npz` (default sample) | one planning instant on the kashiwanoha test map: ego at 6 m/s on a 17-lanelet route, 88 neighbours (constant-speed vehicles), 123 lanes (24 lanelets with traffic lights in the map), 60 line strings (stop lines and road borders), no intersection polygon; 113,893 B, sha256 `d8c2aaef...99f7` | Lanelet2 map [AutowareFoundation/map-carla-kashiwanoha](https://huggingface.co/datasets/AutowareFoundation/map-carla-kashiwanoha) 0.2.0 (`lanelet2_map.osm`, sha256 `4fe358f2...4e6d`, byte-identical to autoware_universe `planning/autoware_diffusion_planner/test_map`); scene scripted by `research/diffusion-planner/scripts/dp_scene.py` (`dp_reference.py --scene osm --osm .../lanelet2_map.osm --n-agents 120 --seed 7`), a Python port of the node's tensor construction (simplifications: SPEC 7) | Apache-2.0 (map: Apache-2.0 per its dataset card) |
+| `straight_road.npz` | procedural 3-lane straight road: ego at 8 m/s, 12 neighbours (vehicles and pedestrians), 33 lanes with a green traffic light ahead, 6 route lanes, 1 intersection polygon, 9 line strings (borders + stop line); the precision-sensitive scene of SPEC 0.5; 10,832 B, sha256 `b9979b90...d381` | generated by `research/diffusion-planner/scripts/dp_scene.py` (`dp_reference.py --scene straight`), no external data | Apache-2.0 (this repo) |

code/tt_diffusion_planner/samples/kashiwanoha_dense.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d8c2aaefae61e155f5281c8b31920820d442416c653b9354be33d1fe089399f7
+size 113893

code/tt_diffusion_planner/samples/straight_road.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b9979b9007df6ca1190b4b9ef61e24534f862c41b2635d0219dd22c2dfd9d381
+size 10832

code/tt_diffusion_planner/samples/straight_road.reference.json

@@ -0,0 +1,887 @@
+{
+ "model": "diffusion-planner-p150",
+ "frame_id": "base_link",
+ "meta": {
+  "predicted_agent_columns": [
+   "x",
+   "y",
+   "yaw",
+   "cos",
+   "sin"
+  ],
+  "predicted_agent_rows": [
+   0,
+   1,
+   2,
+   3,
+   4,
+   5,
+   6,
+   7,
+   8,
+   9,
+   10,
+   11
+  ],
+  "force_stop": false,
+  "time_from_start_s": [
+   0.1,
+   0.2,
+   0.3,
+   0.4,
+   0.5,
+   0.6,
+   0.7,
+   0.8,
+   0.9,
+   1.0,
+   1.1,
+   1.2,
+   1.3,
+   1.4,
+   1.5,
+   1.6,
+   1.7,
+   1.8,
+   1.9,
+   2.0,
+   2.1,
+   2.2,
+   2.3,
+   2.4,
+   2.5,
+   2.6,
+   2.7,
+   2.8,
+   2.9,
+   3.0,
+   3.1,
+   3.2,
+   3.3,
+   3.4,
+   3.5,
+   3.6,
+   3.7,
+   3.8,
+   3.9,
+   4.0,
+   4.1,
+   4.2,
+   4.3,
+   4.4,
+   4.5,
+   4.6,
+   4.7,
+   4.8,
+   4.9,
+   5.0,
+   5.1,
+   5.2,
+   5.3,
+   5.4,
+   5.5,
+   5.6,
+   5.7,
+   5.8,
+   5.9,
+   6.0,
+   6.1,
+   6.2,
+   6.3,
+   6.4,
+   6.5,
+   6.6,
+   6.7,
+   6.8,
+   6.9,
+   7.0,
+   7.1,
+   7.2,
+   7.3,
+   7.4,
+   7.5,
+   7.6,
+   7.7,
+   7.8,
+   7.9,
+   8.0
+  ],
+  "valid_counts": {
+   "ego": 1,
+   "neighbor": 12,
+   "static": 0,
+   "lane": 33,
+   "route": 6,
+   "polygon": 1,
+   "line_string": 9,
+   "goal": 1,
+   "ego_shape": 1,
+   "turn": 1
+  },
+  "reference": "fp32 CPU (torch)"
+ },
+ "timing_ms": {},
+ "num_poses": 80,
+ "columns": [
+  "x",
+  "y",
+  "yaw",
+  "cos",
+  "sin",
+  "velocity",
+  "acceleration"
+ ],
+ "trajectory": [
+  [
+   0.8299,
+   0.0007,
+   -0.0007,
+   1.0033,
+   -0.0007,
+   8.0591,
+   -0.3468
+  ],
+  [
+   1.6377,
+   0.0009,
+   -0.0006,
+   1.0026,
+   -0.0006,
+   8.0244,
+   -0.0349
+  ],
+  [
+   2.4372,
+   0.0009,
+   -0.0012,
+   1.0021,
+   -0.0012,
+   8.0209,
+   0.0592
+  ],
+  [
+   3.2377,
+   0.0016,
+   -0.0016,
+   1.0021,
+   -0.0016,
+   8.0268,
+   -0.0312
+  ],
+  [
+   4.0421,
+   0.0016,
+   -0.0023,
+   1.0018,
+   -0.0023,
+   8.0237,
+   -0.0017
+  ],
+  [
+   4.8417,
+   0.0019,
+   -0.0021,
+   1.0017,
+   -0.0021,
+   8.0236,
+   0.0849
+  ],
+  [
+   5.643,
+   0.0022,
+   -0.0018,
+   1.0014,
+   -0.0018,
+   8.032,
+   0.0807
+  ],
+  [
+   6.4473,
+   0.0021,
+   -0.0013,
+   1.0011,
+   -0.0013,
+   8.0401,
+   -0.0193
+  ],
+  [
+   7.2494,
+   0.0013,
+   -0.0014,
+   1.0009,
+   -0.0014,
+   8.0382,
+   0.0377
+  ],
+  [
+   8.0545,
+   0.0012,
+   -0.0013,
+   1.0007,
+   -0.0013,
+   8.0419,
+   -0.0051
+  ],
+  [
+   8.8587,
+   -0.0027,
+   -0.0003,
+   1.0005,
+   -0.0003,
+   8.0414,
+   0.0536
+  ],
+  [
+   9.6567,
+   -0.0027,
+   -0.0001,
+   1.0003,
+   -0.0001,
+   8.0468,
+   0.1724
+  ],
+  [
+   10.4609,
+   -0.0016,
+   0.0004,
+   1.0002,
+   0.0004,
+   8.064,
+   0.0914
+  ],
+  [
+   11.2674,
+   -0.002,
+   0.0002,
+   1.0002,
+   0.0002,
+   8.0732,
+   -0.0142
+  ],
+  [
+   12.0751,
+   -0.0002,
+   0.0009,
+   1.0003,
+   0.0009,
+   8.0718,
+   0.2182
+  ],
+  [
+   12.8778,
+   0.0009,
+   0.0008,
+   1.0005,
+   0.0008,
+   8.0936,
+   0.1081
+  ],
+  [
+   13.6829,
+   0.0038,
+   0.0015,
+   1.0007,
+   0.0015,
+   8.1044,
+   0.1823
+  ],
+  [
+   14.4876,
+   0.0044,
+   0.0018,
+   1.0007,
+   0.0018,
+   8.1226,
+   0.3151
+  ],
+  [
+   15.2961,
+   0.0073,
+   0.0023,
+   1.0007,
+   0.0023,
+   8.1541,
+   0.2434
+  ],
+  [
+   16.1079,
+   0.0092,
+   0.0022,
+   1.0006,
+   0.0022,
+   8.1785,
+   0.2183
+  ],
+  [
+   16.9194,
+   0.0097,
+   0.0021,
+   1.0007,
+   0.0021,
+   8.2003,
+   0.2977
+  ],
+  [
+   17.7247,
+   0.012,
+   0.0019,
+   1.0003,
+   0.0019,
+   8.2301,
+   0.5019
+  ],
+  [
+   18.5499,
+   0.0152,
+   0.0019,
+   1.0005,
+   0.0019,
+   8.2803,
+   0.294
+  ],
+  [
+   19.3613,
+   0.018,
+   0.0018,
+   1.0002,
+   0.0018,
+   8.3097,
+   0.5381
+  ],
+  [
+   20.181,
+   0.0202,
+   0.0019,
+   1.0002,
+   0.0019,
+   8.3635,
+   0.4827
+  ],
+  [
+   21.0109,
+   0.0217,
+   0.0018,
+   1.0002,
+   0.0018,
+   8.4117,
+   0.4352
+  ],
+  [
+   21.8389,
+   0.0219,
+   0.0013,
+   1.0003,
+   0.0013,
+   8.4553,
+   0.5616
+  ],
+  [
+   22.6681,
+   0.0248,
+   0.0012,
+   1.0002,
+   0.0012,
+   8.5114,
+   0.5495
+  ],
+  [
+   23.5035,
+   0.0257,
+   0.0008,
+   1.0001,
+   0.0008,
+   8.5664,
+   0.6455
+  ],
+  [
+   24.3489,
+   0.0303,
+   0.0013,
+   1.0002,
+   0.0013,
+   8.6309,
+   0.562
+  ],
+  [
+   25.1976,
+   0.0307,
+   0.0015,
+   1.0003,
+   0.0015,
+   8.6871,
+   0.5735
+  ],
+  [
+   26.052,
+   0.0323,
+   0.0015,
+   1.0002,
+   0.0015,
+   8.7445,
+   0.6293
+  ],
+  [
+   26.9104,
+   0.0347,
+   0.0017,
+   1.0005,
+   0.0017,
+   8.8074,
+   0.6244
+  ],
+  [
+   27.7751,
+   0.037,
+   0.0021,
+   1.0007,
+   0.0021,
+   8.8698,
+   0.6727
+  ],
+  [
+   28.648,
+   0.0421,
+   0.0022,
+   1.0006,
+   0.0022,
+   8.9371,
+   0.5461
+  ],
+  [
+   29.5212,
+   0.0447,
+   0.0023,
+   1.0008,
+   0.0023,
+   8.9917,
+   0.8209
+  ],
+  [
+   30.4082,
+   0.0479,
+   0.003,
+   1.001,
+   0.003,
+   9.0738,
+   0.585
+  ],
+  [
+   31.2986,
+   0.047,
+   0.0028,
+   1.001,
+   0.0028,
+   9.1323,
+   0.6027
+  ],
+  [
+   32.1931,
+   0.0503,
+   0.0031,
+   1.0009,
+   0.0031,
+   9.1926,
+   0.8186
+  ],
+  [
+   33.0979,
+   0.0518,
+   0.0032,
+   1.0013,
+   0.0032,
+   9.2744,
+   0.7072
+  ],
+  [
+   34.0062,
+   0.0534,
+   0.0028,
+   1.0012,
+   0.0028,
+   9.3451,
+   0.7215
+  ],
+  [
+   34.9247,
+   0.0575,
+   0.0033,
+   1.0012,
+   0.0033,
+   9.4173,
+   0.7555
+  ],
+  [
+   35.8413,
+   0.0606,
+   0.0032,
+   1.0011,
+   0.0032,
+   9.4928,
+   0.7423
+  ],
+  [
+   36.7802,
+   0.061,
+   0.0034,
+   1.0015,
+   0.0034,
+   9.5671,
+   0.4912
+  ],
+  [
+   37.714,
+   0.0635,
+   0.0032,
+   1.0015,
+   0.0032,
+   9.6162,
+   0.774
+  ],
+  [
+   38.6526,
+   0.0643,
+   0.0027,
+   1.0016,
+   0.0027,
+   9.6936,
+   0.8083
+  ],
+  [
+   39.6127,
+   0.0679,
+   0.003,
+   1.002,
+   0.003,
+   9.7744,
+   0.5879
+  ],
+  [
+   40.574,
+   0.069,
+   0.0024,
+   1.002,
+   0.0024,
+   9.8332,
+   0.6322
+  ],
+  [
+   41.54,
+   0.0739,
+   0.0025,
+   1.0023,
+   0.0025,
+   9.8964,
+   0.7491
+  ],
+  [
+   42.5189,
+   0.0753,
+   0.0022,
+   1.0026,
+   0.0022,
+   9.9714,
+   0.4674
+  ],
+  [
+   43.4949,
+   0.0774,
+   0.0017,
+   1.0025,
+   0.0017,
+   10.0181,
+   0.7418
+  ],
+  [
+   44.4731,
+   0.0796,
+   0.002,
+   1.0028,
+   0.002,
+   10.0923,
+   0.7677
+  ],
+  [
+   45.4688,
+   0.0837,
+   0.0017,
+   1.0026,
+   0.0017,
+   10.169,
+   0.583
+  ],
+  [
+   46.4721,
+   0.0856,
+   0.0019,
+   1.0025,
+   0.0019,
+   10.2274,
+   0.5995
+  ],
+  [
+   47.4792,
+   0.0883,
+   0.0013,
+   1.0028,
+   0.0013,
+   10.2873,
+   0.56
+  ],
+  [
+   48.4911,
+   0.0938,
+   0.0013,
+   1.0026,
+   0.0013,
+   10.3433,
+   0.5217
+  ],
+  [
+   49.517,
+   0.0969,
+   0.0013,
+   1.0025,
+   0.0013,
+   10.3955,
+   0.5525
+  ],
+  [
+   50.5334,
+   0.0991,
+   0.0008,
+   1.0021,
+   0.0008,
+   10.4507,
+   0.5985
+  ],
+  [
+   51.5687,
+   0.1035,
+   0.0005,
+   1.002,
+   0.0005,
+   10.5106,
+   0.424
+  ],
+  [
+   52.6083,
+   0.1078,
+   0.0006,
+   1.002,
+   0.0006,
+   10.553,
+   0.5447
+  ],
+  [
+   53.6507,
+   0.109,
+   -0.0002,
+   1.0017,
+   -0.0002,
+   10.6074,
+   0.3741
+  ],
+  [
+   54.7019,
+   0.113,
+   -0.0004,
+   1.0014,
+   -0.0004,
+   10.6448,
+   0.3706
+  ],
+  [
+   55.7538,
+   0.1194,
+   -0.0005,
+   1.0012,
+   -0.0005,
+   10.6819,
+   0.4656
+  ],
+  [
+   56.8074,
+   0.1212,
+   -0.0005,
+   1.0012,
+   -0.0005,
+   10.7285,
+   0.3772
+  ],
+  [
+   57.8776,
+   0.1224,
+   -0.0012,
+   1.0006,
+   -0.0012,
+   10.7662,
+   0.2135
+  ],
+  [
+   58.9418,
+   0.126,
+   -0.0008,
+   1.0007,
+   -0.0008,
+   10.7875,
+   0.4392
+  ],
+  [
+   60.011,
+   0.1313,
+   -0.0007,
+   1.0008,
+   -0.0007,
+   10.8314,
+   0.2563
+  ],
+  [
+   61.0942,
+   0.1372,
+   -0.0007,
+   1.0008,
+   -0.0007,
+   10.8571,
+   0.1101
+  ],
+  [
+   62.1665,
+   0.14,
+   -0.0007,
+   1.0008,
+   -0.0007,
+   10.8681,
+   0.4464
+  ],
+  [
+   63.2474,
+   0.1409,
+   -0.0002,
+   1.0007,
+   -0.0002,
+   10.9127,
+   0.3852
+  ],
+  [
+   64.3365,
+   0.144,
+   -0.0007,
+   1.0007,
+   -0.0007,
+   10.9513,
+   0.1574
+  ],
+  [
+   65.4203,
+   0.1503,
+   -0.0001,
+   1.0009,
+   -0.0001,
+   10.967,
+   0.2386
+  ],
+  [
+   66.5075,
+   0.149,
+   -0.0005,
+   1.0001,
+   -0.0005,
+   10.9909,
+   0.0
+  ],
+  [
+   67.6069,
+   0.154,
+   -0.0003,
+   1.0002,
+   -0.0003,
+   10.9909,
+   0.0
+  ],
+  [
+   68.6966,
+   0.1604,
+   0.0001,
+   0.9999,
+   0.0001,
+   10.9909,
+   0.0
+  ],
+  [
+   69.7886,
+   0.1624,
+   0.0008,
+   0.9997,
+   0.0008,
+   10.9909,
+   0.0
+  ],
+  [
+   70.8966,
+   0.1674,
+   0.001,
+   0.9997,
+   0.001,
+   10.9909,
+   0.0
+  ],
+  [
+   72.0083,
+   0.1712,
+   0.0015,
+   0.9997,
+   0.0015,
+   10.9909,
+   0.0
+  ],
+  [
+   73.11,
+   0.1757,
+   0.0015,
+   0.999,
+   0.0015,
+   10.9909,
+   0.0
+  ],
+  [
+   74.2129,
+   0.179,
+   0.0022,
+   0.9989,
+   0.0022,
+   10.9909,
+   0.0
+  ]
+ ],
+ "turn_indicator": {
+  "command": 1,
+  "command_name": "DISABLE",
+  "keep_selected": true,
+  "held": false,
+  "logits": [
+   -16.221363067626953,
+   -6.708434581756592,
+   -2.558558940887451,
+   -3.9311578273773193,
+   6.994775295257568
+  ],
+  "probabilities": [
+   2.8843449850768366e-10,
+   3.903549895767355e-06,
+   0.00024758701329119503,
+   6.275029591051862e-05,
+   0.9995858073234558
+  ]
+ },
+ "predicted_agents": {
+  "format": "npz",
+  "key": "predicted_agents",
+  "dtype": "float32",
+  "shape": [
+   12,
+   80,
+   5
+  ],
+  "data": "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"
+ }
+}

code/tt_diffusion_planner/server/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+"""HTTP serving of diffusion-planner-p150, thin bindings of the vendored ``ttaw.server``: ``app.py`` (the ASGI app
+tt-model
+runs with uvicorn), ``client.py`` (stdlib request builder, runnable as a script), ``smoke_test.py`` (stdlib PASS/FAIL
+check of a running server: ETH dispatch and the 12x10 grid asserted, agreement with the stored CPU reference)."""

code/tt_diffusion_planner/server/app.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: Apache-2.0
+"""ASGI serving app of diffusion-planner-p150 on one Tenstorrent Blackhole p150: the HTTP contract of the Autoware
+collection (vendored ``ttaw.server.app``, BUNDLE_CONVENTIONS.md section 7) bound to :class:`DiffusionPlanner`.
+
+Served by tt-model-manager as ``kind: tt-dit-server``::
+
+    python -m uvicorn --host 0.0.0.0 --port <p> --lifespan on tt_diffusion_planner.server.app:app
+
+Routes: ``GET /``, ``/health`` and ``/v1/health`` (always 200: ``ok`` / ``starting`` / ``error``), ``/info``,
+``/v1/models`` (stub), ``POST /predict``; errors 400 / 422 / 503 / 500 (SERVING.md section 3). Everything that
+touches the device happens in the lifespan: weights -> device (ETH dispatch, 12x10) -> graph -> trace capture of
+every warm-up variant, so uvicorn's ``Application startup complete`` (the line ``tt-model serve`` waits for) means
+warm; SIGTERM (``tt-model stop``, 120 s) closes the model under the lock. ``/predict`` calls the Python API, so it
+returns exactly what ``model(...)`` returns. Importing this module has no side effects beyond importing fastapi and
+pydantic (the image's ``verify:`` imports it without a device); the environment is read in the lifespan only.
+
+Model-specific request fields (e.g. PointPainting ``rois``): subclass ``PredictRequest``, pass ``request_model=`` and
+``decode_extra=`` (which adds the decoded field to the call kwargs) to :class:`ServerSpec`, and list the keyword in
+``EXTRA_INPUTS`` of the model class. Host tests swap the model before starting the app:
+``app.state.ttaw.model_factory = Stub``; ``app.state.ttaw.predict(request)`` is the route handler itself.
+"""
+from pathlib import Path
+
+from .. import __version__
+from ..api import DiffusionPlanner
+from ..ttaw.server.app import PredictRequest, ServerSpec, create_app, parse_mesh_shape
+
+__all__ = ["SPEC", "app", "PredictRequest", "parse_mesh_shape"]
+
+SPEC = ServerSpec(
+    model_name=DiffusionPlanner.MODEL_NAME,
+    env_prefix=DiffusionPlanner.ENV_PREFIX,
+    model_cls=DiffusionPlanner,
+    task="ego trajectory planning with a diffusion model (DPM-Solver++ 10 steps), neighbour prediction and a "
+         "turn-indicator command",
+    default_weights=DiffusionPlanner.DEFAULT_REPO,
+    owner="changh95",
+    io="the Autoware planner tensors (ego and neighbour histories, lanes, route, polygons, line strings, goal, ego "
+       "shape, turn-indicator history) in, an 8 s ego trajectory, predicted paths of the valid neighbours and a "
+       "turn-indicator command out",
+    autoware={"package": "autoware_diffusion_planner",
+              "path": "planning/autoware_diffusion_planner",
+              "autoware_universe": "9ceaccf026c31ffc5319bc9eeb4bd7bede0af3fd"},
+    source={"repo": "https://huggingface.co/changh95/diffusion-planner-p150", "license": "Apache-2.0"},
+    calib_dir=Path(__file__).resolve().parents[1] / "calib",
+    version=__version__,
+    description="Diffusion Planner v5.0 (Autoware diffusion_planner) on one Tenstorrent Blackhole p150. "
+                "Not an OpenAI-compatible API.",
+)
+
+app = create_app(SPEC)

code/tt_diffusion_planner/server/client.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Build (and optionally send) a ``POST /predict`` request for diffusion-planner-p150. Standard library only.
+
+    # the planner tensors (.npz holding the 15 raw tensors of INPUT_SCHEMA), with an optional runtime param
+    python3 code/tt_diffusion_planner/server/client.py \
+        --inputs code/tt_diffusion_planner/samples/kashiwanoha_dense.npz --param stopping_threshold=0.3 --out req.json
+    curl -s localhost:20000/predict -H 'Content-Type: application/json' -d @req.json
+
+    # send it directly and print the response
+    python3 code/tt_diffusion_planner/server/client.py \
+        --inputs code/tt_diffusion_planner/samples/kashiwanoha_dense.npz --url http://127.0.0.1:20000
+
+The implementation is the vendored ``ttaw/server/client.py`` (C08); this file runs it from the model repository
+with any Python 3.9+, without numpy and without installing the package. In Python, use
+``tt_diffusion_planner.ttaw.server.client`` (``build_request``, ``post``, ``wait_ready``, ...).
+"""
+import runpy
+from pathlib import Path
+
+if __name__ == "__main__":
+    runpy.run_path(str(Path(__file__).resolve().parents[1] / "ttaw" / "server" / "client.py"), run_name="__main__")

code/tt_diffusion_planner/server/smoke_test.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Smoke test of a running diffusion-planner-p150 server (standard library only; any Python 3.9+, no numpy).
+
+    python3 code/tt_diffusion_planner/server/smoke_test.py --url http://127.0.0.1:20000 --wait 1800
+    # a served container package, one serve profile (what code/scripts/container_smoke.sh runs):
+    python3 code/tt_diffusion_planner/server/smoke_test.py --url http://127.0.0.1:20000 --wait 600 \
+        --manifest <out>/diffusion-planner-p150/tt_kernel_manifest.json [--profile <name>] \
+        --out /tmp/diffusion-planner.json
+
+Checks (all failures are collected; prints ONE line ``PASS ...`` / ``FAIL ...``, exit code 0 / 1):
+  * ``/health`` reports ``ok`` (waiting up to ``--wait`` seconds), ``/info`` and ``/v1/models`` answer;
+  * ``/info`` reports ETH dispatch and the 12x10 grid, the p150 target of every published number (PLAN.md 0.3
+    item 6, D14): WORKER dispatch (e.g. an ETH open that fell back) or any other grid FAILS;
+  * with ``--manifest``: ``/info`` runs what the staged package pins for the serve profile
+    (``DIFFUSION_PLANNER_DISPATCH``,
+    ``DIFFUSION_PLANNER_NUM_CQS``, ``DIFFUSION_PLANNER_VARIANT``, the weights revision);
+  * ``POST /predict`` of the shipped sample (the planner tensors as ``inputs``) answers 200 with the documented fields
+    and passes this model's output gates (:func:`output_gates`: 80 finite trajectory rows of 7 columns, a valid
+    turn-indicator command, the predicted neighbour paths);
+  * the served output agrees with the stored CPU-reference output of the sample within :data:`REFERENCE_GATES`:
+    ``--reference``, else the first of ``<sample stem>.<profile>.reference.json``,
+    ``<stem>.<variant>.reference.json``, ``<stem>.reference.json`` next to the sample (skipped when none exists);
+  * a malformed request answers 400 (not 500).
+
+The checks themselves are the vendored ``ttaw/server/client.py`` and ``ttaw/server/smoke.py`` (stdlib only, loaded
+by path); this file holds the model-specific parts: the sample request, the output gates and their thresholds.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent / "ttaw" / "server"))
+import client as ttaw_client  # noqa: E402  (stdlib-only modules of the vendored ttaw)
+import smoke as ttaw_smoke  # noqa: E402
+
+MODEL = "diffusion-planner-p150"
+ENV_PREFIX = "DIFFUSION_PLANNER"
+EXPECT_DISPATCH, EXPECT_GRID = "eth", "12x10"  # the p150 target; deliberately not a command-line option
+DEFAULT_INPUT = HERE.parent / "samples" / "kashiwanoha_dense.npz"
+DEFAULT_EXPECT = ""  # unused for a planner (no detections); kept for the shared command line
+# Agreement with the stored CPU reference (names of ttaw_smoke.DEFAULT_GATES): the ego trajectory's average / final
+# displacement (the predicted_agents array is reported, not gated). Keep them in line with tests/test_e2e_device.py
+# (ego mean error <= 0.3 m; the max error <= 1.0 m gate needs the whole array and lives in the device test).
+REFERENCE_GATES: Dict[str, Optional[float]] = {"max_ade": 0.3, "max_fde": 1.0}
+REQUIRED_KEYS = ("model", "frame_id", "timing_ms", "num_poses", "columns", "trajectory", "turn_indicator",
+                 "predicted_agents")
+TRAJECTORY_COLUMNS = ["x", "y", "yaw", "cos", "sin", "velocity", "acceleration"]
+
+
+def build_sample_request(path: Path) -> Dict[str, Any]:
+    """The ``/predict`` body for the sample: the planner tensors ``.npz`` as ``inputs``."""
+    if not Path(path).is_file():
+        raise FileNotFoundError(str(path))
+    return ttaw_client.build_request(inputs=str(path))
+
+
+def output_gates(body: Dict[str, Any], expect: str) -> List[str]:
+    """This model's plausibility gates on a 200 response: 80 trajectory rows of the documented 7 finite columns,
+    a turn-indicator command in 0..3 with 5 logits, and an encoded predicted-agents array of 80 x 5 per agent."""
+    fails: List[str] = []
+    traj = body.get("trajectory") or []
+    if body.get("columns") != TRAJECTORY_COLUMNS:
+        fails.append(f"columns {body.get('columns')} != {TRAJECTORY_COLUMNS}")
+    if len(traj) != 80 or body.get("num_poses") != 80:
+        fails.append(f"{len(traj)} trajectory rows, expected 80")
+    if not all(len(row) == 7 and all(math.isfinite(v) for v in row) for row in traj):
+        fails.append("non-finite or malformed trajectory row")
+    turn = body.get("turn_indicator") or {}
+    if turn.get("command") not in (0, 1, 2, 3) or len(turn.get("logits") or []) != 5:
+        fails.append(f"turn_indicator {turn}")
+    agents = body.get("predicted_agents") or {}
+    shape = agents.get("shape") or []
+    if len(shape) != 3 or shape[1:] != [80, 5]:
+        fails.append(f"predicted_agents shape {shape}")
+    return fails
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("--url", default="http://127.0.0.1:20000")
+    ap.add_argument("--input", type=Path, default=DEFAULT_INPUT, help="sample to POST (default: the shipped one)")
+    ap.add_argument("--expect", default=DEFAULT_EXPECT, help="unused by this planner (kept for the shared CLI)")
+    ap.add_argument("--reference", type=Path, help="stored CPU-reference /predict body of --input "
+                                                   "(default: looked up next to it)")
+    ap.add_argument("--manifest", type=Path, help="staged tt_kernel_manifest.json: /info must run what it pins")
+    ap.add_argument("--profile", help="serve profile being smoke-tested (default: the package's default)")
+    ap.add_argument("--wait", type=float, default=0.0, help="seconds to wait for /health == ok")
+    ap.add_argument("--out", type=Path, help="write the /predict response here")
+    a = ap.parse_args(argv)
+    base = a.url.rstrip("/")
+
+    health = ttaw_client.wait_ready(base, wait_s=a.wait)
+    if health.get("status") != "ok":
+        print(ttaw_client.smoke_line(MODEL, f"/health status={health.get('status')!r}",
+                                     [f"not ready after {a.wait:.0f} s (error: {health.get('error')})"]))
+        return 1
+    info, fails = ttaw_client.check_service(base, expect_dispatch=EXPECT_DISPATCH, expect_grid=EXPECT_GRID)
+    if not info:
+        print(ttaw_client.smoke_line(MODEL, "/info unreachable", fails))
+        return 1
+    profile = a.profile
+    if a.manifest:
+        try:
+            pinned = ttaw_smoke.pinned_config(a.manifest, a.profile)
+        except (OSError, ValueError) as e:
+            fails.append(f"manifest: {e}")
+        else:
+            profile = pinned["profile"]
+            fails += ttaw_smoke.check_pinned(info, pinned, ENV_PREFIX)
+
+    code, body = 0, {}
+    t0 = time.perf_counter()
+    try:
+        code, body = ttaw_client.post(base, build_sample_request(a.input))
+    except (OSError, ValueError) as e:  # unreadable sample, unknown suffix, server gone
+        fails.append(f"/predict: {type(e).__name__}: {e}")
+    rtt_ms = (time.perf_counter() - t0) * 1e3
+    if a.out:
+        a.out.write_text(json.dumps(body, indent=1))
+    ref_summary = "none"
+    if code and code != 200:
+        fails.append(f"/predict HTTP {code}: {str(body)[:300]}")
+    elif code == 200:
+        fails += [f"missing key {k!r}" for k in REQUIRED_KEYS if k not in body]
+        fails += output_gates(body, a.expect)
+        ref_path = a.reference or ttaw_smoke.find_reference(a.input, profile, info.get("variant"))
+        if ref_path:
+            try:
+                metrics, more = ttaw_smoke.compare_with_reference(body, ttaw_smoke.load_json(ref_path),
+                                                                  gates=REFERENCE_GATES)
+            except (OSError, ValueError) as e:
+                metrics, more = {}, [f"reference {ref_path}: {e}"]
+            fails += more
+            ref_summary = f"{ref_path.name} ({ttaw_smoke.describe_metrics(metrics)})"
+    try:
+        bad = ttaw_client.check_bad_request(base)
+    except OSError as e:
+        bad = f"malformed-request check: {type(e).__name__}: {e}"
+    if bad:
+        fails.append(bad)
+
+    device, timing = info.get("device") or {}, body.get("timing_ms") or {}
+    turn = (body.get("turn_indicator") or {}).get("command_name")
+    summary = (f"profile={profile or '-'} variant={info.get('variant')} dispatch={device.get('dispatch')} "
+               f"grid={device.get('grid')} cqs={device.get('num_command_queues')} n={body.get('num_poses')} "
+               f"turn={turn} "
+               f"reference={ref_summary} device_ms={timing.get('device')} total_ms={timing.get('total')} "
+               f"rtt_ms={rtt_ms:.1f}")
+    print(ttaw_client.smoke_line(MODEL, summary, fails))
+    return 1 if fails else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code/tt_diffusion_planner/tests/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

code/tt_diffusion_planner/tests/_research.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Access to the verified research scripts of the porting workspace (``research/diffusion-planner/scripts``), the
+independent implementations the host code is unit-tested against. Absent in an installed package or the image:
+tests that need them skip."""
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+PKG = Path(__file__).resolve().parents[1]
+RESEARCH = PKG.parents[3] / "research" / "diffusion-planner"
+SCRIPTS = RESEARCH / "scripts"
+ORT_GOLDENS = RESEARCH / "ort"
+FULL_GOLDENS = RESEARCH / "goldens"
+SAMPLES = PKG / "samples"
+SMALL_GOLDENS = PKG / "tests" / "goldens"
+
+
+def load_script(name: str):
+    """Import ``research/diffusion-planner/scripts/<name>.py`` by path (None when absent). Its directory is put on
+    ``sys.path`` only while it imports (``dp_scene`` imports ``dp_common`` by name)."""
+    path = SCRIPTS / f"{name}.py"
+    if not path.is_file():
+        return None
+    key = f"_dp_research_{name}"
+    if key in sys.modules:
+        return sys.modules[key]
+    spec = importlib.util.spec_from_file_location(key, path)
+    mod = importlib.util.module_from_spec(spec)
+    sys.path.insert(0, str(SCRIPTS))
+    try:
+        spec.loader.exec_module(mod)
+    finally:
+        sys.path.remove(str(SCRIPTS))
+    sys.modules[key] = mod
+    return mod
+
+
+def sample_raw(stem: str) -> dict:
+    with np.load(SAMPLES / f"{stem}.npz") as z:
+        return {k: np.array(z[k]) for k in z.files}
+
+
+def research_scene_raw(scene: str) -> Optional[dict]:
+    path = ORT_GOLDENS / f"golden_{scene}.npz"
+    if not path.is_file():
+        return None
+    with np.load(path) as z:
+        return {k[len("raw/"):]: np.array(z[k]) for k in z.files if k.startswith("raw/")}
+
+
+def research_scenes() -> list:
+    return sorted(p.stem[len("golden_"):] for p in ORT_GOLDENS.glob("golden_*.npz"))