RuView ADR-323: Physics-constrained pose refinement in native Rust

RuView now has an audit-first physics boundary between RF pose inference and semantic publication. The implementation was merged in RuView PR #1617 as merge commit 1d50518a7.

The short version is:

Physics may identify inconsistency, reduce confidence, abstain, or propose a tightly bounded correction. It may never turn a weak RF observation into stronger evidence merely because the result looks physically plausible.

The full decision is ADR-323: Native Rust physics-constrained pose refinement.

Why RuView needs this boundary

RF pose models can emit frames with inconsistent limb lengths, sudden joint motion, floor penetration, impossible joint angles, or stale temporal state. A renderer can smooth those defects, but smoothing alone creates a dangerous failure mode: a wrong pose can look polished and authoritative.

ADR-323 introduces an explicit separation between:

Observed state: what the RF model actually produced.
Derived state: a result computed from the observation and declared constraints.
Hypothesis: an unmeasured possibility such as likely foot contact.
Unknown: insufficient evidence for a defensible result.

The raw observation remains immutable and addressable by a canonical content hash. Downstream systems can always distinguish the original evidence from an assessment or candidate correction.

Where it sits

RF sensors
    |
    v
RF pose observer ---- model identity, uncertainty, trust state
    |
    | immutable PoseObservationV2
    v
wifi-densepose-physics
    |-- contract and input validation
    |-- deterministic kinematic audit
    |-- bounded position-based projection
    |-- optional Rapier dynamics audit
    `-- optional Burn residual model
    |
    | PoseRefinementV1: assessment + optional candidate + provenance
    v
sensing server / Cog publisher
    |
    +-- raw view
    +-- raw + assessed view
    `-- selected refined view, only after independent gates pass

The physics crate does not ingest CSI, assign identities, select RF models, manage HTTP, retrieve artifacts from a network, or publish alerts. Those responsibilities remain in their existing bounded contexts.

The two public contracts

`PoseObservationV2`

The canonical input contains:

monotonic timestamp, sensor epoch, sequence, and session-scoped track ID;
17 COCO joints in a declared coordinate frame;
per-joint covariance, confidence, and visibility;
model and sensor provenance;
calibration and optional floor-plane identity;
dimensionality (Image2d or metric 3D);
RF trust state;
a deterministic BLAKE3 canonical hash.

Metric 3D correction requires a right-handed, Z-up, metre-based room frame, calibrated uncertainty, a trusted floor plane, and authenticated replay-safe source evidence.

Existing 2D pose output is handled honestly: it can be audited for image-plane bounds and temporal behavior, but it cannot enter the 3D projector or be labelled physically corrected.

`PoseRefinementV1`

Every accepted frame gets exactly one result, including when physics is disabled, times out, rejects the input, or abstains. The result carries:

the original observation hash;
rollout mode and typed disposition;
optional refined joints;
physics and effective confidence;
raw and candidate residuals;
correction magnitude and solver iterations;
contact hypotheses;
engine/configuration/model provenance;
a typed abstention reason;
its own deterministic result hash.

There is no silent frame drop and no silent fallback that labels raw output as refined.

The JSON schemas are published with the repository:

Deterministic kinematic layer

The default crate feature is a native Rust auditor and bounded position-based projector using nalgebra. It checks or constrains:

track-specific bone-length consistency;
broad anatomical joint-angle limits;
covariance-weighted velocity and acceleration;
temporal continuity and frame gaps;
penetration of the calibrated floor plane;
foot-contact hypotheses without pretending contact was measured;
correction magnitude, solver iterations, elapsed time, and track-store size.

The internal skeleton keeps COCO17 at the API boundary and derives virtual pelvis and thorax joints for kinematic calculations. Bone lengths use an anonymous track-scoped robust posterior initialized only from sufficiently confident frames. The posterior is memory-only and expires with the track.

The projector uses covariance to decide which joints may move: a low-certainty joint can move more than a high-certainty one. Every correction is still subject to hard per-joint and root caps. A candidate beyond those caps is discarded and the result abstains.

The engine does not contain an upright prior. Sitting, kneeling, child-scale poses, mobility aids, prone poses, and genuine falls are valid states. Floor handling prevents penetration; it does not stand a person up.

Confidence cannot be manufactured

If c_obs is calibrated observer confidence, r is normalized physical residual, and i is normalized intervention magnitude:

c_physics   = exp(-(beta_r * r + beta_i * i))
c_effective = min(c_obs, c_obs * c_physics)

Therefore:

0 <= c_effective <= c_obs <= 1

Physics can lower or preserve effective confidence. It cannot increase observational confidence. A future independent sensor may increase fused confidence only through a separate witnessed sensor-fusion contract.

Rollout modes and authorization

Mode	What happens	Can a candidate be selected?
`off`	Return a typed bypass result	No
`audit`	Validate and report residuals without projection	No
`shadow_correct`	Compute a bounded candidate for evaluation	No
`opt_in_correct`	Publish raw and candidate for an explicitly approved consumer	Only with evidence and frame receipts
`default_correct`	Select refined visualization by default	Only after the final rollout gate

Correction authority is deliberately difficult to obtain. The engine requires both:

a release-evidence receipt bound to the exact physics configuration hash; and
a per-frame receipt bound to the raw hash, sensor epoch, sequence, sensor identity, and calibration.

