api/dev.s7a.strata.state/StateObservation

StateObservation

class StateObservation(beforeMutation: () -> Unit, afterMutation: () -> Unit, invalidated: () -> Unit, validateMutation: () -> Unit) : AutoCloseable(source)

Runtime-owned dependency set for one owner-confined screen evaluator. Successful evaluation replaces dependencies; failed evaluation retains them until terminal cleanup. Closing releases every dependency without closing the caller-owned state and is idempotent.

Parameters

beforeMutation

validates the session phase and enters its equality/reentrancy guard; failure must leave that guard unchanged.

validateMutation

checks the current operation phase without entering a mutation guard.

afterMutation

leaves the guard after an accepted mutation attempt and must not throw.

invalidated

marks the screen dirty after an unequal assignment and must not throw or run application code.

Constructors

StateObservation

constructor(beforeMutation: () -> Unit, afterMutation: () -> Unit, invalidated: () -> Unit, validateMutation: () -> Unit)

Functions

open override fun close()

enterOperation

fun enterOperation()

Installs this session's phase guard for all state writes under the execution owner. The runtime must pair a successful call with leaveOperation in a finally block, including after terminal cleanup. Nested operations from different sessions must leave in reverse order.

evaluate

fun <T> evaluate(content: () -> T): T

Evaluates content synchronously and records exactly its state reads. Requires the execution owner and a live, non-evaluating observation. The result and any application failure are propagated unchanged; nested screen evaluations restore their caller's tracking context.

fork

fun fork(invalidated: () -> Unit): StateObservation

Creates an independently tracked retained region sharing this session's mutation guard. The region owner closes it on removal; closing this observation also releases every remaining region.

leaveOperation

fun leaveOperation()

Removes the innermost operation guard under its execution owner. This remains valid after close releases dependencies during terminal session cleanup.