Add offline uncertainty inference with exact conditioning and joint forecasts

docs/uncertainty/articulated-replay.md

@@ -0,0 +1,46 @@
+# Articulated state in offline replay
+
+September 12, 2026.
+This fixes a missing state component in the [simplification replay contract](simplification-proposal.md#1-establish-the-state-and-replay-contract).
+The production fitter and acting agent are unchanged.
+
+## Reproduction and correction
+
+The original `ReplayState` preserved every robot joint but omitted nonrobot joint states.
+Replaying a candidate could therefore replace an uncertain slider position with its controller endpoint and reset a rotor's position and velocity to fresh-world defaults.
+Repeated runs could agree perfectly while both discarded the same candidate uncertainty.
+
+The [pre-fix native reproduction](../../logs/uncertainty_articulated_replay_repro_20260912/pilot-22639384_1.json) exercises `capture_replay_state` followed by `replay_candidate` with the frozen learned Fan simulator and reconstructed public initial frame.
+It supplies nonendpoint positions and nonzero velocities to the four sliders and twenty rotors.
+All 24 differ after restoration, consistently across two fresh worlds.
+For example, one slider changes from position 7.4 mm and velocity 20 mm/s to zero position and velocity.
+This is a diagnostic candidate, not a complete physical initial-state prior or an agent result.
+
+[ReplayState](../../predicators/code_sim_learning/inference_replay.py) now carries an `ArticulatedBody` record for every nonrobot native body with joints, including bodies omitted from public object keys.
+Each record includes native body ID, body names, joint names/types/link names, and every joint's position and velocity in native order.
+Restoration verifies the complete record sequence against the fresh world's layout after domain initialization, then restores the supplied joint states after the controller reconciliation performed by `_set_state`.
+Missing or duplicate bodies, differing layouts, incomplete joint arrays and nonfinite joint values raise an explicit error.
+These values come from the simulated candidate or an evaluator-only mechanical audit, never from an added agent observation channel.
+
+The native IDs require the same body-allocation protocol as the source candidate.
+Names and joint topology detect mismatches; they are not a semantic remapping algorithm or a proof that interchangeable identical assets were allocated in the same order.
+The existing runtime-identity and same-layout requirements therefore remain necessary.
+This change does not capture solver warm starts, arbitrary motor-controller changes or every other form of engine history.
+Use full-prefix reconstruction for continued contact histories and continue to distinguish repeatable candidate replay from agreement with evaluator physics.
+
+## Validation
+
+The [fixed native audit](../../logs/uncertainty_articulated_replay_fixed_20260912/pilot-22639468_1.json) restores all 24 supplied joint states exactly.
+It also repeats the first 64 recorded actions from that candidate in two fresh worlds.
+All 65 boundaries agree exactly in robot joint states, nonrobot joint states and projected public observations.
+This validates the tested candidate and runtime, not an arbitrary portable mid-contact checkpoint or a calibrated Fan posterior.
+
+Compute job `22639455` passes 22 functional replay tests plus focused mypy, pylint and pinned formatting checks.
+The regression includes a supplementary physical fan without a public object, a moving clip slider, repeated continuations and five malformed-state controls.
+Existing tests continue to cover robot motion, model memory, original weld frames, queued commands and full-prefix replay.
+
+The remaining Fan work is to compose supported scene geometry and articulated priors with the complete recording likelihood, then establish numerical and predictive adequacy against the incumbent fitter.
+
+The [whole-scene follow-up](fan-initial-scene.md) has since supplied a declared geometric root law and exposed later exact-event failures over the full recording.
+Runtime addenda for [the reproduction](../../logs/uncertainty_articulated_replay_repro_20260912/runtime-audit.json) and [the fixed audit](../../logs/uncertainty_articulated_replay_fixed_20260912/runtime-audit.json) correct inherited node1412 labels: those jobs actually ran on node1408 and node1926 respectively.
+The measured within-job repeatability claims remain unchanged; the raw artifacts are preserved.

docs/uncertainty/assembly-prior.md

@@ -0,0 +1,84 @@
+# Rigid-assembly initial-state component
+
+September 12, 2026.
+This is an offline component of Stage A in the [uncertainty simplification plan](simplification-proposal.md), implemented in [inference_assembly.py](../../predicators/code_sim_learning/inference_assembly.py).
+It provides normalized candidate distributions for a fixed rigid geometry, including a planar-contact case.
+It is not the historical balloons task prior, a full scene prior, or a deployed agent estimator.
+
+## Why bodies cannot be initialized independently
+
+A weld constrains relative pose and motion.
+Giving attached bodies independent positions can create an inconsistent constraint immediately.
+Copying the parent's linear velocity to an offset child is also incorrect when the assembly rotates.
+For root position `x`, orientation `R`, linear velocity `v`, angular velocity `omega`, and child offset `r` in the root frame, initialize:
+
+```
+child_position = x + R r
+child_linear_velocity = v + omega cross (R r)
+child_angular_velocity = omega
+```
+
+Child orientation composes the root rotation with the declared local rotation.
+The original parent weld frame is that same local pose, and the child weld frame is identity.
+These quantities describe one correlated candidate; they are not independent noisy readings or separately fitted body states.
+During simulation, finite-force engine constraints can deflect, so the exact initial construction does not assert exact rigidity at every later step.
+
+## Explicit geometry and support assumptions
+
+Each `AssemblyBody` declares a name, a fixed pose relative to the root, and a radius enclosing its collision geometry.
+The first body is the root and has identity local pose.
+The caller must establish these geometric facts from its declared model and permitted inputs.
+The API cannot verify arbitrary mesh geometry or infer a free region from noisy observations.
+Privileged weld metadata and evaluator reset states do not supply these declarations.
+
+The caller also declares an axis-aligned obstacle-free cell.
+Pairwise enclosing spheres must not overlap, which conservatively ensures that distinct bodies do not interpenetrate.
+This rejects some physically valid tightly packed assemblies; rejection is an explicit limitation of this component's support.
+The assembly radius about the root is the largest local-center distance plus that body's radius.
+Eroding the cell by that radius supplies normalized uniform bounds for the root center, without candidate-dependent clipping or rejection normalization.
+A cell too small to contain the declared assembly is rejected before sampling.
+This guarantee covers the declared cell and collision envelopes, not undeclared obstacles, robot links, or articulated bodies.
+
+## Three distinct component priors
+
+| Component | Free coordinates | Normalized distribution | Derived quantities |
+| --- | ---: | --- | --- |
+| Free assembly at instantaneous rest | 6 | Uniform root xyz in the eroded cell; uniform orientation on SO(3) | All body poses; zero linear/angular motion; original weld frames |
+| Free moving assembly | 12 | The same pose distribution plus independent uniform root linear and angular velocity components with declared positive half-widths | Correlated child velocities through the shared rigid twist |
+| Assembly on a horizontal support face | 3 | Uniform root xy in the eroded footprint; uniform yaw | Root height, zero roll/pitch, zero twist, body poses and weld frames |
+
+Uniform SO(3) orientation uses a uniform-quaternion construction from three unit-interval coordinates.
+It does not use independent uniform Euler angles.
+`coordinates` returns a normalized `BoxPrior`, and `lift` maps those coordinates into physical body states.
+The generative probability measure is defined on these coordinates and pushed forward through the map.
+There is no extra product of densities over derived child poses or velocities.
+Geometry and prior support are part of the component digest.
+
+For the supported component, `support_depth` declares an actual lowest horizontal root face at local `z = -depth`.
+The root height is exactly the cell floor plus this depth, and only yaw is sampled.
+The root envelope must fit below the cell ceiling, and attached-body enclosing spheres must remain above the support plane.
+The caller must verify the root face against its collision geometry; a bounding radius alone does not establish that face.
+This is geometric contact at instantaneous rest, not a proof of static balance or a guarantee that the assembly will remain upright.
+
+These components do not assign probabilities to one another.
+A complete scene prior must declare their case masses and any dependence on parameters, layout, attachments, and robot state.
+In particular, the supported component is not obtained by projecting a sample from the free component onto the table.
+It is a separately declared distribution on a lower-dimensional contact case.
+The rest components likewise declare atoms in velocity; they do not infer zero motion from missing observations.
+
+## Validation and scope
+
+The tests compare generated states against actual PyBullet collision geometry, compose weld frames independently through Bullet, and compare the velocity map with a finite difference of rigid motion.
+They also check rotational isotropy, explicit dimensions, identity changes, rejected geometry/support, and exact face contact up to engine distance roundoff.
+That geometric comparison tolerance is not a likelihood or added sensor variance.
+
+The separate physical reference generates a box and an attached sphere entirely from this declared model, then simulates gravity and plane contact in fresh worlds.
+Each trial compares an uninterrupted 240-step trajectory with a fresh repeat and a full-prefix reconstruction returning steps 120 through 240.
+It records initial penetrations, contacts, weld deflection, and every nonzero replay difference.
+The references are generated mechanical cases, not historical-domain fits or agent solve-rate seeds.
+See [the experiment record](experiments-20260912.md#rigid-assembly-prior-and-planar-contact-reference).
+
+Before applying this to recorded tasks, define and justify root attachment cases, uncertain relative geometry, valid scene regions, and robot-state priors.
+An exact tied flag does not identify a weld frame, and a noisy pose cannot silently become a geometric prior bound.
+Subsequent exact robot/contact observations still require a valid conditional representation.
+This component supplies one physical building block without bypassing those requirements.