Class GlobbableApi

Walk candidates in scored order, distributing quantity across matches. Non-globbable matches contribute 1 unit each; globbable matches contribute up to their full getQuantity(). The action callback runs per operand with the contribution applied.

See docs/subsystems/glob.md § GlobbableApi.applyQuantity for the full contract.

Behavior:

• Empty candidate list: immediate { ok: false, status: 'declined' } with an empty-result note. No actions run.
• Strict pre-check (mode: 'strict', kind: 'count'): sum(units(c) for c in candidates) < n → immediate decline with quantity-clamped-rejected. No actions run.
• All-kind: act on every candidate at its full contribution; no clamp.
• Count-kind: walk in scored order; for each candidate contribution = min(units(c), remaining). Split when the candidate is globbable and contribution < c.getQuantity(), else operand = c.
• Action ok:false: emit a target-declined note (target = the candidate, not the operand); if a split occurred, merge the operand back into c (reglob); continue the walk; remaining is unchanged.
• Lenient overflow (mode: 'lenient', count kind, remaining > 0 after walk): emit quantity-clamped; status 'partial'.
• Status rule: 'partial' when any progress was made (any successful action) AND something diverged (target-declined or clamp); 'declined' when applied === 0; absent on a clean run.

Throw propagation (G5): if the action throws, the helper does NOT catch — the throw propagates. Partial state may be left in place (a successful split with no reglob). The controller's outer error handler is responsible.

Symmetric kind-equality check used by both the merge-on-arrival ripple in ContainmentApi.move and the explicit GlobbableApi.merge happy path. Defers to the host's canMergeWith (the shadow-friendly seam); falls through to false for non-Globbable peers.

Fold absorbed into survivor. Validates both are Globbable and that survivor.canMergeWith(absorbed) returns true. Increments the survivor's quantity, destructs the absorbed Stuff (which fires its own onDestruct chain — that's where "this Stuff is going away" subscribers belong), then fires survivor.onMerged(absorbed).

merge itself emits no movement events. Used by:

• The merge-on-arrival ripple in ContainmentApi.move (after the arrival's onContainableAdded has fired, so subscribers see the arrival before the destruct).
• The reglob path inside applyQuantity when an action returns { ok: false } after a split.

Split n units off source into a new Stuff. Semantics:

• Validates n is a positive integer ≤ source.getQuantity(). Programmatic-contract violation throws.
• Runs source.canSplit(n) (shadow seam). Veto throws.
• Whole-stack short circuit: when n === source.getQuantity() returns source itself. The caller is going to move the whole stack; a no-op split avoids the clone churn and matches the slate's "destruct-on-zero" rule (no orphan splitoff to clean up).
• Otherwise: clones a fresh Stuff at source.getTemplatePath(), copies every globIdentityFields value over, sets quantities (splitoff = n, source = M - n), placeDirects the splitoff into source's environment (no arrival witnesses), and fires source.onSplit(splitoff).

placeDirect is what makes split silent on movement events — subdividing matter already in the room is not the same as matter arriving there. See docs/subsystems/glob.md § GlobbableApi.split.