mutable_agent_state.007

-- SPDX-License-Identifier: MPL-2.0
-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
--
-- Example: mutable agent state via `set <field> = <expr>`.
--
-- Agent handlers used to receive a *copy* of agent state with no write-back,
-- so state was effectively immutable. `set` assigns to a declared `state`
-- field and the assignment PERSISTS into the agent instance — a later handler
-- firing observes the new value. This is the runtime substrate the L10
-- rung-3b echo-residue cell builds on.
--
-- Static discipline (type checker):
--   * `set <field>` requires <field> to be a declared `state` of THIS agent
--     (assigning a `let`/param/undeclared name is the `SET_NON_STATE` error);
--   * the value's type must match the field's declared type.

agent Counter {
    -- A mutable accumulator, declared with its type and initial value.
    state total: Int = 0

    control {
        -- Each received amount reads the current `total` and writes it back
        -- incremented — the read-modify-write that immutability disallowed.
        on receive(amount: Int) {
            set total = total + amount
        }

        -- A different handler clears the same persistent state by assigning a
        -- literal. Because state is carried through the agent instance, this
        -- reset is observed by subsequent `receive` firings (cross-handler).
        on reset(ignored: Int) {
            set total = 0
        }
    }
}