FinalBox<T> class

A specialized, write-once container providing a thread-safe, immutable anchor for state that is initialized after construction.

FinalBox implements the Late-Binding Immutability pattern, allowing the system to define properties within a Nucleus or static configuration as "pending." It ensures that once the value is eventually committed, it remains strictly constant for the remainder of the node's lifecycle.

When to use

  • Late-Bound Constants: When a property within an immutable Nucleus or record cannot be determined at instantiation (e.g., unique identifiers, specialized receptor logic).
  • Dependency Injection: Storing upstream Cell references that are resolved during the node's activation or Ingress Gateway sequence.
  • Identity Anchoring: Holding a unique system-wide identifier or cryptographic hash generated during the first Pulse ingestion.
  • One-Time Computations: Wrapping the result of expensive architectural setups that must remain constant for the node's lifecycle.

How it works

  1. Placeholder Integrity: Provides a stable pointer within an immutable structure while the actual data is pending.
  2. Late-Binding Immutability: Utilizes Dart's late final semantics to allow a single assignment after construction.
  3. State Crystallization: Once assigned, the value becomes strictly immutable, enforcing a write-once contract.
  4. Hydration Sequence: Typically initialized during the framework's activation phase, bridging the gap between a stateless blueprint and a crystallized instance.

Example

// Defined within an immutable nucleus record
final config = (id: FinalBox<String>(), category: 'Secure');

// Initialization (allowed exactly once)
config.id.state = 'NODE_7741';

// Subsequent attempts to modify will throw a LateInitializationError
// config.id.state = 'NODE_8888';

Parameters

(None)

Returns

A FinalBox instance representing a Write-Once State Anchor.

See Also:

  • Box: The standard mutable variant for evolving state.
  • SyncBox: The synchronized proxy for asynchronous initialization.
  • Nucleus: The structural container that typically utilizes boxes for state storage.
Implemented types

Constructors

FinalBox()
Creates a FinalBox without an initial state. The value must be set exactly once before it is read.

Properties

async → SyncBox<T>
A Synchronized Proxy of this box, providing thread-safe, asynchronous access to the underlying state.
latefinal
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
value ↔ T?
The immutable state value held by this container.
getter/setter pairoverride

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited