Mirror ZJU4EmbodiedAI/EvolvingNav at dfa6872

.gitattributes

@@ -33,3 +33,19 @@ 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
+assets/explorer/hssd_104348511_topdown.png filter=lfs diff=lfs merge=lfs -text
+assets/explorer/zju.pdf filter=lfs diff=lfs merge=lfs -text
+figures/P4D_Benchmark.pdf filter=lfs diff=lfs merge=lfs -text
+figures/P4D_CaseStudy.pdf filter=lfs diff=lfs merge=lfs -text
+figures/Real_World_Case_third_1.pdf filter=lfs diff=lfs merge=lfs -text
+figures/Real_World_Case_third_2.pdf filter=lfs diff=lfs merge=lfs -text
+figures/benchmark_figure3_web.png filter=lfs diff=lfs merge=lfs -text
+figures/benchmark_figure4_web.png filter=lfs diff=lfs merge=lfs -text
+figures/case_study_web_latest.png filter=lfs diff=lfs merge=lfs -text
+figures/dataset-generate.pdf filter=lfs diff=lfs merge=lfs -text
+figures/method.pdf filter=lfs diff=lfs merge=lfs -text
+figures/method_web_latest.png filter=lfs diff=lfs merge=lfs -text
+figures/overview_web_latest.png filter=lfs diff=lfs merge=lfs -text
+figures/real_indoor_sequence_web.png filter=lfs diff=lfs merge=lfs -text
+figures/real_outdoor_sequence_web.png filter=lfs diff=lfs merge=lfs -text
+main.pdf filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,10 +1,87 @@
 ---
 title: EvolvingNav
-emoji: 🐨
-colorFrom: purple
-colorTo: indigo
+emoji: 🧭
+colorFrom: blue
+colorTo: green
 sdk: static
