# Typed High-Resolution Appearance State Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
> (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use
> checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add an optional doubled-resolution, evidence-residual RGB field while preserving the
accepted geometry state, fixed renderer, legacy checkpoints, and target-independent encoder.

**Architecture:** `StateAppearance` stores deterministic high-resolution evidence plus a bounded
completion residual. The evidence encoder constructs it only when `appearance_resolution_scale=2`,
and the existing renderer samples its reconstructed color for RGB while all other measurements keep
using native typed fields.

**Tech Stack:** Python 3.11, PyTorch 2.7+, pytest, Ruff, YAML, existing MCSS CLI.

## Global Constraints

- Do not pass target cameras or labels into `EvidenceResidualStateEncoder`.
- Keep geometry resolution `[48, 32, 48]`, fixed local bounds, and 64 ray samples unchanged.
- Preserve V4 configs, checkpoints, outputs, evidence fields, and all legacy behavior.
- Create only V5 output directories and retain the sealed final holdout.
- The directory has no Git repository; use the timestamped pre-change backup.

---

### Task 1: Typed Appearance And Strict Configuration

**Files:**
- Modify: `src/mcss/types.py`
- Modify: `src/mcss/model/system.py`
- Modify: `src/mcss/config.py`
- Test: `tests/test_types.py`
- Test: `tests/test_config.py`

**Interfaces:**
- Produces: `StateAppearance` and optional `SceneState.appearance`.
- Produces: `ModelConfig.appearance_resolution_scale: Literal[1, 2]`.

- [ ] Add failing tests for appearance shape/range/provenance validation, exact color
  reconstruction, `.to()` transfer, legacy default scale one, explicit scale two, and rejection of
  scale two with the legacy architecture.
- [ ] Run the focused tests and verify failures identify the absent contract and config key.
- [ ] Implement `StateAppearance`, append `SceneState.appearance`, and parse the strict model key.
- [ ] Run the focused tests and require them to pass.

### Task 2: Fixed Renderer Appearance Sampling

**Files:**
- Modify: `src/mcss/measurements.py`
- Test: `tests/test_measurements.py`

**Interfaces:**
- Consumes: optional `SceneState.appearance`.
- Produces: RGB sampled from `appearance.color` without changing any other measurement.

- [ ] Add a failing renderer test with identical density and native color but a doubled-resolution
  red appearance field; assert RGB changes while depth is exact and appearance gradients are finite.
- [ ] Run the focused test and verify it fails because the renderer ignores appearance.
- [ ] Select the appearance color volume only at the `_sample_volume` RGB boundary.
- [ ] Run the focused renderer tests and require them to pass.

### Task 3: High-Resolution Evidence Completion

**Files:**
- Modify: `src/mcss/model/evidence_encoder.py`
- Modify: `src/mcss/model/system.py`
- Test: `tests/test_evidence_encoder.py`
- Test: `tests/test_model.py`

**Interfaces:**
- Consumes: `appearance_resolution_scale` and native completion hidden state.
- Produces: doubled deterministic evidence fields and bounded high-resolution color residual.

- [ ] Add failing tests for doubled shapes, exact reconstruction, zero residual initialization,
  evidence invariance after optimizer update, bounded residuals, finite backward, and scale-one
  absence.
- [ ] Run the focused tests and verify expected failures.
- [ ] Implement high-resolution projection/evidence construction and a compact lifted-hidden 3D
  residual head whose final convolution is zero initialized.
- [ ] Run focused encoder/model tests and require them to pass.

### Task 4: Regularization, Telemetry, And V5 Configs

**Files:**
- Modify: `src/mcss/engine.py`
- Modify: `scripts/cuda_smoke.py`
- Create: `configs/hypersim_er_v5_appearance2x_smoke.yaml`
- Create: `configs/hypersim_er_v5_appearance2x_mainres_smoke.yaml`
- Create: `configs/hypersim_er_v5_appearance2x_probe.yaml`
- Create: `configs/hypersim_er_v5_appearance2x_overfit.yaml`
- Create: `configs/hypersim_er_v5_appearance2x_train.yaml`
- Create: `configs/hypersim_er_v5_appearance2x_val.yaml`
- Modify: `README.md`
- Test: `tests/test_evidence_encoder.py`

**Interfaces:**
- Produces: appearance rewrite regularization and `state/appearance_*` JSONL telemetry.
- Produces: isolated smoke, probe, overfit, train, and validation commands.

- [ ] Add failing regularization/telemetry assertions for appearance precedence.
- [ ] Implement appearance-aware color rewrite penalty and scalar logs.
- [ ] Extend CUDA smoke with one scale-two fixed-model case.
- [ ] Add V5 configs with unchanged data protocol and isolated output directories.
- [ ] Document the exact smoke, probe, overfit, train, and validation commands.

### Task 5: Verification And Handoff

**Files:**
- Verify all modified and created files.

**Interfaces:**
- Produces: a runnable V5 overfit command, not a main-run recommendation.

- [ ] Run all focused tests, then `uv run pytest -q` with zero failures.
- [ ] Run `uv run ruff check .` with zero errors.
- [ ] Compile every Python file below `src` and `scripts`.
- [ ] Run CPU synthetic train/evaluate smoke and the complete CUDA smoke.
- [ ] Run the V5 main-resolution smoke and short real one-window probe.
- [ ] Inspect fresh logs for finite gradients, stable evidence, appearance residual activity, loss
  reduction, runtime, and peak memory.
- [ ] Stop before the 5,000-step overfit and give Kenny its exact command.