Interface Containable

Privileged setter — only ContainmentApi.placeOn / ContainmentApi.move may call. Runtime-rejected by the call-security gate otherwise. Authors don't touch this directly; the Api maintains the invariant that restingOn is only non-null when the item's container matches the surface's container.

Pass null to clear (apple lifted off the desk).

Declarative-content applier. Phase 2 of the Hydrator's two- phase dispatch reads data.container from the source template and calls this method with the resolved templatePath. The applier resolves the target via StuffApi.singleton (the target MUST be singleton-shaped — validated at template-save time by TemplateApi.validateSingletonContainerTarget) and moves self into it via ContainmentApi.move.

Per-call idempotency: compare current container's templatePath to the declared path; no-op when they match. The compare-and- move shape supports both fresh-clone placement AND Avatar.restore() re-move semantics with no flag.

Optional pre-move veto on the moving item itself.

Auxiliary support pointer. Set when this Containable is resting on a Surfaced host (e.g., apple on a desk). Orthogonal to getContainer() — the apple is in the room AND resting on the desk; both relationships are real.

Null when the item is not on a surface (in a container, in inventory, in an actor's grip, freely in a room).

Runtime-only (Pattern B live ref; see docs/ref-shapes.md). Not persisted: on server restart, the apple's container is preserved but its on-surface relationship resets. The tradeoff is intentional — Pattern A by templatePath only resolves unambiguously for singleton surfaces, which would constrain the natural sandbox case of multiple identical chairs / tables authored in a single area. When sandbox content earns cross-restart on-surface persistence, that build picks the appropriate persistence shape (likely Pattern B with stuffId stamping at save time).

Walk the container chain to the topmost non-null environment. Returns null when this Stuff is already at the root (its own getContainer() is null) — the caller decides whether "I am the root" should be treated as the result or as no-op.

Counterpart to ContainerMixin.getDeepContents() — both side helpers for "walk all the way" navigation. Used by MQL's :E transform; equally available to controllers that want to find the world / zone / outermost room without rolling their own loop.

Fired after the item has moved. Either from or to may be null for first-placement / final-detach edges. Single hook covers every transition — no separate "placed" / "removed" methods on the item side.