Two-agent interaction / object hand-off scenario with ground-truth possession labels

[bamdadd]

Rationale

The benchmark can generate operators placing items, but it cannot yet stage the core multi-agent primitive an exchange/interaction detector needs: two entities converge, a carried object transfers from one to the other, then they diverge — with ground truth for when the transfer happened and who possessed the object at each frame. Exchange/interaction detection across cameras is a high-value multi-camera perception task, and today there is no scene that produces the labels to score it.

This is the producer side of a cross-repo pair: multicam-occlusion will score two-actor exchange detection (see its companion "interaction under occlusion" issue) and consumes the manifest + sidecar this scenario emits.

What to build

A scene recipe / builder that stages two agent entities on converging then diverging paths, one carrying an object entity that changes hands at a defined hand-off frame, plus a ground-truth channel recording the interaction event and per-frame object possession.

Acceptance criteria

• A builder (e.g. examples/handoff.py or a recipes/ entry) produces a Scene with two agent entities and one object entity, converging -> hand-off -> diverging over the frame range.
• Ground truth records: the interaction event (frame/time, giver id, receiver id, object id) and per-frame possession (object id -> holder entity id, or None when in-flight/unheld).
• Additive only. The GT rides in a sidecar (following the order.py OrderResult / ActionEvent precedent), not in the analytic manifest. The existing byte-golden manifest for any pre-existing scene stays byte-identical. New GT is opt-in.
• Possession is consistent with geometry: while held, the object's world point tracks the holder; the hand-off frame is the single frame where the holder id changes.
• Round-trips to JSON via pydantic model_dump and reloads without loss.
• A test asserts the possession timeline and interaction event against the constructed scene.

Files / data model to extend

• src/multicam_sim/entities.py — Entity / EntityFrame (named-points contract; the object is an entity with a center point).
• src/multicam_sim/order.py — the established sidecar pattern (OrderResult, ActionEvent); model the interaction/possession sidecar on this.
• src/multicam_sim/scene.py — Scene container.
• Example precedent: examples/assembly_station.py.

Open design note

Whether per-frame possession is best expressed as a new sidecar model vs. an opt-in field is left to the maintainer; the byte-golden constraint above holds either way.