cell library Features

Cell — reactive state for Dart.

A cell holds a value. A pulse is the immutable message that moves a change. Operators (Cell.state, Cell.observe, …) wire cells together.

Receptor, TestCell, Context, and Synapses are optional. Defaults are pass-through. Nothing is authorized or redacted unless you pass a rule.

Learning order

Get data in → hold state → react → shape streams → go async → combine → isolate writes.

🟢 Group 1: Essential (Foundation)

Operator	Use when
Cell.state	Persistent mutable state atoms
Cell.ingress	Manual entry points for external events
Cell.derive	Pure transformations and projections
Cell.observe	Side effects and reactive termination

🟡 Group 2: Intermediate (Flow Control)

Operator	Use when
Cell.debounce	Emit only after a period of silence
Cell.distinct	Skip equal consecutive values
Cell.throttle	Rate limit signal propagation
Cell.synthesis	Aggregate multiple cells into one

🔵 Group 3: Advanced (Async & Composition)

Operator	Use when
Cell.asyncMap	Concurrency-controlled async logic
Cell.switchMap	Reactively follow the latest inner cell
Cell.fromFuture / Cell.fromStream	Bridge standard `dart:async` types

🔴 Group 4: Expert (Governance & Topology)

Operator	Use when
Cell.hub	Semantic routing based on signal types
Cell.sanitized	PII redaction and security boundaries
Cell.open	Late binding and manual topology control

🟣 Atomic Orchestration (Atomic)

Operator	Use when
Cell.transaction	Multi-cell atomic state transitions
Cell.txApply	Staged execution with compensation/rollback

Each works with zero knowledge of Receptor, TestCell, Context, or Synapses — all optional, all defaulted. They represent the Standard Entry Point, allowing you to build complex reactive systems by connecting simple building blocks. While you focus on your logic, the framework automatically manages the input (Ingress), logic (Transformation), and notifications (Egress), handling all security checks and verification steps in the background.

Groups 1–2 are enough for most applications. Group 4 and the Atomic tier handle complex orchestration: semantic routing, security boundaries, and transactional rollbacks. See the Advanced topic in generated docs.

Transactions

Cell.transaction buffers update/read and applies them together. Locks are taken at commit, not for the whole begin…commit window.

Cell.txApply stages cell.apply(fn, tx: tx, compensate: undo). It is not a second syntax for assigning value.

Governance (opt-in)

Context, DeputyContext, PulseContext, EphemeralPolicy, and PulseEphemeralPolicy record who / why / how and can enforce TTL or clearance if a TestCell (or deputy) actually denies the operation.

Context.describe stores a description. It is not a legal basis, a retention schedule, or an audit log.

Guides live in guide/ (HowTo-Start.md, HowTo-Transaction.md, …).

Classes

ApplyRejected: Explicit soft-reject from Cell.apply (not the same as void → null).
ApplyTransactionScope
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: 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 Getting Started Core 16 Operators Demo:aircraft Demo:hotel Core: A reactive node: holds state (or relays signals), validates every incoming change against a policy, and broadcasts accepted changes to whatever else is listening.
CellBase: The foundational abstract implementation of the Cell interface.
CollectivePulse: A Collective Pulse — a flat bundle of independent pulses travelling together as a single atomic wave.
CollectivePulseBase: The abstract base class for CollectivePulse implementations.
CompensationFailure
Context Advanced Advanced · 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.
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 Advanced Advanced · Deputy Context: Represents the Formal Mandate and declaration of intention for a Deputy.
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> Advanced Advanced · Ephemeral Policy: Defines the Lifecycle Governance for transient reactive nodes.
EvolvedPulse: An immutable signal derived from a previous pulse through a transformation step — a causal link in the signal's journey.
EvolvedPulseBase: The abstract base class for EvolvedPulse implementations.
FilterRule Signals & Synapses: 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.
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.
Identity: A utility for materializing unique identities within the somatic graph.
Inheritable
Instruction<C extends Cell, I extends Pulse, O extends Pulse> Instructions Pipelines & Receptors: 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.
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 Advanced Advanced · 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.
OpenCell Core 16 Operators Core: 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.
PriorityQueue<E>: A collection of elements that maintains a Deterministic Priority Order, serving as a specialized Ranked Execution Buffer for the reactive fabric.
PropagationPolicy Advanced · Propagation Policy: A declarative blueprint defining the Temporal Dynamics and Operational Governance of pulse propagation.
Pulse Pulse Signals & Synapses: A reactive signal — the fundamental unit of communication in the framework.
PulseBase
PulseContext Advanced Advanced · Pulse Context: Represents the Causal Identity and ontological Provenance of a Pulse.
PulseEphemeralPolicy Advanced Advanced · Pulse Ephemeral Policy: A governance policy that defines the Lifecycle Constraints and Termination Logic for a Pulse as it traverses the reactive graph.
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> Pipelines & Receptors: 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.
Shell<T>: A specialized Defensive Perimeter and Projection Layer representing a formal contract for Bidirectional Mutual Authorization.
Synapses Signals & Synapses: The distribution fabric for a Cell's outgoing signals—defining how, when, and to whom a pulse is delivered.
SynapsesBase: 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> Testing & Validation: A specialized behavioral guard for validating imperative logic and functional action execution within the reactive graph.
TestCell<C extends Cell> Testing & Validation: The central validation gate for a Cell – it decides what's allowed.
TestLinkRule<C extends Cell> Testing & Validation: 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> Testing & Validation: A rule that validates incoming Pulse signals before they reach a cell.
TestRule<C> Testing & Validation: A fundamental architectural component representing an Integrity Gate or Validation Guard, responsible for enforcing structural and business invariants across the reactive graph.
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
TxApplyCommitted
TxApplyCompensationFailed
TxApplyCompensationRetry
TxApplyEvent
TxApplyOptions
TxApplyRejected
TxApplyRolledBack
TxApplyStaged
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
UnmodifiableEvolvedPulse
UnmodifiablePulse: A read‑only projection of a pulse that enforces structural finality.
UnmodifiablePulseBase
UnmodifiableValueCell<V>: A specialized read‑only proxy of a ValueCell that enforces immutability.
ValidationFailure: Represents a validation failure for a specific cell.
ValueCell<V> Core: 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.
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
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.
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.
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

PulseExtension on Pulse: Provides a fluent, functional API for operating on individual Pulse instances.
PulseIterableExtension on Iterable<Pulse>: Fluent extensions for collections of Pulse objects.
TekartikLockExtension on Lock: Extension on Lock providing synchronous execution when possible, for synchronous computations that don't need to always go through a Future.

Functions

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>
withCellLocks<T>(Iterable<Cell> cells, Future<T> body(), {int order(Cell a, Cell b)?}) → Future<T>: Convenience: acquire the locks of cells in a deterministic order.
withLocks<T>(Iterable<Lock?> locks, Future<T> body()) → Future<T>: Acquires locks in the given order, runs body, then releases them in reverse order (LIFO unwind of nested synchronized sections).

Typedefs

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 = ({Cell cell, bool Function(I input) emit, Future<bool> Function(I input) emitAsync, Future<void> Function(Pulse 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.
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

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
TxApplyException