Add native ImageNet data and generation path for the joint MoT model

docs/integration/IMAGENET_NATIVE_JOINT.md

@@ -0,0 +1,21 @@
+# ImageNet native joint adapter
+
+This adapter trains the native joint MoT image expert on independent ImageNet-1K images. The complete joint architecture remains constructed: 314,227,000 parameters with QK normalization, RMSNorm and SwiGLU. The `imagenet` embodiment has no pose, action or camera-vector bank; only image patches and the shared Qwen projection execute, covering 159,006,592 parameters. Dormant parameters remain in the model and checkpoint. DDP must enable `find_unused_parameters`.
+
+Select `+experiment=pixel_proprio/native_joint/imagenet_image_generation` with the maintained `train_zarr_cartesian` entry configuration. Every data path and digest is mandatory and initially unbound. The model uses the same 1024-wide image expert, eight blocks, eight heads, 128-wide language projection, and retained EVA/human vector banks as the paired Elmo architecture. The explicit optimizer controls are AdamW peak LR 5e-6, 3,000-update linear warmup then constant LR, weight decay 0.01, no clipping, seed42, four ranks with eight images per rank and 300,000 total updates. These controls must appear in the resolved launch preflight.
+
+Each input is one actual image at camera0/time0, represented by 100 raw RGB patches of width768. Decode applies EXIF orientation, RGB conversion, bicubic resize of the shorter side to160 using round-half-up dimensions, and a centered160 crop with integer-floor origin. Pixel scaling and row-major HWC patchification use the existing native `[-1,1]` path. There is no random augmentation, latent image encoder, fabricated vector stream, class-ID embedding, clean initial frame, fused loss or CFG. Training retains the native independently sampled uniform noise level and plain FP32 x0 MSE. The spatial patch attention remains active; temporal and cross-modal interactions are unexercised for this source.
+
+An explicit class catalog maps each of the 1,000 WNIDs to its exact class-name text. The existing frozen Qwen3-Embedding-0.6B revision produces1024-dimensional unit vectors. The class manifest binds catalog bytes, cache bytes, complete encoder provenance and each class-name/vector hash; features enter the unchanged shared1024→128 language path. Authoring a metadata manifest does not prove that actual Qwen inference occurred. That proof belongs to the allocated producer and retained model-weight provenance.
+
+Allocated CPU preparation uses `scripts/data/prepare_imagenet_imagefolder.py` with `class-language`, `image-inventory` and `validation-anchors` modes. Preparation inventories every admitted image with exact byte size and SHA256. The image-inventory command does not decode every image; a separate allocated all-image decode receipt is mandatory before data admission. It rejects symlinked split/class/image paths and unknown split-root sidecars. Source aliases and the two historical ImageNet train extraction scripts must be handled explicitly in the actual preparation receipt, never silently counted as images. Production configuration requires1,281,167 train images and50,000 official validation images. The small test fixture explicitly substitutes two classes and its actual counts.
+
+The validation-anchor manifest binds the entire official validation inventory and chooses exactly one image per WNID by the first sorted relative image key. Thus scheduled validation uses1,000 frozen official-validation anchors, never TRAIN images. The full50,000-image validation inventory remains part of the immutable data context and stays excluded from training. Validation uses fully noisy input and the actual native20-step sampler; it rejects nonfinite values for every generated RGB pixel and aggregates normalized paired-reference MSE. This MSE is a class-conditioned paired diagnostic, not official FID or a perceptual-quality benchmark. The existing diagnostics save a fixed first32 previews from canonical anchor order on rank0; with the configured four-rank contiguous shards, rank0 owns the first250 anchors. The preview JSON retains source keys, class/feature hashes, pixel metadata and generated/target diagnostics. It writes PNG rather than a fictitious one-frame video.
+
+Training draws images uniformly with replacement through the maintained global rank-slot sampler. Acknowledgement advances only after a consumed training batch; worker prefetch never commits the cursor. Validation shards entire batches without padding or dropping and uses global validation-batch identities for deterministic sampling. The data context binds all source, split, preprocessing/Pillow, class-language, anchor and topology identities and is checked exactly on resume. Its offline loader restores metadata without opening raw image splits.
+
+Checkpointing and validation are scheduled every20,000 updates, retaining all15 immutable epoch+step milestones and a `last.ckpt` symlink. There is no extra terminal production save. At global batch32, 300,000 updates cover9.6million image draws, about7.49 ImageNet train epochs. This is a shared-architecture image-versus-video diagnostic; it does not reproduce the JiT image-training budget or isolate dataset coverage from temporal prediction difficulty.
+
+Local CPU tests use synthetic two-class images and synthetic unit language vectors with clearly synthetic weight provenance. They exercise exact data/class/anchor contracts, deterministic distributed draws and restoration, real optimization, the native20-step sampler without target leakage, RNG preservation, and real scheduled validation through `ModelWrapper`, `WorldModelTrainingBehavior` and Lightning. Small test-only model widths explicitly enable patch compression to keep these CPU fixtures inexpensive; production forbids patch compression and the full constructor is counted separately on meta. These tests do not certify actual ImageNet admission, Qwen generation, CUDA/FA4/Inductor, full-model capacity, distributed optimizer state or throughput.
+
+Before full launch, retain actual official-source inventory/decode, frozen class-name and Qwen provenance, destination space/fsync and readback proofs, exact published source/config, and a new four-rank optimization plus scheduled image-generation validation smoke. The existing ELMo joint smoke checker assumes temporal robot/human data and is not an ImageNet admission certificate; it must be strictly extended or a maintained ImageNet checker must be added. Actual native completion and host exits are required. No local test result supplies those production proofs.

