ReviewOS

also looking at this

stacks/drone

feat: model one point-load intake with conserved momentum

#99
Merged chris wants to merge codex/cargo-fleet-custody into main
45 files +3133 -169
docs/adr/0036-point-load-intake.mdadded+53-0
Changes to docs/adr/0036-point-load-intake.md
@@ -0,0 +1,53 @@
1# ADR 0036: One point-load intake for a receiving vehicle
2
3Status: accepted for software simulation.
4
5## Context
6
7Cargo fleet handover needs a physical parcel to leave one carrier, undergo finite modeled
8station handling and enter another carrier's actual dynamics. A custody-label change or
9an initially loaded second vehicle would bypass that mass transfer. The rigid body already
10supports an attached point load and one zero-ejection separation, but had no empty joint.
11
12## Decision
13
14Add `createReceivingRigidBody` over the same integrator, with a captured `expectedPointLoad`.
15Its lifecycle is `awaiting -> attached -> separated`. The initial body has base mass/inertia;
16the planned load is not an actual parcel. A successful intake consumes this one opportunity.
17The old `createRigidBody` constructor still starts attached and exposes no intake method or
18awaiting phase. Its default/no-load numerical paths and result projections remain unchanged.
19
20The receiving joint reports its position and velocity. The incoming parcel record contains
21its own id, mass, position and velocity. Match id/mass exactly and require exact coincident
22binary64 position components at invocation. This is an ideal programmatic contact condition,
23not a sensor tolerance or claim of physical positioning precision. Captured records and
24finite tuple elements reject accessors. Valid refusal or malformed input does not mutate
25the body or consume its intake opportunity.
26
27Let base mass be `m`, point mass `p`, body-forward joint vector `r`, and combined mass `M=m+p`.
28The new body-frame CG is `c=p*r/M`. Combined center velocity is `(m*vBody+p*vParcel)/M`.
29About that center, body-frame angular momentum is base `I*omega` plus
30`m*p/M * cross(r, inverseRotate(vParcel-vBody))`. Dividing by the combined principal inertia
31gives the new angular rate. Reconstruct datum velocity from center velocity and `omega cross c`.
32The joint is on the body x axis, so the existing diagonal parallel-axis inertia is sufficient.
33
34The base and incoming point jointly determine conserved linear/angular momentum. Structural
35position, quaternion and actual motor state remain unchanged. Kinetic energy may decrease;
36retain before/after energy and raw dissipation. Reject non-finite candidates or a gain beyond
37`64 * Number.EPSILON * max(1, kineticBeforeJ, kineticAfterJ)` before committing state. Keep the
38raw represented loss, including tolerated tiny negatives. NED potential is `-mass*g*down`.
39The event reports both potential values separately.
40
41## Consequences
42
43The primitive models an instantaneous inelastic impulse, not contact duration, force peaks,
44parcel spin/deformation, latch actuation or restitution. The retained acceleration is the last
45continuous integration sample, not an invented impact acceleration. A later physics step uses
46the new mass/CG/inertia without resetting the controller, estimator, pose or motor lag.
47
48World/policy code must own and consume the single parcel, admit the physical operation, model
49finite transport to the joint and capture mechanism/vehicle acknowledgement with current
50authority and source epochs. This primitive does not globally prevent a caller from supplying
51the same record to two independent worlds. A joint pose is not a source parcel or proof of custody.
52Station handling and the actual two-vehicle protocol remain unimplemented at this checkpoint.
53No physical output, authenticated identity, battery endurance or fleet completion is claimed.