IntermediateValidated 1.0.0

Actions, transactions, and events

An action is validated as a complete plan and then either commits all of its changes or leaves the board unchanged.

Action, plan, and commit

An IGridAction describes intent. A plan captures validated mutations and events against one or more source revisions. A commit consumes that plan once, applies every mutation, advances only the boards that changed, and publishes only the batches that contain committed facts.

First placement example

The first action tutorial resolves the authored first-board.crate definition, then previews placing the instance first-board.crate-1 at (1, 1). Preview succeeds while revision remains 0. Applying the action validates again, writes occupancy, advances revision to 1, and publishes one batch containing the placement event. A rejected placement would leave revision and occupancy unchanged.

Rules that keep changes atomic

Preview and planning do not mutate state or publish committed events.
Preview does not reserve board state; a later commit can make its result stale.
A plan is board-specific, revision-specific, and single-use.
All mutation commands validate before the first live write.
An application failure rolls applied commands back in reverse order.
Rejected and rolled-back operations do not advance revision or publish a batch.
Subscriber exceptions are diagnostic failures; they cannot undo a completed commit.

Successful outcomes

Not every successful plan changes state. Use the result, revision, and committed batch for their separate purposes:

Successful outcome	Revision	Event batch
No mutations and no events	Unchanged	None
Events only	Unchanged	Published
One or more mutations	Advances once for each mutated board	Published for each mutated board
Snapshot restoration	Advances once, including an identical restore	Publishes the restoration event

In a multi-board operation, an event-only board publishes its own batch without advancing its revision. A board that has neither mutations nor events publishes nothing. Snapshot restoration is the intentional exception to ordinary mutation detection: applying a valid snapshot represents a new restoration commit even when its values match the live state.

Preview and commit sequence

sequenceDiagram
    accTitle: Action preview and atomic commit sequence
    accDescr: The game previews an action without mutation, then applies a validated plan and conditionally advances revisions and publishes committed event batches according to its mutations and events.
    participant G as Game
    participant R as Action runner
    participant P as Plan
    participant S as Board state
    participant O as Observer
    G->>R: Preview or BuildPlan
    R->>P: Capture revision + mutations
    P-->>G: Result (state unchanged)
    G->>R: Apply
    R->>S: Validate and commit atomically
    opt Board has mutations
        S->>S: Advance revision
    end
    opt Board has mutations or events
        S-->>O: GridBoardEventBatch
    end

Events and visuals stay separate

Events are committed facts, not mutation requests. Visual intents are transient presentation and do not belong in the action event stream.

Table of Contents