Deterministic execution

The property

Given the same observation frame, the same resolved manifest and the same goal, the local planner produces the same plan. It is seeded, and it does not consult wall-clock time, unsynchronised state or any source of entropy you have not declared.

What it buys you

• Tests that mean something. A scenario can be run a thousand times and assert on the trace instead of on timing.
• Replayable incidents. A recorded frame and goal reproduce the decision that caused a problem.
• Reviewable behaviour. Two people can look at the same plan and agree on why it was produced.

What breaks it

The runtime cannot restore a property you have removed. In practice, the causes are:

• Reading os.clock(), os.time() or a random value inside observe without declaring it as an observation field.
• Observing state that is replicated asynchronously and may differ between ticks for reasons outside the frame.
• Mutating world state from outside the runtime in the middle of a tick.
• Enabling external evaluation — see below.

External evaluation

External evaluation is the only sanctioned source of non-determinism, it is opt-in, and disabling it restores reproducibility exactly. It is bounded by a timeout you set, and on expiry the deterministic planner continues alone.

-- External evaluation is opt-in, redacted, and advisory.
Runtime.configureEvaluation({
    enabled = true,
    provider = "your-provider",

    -- Only these observation fields ever leave the server.
    expose = { "inbound_queue.depth", "weather.state", "berth.availability" },

    -- The provider returns a proposal. It is validated like any other input.
    accepts = { "goal_ranking" },

    -- If it is slow or unavailable, the deterministic planner continues alone.
    on_timeout = "fall_back_to_local",
    timeout_ms = 400,
})

Note what the provider cannot do: it holds no capability, it cannot move resources, and it cannot reach the commit. Its output re-enters at validation and is checked exactly like a locally generated plan.

Ticks and frames

Observation is collected once per tick and frozen. Every actor deciding in that tick sees a consistent view, and a plan is never built against state that moved while it was being built. Resource reservations made during the tick are visible to the ledger immediately, which is how contention resolves without the frame having to change.