MovementResult
in package
Immutable summary of one flow execution.
Tags
Table of Contents
Properties
- $events : array<string|int, mixed>
- $remaining : int|float
- $trace : array<string|int, mixed>|null
Methods
- __construct() : mixed
- applyTo() : QuantityState
- Return a copy of the given quantity state with this result's net deltas applied.
- deltas() : array<int, QuantityStateDelta>
- Aggregate per-slot quantity-state deltas for this result.
- isComplete() : bool
- Return true when the requested quantity was fully satisfied.
- ledgerEntries() : array<int, LedgerEntry>
- Convert each movement event to a ledger entry.
- trace() : array<int, array<string|int, mixed>>|null
- Return the per-step decision trace, or null when the solver was not collecting one.
Properties
$events read-only
public
array<string|int, mixed>
$events
$remaining read-only
public
int|float
$remaining
$trace read-only
private
array<string|int, mixed>|null
$trace
= null
Methods
__construct()
public
__construct(array<int, MovementEvent> $events, int|float $remaining[, array<int, array<string|int, mixed>>|null $trace = null ]) : mixed
Parameters
- $events : array<int, MovementEvent>
- $remaining : int|float
- $trace : array<int, array<string|int, mixed>>|null = null
-
per-step decision record, when the solver was asked for one
Tags
applyTo()
Return a copy of the given quantity state with this result's net deltas applied.
public
applyTo(QuantityState $state) : QuantityState
Execution computes movement without touching the state it was handed, so applying a result is an explicit step the caller takes when it wants the resulting state rather than the ledger. The input is left untouched, which is what makes a result safe to hold, inspect, compare against alternatives, or discard.
Parameters
- $state : QuantityState
Return values
QuantityStatedeltas()
Aggregate per-slot quantity-state deltas for this result.
public
deltas() : array<int, QuantityStateDelta>
The output is stable in first-seen slot order, which makes it suitable for deterministic persistence and testing.
Return values
array<int, QuantityStateDelta>isComplete()
Return true when the requested quantity was fully satisfied.
public
isComplete() : bool
Return values
boolledgerEntries()
Convert each movement event to a ledger entry.
public
ledgerEntries([array<string, mixed> $context = [] ]) : array<int, LedgerEntry>
Parameters
- $context : array<string, mixed> = []
Return values
array<int, LedgerEntry>trace()
Return the per-step decision trace, or null when the solver was not collecting one.
public
trace() : array<int, array<string|int, mixed>>|null
Answers "why did it move that" — and, more often, "why did it move nothing". Each step
records its candidate edges, what the filters and ordering did to them, and per edge the
three numbers that separate the usual causes: available (what the source held),
movable (what survived the quantity constraints) and moved (what the remaining quantity
actually took). Zero available means an empty source; available above zero with movable at
zero means a policy capped it; movable above zero with moved at zero means the request was
already satisfied.
Collection is opt-in, since a trace costs memory per step and most executions never look at
one: new MovementEngine(new GreedyFlowSolver(trace: true)).