+app_file: index.html
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# EvolvingNav
+
+## Beyond the Remembered World
+
+**Predictive 4D Belief for Persistent Navigation in Evolving Worlds**
+
+EvolvingNav is an embodied navigation framework for settings where an agent's remembered scene can become stale while it is away or moving. It forecasts whether an observed state will persist, reasons about plausible relocation, and uses visibility-aware RGB-D evidence to revise its belief and replan.
+
+**Mingjian Gao**<sup>1,*</sup>, **Zhaocheng Li**<sup>1,*</sup>, **Haoyang Huang**<sup>2,*</sup>, **Wenqiao Zhang**<sup>1,‡,†</sup>, **Yingjie NIU**<sup>3,4,‡,†</sup>, **Hao Zhou**<sup>1</sup>, **Chao LI**<sup>3</sup>, **Juncheng LI**<sup>1</sup>, **Siliang Tang**<sup>1</sup>, **Yueting Zhuang**<sup>1</sup>
+
+<sup>1</sup> Zhejiang University · <sup>2</sup> University of California, San Diego · <sup>3</sup> Deeprobotics · <sup>4</sup> The Chinese University of Hong Kong<br />
+<sup>*</sup> Equal contribution · <sup>‡</sup> Corresponding authors · <sup>†</sup> Project lead
+
+## At a glance
+
+| 54 scenes | 803.68K tasks | 61.32% first-inspection SR | 86.18% search SR |
+|:--:|:--:|:--:|:--:|
+| EvoWorld-Bench | executable instances | stale-memory decisions | budgeted search |
+
+## Overview
+
+<p align="center"><img src="figures/overview_web_latest.png" alt="EvolvingNav overview" width="960" /></p>
+
+EvolvingNav turns timestamped 3D histories into an arrival-time belief over the current world. The agent predicts, acts for a short horizon, checks whether newly visible evidence should have been observable, and updates its memory before continuing.
+
+## Method
+
+<p align="center"><img src="figures/method_web_latest.png" alt="EvolvingNav method" width="960" /></p>
+
+The framework combines memory construction, state prediction, visibility-aware evidence filtering, and belief-guided route planning. Candidate states are forecast at their estimated arrival times instead of only at the instant of the query.
+
+## EvoWorld-Bench
+
+<p align="center"><img src="figures/benchmark_figure4_web.png" alt="EvoWorld-Bench construction" width="620" /> <img src="figures/benchmark_figure3_web.png" alt="EvoWorld-Bench protocols" width="620" /></p>
+
+The benchmark grounds human traces into executable evolving worlds and evaluates predictive navigation, belief-guided search, evidence-aware replanning, online dynamics, held-out transfer, and embodied question answering.
+
+## Results
+
+| Method | FindingDory HL-SR | GOAT-Bench SR | First-Inspection SR | Search SR | SPL |
+|:--|--:|--:|--:|--:|--:|
+| DynaMem | 30.30 | 14.54 | 45.33 | 71.94 | 56.83 |
+| **EvolvingNav (ours)** | **53.22 ± 3.87** | **35.43 ± 2.16** | **61.32 ± 3.24** | **86.18 ± 2.07** | **70.15 ± 1.74** |
+
+<p align="center"><img src="figures/case_study_web_latest.png" alt="Qualitative cases" width="960" /></p>
+
+## Real-world validation
+
+Across 64 matched LYNX M20 search episodes, EvolvingNav reaches 34.4% first-inspection success, 48.4% search success, and 24.3% recovery success, with 43.8 m mean travel.
+
+## Code
+
+Runnable implementation, Habitat runners, training scripts, and tests are in [`code/`](code/README.md).
+
+```bash
+cd code
+python -m pip install -r requirements.txt
+export PYTHONPATH=.:src:scripts
+python -m pytest tests -q
+```
+
+For dataset paths, model training, and benchmark commands, see [`code/README.md`](code/README.md).
+
+## Project page
+
+The complete paper website is available at [zju4embodiedai.github.io/EvolvingNav](https://zju4embodiedai.github.io/EvolvingNav/).
+
+## Citation
+
+```bibtex
+@inproceedings{evolvingnav2027,
+  title     = {Beyond the Remembered World: Predictive 4D Belief for Persistent Navigation in Evolving Worlds},
+  author    = {Gao, Mingjian and Li, Zhaocheng and Huang, Haoyang and Zhang, Wenqiao and Niu, Yingjie and Zhou, Hao and Li, Chao and Li, Juncheng and Tang, Siliang and Zhuang, Yueting},
+  booktitle = {International Conference on Learning Representations},
+  year      = {2027}
+}
+```

academic.css

@@ -0,0 +1 @@
+:root{--navy:#193453;--teal:#1599ad;--orange:#ed7f3a;--ink:#27313d;--muted:#5f6d7b;--line:#dce2e7;--paper:#fff;--page:#f3f5f6}*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--page);color:var(--ink);font-family:Arial,Helvetica,sans-serif;font-size:16px;line-height:1.62}.page-width{width:min(1080px,calc(100% - 40px));margin:0 auto}.site-header{height:52px;background:#fff;border-bottom:1px solid var(--line);font-size:13px}.header-inner{height:100%;display:flex;align-items:center;justify-content:space-between}.site-name{font-weight:700;color:var(--navy);text-decoration:none;letter-spacing:.01em}.site-header nav{display:flex;gap:24px}.site-header nav a{color:#617080;text-decoration:none}.site-header nav a:hover{color:var(--teal)}.paper-heading{text-align:center;padding:68px 0 30px}.paper-heading h1{font-size:clamp(27px,4vw,42px);line-height:1.18;font-weight:600;letter-spacing:-.025em;color:var(--navy);margin:0 auto 22px;max-width:920px}.authors{font-size:17px;margin:0;color:var(--ink)}.affiliation{font-size:14px;color:var(--muted);margin:2px 0 20px}.paper-links{display:flex;justify-content:center;gap:10px}.paper-links a{display:inline-block;border:1px solid #b8c5d0;border-radius:5px;padding:6px 18px;color:var(--navy);background:#fff;text-decoration:none;font-size:13px}.paper-links a:hover{border-color:var(--teal);color:var(--teal)}figure{margin:0}.main-figure{background:#fff;border:1px solid var(--line);padding:17px 17px 13px;margin:0 auto 55px}.main-figure img{display:block;width:100%;height:auto}.main-figure figcaption,.paper-figure figcaption{color:#687582;font-size:13px;line-height:1.5;margin:12px 4px 0}.main-figure figcaption b,.paper-figure figcaption b{color:var(--navy)}.paper-section{padding:0 0 54px;margin-bottom:12px;border-bottom:1px solid var(--line)}.paper-section h2{font-size:28px;color:var(--navy);font-weight:600;margin:0 0 17px;letter-spacing:-.02em}.paper-section h3{font-size:21px;color:var(--navy);margin:34px 0 11px}.paper-section p{max-width:940px;margin:0 0 15px}.abstract-section p{max-width:980px}.figure-grid{display:grid;grid-template-columns:1fr 1fr;gap:25px;margin:28px 0 17px}.paper-figure{background:#fff;border:1px solid var(--line);padding:12px}.paper-figure img{display:block;width:100%;height:auto}.paper-figure.full{margin:28px 0 25px;padding:16px}.paper-figure.full img{max-height:600px;object-fit:contain}.equation-note{border-left:3px solid var(--teal);background:#eef7f8;color:var(--navy);padding:13px 16px;font-family:Georgia,serif;font-size:18px;word-spacing:5px}.equation-note span{font-weight:600}.protocol-table{display:grid;grid-template-columns:repeat(5,1fr);border:1px solid var(--line);background:#fff;margin-top:24px}.protocol-table>div{padding:14px 12px;border-right:1px solid var(--line);display:flex;flex-direction:column;gap:2px}.protocol-table>div:last-child{border-right:0}.protocol-table b{color:var(--teal);font-family:Georgia,serif;font-size:19px}.protocol-table span{font-size:13px;color:var(--navy);font-weight:600;line-height:1.3}.protocol-table small{font-size:11px;color:var(--muted)}.result-row{display:grid;grid-template-columns:repeat(5,1fr);gap:10px;margin:28px 0;background:#fff;border:1px solid var(--line);padding:16px}.result{padding:8px 9px;border-right:1px solid var(--line);display:flex;flex-direction:column}.result:last-child{border-right:0}.result strong{font-size:24px;line-height:1.15;color:var(--teal);font-weight:600}.result span{font-size:11px;color:var(--muted);line-height:1.35;margin-top:5px}.results-table{width:100%;border-collapse:collapse;background:#fff;border:1px solid var(--line);font-size:13px;margin:14px 0 0}.results-table th{background:#f0f4f6;color:var(--navy);font-weight:600;text-align:center;padding:11px 10px;border-bottom:1px solid var(--line);line-height:1.3}.results-table th:first-child,.results-table td:first-child{text-align:left}.results-table td{padding:12px 10px;border-bottom:1px solid #e9edf0;text-align:center}.results-table tr:last-child td{border-bottom:0}.results-table tr.ours{background:#eff8f8}.results-table tr.ours td{color:var(--navy)}.real-world{margin-top:20px}.real-world .paper-figure:first-child{grid-column:span 1}.resources{border-bottom:0;padding-bottom:30px}.resource-links{display:flex;flex-wrap:wrap;gap:10px}.resource-links a{color:var(--navy);border:1px solid #c4ced6;background:#fff;border-radius:5px;padding:9px 14px;text-decoration:none;font-size:13px}.resource-links a:hover{color:var(--teal);border-color:var(--teal)}.resource-links span{color:var(--orange)}.bibtex{border-bottom:0;padding-bottom:60px}.bibtex pre{overflow:auto;background:#f0f3f5;border:1px solid var(--line);padding:17px;font:13px/1.55 "Courier New",monospace;color:#334b62;margin:0}footer{background:#fff;border-top:1px solid var(--line);padding:22px 0;color:#788592;font-size:12px}.desktop{display:block}@media(max-width:760px){.page-width{width:calc(100% - 28px)}.site-header{height:auto;padding:12px 0}.header-inner{gap:10px;align-items:flex-start}.site-header nav{gap:11px;flex-wrap:wrap;justify-content:flex-end;font-size:11px}.paper-heading{padding:42px 0 25px}.paper-heading h1{font-size:28px}.desktop{display:none}.main-figure{padding:9px;margin-bottom:40px}.figure-grid{grid-template-columns:1fr;gap:17px}.protocol-table{grid-template-columns:1fr 1fr}.protocol-table>div:nth-child(2n){border-right:0}.protocol-table>div{border-bottom:1px solid var(--line)}.protocol-table>div:last-child{grid-column:span 2}.result-row{grid-template-columns:repeat(2,1fr);gap:0}.result{border-bottom:1px solid var(--line);padding:11px 8px}.result:nth-child(2n){border-right:0}.result:last-child{grid-column:span 2;border-bottom:0}.results-table{font-size:11px;min-width:650px}.results-table{display:block;overflow-x:auto}.paper-section{padding-bottom:40px}}

assets/explorer/scene-provenance.json

@@ -0,0 +1,337 @@
+{
+  "purpose": "Genuine HSSD scene backgrounds for an illustrative website interaction",
+  "annotations": "Object hypotheses, time changes, belief values and quadruped animation are authored demonstrations, not benchmark outputs or learned-policy rollouts.",
+  "projection_note": "Downward-facing perspective render. Routes are projected at NavMesh floor elevation; furniture anchor pixels are visually selected image positions.",
+  "scenes": [
+    {
+      "scene_id": "104348511_171513654",
+      "image": "assets/explorer/hssd_104348511_topdown.png",
+      "image_size": [
+        1300,
+        1500
+      ],
+      "recommended_viewbox": [
+        120,
+        100,
+        1080,
+        1080
+      ],
+      "capture_script": "reports/agent_evidence_update_20260914/capture_topdown_v2.py",
+      "capture_manifest": "reports/agent_evidence_update_20260914/assets/capture_manifest.json",
+      "source_notes": "reports/agent_evidence_update_20260914/README_v2.md",
+      "render_engine": "Habitat-Sim",
+      "task_target_added": false,
+      "camera": {
+        "eye": [
+          -8.34,
+          11,
+          -3.38
+        ],
+        "look_at": [
+          -8.34,
+          0,
+          -3.38
+        ],
+        "hfov_degrees": 43
+      },
+      "anchors_px": {
+        "coffee_table": [
+          686,
+          408
+        ],
+        "kitchen_island": [
+          487,
+          985
+        ],
+        "dining_table": [
+          1030,
+          870
+        ]
+      },
+      "robot_points_px": {
+        "start": [
+          361,
+          661
+        ],
+        "coffee_table": [
+          468,
+          457
+        ],
+        "kitchen_island": [
+          788,
+          1007
+        ],
+        "dining_table": [
+          817,
+          850
+        ]
+      },
+      "navigation_check": {
+        "navmesh": "data/4d_dynnav/hssd/multiscene/104348511_171513654/navmeshes/104348511_171513654.navmesh",
+        "floor_y": 0.17658868432044983,
+        "all_points_navigable": true,
+        "paths": [
+          {
+            "from": "start",
+            "to": "coffee_table",
+            "found": true,
+            "length_m": 1.5109581947,
+            "points_px": [
+              [
+                361,
+                661
+              ],
+              [
+                468,
+                457
+              ]
+            ]
+          },
+          {
+            "from": "coffee_table",
+            "to": "kitchen_island",
+            "found": true,
+            "length_m": 4.3134069443,
+            "points_px": [
+              [
+                468,
+                457
+              ],
+              [
+                528.5,
+                695.3
+              ],
+              [
+                719.1,
+                870.6
+              ],
+              [
+                788,
+                1007
+              ]
+            ]
+          },
+          {
+            "from": "kitchen_island",
+            "to": "dining_table",
+            "found": true,
+            "length_m": 1.0472089052,
+            "points_px": [
+              [
+                788,
+                1007
+              ],
+              [
+                817,
+                850
+              ]
+            ]
+          }
+        ],
+        "method": "Habitat-Sim PathFinder.load_nav_mesh; is_navigable; find_path. Projection derived from recorded camera geometry.",
+        "limit": "Does not establish quadruped footprint clearance, dynamics, sensing or policy performance; route smoothing must not cut obstacle corners."
+      },
+      "anchors_crop_normalized": {
+        "coffee_table": [
+          0.52407,
+          0.28519
+        ],
+        "kitchen_island": [
+          0.33981,
+          0.81944
+        ],
+        "dining_table": [
+          0.84259,
+          0.71296
+        ]
+      },
+      "robot_points_crop_normalized": {
+        "start": [
+          0.22315,
+          0.51944
+        ],
+        "coffee_table": [
+          0.32222,
+          0.33056
+        ],
+        "kitchen_island": [
+          0.61852,
+          0.83981
+        ],
+        "dining_table": [
+          0.64537,
+          0.69444
+        ]
+      },
+      "original_source": "reports/agent_evidence_update_20260914/assets/hssd_104348511_topdown.png",
+      "sha256": "a53944b1c072121c0dde1f1629193e33249fddcef6ee4fa6a084493916227a83"
+    },
+    {
+      "scene_id": "102344280",
+      "image": "assets/explorer/hssd_102344280_topdown.png",
+      "image_size": [
+        1400,
+        900
+      ],
+      "recommended_viewbox": [
+        240,
+        170,
+        1150,
+        585
+      ],
+      "capture_script": "reports/agent_evidence_update_20260914/capture_topdown.py",
+      "render_engine": "Habitat-Sim",
+      "task_target_added": false,
+      "camera": {
+        "eye": [
+          -7.3,
+          9,
+          2.7
+        ],
+        "look_at": [
+          -7.3,
+          0,
+          2.7
+        ],
+        "hfov_degrees": 75
+      },
+      "anchors_px": {
+        "dining_table": [
+          493,
+          423
+        ],
+        "center_table": [
+          1040,
+          470
+        ],
+        "kitchen_sink": [
+          945.4,
+          644.1
+        ]
+      },
+      "robot_points_px": {
+        "start": [
+          720,
+          310
+        ],
+        "dining_table": [
+          650,
+          429
+        ],
+        "center_table": [
+          1010,
+          295
+        ],
+        "kitchen_sink": [
+          926.9,
+          558.3
+        ]
+      },
+      "navigation_check": {
+        "navmesh": "data/4d_dynnav/hssd/hssd-hab-subset/navmeshes/102344280.navmesh",
+        "floor_y": 0.15372097492218018,
+        "all_points_navigable": true,
+        "paths": [
+          {
+            "from": "start",
+            "to": "dining_table",
+            "found": true,
+            "length_m": 1.3388005495,
+            "points_px": [
+              [
+                720,
+                310
+              ],
+              [
+                650,
+                429
+              ]
+            ]
+          },
+          {
+            "from": "dining_table",
+            "to": "kitchen_sink",
+            "found": true,
+            "length_m": 2.9634537697,
+            "points_px": [
+              [
+                650,
+                429
+              ],
+              [
+                926.9,
+                558.3
+              ]
+            ]
+          },
+          {
+            "from": "kitchen_sink",
+            "to": "center_table",
+            "found": true,
+            "length_m": 3.4616861343,
+            "points_px": [
+              [
+                926.9,
+                558.3
+              ],
+              [
+                869.8,
+                528.2
+              ],
+              [
+                859.5,
+                512.7
+              ],
+              [
+                864.7,
+                456
+              ],
+              [
+                1010,
+                295
+              ]
+            ]
+          }
+        ],
+        "method": "Habitat-Sim PathFinder.load_nav_mesh; is_navigable; find_path. Projection derived from recorded camera geometry.",
+        "limit": "Does not establish quadruped footprint clearance, dynamics, sensing or policy performance; route smoothing must not cut obstacle corners."
+      },
+      "related_verified_replay": "reports/4d_dynnav/case_study_102344280_20260908/capture_manifest.json",
+      "related_replay_note": "Related source is a separately documented qualitative bowl tabletop-to-sink replay, not the website interaction.",
+      "anchors_crop_normalized": {
+        "dining_table": [
+          0.22,
+          0.43248
+        ],
+        "center_table": [
+          0.69565,
+          0.51282
+        ],
+        "kitchen_sink": [
+          0.61339,
+          0.81043
+        ]
+      },
+      "robot_points_crop_normalized": {
+        "start": [
+          0.41739,
+          0.23932
+        ],
+        "dining_table": [
+          0.35652,
+          0.44274
+        ],
+        "center_table": [
+          0.66957,
+          0.21368
+        ],
+        "kitchen_sink": [
+          0.5973,
+          0.66376
+        ]
+      },
+      "original_source": "reports/agent_evidence_update_20260914/assets/hssd_102344280_topdown.png",
+      "sha256": "2d48e3021ddc215beaa91597a240bdac9b528e9b7ada56a96bc10c435591748e"
+    }
+  ]
+}

assets/explorer/zju.pdf

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

code/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+.env
+runs/

code/README.md

@@ -0,0 +1,101 @@
+# EvolvingNav Agent
+
+## Code
+
+| Path | Function |
+| --- | --- |
+| `src/readyagent/p4d_belief/` | Continuous-time history encoder and persistence–relocation belief |
+| `evolvingnav_paper/memory.py` | Causal entity versions, RGB-D backprojection and evidence provenance |
+| `evolvingnav_paper/transition_model.py` | Row-normalized chronological transition head |
+| `evolvingnav_paper/filter.py` | Current-time belief, arrival forecasts and evidence rounds |
+| `evolvingnav_paper/coverage.py`, `calibration.py` | Online depth coverage and validation-fitted detection probability |
+| `evolvingnav_paper/agent.py`, `controller.py` | Event-driven actions and frozen VLM tool selection |
+| `evolvingnav_paper/world.py`, `backend.py`, `run.py` | Habitat action adapter and benchmark runner |
+| `scripts/` | Dataset packing, belief/transition training and calibration |
+| `tests/` | Unit tests |
+
+## Environment
+
+Use Python 3.11 with Habitat-Sim 0.3.3 installed.
+
+```bash
+cd code
+python -m pip install -r requirements.txt
+export PYTHONPATH=.:src:scripts
+export MAGNUM_LOG=quiet HABITAT_SIM_LOG=quiet
+export P4D_DATASET=/absolute/path/to/p4d_hssd_30d_v0.6.0
+export NAV_TASKS=/absolute/path/to/p4d_navigation_107734254_v1.0
+export HSSD_ROOT=/absolute/path/to/hssd-hab
+export NAVMESH_ROOT=/absolute/path/to/hssd-hab/navmeshes
+```
+
+## Train
+
+If `records/packed/{train,val,test}.npz` are absent:
+
+```bash
+python scripts/pack_p4d_hssd_records.py --root "$P4D_DATASET"
+```
+
+Train the query-time belief and the chronological transition head:
+
+```bash
+python scripts/train_p4d_belief.py \
+  --dataset-root "$P4D_DATASET" --output runs/p4d_seed0 \
+  --seeds 0 --skip-classical
+python scripts/train_transition.py \
+  --dataset "$P4D_DATASET" \
+  --belief-checkpoint runs/p4d_seed0/checkpoints/p4d/seed_0/best.pt \
+  --output runs/transition_seed0
+```
+
+Collect held-out RGB-D validation observations and fit detector calibration:
+
+```bash
+python scripts/collect_calibration.py \
+  --dataset "$P4D_DATASET" --tasks "$NAV_TASKS" \
+  --hssd-root "$HSSD_ROOT" --navmesh-root "$NAVMESH_ROOT" \
+  --limit 8 --output runs/calibration_val.jsonl
+python scripts/fit_calibration.py \
+  --validation-jsonl runs/calibration_val.jsonl \
+  --output runs/detection_calibration.json
+```
+
+## Run
+
+Run the event-driven N3 Agent with Grounding DINO + SAM2:
+
+```bash
+python -m evolvingnav_paper.run \
+  --task n3 --world static --limit 10 \
+  --dataset "$P4D_DATASET" --tasks "$NAV_TASKS" \
+  --hssd-root "$HSSD_ROOT" --navmesh-root "$NAVMESH_ROOT" \
+  --checkpoint runs/p4d_seed0/checkpoints/p4d/seed_0/best.pt \
+  --calibration runs/detection_calibration.json \
+  --output runs/n3_static_10
+python -m evolvingnav_paper.verify_visual runs/n3_static_10 \
+  --tasks "$NAV_TASKS" --hssd-root "$HSSD_ROOT" \
+  --navmesh-root "$NAVMESH_ROOT"
+```
+
+Add `--controller luna` and set `OPENAI_API_KEY` to use the frozen GPT-5.6-Luna tool controller. Model IDs and revisions for Grounding DINO and SAM2 are in `configs/perception.yaml`.
+
+For an N4 task directory with `public/episodes_n4.jsonl`, each private `target_motion_schedule` event supplies seconds after query (`time_s`), `target_position_xyz`, `current_state_id`, and `valid_goal_viewpoints`:
+
+```bash
+python -m evolvingnav_paper.run \
+  --task n4 --world routine --limit 2 \
+  --dataset "$P4D_DATASET" --tasks /absolute/path/to/n4_tasks \
+  --hssd-root "$HSSD_ROOT" --navmesh-root "$NAVMESH_ROOT" \
+  --checkpoint runs/p4d_seed0/checkpoints/p4d/seed_0/best.pt \
+  --transition-checkpoint runs/transition_seed0/best.pt \
+  --output runs/n4_routine_2
+```
+
+Every run writes `policy.jsonl`, `scores.jsonl` and `summary.json` to a new output directory.
+
+## Tests
+
+```bash
+python -m pytest tests -q
+```

code/configs/perception.yaml

@@ -0,0 +1,11 @@
+version: evolvingnav_paper_perception_v1
+device: cuda
+grounding_dino:
+  model_id: IDEA-Research/grounding-dino-tiny
+  revision: a2bb814dd30d776dcf7e30523b00659f4f141c71
+  box_threshold: 0.35
+  text_threshold: 0.25
+sam:
+  model_id: facebook/sam2.1-hiera-tiny
+  revision: de431c4043854a71d8101e17995dfe596bf101a5
+palette_version: cielab_css11_v1

code/evolvingnav_paper/__init__.py

@@ -0,0 +1 @@
+"""EvolvingNav predictive belief and event-driven embodied Agent."""

code/evolvingnav_paper/agent.py

@@ -0,0 +1,249 @@
+"""Event-driven EvolvingNav controller (paper Equations 11–15, 20–22)."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from evolvingnav_paper.filter import BeliefFilter, EvidenceLedger
+from evolvingnav_paper.policy import candidate_utility
+
+
+@dataclass(frozen=True)
+class ViewEvidence:
+    evidence_id: str
+    state_id: int
+    surface_samples: frozenset[int]
+    detection_probability: float
+    covered_fraction: float = 1.0
+    pose_xyz: tuple[float, float, float] = (0.0, 0.0, 0.0)
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    max_inspections: int = 10
+    max_path_m: float = 100.0
+    chunk_m: float = 2.0
+    speed_mps: float = 1.0
+    inspection_s: float = 1.0
+    lambda_time: float = 0.05
+    lambda_inspect: float = 0.25
+    lambda_scan: float = 0.25
+    explore_cost: float = 2.0
+    discovery_probability: float = 0.5
+    speed_ema_alpha: float = 0.8
+    unknown_state: int | None = None
+
+
+@dataclass
+class AgentResult:
+    found: bool = False
+    actions: list[str] = field(default_factory=list)
+    inspections: list[int] = field(default_factory=list)
+    path_m: float = 0.0
+    elapsed_s: float = 0.0
+    posterior: dict[int, float] = field(default_factory=dict)
+    termination: str = ""
+    evidence_trace: list[dict] = field(default_factory=list)
+
+
+class World(Protocol):
+    def distance(self, goal) -> float: ...
+    def move_chunk(self, goal, max_distance: float) -> tuple[float, float]: ...
+    def inspect(self, state: int) -> tuple[bool, list[ViewEvidence]]: ...
+    def explore(self, budget_m: float) -> tuple[dict[int, tuple[object, float]], float, float]: ...
+
+
+class Agent:
+    def __init__(self, prior: dict[int, float], goals: dict[int, object], world: World,
+                 transition, config: AgentConfig | None = None,
+                 sample_count: dict[int, int] | None = None, controller=None,
+                 memory=None, target_id: str | None = None,
+                 time_origin_s: float = 0.0) -> None:
+        self.config = config or AgentConfig()
+        self.filter = BeliefFilter(prior, transition)
+        self.goals = {state: goal for state, goal in goals.items() if state in prior}
+        self.world = world
+        self.ledger = EvidenceLedger(sample_count=sample_count)
+        self.speed = self.config.speed_mps
+        self.controller = controller
+        self.memory = memory
+        self.target_id = target_id
+        self.time_origin_s = time_origin_s
+
+    def _return_probability(self, state: int, eta: float) -> float:
+        if state not in self.filter.posterior:
+            return 0.0
+        forecast = self.filter.arrival(eta)
+        # Equation 21 excludes probability already at this state.
+        return max(0.0, forecast.get(state, 0.0) - self.filter.posterior.get(state, 0.0)
+                   * self.filter.transition.matrix(list(self.filter.posterior), eta)[
+                       list(self.filter.posterior).index(state), list(self.filter.posterior).index(state)])
+
+    def _choose(self, result: AgentResult) -> int | str | None:
+        scored: list[tuple[float, int | str]] = []
+        for state, goal in self.goals.items():
+            distance = self.world.distance(goal)
+            if not math.isfinite(distance) or result.path_m + distance > self.config.max_path_m:
+                continue
+            eta = distance / self.speed + self.config.inspection_s
+            arrival = self.filter.arrival(eta)
+            return_probability = self._return_probability(state, eta)
+            if not self.ledger.eligible(
+                state, belief=self.filter.posterior.get(state, 0.0),
+                return_probability=return_probability, new_coverage=0.0,
+                dynamic=self.filter.transition.dynamic,
+                now_s=result.elapsed_s,
+            ):
+                continue
+            uncovered = max(0.0, 1.0 - self.ledger.coverage(state))
+            new_detection = (
+                self.world.expected_new_detection(state, uncovered)
+                if hasattr(self.world, "expected_new_detection") else uncovered
+            )
+            utility = candidate_utility(
+                arrival_probability=arrival.get(state, 0.0),
+                new_detection_probability=new_detection,
+                distance_m=distance, eta_s=eta,
+                lambda_time=self.config.lambda_time,
+                lambda_inspect=self.config.lambda_inspect,
+            )
+            scored.append((utility, state))
+        unknown = self.config.unknown_state
+        if unknown is not None and self.filter.posterior.get(unknown, 0.0) > 0:
+            utility = (self.filter.posterior[unknown] * self.config.discovery_probability
+                       / (self.config.explore_cost + self.config.lambda_scan))
+            scored.append((utility, "EXPLORE"))
+        if not scored:
+            return None
+        preferred = max(scored, key=lambda row: (row[0], -row[1] if isinstance(row[1], int) else 0))
+        if self.controller is not None:
+            labels = [f"NAVIGATE_TO({action})" if isinstance(action, int) else action
+                      for _, action in scored]
+            chosen = self.controller.choose(labels, {
+                "belief": self.filter.posterior,
+                "utilities": dict(zip(labels, [utility for utility, _ in scored], strict=True)),
+                "elapsed_s": result.elapsed_s, "path_m": result.path_m,
+            })
+            for utility, action in scored:
+                label = f"NAVIGATE_TO({action})" if isinstance(action, int) else action
+                if label == chosen and utility >= preferred[0] - 1e-9:
+                    return action
+        return preferred[1]
+
+    def _admit_negative(self, evidence: list[ViewEvidence], now_s: float,
+                        result: AgentResult) -> None:
+        for item in evidence:
+            new_coverage = self.ledger.admit(item)
+            if new_coverage > 0:
+                probability = min(1.0, item.detection_probability * new_coverage
+                                  / max(item.covered_fraction, 1e-9))
+                before = self.filter.posterior.get(item.state_id, 0.0)
+                applied = self.filter.negative(
+                    {item.state_id: probability},
+                    f"{item.evidence_id}:{item.state_id}",
+                )
+                if applied:
+                    result.evidence_trace.append({
+                        "evidence_id": item.evidence_id,
+                        "state_id": item.state_id,
+                        "time_s": now_s,
+                        "new_coverage": new_coverage,
+                        "detection_probability": probability,
+                        "prior": before,
+                        "posterior": self.filter.posterior.get(item.state_id, 0.0),
+                    })
+                if applied and self.memory is not None:
+                    self.memory.record_negative(
+                        item.evidence_id, item.state_id,
+                        self.time_origin_s + now_s, item.pose_xyz
+                    )
+
+    def run(self) -> AgentResult:
+        result = AgentResult()
+        for _ in range(self.config.max_inspections + len(self.goals) * 20):
+            selected = self._choose(result)
+            if selected is None:
+                result.termination = "search_exhausted"
+                unknown = self.config.unknown_state
+                unknown_mass = self.filter.posterior.get(unknown, 0.0) if unknown is not None else 0.0
+                searchable = sum(self.filter.posterior.get(state, 0.0) for state in self.goals)
+                if unknown_mass < 0.05 and searchable < 0.05:
+                    result.actions.append("NOT_FOUND")
+                break
+            if selected == "EXPLORE":
+                result.actions.append("EXPLORE")
+                discovered, duration, displacement = self.world.explore(
+                    self.config.max_path_m - result.path_m
+                )
+                self.filter.advance(duration)
+                result.elapsed_s += duration
+                result.path_m += displacement
+                if not discovered:
+                    result.termination = "exploration_exhausted"
+                    break
+                unknown = self.config.unknown_state
+                mass = self.filter.posterior[unknown]
+                total_weight = sum(weight for _, weight in discovered.values())
+                allocated = min(mass, total_weight)
+                self.filter.posterior[unknown] -= allocated
+                for state, (goal, probability) in discovered.items():
+                    self.goals[state] = goal
+                    if hasattr(self.world, "sample_count"):
+                        self.ledger.sample_count[state] = self.world.sample_count(state)
+                    if hasattr(self.filter.transition, "add_candidate"):
+                        self.filter.transition.add_candidate(state)
+                    self.filter.posterior[state] = self.filter.posterior.get(state, 0.0) + (
+                        allocated * probability / total_weight)
+                continue
+            state = int(selected)
+            goal = self.goals[state]
+            result.actions.append(f"NAVIGATE_TO({state})")
+            while self.world.distance(goal) > 1e-4:
+                remaining = self.config.max_path_m - result.path_m
+                if remaining <= 0:
+                    result.termination = "path_budget_exhausted"
+                    result.posterior = self.filter.posterior.copy()
+                    return result
+                displacement, duration = self.world.move_chunk(goal, min(self.config.chunk_m, remaining))
+                if displacement <= 0 or duration <= 0:
+                    result.termination = "navigation_blocked"
+                    result.posterior = self.filter.posterior.copy()
+                    return result
+                self.filter.advance(duration)
+                result.path_m += displacement
+                result.elapsed_s += duration
+                self.speed = (self.config.speed_ema_alpha * self.speed
+                              + (1 - self.config.speed_ema_alpha) * displacement / duration)
+                if hasattr(self.world, "observe_chunk"):
+                    self._admit_negative(self.world.observe_chunk(), result.elapsed_s, result)
+                if self._choose(result) != state:
+                    break
+            else:
+                result.actions.append(f"INSPECT({state})")
+                if hasattr(self.world, "advance_time"):
+                    self.world.advance_time(self.config.inspection_s)
+                self.filter.advance(self.config.inspection_s)
+                result.elapsed_s += self.config.inspection_s
+                detected, evidence = self.world.inspect(state)
+                result.inspections.append(state)
+                self.ledger.mark_inspected(state, now_s=result.elapsed_s)
+                if detected:
+                    detection = getattr(self.world, "last_detection", None)
+                    if (self.memory is not None and self.target_id is not None
+                            and detection is not None):
+                        self.memory.observe(
+                            self.target_id, state, self.time_origin_s + result.elapsed_s,
+                            detection["confidence"], detection["evidence_id"],
+                            detection["world_point"],
+                        )
+                    result.found = True
+                    result.actions.append("STOP")
+                    break
+                self._admit_negative(evidence, result.elapsed_s, result)
+                if len(result.inspections) >= self.config.max_inspections:
+                    result.termination = "inspection_budget_exhausted"
+                    break
+        result.posterior = self.filter.posterior.copy()
+        return result

code/evolvingnav_paper/backend.py

@@ -0,0 +1,188 @@
+"""Habitat navigation and evaluator-private visual inspection."""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Callable
+
+import habitat_sim
+import magnum as mn
+import numpy as np
+
+from evolvingnav_paper.habitat_utils import make_simulator, path_distance, sensor_specs, set_agent
+
+
+def visible_fraction_from_masks(actual: np.ndarray, target_only: np.ndarray, semantic_id: int) -> float:
+    """Visible target pixels divided by its unobstructed projection at the same pose."""
+    projected = int(np.count_nonzero(target_only == semantic_id))
+    if projected == 0:
+        return 0.0
+    visible = int(np.count_nonzero(actual == semantic_id))
+    return min(1.0, visible / projected)
+
+
+class HabitatInspectionBackend:
+    def __init__(
+        self, hssd_root: Path, scene_id: str, navmesh: Path,
+        public_viewpoints: dict[int, dict], *, gpu: int = 0,
+        detector: Callable[[np.ndarray, np.ndarray, str], bool] | None = None,
+    ) -> None:
+        self.hssd_root = hssd_root
+        self.scene_id = scene_id
+        self.navmesh = navmesh
+        self.gpu = gpu
+        self.public_viewpoints = public_viewpoints
+        self.detector = detector
+        self.real = None
+        self.target_only = None
+        self.target_only_object_id = None
+        self.object_id = None
+        self.truth = None
+        self.projected_pixels = {}
+        self.last_observation = None
+        self.last_detections = ()
+        self.last_semantic = None
+
+    def distance(self, start, goal) -> float:
+        if self.real is None:
+            raise RuntimeError("prepare an episode before requesting paths")
+        return path_distance(self.real.pathfinder, start, goal)
+
+    def _place_target(self, sim, truth: dict, target: dict) -> int:
+        config_path = self.hssd_root / target["template_handle"]
+        manager = sim.get_object_template_manager()
+        manager.load_configs(str(config_path.resolve()))
+        handles = manager.get_template_handles(target["template_hash"])
+        if not handles:
+            raise RuntimeError(f"target template unavailable: {config_path}")
+        obj = sim.get_rigid_object_manager().add_object_by_template_handle(handles[-1])
+        obj.motion_type = habitat_sim.physics.MotionType.KINEMATIC
+        obj.semantic_id = self.semantic_id
+        obj.translation = mn.Vector3(*truth["target_position_xyz"])
+        obj.rotation = mn.Quaternion.rotation(
+            mn.Rad((self.semantic_id % 12) * math.pi / 6), mn.Vector3.y_axis()
+        )
+        sim.perform_discrete_collision_detection()
+        return obj.object_id
+
+    def prepare(self, truth: dict, target: dict, candidate_ids: list[int],
+                *, dynamic: bool = False) -> None:
+        self.clear()
+        if self.real is not None:
+            self.real.close()
+            self.real = None
+        self.truth = dict(truth)
+        self.semantic_id = int(target["semantic_instance_id"])
+        self.target_category = str(target["category_canonical"])
+        config = habitat_sim.SimulatorConfiguration()
+        config.scene_id = "NONE"
+        config.create_renderer = True
+        config.enable_physics = True
+        config.gpu_device_id = self.gpu
+        agent = habitat_sim.agent.AgentConfiguration()
+        agent.sensor_specifications = sensor_specs(320, 240)
+        target_only = habitat_sim.Simulator(habitat_sim.Configuration(config, [agent]))
+        try:
+            target_only_id = self._place_target(target_only, truth, target)
+            self.projected_pixels = {}
+            for state in candidate_ids:
+                viewpoint = self.public_viewpoints[state]
+                set_agent(
+                    target_only.get_agent(0), viewpoint["position_xyz"],
+                    viewpoint["rotation_xyzw"],
+                )
+                semantic = np.asarray(target_only.get_sensor_observations()["semantic"])
+                self.projected_pixels[state] = int(np.count_nonzero(semantic == self.semantic_id))
+        finally:
+            if not dynamic:
+                target_only.close()
+        if dynamic:
+            self.target_only = target_only
+            self.target_only_object_id = target_only_id
+        self.real = make_simulator(
+            self.hssd_root, self.scene_id, self.navmesh, self.gpu, 320, 240
+        )
+        self.object_id = self._place_target(self.real, truth, target)
+
+    def inspect(self, state: int, position) -> dict:
+        if self.truth is None:
+            raise RuntimeError("prepare an episode before inspection")
+        viewpoint = self.public_viewpoints[state]
+        set_agent(self.real.get_agent(0), position, viewpoint["rotation_xyzw"])
+        observations = self.real.get_sensor_observations()
+        self.last_observation = {
+            "rgb": np.asarray(observations["rgb"]),
+            "depth": np.asarray(observations["depth"]),
+        }
+        actual = np.asarray(observations["semantic"])
+        self.last_semantic = actual
+        actual_pixels = int(np.count_nonzero(actual == self.semantic_id))
+        if self.target_only is not None:
+            set_agent(self.target_only.get_agent(0), position, viewpoint["rotation_xyzw"])
+            projection = np.asarray(self.target_only.get_sensor_observations()["semantic"])
+            projected_pixels = int(np.count_nonzero(projection == self.semantic_id))
+        else:
+            projected_pixels = self.projected_pixels[state]
+        visible_fraction = min(1.0, actual_pixels / projected_pixels) if projected_pixels else 0.0
+        goal_distance = min(
+            self.distance(position, goal["position_xyz"])
+            for goal in self.truth["valid_goal_viewpoints"]
+        )
+        if self.detector is not None and hasattr(self.detector, "detect_instances"):
+            self.last_detections = self.detector.detect_instances(
+                np.asarray(observations["rgb"]), self.target_category
+            )
+            detected = bool(self.last_detections)
+        elif self.detector is not None:
+            self.last_detections = ()
+            detected = self.detector(
+                np.asarray(observations["rgb"]),
+                np.asarray(observations["depth"]),
+                self.target_category,
+            )
+        else:
+            self.last_detections = ()
+            detected = actual_pixels > 0
+        return {
+            "detected": detected,
+            "visible_fraction": visible_fraction,
+            "distance_to_valid_goal_m": goal_distance,
+            "visible_target_pixels": actual_pixels,
+            "projected_target_pixels": projected_pixels,
+        }
+
+    def move_target(self, event: dict) -> None:
+        if self.real is None or self.object_id is None:
+            raise RuntimeError("prepare an episode before moving its target")
+        position = mn.Vector3(*event["target_position_xyz"])
+        self.real.get_rigid_object_manager().get_object_by_id(self.object_id).translation = position
+        if self.target_only is not None and self.target_only_object_id is not None:
+            self.target_only.get_rigid_object_manager().get_object_by_id(
+                self.target_only_object_id
+            ).translation = position
+        self.real.perform_discrete_collision_detection()
+        self.truth["target_position_xyz"] = event["target_position_xyz"]
+        if "valid_goal_viewpoints" in event:
+            self.truth["valid_goal_viewpoints"] = event["valid_goal_viewpoints"]
+        if "current_state_id" in event:
+            self.truth["current_state_id"] = event["current_state_id"]
+
+    def clear(self) -> None:
+        if self.real is not None and self.object_id is not None:
+            self.real.get_rigid_object_manager().remove_object_by_id(self.object_id)
+        self.object_id = None
+        self.truth = None
+        self.last_observation = None
+        self.last_detections = ()
+        self.last_semantic = None
+        if self.target_only is not None:
+            self.target_only.close()
+            self.target_only = None
+            self.target_only_object_id = None
+
+    def close(self) -> None:
+        self.clear()
+        if self.real is not None:
+            self.real.close()
+            self.real = None

code/evolvingnav_paper/calibration.py

@@ -0,0 +1,66 @@
+"""Validation-only logistic calibration of online detector recall."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from sklearn.linear_model import LogisticRegression
+from sklearn.preprocessing import StandardScaler
+
+
+FEATURES = (
+    "coverage", "range_m", "angle_cos", "projected_pixels",
+    "depth_quality", "category_recall",
+)
+
+
+@dataclass(frozen=True)
+class DetectionCalibrator:
+    intercept: float
+    coefficients: tuple[float, ...]
+    means: tuple[float, ...]
+    scales: tuple[float, ...]
+
+    @classmethod
+    def fit(cls, validation_rows: list[dict]) -> "DetectionCalibrator":
+        if not validation_rows or {int(row["detected"]) for row in validation_rows} != {0, 1}:
+            raise ValueError("calibration requires positive and negative validation observations")
+        features = np.asarray(
+            [[float(row[key]) for key in FEATURES] for row in validation_rows], dtype=float
+        )
+        if not np.isfinite(features).all():
+            raise ValueError("calibration features must be finite")
+        scaler = StandardScaler().fit(features)
+        classifier = LogisticRegression(max_iter=1000).fit(
+            scaler.transform(features), [int(row["detected"]) for row in validation_rows]
+        )
+        return cls(
+            float(classifier.intercept_[0]), tuple(classifier.coef_[0].tolist()),
+            tuple(scaler.mean_.tolist()), tuple(scaler.scale_.tolist()),
+        )
+
+    def predict(self, online_features: dict) -> float:
+        values = np.asarray([float(online_features[key]) for key in FEATURES])
+        standardized = (values - self.means) / self.scales
+        logit = self.intercept + float(np.dot(self.coefficients, standardized))
+        return float(1.0 / (1.0 + np.exp(-np.clip(logit, -30, 30))))
+
+    def save(self, path: Path) -> None:
+        path.write_text(json.dumps({
+            "intercept": self.intercept, "coefficients": self.coefficients,
+            "means": self.means, "scales": self.scales,
+            "features": FEATURES,
+        }, indent=2) + "\n", encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> "DetectionCalibrator":
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if tuple(data["features"]) != FEATURES:
+            raise ValueError("calibrator feature schema mismatch")
+        return cls(
+            float(data["intercept"]), tuple(data["coefficients"]),
+            tuple(data["means"]), tuple(data["scales"]),
+        )

code/evolvingnav_paper/controller.py

@@ -0,0 +1,65 @@
+"""Frozen GPT-5.6-Luna function-call controller for legal high-level actions."""
+
+from __future__ import annotations
+
+import json
+import os
+from urllib.request import Request, urlopen
+
+
+class LunaToolController:
+    def __init__(self, *, requester=None) -> None:
+        self.requester = requester or self._request
+
+    @staticmethod
+    def _request(payload: dict) -> dict:
+        key = os.environ.get("OPENAI_API_KEY")
+        if not key:
+            raise RuntimeError("OPENAI_API_KEY is required for the Luna controller")
+        request = Request(
+            "https://api.openai.com/v1/responses",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+            method="POST",
+        )
+        with urlopen(request, timeout=60) as response:
+            return json.load(response)
+
+    def choose(self, legal_actions: list[str], public_context: dict) -> str:
+        if not legal_actions:
+            raise ValueError("controller needs at least one legal action")
+        forbidden = ("private", "ground_truth", "true_state", "target_position_xyz",
+                     "oracle_shortest_path")
+        if any(token in str(key).lower() for key in public_context for token in forbidden):
+            raise ValueError("evaluator-private field in controller context")
+        payload = {
+            "model": "gpt-5.6-luna",
+            "input": [
+                {"role": "system", "content": (
+                    "You are a frozen embodied-search tool controller. Choose one legal high-level "
+                    "action using only the supplied public belief, memory, costs and evidence. "
+                    "Prefer the maximum paper utility and never infer evaluator-private truth."
+                )},
+                {"role": "user", "content": json.dumps(public_context, ensure_ascii=False)},
+            ],
+            "tools": [{
+                "type": "function", "name": "select_action",
+                "description": "Choose one legal EvolvingNav high-level action.",
+                "strict": True,
+                "parameters": {
+                    "type": "object",
+                    "properties": {"action": {"type": "string", "enum": legal_actions}},
+                    "required": ["action"], "additionalProperties": False,
+                },
+            }],
+            "tool_choice": {"type": "function", "name": "select_action"},
+        }
+        response = self.requester(payload)
+        calls = [item for item in response.get("output", [])
+                 if item.get("type") == "function_call" and item.get("name") == "select_action"]
+        if len(calls) != 1:
+            raise ValueError("Luna did not return exactly one select_action call")
+        action = json.loads(calls[0]["arguments"])["action"]
+        if action not in legal_actions:
+            raise ValueError("Luna selected an illegal action")
+        return action

code/evolvingnav_paper/coverage.py

@@ -0,0 +1,81 @@
+"""Project public candidate geometry into an online depth frame (Appendix A.4)."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+
+def candidate_surface_samples(center_xyz, radius_m: float = 0.15,
+                              place_points=None) -> np.ndarray:
+    """A 5x5 surface grid from public receptacle slots or a center fallback."""
+    center = np.asarray(center_xyz, dtype=float)
+    if place_points:
+        points = np.asarray(place_points, dtype=float)
+        xs = np.linspace(points[:, 0].min(), points[:, 0].max(), 5)
+        zs = np.linspace(points[:, 2].min(), points[:, 2].max(), 5)
+        height = float(np.median(points[:, 1]))
+        return np.asarray([[x, height, z] for x in xs for z in zs])
+    offsets = np.linspace(-radius_m, radius_m, 5)
+    return np.asarray([center + [x, 0.0, z] for x in offsets for z in offsets])
+
+
+def _rotation(xyzw) -> np.ndarray:
+    x, y, z, w = np.asarray(xyzw, dtype=float)
+    norm = x*x + y*y + z*z + w*w
+    if norm <= 0:
+        raise ValueError("invalid camera orientation")
+    s = 2.0 / norm
+    return np.array([
+        [1-s*(y*y+z*z), s*(x*y-z*w), s*(x*z+y*w)],
+        [s*(x*y+z*w), 1-s*(x*x+z*z), s*(y*z-x*w)],
+        [s*(x*z-y*w), s*(y*z+x*w), 1-s*(x*x+y*y)],
+    ])
+
+
+def camera_forward(xyzw) -> np.ndarray:
+    return _rotation(xyzw) @ np.array([0.0, 0.0, -1.0])
+
+
+def heading_quaternion(displacement_xyz) -> list[float]:
+    direction = np.asarray(displacement_xyz, dtype=float)
+    if math.hypot(direction[0], direction[2]) <= 1e-9:
+        raise ValueError("heading needs horizontal displacement")
+    yaw = math.atan2(-direction[0], -direction[2])
+    return [0.0, math.sin(yaw / 2), 0.0, math.cos(yaw / 2)]
+
+
+def depth_quality(depth: np.ndarray) -> float:
+    values = np.asarray(depth)
+    return float(np.mean(np.isfinite(values) & (values > 0)))
+
+
+def camera_transform(agent_xyz, agent_xyzw, sensor_height_m: float = 1.35) -> np.ndarray:
+    rotation = _rotation(agent_xyzw)
+    transform = np.eye(4, dtype=float)
+    transform[:3, :3] = rotation
+    transform[:3, 3] = np.asarray(agent_xyz, dtype=float) + rotation @ [0, sensor_height_m, 0]
+    return transform
+
+
+def visible_sample_ids(samples: np.ndarray, agent_xyz, agent_xyzw, depth: np.ndarray,
+                       hfov_degrees: float, *, sensor_height_m: float = 1.35,
+                       depth_tolerance_m: float = 0.25) -> frozenset[int]:
+    height, width = depth.shape
+    transform = camera_transform(agent_xyz, agent_xyzw, sensor_height_m)
+    rotation = transform[:3, :3]
+    camera_xyz = transform[:3, 3]
+    camera_points = (np.asarray(samples, dtype=float) - camera_xyz) @ rotation
+    focal = width / (2.0 * math.tan(math.radians(hfov_degrees) / 2.0))
+    visible: set[int] = set()
+    for index, (x, y, z) in enumerate(camera_points):
+        if z >= -0.05:
+            continue
+        u = int(round(width / 2 + focal * x / -z))
+        v = int(round(height / 2 - focal * y / -z))
+        if 0 <= u < width and 0 <= v < height:
+            measured = float(depth[v, u])
+            if math.isfinite(measured) and measured > 0 and abs(measured + z) <= depth_tolerance_m:
+                visible.add(index)
+    return frozenset(visible)

code/evolvingnav_paper/evaluate.py

@@ -0,0 +1,67 @@
+"""Evaluator-only truth access and high-level N1/N2 scoring."""
+
+from __future__ import annotations
+
+import math
+from typing import Callable
+
+
+def evaluate_search(
+    episode: dict,
+    truth: dict,
+    belief: dict[int, float],
+    *,
+    start,
+    goals: dict,
+    distance: Callable,
+    inspect: Callable,
+    task: str = "n2",
+) -> dict:
+    from evolvingnav_paper.policy import rank_candidates
+
+    if task not in {"n1", "n2"}:
+        raise ValueError(task)
+    true_state = int(truth["current_state_id"])
+    oracle_m = float(truth["oracle_shortest_path_m"])
+    max_inspections = 1 if task == "n1" else int(episode["episode_budget"]["max_candidate_inspections"])
+    max_path = float(episode["episode_budget"]["max_path_length_m"])
+    current, travelled, inspected, actions, evidence = start, 0.0, [], [], []
+    remaining = set(belief) & set(goals)
+    success = False
+    for _ in range(max_inspections):
+        costs = {state: float(distance(current, goals[state])) for state in remaining}
+        reachable = {state: belief[state] for state in remaining if math.isfinite(costs[state])}
+        if not reachable:
+            break
+        state = rank_candidates(reachable, costs, task=task)[0]
+        goal = goals[state]
+        leg = costs[state]
+        if not math.isfinite(leg) or travelled + leg > max_path:
+            break
+        travelled += leg
+        inspected.append(state)
+        actions.extend((f"NAVIGATE_TO({state})", f"INSPECT({state})"))
+        current = goal
+        observation = inspect(state, goal)
+        evidence.append({"state_id": state, **observation})
+        if observation["detected"]:
+            actions.append("STOP")
+            success = (
+                float(observation["distance_to_valid_goal_m"])
+                <= float(episode["success_spec"]["max_geodesic_distance_m"])
+                and float(observation["visible_fraction"]) >= 0.20
+            )
+            break
+        remaining.remove(state)
+    return {
+        "base_episode_id": episode["base_episode_id"],
+        "task": task,
+        "success": success,
+        "inspections": len(inspected),
+        "inspection_order": inspected,
+        "inspection_evidence": evidence,
+        "actions": actions,
+        "path_m": round(travelled, 6),
+        "spl": round(float(success) * oracle_m / max(travelled, oracle_m, 1e-9), 6),
+        "true_state_id": true_state,
+    }

code/evolvingnav_paper/filter.py

@@ -0,0 +1,101 @@
+"""Current-time filtering, counterfactual arrival forecasts, and evidence rounds."""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+
+import numpy as np
+
+
+class BeliefFilter:
+    def __init__(self, prior: dict[int, float], transition) -> None:
+        if not prior or any(v < 0 for v in prior.values()) or sum(prior.values()) <= 0:
+            raise ValueError("prior must be a nonempty probability distribution")
+        total = sum(prior.values())
+        self.posterior = {int(k): float(v / total) for k, v in prior.items()}
+        self.transition = transition
+        self.applied_evidence: set[str] = set()
+
+    def arrival(self, elapsed_s: float) -> dict[int, float]:
+        if elapsed_s < 0:
+            raise ValueError("time cannot go backwards")
+        states = list(self.posterior)
+        kernel = self.transition.matrix(states, elapsed_s)
+        prediction = np.asarray(list(self.posterior.values())) @ kernel
+        return dict(zip(states, prediction.tolist(), strict=True))
+
+    def advance(self, elapsed_s: float) -> None:
+        self.posterior = self.arrival(elapsed_s)
+        if hasattr(self.transition, "advance_clock"):
+            self.transition.advance_clock(elapsed_s)
+
+    def negative(self, detection_probability: dict[int, float], evidence_id: str) -> bool:
+        if evidence_id in self.applied_evidence:
+            return False
+        unnormalized = {
+            state: probability * (1.0 - float(detection_probability.get(state, 0.0)))
+            for state, probability in self.posterior.items()
+        }
+        if any(value < 0 for value in unnormalized.values()):
+            raise ValueError("detection probability must be in [0, 1]")
+        total = sum(unnormalized.values())
+        if total <= 0:
+            raise ValueError("measurement removes all belief mass")
+        self.posterior = {state: value / total for state, value in unnormalized.items()}
+        self.applied_evidence.add(evidence_id)
+        return True
+
+
+class EvidenceLedger:
+    def __init__(self, *, min_new_coverage: float = 0.05, sufficient_coverage: float = 0.70,
+                 sample_count: dict[int, int] | None = None) -> None:
+        self.min_new_coverage = min_new_coverage
+        self.sufficient_coverage = sufficient_coverage
+        self.sample_count = sample_count or {}
+        self._round = defaultdict(int)
+        self._covered: dict[tuple[int, int], set[int]] = defaultdict(set)
+        self._used: set[str] = set()
+        self._inspected: set[int] = set()
+        self._last_round_time: dict[int, float] = {}
+
+    def round(self, state: int) -> int:
+        return self._round[state]
+
+    def coverage(self, state: int) -> float:
+        samples = self.sample_count.get(state, 1)
+        return len(self._covered[(state, self.round(state))]) / samples
+
+    def admit(self, evidence) -> float:
+        if evidence.evidence_id in self._used:
+            return 0.0
+        state = evidence.state_id
+        previous = self._covered[(state, self.round(state))]
+        new = set(evidence.surface_samples) - previous
+        fraction = len(new) / self.sample_count.get(state, max(len(new), 1))
+        self._used.add(evidence.evidence_id)
+        if fraction <= self.min_new_coverage:
+            return 0.0
+        previous.update(new)
+        return min(1.0, fraction)
+
+    def mark_inspected(self, state: int, now_s: float | None = None) -> None:
+        self._inspected.add(state)
+        if now_s is not None:
+            self._last_round_time[state] = now_s
+
+    def eligible(self, state: int, *, belief: float, return_probability: float,
+                 new_coverage: float, dynamic: bool = True,
+                 now_s: float | None = None) -> bool:
+        if state not in self._inspected and self.coverage(state) < self.sufficient_coverage:
+            return True
+        if new_coverage > self.min_new_coverage:
+            return True
+        time_passed = now_s is None or now_s > self._last_round_time.get(state, -math.inf)
+        if dynamic and time_passed and (belief > 0.10 or return_probability > 0.05):
+            self._round[state] += 1
+            self._inspected.discard(state)
+            if now_s is not None:
+                self._last_round_time[state] = now_s
+            return True
+        return False

code/evolvingnav_paper/habitat_utils.py

@@ -0,0 +1,67 @@
+"""Habitat-Sim camera, NavMesh and agent-pose helpers."""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Any
+
+import habitat_sim
+import numpy as np
+
+
+def sensor_specs(width: int, height: int) -> list[Any]:
+    specs = []
+    for name, sensor_type in (
+        ("rgb", habitat_sim.SensorType.COLOR),
+        ("depth", habitat_sim.SensorType.DEPTH),
+        ("semantic", habitat_sim.SensorType.SEMANTIC),
+    ):
+        spec = habitat_sim.CameraSensorSpec()
+        spec.uuid = name
+        spec.sensor_type = sensor_type
+        spec.sensor_subtype = habitat_sim.SensorSubType.PINHOLE
+        spec.resolution = [height, width]
+        spec.position = [0.0, 1.35, 0.0]
+        spec.hfov = 79.0
+        specs.append(spec)
+    return specs
+
+
+def make_simulator(
+    hssd: Path, scene_id: str, navmesh: Path, gpu: int, width: int, height: int
+) -> Any:
+    sim_config = habitat_sim.SimulatorConfiguration()
+    sim_config.scene_id = str(
+        (hssd / f"scenes-uncluttered/{scene_id}.scene_instance.json").resolve()
+    )
+    sim_config.scene_dataset_config_file = str(
+        (hssd / "hssd-hab-uncluttered.scene_dataset_config.json").resolve()
+    )
+    sim_config.enable_physics = True
+    sim_config.create_renderer = True
+    sim_config.load_semantic_mesh = True
+    sim_config.gpu_device_id = gpu
+    agent_config = habitat_sim.agent.AgentConfiguration()
+    agent_config.sensor_specifications = sensor_specs(width, height)
+    simulator = habitat_sim.Simulator(
+        habitat_sim.Configuration(sim_config, [agent_config])
+    )
+    if not simulator.pathfinder.load_nav_mesh(str(navmesh.resolve())):
+        simulator.close()
+        raise RuntimeError(f"cannot load navmesh {navmesh}")
+    return simulator
+
+
+def set_agent(agent: Any, position: list[float], xyzw: list[float]) -> None:
+    state = habitat_sim.AgentState()
+    state.position = np.asarray(position, dtype=np.float32)
+    state.rotation = np.asarray(xyzw, dtype=np.float32)
+    agent.set_state(state)
+
+
+def path_distance(pathfinder: Any, start: list[float], goal: list[float]) -> float:
+    path = habitat_sim.ShortestPath()
+    path.requested_start = np.asarray(start, dtype=np.float32)
+    path.requested_end = np.asarray(goal, dtype=np.float32)
+    return float(path.geodesic_distance) if pathfinder.find_path(path) else math.inf

code/evolvingnav_paper/memory.py

@@ -0,0 +1,106 @@
+"""Causal, time-valid 4D entity memory (paper Equations 3, 17 and 18)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+import numpy as np
+
+
+def backproject(u: float, v: float, depth_m: float, intrinsics: np.ndarray,
+                camera_to_world: np.ndarray) -> np.ndarray:
+    if not np.isfinite(depth_m) or depth_m <= 0:
+        raise ValueError("depth must be positive and finite")
+    ray = np.linalg.solve(np.asarray(intrinsics, dtype=float), [u, v, 1.0])
+    camera_point = np.r_[depth_m * ray, 1.0]
+    world = np.asarray(camera_to_world, dtype=float) @ camera_point
+    return world[:3] / world[3]
+
+
+@dataclass
+class EntityVersion:
+    valid_from: float
+    valid_to: float | None
+    state_id: int
+    confidence: float
+    feature: tuple[float, ...] = ()
+    evidence_handles: list[str] = field(default_factory=list)
+    world_points: list[tuple[float, float, float]] = field(default_factory=list)
+    evidence_times: list[float] = field(default_factory=list)
+    evidence_confidences: list[float] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class NegativeFrame:
+    evidence_id: str
+    state_id: int
+    timestamp: float
+    pose_xyz: tuple[float, float, float]
+
+
+class VersionedMemory:
+    def __init__(self) -> None:
+        self.entities: dict[str, list[EntityVersion]] = {}
+        self.used_evidence: set[str] = set()
+        self.negative_frames: list[NegativeFrame] = []
+
+    def record_negative(self, evidence_id: str, state_id: int, timestamp: float,
+                        pose_xyz) -> None:
+        if evidence_id in self.used_evidence:
+            return
+        self.negative_frames.append(NegativeFrame(
+            evidence_id, state_id, timestamp, tuple(float(x) for x in pose_xyz)
+        ))
+        self.used_evidence.add(evidence_id)
+
+    def evidence_at(self, cutoff: float) -> list[NegativeFrame]:
+        return [frame for frame in self.negative_frames if frame.timestamp <= cutoff]
+
+    def observe(self, entity_id: str, state_id: int, timestamp: float,
+                confidence: float, evidence_id: str, world_point: np.ndarray,
+                feature: tuple[float, ...] = ()) -> None:
+        if evidence_id in self.used_evidence:
+            return
+        versions = self.entities.setdefault(entity_id, [])
+        if versions and timestamp < versions[-1].valid_from:
+            raise ValueError("causal memory cannot accept an older observation")
+        if not 0 <= confidence <= 1:
+            raise ValueError("confidence must be a probability")
+        point = tuple(float(x) for x in world_point)
+        if versions and versions[-1].state_id == state_id:
+            current = versions[-1]
+            current.confidence = max(current.confidence, confidence)
+            current.evidence_handles.append(evidence_id)
+            current.world_points.append(point)
+            current.evidence_times.append(timestamp)
+            current.evidence_confidences.append(confidence)
+        else:
+            if versions:
+                versions[-1].valid_to = timestamp
+            versions.append(EntityVersion(timestamp, None, state_id, confidence,
+                                          feature, [evidence_id], [point],
+                                          [timestamp], [confidence]))
+        self.used_evidence.add(evidence_id)
+
+    @staticmethod
+    def _causal(version: EntityVersion, cutoff: float) -> EntityVersion:
+        indices = [i for i, time in enumerate(version.evidence_times) if time <= cutoff]
+        return replace(
+            version,
+            valid_to=version.valid_to if version.valid_to is not None and version.valid_to <= cutoff else None,
+            confidence=max(version.evidence_confidences[i] for i in indices),
+            evidence_handles=[version.evidence_handles[i] for i in indices],
+            world_points=[version.world_points[i] for i in indices],
+            evidence_times=[version.evidence_times[i] for i in indices],
+            evidence_confidences=[version.evidence_confidences[i] for i in indices],
+        )
+
+    def at(self, entity_id: str, timestamp: float) -> EntityVersion | None:
+        for version in reversed(self.entities.get(entity_id, [])):
+            if version.valid_from <= timestamp and (version.valid_to is None or timestamp < version.valid_to):
+                return self._causal(version, timestamp)
+        return None
+
+    def history(self, entity_id: str, cutoff: float) -> list[EntityVersion]:
+        return [self._causal(v, cutoff)
+                for v in self.entities.get(entity_id, []) if v.valid_from <= cutoff]

code/evolvingnav_paper/perception.py

@@ -0,0 +1,120 @@
+"""Frozen Grounding DINO and SAM2 target-category inspection."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import yaml
+
+Detection = tuple[str, float, tuple[float, float, float, float]]
+Detector = Callable[[np.ndarray, tuple[str, ...]], tuple[Detection, ...]]
+Segmenter = Callable[[np.ndarray, tuple[float, float, float, float]], np.ndarray]
+
+
+@dataclass(frozen=True)
+class InstanceDetection:
+    category: str
+    confidence: float
+    mask: np.ndarray
+
+
+def detect_instances(detector: Detector, segmenter: Segmenter,
+                     rgb: np.ndarray, category: str) -> tuple[InstanceDetection, ...]:
+    image = np.asarray(rgb)[..., :3]
+    found = []
+    for label, score, box in detector(image, (category,)):
+        if label != category:
+            continue
+        mask = np.asarray(segmenter(image, box), dtype=bool)
+        if mask.shape == image.shape[:2] and mask.any():
+            found.append(InstanceDetection(label, float(score), mask))
+    return tuple(found)
+
+
+def detect_category(
+    detector: Detector, segmenter: Segmenter, rgb: np.ndarray, category: str
+) -> bool:
+    """Use only the rendered RGB image and public target category for STOP."""
+    return bool(detect_instances(detector, segmenter, rgb, category))
+
+
+class GroundedSAMInspector:
+    """Frozen public models; the private semantic image never enters these heads."""
+
+    def __init__(self, config_path: Path, *, dino_model: str, sam_model: str) -> None:
+        config = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+        self.detector, self.segmenter = _load_models(
+            dino_model, sam_model, config
+        )
+
+    def __call__(self, rgb: np.ndarray, _depth: np.ndarray, category: str) -> bool:
+        return detect_category(self.detector, self.segmenter, rgb, category)
+
+    def detect_instances(self, rgb: np.ndarray, category: str) -> tuple[InstanceDetection, ...]:
+        return detect_instances(self.detector, self.segmenter, rgb, category)
+
+    def close(self) -> None:
+        del self.detector, self.segmenter
+
+
+def _load_models(dino_model: str, sam_model: str, config: dict):
+    import torch
+    from PIL import Image
+    from transformers import (
+        AutoModelForZeroShotObjectDetection,
+        AutoProcessor,
+        Sam2Model,
+        Sam2Processor,
+    )
+
+    device = config["device"]
+    dino_revision = config["grounding_dino"]["revision"]
+    sam_revision = config["sam"]["revision"]
+    dino_kwargs = {"revision": dino_revision} if dino_model == config["grounding_dino"]["model_id"] else {}
+    sam_kwargs = {"revision": sam_revision} if sam_model == config["sam"]["model_id"] else {}
+    dino_processor = AutoProcessor.from_pretrained(dino_model, **dino_kwargs)
+    dino = AutoModelForZeroShotObjectDetection.from_pretrained(
+        dino_model, **dino_kwargs
+    ).to(device).eval()
+    sam_processor = Sam2Processor.from_pretrained(sam_model, **sam_kwargs)
+    sam = Sam2Model.from_pretrained(sam_model, **sam_kwargs).to(device).eval()
+
+    def detector(rgb: np.ndarray, categories: tuple[str, ...]) -> tuple[Detection, ...]:
+        image = Image.fromarray(rgb)
+        inputs = dino_processor(
+            images=image, text=[list(categories)], return_tensors="pt"
+        ).to(device)
+        with torch.inference_mode():
+            outputs = dino(**inputs)
+        processed = dino_processor.post_process_grounded_object_detection(
+            outputs,
+            inputs.input_ids,
+            threshold=config["grounding_dino"]["box_threshold"],
+            text_threshold=config["grounding_dino"]["text_threshold"],
+            target_sizes=[image.size[::-1]],
+        )[0]
+        labels = processed.get("text_labels", processed.get("labels", ()))
+        return tuple(
+            (str(label), float(score), tuple(float(value) for value in box))
+            for label, score, box in zip(
+                labels, processed["scores"], processed["boxes"], strict=True
+            )
+        )
+
+    def segmenter(rgb: np.ndarray, box: tuple[float, float, float, float]) -> np.ndarray:
+        image = Image.fromarray(rgb)
+        inputs = sam_processor(
+            images=image, input_boxes=[[[*box]]], return_tensors="pt"
+        ).to(device)
+        with torch.inference_mode():
+            outputs = sam(**inputs)
+        masks = sam_processor.post_process_masks(
+            outputs.pred_masks.cpu(), inputs["original_sizes"]
+        )[0]
+        scores = outputs.iou_scores[0, 0].cpu()
+        return masks[0, int(scores.argmax())].numpy().astype(bool)
+
+    return detector, segmenter

code/evolvingnav_paper/policy.py

@@ -0,0 +1,126 @@
+"""Public-input belief and candidate selection for the N1/N2 high-level track."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from pack_p4d_hssd_records import pack_split
+from readyagent.p4d_belief.data import MODEL_INPUT_KEYS, OPTIONAL_MODEL_INPUT_KEYS, derive_last_state
+
+
+def pack_public_query(query: dict, schema: dict, candidate_features: dict) -> dict[str, np.ndarray]:
+    """Reuse the frozen feature schema without passing evaluator labels to the model."""
+    query_time = float(query["input"]["query"]["query_time_s"])
+    for field in ("target_history", "observable_context_history"):
+        timestamps = [float(row["timestamp_s"]) for row in query["input"].get(field, [])]
+        if any(timestamp > query_time for timestamp in timestamps):
+            raise ValueError(f"future observation in {field}")
+        if timestamps != sorted(timestamps):
+            raise ValueError(f"out-of-order observation in {field}")
+    record = {
+        "record_id": query["query_id"],
+        "world_variant": "routine",  # packer metadata only; discarded below
+        "input": query["input"],
+        "supervision": {"current_state_id": 0, "moved_since_last_positive": False},
+    }
+    packed = pack_split(
+        [record],
+        max_history=64,
+        category_to_id=schema["category_to_id"],
+        state_count=int(schema["state_count_including_unknown"]),
+        candidate_features=candidate_features,
+    )
+    allowed = (*MODEL_INPUT_KEYS, *OPTIONAL_MODEL_INPUT_KEYS, "instance_uuid")
+    return {key: packed[key] for key in allowed if key in packed}
+
+
+def candidate_utility(
+    *, arrival_probability: float, new_detection_probability: float,
+    distance_m: float, eta_s: float, lambda_time: float, lambda_inspect: float,
+) -> float:
+    """Equation (12): arrival belief times new detection chance per action cost."""
+    denominator = distance_m + lambda_time * eta_s + lambda_inspect
+    if not math.isfinite(denominator) or denominator <= 0:
+        return -math.inf
+    return arrival_probability * new_detection_probability / denominator
+
+
+def rank_candidates(
+    belief: dict[int, float], public_costs: dict[int, float], *, task: str = "n2",
+    detection_probabilities: dict[int, float] | None = None,
+    speed_mps: float = 1.0, inspection_s: float = 1.0,
+    lambda_time: float = 0.05, lambda_inspect: float = 0.25,
+) -> list[int]:
+    """N1 takes Top-1; fixed-target N2 applies Equation (12) to public viewpoints."""
+    if not belief:
+        return []
+    if task == "n1":
+        return [max(belief, key=lambda state: (belief[state], -state))]
+    if task != "n2":
+        raise ValueError(task)
+    if speed_mps <= 0:
+        raise ValueError("speed_mps must be positive")
+    detection_probabilities = detection_probabilities or {}
+    return sorted(
+        belief,
+        key=lambda state: (
+            -candidate_utility(
+                arrival_probability=belief[state],
+                new_detection_probability=detection_probabilities.get(state, 1.0),
+                distance_m=public_costs[state],
+                eta_s=public_costs[state] / speed_mps + inspection_s,
+                lambda_time=lambda_time,
+                lambda_inspect=lambda_inspect,
+            ),
+            state,
+        ),
+    )
+
+
+def load_belief(checkpoint_path, dataset_root):
+    import torch
+    from readyagent.p4d_belief.data import load_catalog
+    from readyagent.p4d_belief.models import ModelConfig
+    from readyagent.p4d_belief.training import build_model
+
+    catalog = load_catalog(dataset_root)
+    checkpoint = torch.load(checkpoint_path, map_location="cpu", weights_only=True)
+    if checkpoint.get("model_name", "p4d" if "transition_head" in checkpoint else None) != "p4d":
+        raise ValueError("checkpoint is not a P4D belief model")
+    model = build_model("p4d", catalog, ModelConfig(**checkpoint["model_config"]))
+    model.load_state_dict(checkpoint["model"])
+    return model.eval(), catalog.schema
+
+
+def model_input_batch(arrays: dict[str, np.ndarray], schema: dict):
+    """Strict public-input allowlist for belief and transition inference."""
+    import torch
+
+    last_state = int(derive_last_state(arrays)[0])
+    candidates = arrays["candidate_state_ids"][0].tolist()
+    last_index = candidates.index(last_state)
+    instance = str(arrays["instance_uuid"][0])
+    vocabulary = schema.get("instance_uuid_to_id", {})
+    if instance not in vocabulary:
+        raise ValueError(f"unseen instance identity for this checkpoint: {instance}")
+    batch = {
+        key: torch.as_tensor(arrays[key])
+        for key in (*MODEL_INPUT_KEYS, *OPTIONAL_MODEL_INPUT_KEYS)
+        if key in arrays
+    }
+    batch["target_instance_id"] = torch.tensor([vocabulary[instance]])
+    batch["last_state"] = torch.tensor([last_state])
+    batch["last_candidate_index"] = torch.tensor([last_index])
+    return batch
+
+
+def predict_public(model, schema: dict, arrays: dict[str, np.ndarray]) -> dict[int, float]:
+    batch = model_input_batch(arrays, schema)
+    candidates = arrays["candidate_state_ids"][0].tolist()
+    import torch
+
+    with torch.inference_mode():
+        probabilities = model(batch)["probabilities"][0].cpu().numpy()
+    return {int(state): float(probabilities[index]) for index, state in enumerate(candidates) if state >= 0}

code/evolvingnav_paper/run.py

@@ -0,0 +1,272 @@
+"""Run P4D-HSSD navigation episodes with belief or closed-loop Agent control."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import numpy as np
+
+from evolvingnav_paper.backend import HabitatInspectionBackend
+from evolvingnav_paper.agent import Agent, AgentConfig
+from evolvingnav_paper.calibration import DetectionCalibrator
+from evolvingnav_paper.controller import LunaToolController
+from evolvingnav_paper.evaluate import evaluate_search
+from evolvingnav_paper.memory import VersionedMemory
+from evolvingnav_paper.perception import GroundedSAMInspector
+from evolvingnav_paper.policy import load_belief, model_input_batch, pack_public_query, predict_public
+from evolvingnav_paper.transition import IdentityTransition
+from evolvingnav_paper.transition_model import NeuralTransition, TransitionHead
+from evolvingnav_paper.world import HabitatAgentWorld
+
+CODE_ROOT = Path(__file__).resolve().parents[1]
+
+
+def rows(path: Path):
+    with path.open(encoding="utf-8") as handle:
+        for line in handle:
+            if line.strip():
+                yield json.loads(line)
+
+
+def arguments(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--task", choices=("n1", "n2", "n3", "n4"), default="n3")
+    parser.add_argument("--agent", action="store_true", help="Run the event-driven Agent for N1/N2 as well")
+    parser.add_argument("--controller", choices=("utility", "luna"), default="utility")
+    parser.add_argument("--limit", type=int, default=5)
+    parser.add_argument("--world", choices=("routine", "random", "static"), default="routine")
+    parser.add_argument("--dataset", type=Path, required=True)
+    parser.add_argument("--tasks", type=Path, required=True)
+    parser.add_argument("--checkpoint", type=Path, required=True)
+    parser.add_argument("--transition-checkpoint", type=Path)
+    parser.add_argument("--inspection", choices=("semantic-oracle", "grounded-sam"), default="grounded-sam")
+    parser.add_argument("--hssd-root", type=Path, required=True)
+    parser.add_argument("--navmesh-root", type=Path, required=True)
+    parser.add_argument("--grounding-dino-model", default="IDEA-Research/grounding-dino-tiny")
+    parser.add_argument("--sam2-model", default="facebook/sam2.1-hiera-tiny")
+    parser.add_argument("--perception-config", type=Path, default=CODE_ROOT / "configs/perception.yaml")
+    parser.add_argument("--calibration", type=Path)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args(argv)
+    if args.limit < 1:
+        parser.error("--limit must be positive")
+    if args.task == "n4" and args.transition_checkpoint is None:
+        parser.error("N4 requires --transition-checkpoint")
+    return args
+
+
+def main() -> int:
+    args = arguments()
+    if args.output.exists():
+        raise FileExistsError(f"output already exists: {args.output}")
+
+    episodes = []
+    for episode in rows(args.tasks / f"public/episodes_{args.task}.jsonl"):
+        if episode["world_variant"] == args.world:
+            episodes.append(episode)
+        if len(episodes) == args.limit:
+            break
+    if len(episodes) != args.limit:
+        raise ValueError(f"only found {len(episodes)} matching episodes")
+    wanted_queries = {episode["query_id"] for episode in episodes}
+    queries = {row["query_id"]: row for row in rows(args.tasks / "public/query_inputs.jsonl") if row["query_id"] in wanted_queries}
+    active_checkpoint = args.transition_checkpoint if args.task == "n4" else args.checkpoint
+    model, schema = load_belief(active_checkpoint, args.dataset)
+    transition_head = None
+    if args.task == "n4":
+        import torch
+
+        checkpoint = torch.load(active_checkpoint, map_location="cpu", weights_only=True)
+        transition_head = TransitionHead(checkpoint["model_config"]["hidden_dim"])
+        transition_head.load_state_dict(checkpoint["transition_head"])
+        transition_head.eval()
+    with np.load(args.dataset / "records/packed/train.npz", allow_pickle=False) as train:
+        features = {key: train[key] for key in (
+            "candidate_region_category_id", "candidate_receptacle_category_id",
+            "candidate_center_xyz", "candidate_is_unknown",
+        )}
+    catalog = json.loads((args.tasks / "catalogs/candidate_states_navigation.json").read_text())
+    public_viewpoints = {
+        int(row["state_id"]): row["navigation_viewpoint"]
+        for row in catalog["states"] if row.get("navigation_eligible")
+    }
+    public_goals = {state: row["position_xyz"] for state, row in public_viewpoints.items()}
+    all_centers = {
+        int(row["state_id"]): row["state_center"] for row in catalog["states"]
+    }
+    state_centers = {
+        int(row["state_id"]): row["state_center"]
+        for row in catalog["states"] if row.get("navigation_eligible")
+    }
+    surface_points = {
+        int(row["state_id"]): [slot["point"] for slot in row.get("sampled_place_points", [])]
+        for row in rows(args.tasks / "catalogs/receptacles.jsonl")
+    }
+    objects = {
+        row["instance_uuid"]: row
+        for row in rows(args.tasks / "catalogs/object_instances.jsonl")
+    }
+
+    decisions = []
+    query_batches = []
+    for episode in episodes:
+        query = queries[episode["query_id"]]
+        packed = pack_public_query(query, schema, features)
+        query_batches.append(model_input_batch(packed, schema))
+        belief = predict_public(model, schema, packed)
+        candidates = {
+            int(state): belief[int(state)]
+            for state in episode["public_refs"]["candidate_state_ids"]
+        }
+        decisions.append({
+            "base_episode_id": episode["base_episode_id"], "query_id": episode["query_id"],
+            "task": args.task, "belief": candidates,
+        })
+
+    wanted = {episode["base_episode_id"] for episode in episodes}
+    private = {
+        row["base_episode_id"]: row["evaluation_private"]
+        for row in rows(args.tasks / "private/evaluation_gt.jsonl")
+        if row["base_episode_id"] in wanted
+    }
+    scene_ids = {episode["scene_id"] for episode in episodes}
+    if len(scene_ids) != 1:
+        raise ValueError("--tasks must select episodes from one scene")
+    scene_id = next(iter(scene_ids))
+    navmesh = args.navmesh_root / f"{scene_id}.navmesh"
+    inspector = (
+        GroundedSAMInspector(
+            args.perception_config,
+            dino_model=args.grounding_dino_model,
+            sam_model=args.sam2_model,
+        )
+        if args.inspection == "grounded-sam" else None
+    )
+    backend = HabitatInspectionBackend(
+        args.hssd_root, scene_id, navmesh, public_viewpoints,
+        detector=inspector,
+    )
+    calibrator = DetectionCalibrator.load(args.calibration) if args.calibration else None
+    controller = LunaToolController() if args.controller == "luna" else None
+    scores = []
+    try:
+        for episode, decision in zip(episodes, decisions, strict=True):
+            truth = private[episode["base_episode_id"]]
+            backend.prepare(
+                truth, objects[episode["target"]["object_id"]],
+                [state for state in decision["belief"] if state in public_goals],
+                dynamic=args.task == "n4",
+            )
+            if args.task in {"n3", "n4"} or args.agent:
+                query = queries[episode["query_id"]]
+                target_id = query["input"]["target"]["instance_uuid"]
+                memory = VersionedMemory()
+                for index, event in enumerate(query["input"].get("target_history", [])):
+                    if event["event_type"] == "positive_observation":
+                        observed_state = int(event["observed_state_id"])
+                        memory.observe(
+                            target_id, observed_state, float(event["timestamp_s"]),
+                            float(event["detector_confidence"])
+                            * float(event["instance_match_confidence"]),
+                            f"{query['query_id']}:history:{index}",
+                            np.asarray(all_centers[observed_state]),
+                        )
+                motion_schedule = None
+                if args.task == "n4":
+                    motion_schedule = truth.get("target_motion_schedule")
+                    if motion_schedule is None:
+                        raise ValueError("N4 private evaluation record requires target_motion_schedule")
+                    required_motion = {
+                        "time_s", "target_position_xyz", "current_state_id",
+                        "valid_goal_viewpoints",
+                    }
+                    if any(required_motion - set(event) for event in motion_schedule):
+                        raise ValueError("N4 target_motion_schedule has incomplete motion events")
+                world = HabitatAgentWorld(
+                    backend, public_viewpoints,
+                    state_centers,
+                    episode["agent_start"]["position_xyz"],
+                    episode["agent_start"]["rotation_xyzw"],
+                    calibrator=calibrator,
+                    known_states=set(decision["belief"]),
+                    motion_schedule=motion_schedule,
+                    surface_points=surface_points,
+                )
+                unknown_ids = [int(i) for i, flag in enumerate(features["candidate_is_unknown"]) if flag]
+                can_explore = "EXPLORE" in episode["public_refs"].get("action_space", [])
+                transition = (NeuralTransition(model, transition_head, query_batches[len(scores)])
+                              if args.task == "n4" else IdentityTransition())
+                agent = Agent(
+                    decision["belief"], public_goals, world, transition,
+                    AgentConfig(
+                        max_inspections=1 if args.task == "n1" else int(
+                            episode["episode_budget"]["max_candidate_inspections"]),
+                        max_path_m=float(episode["episode_budget"]["max_path_length_m"]),
+                        chunk_m=2.0,
+                        unknown_state=unknown_ids[0] if can_explore and unknown_ids else None,
+                    ),
+                    sample_count={state: 25 for state in decision["belief"]},
+                    controller=controller,
+                    memory=memory, target_id=target_id,
+                    time_origin_s=float(query["input"]["query"]["query_time_s"]),
+                )
+                result = agent.run()
+                final = world.private_inspections[-1] if world.private_inspections else None
+                success = bool(
+                    result.found and final is not None
+                    and final["distance_to_valid_goal_m"]
+                    <= float(episode["success_spec"]["max_geodesic_distance_m"])
+                    and final["visible_fraction"] >= 0.20
+                )
+                oracle_m = float(truth["oracle_shortest_path_m"])
+                score = {
+                    "base_episode_id": episode["base_episode_id"],
+                    "task": args.task, "success": success,
+                    "inspections": len(result.inspections),
+                    "inspection_order": result.inspections,
+                    "inspection_evidence": world.private_inspections,
+                    "actions": result.actions, "path_m": round(result.path_m, 6),
+                    "spl": round(float(success) * oracle_m / max(result.path_m, oracle_m, 1e-9), 6),
+                    "true_state_id": int(backend.truth["current_state_id"]),
+                    "posterior": result.posterior,
+                    "termination": result.termination,
+                    "evidence_trace": result.evidence_trace,
+                }
+            else:
+                score = evaluate_search(
+                    episode, truth, decision["belief"],
+                    start=episode["agent_start"]["position_xyz"], goals=public_goals,
+                    distance=backend.distance, inspect=backend.inspect, task=args.task,
+                )
+            scores.append(score)
+            backend.clear()
+    finally:
+        backend.close()
+        if inspector is not None:
+            inspector.close()
+
+    args.output.mkdir(parents=True)
+    with (args.output / "policy.jsonl").open("w", encoding="utf-8") as handle:
+        for decision in decisions:
+            handle.write(json.dumps(decision, ensure_ascii=False) + "\n")
+    with (args.output / "scores.jsonl").open("w", encoding="utf-8") as handle:
+        for score in scores:
+            handle.write(json.dumps(score, ensure_ascii=False) + "\n")
+    summary = {
+        "task": args.task, "world": args.world, "episodes": len(scores),
+        "successes": sum(row["success"] for row in scores),
+        "sr": sum(row["success"] for row in scores) / len(scores),
+        "spl": sum(row["spl"] for row in scores) / len(scores),
+        "track": f"high_level_{'event_agent' if args.task in {'n3', 'n4'} or args.agent else 'ranked'}_{args.inspection}",
+        "min_visible_fraction": 0.20,
+        "dataset": str(args.tasks), "checkpoint": str(args.checkpoint),
+    }
+    (args.output / "summary.json").write_text(json.dumps(summary, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code/evolvingnav_paper/transition.py

@@ -0,0 +1,32 @@
+"""Row-normalized state transitions and fixed-target identity dynamics."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+class IdentityTransition:
+    dynamic = False
+
+    def matrix(self, states: list[int], elapsed_s: float) -> np.ndarray:
+        return np.eye(len(states), dtype=float)
+
+
+class MatrixTransition:
+    """A supplied row-stochastic transition, useful for deterministic integration tests."""
+
+    dynamic = True
+
+    def __init__(self, matrix: np.ndarray) -> None:
+        self.values = np.asarray(matrix, dtype=float)
+        if self.values.ndim != 2 or self.values.shape[0] != self.values.shape[1]:
+            raise ValueError("transition must be square")
+        if np.any(self.values < 0) or not np.allclose(self.values.sum(axis=1), 1):
+            raise ValueError("transition rows must sum to one")
+
+    def matrix(self, states: list[int], elapsed_s: float) -> np.ndarray:
+        if elapsed_s < 0:
+            raise ValueError("time cannot go backwards")
+        if len(states) != len(self.values):
+            raise ValueError("transition state count mismatch")
+        return np.eye(len(states)) if elapsed_s == 0 else self.values

code/evolvingnav_paper/transition_model.py

@@ -0,0 +1,177 @@
+"""Learned row-conditional transition head for N4 (Equations 10 and 19)."""
+
+from __future__ import annotations
+
+import math
+from bisect import bisect_right
+from collections import defaultdict
+
+import numpy as np
+import torch
+from torch import nn
+
+
+class TransitionHead(nn.Module):
+    """Shares the belief backbone's query/candidate embeddings; has separate parameters."""
+
+    def __init__(self, hidden_dim: int = 128) -> None:
+        super().__init__()
+        self.mlp = nn.Sequential(
+            nn.Linear(3 * hidden_dim + 4, hidden_dim),
+            nn.GELU(),
+            nn.Linear(hidden_dim, 1),
+        )
+
+    def forward(self, context: torch.Tensor, candidates: torch.Tensor,
+                horizon_s: torch.Tensor, candidate_mask: torch.Tensor) -> torch.Tensor:
+        batch, states, hidden = candidates.shape
+        if context.shape != (batch, hidden) or horizon_s.shape != (batch,):
+            raise ValueError("transition context or horizon has incorrect shape")
+        if torch.any(horizon_s < 0):
+            raise ValueError("transition horizon must be nonnegative")
+        phase = horizon_s.float() * (2 * math.pi / 86400.0)
+        time = torch.stack((torch.log1p(horizon_s.float()),
+                            torch.sin(phase), torch.cos(phase),
+                            horizon_s.float() / 86400.0), dim=-1)
+        features = torch.cat((
+            context[:, None, None, :].expand(-1, states, states, -1),
+            candidates[:, :, None, :].expand(-1, -1, states, -1),
+            candidates[:, None, :, :].expand(-1, states, -1, -1),
+            time[:, None, None, :].expand(-1, states, states, -1),
+        ), dim=-1)
+        logits = self.mlp(features).squeeze(-1)
+        logits = logits.masked_fill(~candidate_mask[:, None, :].bool(), -1e4)
+        probabilities = torch.softmax(logits, dim=-1)
+        return probabilities * candidate_mask[:, :, None].float()
+
+
+def transition_nll(kernel: torch.Tensor, source_index: torch.Tensor,
+                   destination_index: torch.Tensor) -> torch.Tensor:
+    rows = kernel[torch.arange(len(kernel), device=kernel.device), source_index.long()]
+    selected = rows.gather(1, destination_index.long()[:, None]).squeeze(1)
+    return -selected.clamp_min(1e-9).log().mean()
+
+
+def chronological_pairs(*, instance_ids: np.ndarray, world_ids: np.ndarray,
+                        times_s: np.ndarray, states: np.ndarray,
+                        max_horizon_s: float) -> list[tuple[int, int, float, int, int]]:
+    """Create train-only H<=ta, s(ta), delta, s(ta+delta) labels."""
+    groups: dict[tuple[str, int], list[int]] = defaultdict(list)
+    for index, (instance, world) in enumerate(zip(instance_ids, world_ids, strict=True)):
+        groups[(str(instance), int(world))].append(index)
+    pairs = []
+    for indices in groups.values():
+        ordered = sorted(indices, key=lambda i: float(times_s[i]))
+        for source, destination in zip(ordered, ordered[1:], strict=False):
+            horizon = float(times_s[destination] - times_s[source])
+            if 0 < horizon <= max_horizon_s:
+                pairs.append((source, destination, horizon,
+                              int(states[source]), int(states[destination])))
+    return pairs
+
+
+def event_horizon_pairs(*, instance_ids: np.ndarray, world_ids: np.ndarray,
+                        query_times_s: np.ndarray, query_states: np.ndarray,
+                        events: list[dict], horizons_s: tuple[float, ...]
+                        ) -> list[tuple[int, float, float, int, int]]:
+    """Sample short stationary and event-crossing tuples from one split's causal snapshots."""
+    if not horizons_s or any(h <= 0 for h in horizons_s):
+        raise ValueError("horizons must be positive")
+    groups: dict[tuple[str, int], list[int]] = defaultdict(list)
+    event_groups: dict[tuple[str, int], list[dict]] = defaultdict(list)
+    for index, (instance, world) in enumerate(zip(instance_ids, world_ids, strict=True)):
+        groups[(str(instance), int(world))].append(index)
+    for event in events:
+        event_groups[(str(event["instance_uuid"]), int(event.get("world_id", 0)))].append(event)
+    pairs: list[tuple[int, float, float, int, int]] = []
+    for (instance, world), indices in groups.items():
+        ordered = sorted(indices, key=lambda i: float(query_times_s[i]))
+        times = [float(query_times_s[i]) for i in ordered]
+        relevant = sorted(event_groups.get((instance, world), []),
+                          key=lambda event: float(event["event_time_s"]))
+        event_times = [float(event["event_time_s"]) for event in relevant]
+        for position, source in enumerate(ordered):
+            horizon = float(horizons_s[position % len(horizons_s)])
+            anchor = times[position]
+            if anchor + horizon > times[-1]:
+                continue
+            if bisect_right(event_times, anchor + horizon) == bisect_right(event_times, anchor):
+                state = int(query_states[source])
+                pairs.append((source, anchor, horizon, state, state))
+        for event_index, event in enumerate(relevant):
+            event_time = float(event["event_time_s"])
+            for horizon in horizons_s:
+                anchor = event_time - horizon / 2.0
+                future = anchor + horizon
+                if anchor < times[0] or future > times[-1]:
+                    continue
+                if (event_index > 0 and event_times[event_index - 1] >= anchor) or (
+                    event_index + 1 < len(event_times) and event_times[event_index + 1] <= future
+                ):
+                    continue
+                source_position = bisect_right(times, anchor) - 1
+                if source_position < 0:
+                    continue
+                pairs.append((
+                    ordered[source_position], anchor, float(horizon),
+                    int(event["source_state_id"]), int(event["destination_state_id"]),
+                ))
+    return pairs
+
+
+class NeuralTransition:
+    """Inference adapter that never receives transition labels or mobility tags."""
+
+    dynamic = True
+
+    def __init__(self, belief_model: nn.Module, head: TransitionHead,
+                 packed_batch: dict[str, torch.Tensor]) -> None:
+        self.model = belief_model.eval()
+        self.head = head.eval()
+        self.batch = {key: value.clone() for key, value in packed_batch.items()}
+        if self.batch["candidate_state_ids"].shape[0] != 1:
+            raise ValueError("N4 transition adapter expects one active episode")
+        self.elapsed_s = 0.0
+
+    def add_candidate(self, state_id: int) -> None:
+        present = self.batch["candidate_state_ids"][0].tolist()
+        if state_id in present:
+            return
+        self.batch["candidate_state_ids"] = torch.cat((
+            self.batch["candidate_state_ids"],
+            torch.tensor([[state_id]], dtype=self.batch["candidate_state_ids"].dtype),
+        ), dim=1)
+        self.batch["candidate_mask"] = torch.cat((
+            self.batch["candidate_mask"],
+            torch.ones((1, 1), dtype=self.batch["candidate_mask"].dtype),
+        ), dim=1)
+
+    def matrix(self, states: list[int], elapsed_s: float) -> np.ndarray:
+        if elapsed_s < 0:
+            raise ValueError("time cannot go backwards")
+        if elapsed_s == 0:
+            return np.eye(len(states), dtype=float)
+        device = next(self.model.parameters()).device
+        batch = {key: value.to(device) for key, value in self.batch.items()}
+        batch["query_time_days"] = batch["query_time_days"] + self.elapsed_s / 86400.0
+        batch["elapsed_since_last_positive_days"] = (
+            batch["elapsed_since_last_positive_days"] + self.elapsed_s / 86400.0
+        )
+        day_phase = 2 * math.pi * batch["query_time_days"]
+        batch["query_time_of_day_sin_cos"] = torch.stack(
+            (day_phase.sin(), day_phase.cos()), dim=-1
+        )
+        with torch.inference_mode():
+            context, candidates = self.model.backbone(batch)
+            kernel = self.head(
+                context, candidates, torch.tensor([elapsed_s], device=device),
+                batch["candidate_mask"],
+            )[0]
+        candidate_ids = batch["candidate_state_ids"][0].tolist()
+        index = [candidate_ids.index(state) for state in states]
+        return kernel[index][:, index].cpu().numpy()
+
+    def advance_clock(self, elapsed_s: float) -> None:
+        if elapsed_s < 0:
+            raise ValueError("time cannot go backwards")
+        self.elapsed_s += elapsed_s

code/evolvingnav_paper/verify_visual.py

@@ -0,0 +1,77 @@
+"""Render one scored success and confirm the benchmark visibility contract."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import numpy as np
+
+from evolvingnav_paper.backend import HabitatInspectionBackend
+from evolvingnav_paper.habitat_utils import set_agent
+from evolvingnav_paper.run import rows
+
+
+def arguments(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("run", type=Path, help="a completed N1/N2/N3 run directory")
+    parser.add_argument("--tasks", type=Path, required=True)
+    parser.add_argument("--hssd-root", type=Path, required=True)
+    parser.add_argument("--navmesh-root", type=Path, required=True)
+    return parser.parse_args(argv)
+
+
+def main() -> int:
+    args = arguments()
+    passed = next((row for row in rows(args.run / "scores.jsonl") if row["success"]), None)
+    if passed is None:
+        raise ValueError("run has no successful episode to verify")
+    episode_id = passed["base_episode_id"]
+    episode = next(row for row in rows(args.tasks / "public/base_episodes.jsonl") if row["base_episode_id"] == episode_id)
+    truth = next(row["evaluation_private"] for row in rows(args.tasks / "private/evaluation_gt.jsonl") if row["base_episode_id"] == episode_id)
+    target = next(row for row in rows(args.tasks / "catalogs/object_instances.jsonl") if row["instance_uuid"] == episode["target"]["object_id"])
+    stop_state = int(passed["inspection_order"][-1])
+    candidate_catalog = json.loads(
+        (args.tasks / "catalogs/candidate_states_navigation.json").read_text()
+    )
+    viewpoints = {
+        int(row["state_id"]): row["navigation_viewpoint"]
+        for row in candidate_catalog["states"] if row.get("navigation_eligible")
+    }
+    scene_id = episode["scene_id"]
+    navmesh = args.navmesh_root / f"{scene_id}.navmesh"
+    backend = HabitatInspectionBackend(args.hssd_root, scene_id, navmesh, viewpoints)
+    try:
+        backend.prepare(truth, target, [stop_state])
+        start = episode["agent_start"]
+        set_agent(backend.real.get_agent(0), start["position_xyz"], start["rotation_xyzw"])
+        start_pixels = int((np.asarray(backend.real.get_sensor_observations()["semantic"]) == int(target["semantic_instance_id"])).sum())
+        viewpoint = viewpoints[stop_state]
+        observation = backend.inspect(stop_state, viewpoint["position_xyz"])
+    finally:
+        backend.close()
+    result = {
+        "base_episode_id": episode_id,
+        "stop_state_id": stop_state,
+        "start_target_pixels": start_pixels,
+        "stop_target_pixels": observation["visible_target_pixels"],
+        "projected_target_pixels": observation["projected_target_pixels"],
+        "visible_fraction": observation["visible_fraction"],
+        "distance_to_valid_goal_m": observation["distance_to_valid_goal_m"],
+        "start_hidden": start_pixels == 0,
+        "stop_visible": observation["visible_fraction"] >= 0.20,
+        "valid_stop_distance": observation["distance_to_valid_goal_m"] <= 1.0,
+        "stop_action": passed["actions"][-1] == "STOP",
+        "matches_record": observation["visible_fraction"] == passed["inspection_evidence"][-1]["visible_fraction"],
+    }
+    result["passed"] = all(result[key] for key in (
+        "start_hidden", "stop_visible", "valid_stop_distance", "stop_action", "matches_record",
+    ))
+    (args.run / "visual_check.json").write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(result, indent=2))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code/evolvingnav_paper/world.py

@@ -0,0 +1,202 @@
+"""High-level Habitat action adapter; evaluator-private fields never enter Agent."""
+
+from __future__ import annotations
+
+import habitat_sim
+import numpy as np
+
+from evolvingnav_paper.agent import ViewEvidence
+from evolvingnav_paper.coverage import (
+    camera_forward, camera_transform, candidate_surface_samples, depth_quality,
+    heading_quaternion,
+    visible_sample_ids,
+)
+from evolvingnav_paper.habitat_utils import set_agent
+from evolvingnav_paper.memory import backproject
+
+
+class HabitatAgentWorld:
+    def __init__(self, backend, viewpoints: dict[int, dict], state_centers: dict[int, list],
+                 start_xyz, start_xyzw, *, speed_mps: float = 1.0,
+                 calibrator=None, category_recall: float = 0.8,
+                 known_states: set[int] | None = None,
+                 motion_schedule: list[dict] | None = None,
+                 surface_points: dict[int, list] | None = None) -> None:
+        self.backend = backend
+        self.viewpoints = viewpoints
+        self.state_centers = state_centers
+        self.position = np.asarray(start_xyz, dtype=float)
+        self.rotation = list(start_xyzw)
+        self.speed_mps = speed_mps
+        self.calibrator = calibrator
+        self.category_recall = category_recall
+        self.frame = 0
+        self.private_inspections: list[dict] = []
+        self.last_detection = None
+        surface_points = surface_points or {}
+        self.samples = {state: candidate_surface_samples(
+            center, place_points=surface_points.get(state))
+                        for state, center in state_centers.items()}
+        self.frontiers = set(viewpoints) - (known_states or set())
+        self.motion_schedule = sorted(motion_schedule or [], key=lambda row: row["time_s"])
+        self.world_time_s = 0.0
+        self._next_motion = 0
+
+    def advance_time(self, seconds: float) -> None:
+        if seconds < 0:
+            raise ValueError("world time cannot move backwards")
+        self.world_time_s += seconds
+        while (self._next_motion < len(self.motion_schedule)
+               and self.motion_schedule[self._next_motion]["time_s"] <= self.world_time_s):
+            self.backend.move_target(self.motion_schedule[self._next_motion])
+            self._next_motion += 1
+
+    def distance(self, goal) -> float:
+        return self.backend.distance(self.position, goal)
+
+    def sample_count(self, state: int) -> int:
+        return len(self.samples[state])
+
+    def expected_new_detection(self, state: int, uncovered: float) -> float:
+        center = np.asarray(self.state_centers[state], dtype=float)
+        viewpoint = self.viewpoints[state]
+        distance = float(np.linalg.norm(center - np.asarray(viewpoint["position_xyz"])))
+        direction = center - np.asarray(viewpoint["position_xyz"])
+        angle = max(0.0, float(np.dot(
+            direction / max(distance, 1e-9),
+            camera_forward(viewpoint["rotation_xyzw"]),
+        )))
+        if self.calibrator is None:
+            return self.category_recall * uncovered
+        return self.calibrator.predict({
+            "coverage": uncovered,
+            "range_m": distance,
+            "angle_cos": angle,
+            "projected_pixels": int(25 * uncovered),
+            "depth_quality": 1.0,
+            "category_recall": self.category_recall,
+        })
+
+    def move_chunk(self, goal, max_distance: float) -> tuple[float, float]:
+        path = habitat_sim.ShortestPath()
+        path.requested_start = np.asarray(self.position, dtype=np.float32)
+        path.requested_end = np.asarray(goal, dtype=np.float32)
+        if not self.backend.real.pathfinder.find_path(path):
+            return 0.0, 0.0
+        remaining = min(float(max_distance), float(path.geodesic_distance))
+        points = [np.asarray(point, dtype=float) for point in path.points]
+        new_position = points[0]
+        for point in points[1:]:
+            length = float(np.linalg.norm(point - new_position))
+            if length >= remaining:
+                new_position = new_position + (point - new_position) * (remaining / length)
+                break
+            remaining -= length
+            new_position = point
+        displacement = min(float(max_distance), float(path.geodesic_distance))
+        heading = new_position - self.position
+        if np.linalg.norm(heading[[0, 2]]) > 1e-6:
+            self.rotation = heading_quaternion(heading)
+        self.position = new_position
+        set_agent(self.backend.real.get_agent(0), self.position.tolist(), self.rotation)
+        self.advance_time(displacement / self.speed_mps)
+        return displacement, displacement / self.speed_mps
+
+    def inspect(self, state: int) -> tuple[bool, list[ViewEvidence]]:
+        viewpoint = self.viewpoints[state]
+        self.position = np.asarray(viewpoint["position_xyz"], dtype=float)
+        self.rotation = viewpoint["rotation_xyzw"]
+        private = self.backend.inspect(state, self.position.tolist())
+        self.private_inspections.append({"state_id": state, **private})
+        observation = self.backend.last_observation
+        if observation is None:
+            raise RuntimeError("Habitat did not produce an RGB-D frame")
+        self.last_detection = None
+        if self.backend.last_detections:
+            strongest = max(self.backend.last_detections, key=lambda item: item.confidence)
+            depth = observation["depth"]
+            pixels = np.argwhere(strongest.mask & np.isfinite(depth) & (depth > 0))
+            if len(pixels):
+                v, u = np.median(pixels, axis=0)
+                depth_m = float(np.median(depth[pixels[:, 0], pixels[:, 1]]))
+                height, width = depth.shape
+                focal = width / (2 * np.tan(np.deg2rad(79.0) / 2))
+                intrinsics = np.array([[focal, 0, width / 2],
+                                       [0, focal, height / 2], [0, 0, 1]], dtype=float)
+                point = backproject(u, v, depth_m, intrinsics,
+                                    camera_transform(self.position, self.rotation))
+                self.last_detection = {
+                    "world_point": point,
+                    "confidence": strongest.confidence,
+                    "evidence_id": f"frame-{self.frame + 1}:positive",
+                }
+        return bool(private["detected"]), self._evidence_from_depth(observation["depth"])
+
+    def observe_chunk(self) -> list[ViewEvidence]:
+        if self.backend.detector is None:
+            return []
+        observation = self.backend.real.get_sensor_observations()
+        depth = np.asarray(observation["depth"])
+        covered_any = any(visible_sample_ids(
+            samples, self.position, self.rotation, depth, 79.0
+        ) for samples in self.samples.values())
+        if not covered_any:
+            return []
+        detected = self.backend.detector(
+            np.asarray(observation["rgb"]), depth, self.backend.target_category
+        )
+        return [] if detected else self._evidence_from_depth(depth)
+
+    def _evidence_from_depth(self, depth: np.ndarray) -> list[ViewEvidence]:
+        self.frame += 1
+        evidence = []
+        for candidate, samples in self.samples.items():
+            covered = visible_sample_ids(
+                samples, self.position, self.rotation, depth, 79.0
+            )
+            if covered:
+                fraction = len(covered) / len(samples)
+                if self.calibrator is None:
+                    detection_probability = self.category_recall * fraction
+                else:
+                    direction = np.asarray(self.state_centers[candidate]) - self.position
+                    distance = float(np.linalg.norm(direction))
+                    features = {
+                        "coverage": fraction,
+                        "range_m": distance,
+                        "angle_cos": max(0.0, float(np.dot(
+                            direction / max(distance, 1e-9), camera_forward(self.rotation)))),
+                        "projected_pixels": len(covered),
+                        "depth_quality": depth_quality(depth),
+                        "category_recall": self.category_recall,
+                    }
+                    detection_probability = self.calibrator.predict(features)
+                evidence.append(ViewEvidence(
+                    f"frame-{self.frame}:state-{candidate}", candidate, covered,
+                    detection_probability, fraction, tuple(self.position.tolist()),
+                ))
+        return evidence
+
+    def explore(self, budget_m: float) -> tuple[dict[int, tuple[object, float]], float, float]:
+        reachable = [
+            (self.distance(self.viewpoints[state]["position_xyz"]), state)
+            for state in self.frontiers
+        ]
+        reachable = [(distance, state) for distance, state in reachable
+                     if np.isfinite(distance) and distance <= budget_m]
+        if not reachable:
+            return {}, 0.0, 0.0
+        distance, state = min(reachable)
+        self.frontiers.remove(state)
+        goal = self.viewpoints[state]["position_xyz"]
+        displacement, duration = self.move_chunk(goal, distance)
+        self.rotation = self.viewpoints[state]["rotation_xyzw"]
+        set_agent(self.backend.real.get_agent(0), self.position.tolist(), self.rotation)
+        observations = self.backend.real.get_sensor_observations()
+        detected = (
+            bool(self.backend.detector(
+                np.asarray(observations["rgb"]), np.asarray(observations["depth"]),
+                self.backend.target_category,
+            )) if self.backend.detector is not None else False
+        )
+        return {state: (goal, 1.0 if detected else 0.5)}, duration, displacement

code/requirements.txt

@@ -0,0 +1,8 @@
+numpy==1.26.4
+torch==2.7.1
+torchvision==0.22.1
+scikit-learn==1.9.0
+transformers==4.57.1
+Pillow==10.4.0
+PyYAML==6.0.3
+pytest==8.4.2

code/scripts/collect_calibration.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Collect held-out RGB-D detector observations for logistic recall calibration."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import numpy as np
+
+from evolvingnav_paper.backend import HabitatInspectionBackend
+from evolvingnav_paper.coverage import (
+    camera_forward, candidate_surface_samples, depth_quality, visible_sample_ids,
+)
+from evolvingnav_paper.perception import GroundedSAMInspector
+from evolvingnav_paper.run import rows
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--dataset", type=Path, required=True)
+    parser.add_argument("--tasks", type=Path, required=True)
+    parser.add_argument("--hssd-root", type=Path, required=True)
+    parser.add_argument("--navmesh-root", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--limit", type=int, default=16)
+    parser.add_argument("--dino-model", default="IDEA-Research/grounding-dino-tiny")
+    parser.add_argument("--sam-model", default="facebook/sam2.1-hiera-tiny")
+    parser.add_argument("--perception-config", type=Path,
+                        default=Path(__file__).resolve().parents[1] / "configs/perception.yaml")
+    args = parser.parse_args()
+    if args.output.exists():
+        raise FileExistsError(args.output)
+    catalog = json.loads((args.tasks / "catalogs/candidate_states_navigation.json").read_text())
+    viewpoints = {int(row["state_id"]): row["navigation_viewpoint"]
+                  for row in catalog["states"] if row.get("navigation_eligible")}
+    centers = {int(row["state_id"]): np.asarray(row["state_center"], dtype=float)
+               for row in catalog["states"]}
+    surface_points = {
+        int(row["state_id"]): [slot["point"] for slot in row.get("sampled_place_points", [])]
+        for row in rows(args.tasks / "catalogs/receptacles.jsonl")
+    }
+    objects = {row["instance_uuid"]: row
+               for row in rows(args.tasks / "catalogs/object_instances.jsonl")}
+    selected = []
+    for record in rows(args.dataset / "records/val_queries.jsonl"):
+        state = int(record["supervision"]["current_state_id"])
+        if state in viewpoints and record["input"]["target"]["instance_uuid"] in objects:
+            selected.append(record)
+        if len(selected) >= args.limit:
+            break
+    if len(selected) < args.limit:
+        raise ValueError(f"only {len(selected)} validation records have a public viewpoint")
+    inspector = GroundedSAMInspector(
+        args.perception_config, dino_model=args.dino_model, sam_model=args.sam_model
+    )
+    backend = HabitatInspectionBackend(
+        args.hssd_root, selected[0]["scene_id"],
+        args.navmesh_root / f"{selected[0]['scene_id']}.navmesh",
+        viewpoints, detector=inspector,
+    )
+    observations = []
+    try:
+        for record in selected:
+            target = record["input"]["target"]
+            state = int(record["supervision"]["current_state_id"])
+            center = centers[state]
+            nearest = sorted(viewpoints, key=lambda candidate: float(np.linalg.norm(
+                np.asarray(viewpoints[candidate]["position_xyz"]) - center
+            )))
+            selected_views = list(dict.fromkeys(
+                [state, *nearest[:3], nearest[len(nearest) // 2], nearest[-1]]
+            ))
+            truth = {
+                "target_position_xyz": record["supervision"]["current_position"],
+                "current_state_id": state,
+                "valid_goal_viewpoints": [viewpoints[state]],
+            }
+            backend.prepare(truth, objects[target["instance_uuid"]], selected_views)
+            samples = candidate_surface_samples(center, place_points=surface_points.get(state))
+            for view_state in selected_views:
+                viewpoint = viewpoints[view_state]
+                backend.inspect(view_state, viewpoint["position_xyz"])
+                depth = backend.last_observation["depth"]
+                covered = visible_sample_ids(
+                    samples, viewpoint["position_xyz"], viewpoint["rotation_xyzw"],
+                    depth, 79.0,
+                )
+                semantic = backend.last_semantic == int(objects[target["instance_uuid"]]["semantic_instance_id"])
+                target_pixels = int(np.count_nonzero(semantic))
+                overlaps = [int(np.count_nonzero(detection.mask & semantic))
+                            for detection in backend.last_detections]
+                position = np.asarray(viewpoint["position_xyz"], dtype=float)
+                direction = center - position
+                distance = float(np.linalg.norm(direction))
+                observations.append({
+                    "coverage": len(covered) / len(samples),
+                    "range_m": distance,
+                    "angle_cos": max(0.0, float(np.dot(
+                        direction / max(distance, 1e-9),
+                        camera_forward(viewpoint["rotation_xyzw"])))),
+                    "projected_pixels": len(covered),
+                    "depth_quality": depth_quality(depth),
+                    "category_recall": 0.8,
+                    "detected": bool(target_pixels >= 20 and max(overlaps, default=0) / target_pixels >= 0.1),
+                })
+            backend.clear()
+    finally:
+        backend.close()
+        inspector.close()
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    with args.output.open("w", encoding="utf-8") as handle:
+        for row in observations:
+            handle.write(json.dumps(row) + "\n")
+    print(json.dumps({
+        "observations": len(observations),
+        "detected": sum(row["detected"] for row in observations),
+        "output": str(args.output),
+    }, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code/scripts/fit_calibration.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Fit detection recall from held-out RGB-D validation observations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from evolvingnav_paper.calibration import DetectionCalibrator
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--validation-jsonl", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    if args.output.exists():
+        raise FileExistsError(args.output)
+    with args.validation_jsonl.open(encoding="utf-8") as handle:
+        rows = [json.loads(line) for line in handle if line.strip()]
+    DetectionCalibrator.fit(rows).save(args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code/scripts/pack_p4d_hssd_records.py

@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+"""Pack P4D JSONL query records into leakage-safe NumPy training tensors."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+
+MAX_HISTORY = 64
+MAX_CONTEXT_HISTORY = 16
+
+
+def arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, required=True)
+    parser.add_argument("--max-history", type=int, default=MAX_HISTORY)
+    return parser.parse_args()
+
+
+def load_jsonl(path: Path) -> list[dict[str, Any]]:
+    with path.open(encoding="utf-8") as handle:
+        return [json.loads(line) for line in handle if line.strip()]
+
+
+def pack_split(
+    records: list[dict[str, Any]],
+    *,
+    max_history: int,
+    category_to_id: dict[str, int],
+    state_count: int,
+    candidate_features: dict[str, np.ndarray],
+) -> dict[str, np.ndarray]:
+    count = len(records)
+    event_type = np.zeros((count, max_history), dtype=np.int8)
+    event_time_days = np.zeros((count, max_history), dtype=np.float32)
+    delta_time_log1p = np.zeros((count, max_history), dtype=np.float32)
+    observed_state_id = np.full((count, max_history), -1, dtype=np.int16)
+    candidate_state_id = np.full((count, max_history), -1, dtype=np.int16)
+    # detector_conf, identity_conf, visible_fraction, frustum, unoccluded, neg_strength
+    evidence_features = np.zeros((count, max_history, 6), dtype=np.float32)
+    history_mask = np.zeros((count, max_history), dtype=np.bool_)
+    candidate_state_ids = np.full((count, state_count), -1, dtype=np.int16)
+    candidate_mask = np.zeros((count, state_count), dtype=np.bool_)
+    target_category_id = np.zeros(count, dtype=np.int16)
+    context_time_days = np.zeros((count, MAX_CONTEXT_HISTORY), dtype=np.float32)
+    context_category_counts = np.zeros(
+        (count, MAX_CONTEXT_HISTORY, len(category_to_id)), dtype=np.float32
+    )
+    context_observation_features = np.zeros(
+        (count, MAX_CONTEXT_HISTORY, 4), dtype=np.float32
+    )
+    context_mask = np.zeros((count, MAX_CONTEXT_HISTORY), dtype=np.bool_)
+    query_time_days = np.zeros(count, dtype=np.float32)
+    query_time_of_day_sin_cos = np.zeros((count, 2), dtype=np.float32)
+    query_weekday_id = np.zeros(count, dtype=np.int8)
+    elapsed_since_last_positive_days = np.zeros(count, dtype=np.float32)
+    meta_world_variant_id = np.zeros(count, dtype=np.int8)
+    meta_grounding_quality_id = np.zeros(count, dtype=np.int8)
+    y_current_state = np.zeros(count, dtype=np.int16)
+    y_moved = np.zeros(count, dtype=np.bool_)
+    y_transition_occurred = np.zeros(count, dtype=np.bool_)
+    y_returned_to_last = np.zeros(count, dtype=np.bool_)
+    record_ids = []
+    instance_ids = []
+    world_ids = {"routine": 0, "random": 1, "static": 2}
+    grounding_ids = {
+        "exact": 0,
+        "role_equivalent": 1,
+        "fallback": 2,
+        "counterfactual": 3,
+        "no_transition": 4,
+    }
+
+    for row_index, record in enumerate(records):
+        model_input = record["input"]
+        history = model_input["target_history"][-max_history:]
+        offset = max_history - len(history)
+        for history_index, event in enumerate(history, start=offset):
+            history_mask[row_index, history_index] = True
+            event_time_days[row_index, history_index] = event["timestamp_s"] / 86400.0
+            delta_time_log1p[row_index, history_index] = math.log1p(
+                max(0.0, event["delta_t_from_previous_s"])
+            )
+            if event["event_type"] == "positive_observation":
+                event_type[row_index, history_index] = 1
+                observed_state_id[row_index, history_index] = event["observed_state_id"]
+                evidence_features[row_index, history_index, :3] = (
+                    event["detector_confidence"],
+                    event["instance_match_confidence"],
+                    event["visible_fraction_estimate"],
+                )
+            elif event["event_type"] == "candidate_inspection":
+                event_type[row_index, history_index] = 2
+                candidate_state_id[row_index, history_index] = event["candidate_state_id"]
+                evidence_features[row_index, history_index, 3:] = (
+                    event["surface_in_frustum_fraction"],
+                    event["surface_unoccluded_fraction"],
+                    event["negative_evidence_strength"],
+                )
+            else:
+                raise ValueError(f"unknown event type: {event['event_type']}")
+        candidates = model_input["candidate_state_ids"]
+        if len(candidates) > state_count:
+            raise ValueError(f"candidate overflow: {record['record_id']}")
+        candidate_state_ids[row_index, : len(candidates)] = candidates
+        candidate_mask[row_index, : len(candidates)] = True
+        target = model_input["target"]
+        target_category_id[row_index] = category_to_id[target["category"]]
+        query_time_s = model_input["query"]["query_time_s"]
+        query_time_days[row_index] = query_time_s / 86400.0
+        phase = 2.0 * math.pi * (query_time_s % 86400.0) / 86400.0
+        query_time_of_day_sin_cos[row_index] = (math.sin(phase), math.cos(phase))
+        query_weekday_id[row_index] = int(query_time_s // 86400) % 7
+        context_history = model_input.get(
+            "observable_context_history", []
+        )[-MAX_CONTEXT_HISTORY:]
+        context_offset = MAX_CONTEXT_HISTORY - len(context_history)
+        for context_index, context in enumerate(
+            context_history, start=context_offset
+        ):
+            context_mask[row_index, context_index] = True
+            context_time_days[row_index, context_index] = (
+                context["timestamp_s"] / 86400.0
+            )
+            for category, value in context["observed_category_counts"].items():
+                context_category_counts[
+                    row_index, context_index, category_to_id[category]
+                ] = float(value)
+            context_observation_features[row_index, context_index] = (
+                float(context["detected_object_count"]),
+                float(context["observed_change_count"]),
+                float(len(context["inspected_candidate_state_ids"])),
+                float(len(context["observed_region_ids"])),
+            )
+        elapsed_since_last_positive_days[row_index] = (
+            model_input["history_summary"]["elapsed_since_last_positive_s"] / 86400.0
+        )
+        meta_world_variant_id[row_index] = world_ids[record["world_variant"]]
+        grounding = record["supervision"].get(
+            "last_transition_grounding_quality", "no_transition"
+        )
+        meta_grounding_quality_id[row_index] = grounding_ids.get(
+            grounding, grounding_ids["no_transition"]
+        )
+        y_current_state[row_index] = record["supervision"]["current_state_id"]
+        y_moved[row_index] = record["supervision"]["moved_since_last_positive"]
+        y_transition_occurred[row_index] = record["supervision"].get(
+            "transition_occurred_since_last_positive", y_moved[row_index]
+        )
+        y_returned_to_last[row_index] = record["supervision"].get(
+            "returned_to_last_state", False
+        )
+        record_ids.append(record["record_id"])
+        instance_ids.append(target["instance_uuid"])
+
+    return {
+        "event_type": event_type,
+        "event_time_days": event_time_days,
+        "delta_time_log1p": delta_time_log1p,
+        "observed_state_id": observed_state_id,
+        "candidate_state_id": candidate_state_id,
+        "evidence_features": evidence_features,
+        "history_mask": history_mask,
+        "candidate_state_ids": candidate_state_ids,
+        "candidate_mask": candidate_mask,
+        "target_category_id": target_category_id,
+        "context_time_days": context_time_days,
+        "context_category_counts": context_category_counts,
+        "context_observation_features": context_observation_features,
+        "context_mask": context_mask,
+        "query_time_days": query_time_days,
+        "query_time_of_day_sin_cos": query_time_of_day_sin_cos,
+        "query_weekday_id": query_weekday_id,
+        "elapsed_since_last_positive_days": elapsed_since_last_positive_days,
+        "meta_world_variant_id": meta_world_variant_id,
+        "meta_grounding_quality_id": meta_grounding_quality_id,
+        "y_current_state": y_current_state,
+        "y_moved": y_moved,
+        "y_transition_occurred": y_transition_occurred,
+        "y_returned_to_last": y_returned_to_last,
+        "record_id": np.asarray(record_ids),
+        "instance_uuid": np.asarray(instance_ids),
+        **candidate_features,
+    }
+
+
+def main() -> int:
+    args = arguments()
+    root = args.root.resolve()
+    objects = load_jsonl(root / "object_pool/objects.jsonl")
+    categories = sorted({row["category_canonical"] for row in objects})
+    category_to_id = {category: index for index, category in enumerate(categories)}
+    state_space = json.loads((root / "scene/candidate_states.json").read_text())
+    state_count = len(state_space["states"])
+    all_records = {
+        split: load_jsonl(root / f"records/{split}_queries.jsonl")
+        for split in ("train", "val", "test")
+    }
+    region_categories = sorted(
+        {row["region_category"] for row in state_space["states"]}
+    )
+    receptacle_categories = sorted(
+        {row["receptacle_category"] for row in state_space["states"]}
+    )
+    region_to_id = {value: index for index, value in enumerate(region_categories)}
+    receptacle_to_id = {
+        value: index for index, value in enumerate(receptacle_categories)
+    }
+    candidate_features = {
+        "candidate_region_category_id": np.asarray(
+            [region_to_id[row["region_category"]] for row in state_space["states"]],
+            dtype=np.int16,
+        ),
+        "candidate_receptacle_category_id": np.asarray(
+            [
+                receptacle_to_id[row["receptacle_category"]]
+                for row in state_space["states"]
+            ],
+            dtype=np.int16,
+        ),
+        "candidate_center_xyz": np.asarray(
+            [row["state_center"] or [0.0, 0.0, 0.0] for row in state_space["states"]],
+            dtype=np.float32,
+        ),
+        "candidate_is_unknown": np.asarray(
+            [row["region_id"] == "unknown" for row in state_space["states"]],
+            dtype=np.bool_,
+        ),
+    }
+    summaries = {}
+    output_dir = root / "records/packed"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    for split in ("train", "val", "test"):
+        records = all_records[split]
+        tensors = pack_split(
+            records,
+            max_history=args.max_history,
+            category_to_id=category_to_id,
+            state_count=state_count,
+            candidate_features=candidate_features,
+        )
+        numeric = [value for value in tensors.values() if value.dtype.kind in "biufc"]
+        if not all(np.isfinite(value).all() for value in numeric):
+            raise ValueError(f"non-finite tensor in {split}")
+        if not np.all((tensors["y_current_state"] >= 0) & (tensors["y_current_state"] < state_count)):
+            raise ValueError(f"invalid state label in {split}")
+        if not np.all(tensors["history_mask"].any(axis=1)):
+            raise ValueError(f"empty history in {split}")
+        positive_mask = tensors["event_type"] == 1
+        if not np.all(positive_mask.any(axis=1)):
+            raise ValueError(f"missing positive event in {split}")
+        path = output_dir / f"{split}.npz"
+        np.savez_compressed(path, **tensors)
+        summaries[split] = {
+            "records": len(records),
+            "path": str(path.relative_to(root)),
+            "bytes": path.stat().st_size,
+            "history_length_min": int(tensors["history_mask"].sum(axis=1).min()),
+            "history_length_max": int(tensors["history_mask"].sum(axis=1).max()),
+            "moved_fraction": float(tensors["y_moved"].mean()),
+            "transition_occurred_fraction": float(
+                tensors["y_transition_occurred"].mean()
+            ),
+            "returned_to_last_fraction": float(
+                tensors["y_returned_to_last"].mean()
+            ),
+        }
+    schema = {
+        "schema_version": "p4d_packed_tensor_v1.2",
+        "max_history": args.max_history,
+        "state_count_including_unknown": state_count,
+        "category_to_id": category_to_id,
+        "region_category_to_id": region_to_id,
+        "receptacle_category_to_id": receptacle_to_id,
+        "metadata_world_variant_to_id": {"routine": 0, "random": 1, "static": 2},
+        "metadata_grounding_quality_to_id": {
+            "exact": 0,
+            "role_equivalent": 1,
+            "fallback": 2,
+            "counterfactual": 3,
+            "no_transition": 4,
+        },
+        "event_type_to_id": {"padding": 0, "positive_observation": 1, "candidate_inspection": 2},
+        "evidence_feature_order": [
+            "detector_confidence",
+            "instance_match_confidence",
+            "visible_fraction_estimate",
+            "surface_in_frustum_fraction",
+            "surface_unoccluded_fraction",
+            "negative_evidence_strength",
+        ],
+        "observable_context_feature_order": [
+            "detected_object_count",
+            "observed_change_count",
+            "inspected_candidate_state_count",
+            "observed_region_count",
+        ],
+        "label_tensors": [
+            "y_current_state",
+            "y_moved",
+            "y_transition_occurred",
+            "y_returned_to_last",
+        ],
+        "metadata_tensors_not_for_model_input": [
+            "meta_world_variant_id",
+            "meta_grounding_quality_id",
+            "record_id",
+            "instance_uuid",
+        ],
+        "access_rule": "input tensors derive from query.input; y_* derives from supervision; meta_* is only for filtering and reporting",
+        "pytorch_dtype_note": "cast int16 state/category ID arrays to torch.long before embedding, one_hot, or cross_entropy",
+        "splits": summaries,
+        "validation": {
+            "finite_numeric_tensors": True,
+            "valid_label_ranges": True,
+            "nonempty_history": True,
+            "positive_anchor_present": True,
+        },
+    }
+    (output_dir / "feature_schema.json").write_text(
+        json.dumps(schema, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    print(json.dumps(schema, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code/scripts/train_p4d_belief.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Train and evaluate P4D-Belief on the frozen 30-day HSSD dataset."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+import torch
+
+from readyagent.p4d_belief.data import audit_training_contract, load_catalog
+from readyagent.p4d_belief.models import ModelConfig
+from readyagent.p4d_belief.training import (
+    TrainConfig,
+    evaluate_classical_baselines,
+    evaluate_model,
+    summarize_neural,
+    train_model,
+)
+
+
+def arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--dataset-root", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--models", nargs="+", choices=("p4d", "direct", "gru"), default=["p4d"])
+    parser.add_argument("--seeds", nargs="+", type=int, default=[0, 1, 2, 3, 4])
+    parser.add_argument("--layers", type=int, default=3)
+    parser.add_argument("--hidden-dim", type=int, default=128)
+    parser.add_argument("--heads", type=int, default=4)
+    parser.add_argument("--dropout", type=float, default=0.1)
+    parser.add_argument(
+        "--use-instance-identity",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Use the observable target instance UUID as a stable identity embedding.",
+    )
+    parser.add_argument("--use-compatibility", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--batch-size", type=int, default=64)
+    parser.add_argument("--eval-batch-size", type=int, default=256)
+    parser.add_argument("--epochs", type=int, default=100)
+    parser.add_argument("--patience", type=int, default=10)
+    parser.add_argument("--learning-rate", type=float, default=3e-4)
+    parser.add_argument("--weight-decay", type=float, default=1e-2)
+    parser.add_argument("--gradient-clip", type=float, default=1.0)
+    parser.add_argument(
+        "--routine-train-fraction",
+        type=float,
+        default=0.5,
+        help="Expected Routine fraction in the Routine/Static weighted sampler.",
+    )
+    parser.add_argument(
+        "--validation-subset",
+        choices=("main", "routine_all", "routine_exact", "static"),
+        default="main",
+        help="Subset whose NLL selects the early-stopping checkpoint.",
+    )
+    parser.add_argument(
+        "--unknown-train-boost",
+        type=float,
+        default=1.0,
+        help="Within-Routine sampling multiplier for true Unknown targets.",
+    )
+    parser.add_argument("--device", default="cuda")
+    parser.add_argument("--eval-split", choices=("val", "test"), default="val")
+    parser.add_argument("--skip-classical", action="store_true")
+    return parser.parse_args()
+
+
+def write_report(
+    output: Path,
+    *,
+    audit: dict,
+    classical: dict,
+    aggregate: dict,
+    model_config: ModelConfig,
+    train_config: TrainConfig,
+) -> None:
+    lines = [
+        "# P4D-Belief 30天 Pilot 训练与测试报告",
+        "",
+        "## 实验设置",
+        "",
+        f"- 模型：Query-Conditioned Continuous-Time Transformer，{model_config.layers}层，hidden={model_config.hidden_dim}，heads={model_config.heads}",
+        f"- 目标身份特征：{'启用稳定instance embedding' if model_config.use_instance_identity else '仅使用object category'}。",
+        f"- 训练：Routine Exact/No-transition + Static；Routine采样占比={train_config.routine_train_fraction:.0%}；AdamW，lr={train_config.learning_rate}，batch={train_config.batch_size}",
+        f"- 早停依据：验证集 `{train_config.validation_subset}` 的状态NLL。",
+        f"- Unknown正样本训练采样倍率：{train_config.unknown_train_boost:g}×。",
+        "- 模型输入不含 world type、grounding quality、GT activity、隐藏变化或监督字段；可选instance embedding只编码查询中已知的目标身份。",
+        "- P4D-Belief仅使用最终状态NLL；Bayesian Update不参与训练。",
+        "",
+        "## 训练前审计",
+        "",
+        f"- 审计通过：{audit['passed']}",
+        f"- Routine发生隐藏事件后回到last state的记录：{audit['routine_return_to_last_records']}",
+        "- `y_moved`表示查询状态与last state是否不同，不表示期间是否曾发生移动。",
+        "",
+        "## Test主结果（5 seeds均值±标准差）",
+        "",
+        "| 方法 | 子集 | Top-1 | Top-3 | NLL | ECE | 平均检查位置 | Persistence AUROC |",
+        "| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |",
+    ]
+    for method, subsets in classical.items():
+        for subset in ("routine_exact", "routine_all", "random", "static"):
+            row = subsets[subset]
+            lines.append(
+                f"| {method} | {subset} | {row['top1']:.3f} | {row['top3']:.3f} | {row['nll']:.3f} | {row['ece']:.3f} | {row['mean_receptacles_checked']:.2f} | {row['persistence_auroc']:.3f} |"
+            )
+    for method, subsets in aggregate.items():
+        for subset in ("routine_exact", "routine_all", "random", "static"):
+            row = subsets[subset]
+            def cell(key: str) -> str:
+                return f"{row[key]['mean']:.3f}±{row[key]['std']:.3f}"
+            lines.append(
+                f"| {method} | {subset} | {cell('top1')} | {cell('top3')} | {cell('nll')} | {cell('ece')} | {cell('mean_receptacles_checked')} | {cell('persistence_auroc')} |"
+            )
+    lines.extend(
+        [
+            "",
+            "## 新版专项结果",
+            "",
+            "| 方法 | 子集 | 样本 | Top-1 | Top-3 | NLL | 平均检查位置 |",
+            "| --- | --- | ---: | ---: | ---: | ---: | ---: |",
+        ]
+    )
+    for method, subsets in classical.items():
+        for subset in ("routine_unknown", "routine_returned"):
+            if subset not in subsets:
+                continue
+            row = subsets[subset]
+            lines.append(
+                f"| {method} | {subset} | {row['records']} | {row['top1']:.3f} | {row['top3']:.3f} | {row['nll']:.3f} | {row['mean_receptacles_checked']:.2f} |"
+            )
+    for method, subsets in aggregate.items():
+        for subset in ("routine_unknown", "routine_returned"):
+            if subset not in subsets:
+                continue
+            row = subsets[subset]
+            def diagnostic_cell(key: str) -> str:
+                return f"{row[key]['mean']:.3f}±{row[key]['std']:.3f}"
+            lines.append(
+                f"| {method} | {subset} | {row['records']} | {diagnostic_cell('top1')} | {diagnostic_cell('top3')} | {diagnostic_cell('nll')} | {diagnostic_cell('mean_receptacles_checked')} |"
+            )
+    lines.extend(
+        [
+            "",
+            "## 解释边界",
+            "",
+            "- 当前负证据的confidence/coverage来自受控模拟，不代表真实视觉检测器。",
+            "- 数据仅有一个HSSD场景；共享语义位置编码避免了state-ID embedding，但尚不能证明跨场景泛化。",
+            "- Unknown正标签表示对象物理离开建模场景，不表示遮挡或检测失败。",
+            "- `returned_to_last`用于区分期间发生移动与查询时最终Persistence；它不直接作为状态预测模型输入。",
+            "- 生成器GT Activity不进入模型；上下文只来自机器人可观察的巡检聚合。",
+        ]
+    )
+    (output / "REPORT_ZH.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    args = arguments()
+    dataset_root = args.dataset_root.resolve()
+    output = args.output.resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    device = torch.device(args.device if args.device != "cuda" or torch.cuda.is_available() else "cpu")
+    catalog = load_catalog(dataset_root)
+    audit = audit_training_contract(dataset_root)
+    if not audit["passed"]:
+        raise RuntimeError("training contract audit failed")
+    (output / "training_contract_audit.json").write_text(
+        json.dumps(audit, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    model_config = ModelConfig(
+        hidden_dim=args.hidden_dim,
+        layers=args.layers,
+        heads=args.heads,
+        dropout=args.dropout,
+        use_instance_identity=args.use_instance_identity,
+        use_compatibility=args.use_compatibility,
+    )
+    train_config = TrainConfig(
+        batch_size=args.batch_size,
+        eval_batch_size=args.eval_batch_size,
+        learning_rate=args.learning_rate,
+        weight_decay=args.weight_decay,
+        max_epochs=args.epochs,
+        patience=args.patience,
+        gradient_clip=args.gradient_clip,
+        routine_train_fraction=args.routine_train_fraction,
+        validation_subset=args.validation_subset,
+        unknown_train_boost=args.unknown_train_boost,
+    )
+    run_config = {
+        "dataset_root": str(dataset_root),
+        "output": str(output),
+        "device": str(device),
+        "gpu": torch.cuda.get_device_name(device) if device.type == "cuda" else None,
+        "models": args.models,
+        "seeds": args.seeds,
+        "model_config": asdict(model_config),
+        "train_config": asdict(train_config),
+    }
+    (output / "config.json").write_text(
+        json.dumps(run_config, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    classical = {} if args.skip_classical else evaluate_classical_baselines(dataset_root, catalog)
+    (output / "classical_baselines.json").write_text(
+        json.dumps(classical, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    seed_results: dict[str, list[dict]] = {name: [] for name in args.models}
+    training_results: list[dict] = []
+    for name in args.models:
+        for seed in args.seeds:
+            run_dir = output / "checkpoints" / name / f"seed_{seed}"
+            print(f"TRAIN model={name} seed={seed} device={device}", flush=True)
+            model, training = train_model(
+                name=name,
+                seed=seed,
+                dataset_root=dataset_root,
+                catalog=catalog,
+                model_config=model_config,
+                train_config=train_config,
+                device=device,
+                output_dir=run_dir,
+            )
+            metrics = evaluate_model(
+                model,
+                dataset_root=dataset_root,
+                catalog=catalog,
+                split=args.eval_split,
+                device=device,
+                batch_size=args.eval_batch_size,
+                include_update=name == "p4d",
+            )
+            (run_dir / f"{args.eval_split}_metrics.json").write_text(
+                json.dumps(metrics, ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+            seed_results[name].append(metrics)
+            training_results.append(training)
+            print(
+                f"DONE model={name} seed={seed} epoch={training['best_epoch']} "
+                f"routine_exact_top1={metrics['routine_exact']['top1']:.4f}",
+                flush=True,
+            )
+            del model
+            if device.type == "cuda":
+                torch.cuda.empty_cache()
+    aggregate = summarize_neural(seed_results)
+    (output / "neural_aggregate.json").write_text(
+        json.dumps(aggregate, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    (output / "training_summary.json").write_text(
+        json.dumps(training_results, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    write_report(
+        output,
+        audit=audit,
+        classical=classical,
+        aggregate=aggregate,
+        model_config=model_config,
+        train_config=train_config,
+    )
+    print(json.dumps({"status": "OK", "output": str(output)}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code/scripts/train_transition.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Jointly fine-tune P4D state belief and chronological transition head."""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import math
+import random
+from pathlib import Path
+
+import torch
+from torch.utils.data import DataLoader, Dataset
+
+from evolvingnav_paper.transition_model import (
+    TransitionHead, event_horizon_pairs, transition_nll,
+)
+from readyagent.p4d_belief.data import PackedQueries, load_catalog
+from readyagent.p4d_belief.models import ModelConfig, state_nll
+from readyagent.p4d_belief.training import build_model
+
+
+class ChronologicalDataset(Dataset):
+    def __init__(self, root: Path, split: str, horizons_s: tuple[float, ...],
+                 max_pairs: int | None = None) -> None:
+        self.records = PackedQueries(root / f"records/packed/{split}.npz")
+        arrays = self.records.arrays
+        events = []
+        for world_id, name in ((0, "routine"), (1, "random")):
+            events_path = root / f"worlds/{name}/private_gt/hidden_transitions.jsonl"
+            with events_path.open(encoding="utf-8") as handle:
+                for line in handle:
+                    if line.strip():
+                        event = json.loads(line)
+                        event["world_id"] = world_id
+                        events.append(event)
+        self.pairs = event_horizon_pairs(
+            instance_ids=arrays["instance_uuid"],
+            world_ids=arrays["meta_world_variant_id"],
+            query_times_s=arrays["query_time_days"].astype(float) * 86400.0,
+            query_states=arrays["y_current_state"], events=events,
+            horizons_s=horizons_s,
+        )
+        if max_pairs is not None:
+            self.pairs = self.pairs[:max_pairs]
+        if not self.pairs:
+            raise ValueError(f"no chronological pairs in {split}")
+
+    def __len__(self) -> int:
+        return len(self.pairs)
+
+    def __getitem__(self, item: int) -> dict[str, torch.Tensor]:
+        source, anchor_time, horizon, source_state, destination_state = self.pairs[item]
+        batch = self.records[source]
+        candidates = self.records.arrays["candidate_state_ids"][source].tolist()
+        source_time = float(self.records.arrays["query_time_days"][source]) * 86400.0
+        anchor_days = anchor_time / 86400.0
+        phase = 2 * math.pi * anchor_days
+        batch["query_time_days"] = torch.tensor(anchor_days, dtype=torch.float32)
+        batch["query_time_of_day_sin_cos"] = torch.tensor(
+            [math.sin(phase), math.cos(phase)], dtype=torch.float32
+        )
+        batch["query_weekday_id"] = torch.tensor(
+            (int(batch["query_weekday_id"]) + math.floor(anchor_days)
+             - math.floor(source_time / 86400.0)) % 7, dtype=torch.long
+        )
+        batch["elapsed_since_last_positive_days"] = (
+            batch["elapsed_since_last_positive_days"]
+            + torch.tensor((anchor_time - source_time) / 86400.0, dtype=torch.float32)
+        )
+        batch["target_candidate_index"] = torch.tensor(candidates.index(source_state))
+        batch["y_current_state"] = torch.tensor(source_state)
+        batch["transition_source_index"] = torch.tensor(candidates.index(source_state))
+        batch["transition_destination_index"] = torch.tensor(candidates.index(destination_state))
+        batch["transition_horizon_s"] = torch.tensor(horizon, dtype=torch.float32)
+        return batch
+
+
+def epoch(model, head, loader, optimizer, device, gradient_clip: float) -> float:
+    training = optimizer is not None
+    model.train(training)
+    head.train(training)
+    total, count = 0.0, 0
+    for raw in loader:
+        batch = {key: value.to(device) for key, value in raw.items()}
+        with torch.set_grad_enabled(training):
+            output = model(batch)
+            kernel = head(output["context"], output["candidates"],
+                          batch["transition_horizon_s"], batch["candidate_mask"])
+            loss = state_nll(output["probabilities"], batch["target_candidate_index"])
+            loss = loss + transition_nll(
+                kernel, batch["transition_source_index"],
+                batch["transition_destination_index"],
+            )
+            if training:
+                optimizer.zero_grad(set_to_none=True)
+                loss.backward()
+                torch.nn.utils.clip_grad_norm_(
+                    list(model.parameters()) + list(head.parameters()), gradient_clip
+                )
+                optimizer.step()
+        total += float(loss.detach()) * len(batch["transition_horizon_s"])
+        count += len(batch["transition_horizon_s"])
+    return total / count
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--dataset", type=Path, required=True)
+    parser.add_argument("--belief-checkpoint", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--horizons-s", nargs="+", type=float,
+                        default=[2.0, 10.0, 30.0, 60.0, 120.0, 300.0])
+    parser.add_argument("--max-pairs", type=int)
+    parser.add_argument("--epochs", type=int, default=100)
+    parser.add_argument("--patience", type=int, default=10)
+    parser.add_argument("--batch-size", type=int, default=64)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--device", default="cuda")
+    args = parser.parse_args()
+    random.seed(args.seed)
+    torch.manual_seed(args.seed)
+    torch.cuda.manual_seed_all(args.seed)
+    if args.output.exists():
+        raise FileExistsError(args.output)
+    device = torch.device(args.device if args.device != "cuda" or torch.cuda.is_available() else "cpu")
+    catalog = load_catalog(args.dataset)
+    original = torch.load(args.belief_checkpoint, map_location="cpu", weights_only=True)
+    model = build_model("p4d", catalog, ModelConfig(**original["model_config"]))
+    model.load_state_dict(original["model"])
+    model.to(device)
+    head = TransitionHead(int(original["model_config"]["hidden_dim"])).to(device)
+    train = ChronologicalDataset(args.dataset, "train", tuple(args.horizons_s), args.max_pairs)
+    val = ChronologicalDataset(args.dataset, "val", tuple(args.horizons_s), args.max_pairs)
+    train_loader = DataLoader(train, batch_size=args.batch_size, shuffle=True)
+    val_loader = DataLoader(val, batch_size=args.batch_size)
+    optimizer = torch.optim.AdamW(
+        list(model.parameters()) + list(head.parameters()), lr=3e-4, weight_decay=1e-2
+    )
+    best, stale, state = float("inf"), 0, None
+    for number in range(1, args.epochs + 1):
+        train_loss = epoch(model, head, train_loader, optimizer, device, 1.0)
+        val_loss = epoch(model, head, val_loader, None, device, 1.0)
+        print(f"epoch={number} train={train_loss:.5f} val={val_loss:.5f}", flush=True)
+        if val_loss < best - 1e-5:
+            best, stale = val_loss, 0
+            state = (copy.deepcopy(model.state_dict()), copy.deepcopy(head.state_dict()))
+        else:
+            stale += 1
+        if stale >= args.patience:
+            break
+    if state is None:
+        raise RuntimeError("transition training produced no checkpoint")
+    args.output.mkdir(parents=True)
+    torch.save({
+        "model": state[0], "transition_head": state[1],
+        "model_config": original["model_config"], "best_validation_loss": best,
+        "horizons_s": args.horizons_s,
+    }, args.output / "best.pt")
+    (args.output / "summary.json").write_text(json.dumps({
+        "train_pairs": len(train), "val_pairs": len(val),
+        "best_validation_loss": best,
+    }, indent=2) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code/src/readyagent/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

code/src/readyagent/p4d_belief/__init__.py

@@ -0,0 +1,15 @@
+"""P4D-Belief training and evaluation components."""
+
+from readyagent.p4d_belief.models import (
+    DirectPointer,
+    GRUDirectPointer,
+    P4DBelief,
+    bayesian_update,
+)
+
+__all__ = [
+    "DirectPointer",
+    "GRUDirectPointer",
+    "P4DBelief",
+    "bayesian_update",
+]

code/src/readyagent/p4d_belief/baselines.py

@@ -0,0 +1,74 @@
+"""Leakage-safe classical baselines for current-state prediction."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+def _normalize(counts: np.ndarray) -> np.ndarray:
+    return counts / counts.sum(axis=-1, keepdims=True).clip(min=1e-12)
+
+
+@dataclass
+class ClassicalBaselines:
+    state_count: int
+    category_count: int
+    smoothing: float = 0.25
+
+    def fit(
+        self,
+        *,
+        target_category: np.ndarray,
+        target_state: np.ndarray,
+        last_state: np.ndarray,
+        weekday: np.ndarray,
+        time_sin_cos: np.ndarray,
+    ) -> None:
+        self.object_counts = np.full(
+            (self.category_count, self.state_count), self.smoothing, dtype=np.float64
+        )
+        self.markov_counts = np.full(
+            (self.category_count, self.state_count, self.state_count),
+            self.smoothing,
+            dtype=np.float64,
+        )
+        self.time_counts = np.full(
+            (self.category_count, 7, 4, self.state_count), self.smoothing, dtype=np.float64
+        )
+        hour = _time_quarter(time_sin_cos)
+        np.add.at(self.object_counts, (target_category, target_state), 1.0)
+        np.add.at(self.markov_counts, (target_category, last_state, target_state), 1.0)
+        np.add.at(self.time_counts, (target_category, weekday, hour, target_state), 1.0)
+        self.object_probabilities = _normalize(self.object_counts)
+        self.markov_probabilities = _normalize(self.markov_counts)
+        self.time_probabilities = _normalize(self.time_counts)
+
+    def predict(
+        self,
+        method: str,
+        *,
+        target_category: np.ndarray,
+        last_state: np.ndarray,
+        weekday: np.ndarray,
+        time_sin_cos: np.ndarray,
+    ) -> np.ndarray:
+        if method == "last_seen":
+            probabilities = np.zeros((len(last_state), self.state_count), dtype=np.float64)
+            probabilities[np.arange(len(last_state)), last_state] = 1.0
+            return probabilities
+        if method == "object_frequency":
+            return self.object_probabilities[target_category]
+        if method == "markov":
+            return self.markov_probabilities[target_category, last_state]
+        if method == "time_frequency":
+            quarter = _time_quarter(time_sin_cos)
+            return self.time_probabilities[target_category, weekday, quarter]
+        raise ValueError(method)
+
+
+def _time_quarter(time_sin_cos: np.ndarray) -> np.ndarray:
+    angle = np.arctan2(time_sin_cos[:, 0], time_sin_cos[:, 1])
+    fraction = np.mod(angle, 2 * np.pi) / (2 * np.pi)
+    return np.floor(fraction * 4).astype(np.int64).clip(0, 3)

code/src/readyagent/p4d_belief/data.py

@@ -0,0 +1,294 @@
+"""Leakage-safe loader for packed P4D-HSSD query records."""
+
+from __future__ import annotations
+
+import bisect
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+from torch.utils.data import Dataset
+
+
+WORLD_NAMES = {0: "routine", 1: "random", 2: "static"}
+QUALITY_NAMES = {0: "exact", 1: "fallback", 2: "counterfactual", 3: "no_transition"}
+
+# This is the complete allowlist passed to neural models. In particular, no
+# meta_world_variant_id, meta_grounding_quality_id, activity or supervision field
+# is included.
+MODEL_INPUT_KEYS = (
+    "event_type",
+    "event_time_days",
+    "observed_state_id",
+    "candidate_state_id",
+    "evidence_features",
+    "history_mask",
+    "candidate_state_ids",
+    "candidate_mask",
+    "target_category_id",
+    "query_time_days",
+    "query_time_of_day_sin_cos",
+    "query_weekday_id",
+    "elapsed_since_last_positive_days",
+)
+
+OPTIONAL_MODEL_INPUT_KEYS = (
+    "context_time_days",
+    "context_category_counts",
+    "context_observation_features",
+    "context_mask",
+)
+
+DERIVED_MODEL_INPUT_KEYS = ("target_instance_id",)
+
+
+@dataclass(frozen=True)
+class Catalog:
+    """Static scene catalog used by the shared semantic candidate encoder."""
+
+    region_category: torch.Tensor
+    receptacle_category: torch.Tensor
+    center_xyz: torch.Tensor
+    is_unknown: torch.Tensor
+    region_instance_ids: tuple[str, ...]
+    schema: dict[str, Any]
+
+    @property
+    def state_count(self) -> int:
+        return int(self.region_category.shape[0])
+
+
+class PackedQueries(Dataset[dict[str, torch.Tensor]]):
+    """Selected packed records with metadata kept outside model inputs."""
+
+    def __init__(self, packed_path: Path, indices: np.ndarray | None = None) -> None:
+        data = np.load(packed_path, allow_pickle=False)
+        self.arrays = {key: data[key] for key in data.files}
+        instance_values = sorted(str(value) for value in np.unique(self.arrays["instance_uuid"]))
+        instance_to_id = {value: index for index, value in enumerate(instance_values)}
+        self.target_instance_id = np.asarray(
+            [instance_to_id[str(value)] for value in self.arrays["instance_uuid"]],
+            dtype=np.int64,
+        )
+        total = len(self.arrays["y_current_state"])
+        self.indices = (
+            np.arange(total, dtype=np.int64)
+            if indices is None
+            else np.asarray(indices, dtype=np.int64)
+        )
+        self.last_state = derive_last_state(self.arrays)
+        self.target_candidate_index = map_state_to_candidate_index(
+            self.arrays["candidate_state_ids"], self.arrays["y_current_state"]
+        )
+        self.last_candidate_index = map_state_to_candidate_index(
+            self.arrays["candidate_state_ids"], self.last_state
+        )
+
+    def __len__(self) -> int:
+        return len(self.indices)
+
+    def __getitem__(self, item: int) -> dict[str, torch.Tensor]:
+        index = int(self.indices[item])
+        result: dict[str, torch.Tensor] = {}
+        for key in MODEL_INPUT_KEYS:
+            result[key] = torch.as_tensor(self.arrays[key][index])
+        for key in OPTIONAL_MODEL_INPUT_KEYS:
+            if key in self.arrays:
+                result[key] = torch.as_tensor(self.arrays[key][index])
+        result["target_instance_id"] = torch.tensor(
+            self.target_instance_id[index], dtype=torch.long
+        )
+        result["last_state"] = torch.tensor(self.last_state[index], dtype=torch.long)
+        result["last_candidate_index"] = torch.tensor(
+            self.last_candidate_index[index], dtype=torch.long
+        )
+        result["target_candidate_index"] = torch.tensor(
+            self.target_candidate_index[index], dtype=torch.long
+        )
+        result["y_current_state"] = torch.tensor(
+            self.arrays["y_current_state"][index], dtype=torch.long
+        )
+        result["y_persist"] = torch.tensor(
+            self.last_state[index] == self.arrays["y_current_state"][index],
+            dtype=torch.float32,
+        )
+        result["source_index"] = torch.tensor(index, dtype=torch.long)
+        return result
+
+
+def load_catalog(dataset_root: Path) -> Catalog:
+    packed = dataset_root / "records/packed"
+    schema = json.loads((packed / "feature_schema.json").read_text(encoding="utf-8"))
+    with np.load(packed / "train.npz", allow_pickle=False) as data:
+        region = torch.from_numpy(data["candidate_region_category_id"].astype(np.int64))
+        receptacle = torch.from_numpy(
+            data["candidate_receptacle_category_id"].astype(np.int64)
+        )
+        center = torch.from_numpy(data["candidate_center_xyz"].astype(np.float32))
+        unknown = torch.from_numpy(data["candidate_is_unknown"].astype(np.bool_))
+        instance_values = sorted(str(value) for value in np.unique(data["instance_uuid"]))
+    schema["instance_uuid_to_id"] = {
+        value: index for index, value in enumerate(instance_values)
+    }
+    candidate_json = json.loads(
+        (dataset_root / "scene/candidate_states.json").read_text(encoding="utf-8")
+    )
+    states = sorted(candidate_json["states"], key=lambda row: row["state_id"])
+    if len(states) != len(region):
+        raise ValueError("candidate catalog and packed arrays have different lengths")
+    region_ids = tuple(str(row["region_id"]) for row in states)
+    return Catalog(region, receptacle, center, unknown, region_ids, schema)
+
+
+def derive_last_state(arrays: dict[str, np.ndarray]) -> np.ndarray:
+    positive = (arrays["event_type"] == 1) & arrays["history_mask"]
+    positions = np.where(positive, np.arange(positive.shape[1])[None, :], -1)
+    last_index = positions.max(axis=1)
+    if np.any(last_index < 0):
+        raise ValueError("every query must contain a positive observation anchor")
+    last_state = arrays["observed_state_id"][np.arange(len(last_index)), last_index]
+    if np.any(last_state < 0):
+        raise ValueError("positive observation has an invalid state")
+    return last_state.astype(np.int64)
+
+
+def map_state_to_candidate_index(candidates: np.ndarray, states: np.ndarray) -> np.ndarray:
+    matches = candidates == np.asarray(states)[:, None]
+    if not np.all(matches.any(axis=1)):
+        raise ValueError("target or last state is absent from candidate set")
+    return matches.argmax(axis=1).astype(np.int64)
+
+
+def subset_indices(
+    arrays: dict[str, np.ndarray],
+    *,
+    world: str,
+    quality: str = "all",
+) -> np.ndarray:
+    reverse_world = {value: key for key, value in WORLD_NAMES.items()}
+    if world == "main":
+        # Main training/validation excludes semantically-fallback transitions:
+        # Routine exact/no-transition plus all Static records.
+        keep = (
+            ((arrays["meta_world_variant_id"] == reverse_world["routine"])
+             & np.isin(arrays["meta_grounding_quality_id"], (0, 3)))
+            | (arrays["meta_world_variant_id"] == reverse_world["static"])
+        )
+    else:
+        keep = arrays["meta_world_variant_id"] == reverse_world[world]
+    if quality == "exact":
+        # Exact Routine includes unchanged queries, for which grounding is not
+        # applicable and is explicitly labelled no_transition.
+        keep &= np.isin(arrays["meta_grounding_quality_id"], (0, 3))
+    elif quality == "fallback":
+        keep &= arrays["meta_grounding_quality_id"] == 1
+    elif quality != "all":
+        raise ValueError(f"unknown quality subset: {quality}")
+    return np.flatnonzero(keep)
+
+
+def load_arrays(dataset_root: Path, split: str) -> dict[str, np.ndarray]:
+    path = dataset_root / "records/packed" / f"{split}.npz"
+    with np.load(path, allow_pickle=False) as data:
+        return {key: data[key] for key in data.files}
+
+
+def audit_training_contract(dataset_root: Path) -> dict[str, Any]:
+    """Fail fast on label, chronology, candidate and leakage assumptions."""
+
+    report: dict[str, Any] = {
+        "splits": {},
+        "model_input_keys": list(
+            MODEL_INPUT_KEYS + OPTIONAL_MODEL_INPUT_KEYS + DERIVED_MODEL_INPUT_KEYS
+        ),
+    }
+    forbidden = {
+        "meta_world_variant_id",
+        "meta_grounding_quality_id",
+        "activity_type_id",
+        "activity_history",
+        "y_current_state",
+        "y_moved",
+    }
+    report["forbidden_keys_absent_from_model_input"] = not bool(
+        forbidden.intersection(
+            MODEL_INPUT_KEYS + OPTIONAL_MODEL_INPUT_KEYS + DERIVED_MODEL_INPUT_KEYS
+        )
+    )
+    total_disagreement = 0
+    scheduled_events: dict[str, list[float]] = {}
+    schedule_path = dataset_root / "schedules/routine_events.jsonl"
+    if schedule_path.exists():
+        for line in schedule_path.read_text(encoding="utf-8").splitlines():
+            event = json.loads(line)
+            scheduled_events.setdefault(str(event["instance_uuid"]), []).append(
+                float(event["event_time_s"]) / 86400.0
+            )
+        for timestamps in scheduled_events.values():
+            timestamps.sort()
+    total_return_to_last = 0
+    for split in ("train", "val", "test"):
+        arrays = load_arrays(dataset_root, split)
+        last = derive_last_state(arrays)
+        target_index = map_state_to_candidate_index(
+            arrays["candidate_state_ids"], arrays["y_current_state"]
+        )
+        last_index = map_state_to_candidate_index(arrays["candidate_state_ids"], last)
+        valid_time = arrays["event_time_days"] <= arrays["query_time_days"][:, None] + 1e-6
+        valid_time |= ~arrays["history_mask"]
+        persist = last == arrays["y_current_state"]
+        disagreement = int(np.sum(arrays["y_moved"] != ~persist))
+        total_disagreement += disagreement
+        routine = arrays["meta_world_variant_id"] == 0
+        routine_indices = np.flatnonzero(routine)
+        hidden_event_count = np.zeros(len(routine_indices), dtype=np.int64)
+        for output_index, record_index in enumerate(routine_indices):
+            positive = (
+                (arrays["event_type"][record_index] == 1)
+                & arrays["history_mask"][record_index]
+            )
+            last_time = float(
+                arrays["event_time_days"][record_index, np.flatnonzero(positive)[-1]]
+            )
+            query_time = float(arrays["query_time_days"][record_index])
+            timestamps = scheduled_events.get(str(arrays["instance_uuid"][record_index]), [])
+            hidden_event_count[output_index] = bisect.bisect_right(
+                timestamps, query_time + 1e-6
+            ) - bisect.bisect_right(timestamps, last_time + 1e-6)
+        routine_persist = persist[routine_indices]
+        returns = int(np.sum((hidden_event_count > 0) & routine_persist))
+        total_return_to_last += returns
+        report["splits"][split] = {
+            "records": int(len(last)),
+            "target_present": bool(np.all(target_index >= 0)),
+            "last_present": bool(np.all(last_index >= 0)),
+            "no_future_history": bool(np.all(valid_time)),
+            "persist_fraction": float(np.mean(persist)),
+            "moved_vs_nonpersist_disagreement": disagreement,
+            "routine_no_hidden_event_since_last_positive": int(
+                np.sum(hidden_event_count == 0)
+            ),
+            "routine_event_and_return_to_last": returns,
+            "routine_event_and_changed": int(
+                np.sum((hidden_event_count > 0) & ~routine_persist)
+            ),
+            "unknown_targets": int(
+                np.sum(arrays["y_current_state"] == int(arrays["candidate_is_unknown"].argmax()))
+            ),
+        }
+    report["moved_label_semantics"] = (
+        "y_moved is net current-state difference from last positive, not whether any "
+        "hidden transition occurred"
+    )
+    report["routine_return_to_last_records"] = total_return_to_last
+    report["passed"] = bool(
+        report["forbidden_keys_absent_from_model_input"]
+        and all(
+            row["target_present"] and row["last_present"] and row["no_future_history"]
+            for row in report["splits"].values()
+        )
+    )
+    return report

code/src/readyagent/p4d_belief/metrics.py

@@ -0,0 +1,119 @@
+"""Belief, persistence, calibration and offline-search metrics."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from sklearn.metrics import f1_score, roc_auc_score
+
+
+def expected_calibration_error(
+    probabilities: np.ndarray, targets: np.ndarray, bins: int = 15
+) -> float:
+    confidence = probabilities.max(axis=1)
+    correct = probabilities.argmax(axis=1) == targets
+    boundaries = np.linspace(0.0, 1.0, bins + 1)
+    result = 0.0
+    for low, high in zip(boundaries[:-1], boundaries[1:], strict=True):
+        selected = (confidence > low) & (confidence <= high)
+        if selected.any():
+            result += selected.mean() * abs(confidence[selected].mean() - correct[selected].mean())
+    return float(result)
+
+
+def binary_ece(probability: np.ndarray, target: np.ndarray, bins: int = 15) -> float:
+    boundaries = np.linspace(0.0, 1.0, bins + 1)
+    result = 0.0
+    for low, high in zip(boundaries[:-1], boundaries[1:], strict=True):
+        selected = (probability > low) & (probability <= high)
+        if selected.any():
+            result += selected.mean() * abs(probability[selected].mean() - target[selected].mean())
+    return float(result)
+
+
+def evaluate_probabilities(
+    probabilities: np.ndarray,
+    targets: np.ndarray,
+    last_indices: np.ndarray,
+    region_instance_ids: tuple[str, ...],
+) -> dict[str, Any]:
+    probabilities = np.asarray(probabilities, dtype=np.float64)
+    probabilities /= probabilities.sum(axis=1, keepdims=True).clip(min=1e-12)
+    target_probability = probabilities[np.arange(len(targets)), targets].clip(min=1e-12)
+    ordering = np.argsort(-probabilities, axis=1, kind="stable")
+    ranks = np.empty(len(targets), dtype=np.float64)
+    reciprocal_ranks = np.empty(len(targets), dtype=np.float64)
+    success_at_1 = np.empty(len(targets), dtype=np.float64)
+    success_at_3 = np.empty(len(targets), dtype=np.float64)
+    success_at_5 = np.empty(len(targets), dtype=np.float64)
+    room_checks = np.empty(len(targets), dtype=np.int64)
+    for row, order in enumerate(ordering):
+        score = probabilities[row, targets[row]]
+        greater = int(np.sum(probabilities[row] > score + 1e-12))
+        tied = int(np.sum(np.isclose(probabilities[row], score, rtol=0.0, atol=1e-12)))
+        first_rank = greater + 1
+        last_rank = greater + tied
+        ranks[row] = (first_rank + last_rank) / 2.0
+        reciprocal_ranks[row] = np.mean(1.0 / np.arange(first_rank, last_rank + 1))
+        for cutoff, destination in (
+            (1, success_at_1), (3, success_at_3), (5, success_at_5)
+        ):
+            destination[row] = np.clip((cutoff - greater) / max(tied, 1), 0.0, 1.0)
+        # Room checks use a documented, stable catalog-order tiebreak because an
+        # exact expected number of unique rooms under tied permutations is not
+        # represented by the packed benchmark.
+        rank = int(np.flatnonzero(order == targets[row])[0]) + 1
+        rooms: set[str] = set()
+        for candidate in order[:rank]:
+            rooms.add(region_instance_ids[int(candidate)])
+        room_checks[row] = len(rooms)
+    one_hot = np.zeros_like(probabilities)
+    one_hot[np.arange(len(targets)), targets] = 1.0
+    persist_target = targets == last_indices
+    persist_probability = probabilities[np.arange(len(targets)), last_indices]
+    predicted_persist = persist_probability >= 0.5
+    persistence_auc = (
+        float(roc_auc_score(persist_target, persist_probability))
+        if len(np.unique(persist_target)) == 2
+        else float("nan")
+    )
+    return {
+        "records": int(len(targets)),
+        "top1": float(success_at_1.mean()),
+        "top3": float(success_at_3.mean()),
+        "success_at_5": float(success_at_5.mean()),
+        "mrr": float(reciprocal_ranks.mean()),
+        "nll": float(-np.log(target_probability).mean()),
+        "brier": float(np.square(probabilities - one_hot).sum(axis=1).mean()),
+        "ece": expected_calibration_error(probabilities, targets),
+        "mean_target_rank": float(ranks.mean()),
+        "mean_receptacles_checked": float(ranks.mean()),
+        "mean_rooms_checked": float(room_checks.mean()),
+        "persistence_accuracy": float(np.mean(predicted_persist == persist_target)),
+        "persistence_f1": float(f1_score(persist_target, predicted_persist, zero_division=0)),
+        "persistence_auroc": persistence_auc,
+        "persistence_brier": float(np.square(persist_probability - persist_target).mean()),
+        "persistence_ece": binary_ece(persist_probability, persist_target),
+        "mean_persistence_probability": float(persist_probability.mean()),
+    }
+
+
+def aggregate_seed_metrics(seed_results: list[dict[str, Any]]) -> dict[str, Any]:
+    if not seed_results:
+        return {}
+    aggregate: dict[str, Any] = {"seeds": len(seed_results)}
+    for subset in seed_results[0]:
+        rows = [result[subset] for result in seed_results if subset in result]
+        aggregate[subset] = {}
+        for key, value in rows[0].items():
+            if isinstance(value, (int, float)) and key != "records":
+                values = np.asarray([row[key] for row in rows], dtype=np.float64)
+                finite = values[np.isfinite(values)]
+                aggregate[subset][key] = {
+                    "mean": float(finite.mean()) if len(finite) else float("nan"),
+                    "std": float(finite.std(ddof=1)) if len(finite) > 1 else 0.0,
+                }
+            elif key == "records":
+                aggregate[subset][key] = value
+    return aggregate

code/src/readyagent/p4d_belief/models.py

@@ -0,0 +1,457 @@
+"""Query-conditioned continuous-time pointer models for P4D-Belief."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import torch
+from torch import nn
+
+from readyagent.p4d_belief.data import Catalog
+
+
+@dataclass(frozen=True)
+class ModelConfig:
+    hidden_dim: int = 128
+    layers: int = 3
+    heads: int = 4
+    dropout: float = 0.15
+    use_instance_identity: bool = False
+    use_compatibility: bool = False
+
+
+class SemanticLocationEncoder(nn.Module):
+    """Shared location encoder with no scene-specific state-ID embedding."""
+
+    def __init__(self, catalog: Catalog, hidden_dim: int) -> None:
+        super().__init__()
+        region_count = len(catalog.schema["region_category_to_id"])
+        receptacle_count = len(catalog.schema["receptacle_category_to_id"])
+        semantic_dim = hidden_dim // 4
+        self.region_embedding = nn.Embedding(region_count, semantic_dim)
+        self.receptacle_embedding = nn.Embedding(receptacle_count, semantic_dim)
+        self.project = nn.Sequential(
+            nn.Linear(semantic_dim * 2 + 4, hidden_dim),
+            nn.GELU(),
+            nn.LayerNorm(hidden_dim),
+        )
+        center = catalog.center_xyz.float()
+        known = ~catalog.is_unknown.bool()
+        mean = center[known].mean(dim=0)
+        std = center[known].std(dim=0).clamp_min(1e-3)
+        self.register_buffer("region_category", catalog.region_category.long())
+        self.register_buffer("receptacle_category", catalog.receptacle_category.long())
+        self.register_buffer("center", center)
+        self.register_buffer("center_mean", mean)
+        self.register_buffer("center_std", std)
+        self.register_buffer("is_unknown", catalog.is_unknown.float())
+
+    def base_nodes(self) -> torch.Tensor:
+        normalized_center = (self.center - self.center_mean) / self.center_std
+        return self.project(
+            torch.cat(
+                (
+                    self.region_embedding(self.region_category),
+                    self.receptacle_embedding(self.receptacle_category),
+                    normalized_center,
+                    self.is_unknown[:, None],
+                ),
+                dim=-1,
+            )
+        )
+
+
+class RelativeTimeEncoderLayer(nn.Module):
+    """Transformer layer with a learned, per-head continuous-time bias."""
+
+    def __init__(self, hidden_dim: int, heads: int, dropout: float) -> None:
+        super().__init__()
+        self.heads = heads
+        self.time_bias = nn.Linear(2, heads, bias=False)
+        self.attention = nn.MultiheadAttention(
+            hidden_dim, heads, dropout=dropout, batch_first=True
+        )
+        self.norm1 = nn.LayerNorm(hidden_dim)
+        self.norm2 = nn.LayerNorm(hidden_dim)
+        self.feed_forward = nn.Sequential(
+            nn.Linear(hidden_dim, hidden_dim * 4),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(hidden_dim * 4, hidden_dim),
+            nn.Dropout(dropout),
+        )
+        self.dropout = nn.Dropout(dropout)
+
+    def forward(
+        self, tokens: torch.Tensor, times_days: torch.Tensor, valid: torch.Tensor
+    ) -> torch.Tensor:
+        delta_hours = (times_days[:, :, None] - times_days[:, None, :]) * 24.0
+        time_features = torch.stack(
+            (torch.sign(delta_hours), torch.log1p(delta_hours.abs())), dim=-1
+        )
+        bias = self.time_bias(time_features).permute(0, 3, 1, 2)
+        key_mask = (~valid)[:, None, None, :]
+        bias = bias.masked_fill(key_mask, -1e4)
+        batch, length = valid.shape
+        attention_mask = bias.reshape(batch * self.heads, length, length)
+        attended, _ = self.attention(
+            tokens, tokens, tokens, attn_mask=attention_mask, need_weights=False
+        )
+        tokens = self.norm1(tokens + self.dropout(attended))
+        return self.norm2(tokens + self.feed_forward(tokens))
+
+
+class HistoryInputs(nn.Module):
+    def __init__(self, catalog: Catalog, config: ModelConfig) -> None:
+        super().__init__()
+        hidden = config.hidden_dim
+        category_count = len(catalog.schema["category_to_id"])
+        instance_count = len(catalog.schema.get("instance_uuid_to_id", {}))
+        self.location = SemanticLocationEncoder(catalog, hidden)
+        self.object_embedding = nn.Embedding(category_count, hidden)
+        self.instance_embedding = (
+            nn.Embedding(instance_count, hidden)
+            if config.use_instance_identity and instance_count
+            else None
+        )
+        self.event_embedding = nn.Embedding(3, hidden)
+        self.weekday_embedding = nn.Embedding(7, hidden // 4)
+        self.quality_projection = nn.Sequential(
+            nn.Linear(6, hidden // 2), nn.GELU(), nn.Linear(hidden // 2, hidden)
+        )
+        self.time_projection = nn.Linear(5, hidden)
+        self.query_projection = nn.Sequential(
+            nn.Linear(hidden + hidden // 4 + 4, hidden),
+            nn.GELU(),
+            nn.LayerNorm(hidden),
+        )
+        self.history_summary_projection = nn.Sequential(
+            nn.Linear(7, hidden), nn.GELU(), nn.Linear(hidden, hidden)
+        )
+        self.observable_context_projection = nn.Sequential(
+            nn.Linear(category_count + 5, hidden),
+            nn.GELU(),
+            nn.Linear(hidden, hidden),
+        )
+        self.query_context_norm = nn.LayerNorm(hidden)
+        self.candidate_geometry = nn.Sequential(
+            nn.Linear(5, hidden), nn.GELU(), nn.LayerNorm(hidden)
+        )
+        self.token_norm = nn.LayerNorm(hidden)
+
+    def forward(
+        self, batch: dict[str, torch.Tensor]
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+        base_nodes = self.location.base_nodes()
+        event_type = batch["event_type"].long()
+        history_mask = batch["history_mask"].bool()
+        observed = batch["observed_state_id"].long()
+        inspected = batch["candidate_state_id"].long()
+        location_id = torch.where(event_type == 1, observed, inspected).clamp_min(0)
+        location_token = base_nodes[location_id]
+        query_days = batch["query_time_days"].float()
+        event_days = batch["event_time_days"].float()
+        age_hours = ((query_days[:, None] - event_days) * 24.0).clamp_min(0.0)
+        time_features = torch.stack(
+            (
+                torch.log1p(age_hours),
+                torch.sin(2 * math.pi * event_days),
+                torch.cos(2 * math.pi * event_days),
+                torch.sin(2 * math.pi * event_days / 7.0),
+                torch.cos(2 * math.pi * event_days / 7.0),
+            ),
+            dim=-1,
+        )
+        object_token = self.object_embedding(batch["target_category_id"].long())
+        if self.instance_embedding is not None:
+            object_token = object_token + self.instance_embedding(
+                batch["target_instance_id"].long()
+            )
+        tokens = self.token_norm(
+            location_token
+            + self.event_embedding(event_type)
+            + self.quality_projection(batch["evidence_features"].float())
+            + self.time_projection(time_features)
+            + object_token[:, None, :]
+        )
+        query_features = torch.cat(
+            (
+                object_token,
+                self.weekday_embedding(batch["query_weekday_id"].long()),
+                batch["query_time_of_day_sin_cos"].float(),
+                torch.log1p(batch["elapsed_since_last_positive_days"].float())[:, None],
+                torch.ones_like(query_days)[:, None],
+            ),
+            dim=-1,
+        )
+        positive = (event_type == 1) & history_mask
+        inspection = (event_type == 2) & history_mask
+        positive_count = positive.sum(dim=1).float()
+        inspection_count = inspection.sum(dim=1).float()
+        state_one_hot = torch.nn.functional.one_hot(
+            observed.clamp_min(0), num_classes=base_nodes.shape[0]
+        ).bool()
+        distinct_states = (state_one_hot & positive[:, :, None]).any(dim=1).sum(dim=1).float()
+        previous = torch.full(
+            (event_type.shape[0],), -1, dtype=torch.long, device=event_type.device
+        )
+        change_count = torch.zeros_like(positive_count)
+        for position in range(event_type.shape[1]):
+            current = observed[:, position]
+            is_positive = positive[:, position]
+            change_count += (
+                is_positive & (previous >= 0) & (current != previous)
+            ).float()
+            previous = torch.where(is_positive, current, previous)
+        inspected_time = torch.where(
+            inspection, event_days, torch.full_like(event_days, -1e9)
+        ).max(dim=1).values
+        time_since_inspection = torch.where(
+            inspection.any(dim=1),
+            (query_days - inspected_time).clamp_min(0.0),
+            batch["elapsed_since_last_positive_days"].float(),
+        )
+        negative_strength = batch["evidence_features"].float()[:, :, 5]
+        negative_sum = (negative_strength * inspection.float()).sum(dim=1)
+        negative_mean = negative_sum / inspection_count.clamp_min(1.0)
+        negative_max = negative_strength.masked_fill(~inspection, 0.0).max(dim=1).values
+        summary = torch.stack(
+            (
+                torch.log1p(positive_count),
+                torch.log1p(inspection_count),
+                torch.log1p(distinct_states),
+                torch.log1p(change_count),
+                torch.log1p(time_since_inspection * 24.0),
+                negative_mean,
+                negative_max,
+            ),
+            dim=-1,
+        )
+        last_node = base_nodes[batch["last_state"].long()]
+        observable_context = torch.zeros_like(last_node)
+        if "context_mask" in batch:
+            context_mask = batch["context_mask"].bool()
+            context_age_hours = (
+                (query_days[:, None] - batch["context_time_days"].float()) * 24.0
+            ).clamp_min(0.0)
+            context_features = torch.cat(
+                (
+                    batch["context_category_counts"].float(),
+                    batch["context_observation_features"].float(),
+                    torch.log1p(context_age_hours)[:, :, None],
+                ),
+                dim=-1,
+            )
+            projected_context = self.observable_context_projection(context_features)
+            observable_context = (
+                projected_context * context_mask[:, :, None].float()
+            ).sum(dim=1) / context_mask.sum(dim=1).clamp_min(1)[:, None]
+        query_token = self.query_context_norm(
+            self.query_projection(query_features)
+            + last_node
+            + self.history_summary_projection(summary)
+            + observable_context
+        )
+        return tokens, query_token, base_nodes, history_mask
+
+    def candidate_nodes(
+        self, base_nodes: torch.Tensor, batch: dict[str, torch.Tensor]
+    ) -> torch.Tensor:
+        candidate_ids = batch["candidate_state_ids"].long().clamp_min(0)
+        nodes = base_nodes[candidate_ids]
+        centers = self.location.center[candidate_ids]
+        last_center = self.location.center[batch["last_state"].long()]
+        relative = (centers - last_center[:, None, :]) / self.location.center_std
+        distance = torch.linalg.vector_norm(relative, dim=-1, keepdim=True)
+        is_last = (
+            candidate_ids == batch["last_state"].long()[:, None]
+        ).float()[:, :, None]
+        # Geometry is added without introducing a scene-specific state embedding.
+        geometry = torch.cat((relative, distance, is_last), dim=-1)
+        return nodes + self.candidate_geometry(geometry)
+
+
+class CTTransformerBackbone(nn.Module):
+    def __init__(self, catalog: Catalog, config: ModelConfig) -> None:
+        super().__init__()
+        self.inputs = HistoryInputs(catalog, config)
+        self.layers = nn.ModuleList(
+            RelativeTimeEncoderLayer(config.hidden_dim, config.heads, config.dropout)
+            for _ in range(config.layers)
+        )
+
+    def forward(
+        self, batch: dict[str, torch.Tensor]
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        history, query, base_nodes, history_mask = self.inputs(batch)
+        tokens = torch.cat((history, query[:, None, :]), dim=1)
+        query_valid = torch.ones(
+            (history_mask.shape[0], 1), dtype=torch.bool, device=history_mask.device
+        )
+        valid = torch.cat((history_mask, query_valid), dim=1)
+        times = torch.cat(
+            (batch["event_time_days"].float(), batch["query_time_days"].float()[:, None]),
+            dim=1,
+        )
+        for layer in self.layers:
+            tokens = layer(tokens, times, valid)
+        candidates = self.inputs.candidate_nodes(base_nodes, batch)
+        return tokens[:, -1], candidates
+
+
+class GRUBackbone(nn.Module):
+    def __init__(self, catalog: Catalog, config: ModelConfig) -> None:
+        super().__init__()
+        self.inputs = HistoryInputs(catalog, config)
+        self.gru = nn.GRU(
+            config.hidden_dim,
+            config.hidden_dim,
+            num_layers=2,
+            dropout=config.dropout,
+            batch_first=True,
+        )
+
+    def forward(
+        self, batch: dict[str, torch.Tensor]
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        history, query, base_nodes, history_mask = self.inputs(batch)
+        lengths = history_mask.sum(dim=1).long()
+        sequence = torch.zeros(
+            history.shape[0], history.shape[1] + 1, history.shape[2],
+            device=history.device, dtype=history.dtype,
+        )
+        sequence[:, : history.shape[1]] = history
+        sequence[torch.arange(len(lengths), device=history.device), lengths] = query
+        packed = nn.utils.rnn.pack_padded_sequence(
+            sequence, (lengths + 1).cpu(), batch_first=True, enforce_sorted=False
+        )
+        _, hidden = self.gru(packed)
+        candidates = self.inputs.candidate_nodes(base_nodes, batch)
+        return hidden[-1], candidates
+
+
+class PointerBase(nn.Module):
+    def __init__(self, backbone: nn.Module, hidden_dim: int) -> None:
+        super().__init__()
+        self.backbone = backbone
+        self.query_pointer = nn.Linear(hidden_dim, hidden_dim, bias=False)
+        self.candidate_pointer = nn.Linear(hidden_dim, hidden_dim, bias=False)
+        self.scale = hidden_dim**-0.5
+
+    def pointer_logits(
+        self, query: torch.Tensor, candidates: torch.Tensor, mask: torch.Tensor
+    ) -> torch.Tensor:
+        logits = torch.einsum(
+            "bd,bmd->bm", self.query_pointer(query), self.candidate_pointer(candidates)
+        ) * self.scale
+        return logits.masked_fill(~mask.bool(), -1e4)
+
+
+class DirectPointer(PointerBase):
+    """Direct softmax comparator using the same CT Transformer and pointer."""
+
+    def __init__(self, catalog: Catalog, config: ModelConfig) -> None:
+        super().__init__(CTTransformerBackbone(catalog, config), config.hidden_dim)
+
+    def forward(self, batch: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        query, candidates = self.backbone(batch)
+        logits = self.pointer_logits(query, candidates, batch["candidate_mask"])
+        probabilities = torch.softmax(logits, dim=-1)
+        last_probability = probabilities.gather(
+            1, batch["last_candidate_index"].long()[:, None]
+        ).squeeze(1)
+        return {"probabilities": probabilities, "rho": last_probability, "logits": logits}
+
+
+class GRUDirectPointer(PointerBase):
+    def __init__(self, catalog: Catalog, config: ModelConfig) -> None:
+        super().__init__(GRUBackbone(catalog, config), config.hidden_dim)
+
+    def forward(self, batch: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        query, candidates = self.backbone(batch)
+        logits = self.pointer_logits(query, candidates, batch["candidate_mask"])
+        probabilities = torch.softmax(logits, dim=-1)
+        rho = probabilities.gather(
+            1, batch["last_candidate_index"].long()[:, None]
+        ).squeeze(1)
+        return {"probabilities": probabilities, "rho": rho, "logits": logits}
+
+
+class P4DBelief(PointerBase):
+    """Persistence-relocation factorized pointer with a single final-state NLL."""
+
+    def __init__(self, catalog: Catalog, config: ModelConfig) -> None:
+        super().__init__(CTTransformerBackbone(catalog, config), config.hidden_dim)
+        self.persistence = nn.Linear(config.hidden_dim, 1)
+        self.compatibility = (
+            nn.Sequential(
+                nn.Linear(config.hidden_dim * 2, config.hidden_dim),
+                nn.GELU(),
+                nn.Linear(config.hidden_dim, 1),
+            )
+            if config.use_compatibility else None
+        )
+
+    def forward(self, batch: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        query, candidates = self.backbone(batch)
+        rho = torch.sigmoid(self.persistence(query)).squeeze(-1)
+        relocation_mask = batch["candidate_mask"].bool().clone()
+        relocation_mask.scatter_(
+            1, batch["last_candidate_index"].long()[:, None], False
+        )
+        relocation_logits = self.pointer_logits(query, candidates, relocation_mask)
+        if self.compatibility is not None:
+            paired = torch.cat(
+                (query[:, None, :].expand_as(candidates), candidates), dim=-1
+            )
+            relocation_logits = relocation_logits + self.compatibility(paired).squeeze(-1)
+            relocation_logits = relocation_logits.masked_fill(~relocation_mask, -1e4)
+        relocation = torch.softmax(relocation_logits, dim=-1)
+        probabilities = relocation * (1.0 - rho[:, None])
+        probabilities.scatter_(
+            1, batch["last_candidate_index"].long()[:, None], rho[:, None]
+        )
+        probabilities = probabilities * batch["candidate_mask"].float()
+        return {
+            "probabilities": probabilities,
+            "rho": rho,
+            "relocation_probabilities": relocation,
+            "relocation_mask": relocation_mask,
+            "context": query,
+            "candidates": candidates,
+        }
+
+
+def state_nll(probabilities: torch.Tensor, targets: torch.Tensor) -> torch.Tensor:
+    selected = probabilities.gather(1, targets.long()[:, None]).squeeze(1)
+    return -torch.log(selected.clamp_min(1e-9)).mean()
+
+
+def bayesian_update(
+    prior: torch.Tensor,
+    checked_candidate: torch.Tensor,
+    *,
+    observed: torch.Tensor,
+    confidence: torch.Tensor,
+    coverage: torch.Tensor,
+) -> torch.Tensor:
+    """Apply one parameter-free visibility-aware observation update."""
+
+    likelihood = torch.ones_like(prior)
+    strength = (confidence * coverage).clamp(0.0, 1.0)
+    rows = torch.arange(prior.shape[0], device=prior.device)
+    not_seen_likelihood = (1.0 - strength).clamp_min(1e-6)
+    likelihood[rows, checked_candidate.long()] = torch.where(
+        observed.bool(),
+        torch.ones_like(strength),
+        not_seen_likelihood,
+    )
+    if observed.any():
+        detected_rows = rows[observed.bool()]
+        likelihood[detected_rows] = 1e-6
+        likelihood[detected_rows, checked_candidate[observed.bool()].long()] = strength[
+            observed.bool()
+        ].clamp_min(1e-6)
+    posterior = prior * likelihood
+    return posterior / posterior.sum(dim=-1, keepdim=True).clamp_min(1e-12)

code/src/readyagent/p4d_belief/training.py

@@ -0,0 +1,422 @@
+"""Training, inference and experiment orchestration utilities."""
+
+from __future__ import annotations
+
+import copy
+import json
+import random
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+from torch.utils.data import DataLoader, WeightedRandomSampler
+
+from readyagent.p4d_belief.baselines import ClassicalBaselines
+from readyagent.p4d_belief.data import (
+    Catalog,
+    PackedQueries,
+    derive_last_state,
+    load_arrays,
+    subset_indices,
+)
+from readyagent.p4d_belief.metrics import aggregate_seed_metrics, evaluate_probabilities
+from readyagent.p4d_belief.models import (
+    DirectPointer,
+    GRUDirectPointer,
+    ModelConfig,
+    P4DBelief,
+    bayesian_update,
+    state_nll,
+)
+
+
+@dataclass(frozen=True)
+class TrainConfig:
+    batch_size: int = 32
+    eval_batch_size: int = 256
+    learning_rate: float = 3e-4
+    weight_decay: float = 1e-4
+    max_epochs: int = 100
+    patience: int = 12
+    gradient_clip: float = 1.0
+    num_workers: int = 0
+    routine_train_fraction: float = 0.5
+    validation_subset: str = "main"
+    unknown_train_boost: float = 1.0
+
+
+EVALUATION_SUBSETS = {
+    "routine_all": ("routine", "all"),
+    "routine_exact": ("routine", "exact"),
+    "routine_fallback": ("routine", "fallback"),
+    "random": ("random", "all"),
+    "static": ("static", "all"),
+}
+
+SPECIAL_EVALUATION_SUBSETS = (
+    "routine_unknown",
+    "routine_returned",
+)
+
+
+def evaluation_subset_indices(
+    arrays: dict[str, np.ndarray], subset_name: str
+) -> np.ndarray:
+    if subset_name in EVALUATION_SUBSETS:
+        world, quality = EVALUATION_SUBSETS[subset_name]
+        return subset_indices(arrays, world=world, quality=quality)
+    routine = arrays["meta_world_variant_id"] == 0
+    if subset_name == "routine_unknown":
+        unknown_candidates = np.flatnonzero(arrays["candidate_is_unknown"])
+        if not len(unknown_candidates):
+            return np.empty(0, dtype=np.int64)
+        return np.flatnonzero(
+            routine & (arrays["y_current_state"] == int(unknown_candidates[0]))
+        )
+    if subset_name == "routine_returned":
+        if "y_returned_to_last" not in arrays:
+            return np.empty(0, dtype=np.int64)
+        return np.flatnonzero(routine & arrays["y_returned_to_last"].astype(bool))
+    raise ValueError(f"unknown evaluation subset: {subset_name}")
+
+
+def seed_everything(seed: int) -> None:
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+
+
+def move_batch(batch: dict[str, torch.Tensor], device: torch.device) -> dict[str, torch.Tensor]:
+    return {key: value.to(device, non_blocking=True) for key, value in batch.items()}
+
+
+def build_model(name: str, catalog: Catalog, config: ModelConfig) -> torch.nn.Module:
+    if name == "p4d":
+        return P4DBelief(catalog, config)
+    if name == "direct":
+        return DirectPointer(catalog, config)
+    if name == "gru":
+        return GRUDirectPointer(catalog, config)
+    raise ValueError(name)
+
+
+def main_training_indices(
+    arrays: dict[str, np.ndarray],
+    routine_fraction: float = 0.5,
+    unknown_boost: float = 1.0,
+) -> tuple[np.ndarray, np.ndarray]:
+    if not 0.0 <= routine_fraction <= 1.0:
+        raise ValueError("routine_fraction must be in [0, 1]")
+    if unknown_boost < 1.0:
+        raise ValueError("unknown_boost must be >= 1")
+    indices = subset_indices(arrays, world="main")
+    world = arrays["meta_world_variant_id"][indices]
+    routine = world == 0
+    weights = np.zeros(len(indices), dtype=np.float64)
+    if routine_fraction > 0.0:
+        routine_weights = np.ones(int(routine.sum()), dtype=np.float64)
+        unknown_candidates = np.flatnonzero(arrays["candidate_is_unknown"])
+        if len(unknown_candidates):
+            routine_targets = arrays["y_current_state"][indices[routine]]
+            routine_weights[routine_targets == int(unknown_candidates[0])] *= unknown_boost
+        weights[routine] = routine_fraction * routine_weights / routine_weights.sum()
+    if routine_fraction < 1.0:
+        weights[~routine] = (1.0 - routine_fraction) / (~routine).sum()
+    return indices, weights.astype(np.float64)
+
+
+def validation_indices(
+    arrays: dict[str, np.ndarray], validation_subset: str
+) -> np.ndarray:
+    if validation_subset == "main":
+        return subset_indices(arrays, world="main")
+    if validation_subset in (*EVALUATION_SUBSETS, *SPECIAL_EVALUATION_SUBSETS):
+        return evaluation_subset_indices(arrays, validation_subset)
+    raise ValueError(f"unknown validation subset: {validation_subset}")
+
+
+@torch.no_grad()
+def validation_nll(
+    model: torch.nn.Module, loader: DataLoader, device: torch.device
+) -> float:
+    model.eval()
+    total_loss = 0.0
+    records = 0
+    for raw_batch in loader:
+        batch = move_batch(raw_batch, device)
+        probabilities = model(batch)["probabilities"]
+        loss = state_nll(probabilities, batch["target_candidate_index"])
+        total_loss += float(loss) * len(probabilities)
+        records += len(probabilities)
+    return total_loss / max(records, 1)
+
+
+def train_model(
+    *,
+    name: str,
+    seed: int,
+    dataset_root: Path,
+    catalog: Catalog,
+    model_config: ModelConfig,
+    train_config: TrainConfig,
+    device: torch.device,
+    output_dir: Path,
+) -> tuple[torch.nn.Module, dict[str, Any]]:
+    seed_everything(seed)
+    train_path = dataset_root / "records/packed/train.npz"
+    val_path = dataset_root / "records/packed/val.npz"
+    train_arrays = load_arrays(dataset_root, "train")
+    train_indices, weights = main_training_indices(
+        train_arrays,
+        train_config.routine_train_fraction,
+        train_config.unknown_train_boost,
+    )
+    val_arrays = load_arrays(dataset_root, "val")
+    val_indices = validation_indices(val_arrays, train_config.validation_subset)
+    train_dataset = PackedQueries(train_path, train_indices)
+    val_dataset = PackedQueries(val_path, val_indices)
+    generator = torch.Generator().manual_seed(seed)
+    sampler = WeightedRandomSampler(
+        torch.as_tensor(weights, dtype=torch.double),
+        num_samples=len(train_indices),
+        replacement=True,
+        generator=generator,
+    )
+    train_loader = DataLoader(
+        train_dataset,
+        batch_size=train_config.batch_size,
+        sampler=sampler,
+        num_workers=train_config.num_workers,
+        pin_memory=device.type == "cuda",
+    )
+    val_loader = DataLoader(
+        val_dataset,
+        batch_size=train_config.eval_batch_size,
+        shuffle=False,
+        num_workers=train_config.num_workers,
+        pin_memory=device.type == "cuda",
+    )
+    model = build_model(name, catalog, model_config).to(device)
+    optimizer = torch.optim.AdamW(
+        model.parameters(), lr=train_config.learning_rate, weight_decay=train_config.weight_decay
+    )
+    best_state: dict[str, torch.Tensor] | None = None
+    best_val = float("inf")
+    best_epoch = -1
+    history: list[dict[str, float]] = []
+    stale = 0
+    start = time.time()
+    for epoch in range(train_config.max_epochs):
+        model.train()
+        running = 0.0
+        seen = 0
+        for raw_batch in train_loader:
+            batch = move_batch(raw_batch, device)
+            optimizer.zero_grad(set_to_none=True)
+            probabilities = model(batch)["probabilities"]
+            loss = state_nll(probabilities, batch["target_candidate_index"])
+            if not torch.isfinite(loss):
+                raise RuntimeError(f"non-finite training loss for {name}, seed {seed}")
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(model.parameters(), train_config.gradient_clip)
+            optimizer.step()
+            running += float(loss.detach()) * len(probabilities)
+            seen += len(probabilities)
+        train_nll = running / seen
+        val_nll = validation_nll(model, val_loader, device)
+        history.append({"epoch": epoch + 1, "train_nll": train_nll, "val_nll": val_nll})
+        if val_nll < best_val - 1e-5:
+            best_val = val_nll
+            best_epoch = epoch + 1
+            best_state = copy.deepcopy(model.state_dict())
+            stale = 0
+        else:
+            stale += 1
+        if stale >= train_config.patience:
+            break
+    if best_state is None:
+        raise RuntimeError("training did not produce a checkpoint")
+    model.load_state_dict(best_state)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    checkpoint_path = output_dir / "best.pt"
+    torch.save(
+        {
+            "model": best_state,
+            "model_name": name,
+            "seed": seed,
+            "model_config": asdict(model_config),
+            "train_config": asdict(train_config),
+            "best_epoch": best_epoch,
+            "best_val_nll": best_val,
+        },
+        checkpoint_path,
+    )
+    training_result = {
+        "model": name,
+        "seed": seed,
+        "parameters": sum(parameter.numel() for parameter in model.parameters()),
+        "best_epoch": best_epoch,
+        "best_val_nll": best_val,
+        "epochs_run": len(history),
+        "wall_seconds": time.time() - start,
+        "checkpoint": str(checkpoint_path),
+        "history": history,
+    }
+    (output_dir / "training.json").write_text(
+        json.dumps(training_result, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    return model, training_result
+
+
+@torch.no_grad()
+def predict_model(
+    model: torch.nn.Module,
+    dataset: PackedQueries,
+    *,
+    batch_size: int,
+    device: torch.device,
+    hold_out_last_inspection: bool = False,
+    apply_update: bool = False,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    loader = DataLoader(dataset, batch_size=batch_size, shuffle=False, pin_memory=device.type == "cuda")
+    model.eval()
+    probabilities: list[np.ndarray] = []
+    targets: list[np.ndarray] = []
+    lasts: list[np.ndarray] = []
+    for raw_batch in loader:
+        batch = move_batch(raw_batch, device)
+        checked: torch.Tensor | None = None
+        strength: torch.Tensor | None = None
+        coverage: torch.Tensor | None = None
+        eligible: torch.Tensor | None = None
+        if hold_out_last_inspection:
+            inspection = (batch["event_type"] == 2) & batch["history_mask"].bool()
+            positions = torch.where(
+                inspection,
+                torch.arange(inspection.shape[1], device=device)[None, :],
+                -1,
+            )
+            held_index = positions.max(dim=1).values
+            eligible = held_index >= 0
+            safe_index = held_index.clamp_min(0)
+            rows = torch.arange(len(held_index), device=device)
+            checked = batch["candidate_state_id"][rows, safe_index].long().clamp_min(0)
+            evidence = batch["evidence_features"][rows, safe_index].float()
+            coverage = (evidence[:, 3] * evidence[:, 4]).clamp(0.0, 1.0)
+            strength = evidence[:, 5].clamp(0.0, 1.0)
+            batch["history_mask"] = batch["history_mask"].clone()
+            batch["history_mask"][rows[eligible], held_index[eligible]] = False
+        output = model(batch)
+        belief = output["probabilities"]
+        if apply_update and checked is not None and eligible is not None:
+            updated = bayesian_update(
+                belief,
+                checked,
+                observed=torch.zeros_like(eligible),
+                confidence=strength,
+                coverage=coverage,
+            )
+            belief = torch.where(eligible[:, None], updated, belief)
+        probabilities.append(belief.cpu().numpy())
+        targets.append(batch["target_candidate_index"].cpu().numpy())
+        lasts.append(batch["last_candidate_index"].cpu().numpy())
+    return np.concatenate(probabilities), np.concatenate(targets), np.concatenate(lasts)
+
+
+def evaluate_model(
+    model: torch.nn.Module,
+    *,
+    dataset_root: Path,
+    catalog: Catalog,
+    split: str,
+    device: torch.device,
+    batch_size: int,
+    include_update: bool,
+) -> dict[str, dict[str, Any]]:
+    packed_path = dataset_root / "records/packed" / f"{split}.npz"
+    arrays = load_arrays(dataset_root, split)
+    result: dict[str, dict[str, Any]] = {}
+    for subset_name in (*EVALUATION_SUBSETS, *SPECIAL_EVALUATION_SUBSETS):
+        indices = evaluation_subset_indices(arrays, subset_name)
+        if not len(indices):
+            continue
+        dataset = PackedQueries(packed_path, indices)
+        probabilities, targets, lasts = predict_model(
+            model, dataset, batch_size=batch_size, device=device
+        )
+        result[subset_name] = evaluate_probabilities(
+            probabilities, targets, lasts, catalog.region_instance_ids
+        )
+        if include_update:
+            held_prior, held_targets, held_lasts = predict_model(
+                model,
+                dataset,
+                batch_size=batch_size,
+                device=device,
+                hold_out_last_inspection=True,
+                apply_update=False,
+            )
+            updated, _, _ = predict_model(
+                model,
+                dataset,
+                batch_size=batch_size,
+                device=device,
+                hold_out_last_inspection=True,
+                apply_update=True,
+            )
+            result[f"{subset_name}_heldout_prior"] = evaluate_probabilities(
+                held_prior, held_targets, held_lasts, catalog.region_instance_ids
+            )
+            result[f"{subset_name}_bayes_update"] = evaluate_probabilities(
+                updated, held_targets, held_lasts, catalog.region_instance_ids
+            )
+    return result
+
+
+def evaluate_classical_baselines(
+    dataset_root: Path, catalog: Catalog, split: str = "test"
+) -> dict[str, dict[str, dict[str, Any]]]:
+    train = load_arrays(dataset_root, "train")
+    train_indices = subset_indices(train, world="main")
+    train_last = derive_last_state(train)
+    baseline = ClassicalBaselines(
+        state_count=catalog.state_count,
+        category_count=len(catalog.schema["category_to_id"]),
+    )
+    baseline.fit(
+        target_category=train["target_category_id"][train_indices].astype(np.int64),
+        target_state=train["y_current_state"][train_indices].astype(np.int64),
+        last_state=train_last[train_indices],
+        weekday=train["query_weekday_id"][train_indices].astype(np.int64),
+        time_sin_cos=train["query_time_of_day_sin_cos"][train_indices],
+    )
+    test = load_arrays(dataset_root, split)
+    test_last = derive_last_state(test)
+    all_results: dict[str, dict[str, dict[str, Any]]] = {}
+    for method in ("last_seen", "object_frequency", "time_frequency", "markov"):
+        method_results: dict[str, dict[str, Any]] = {}
+        for subset_name in (*EVALUATION_SUBSETS, *SPECIAL_EVALUATION_SUBSETS):
+            indices = evaluation_subset_indices(test, subset_name)
+            if not len(indices):
+                continue
+            probabilities = baseline.predict(
+                method,
+                target_category=test["target_category_id"][indices].astype(np.int64),
+                last_state=test_last[indices],
+                weekday=test["query_weekday_id"][indices].astype(np.int64),
+                time_sin_cos=test["query_time_of_day_sin_cos"][indices],
+            )
+            targets = test["y_current_state"][indices].astype(np.int64)
+            method_results[subset_name] = evaluate_probabilities(
+                probabilities, targets, test_last[indices], catalog.region_instance_ids
+            )
+        all_results[method] = method_results
+    return all_results
+
+
+def summarize_neural(seed_results: dict[str, list[dict[str, Any]]]) -> dict[str, Any]:
+    return {name: aggregate_seed_metrics(results) for name, results in seed_results.items()}

code/tests/test_agent_core.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from evolvingnav_paper.agent import Agent, AgentConfig, ViewEvidence
+from evolvingnav_paper.filter import BeliefFilter, EvidenceLedger
+from evolvingnav_paper.memory import VersionedMemory, backproject
+from evolvingnav_paper.transition import IdentityTransition, MatrixTransition
+from evolvingnav_paper.coverage import (
+    camera_forward, candidate_surface_samples, depth_quality, heading_quaternion,
+    visible_sample_ids,
+)
+
+
+def test_backprojection_and_causal_versions() -> None:
+    point = backproject(1, 1, 2.0, np.diag([2., 2., 1.]), np.eye(4))
+    np.testing.assert_allclose(point, [1., 1., 2.])
+    memory = VersionedMemory()
+    memory.observe("cup", 2, 4.0, 0.8, "frame-1", point)
+    memory.observe("cup", 2, 8.0, 0.95, "frame-later", point)
+    memory.observe("cup", 3, 9.0, 0.9, "frame-2", point)
+    assert memory.at("cup", 7.0).state_id == 2
+    assert memory.at("cup", 7.0).valid_to is None
+    assert memory.at("cup", 7.0).evidence_handles == ["frame-1"]
+    assert memory.at("cup", 7.0).confidence == 0.8
+    assert memory.at("cup", 10.0).state_id == 3
+    assert memory.history("cup", 10.0)[0].valid_to == 9.0
+    memory.record_negative("frame-neg", 2, 10.5, [1, 2, 3])
+    assert memory.evidence_at(10.0) == []
+    assert memory.evidence_at(11.0)[0].state_id == 2
+    with pytest.raises(ValueError, match="causal"):
+        memory.observe("cup", 1, 8.0, 0.8, "old", point)
+
+
+def test_filter_propagation_then_new_evidence_once_and_arrival_independent() -> None:
+    kernel = MatrixTransition(np.array([[0.8, 0.2], [0.1, 0.9]]))
+    belief = BeliefFilter({1: 0.8, 2: 0.2}, kernel)
+    arrival = belief.arrival(5.0)
+    assert arrival[2] > 0.2
+    assert belief.posterior == {1: 0.8, 2: 0.2}
+    belief.advance(5.0)
+    assert belief.posterior[2] == pytest.approx(arrival[2])
+    evidence = ViewEvidence("frame-1", 1, frozenset({1, 2, 3, 4}), 0.8)
+    ledger = EvidenceLedger(min_new_coverage=0.05, sample_count={1: 10, 2: 10})
+    admitted = ledger.admit(evidence)
+    assert admitted == pytest.approx(0.4)
+    prior = belief.posterior[1]
+    belief.negative({1: 0.8 * admitted}, "frame-1:1")
+    assert belief.posterior[1] < prior
+    unchanged = belief.posterior.copy()
+    assert ledger.admit(evidence) == 0.0
+    assert belief.negative({1: 0.3}, "frame-1:1") is False
+    assert belief.posterior == unchanged
+
+
+def test_filter_advances_transition_context_only_after_elapsed_chunk() -> None:
+    class Clocked(IdentityTransition):
+        def __init__(self):
+            self.clock = 0.0
+
+        def advance_clock(self, seconds):
+            self.clock += seconds
+
+    transition = Clocked()
+    belief = BeliefFilter({1: 1.0}, transition)
+    belief.arrival(10.0)
+    assert transition.clock == 0.0
+    belief.advance(4.0)
+    assert transition.clock == 4.0
+
+
+def test_dynamic_reopening_and_static_no_return() -> None:
+    ledger = EvidenceLedger(sample_count={1: 10})
+    ledger.admit(ViewEvidence("a", 1, frozenset(range(8)), 0.9))
+    assert not ledger.eligible(1, belief=0.01, return_probability=0.0, new_coverage=0.0)
+    assert ledger.eligible(1, belief=0.01, return_probability=0.06, new_coverage=0.0)
+    assert ledger.round(1) == 1
+    assert ledger.admit(ViewEvidence("b", 1, frozenset(range(8)), 0.9)) == 0.8
+    fixed = BeliefFilter({1: 0.8, 2: 0.2}, IdentityTransition())
+    fixed.advance(100.0)
+    assert fixed.posterior == {1: 0.8, 2: 0.2}
+
+
+def test_dynamic_round_does_not_reopen_without_elapsed_time() -> None:
+    ledger = EvidenceLedger(sample_count={1: 10})
+    ledger.admit(ViewEvidence("a", 1, frozenset(range(8)), 0.9))
+    ledger.mark_inspected(1, now_s=5.0)
+    assert not ledger.eligible(1, belief=0.8, return_probability=0.0,
+                               new_coverage=0.0, now_s=5.0)
+    assert ledger.eligible(1, belief=0.8, return_probability=0.0,
+                           new_coverage=0.0, now_s=6.0)
+    assert ledger.round(1) == 1
+    assert ledger.eligible(1, belief=0.8, return_probability=0.0,
+                           new_coverage=0.0, now_s=6.0)
+    assert ledger.round(1) == 1
+
+
+def test_agent_replans_after_negative_and_stops_on_verified_detection() -> None:
+    class World:
+        def __init__(self):
+            self.position = 0.0
+
+        def distance(self, goal):
+            return abs(goal - self.position)
+
+        def move_chunk(self, goal, max_distance):
+            delta = min(abs(goal - self.position), max_distance)
+            self.position += np.sign(goal - self.position) * delta
+            return delta, delta / 1.0
+
+        def inspect(self, state):
+            return (state == 2, [ViewEvidence(f"frame-{state}", state,
+                frozenset(range(10)), 0.9)])
+
+        def explore(self):
+            return {}, 0.0
+
+    world = World()
+    agent = Agent(
+        {1: 0.8, 2: 0.2}, {1: 1.0, 2: 3.0, 3: 0.1}, world,
+        IdentityTransition(), AgentConfig(max_inspections=2, max_path_m=10.0,
+            chunk_m=1.0), sample_count={1: 10, 2: 10},
+    )
+    result = agent.run()
+    assert result.found
+    assert result.inspections == [1, 2]
+    assert result.actions[-1] == "STOP"
+    assert agent.filter.posterior[1] < 0.8
+
+
+def test_agent_uses_new_rgbd_evidence_before_arrival() -> None:
+    class World:
+        def __init__(self):
+            self.position = 0.0
+            self.frames = 0
+
+        def distance(self, goal):
+            return abs(goal - self.position)
+
+        def move_chunk(self, goal, max_distance):
+            displacement = min(abs(goal - self.position), max_distance)
+            self.position += np.sign(goal - self.position) * displacement
+            return displacement, displacement
+
+        def observe_chunk(self):
+            self.frames += 1
+            return [ViewEvidence("en-route-1", 1, frozenset({0}), 1.0)] if self.frames == 1 else []
+
+        def inspect(self, state):
+            return state == 2, []
+
+    agent = Agent({1: 0.8, 2: 0.2}, {1: 2.0, 2: 4.0}, World(),
+                  IdentityTransition(), AgentConfig(max_inspections=2, chunk_m=1.0),
+                  sample_count={1: 1, 2: 1})
+    result = agent.run()
+    assert result.found
+    assert result.inspections == [2]
+    assert agent.filter.posterior[1] == 0.0
+
+
+def test_unknown_mass_executes_explore_and_adds_a_searchable_state() -> None:
+    class World:
+        def __init__(self):
+            self.position = 0.0
+
+        def distance(self, goal):
+            return abs(goal - self.position)
+
+        def move_chunk(self, goal, max_distance):
+            distance = min(abs(goal - self.position), max_distance)
+            self.position += distance
+            return distance, distance
+
+        def explore(self, _budget_m):
+            self.position = 1.0
+            return {2: (2.0, 0.8)}, 1.0, 1.0
+
+        def inspect(self, state):
+            return state == 2, []
+
+    agent = Agent(
+        {1: 0.05, 99: 0.95}, {1: 10.0}, World(), IdentityTransition(),
+        AgentConfig(unknown_state=99, max_inspections=2),
+    )
+    result = agent.run()
+    assert result.found
+    assert result.actions[0] == "EXPLORE"
+    assert result.inspections == [2]
+    assert result.posterior[99] < 0.95
+
+
+def test_online_depth_coverage_uses_public_geometry_not_target_mask() -> None:
+    samples = candidate_surface_samples([0, 0, -2], radius_m=0.0)
+    depth = np.full((100, 100), 2.0, dtype=float)
+    seen = visible_sample_ids(samples, [0, 0, 0], [0, 0, 0, 1], depth, 90.0,
+                              sensor_height_m=0.0)
+    assert seen == frozenset(range(len(samples)))
+    depth[:] = 1.0
+    assert not visible_sample_ids(samples, [0, 0, 0], [0, 0, 0, 1], depth, 90.0,
+                                  sensor_height_m=0.0)
+    np.testing.assert_allclose(camera_forward(heading_quaternion([1, 0, 0])),
+                               [1, 0, 0], atol=1e-6)
+    assert depth_quality(np.array([[1., 2.], [0., np.nan]])) == 0.5
+    slots = [[-1., 0.9, -1.], [1., 0.9, -1.], [-1., 0.9, 1.], [1., 0.9, 1.]]
+    surface = candidate_surface_samples([0., 0.9, 0.], place_points=slots)
+    assert len(surface) == 25
+    np.testing.assert_allclose(surface.min(axis=0), [-1., 0.9, -1.])
+    np.testing.assert_allclose(surface.max(axis=0), [1., 0.9, 1.])
+
+
+def test_learned_transition_rows_are_normalized_and_chronological_loss() -> None:
+    import torch
+    from evolvingnav_paper.transition_model import TransitionHead, transition_nll
+
+    head = TransitionHead(hidden_dim=8)
+    context = torch.randn(2, 8)
+    candidates = torch.randn(2, 3, 8)
+    probabilities = head(context, candidates, torch.tensor([2.0, 4.0]),
+                         torch.ones(2, 3, dtype=torch.bool))
+    assert probabilities.shape == (2, 3, 3)
+    torch.testing.assert_close(probabilities.sum(-1), torch.ones(2, 3))
+    loss = transition_nll(probabilities, torch.tensor([0, 2]), torch.tensor([1, 0]))
+    assert torch.isfinite(loss)
+    loss.backward()
+    assert head.mlp[0].weight.grad is not None
+
+
+def test_transition_pairs_use_only_same_world_instance_and_later_times() -> None:
+    from evolvingnav_paper.transition_model import chronological_pairs
+
+    pairs = chronological_pairs(
+        instance_ids=np.array(["a", "a", "b", "a"]),
+        world_ids=np.array([0, 0, 0, 1]),
+        times_s=np.array([1., 4., 2., 5.]),
+        states=np.array([1, 2, 3, 4]), max_horizon_s=10,
+    )
+    assert pairs == [(0, 1, 3.0, 1, 2)]
+
+
+def test_event_horizon_pairs_are_causal_and_cover_short_target_motion() -> None:
+    from evolvingnav_paper.transition_model import event_horizon_pairs
+
+    pairs = event_horizon_pairs(
+        instance_ids=np.array(["a", "a", "a"]),
+        world_ids=np.array([0, 0, 0]),
+        query_times_s=np.array([10., 40., 100.]),
+        query_states=np.array([1, 1, 2]),
+        events=[{"instance_uuid": "a", "event_time_s": 60.,
+                 "source_state_id": 1, "destination_state_id": 2}],
+        horizons_s=(20.,),
+    )
+    assert (1, 50.0, 20.0, 1, 2) in pairs
+    assert all(source_time >= [10., 40., 100.][source] for source, source_time, *_ in pairs)
+
+
+def test_validation_fitted_detection_probability_uses_online_features() -> None:
+    from evolvingnav_paper.calibration import DetectionCalibrator
+
+    rows = [
+        {"coverage": float(i) / 20, "range_m": 1.0, "angle_cos": 1.0,
+         "projected_pixels": 100, "depth_quality": 1.0, "category_recall": 0.9,
+         "detected": i >= 10}
+        for i in range(21)
+    ]
+    calibrator = DetectionCalibrator.fit(rows)
+    low = calibrator.predict({key: value for key, value in rows[0].items() if key != "detected"})
+    high = calibrator.predict({key: value for key, value in rows[-1].items() if key != "detected"})
+    assert 0 < low < high < 1
+
+
+def test_frozen_vlm_controller_can_only_select_legal_public_action() -> None:
+    from evolvingnav_paper.controller import LunaToolController
+
+    def requester(payload):
+        assert payload["model"] == "gpt-5.6-luna"
+        assert "evaluation_private" not in str(payload)
+        assert payload["tools"][0]["parameters"]["properties"]["action"]["enum"] == [
+            "NAVIGATE_TO(1)", "EXPLORE"
+        ]
+        return {"output": [{"type": "function_call", "name": "select_action",
+                            "arguments": '{"action":"NAVIGATE_TO(1)"}'}]}
+
+    controller = LunaToolController(requester=requester)
+    assert controller.choose(["NAVIGATE_TO(1)", "EXPLORE"],
+                             {"belief": {1: 0.7}}) == "NAVIGATE_TO(1)"

code/tests/test_package_layout.py

@@ -0,0 +1,55 @@
+"""The published code keeps its runtime helpers inside its own package."""
+
+import importlib.util
+from pathlib import Path
+
+
+def test_habitat_helpers_are_packaged() -> None:
+    assert importlib.util.find_spec("evolvingnav_paper.habitat_utils") is not None
+
+
+def test_perception_does_not_import_the_original_readyagent_stack() -> None:
+    source = (Path(__file__).resolve().parents[1] / "evolvingnav_paper/perception.py").read_text()
+    assert "readyagent.artifacts" not in source
+    assert "readyagent.perception" not in source
+
+
+def test_navigation_cli_accepts_explicit_asset_paths() -> None:
+    from evolvingnav_paper import run
+
+    assert hasattr(run, "arguments")
+    args = run.arguments([
+        "--dataset", "/data/belief", "--tasks", "/data/tasks",
+        "--hssd-root", "/data/hssd", "--navmesh-root", "/data/navmeshes",
+        "--checkpoint", "/models/p4d.pt", "--output", "/tmp/p4d-run",
+    ])
+    assert args.navmesh_root == Path("/data/navmeshes")
+    assert args.inspection == "grounded-sam"
+
+
+def test_visual_verifier_accepts_explicit_asset_paths() -> None:
+    from evolvingnav_paper import verify_visual
+
+    assert hasattr(verify_visual, "arguments")
+    args = verify_visual.arguments([
+        "/tmp/p4d-run", "--tasks", "/data/tasks",
+        "--hssd-root", "/data/hssd", "--navmesh-root", "/data/navmeshes",
+    ])
+    assert args.navmesh_root == Path("/data/navmeshes")
+
+
+def test_unit_tests_do_not_require_the_local_benchmark_dataset() -> None:
+    source = (Path(__file__).resolve().parent / "test_paper_code.py").read_text()
+    assert "data/task_datasets" not in source
+
+
+def test_record_packer_requires_an_explicit_dataset_root(monkeypatch) -> None:
+    import sys
+
+    import pytest
+    from pack_p4d_hssd_records import arguments
+
+    monkeypatch.setattr(sys, "argv", ["pack_p4d_hssd_records.py"])
+    with pytest.raises(SystemExit) as error:
+        arguments()
+    assert error.value.code == 2

code/tests/test_paper_code.py

@@ -0,0 +1,361 @@
+from __future__ import annotations
+
+import numpy as np
+
+from evolvingnav_paper.policy import candidate_utility, pack_public_query, predict_public, rank_candidates
+from evolvingnav_paper.evaluate import evaluate_search
+from evolvingnav_paper.backend import visible_fraction_from_masks
+
+
+def test_public_packing_never_exposes_labels_or_world_metadata() -> None:
+    query = {
+        "query_id": "q1", "world_variant": "routine",
+        "input": {
+            "target": {"instance_uuid": "mug_1", "category": "mug"},
+            "query": {"query_time_s": 100000.0},
+            "history_summary": {"elapsed_since_last_positive_s": 10.0},
+            "target_history": [{
+                "timestamp_s": 99990.0, "delta_t_from_previous_s": 0.0,
+                "event_type": "positive_observation", "observed_state_id": 1,
+                "detector_confidence": 1.0, "instance_match_confidence": 1.0,
+                "visible_fraction_estimate": 1.0,
+            }],
+            "candidate_state_ids": [1, 2],
+        },
+    }
+    schema = {"category_to_id": {"mug": 0}, "state_count_including_unknown": 3}
+    features = {
+        "candidate_region_category_id": np.zeros(3, dtype=np.int16),
+        "candidate_receptacle_category_id": np.zeros(3, dtype=np.int16),
+        "candidate_center_xyz": np.zeros((3, 3), dtype=np.float32),
+        "candidate_is_unknown": np.zeros(3, dtype=bool),
+    }
+    arrays = pack_public_query(query, schema, features)
+    assert "y_current_state" not in arrays
+    assert "meta_world_variant_id" not in arrays
+    assert arrays["observed_state_id"][0, -1] == 1
+
+
+def test_search_uses_public_cost_and_evaluator_scores_private_goal() -> None:
+    belief = {1: 0.75, 2: 0.25}
+    order = rank_candidates(belief, {1: 3.0, 2: 1.0})
+    assert order == [1, 2]
+    truth = {"current_state_id": 2, "oracle_shortest_path_m": 1.0}
+    public = {
+        "base_episode_id": "ep",
+        "episode_budget": {"max_candidate_inspections": 2, "max_path_length_m": 8.0},
+        "success_spec": {"max_geodesic_distance_m": 1.0},
+    }
+    def route(a, b):
+        return abs(a - b)
+
+    def inspect(state, _viewpoint):
+        return {
+            "detected": state == 2, "visible_fraction": 1.0,
+            "distance_to_valid_goal_m": 0.0,
+        }
+
+    result = evaluate_search(
+        public, truth, belief, start=0.0, goals={1: 3.0, 2: 4.0},
+        distance=route, inspect=inspect,
+    )
+    assert result["success"] is True
+    assert result["inspections"] == 2
+    assert result["path_m"] == 4.0
+    assert result["spl"] == 0.25
+
+
+def test_candidate_utility_matches_equation_twelve() -> None:
+    assert candidate_utility(
+        arrival_probability=0.6, new_detection_probability=0.8,
+        distance_m=2.0, eta_s=5.0, lambda_time=0.2, lambda_inspect=1.0,
+    ) == 0.12
+
+
+def test_n1_selects_belief_top1_even_when_other_goal_is_nearer() -> None:
+    belief = {1: 0.7, 2: 0.3}
+    costs = {1: 9.0, 2: 1.0}
+    assert rank_candidates(belief, costs, task="n1") == [1]
+
+
+def test_model_receives_last_state_derived_from_public_history() -> None:
+    import torch
+
+    class RecordingModel:
+        def __call__(self, batch):
+            assert batch["last_state"].tolist() == [1]
+            assert batch["last_candidate_index"].tolist() == [0]
+            return {"probabilities": torch.tensor([[0.8, 0.2]])}
+
+    arrays = {
+        "event_type": np.array([[1]], dtype=np.int8),
+        "history_mask": np.array([[True]]),
+        "observed_state_id": np.array([[1]], dtype=np.int16),
+        "candidate_state_ids": np.array([[1, 2]], dtype=np.int16),
+        "candidate_mask": np.array([[True, True]]),
+        "instance_uuid": np.array(["mug_1"]),
+    }
+    schema = {"instance_uuid_to_id": {"mug_1": 0}}
+    assert predict_public(RecordingModel(), schema, arrays) == {1: 0.800000011920929, 2: 0.20000000298023224}
+
+
+def test_transition_model_batch_contains_no_evaluator_fields() -> None:
+    from evolvingnav_paper.policy import model_input_batch
+
+    arrays = {
+        "event_type": np.array([[1]], dtype=np.int8),
+        "history_mask": np.array([[True]]),
+        "observed_state_id": np.array([[1]], dtype=np.int16),
+        "candidate_state_ids": np.array([[1, 2]], dtype=np.int16),
+        "candidate_mask": np.array([[True, True]]),
+        "instance_uuid": np.array(["mug_1"]),
+        "evaluation_private": np.array([123]),
+    }
+    result = model_input_batch(arrays, {"instance_uuid_to_id": {"mug_1": 0}})
+    assert "evaluation_private" not in result
+    assert result["last_state"].item() == 1
+
+
+def test_public_packing_rejects_future_observation() -> None:
+    import pytest
+
+    query = {
+        "query_id": "future", "input": {
+            "target": {"instance_uuid": "mug_1", "category": "mug"},
+            "query": {"query_time_s": 100.0},
+            "history_summary": {"elapsed_since_last_positive_s": 0.0},
+            "target_history": [{
+                "timestamp_s": 101.0, "delta_t_from_previous_s": 0.0,
+                "event_type": "positive_observation", "observed_state_id": 1,
+                "detector_confidence": 1.0, "instance_match_confidence": 1.0,
+                "visible_fraction_estimate": 1.0,
+            }],
+            "candidate_state_ids": [1, 2],
+        },
+    }
+    schema = {"category_to_id": {"mug": 0}, "state_count_including_unknown": 3}
+    features = {
+        "candidate_region_category_id": np.zeros(3, dtype=np.int16),
+        "candidate_receptacle_category_id": np.zeros(3, dtype=np.int16),
+        "candidate_center_xyz": np.zeros((3, 3), dtype=np.float32),
+        "candidate_is_unknown": np.zeros(3, dtype=bool),
+    }
+    with pytest.raises(ValueError, match="future"):
+        pack_public_query(query, schema, features)
+
+
+def test_n2_replans_from_current_viewpoint_and_stops_at_verified_goal() -> None:
+    episode = {
+        "base_episode_id": "ep", "episode_budget": {
+            "max_candidate_inspections": 3, "max_path_length_m": 30.0,
+        },
+        "success_spec": {"max_geodesic_distance_m": 1.0, "require_stop_action": True},
+    }
+    truth = {"current_state_id": 3, "oracle_shortest_path_m": 5.0}
+    belief = {1: 0.8, 2: 0.12, 3: 0.08}
+    goals = {1: 4.0, 2: -3.0, 3: 5.0}
+
+    def inspect(state, viewpoint):
+        return {
+            "detected": state == 3,
+            "visible_fraction": 0.9 if state == 3 else 0.0,
+            "distance_to_valid_goal_m": 0.0 if state == 3 else 5.0,
+        }
+
+    result = evaluate_search(
+        episode, truth, belief, start=0.0, goals=goals,
+        distance=lambda a, b: abs(a - b), inspect=inspect,
+    )
+    assert result["inspection_order"] == [1, 3]
+    assert result["actions"][-1] == "STOP"
+    assert result["success"] is True
+    assert result["inspection_evidence"][-1]["state_id"] == 3
+    assert result["inspection_evidence"][-1]["visible_fraction"] == 0.9
+
+
+def test_correct_state_without_valid_view_is_not_success() -> None:
+    episode = {
+        "base_episode_id": "ep", "episode_budget": {
+            "max_candidate_inspections": 1, "max_path_length_m": 10.0,
+        },
+        "success_spec": {"max_geodesic_distance_m": 1.0, "require_stop_action": True},
+    }
+    truth = {"current_state_id": 1, "oracle_shortest_path_m": 2.0}
+
+    def inspect(_state, _viewpoint):
+        return {"detected": True, "visible_fraction": 0.8, "distance_to_valid_goal_m": 1.5}
+
+    result = evaluate_search(
+        episode, truth, {1: 1.0}, start=0.0, goals={1: 2.0},
+        distance=lambda a, b: abs(a - b), inspect=inspect, task="n1",
+    )
+    assert result["success"] is False
+    assert result["actions"][-1] == "STOP"
+
+
+def test_verified_instance_at_neighbor_state_viewpoint_can_succeed() -> None:
+    episode = {
+        "base_episode_id": "ep", "episode_budget": {
+            "max_candidate_inspections": 1, "max_path_length_m": 10.0,
+        },
+        "success_spec": {"max_geodesic_distance_m": 1.0},
+    }
+    truth = {"current_state_id": 2, "oracle_shortest_path_m": 2.0}
+
+    result = evaluate_search(
+        episode, truth, {1: 1.0}, start=0.0, goals={1: 2.0},
+        distance=lambda a, b: abs(a - b),
+        inspect=lambda _state, _viewpoint: {
+            "detected": True, "visible_fraction": 0.8,
+            "distance_to_valid_goal_m": 0.4,
+        },
+        task="n1",
+    )
+    assert result["success"] is True
+
+
+def test_paper_success_requires_twenty_percent_visibility() -> None:
+    episode = {
+        "base_episode_id": "ep", "episode_budget": {
+            "max_candidate_inspections": 1, "max_path_length_m": 10.0,
+        },
+        "success_spec": {"max_geodesic_distance_m": 1.0, "min_visible_fraction": 0.05},
+    }
+    truth = {"current_state_id": 1, "oracle_shortest_path_m": 2.0}
+
+    def inspect(_state, _viewpoint):
+        return {"detected": True, "visible_fraction": 0.19, "distance_to_valid_goal_m": 0.0}
+
+    result = evaluate_search(
+        episode, truth, {1: 1.0}, start=0.0, goals={1: 2.0},
+        distance=lambda a, b: abs(a - b), inspect=inspect, task="n1",
+    )
+    assert result["success"] is False
+
+
+def test_visible_fraction_uses_target_only_projection_as_denominator() -> None:
+    actual = np.array([[7, 7, 0], [0, 7, 0]])
+    target_only = np.array([[7, 7, 7], [7, 7, 0]])
+    assert visible_fraction_from_masks(actual, target_only, semantic_id=7) == 0.6
+
+
+def test_grounded_sam_policy_detection_uses_rgb_depth_and_category_only() -> None:
+    from evolvingnav_paper.perception import detect_category
+
+    def detector(rgb, categories):
+        assert rgb.shape == (2, 2, 3)
+        assert categories == ("bottle",)
+        return (("bottle", 0.9, (0.0, 0.0, 1.0, 1.0)),)
+
+    def segmenter(rgb, box):
+        assert rgb.shape == (2, 2, 3)
+        assert box == (0.0, 0.0, 1.0, 1.0)
+        return np.ones((2, 2), dtype=bool)
+
+    assert detect_category(
+        detector, segmenter, np.zeros((2, 2, 4), dtype=np.uint8), "bottle"
+    ) is True
+
+
+def test_grounded_sam_returns_mask_for_rgbd_memory_backprojection() -> None:
+    from evolvingnav_paper.perception import detect_instances
+
+    found = detect_instances(
+        lambda _rgb, _categories: (("bottle", 0.9, (0., 0., 1., 1.)),),
+        lambda _rgb, _box: np.ones((2, 2), dtype=bool),
+        np.zeros((2, 2, 4), dtype=np.uint8), "bottle",
+    )
+    assert len(found) == 1
+    assert found[0].confidence == 0.9
+    assert found[0].mask.sum() == 4
+
+
+def test_grounded_sam_requires_a_nonempty_target_category_mask() -> None:
+    from evolvingnav_paper.perception import detect_category
+
+    rgb = np.zeros((2, 2, 3), dtype=np.uint8)
+    def detector(_rgb, _categories):
+        return (
+            ("book", 0.9, (0.0, 0.0, 1.0, 1.0)),
+            ("bottle", 0.8, (0.0, 0.0, 1.0, 1.0)),
+        )
+
+    def empty_mask(_rgb, _box):
+        return np.zeros((2, 2), dtype=bool)
+    assert detect_category(detector, empty_mask, rgb, "bottle") is False
+
+
+def test_training_cli_exposes_paper_optimizer_parameters(monkeypatch) -> None:
+    import sys
+    from train_p4d_belief import arguments
+
+    monkeypatch.setattr(sys, "argv", [
+        "train_p4d_belief.py", "--dataset-root", "/data/p4d", "--output", "/tmp/p4d",
+        "--weight-decay", "0.01", "--gradient-clip", "1.0",
+    ])
+    args = arguments()
+    assert args.weight_decay == 0.01
+    assert args.gradient_clip == 1.0
+
+
+def test_training_cli_defaults_match_paper_configuration(monkeypatch) -> None:
+    import sys
+    from train_p4d_belief import arguments
+
+    monkeypatch.setattr(sys, "argv", [
+        "train_p4d_belief.py", "--dataset-root", "/data/p4d", "--output", "/tmp/p4d",
+    ])
+    args = arguments()
+    assert args.models == ["p4d"]
+    assert args.seeds == [0, 1, 2, 3, 4]
+    assert (args.layers, args.hidden_dim, args.heads, args.dropout) == (3, 128, 4, 0.1)
+    assert (args.batch_size, args.patience, args.weight_decay) == (64, 10, 0.01)
+    assert args.eval_split == "val"
+    assert args.use_instance_identity is True
+    assert args.use_compatibility is True
+
+
+def test_paper_compatibility_head_receives_state_loss_gradient() -> None:
+    import torch
+
+    from readyagent.p4d_belief.data import Catalog
+    from readyagent.p4d_belief.models import ModelConfig, P4DBelief, state_nll
+
+    catalog = Catalog(
+        region_category=torch.tensor([0, 0, 0]),
+        receptacle_category=torch.tensor([0, 0, 0]),
+        center_xyz=torch.tensor([[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 0.0, 1.0]]),
+        is_unknown=torch.tensor([False, False, True]),
+        region_instance_ids=("room", "room", "unknown"),
+        schema={
+            "region_category_to_id": {"room": 0},
+            "receptacle_category_to_id": {"shelf": 0},
+            "category_to_id": {"mug": 0},
+        },
+    )
+    batch = {
+        "event_type": torch.tensor([[1, 0]]),
+        "event_time_days": torch.tensor([[0.0, 0.0]]),
+        "observed_state_id": torch.tensor([[0, -1]]),
+        "candidate_state_id": torch.tensor([[-1, -1]]),
+        "evidence_features": torch.zeros((1, 2, 6)),
+        "history_mask": torch.tensor([[True, False]]),
+        "candidate_state_ids": torch.tensor([[0, 1, 2]]),
+        "candidate_mask": torch.tensor([[True, True, True]]),
+        "target_category_id": torch.tensor([0]),
+        "query_time_days": torch.tensor([0.1]),
+        "query_time_of_day_sin_cos": torch.tensor([[0.0, 1.0]]),
+        "query_weekday_id": torch.tensor([0]),
+        "elapsed_since_last_positive_days": torch.tensor([0.1]),
+        "last_state": torch.tensor([0]),
+        "last_candidate_index": torch.tensor([0]),
+        "target_candidate_index": torch.tensor([1]),
+    }
+    model = P4DBelief(catalog, ModelConfig(
+        hidden_dim=32, layers=1, heads=4, dropout=0.0, use_compatibility=True,
+    ))
+    loss = state_nll(model(batch)["probabilities"], batch["target_candidate_index"])
+    loss.backward()
+    gradients = [parameter.grad for parameter in model.compatibility.parameters()]
+    assert all(gradient is not None for gradient in gradients)
+    assert sum(float(gradient.abs().sum()) for gradient in gradients) > 0

editorial.css

@@ -0,0 +1,32 @@
+/* Editorial presentation: research footage, quiet typography, and unaltered paper figures. */
+:root{--ink:#192927;--navy:#192927;--teal:#267b70;--muted:#65736e;--line:#dce4df;--page:#f7f9f6;--orange:#c7966c}
+body{background:var(--page);color:var(--ink);font-family:Inter,"Helvetica Neue",Arial,sans-serif;font-size:17px;line-height:1.75;overflow-x:clip}
+.page-width{width:min(1320px,calc(100% - 80px))}a{color:var(--teal)}
+.site-background{display:none}html{scroll-padding-top:90px}.site-header{position:sticky;top:0;height:66px;background:#f7f9f6f2;backdrop-filter:blur(18px);z-index:20;border-bottom:1px solid var(--line)}
+.site-header .site-name{font-size:21px;font-weight:800;letter-spacing:-.055em;color:#1c3730}.site-name:before{content:"";display:inline-block;width:9px;height:9px;border-radius:50%;background:#579d8b;margin-right:10px}
+.site-header nav{gap:26px}.site-header nav a{font-size:13px;color:#56655f}.site-header nav a:hover,.site-header nav a[aria-current]{color:#207b68}
+.paper-heading{padding:0 0 72px;text-align:left}.cinema-hero,.demo-gallery{position:relative;width:100vw;margin-left:calc(50% - 50vw);background:#112822;color:#fff}
+.cinema-hero{isolation:isolate;overflow:hidden;padding:62px max(40px,calc((100vw - 1320px)/2)) 24px}
+.hero-footage{position:absolute;inset:0;z-index:-2;display:grid;grid-template-columns:1fr 1fr;gap:3px;opacity:.65;background:#253c32}.hero-footage video{width:100%;height:100%;object-fit:cover;min-width:0}.hero-footage video:last-child{object-fit:cover;object-position:right center}
+.cinema-hero:after{content:"";position:absolute;inset:0;z-index:-1;background:linear-gradient(90deg,rgba(9,29,25,.96),rgba(9,29,25,.77) 53%,rgba(9,29,25,.24)),linear-gradient(0deg,#112822,transparent 45%)}
+.hero-content{max-width:1080px}.paper-kicker{display:flex;align-items:center;gap:12px;justify-content:flex-start;margin:0 0 25px;color:#b0d1c1;font-size:11px;letter-spacing:.15em;font-weight:700}.paper-kicker span{color:#9cbcaf}.status-dot{width:7px;height:7px;background:#a6d5ba;border-radius:50%;box-shadow:0 0 0 5px #a6d5ba15;animation:beacon 3s ease-in-out infinite}
+.paper-heading h1.latest-paper-title{text-align:left;max-width:980px;margin:0 0 28px;color:#fff;font-weight:650}.latest-paper-title .title-project{font-size:clamp(42px,5.2vw,76px);line-height:1.02;letter-spacing:-.055em;max-width:880px;color:#fff}.latest-paper-title .title-colon{display:none}.latest-paper-title .title-description{font-size:clamp(20px,2.2vw,29px);letter-spacing:-.025em;line-height:1.35;margin-top:22px;max-width:850px;color:#dbe7e0;font-weight:400}
+.paper-authors{max-width:1060px;margin:0 0 26px;color:#fff}.author-line{justify-content:flex-start;gap:5px 20px;font-size:15px;line-height:1.7;max-width:940px}.author-line span{white-space:nowrap}.author-line sup{color:#b0d3c0}.affiliation-line{margin:0 0 7px!important;max-width:890px!important;color:#c2d1c9!important;font-size:12px!important;line-height:1.7!important}.author-notes{color:#b2c6bb!important;font-size:11px!important;line-height:1.6!important}.author-notes span{margin:0 9px}
+.paper-heading .paper-links{display:flex!important;flex-wrap:wrap;justify-content:flex-start;max-width:none;gap:10px!important;margin:0}.paper-links .resource-button{min-height:48px;padding:9px 18px!important;border-radius:6px!important;border:1px solid #ffffff38!important;background:#ffffff0c!important;backdrop-filter:blur(12px);box-shadow:none;color:#fff!important;gap:9px}.paper-links .resource-button:hover{background:#ffffff20!important;border-color:#a4caba!important;transform:translateY(-2px)}.resource-button .button-symbol{border:none;background:none;color:#c3ded0;font:500 19px/1 Arial;width:22px;height:24px;flex-basis:22px}.button-copy strong{color:#fff;font-size:13px;font-weight:600}.button-copy small{display:none}.paper-links .resource-button.explore-link{background:#d7eddf!important;border-color:#d7eddf!important}.resource-button.explore-link .button-copy strong,.resource-button.explore-link .button-symbol{color:#193b2b;background:none}.paper-links .resource-button.explore-link:hover{background:#eefaf2!important}
+.hero-bottom{display:flex;justify-content:space-between;align-items:center;gap:16px;margin-top:32px;padding-top:16px;border-top:1px solid #ffffff20;color:#abc1b6;font-size:11px;letter-spacing:.02em}#motion-toggle{border:none;background:none;color:#d2e1d8;cursor:pointer;font:inherit;padding:7px 0;white-space:nowrap}#motion-toggle span{margin-left:12px}
+.demo-gallery{padding:0 max(40px,calc((100vw - 1320px)/2)) 48px;background:#112822}.hssd-demo-strip{margin:0;padding:24px 0 0;border-top:none}.hssd-demo-strip+.hssd-demo-strip{margin-top:26px;padding-top:30px;border-top:1px solid #ffffff1c}.hssd-demo-heading{margin-bottom:18px;gap:20px;align-items:center}.hssd-demo-heading h2{font-size:27px;font-weight:750;color:#eef6f0;letter-spacing:-.035em;line-height:1.2}.hssd-demo-heading h2 span{font-weight:400;color:#96b6a6}.hssd-demo-heading .hssd-demo-note{font-size:12px;color:#a6beb0}.hssd-video-grid{gap:16px;grid-template-columns:repeat(4,minmax(0,1fr))}.hssd-video-card{border:1px solid #ffffff26;border-radius:8px;background:#1b342b;box-shadow:0 6px 20px #07180e33;transition:border-color .2s,transform .2s}.hssd-video-card:hover{border-color:#82b99c;transform:translateY(-3px)}.hssd-video-label{position:static;background:#1b342b;color:#e0ebe4;padding:13px 12px;min-height:60px;font-size:12px;line-height:1.45;border-bottom:1px solid #ffffff15;letter-spacing:0}.hssd-video-frame video{object-fit:contain}.hssd-video-card figcaption{padding:11px 12px;font-size:11px;color:#aec7b8}.hssd-video-card figcaption:before{background:#76ad94}
+.paper-highlights{max-width:none;margin:0;padding:36px 0;display:grid;grid-template-columns:repeat(4,1fr);border:none;border-bottom:1px solid var(--line);background:none;border-radius:0;gap:0}.paper-highlights>div{display:flex;flex-direction:column;align-items:flex-start;gap:8px;padding:0 28px;border-right:1px solid var(--line)}.paper-highlights>div:first-child{padding-left:0}.paper-highlights>div:last-child{border:0}.paper-highlights strong{font-size:44px;font-weight:550;letter-spacing:-.055em;line-height:1.1;color:#204c3f}.paper-highlights span{font-size:12px;line-height:1.5;color:#6d7d73}.paper-highlights br{display:none}
+.section-kicker{display:block;color:#458271;font-size:11px;font-weight:700;letter-spacing:.17em;margin-bottom:15px;line-height:1.5}.overview-heading{display:grid;grid-template-columns:1.2fr 1fr;column-gap:90px;align-items:end;margin:0 0 32px}.overview-heading .section-kicker{grid-column:1/-1}.overview-heading h2,.paper-section h2,.core-loop-intro h2{font-size:clamp(30px,3.4vw,46px);line-height:1.13;font-weight:600;letter-spacing:-.045em;color:#203a30;margin:0 0 24px}.overview-heading h2{margin:0}.overview-heading p{font-size:17px;color:#68766e;max-width:410px;margin:0 0 4px}
+.main-figure,.paper-figure,.paper-figure.full,.benchmark-figure{border:1px solid var(--line);border-radius:10px;padding:24px;background:#fff;box-shadow:0 8px 28px #29453605}.main-figure{margin-bottom:65px}.main-figure figcaption,.paper-figure figcaption,.benchmark-figure figcaption{font-size:13px;line-height:1.8;color:#68766e;margin:20px 0 0;padding-top:16px;border-top:1px solid #edf0ec}.paper-figure img,.paper-figure.full img{max-height:none;object-fit:contain}.figure-open{transition:opacity .2s;display:block}.figure-open:hover{opacity:.85}.figure-number{color:#518270!important;line-height:1.5!important}
+.core-loop{display:grid;grid-template-columns:1fr 1.7fr;gap:54px;background:#eaf0e9;border:1px solid #d9e3d8;padding:42px;border-radius:12px;margin:0 0 80px}.core-loop-intro h2{font-size:32px;line-height:1.16}.core-loop-intro p{font-size:15px!important;line-height:1.8!important;color:#607368!important;max-width:none!important}.core-loop-grid{display:grid;grid-template-columns:1fr 1fr;gap:24px}.core-loop-grid article{padding:0 0 18px;background:none;border:0;border-bottom:1px solid #cddacf;border-radius:0;min-height:0}.loop-index{font-size:11px;color:#699480}.core-loop-grid h3{font-size:20px;letter-spacing:-.03em;margin:5px 0 8px;color:#264e3c}.core-loop-grid p{font-size:13px!important;line-height:1.75!important;color:#607368!important}
+.paper-section{margin:0 0 76px;padding:0 0 76px;border-bottom:1px solid var(--line)}.paper-section>p{font-size:17px;line-height:1.85;max-width:1040px;color:#52635a;margin-bottom:22px}.abstract-section{display:grid;grid-template-columns:1fr 2fr;gap:0 60px}.abstract-section>.section-kicker{grid-column:1}.abstract-section h2{grid-column:1}.abstract-section>p{grid-column:2}.abstract-section>p:first-of-type{grid-row:1/3}.abstract-section>p:last-of-type{margin-bottom:0}.equation-note{display:flex;flex-wrap:wrap;gap:10px;align-items:center;font:13px/1.6 "Helvetica Neue",Arial,sans-serif!important;padding:20px 24px;background:#eaf1eb;border-color:#5c947e;border-radius:0 6px 6px 0;max-width:none!important}.equation-note span{font-weight:500}
+.ex-intro{margin-bottom:14px}.ex-eyebrow{color:#548572}.ex-demo-label{font-size:11px}.ex-shell{border-radius:12px;overflow:hidden;box-shadow:0 14px 40px #1c392c0c}.ex-footnote{margin-top:20px!important;font-size:12px!important}.benchmark-figure-grid{gap:24px;align-items:stretch}.benchmark-figure .figure-open{display:flex;align-items:center;flex:1}.benchmark-figure img{height:auto;max-height:none}.protocol-table{border-radius:8px;overflow:hidden}.protocol-table>div{padding:22px 17px}.protocol-table b{color:#42856c;font:600 24px/1.5 Arial}.protocol-table span{font-size:13px}.protocol-table small{font-size:11px}
+.result-row{padding:26px 12px;background:#eaf0e9;border-radius:8px;border:1px solid #d6e2d6;gap:0}.result{padding:0 18px}.result strong{color:#2a6950;font-size:32px;letter-spacing:-.04em;font-weight:600}.result span{font-size:12px;margin-top:10px}.table-scroll{overflow-x:auto;border-radius:8px;border:1px solid var(--line)}.results-table{margin:0;border:0;font-size:13px}.results-table th{background:#e9eee8;font-size:12px;padding:18px 13px}.results-table td{padding:20px 13px;white-space:nowrap}.results-table .ours td{background:#eef5eb;color:#2a5f45}.latest-results-figures{gap:28px}.latest-results-figures .paper-figure{margin:0;padding:24px}.compact-result-figure img{max-height:400px!important}.paper-section h3{font-size:32px;letter-spacing:-.035em;margin:46px 0 16px}.sequence-grid{gap:24px;align-items:start}.real-world-sequence{padding:20px!important;border-radius:10px}.real-world-sequence img{height:auto!important;max-height:none!important}.real-world-sequence figcaption{min-height:0}
+.resources .resource-links{display:grid;grid-template-columns:repeat(3,1fr);gap:12px}.resource-links a{background:#fff;border:1px solid var(--line);border-radius:7px;padding:18px 20px;font-size:13px;color:#345d47}.citation-heading{display:flex;align-items:center;gap:20px;justify-content:space-between}.citation-heading h2{margin:0 0 20px}.citation-heading button{padding:11px 17px;border:1px solid #c9d7cb;border-radius:6px;background:#edf3ed;color:#315e45;cursor:pointer;font:500 12px Arial}#copy-status{font-size:12px;color:#477a5c}.bibtex pre{background:#edf1eb;border:1px solid #d7e0d5;color:#425347;padding:28px;border-radius:9px;font:12px/1.9 ui-monospace,monospace;white-space:pre-wrap;overflow-wrap:anywhere}.bibtex{border:none;margin-bottom:0;padding-bottom:70px}
+footer{background:#112822;border:0;padding:46px 0 42px;color:#a5c1b0;font-size:12px}footer .page-width{display:flex;align-items:center;gap:35px}footer a{color:#c8dfce;text-decoration:none}.footer-wordmark{font-size:24px;font-weight:700;letter-spacing:-.05em}.footer-wordmark span{margin-left:18px;font-weight:400}footer p{flex:1;margin:0}
+:focus-visible{outline:3px solid #67ac8a;outline-offset:5px}@keyframes beacon{50%{box-shadow:0 0 0 9px #a6d5ba05}}.motion-paused .status-dot{animation:none}
+@media(min-width:1600px){.cinema-hero{padding-top:72px;padding-bottom:25px}.latest-paper-title .title-project{font-size:80px}}
+@media(max-width:1050px){.page-width{width:calc(100% - 48px)}.cinema-hero{padding:44px 24px 20px}.demo-gallery{padding:0 24px 38px}.site-header nav{gap:16px}.hssd-video-grid{gap:10px}.hssd-video-label{font-size:11px;padding:10px}.hssd-video-card figcaption{font-size:10px}.core-loop{padding:30px;gap:30px}.paper-highlights strong{font-size:36px}.result strong{font-size:26px}.result{padding:0 12px}}
+@media(max-width:760px){.page-width{width:calc(100% - 36px)}.site-header{height:auto;padding:12px 0}.header-inner{gap:10px}.site-header .site-name{font-size:19px}.site-header nav{gap:16px;overflow:auto;max-width:100%;padding:2px 0}.site-header nav a{font-size:11px}.cinema-hero{padding:38px 18px 18px}.hero-footage{grid-template-columns:1fr}.hero-footage video:last-child{display:none}.cinema-hero:after{background:linear-gradient(90deg,#0d271feb,#0d271faa),linear-gradient(0deg,#112822,transparent)}.paper-kicker{font-size:9px;gap:8px;letter-spacing:.09em;margin-bottom:24px}.latest-paper-title .title-project{font-size:44px;line-height:1.03}.latest-paper-title .title-description{font-size:21px;line-height:1.4;margin-top:18px}.paper-authors{margin-bottom:22px}.author-line{font-size:12px;gap:6px 14px}.affiliation-line{font-size:10px!important}.author-notes{font-size:10px!important}.paper-heading .paper-links{display:grid!important;grid-template-columns:1fr 1fr;gap:8px!important}.paper-links .resource-button{padding:11px 12px!important;min-height:46px}.button-copy strong{font-size:12px}.hero-bottom{font-size:10px;margin-top:25px}.hero-bottom>span{max-width:200px}.demo-gallery{padding:0 18px 32px}.hssd-video-grid{grid-template-columns:repeat(2,minmax(0,1fr));gap:14px}.hssd-demo-heading{align-items:flex-start;flex-wrap:wrap;gap:6px}.hssd-demo-heading h2{font-size:25px}.hssd-demo-heading .hssd-demo-note{font-size:11px;margin:0;width:100%}.hssd-video-label{font-size:11px;min-height:55px}.hssd-video-card figcaption{font-size:10px;line-height:1.5}.paper-heading{padding-bottom:44px}.paper-highlights{grid-template-columns:1fr 1fr;padding:28px 0;gap:28px 0}.paper-highlights>div{padding:0 18px}.paper-highlights>div:nth-child(odd){padding-left:0}.paper-highlights>div:nth-child(even){border:0}.paper-highlights strong{font-size:34px}.paper-highlights span{font-size:11px}.overview-heading{grid-template-columns:1fr;gap:0}.overview-heading p{margin-top:18px;font-size:15px}.overview-heading h2,.paper-section h2{font-size:34px}.main-figure,.paper-figure.full,.benchmark-figure{padding:12px;border-radius:7px}.main-figure figcaption,.paper-figure figcaption,.benchmark-figure figcaption{font-size:11px;padding-top:12px;margin-top:12px}.main-figure{margin-bottom:36px}.core-loop{grid-template-columns:1fr;padding:24px;gap:28px;margin-bottom:50px}.core-loop-intro h2{font-size:30px}.core-loop-intro p{font-size:14px!important}.core-loop-grid{gap:20px}.core-loop-grid p{font-size:12px!important}.paper-section{padding-bottom:45px;margin-bottom:45px}.paper-section>p{font-size:15px;line-height:1.8}.abstract-section{display:block}.benchmark-figure-grid{grid-template-columns:1fr;gap:18px}.protocol-table{grid-template-columns:1fr 1fr}.protocol-table>div{padding:16px;border-bottom:1px solid var(--line)}.protocol-table>div:last-child{grid-column:1/-1}.result-row{grid-template-columns:1fr 1fr;gap:24px 0}.result{padding:0 16px}.result:nth-child(even){border:0}.result strong{font-size:29px}.result span{font-size:11px}.results-table{min-width:700px;font-size:12px}.latest-results-figures .paper-figure{padding:12px}.latest-method-figure figcaption{display:block}.latest-method-figure figcaption>a{display:inline-block;margin-top:10px}.resources .resource-links{grid-template-columns:1fr}.citation-heading{flex-wrap:wrap;gap:8px}.citation-heading h2{margin-bottom:8px}.citation-heading button{margin-bottom:12px}.bibtex pre{padding:18px;font-size:10px}.sequence-grid{grid-template-columns:1fr}.real-world-sequence{padding:12px!important}footer .page-width{flex-wrap:wrap;gap:8px 24px}footer p{flex-basis:100%;order:3}footer{padding:32px 0}.ex-demo-label{font-size:9px}}
+@media(max-width:390px){.latest-paper-title .title-project{font-size:39px}.hssd-video-grid{grid-template-columns:1fr}.paper-kicker{font-size:8px}.core-loop-grid{grid-template-columns:1fr}}
+@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}*,*:before,*:after{animation:none!important;transition:none!important}}

editorial.js

@@ -0,0 +1,37 @@
+(() => {
+  const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+  const ambient = [...document.querySelectorAll('.ambient-video')];
+  const toggle = document.getElementById('motion-toggle');
+  let motionPaused = reducedMotion.matches;
+  let heroVisible = true;
+  const syncMotion = () => {
+    document.body.classList.toggle('motion-paused', motionPaused);
+    toggle.setAttribute('aria-pressed', String(motionPaused));
+    toggle.innerHTML = motionPaused ? 'Play background <span aria-hidden="true">▶</span>' : 'Pause background <span aria-hidden="true">Ⅱ</span>';
+    ambient.forEach(video => {
+      if (motionPaused || !heroVisible || document.hidden) video.pause();
+      else video.play().catch(() => {});
+    });
+  };
+  toggle.addEventListener('click', () => { motionPaused = !motionPaused; syncMotion(); });
+  reducedMotion.addEventListener('change', event => { motionPaused = event.matches; syncMotion(); });
+  document.addEventListener('visibilitychange', syncMotion);
+  if ('IntersectionObserver' in window) {
+    new IntersectionObserver(entries => { heroVisible = entries[0].isIntersecting; syncMotion(); }).observe(document.querySelector('.cinema-hero'));
+    const demos = new IntersectionObserver(entries => entries.forEach(({target,isIntersecting}) => {
+      if (!isIntersecting) target.pause();
+      else if (!reducedMotion.matches) target.play().catch(() => {});
+    }), {threshold:0.2});
+    document.querySelectorAll('.hssd-video-frame video').forEach(video => {
+      video.removeAttribute('autoplay');
+      video.setAttribute('aria-label', video.closest('figure').querySelector('.hssd-video-label').textContent);
+      demos.observe(video);
+    });
+  }
+  syncMotion();
+  document.getElementById('copy-citation').addEventListener('click', async () => {
+    const status = document.getElementById('copy-status');
+    try { await navigator.clipboard.writeText(document.querySelector('#bibtex pre').textContent); status.textContent = 'Copied'; }
+    catch { status.textContent = 'Select the citation below to copy.'; }
+  });
+})();

figures/P4D_Benchmark.pdf

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

figures/P4D_CaseStudy.pdf

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

figures/Real_World_Case_third_1.pdf

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

figures/Real_World_Case_third_2.pdf

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