worldgap 0.1.0__tar.gz

worldgap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Test
+        run: pytest tests/ -v

worldgap-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+.venv/
+venv/
+
+# data (spec 12.16 -- raw datasets MUST NOT be committed)
+data/raw/
+data/processed/
+data/index.db
+
+# experiment tracking / notebooks scratch
+wandb/
+.ipynb_checkpoints/
+notebooks/*.html
+notebooks/*.png
+*.pt
+*.pth

worldgap-0.1.0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+- `pyproject.toml`: added `[project.urls]` (Homepage/Repository/Issues/Changelog)
+  and completed the classifier list (Python 3.10/3.11/3.12, OS Independent,
+  `Human Machine Interfaces` in place of a nonexistent `Robotics` topic
+  classifier — verified against the real `trove-classifiers` package, not
+  guessed). Verified `python -m build` + `twine check` pass, and that the
+  built wheel installs and runs correctly (`import worldgap`, `GapAnalyzer`,
+  and the `worldgap` console script) in a completely clean venv.
+- `notebooks/demo.ipynb`: added a Colab badge and an auto-install cell so the
+  notebook works from a fresh Colab runtime (installs from GitHub until the
+  package is on PyPI, then from PyPI). Re-verified zero errors after the change.
+- `README.md`: added PyPI and Colab badges.
+- `data/index.py`: `RolloutIndex`, a SQLite metadata index per spec 5.3.
+  `Rollout.save()`/`Rollout.load()` alone can't round-trip a rollout's
+  condition/source/metadata without the caller already knowing them
+  out-of-band; this closes that gap and is what makes "load every rollout in
+  a directory" possible. Tested in `tests/test_index.py`.
+- `GapAnalyzer.save_checkpoint()` / `GapAnalyzer.load_checkpoint()`: model +
+  optimizer + config persistence, needed so `worldgap train` and
+  `worldgap analyze` can be separate processes. Tested in
+  `tests/test_checkpoint.py`.
+- `GapConfig.from_yaml()`: loads `configs/v1_default.yaml`-style files for
+  `worldgap train --config`. Tested against the real default configs in
+  `tests/test_config_yaml.py`.
+- `report.py`: HTML/Markdown report generation per spec 9.3 — condition
+  table, Frechet/MMD trend plot, low-confidence warning surfacing, and a
+  Frechet/MMD rank-disagreement diagnostic per spec Section 210. Tested in
+  `tests/test_report.py`.
+- CLI wired end-to-end: `train`, `analyze`, and `validate` now actually call
+  `GapAnalyzer`/`ValidationHarness` against local rollout stores rather than
+  only parsing arguments. Documented decision: each of
+  `--data-dir`/`--source`/`--target` is a self-contained rollout store
+  (`{dir}/index.db` + `{dir}/{modality}/*.npz`) rather than assuming one
+  shared repo-wide `data/` root — see `cli.py`'s module docstring and the
+  corresponding note added to spec 9.2. Tested end-to-end in
+  `tests/test_cli.py`, including against the real installed console-script.
+- `notebooks/demo.ipynb`: runs top-to-bottom via `jupyter nbconvert --execute`
+  with zero manual intervention (spec Section 13 acceptance criterion) —
+  covers V1 perception gap with a perturbation-severity sanity sweep, the
+  V1/V2 reusability claim via the identical `GapAnalyzer` class, report
+  generation, and the validation harness's anti-cherry-picking rejection.
+  Entirely synthetic data; no Kaggle/MediaPipe/GPU access needed.
+- `matplotlib` added as a core dependency (needed by `report.py`).
+
+### Fixed
+- `inject_tremor` / `reduce_range_of_motion` (`data/loaders/synthetic_perturb.py`)
+  were perturbing every state channel, including the pose block's `visibility`
+  column — contradicting `inject_tremor`'s own docstring and silently injecting
+  noise into what would later be MediaPipe-confidence-derived validation
+  ground truth (spec 8.1). Both now use a new `perception_position_channel_mask`
+  (`data/rollout.py`) to restrict spatial perturbations to x/y/z channels only,
+  for real 258-dim perception rollouts; behavior on non-standard-shape
+  (test-fixture/actuation) rollouts is unchanged.
+- `cli.py`'s module docstring claimed `train`/`analyze` were "wired to
+  GapAnalyzer" — they aren't yet (matches ROADMAP.md, which was already
+  accurate); docstring corrected to match actual behavior.
+- `GapResult` (`analyzer.py`) now exposes `n_source`/`n_target`/`confidence`
+  as read-only properties proxying `.frechet`, matching spec 9.1's API
+  example literally rather than only via `result.frechet.n_source`.
+- `spearman_with_bootstrap_ci` (`validation/stats.py`) now raises a clear
+  error instead of crashing on `np.percentile` if every bootstrap resample
+  produces a NaN rho (fully degenerate/constant input).
+- `docs/TECHNICAL_SPEC.md` Sections 9, 10, 13 still referenced the project's
+  old name (`simgap`) in code samples and the repo-tree block; corrected to
+  `worldgap` throughout. Section 12.13 also gained an explicit note
+  documenting that the hysteresis fit is a two-branch polynomial split, not
+  literally Bouc-Wen/Hammerstein-Wiener as the MUST names — a conscious,
+  tested simplification rather than an unremarked deviation.
+
+### Added
+- Initial repo scaffolding: `pyproject.toml`, src-layout package, CI workflow.
+- `Rollout` schema with content-hashed IDs, save/load round-trip (spec 5.1–5.3).
+- Synthetic perturbation pipeline: tremor injection, reduced range-of-motion,
+  occlusion simulation — all seeded and reproducible (spec 5.4).
+- `LandmarkEncoder` (Transformer, spec 6.1) and `ActuatorEncoder` (TCN, spec 6.2).
+- Shared `WorldModel` JEPA-style core with EMA target encoder and an automated
+  representation-collapse safeguard (spec 6.3, edge case 12.7).
+- Fréchet-distance divergence metric with Ledoit-Wolf covariance shrinkage,
+  numerically-stable matrix-sqrt handling, and a sample-size confidence flag
+  (spec 7.1, 7.3, edge case 12.9).
+- MMD cross-check metric (spec 7.2).
+- `GapAnalyzer` top-level API, verified identical across the perception and
+  actuation modalities via `tests/test_modality_swap.py` — the concrete test
+  of the "one core, swappable encoder" reusability claim (spec Section 3).
+- `ValidationHarness` with pre-registration enforced in code, not just
+  documented — submitting a condition set that doesn't exactly match what was
+  pre-registered raises rather than silently proceeding (spec 8.3).
+- Two-branch (loading/unloading) hysteresis-aware curve fit for PGM actuator
+  reference data, with a residual-structure diagnostic that catches the naive
+  single-branch mistake (spec 5.5, edge case 12.13).
+- HaGRID/EgoHands loaders: directory scanning and canonical-gesture filtering
+  implemented and tested; MediaPipe landmark extraction left as a documented
+  `NotImplementedError` seam (needs real data + network access unavailable in
+  the scaffolding sandbox).
+- CLI skeleton (`worldgap train/analyze/validate`).
+- `docs/TECHNICAL_SPEC.md`, `docs/architecture.md`, `docs/data_spec.md`,
+  `ROADMAP.md`.
+
+### Known gaps (see ROADMAP.md)
+- No dataset actually downloaded or run through MediaPipe yet.
+- No real PGM characterization data digitized yet (synthetic data only, for
+  testing the fitting code itself).
+- No end-to-end V1 validation run against real ground truth yet.
+- CLI does not yet call the loaders end-to-end.
+- Report generation (spec 9.3) not implemented.

worldgap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Min
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

worldgap-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: worldgap
+Version: 0.1.0
+Summary: Reusable world-model-based domain-gap quantification for perception and actuation pipelines, before touching hardware.
+Project-URL: Homepage, https://github.com/Mattral/worldgap
+Project-URL: Repository, https://github.com/Mattral/worldgap
+Project-URL: Issues, https://github.com/Mattral/worldgap/issues
+Project-URL: Changelog, https://github.com/Mattral/worldgap/blob/main/CHANGELOG.md
+Author: Min (Mattral)
+License: MIT
+License-File: LICENSE
+Keywords: domain-gap,jepa,rehabilitation,robotics,sim2real,world-model
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.11
+Requires-Dist: torch>=2.2
+Provides-Extra: actuation
+Requires-Dist: mujoco>=3.1; extra == 'actuation'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: perception
+Requires-Dist: mediapipe>=0.10; extra == 'perception'
+Description-Content-Type: text/markdown
+
+# worldgap
+
+[![PyPI](https://img.shields.io/pypi/v/worldgap.svg)](https://pypi.org/project/worldgap/)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Mattral/worldgap/blob/main/notebooks/demo.ipynb)
+
+Reusable world-model-based domain-gap quantification — for perception pipelines and
+actuator/mechanism models — before any hardware is touched.
+
+Ground truth for this project's design is [`docs/TECHNICAL_SPEC.md`](docs/TECHNICAL_SPEC.md).
+Read that before changing architecture, data schemas, or metric definitions.
+
+## What this is
+
+Given two sets of rollouts (a source domain and a target domain — e.g. clean-lighting
+hand-tracking data vs. occluded/low-light data, or a simulated actuator vs. a published
+real-actuator characterization curve), `worldgap` trains a shared world model, encodes
+both domains into a common latent space, and reports a divergence score that is designed
+to *predict* real-world transfer degradation — validated against independently measured
+ground truth, not asserted.
+
+One core library. Two current use cases, distinguished only by which encoder plugs in:
+
+- **V1 — perception gap**: MediaPipe landmark sequences. No hardware required.
+- **V2 — actuation gap**: pneumatic gel muscle (PGM) pressure/response sequences, using
+  a published characterization curve as the "real" reference. No hardware required.
+- **V3 — closed loop** (not started, contingent on lab access): swaps in live logged
+  telemetry from real hardware. Same core code, new data loader only — see spec Section 15.
+
+## Status
+
+Core library, CLI, report generation, and demo notebook are implemented and tested
+end-to-end against synthetic/local data. Real-data phases (HaGRID/EgoHands MediaPipe
+extraction, the real Ogawa et al. PGM curve) are blocked on external access this
+environment doesn't have. See [`ROADMAP.md`](ROADMAP.md) for the exact phase-by-phase
+status, and [`CHANGELOG.md`](CHANGELOG.md) for what's landed so far.
+
+## Install
+
+```bash
+pip install -e .                 # core: torch + the World Model, works for both modalities
+pip install -e ".[perception]"   # + MediaPipe, for V1 data loading (HaGRID/EgoHands)
+pip install -e ".[actuation]"    # + MuJoCo, for V2 data loading/simulation
+pip install -e ".[dev]"          # test tooling
+```
+
+## Quickstart
+
+The library API works with any `Rollout` objects you construct yourself — the note
+below only applies to *producing* rollouts from raw HaGRID/EgoHands data, which still
+needs MediaPipe + real downloads (see ROADMAP Phase 0/1).
+
+```python
+from worldgap import GapAnalyzer
+from worldgap.config import GapConfig
+
+config = GapConfig(modality="perception")
+analyzer = GapAnalyzer(config)
+analyzer.fit(train_rollouts)
+result = analyzer.compute_gap(source_rollouts, target_rollouts)
+print(result.frechet.distance, result.confidence)
+```
+
+See [`notebooks/demo.ipynb`](notebooks/demo.ipynb) for a runnable end-to-end example
+(synthetic data, no external dependencies) covering both modalities, report
+generation, and the validation harness.
+
+## CLI
+
+```bash
+worldgap train    --modality perception --data-dir ./data/processed --config configs/v1_default.yaml
+worldgap analyze  --source ./data/clean --target ./data/perturbed --modality perception --output report.html
+worldgap validate --gap-scores results.csv --ground-truth degradation.csv
+```
+
+`--data-dir`/`--source`/`--target` are each a self-contained rollout store
+(`{dir}/index.db` + `{dir}/{modality}/*.npz`, built with `Rollout.save()` +
+`RolloutIndex.add()` — see `tests/test_index.py`). See `src/worldgap/cli.py`'s module
+docstring for why this differs slightly from spec 5.3's single-shared-index diagram.
+
+## Why not a webapp
+
+This is infra meant to be dropped into someone else's pipeline, not a hosted service.
+See spec Section 9 for the full API/CLI contract.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

worldgap-0.1.0/README.md

@@ -0,0 +1,87 @@
+# worldgap
+
+[![PyPI](https://img.shields.io/pypi/v/worldgap.svg)](https://pypi.org/project/worldgap/)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Mattral/worldgap/blob/main/notebooks/demo.ipynb)
+
+Reusable world-model-based domain-gap quantification — for perception pipelines and
+actuator/mechanism models — before any hardware is touched.
+
+Ground truth for this project's design is [`docs/TECHNICAL_SPEC.md`](docs/TECHNICAL_SPEC.md).
+Read that before changing architecture, data schemas, or metric definitions.
+
+## What this is
+
+Given two sets of rollouts (a source domain and a target domain — e.g. clean-lighting
+hand-tracking data vs. occluded/low-light data, or a simulated actuator vs. a published
+real-actuator characterization curve), `worldgap` trains a shared world model, encodes
+both domains into a common latent space, and reports a divergence score that is designed
+to *predict* real-world transfer degradation — validated against independently measured
+ground truth, not asserted.
+
+One core library. Two current use cases, distinguished only by which encoder plugs in:
+
+- **V1 — perception gap**: MediaPipe landmark sequences. No hardware required.
+- **V2 — actuation gap**: pneumatic gel muscle (PGM) pressure/response sequences, using
+  a published characterization curve as the "real" reference. No hardware required.
+- **V3 — closed loop** (not started, contingent on lab access): swaps in live logged
+  telemetry from real hardware. Same core code, new data loader only — see spec Section 15.
+
+## Status
+
+Core library, CLI, report generation, and demo notebook are implemented and tested
+end-to-end against synthetic/local data. Real-data phases (HaGRID/EgoHands MediaPipe
+extraction, the real Ogawa et al. PGM curve) are blocked on external access this
+environment doesn't have. See [`ROADMAP.md`](ROADMAP.md) for the exact phase-by-phase
+status, and [`CHANGELOG.md`](CHANGELOG.md) for what's landed so far.
+
+## Install
+
+```bash
+pip install -e .                 # core: torch + the World Model, works for both modalities
+pip install -e ".[perception]"   # + MediaPipe, for V1 data loading (HaGRID/EgoHands)
+pip install -e ".[actuation]"    # + MuJoCo, for V2 data loading/simulation
+pip install -e ".[dev]"          # test tooling
+```
+
+## Quickstart
+
+The library API works with any `Rollout` objects you construct yourself — the note
+below only applies to *producing* rollouts from raw HaGRID/EgoHands data, which still
+needs MediaPipe + real downloads (see ROADMAP Phase 0/1).
+
+```python
+from worldgap import GapAnalyzer
+from worldgap.config import GapConfig
+
+config = GapConfig(modality="perception")
+analyzer = GapAnalyzer(config)
+analyzer.fit(train_rollouts)
+result = analyzer.compute_gap(source_rollouts, target_rollouts)
+print(result.frechet.distance, result.confidence)
+```
+
+See [`notebooks/demo.ipynb`](notebooks/demo.ipynb) for a runnable end-to-end example
+(synthetic data, no external dependencies) covering both modalities, report
+generation, and the validation harness.
+
+## CLI
+
+```bash
+worldgap train    --modality perception --data-dir ./data/processed --config configs/v1_default.yaml
+worldgap analyze  --source ./data/clean --target ./data/perturbed --modality perception --output report.html
+worldgap validate --gap-scores results.csv --ground-truth degradation.csv
+```
+
+`--data-dir`/`--source`/`--target` are each a self-contained rollout store
+(`{dir}/index.db` + `{dir}/{modality}/*.npz`, built with `Rollout.save()` +
+`RolloutIndex.add()` — see `tests/test_index.py`). See `src/worldgap/cli.py`'s module
+docstring for why this differs slightly from spec 5.3's single-shared-index diagram.
+
+## Why not a webapp
+
+This is infra meant to be dropped into someone else's pipeline, not a hosted service.
+See spec Section 9 for the full API/CLI contract.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

worldgap-0.1.0/ROADMAP.md

@@ -0,0 +1,104 @@
+# Roadmap
+
+Phases per [`docs/TECHNICAL_SPEC.md`](docs/TECHNICAL_SPEC.md) Section 16. Checkboxes
+reflect actual status, not aspiration — update this file every session, not just
+at the end of a phase.
+
+## Phase 0 — Data audit
+- [x] Confirm HaGRID canonical-gesture-subset sample counts are sufficient —
+      resolved without needing Kaggle access: all four names in
+      `CANONICAL_GESTURES` are confirmed real HaGRID v1 class names, and the
+      dataset's own paper (Kapitanov et al. 2022, arXiv:2206.08219) states
+      each of the 18 classes contains 30,000+ images. Still open, and this
+      part *does* need real data: whether these four gestures are the best
+      semantic match to the ForceHand glove's actual DOFs.
+- [ ] Confirm Ogawa et al. (2017) is accessible (open access, or via institutional
+      library) — flagged in spec Section 14 as the one real external dependency.
+      Checked so far: it's published in *Advanced Robotics* (Taylor & Francis,
+      subscription), and the only copy found online is a ResearchGate
+      "Request PDF" listing, not an open one — likely needs institutional
+      access or emailing the Kurita Lab directly.
+
+## Phase 1 — Rollout schema, storage, loaders, perturbation
+- [x] `Rollout` schema + save/load round-trip (`data/rollout.py`) — tested
+- [x] Synthetic perturbation pipeline: tremor, reduced ROM, occlusion
+      (`data/loaders/synthetic_perturb.py`) — tested
+- [x] HaGRID/EgoHands directory scanning + canonical gesture filtering — tested
+      (network-free portion only)
+- [ ] HaGRID/EgoHands MediaPipe landmark extraction — **blocked**: needs real
+      downloaded frames + the `perception` extra, neither available in the
+      sandbox that produced this scaffolding. Currently a `NotImplementedError`
+      stub with the exact contract documented.
+- [x] SQLite metadata index (spec 5.3) — `data/index.py`, tested
+      (documented decision: indexed per rollout-store directory, not one
+      shared repo-wide index — see `cli.py` module docstring)
+
+## Phase 2 — World model core
+- [x] `LandmarkEncoder` (Transformer, spec 6.1) — tested via forward pass
+- [x] `ActuatorEncoder` (TCN, spec 6.2) — tested via forward pass
+- [x] Shared `WorldModel` (JEPA-style core, EMA target encoder, spec 6.3) — tested
+- [x] `CollapseSafeguard` — tested, both in isolation and wired into `fit()`
+- [ ] Real convergence check on actual (non-synthetic-placeholder) data — blocked
+      on Phase 0/1 data access
+
+## Phase 3 — Divergence module
+- [x] Fréchet distance with Ledoit-Wolf shrinkage + complex-component handling
+      (spec 7.1) — tested, including the sample-size confidence flag (7.3)
+- [x] MMD cross-check (spec 7.2) — tested
+
+## Phase 4 — Validation harness
+- [x] `ValidationHarness` with enforced pre-registration (anti-cherry-picking,
+      spec 8.3) — tested
+- [x] Spearman + bootstrap CI (spec 8.2) — tested
+- [ ] Actual V1 validation run against real MediaPipe-confidence ground truth —
+      blocked on Phase 0/1 data access
+
+## Phase 5 — Packaging, CLI, demo notebook
+- [x] `pyproject.toml`, src-layout, editable install — verified working
+- [x] `GapAnalyzer` public API (spec 9.1) — tested across both modalities
+      (`tests/test_modality_swap.py` — the concrete reusability check)
+- [x] CLI (`worldgap train/analyze/validate`) — wired end-to-end against local
+      rollout stores; verified via `tests/test_cli.py` (train->analyze
+      round trip, empty/missing-store errors, validate join + anti-cherry-pick
+      rejection) and against the real installed console-script entry point.
+      Still out of scope: producing rollout stores from raw HaGRID/EgoHands
+      frames in the first place (Phase 1's MediaPipe blocker)
+- [x] Demo notebook (`notebooks/demo.ipynb`) — executes top-to-bottom via
+      `jupyter nbconvert --execute` with zero manual intervention (acceptance
+      criterion, spec Section 13); covers V1, the V1/V2 reusability claim, and
+      the validation harness's anti-cherry-picking rejection, entirely on
+      synthetic data
+- [x] Report generation (spec 9.3) — `report.py`, HTML and Markdown output,
+      tested; includes the spec-210 Frechet/MMD rank-disagreement diagnostic
+
+## Phase 6 — V2 actuation gap
+- [x] Two-branch hysteresis-aware curve fit (spec 5.5, edge case 12.13) — tested
+      on synthetic hysteresis data, including a test that the naive
+      single-branch mistake is actually caught by the residual-structure check
+- [ ] Digitize real Ogawa et al. curve via WebPlotDigitizer — blocked on Phase 0
+- [ ] `test_modality_swap.py`-style end-to-end run on real PGM data — blocked
+
+## Phase 7 — V3 (deferred)
+- [ ] Not started. Contingent on Kurita Lab access (spec Section 15). What
+      changes and what doesn't is already documented there — no new design work
+      needed until access exists, only a new data loader.
+
+---
+
+## What's actually done vs. what's scaffolded
+
+**Genuinely implemented and tested** (71 passing tests as of this writing):
+Rollout schema, SQLite metadata index, synthetic perturbation, Fréchet + MMD
+metrics, EMA, collapse safeguard, both encoders, the shared World Model Core,
+`GapAnalyzer` end-to-end across both modalities (including checkpoint
+save/load), the validation harness's anti-cherry-picking enforcement, the PGM
+hysteresis fit (on synthetic data), HTML/Markdown report generation, the full
+CLI (`train`/`analyze`/`validate`) against local rollout stores, and a demo
+notebook that runs top-to-bottom on synthetic data with zero manual steps.
+
+**Still blocked, not skipped for convenience**: the HaGRID/EgoHands MediaPipe
+extraction step (needs real downloaded frames + network access this sandbox
+doesn't have) and digitizing the real Ogawa et al. (2017) curve (needs a
+likely-paywalled Taylor & Francis figure). Both have a clearly marked seam in
+the code rather than a silent gap. Everything else in Phase 5 that doesn't
+require those two inputs is done.

worldgap-0.1.0/configs/v1_default.yaml

@@ -0,0 +1,27 @@
+# Default config for V1 (perception gap). Loaded via `worldgap train --config`.
+# modality is set by the --modality CLI flag, not here (spec 9.2) -- this file
+# starts from GapConfig's own defaults for everything else.
+
+state_dim: 258  # 33*4 (pose) + 21*3 + 21*3 (hands), per spec 5.1.1
+
+encoder:
+  d_model: 256
+  n_layers: 4
+  n_heads: 4
+  dim_feedforward: 1024
+  dropout: 0.1
+
+world_model:
+  context_frames: 16      # ~0.5s at 30fps
+  predict_frames: 8       # ~0.25s at 30fps
+  ema_decay: 0.996
+  summary_dim: 64         # kept small deliberately -- spec 7.3
+  collapse_variance_threshold: 0.0001
+  collapse_patience_checks: 3
+
+training:
+  lr: 0.0003
+  weight_decay: 0.01
+  batch_size: 64
+  max_epochs: 100
+  seed: 0

worldgap-0.1.0/configs/v2_default.yaml

@@ -0,0 +1,29 @@
+# Default config for V2 (actuation gap). Loaded via `worldgap train --config`.
+# state_dim MUST be set explicitly for actuation (GapConfig raises otherwise,
+# per spec 5.1.1) -- 2 here assumes the minimum-viable single-DOF case
+# (wrist flexion): [commanded_pressure, resulting_joint_angle]. Bump this if
+# modeling more DOFs.
+
+state_dim: 2
+
+encoder:
+  d_model: 64          # smaller than V1's -- spec 6.2, much lower input dimensionality
+  n_layers: 2
+  n_heads: 2
+  dim_feedforward: 128
+  dropout: 0.1
+
+world_model:
+  context_frames: 16
+  predict_frames: 8
+  ema_decay: 0.996
+  summary_dim: 32       # smaller than V1's 64 -- fewer samples expected for V2, spec 7.3
+  collapse_variance_threshold: 0.0001
+  collapse_patience_checks: 3
+
+training:
+  lr: 0.0003
+  weight_decay: 0.01
+  batch_size: 32
+  max_epochs: 100
+  seed: 0