testing library

Testing utilities for cell_flutter.

testing.dart is the binding's Test Surface — the barrel library that exports every test helper the binding provides, plus the application-facing surface (cell_flutter.dart) they build on. It is the single import a test needs to pump, emit, record, and assert against cells inside a testWidgets body.

Why it is used

Widget-testing a cell-backed widget has three recurring shapes, and this library covers each without hand-rolled scaffolding:

  • Pumping: a widget needs a CellScope (for lookups) or at least a MaterialApp + Scaffold frame (for text and theme). pumpWithCells and pumpCell assemble the correct tree with one call.
  • Emitting: writing cell.value = ... does not trigger a render on its own; emitAndSettle and emitAndPump combine the write with the pumping needed to see the result.
  • Observing: recordPulses captures the full pulse sequence, and expectCellValue / expectCellGolden assert on the current value or the rendered pixels.

CellTestHarness bundles all three for suites with several shared cells, and takes care of recorder cleanup in tearDown.

Import from test files only

import 'package:cell_flutter/testing.dart';
import 'package:flutter_test/flutter_test.dart';

Requirement: test-only usage (read this)

cell_flutter/testing.dart imports package:flutter_test/flutter_test.dart. cell_flutter declares flutter_test as a regular dependency — the same pattern bloc_test, mocktail, and mockito use — so the import resolves automatically. To keep flutter_test out of production builds, add cell_flutter itself to your dev_dependencies:

dev_dependencies:
  cell_flutter: ^0.4.0

Application code that imports package:cell_flutter/cell_flutter.dart (not testing.dart) is unaffected; the flutter_test import never enters the production graph.

What this library exports

Re-export:

  • package:cell_flutter/cell_flutter.dart — the entire application-facing surface (CellBuilder, CellSelector, CellValueBuilder, CellAsyncBuilder, CellListener, CellScope, CellNotifier, CellAsStream, CellAsValue, plus the core cell re-export). Test helpers are typically written against the same surface the production code uses, so this library re-exports it.

Widget pumping:

  • CellPumpWithCells.pumpWithCells — pumps a widget inside a CellScope, with an optional custom wrapper.
  • CellPumpCell.pumpCell — pumps a bare CellBuilder in a default MaterialApp + Scaffold frame.

Emission:

  • CellEmitAndSettle.emitAndSettle — writes the value and pumps until the tree settles.
  • CellEmitAndSettle.emitAndPump — writes the value and pumps a single frame (or an explicit Duration), without waiting for settle.

Observation:

  • CellRecordPulses.recordPulses — records the ordered pulse sequence emitted by any Cell.
  • PulseRecorder<T> — the recorder type; exposes pulses and payloads.
  • CellExpectValue.expectCellValue — asserts a ValueCell's current value against a matcher.
  • CellExpectGolden.expectCellGolden — captures a golden image of a CellBuilder at the cell's current value.

Fixture:

  • CellTestHarness — a per-test registry that owns recorders and bundles pumping + emission + cleanup.

Inherited caveats

The binding rests on cell's verified replay round-trip (commit 05b4895d). Concurrent asyncMap effect attribution is tracked separately and is not claimed by this binding. recordPulses records every pulse regardless of type; only Cell.fromFuture currently emits error pulses in the core package — fromStream and asyncMap do not. See record_pulses.dart for the full explanation.

See Also:

  • package:cell_flutter/cell_flutter.dart — the application-facing surface this library re-exports.
  • package:cell_flutter/hooks.dart — the optional flutter_hooks integration, with its own hook equivalents for tests that use HookWidget.
  • record_pulses.dart — the authoritative statement of per-source error-pulse behavior (overrides contradictory claims in other binding docs).
  • test/error_pulse_sources_test.dart — the test file that locks in the per-source error-pulse behavior these docs describe.
  • CellTestHarness — the higher-level fixture for multi-cell suites.

Classes

ApplyAccepted<R>
The command was authorized, safety-checked, and successfully executed.
ApplyCommandRunner
A helper class used to set up and execute an action on a cell.
ApplyLedger
The framework's internal Record Keeper and receipt generator.
ApplyOutcome<R>
The official, auditable result of submitting an ApplyCommand.
ApplyRejected<R>
The command was denied by the framework's safety rules (the Integrity Gate).
ApplyStaged
The command was accepted and placed into a transaction to be run later.
ApplyTransactionScope
Handle for a staged command transaction — the mechanism behind Cell.txApply.
ApplyVeto
A special signal used by a function to cancel its own operation.
Async<C>
A foundational marker interface and architectural contract representing an Asynchronous Proxy or Controller for a core component C.
AsyncPriorityQueue<E>
AsyncQueueList<E>
AsyncSynapses<P extends Pulse, L extends Cell>
An Asynchronous Projection of a Synapses instance for non‑blocking signal distribution.
Box<T>
A specialized, lightweight container used to provide a mutable state anchor within the framework's immutable Record architecture.
Cell
A reactive node: holds state (or relays signals), validates every incoming change against a policy, and broadcasts accepted changes to whatever else is listening.
CellAsyncBuilder<V>
A widget that renders the asynchronous state of any Cell as an AsyncSnapshot<V>.
CellBase
The foundational abstract implementation of the Cell interface.
CellBuilder<V>
A widget that rebuilds its builder whenever cell's value changes.
CellEditingController
A TextEditingController bound two-way to a ValueCell<String>.
CellErrorBoundary
Renders a fallback instead of Flutter's error screen when a cell-driven error is thrown while building the subtree below it.
CellErrorBoundaryState
The state behind CellErrorBoundary.
CellFlutterDevTools
The in-app Cell Inspector.
CellFormField<T>
A FormField whose value is bound two-way to a ValueCell<T>.
CellGraph
A registered cell graph: the unit of identity and replay in the framework.
CellGraphBuilder
The entry point for constructing a CellGraph.
CellGraphRegistry
Public read-only access to the cell id registry.
CellGraphSnapshot
A serialisable snapshot of an entire cell graph.
CellInspectorOverlay
A floating in-app Cell Inspector panel.
CellListener<V>
A widget that invokes onPulse for every pulse emitted by cell, without rebuilding its subtree.
CellListView<T>
A virtualized list whose item collection is bound to a Cell.
CellNotifier<V>
Adapts a ValueCell to Flutter's ValueNotifier contract as a read-only bridge.
CellPulseRecord
One recorded pulse, display-formatted.
CellRegistry
The live registry behind CellFlutterDevTools.
CellRegistryEntry
One registered cell and its journal.
CellRestorationScope
Provides a RestorationBucket to descendant RestorableCells and registers them automatically with Flutter's restoration protocol.
CellRestorationScopeState
The stateful, mixin-bearing half of CellRestorationScope.
CellScope
An InheritedWidget that provides a small set of app-level cells to the subtree below it, addressed by Symbol.
CellSelector<V, S>
A widget that rebuilds its builder only when a selected slice of cell's value changes.
CellSnapshot
A serialisable projection of one cell's identity and current value.
CellTestHarness
A per-test Cell Registry that bundles the cells a test suite needs, tracks their pulse recorders, and disposes both in one call.
CellTextField
A TextFormField whose value is bound two-way to a ValueCell<String>.
CellValueBuilder<V>
A widget that rebuilds its builder whenever any Cell emits a new value.
ClockEffect
A read of the system clock. Records the epoch millis.
CollectivePulse<P>
A Collective Pulse — a flat bundle of independent pulses travelling together as a single atomic wave.
CollectivePulseBase<P>
The abstract base class for CollectivePulse implementations.
CompensationFailure
Describes a single failed compensation attempt.
Context
Metadata describing a Cell's tier, domain, and operational boundaries — used by TestCell rules to make context-aware decisions.
ContextBase
The foundational implementation of the Operational Environment, providing the core logic for Prototype-based Inheritance and Ontological Resolution.
ContextTranslator
Bridges a DeputyContext across mandate schema versions.
ContextTranslatorRegistry
A simple registry of translators keyed by (from, to).
CycleChecker
A specialized Traversal Guard and Topology Validator, responsible for preventing infinite recursion and ensuring the reactive graph remains a Directed Acyclic Graph (DAG) during signal propagation.
DefaultValue
DefaultValue is a metadata annotation primarily used by the code generation framework (such as build_model) to define a fallback or initial value for fields in a model class.
DeputyContext
Represents the Formal Mandate and declaration of intention for a Deputy.
DivergenceReport
A single point at which a replay diverged from its recording.
EffectJournal
The boundary between a receptor and the outside world.
EffectRecord
A single recorded non-deterministic observation.
EmailPattern
EmailPattern is a specialized EntryPattern metadata annotation designed to validate whether a string conforms to a standard email address format.
EntryPattern
EntryPattern is a specialized TestRule metadata annotation that validates whether a string input matches a specific Regular Expression (RegExp).
EphemeralPolicy<C extends Cell>
Defines the Lifecycle Governance for transient reactive nodes.
EvolvedPulse<P>
An immutable signal derived from a previous pulse through a transformation step — a causal link in the signal's journey.
EvolvedPulseBase<P>
The abstract base class for EvolvedPulse implementations.
FilterRule<P extends Pulse>
A filter that can transform, redact, or suppress a Pulse before it is broadcast to downstream observers.
FinalBox<T>
A specialized, write-once container providing a thread-safe, immutable anchor for state that is initialized after construction.
ForkHandle
A forked history.
ForkLedgerStore
A LedgerStore wrapper that injects a synthetic ForkRecord entry at seq 0.
ForkRecord
The genesis record of a fork ledger.
FunctionObject
Simple wrapper for functions or records containing function information. Used to pass function metadata through the system.
FunctionTypeObject<T>
Lazy-evaluated version of TypeObject that executes a function to get the value. Useful for deferred initialization or expensive object creation.
Governance<V>
The foundational Authority Protocol for defining structural and behavioral guardrails within the framework's Mandate ontology.
GovernanceEntry<G extends Governance<V>, V>
A strongly-typed key-value pair that represents a single dimension of governance within the framework's Scene-Driven Ontology.
HashChain
The rolling hash chain that binds ledger entries.
Identity
A utility for materializing unique identities within the somatic graph.
Inheritable
InMemoryLedgerStore
An in-memory LedgerStore, suitable for tests and for ephemeral graphs whose ledger does not need to survive the process.
Instruction<C extends Cell, I extends Pulse, O extends Pulse>
A discrete logic unit that defines how a Receptor reacts to a Pulse.
InstructionBase<C extends Cell, I extends Pulse, O extends Pulse>
The foundational implementation and architectural base for all Instruction variants.
InstructionChain<C extends Cell, I extends Pulse, O extends Pulse>
A composite Instruction that orchestrates a sequence of processing units.
IoEffect
A single I/O call (network, disk, database). Records the label, the request digest, and the response digest; the raw response is held only if the caller supplied rawOutput. For replay, rawOutput is required — the digest alone cannot reconstruct the response.
JournalScope
The task-local stack of active journals.
Ledger
The durable, hash-chained record of every state transition.
LedgerEntry
A single, immutable row in the ledger.
LedgerScope
The graph-scoped ambient that coordinates state capture and ledger append.
LedgerScopeImpl
The per-graph implementation of the scope.
LedgerStore
The persistence backend for a Ledger.
Lock
A mutual-exclusion lock: serializes access to a shared resource across asynchronous code, similar to Java's synchronized.
MaxLength
MaxLength is a specialized TestRule metadata annotation used primarily by the code generation framework (such as build_model) to enforce structural and data-integrity constraints on model fields.
Modifiable
A specialized architectural marker and base interface for objects that support controlled mutation through the framework's dynamic command pattern.
ModifiableAsync<C extends Cell>
Provides asynchronous execution of operations on a Cell.
MultiLock
A Lock that atomically acquires several other locks together.
Nucleolus
A specialized, terminal implementation of the Nucleus contract representing the framework's "zero-state" and Ontological Root.
Nucleus
The immutable blueprint underlying every Cell — its receptor, testRule, context, synapses, and lifecycle policy, stored separately from the live cell instance.
NucleusBase
The foundational base implementation of the Nucleus contract, providing a memory-optimized storage engine for reactive cell properties.
NullJournal
The "no journal in scope" sentinel. Every effectful operation fails loudly.
OpenCell
A specialized, interactive Cell that serves as a Reactive Bridge for external stimulus injection and dynamic topology management.
OpenCellAsync
Represents the Asynchronous Governance Interface for an OpenCell.
PolicyReplay
Policy-tick journaling for EphemeralPolicy.
PolicyTickEffect
A single tick of an EphemeralPolicy.
PriorityQueue<E>
A collection of elements that maintains a Deterministic Priority Order, serving as a specialized Ranked Execution Buffer for the reactive fabric.
PropagationPolicy
A declarative blueprint defining the Temporal Dynamics and Operational Governance of pulse propagation.
Pulse<P>
A reactive signal — the fundamental unit of communication in the framework.
PulseBase<P>
The foundational blueprint for all nervous signals within the reactive graph.
PulseCodec
Canonical serialiser for Pulse.
PulseContext
Represents the Causal Identity and ontological Provenance of a Pulse.
PulseContextCodec
Serialises and deserialises PulseContext, preserving the full parent chain.
PulseEphemeralPolicy
A governance policy that defines the Lifecycle Constraints and Termination Logic for a Pulse as it traverses the reactive graph.
PulseReconstructor
Reconstructs the input Pulse that produced a LedgerEntry.
PulseRecorder<T extends Cell>
A recorder that captures every pulse emitted by a Cell, in order.
PulseShell<P, R extends Receptor<Cell>>
A specialized Shell providing a Perceptual Projection of a Pulse to facilitate pre-execution validation and security gating.
QueueList<E>
Receptor<C extends Cell>
The transformation pipeline that decides how a Cell responds to an incoming Pulse.
ReceptorAsync<C extends Cell>
An asynchronous execution handle for a Receptor that facilitates non‑blocking pulse processing and lifecycle synchronization.
ReceptorBase<C extends Cell>
The foundational base implementation of Receptor that provides the core synchronization and pulse propagation engine.
RecordingJournal
The recording side of the journal.
RegisteredCell
A thin wrapper that pairs a Cell with its graph-scoped name.
ReplayEngine
The replay engine.
ReplayJournal
The replay side of the journal.
ReplayOptions
Strictness flags that control the replay engine's behaviour when the replayed state diverges from the recorded state.
ReplayResult
The result of a ReplayEngine.replay call.
RestorableCell<V>
A ValueCell whose value participates in Flutter's state restoration.
RestorableCellDelegate<V>
The internal RestorableProperty that bridges a RestorableCell to Flutter's restoration protocol.
Shell<T>
A specialized Defensive Perimeter and Projection Layer representing a formal contract for Bidirectional Mutual Authorization.
StateDelta
A single cell's state change within a ledger entry.
StreamEffect
A stream event. Records the event's stream label, the digest of the value, and optionally the raw value.
Synapses<P extends Pulse, L extends Cell>
The distribution fabric for a Cell's outgoing signals—defining how, when, and to whom a pulse is delivered.
SynapsesBase<P extends Pulse, C extends Cell>
The foundational base implementation for Synapses, serving as the Transmission Engine of the cell.core reactive framework.
SyncBox<T>
A synchronized variant of Box providing Thread-Safe Access and facilitating Atomic State Transitions across concurrent execution boundaries.
SyncCycleChecker
A thread-safe, Synchronized Circular Dependency Guard for asynchronous reactive flows.
SyncQueue<E>
A thread-safe implementation of a PriorityQueue, providing Synchronized Access for prioritized collection-based state.
SyncSet<E>
A thread-safe implementation of a Set, providing Synchronized Access for collection-based state.
SynthesisCell
Represents a Synthesis Cell—a specialized structural node that aggregates signals from multiple source cells into a single unified stream.
TestActionRule<C extends Cell>
A specialized behavioral guard for validating imperative logic and functional action execution within the reactive graph.
TestCell<C extends Cell>
The central validation gate for a Cell – it decides what's allowed.
TestCellReplay
Purity-aware invocation of a TestCell.
TestLinkRule<C extends Cell>
A specialized behavioral guard for validating Topological Synapses and graph formation within the reactive framework.
TestPasses
A sentinel implementation of TestCell that always authorises every operation.
TestPulseRule<C extends Cell>
A rule that validates incoming Pulse signals before they reach a cell.
TestRule<C>
A fundamental architectural component representing an Integrity Gate or Validation Guard, responsible for enforcing structural and business invariants across the reactive graph.
TimerEffect
A timer firing. Records the scheduled duration and the actual fire time; the pair is what makes debounce/throttle replayable.
TransactionBegun
Emitted when a transaction begins.
TransactionCommitted
Emitted when a transaction commits successfully.
TransactionEvent
Base class for all transaction lifecycle events.
TransactionOptions
Configuration options for a Cell.transaction.
TransactionRolledBack
Emitted when a transaction is rolled back.
TransactionTimedOut
Emitted when a transaction times out.
TransactionUpdated
Emitted when a cell is updated during a transaction.
TxApplyBegun
Emitted once, immediately after ApplyTransactionScope.begin succeeds.
TxApplyCommitted
Emitted after a successful ApplyTransactionScope.commit.
TxApplyCompensationFailed
Emitted each time a compensation attempt fails.
TxApplyCompensationRetry
Emitted before each retry of a compensation function.
TxApplyEvent
Base class for all lifecycle events emitted by an ApplyTransactionScope.
TxApplyOptions
Configuration for Cell.txApply.
TxApplyRejected
Emitted when a staged command is refused.
TxApplyRolledBack
Emitted after a rollback (full or savepoint-scoped).
TxApplyStaged
Emitted once per successful ApplyTransactionScope.enqueueCommand.
TypeObject<T>
Wrapper class for holding typed objects. Provides type safety when working with generic containers.
Unmodifiable
A specialized Marker Interface and architectural anchor used to identify reactive nodes and data structures that have been restricted to Read-Only access.
UnmodifiableCollectivePulse<P>
UnmodifiableEvolvedPulse<P>
UnmodifiablePulse<P>
A read‑only projection of a pulse that enforces structural finality.
UnmodifiablePulseBase<P>
UnmodifiableValueCell<V>
A specialized read‑only proxy of a ValueCell that enforces immutability.
UuidEffect
A UUID generation. Records the generated UUID.
ValidationFailure
Represents a validation failure for a specific cell.
ValueCell<V>
A state‑bearing reactive node – the primary way to manage persistent state in the Cell Framework.
ValueCellAsync<V>
A specialized asynchronous controller for ValueCell, providing a thread‑safe and non‑blocking interface for state interaction.
ValueNucleus<V>
A specialized Nucleus blueprint designed to manage and propagate a discrete, persistent state value of type V.
ValueRange
ValueRange is a specialized TestRule metadata annotation designed to validate whether a numeric input falls within a specific inclusive boundary.
Values
Values is a specialized TestRule that validates whether a given input is present within a predefined collection of allowed values.
VerdictEffect
The decision reached by an effectful TestCell.
VersionRegistry
Maps (cellId, version) to the receptor and test rule that implemented that version.
WebsiteUrlPattern
WebsiteUrlPattern is a specialized EntryPattern metadata annotation designed to validate whether a string conforms to a standard web URL format.

Enums

AuditLevel
Defines the Observability Granularity and XAI Verbosity required for a Deputy's operations.
Clearance
Defines the Sovereign Physical Laws and structural boundaries of reactive operations within the framework.
CompensationErrorPolicy
Determines how the transaction scope behaves when a compensation attempt fails.
ForkPolicy
How a fork handles the parent graph's state.
HubRouting
Defines how a Cell.hub decides which spoke (child cell) should receive an incoming signal.
Isolation
Defines the Architectural Boundary & State Visibility of a Deputy.
IsolationLevel
Defines the consistency and visibility guarantees for a transaction.
LineageArgument
Defines the specific data field to be extracted when traversing a Pulse's Causal History via the lineage method.
LockOrdering
Defines the order in which locks are acquired during commit.
Mandate<V>
Defines the Capability Profile and Authorization Scope for a Deputy.
Ontology<V>
Defines the Structural Taxonomy, Static Identity, and Architectural Shape of a Cell.
PriorityTier
Defines the Semantic Urgency Tiers for signal execution.
PropagationStrategy
Defines the tactical execution models for Pulse Propagation within the Cell framework's reactive graph.
Provenance<V>
Defines the Causal Accountability, Audit Trail, and Operational Intent of a Pulse.
Purity
Classifies a Receptor or TestCell by its effect footprint.
ReasoningStrategy
Defines the Logical Pedigree and algorithmic origin of a Pulse.
Sensitivity
Defines the Information Classification and data-privacy tier of a Pulse.
Sovereignty
Defines the Commitment Authority and Escalation Protocol assigned to a Deputy.

Mixins

Deputy<C extends Cell>
The mixin implementing proxy behavior for Cell.deputy — you don't use this directly.
Effectful
The declarative marker for effectful receptors and rules.
EffectfulReadOnly
A variant of Effectful for receptors that read the outside world but do not mutate it (clocks, environment variables, read-only database lookups). Reports Purity.readOnlyExternal.
GovernanceMixin<G extends Governance<V>, V>
A convenient mixin that provides default implementations for the Governance interface methods.
InstructionChainMixin<C extends Cell, I extends Pulse, O extends Pulse>
A mixin that provides the core execution engine for composite instructions.
OpenReceptorMixin
A mixin that implements the Manual Control Interface for the reactive network.
OpenSynapsesMixin
A mixin that implements the Reactive Topology Interface for OpenCell architectures.

Extensions

ApplyCommandDSL on Cell
A "fluent" shortcut that makes it easier to create and run commands on a cell.
CellAsStream on Cell
Bridges a Cell to a Dart Stream<V?>.
CellAsValue on Cell
An extension that mirrors any Cell into a fresh ValueCell.
CellEmitAndSettle on WidgetTester
An extension on WidgetTester that drives a ValueCell through the widget tree and lets the frame pipeline catch up.
CellExpectGolden on WidgetTester
An extension on WidgetTester that captures a golden image of a CellBuilder over a ValueCell, at the cell's current value.
CellExpectValue on WidgetTester
An extension on WidgetTester that asserts a ValueCell's current value against a matcher, with a cell-naming diagnostic on failure.
CellGraphFork on CellGraph
Forking extensions for CellGraph.
CellGraphTranslators on CellGraph
The graph-scoped translator registry.
CellGraphVersions on CellGraph
The graph-scoped version registry (see VersionRegistry).
CellGraphVisualise on CellGraph
Visualisation for CellGraph and Ledger.
CellPumpCell on WidgetTester
An extension on WidgetTester that pumps a bare CellBuilder over a ValueCell.
CellPumpWithCells on WidgetTester
An extension on WidgetTester that pumps a widget inside a CellScope.
CellRecordPulses on T
An extension that records every pulse emitted by a Cell, for assertion in tests.
CellRestoration on Cell
Static factory access for RestorableCell.
ForkParentLookup on Ledger
The parent ledger's hash at a given sequence.
ForkVerify on ForkHandle
Fork-aware verification. A fork's verify requires the parent ledger's verify() to pass.
LedgerVisualise on Ledger
Visualisation for a Ledger's entries (also used by the CLI).
PulseExtension on Pulse<P>
Provides a fluent, functional API for operating on individual Pulse instances.
PulseIterableExtension on Iterable<Pulse>
Fluent extensions for collections of Pulse objects.
ReplayEngineFork on ReplayEngine
Fork-aware replay: replays a parent ledger into a fork handle, applying a Mutation to each entry.
TekartikLockExtension on Lock
Extension on Lock providing synchronous execution when possible, for synchronous computations that don't need to always go through a Future.
ValueCellBuilder on ValueCell<V>
Fluent constructor for a CellBuilder over a ValueCell.

Functions

canonicalJsonDecode(String source) → Object?
Decodes a canonical JSON string into a JSON-encodable object tree.
canonicalJsonEncode(Object? value, {bool omitNulls = false}) → String
Encodes value into deterministic, canonical JSON.
cellEditingController(ValueCell<String> cell) → CellEditingController
Creates a CellEditingController bound to cell.
fingerprint(Object? value) → String
Computes the SHA-256 fingerprint of value's canonical JSON form, hex-encoded.
get<T>(Function fn, {Function? fallback, T? orElse}) → T
A robust functional utility for safely executing operations of type T with multi-stage recovery logic and hierarchical fallbacks.
mapMerge<K, V>(Map<String, dynamic> map, Map<String, dynamic> other) → Map<String, dynamic>
restorableState<V>({required String restorationId, V? initial, V? fromPrimitives(Object? data)?, Object? toPrimitives(V? value)?}) → RestorableCell<V>
The unqualified alias for CellRestoration.restorableState.
snapshotForCell<V>(Cell cell) → AsyncSnapshot<V>?
Returns the AsyncSnapshot the widget should show for cell's currently retained pulse, or null when nothing usable is retained.
snapshotForPulse<V>(Pulse<Object?> pulse) → AsyncSnapshot<V>
Projects a single Pulse into an AsyncSnapshot for a CellAsyncBuilder.
withCellLocks<T>(Iterable<Cell> cells, Future<T> body(), {int order(Cell a, Cell b)?}) → Future<T>
Acquires the locks of cells in a deterministic total order.
withLocks<T>(Iterable<Lock?> locks, Future<T> body()) → Future<T>
Creates a cell that emits the values of a Dart Stream.

Typedefs

ApplyArguments = ({Map<Symbol, Object?>? namedArguments, List<Object?>? positionalArguments})
A structured container for function arguments that allows for auditing and reversals.
ApplyCommand = ({ApplyArguments arguments, ApplyCompensation? compensation, Function function})
A complete request to perform an action or change state within a cell.
ApplyCompensation = ({ApplyArguments arguments, Cell? cell, Function function})
A set of instructions used to undo or "roll back" a change if it fails.
ApplyReceipt = ({ApplyArguments arguments, Cell cell, String? contextVersion, Function function, String id, int? ledgerSeq, String? pulseDigest, String? receptorVersion, String? ruleVersion, DateTime timestamp, int? txSequence, bool vetted})
The permanent, official record of a specific action taken by a cell.
Arguments = ({Map<Symbol, dynamic>? namedArguments, List? positionalArguments})
Represents a tuple of positional and named arguments for function calls. Used when validating or processing function applications in cells.
EgressHandle<S extends Pulse> = ({Cell cell, void Function() start, void Function() stop})
A management handle for an Output Terminal, providing a controlled interface to manage an external side-effect listener.
FunctionType<R> = R Function()
Generic function type that takes no parameters and returns RNA. Used in FunctionTypeObject for lazy evaluation.
HubHandle = ({Pulse? Function(Pulse pulse) emit, Future<Pulse?> Function(Pulse pulse) emitAsync, Future<void> Function(Pulse pulse, {bool serializedCompletion}) ingest, Cell root, Iterable<Cell> spokes})
A management handle for a Signal Distribution Hub, providing a unified interface to control a multi-destination routing cluster.
IngressHandle<I> = ({Cell cell, bool Function(I input) emit, Future<bool> Function(I input) emitAsync, Future<void> Function(Pulse<I> pulse, {bool serializedCompletion}) ingest})
A management handle for an Input Gateway, providing a controlled interface for injecting external imperative stimuli into the reactive graph.
InheritableHandle = ({Cell? bind, Context context, EphemeralPolicy<Cell>? ephemeralPolicy, Receptor<Cell> receptor, TestCell<Cell> testRule})
A structured grouping of the Governance & Logic properties that define a node's operational identity and can be cascaded through the inheritance chain.
MirroredCell<V> = ({ValueCell<V> cell, void Function() dispose})
The paired result of CellAsValue.asValueCell: a mirror cell and the callback that releases it.
Mutation = Pulse? Function(LedgerEntry entry, Pulse pulse)
A what-if mutation hook.
NucleusSimplest = Nucleolus
A semantic type alias representing the framework's Zero-Overhead Root and the terminal ancestor of all reactive blueprints.
OpenCellBase = _OpenCell
Base class for all OpenCell types.
SpokeRegistration = ({DeputyContext? context, Pulse? Function(Cell cell, Pulse pulse, {dynamic user})? handler, String key, bool Function(String? type)? match, int priority, Receptor<Cell>? receptor})
A configuration record for an individual Spoke (Destination) within a Cell.hub.
StateHandle<V> = ({ValueCell<V> cell, Future<void> Function(Pulse<V> pulse, {bool serializedCompletion}) ingest, bool Function(V? value) update, Future<bool> Function(V? value) updateAsync})
A management record that bundles a ValueCell with its imperative update functions — the standard way to create and interact with a state atom.
SynthesisHandle = ({bool Function(Cell cell) add, void Function(Iterable<Cell> cells) addAll, SynthesisCell cell, bool Function() clear, bool Function() isEmpty, bool Function(Cell cell) remove, void Function(Iterable<Cell> cells) removeAll, void Function() start, void Function() stop, List<Cell> Function() toList})
An Administrative Record providing a control interface for dynamic SynthesisCell topographies.
TransactionScope = ({Future<void> Function(Iterable<Cell> cells) begin, Future<void> Function() commit, dynamic Function(Cell cell) pending, dynamic Function(Cell cell) read, Future<void> Function({Object? savepoint}) rollback, Object Function() savepoint, void Function(Cell cell, dynamic value) update})
A handle for coordinating atomic, multi‑cell transactions.

Exceptions / Errors

ForkIntegrityException
Thrown by ForkVerify.verify when a fork's parent ledger, fork ledger, or genesis binding is invalid.
LedgerIntegrityException
Thrown by Ledger.verify when an entry's hash, sequence, or predecessor chain does not match.
ReplayDivergenceException
Thrown when a replay diverges from the recording.
TransactionConflictException
Thrown when an isolation conflict is detected during commit.
TransactionTimeoutException
Thrown when a transaction exceeds its timeout duration.
TransactionValidationException
Thrown when validation of buffered writes fails during commit.
TxApplyCompensationException
Raised when one or more compensations fail under CompensationErrorPolicy.collectThenThrow or CompensationErrorPolicy.failFast.
TxApplyException
Raised for control-flow problems in a ApplyTransactionScope: wrong phase (e.g. commit before begin), non-modifiable function, non- participant cell, or a rejected command at commit time.