docs/integration/IMAGENET_RAW_IMAGE_PREPARATION.md

@@ -0,0 +1,112 @@
+# Raw ImageNet inventory and complete decode candidate
+
+Local implementation only. No production ImageNet image, Qwen encoder/cache,
+checkpoint, native allocation, deployment or remote job was certified here.
+The sealed image-adapter-candidate-v1 is unchanged.
+
+## Public API and CLI
+
+Publish `source/egomimic/rldb/imagenet_preparation.py` as
+`egomimic/rldb/imagenet_preparation.py` and
+`source/scripts/data/verify_imagenet_images.py` as
+`scripts/data/verify_imagenet_images.py`. The module imports the exact sealed
+adapter's `_decode_rgb160`, hard-pins its module SHA256
+`b43103a338b1cb732c1db6d3c07516699c162a9517f2212cc648948d9d93d737`, and
+records Pillow version plus the complete existing preprocessing contract.
+No Qwen cache or model is required by `inventory-decode`. Importing the shared
+adapter requires its existing CPU Python dependencies; it does not construct or
+load a model. Run only in a genuinely allocated CPU producer through the separately
+reviewed source/runtime/native/host guards.
+
+```
+python scripts/data/verify_imagenet_images.py inventory-decode \
+  --train-root /coc/dataset/ImageNet/train \
+  --val-root /coc/dataset/ImageNet/val \
+  --train-sidecars ACTUAL_SIDECAR_RECIPE.json \
+  --train-sidecars-sha256 ACTUAL_RECIPE_SHA256 \
+  --output FRESH_RAW_INVENTORY.json
+```
+
+CLI counts are fixed to 1,000 WNIDs in BOTH splits, 1,281,167 TRAIN and 50,000
+official VAL images. API expected-count overrides exist for explicit synthetic
+fixture tests, not to relabel an incomplete production inventory. Both roots must
+be physical absolute sibling directories named `train` and `val`. Root aliases,
+class/file symlinks, unknown sidecars, unexpected extensions and empty/corrupt
+images fail. Every accepted image is opened once, raw-size/hashed and fully
+decoded with the unchanged native resize/crop; each canonical record retains
+`path, wnid, bytes, sha256, rgb160_sha256`. No image/cache writes occur.
+
+The sidecar receipt is an object with exactly
+`schema: imagenet-train-sidecar-exclusions-v1` and `exclusions: [...]`.
+An ordinary exclusion has exactly `name, bytes, sha256`. Only
+`tar_extract_script.sh~` (0 bytes) and `tar_extract_script.sh` (108 bytes) are
+eligible, and their actual size/hash must match. An explicit empty list is legal
+only when no sidecar is present. No optional directory filtering occurs.
+
+For the specifically reported unreadable 108-byte nonconsumed TRAIN script,
+the alternative reviewed recipe is exactly:
+
+```
+{"name":"tar_extract_script.sh","bytes":108,
+ "status":"UNREADABLE_EXCLUDED","uid":ACTUAL_UID,
+ "mode":"ACTUAL_FOUR_OCTAL_DIGITS","mtime_seconds":ACTUAL_FLOOR_MTIME}
+```
+
+The producer actually attempts its no-follow read. Only `PermissionError` with
+errno13 is accepted, and before/after regular-file identity/metadata must match
+the explicit uid/mode/size/mtime recipe. A readable file, another errno, metadata
+change, another name or a symlink fails. The raw report retains the actual read
+attempt outcome and makes NO SHA256 claim for this excluded nonimage sidecar.
+No chmod, deletion or permission changes are performed.
+
+`verify_images(...)` defaults to 4 threads and at most 16 submitted futures;
+canonical ordered consumption avoids eager executor.map over 1.33 million rows.
+Directory identity/mtime is rechecked after the complete scan. The portable
+content digest excludes physical roots and timestamps; physical roots, excluded
+sidecar provenance, concurrency and external native/host requirements remain
+separate report metadata. Later normal dataset reads still verify raw file SHA.
+
+## Immutable outputs and failure
+
+An exclusive `.intent.json` consumes the namespace before inventory work. An
+exclusive fsynced `.progress.jsonl` records bounded progress and failure. A
+failure writes `.failure.json`; no retry or cleanup is automatic. A completed
+fsynced `.payload` is atomically hardlinked no-clobber to the requested report,
+and both names are retained. A failure receipt invalidates even a final report
+published before a later I/O failure. Existing intent/output/journal/failure/
+payload names reject. External host/native success must also be bound before
+any downstream admission; `PASS_IMAGE_BYTES_AND_DECODE_ONLY` is explicitly
+`data_admitted: false` and never an allocation or training readiness certificate.
+
+## Later class-language join
+
+```
+python scripts/data/verify_imagenet_images.py join-language \
+  --raw-report ACTUAL_RAW.json --raw-report-sha256 ACTUAL_RAW_SHA256 \
+  --class-language ACTUAL_CLASSES.json --class-language-sha256 ACTUAL_CLASSES_SHA256 \
+  --language-features ACTUAL_QWEN.json --language-features-sha256 ACTUAL_QWEN_SHA256 \
+  --output FRESH_MANIFEST.json
+```
+
+`join_raw_inventory(...)` revalidates the actual raw-report SHA/schema/content
+digests/provenance and exact actual class-name/Qwen bindings, then projects image
+rows to the SEALED adapter's exact `imagenet-imagefolder-manifest-v1` DATA_SCHEMA
+without adding unrecognized fields. It does not stat/read/hash/decode any source
+image or reopen the physical dataset roots. It returns a separate join receipt
+retaining raw-report SHA and class/Qwen/manifest bindings, with
+`images_rehashed_or_decoded: 0` and `data_admitted: false`.
+
+Raw producer, join and eventual training runtime must use the same pinned Pillow
+version and exact adapter module; a cross-cluster decoder-version mismatch fails
+closed and must not be relabelled. Actual allocated CPU byte/decode producer
+source/claim/host/native proof, language encoder proof, data staging, ImageNet
+specific smoke/full admission and actual 4-rank GPU smoke remain external gates.
+
+## Local verification
+
+43 focused synthetic CPU tests passed, including unreadable-sidecar rejection
+cases, bounded submission, alias/corrupt/count failures, retained provenance and
+join with all image read/decode calls forbidden. The tests use the sealed
+`tests/imagenet_native/imagenet_fixture.py`; synthetic vectors are never claimed
+as actual Qwen output. Python 3.10 grammar is checked separately. See the dated
+validation receipt and publication path map for exact bytes.