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 commands — cell.apply(command, tx: tx) with the
forensic ApplyCommand model. 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, …).
cell — the Cell layer
Layer contract (the seam sentence): the instruction decides, the chain assembles, the observer glues.
Public surface (top entry points) — the full catalog is in
HowTo-Mitose-Cell.md §2–§3 and lib/doc/api_chooser.dart.
| Group | Entry point | When to use |
|---|---|---|
| Entry | Cell.ingress |
Every external fact the BRD names (identity, class, quantity, tick, ACK) |
| State | Cell.state |
Retained setting read at any time; no Tissue book named |
| Egress | Cell.observe |
The only Flow → Tissue glue; books and side effects move here |
| Projection | Cell.derive / Cell.synthesis |
"show X derived from Y" / one screen from many feeds |
| Governance | Cell.sanitized, Cell.deputy, Cell.unmodifiable |
PII redaction and least-privilege views |
| Commit | Cell.txApply |
Two retained facts or a command and its undo commit together, on Tissue books |
| Deferred | Cell.transaction |
Coordinates ValueCell; not the Mitose commit — defer it in a Demo |
Do NOT use this package for: the decision (that is cell_flow), the
books (that is cell_tissue), or invented factories (Cell.gate,
Cell.book, Cell.policy do not exist). See HowTo-Mitose-Cell.md §1.
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 Getting Started Core 16 Operators Transactions Apply + Transactions Demo:aircraft 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<
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 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
- 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<
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> 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
- 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<
P> Pulse Signals & Synapses - A reactive signal — the fundamental unit of communication in the framework.
-
PulseBase<
P> - The foundational blueprint for all nervous signals within the reactive graph.
- 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<
P extends Pulse, L extends Cell> Signals & Synapses - 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.corereactive 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
- 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
ValueCellthat enforces immutability. - 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.
- 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.
- 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
lineagemethod. - 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
- ApplyCommandDSL on Cell
- A "fluent" shortcut that makes it easier to create and run commands on a cell.
-
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.
- 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
Twith 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
cellsin a deterministic order. -
withLocks<
T> (Iterable< Lock?> locks, Future<T> body()) → Future<T> -
Acquires
locksin the given order, runsbody, then releases them in reverse order (LIFO unwind of nestedsynchronizedsections).
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, Function function, String id, 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.
- 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
- 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.
commitbeforebegin), non-modifiable function, non- participant cell, or a rejected command at commit time.