Calling the ordinary processing API cannot select a corrected pose. Mode changes are atomic, and switching to off clears temporal state without restarting the server.

Optional Rapier dynamics audit

The dynamics feature adds a persistent articulated Rapier world per track. It builds bounded capsule segments, spherical joints, a floor collider, fixed substeps, and proportional-derivative tracking. It reports:

tracking and joint-anchor error;
contact count;
floor penetration;
control effort;
numerical stability.

This layer is audit-only. Rapier state and snapshots are process-owned and are never accepted from network input.

Optional Burn residual model

The learned boundary implements a two-layer GRU with a 20-frame history and hidden width 128. Its inputs include raw joints, covariance, deterministic residuals, temporal features, floor-relative geometry, RF trust/coherence, and an optional RF embedding. Separate heads emit:

bounded joint residuals;
residual log variance;
left/right contact hypotheses;
abstention probability.

The learned residual is tanh-bounded and cannot bypass deterministic limits or the confidence invariant. Artifacts are hash-addressed, size-limited, and verified before deserialization.

No trained model is being selected in production. The resolved Burn/CubeCL graph also requires Rust 1.92, while the repository release toolchain is older, so standard activation remains blocked until the toolchain is deliberately upgraded and revalidated.

Cargo feature boundary

[features]
default = ["kinematic"]
kinematic = []
dynamics = ["dep:rapier3d"]
learned = ["dep:burn-core", "dep:burn-nn"]
learned-cpu = ["learned", "dep:burn-ndarray"]
learned-train = ["learned", "dep:burn-train"]
learned-wgpu = ["learned-train", "dep:burn-wgpu"]
learned-cuda = ["learned-train", "dep:burn-cuda"]
deterministic = ["rapier3d?/enhanced-determinism"]

The default edge build does not pull in Rapier, Burn, ONNX Runtime, Tch, Python, CUDA, or a network client.

Server and Cog behavior

The sensing server publishes additive physics data and supports:

GET /api/v1/pose/current?view=raw
GET /api/v1/pose/current?view=both
GET /api/v1/pose/current?view=refined
GET /api/v1/pose/physics/metrics

view=refined returns a typed HTTP 409 if no selected refined result exists. It does not return raw data under a refined label.

The current live pose Cog emits its actual normalized 2D output as Image2d, with degraded trust and uncalibrated uncertainty. That output enters the audit path but is structurally unable to activate 3D correction. This is intentional: the physics layer does not pretend the current observer has depth or uncertainty evidence that it does not have.

Backpressure retains the newest pending frame per track, bounds active tracks, drops intermediate refinement work rather than raw observations, and resets temporal derivatives after excessive gaps.

Privacy and security properties

unsafe Rust is forbidden in the physics crate.
Inference adds no network access.
Fixed-size or capped structures bound allocation and solver work.
NaN, infinity, invalid covariance, stale frames, replay conflicts, unknown frames, and inconsistent coordinate systems produce typed rejection or abstention.
Metrics contain scalar residuals and counts, not joint arrays, room coordinates, raw CSI, body dimensions, or persistent identities.
Track-scoped body posteriors are memory-only and expire with the track.
Raw observation and refinement hashes make provenance and replay comparison explicit.

Validation completed for the merge

The implementation includes unit, property, schema, golden replay, strict-split, integration, feature-boundary, benchmark, and fuzz-build coverage. The merge CI reported:

44 checks passed;
5 checks skipped by workflow conditions;
Rust workspace tests passed twice on the push and pull-request runs;
benchmark compilation and informational fast benchmarks passed twice;
Docker, Python 3.10/3.11/3.12, MQTT, secret, license, SAST, dependency, infrastructure, and UI checks passed.

One ADR-299 CSI-data-policy check failed because six legacy raw CSI recordings are already tracked on main. ADR-299 explicitly records that incident and requires data-owner approval before destructive tree/history remediation. ADR-323 did not add or modify those recordings, and the merge was explicitly authorized with that known pre-existing failure.

Local performance evidence

On the authoring Windows x86_64 host (Intel Core Ultra 9 285H, Rust 1.91.1), a warm one-track deterministic shadow probe measured 20,000 iterations:

Metric	Result
p50	0.0071 ms
p95	0.0084 ms
p99	0.0147 ms
max	1.5994 ms

This is MEASURED local-host evidence, not Raspberry Pi 5 evidence. It excludes transport, publication, resident-memory change, dynamics, and learned inference. The append-only source ledger is physics-pose-refinement.md.

What is not being claimed

Merging ADR-323 does not mean physics correction is production-approved or state of the art. It does not improve RF observability by itself, turn 2D into 3D, infer measured force, repair a weak observer, diagnose biomechanics, certify fall detection, or provide a safety case.

Correction remains gated on evidence that cannot be manufactured in source code:

a released metric-3D observer with calibrated per-joint covariance;
subject-, room-, hardware-, and session-disjoint RF plus optical ground truth;
positive held-out MPJPE, foot-slide, jerk, calibration, and fall-preservation results;
Pi 5 latency and memory measurements;
24-hour accelerated replay and the scheduled 100-million-case fuzz gate;
authenticated sensor identity and replay protection;
opted-in shadow deployments followed by thirty days of operational evidence.

Until those gates pass, audit is the correct production state. That is a feature of the design, not an unfinished fallback.

ruvnet/ADR-323-RuView-Physics-Pose-Refinement.md

Select an option

No results found