cell 1.1.0
cell: ^1.1.0 copied to clipboard
Foundation layer of the Cell Framework — Cells, Nucleus, Context, Deputy Pattern, and Conactive execution with Causal Integrity.
cell #
Install and import #
dart pub add cell cell_flow cell_tissue
import 'package:cell/cell.dart'; // Cell layer only
import 'package:cell_flow/cell_flow.dart'; // re-exports package:cell
import 'package:cell_tissue/cell_tissue.dart';
AI agents start here #
Read this before opening any other page.
cell is designed with AI coding agents in mind. Every top public symbol
carries a machine-readable ### AI Agent Guide block, and the surfaces below
let an agent reliably pick the right factory and generate code that compiles
against the live API.
- Version pin:
cell 1.1.0,cell_flow 1.0.0,cell_tissue 1.0.0. - Preflight:
dart run tool/ai_preflight.dart— prints the resolved versions and any stale pins. - API chooser:
lib/doc/api_chooser.dart(generated from the### AI Agent Guidedoc blocks). - Layer guides:
guide/HowTo-Mitose-Cell.md— Cell factory choicesguide/HowTo-Mitose-Flow.md— Flow operator choicesguide/HowTo-Mitose-Tissue.md— Tissue collection choices
- The seam sentence: The instruction decides, the chain assembles, the observer glues.
If you have a BRD sentence that says… #
| BRD sentence | First factory | Do NOT |
|---|---|---|
| "capture X" / "record X entering" | Cell.ingress |
create a custom Cell |
| "record every Y" (history) | Cell.observe + TissueList |
put in instruction |
| "reserve N units" | TissueValue + invariant |
use Cell.state<int> |
| "flag when Y happens" | FlowInstructionBase subclass in Flow |
put in Cell.observe |
| "two facts move together" | Cell.txApply on Tissue |
Cell.transaction |
| "wait for silence" | Debounce in cell_flow |
roll your own Timer |
(The full matrix lives in lib/doc/api_chooser.dart; this is the 6-row elevator version.)
Reactive State for Dart — transaction-ready, observable, validated, synchronized, auditable, and zero-copy deputy-able cells, pulses, and operators. Plain Dart state, plus a governance contract.
This is the foundation package of the Cell Framework (Mitosis). Sibling packages add collections, relations, stream combinators, persistence, and codegen.
Mitose pipeline — the umbrella feature. The root repository ships an AI-executable pipeline that turns a business requirement into a working Cell + Flow + Tissue solution with its BRD, WalkThrough, Demo, ARCHITECTURE, and FEATURES documents. An AI prompt agent follows
guide/HowTo-Mitose.md; this package supplies the Cell layer rules viaguide/HowTo-Mitose-Cell.md. See the root README.
Overview #
A cell holds a value or relays a signal. A pulse is the immutable
message that moves a change. Operators (Cell.state, Cell.observe, …) wire
cells together into a reactive graph — and that graph is governed:
- Transaction ready, built into the foundation —
Cell.txApply(staged commands with Saga compensation and rollback) andCell.transaction(buffered multi-cell atomic commits) are core factories of thecellpackage itself — an integral part of the reactive graph, not an add-on layer. Every mutation request is a first-class, auditable command (apply+ApplyCommand→ sealedApplyOutcome). Plain Dart state — and most reactive frameworks — have no equivalent: a multi-step update that throws halfway through leaves permanent, partial state; here it rolls back through recorded compensation. - Observable — every change emits a typed
Pulsethat downstream cells react to; plain Dart requires hand-rolled listener orStreamplumbing. - Validated — a
TestCellgate runs on every write, so validation is enforced by the framework instead of being anifyou remember to call. - Deputy-able — hand out zero-copy read-only views (
.unmodifiable) or restricted proxies (.deputy()); a deputy is the principal (cell == cell.deputy()istrue) and its rules can only narrow what the principal already allows. - Auditable —
ApplyReceiptforensics, causal trace, and provenance metadata ride every pulse;Cell.sanitizedredacts before egress. - Synchronized — transactional writes serialize through the ledger, and governed cells carry synchronization locks for high-integrity paths.
- Timing control —
debounce,throttle, anddistinctare library behavior, not ad-hocTimers. - Composable — 16 core operators cover state, events, projection,
fan-in, async mapping (
asyncMapwith concurrency control), routing (hub), and switching (switchMap);fromFuture/fromStreambridgedart:async. - Extensible —
Receptor/Instructiontransform pipelines,Synapses+PropagationPolicycontrol delivery,Contextcarries authority, andNucleus/Cell.governedunlock high-integrity nodes.
Where plain Dart gives you a field, cell gives you a field with a
governance contract:
| Capability | Plain Dart (setState / ValueNotifier / Stream) |
cell |
|---|---|---|
| Change notification | Manual listener or stream wiring | Built-in pulse graph — every change emits |
| Transactions | None — failures leave partial state | Built-in Cell.transaction / Cell.txApply: commands with compensation, atomic staging, and rollback |
| Validation | Manual if checks at call sites |
TestCell gate on every write |
| Restricted views | None, or copying the data | Zero-copy unmodifiable / deputy proxies |
| Audit trail | None | ApplyReceipt, causal trace, provenance |
| Timing operators | Hand-rolled Timers |
debounce / throttle / distinct |
| Async combinators | Hand-rolled Future/Stream plumbing |
asyncMap (concurrency/latest/exhaust), switchMap, fromFuture/fromStream |
| Multi-source aggregation | Manual bookkeeping | Cell.synthesis fan-in |
Transaction ready, in one breath:
final counter = Cell.state<int>(initial: 0); // One audited, compensable command: final outcome = await counter.cell.command(increment) .args([5]) .undo(decrement, args: [5]) .run(); // ApplyAccepted with a receipt — or ApplyRejected, never a throw // Stage commands with recorded compensation inside a transaction ledger: final tx = Cell.txApply(); await tx.execute(participants: [counter.cell], body: (scope) { counter.cell.apply<dynamic>( ( function: increment, arguments: (positionalArguments: [5], namedArguments: null), compensation: ( function: decrement, arguments: (positionalArguments: [5], namedArguments: null), cell: counter.cell, ), ), tx: scope, ); // buffered — invisible to readers until the transaction commits }); // Or buffer several cells into one atomic commit: final tx2 = Cell.transaction(); await tx2.begin([counter.cell, settings.cell]); tx2.update(counter.cell, 5); // buffered tx2.update(settings.cell, theme); // buffered await tx2.commit(); // both land together — or neither does
Defaults are pass-through and allow-all — you can ship a counter without
learning Nucleus. Validation, deputies, provenance, and timing control are
available when you need them.
Table of Contents #
- Overview
- What's new in 1.1
- When it fits
- Install
- Quick example
- Core operators
- How much you need to know
- Documentation
- Ecosystem
- Status
- License
What's new in 1.1 #
Two headline changes shipped with the stable release.
Forensic Cell.apply #
Every mutation request is now a first-class, auditable command — not a bag of positional parameters.
final outcome = await userCell.command(updateProfile)
.args(['Simon'])
.named({#active: true})
.undo(updateProfile, args: ['Original Name'])
.run();
switch (outcome) {
case ApplyAccepted(result: final user):
print('Update successful: ${user.name}');
case ApplyRejected(reason: final error):
print('Safety gate blocked the change: $error');
case ApplyStaged():
print('Staged in the transaction ledger');
}
apply<R>(ApplyCommand, {tx}) is the only gateway: sealed ApplyOutcome<R> results, ApplyReceipt forensics, the cell.command(...) builder DSL, vetted/trusted modifiable whitelists, and Saga compensation through Cell.txApply — with validation running through the deputy's full testRule chain. The complete list is in CHANGELOG.md.
Performance #
Six optimization phases, tracked by a committed benchmark suite with a regression gate (benchmark/):
| Shape | Before | 1.1.0 |
|---|---|---|
Single-hop emit (ingress → observer) |
~170 µs | ~5–6 µs (~30×) |
Cell.distinct, duplicate-heavy |
~1.7 ms | ~8 µs (~210×) |
| Chain depth 50 | ~8.3 s (exponential) | ~12.7 ms (linear) |
Cell() construction |
~3.7 µs | ~2.1 µs |
Cell() heap footprint |
~2.7 KB | ~1.1 KB |
Run dart run benchmark/runner.dart --out current.json and compare against benchmark/baseline.json; the honest comparison story is feature-accounted in benchmark/README.md.
When it fits #
Cell is a good match if you want:
- Persistent reactive state with an explicit update path
- Events (clicks, sockets, sensors) entering the same graph as state
- Validation that is a gate, not a callback you remember to call
- Restricted views of the same data without copying it (
deputy,unmodifiable) - Multi-cell commits (
transaction) or staged commands with undo (txApply) - Debounce / throttle as library behavior rather than ad-hoc
Timers
It is more machinery than you need for a couple of flags, a basic form, or a single Future. For Rx-style combinators (merge, zip, scan, windows), use cell_flow.
Install #
The package is on pub.dev. From this monorepo:
dependencies:
cell: ^1.1.0 # stable
From git:
dependencies:
cell:
git:
url: https://github.com/simon-m-lee/cell.git
path: packages/cell
Requires Dart >=3.5.0 <4.0.0.
import 'package:cell/cell.dart';
Quick example #
import 'package:cell/cell.dart';
void main() {
final counter = Cell.state<int>(
initial: 0,
evolve: (host, input) {
final delta = input.payload as int? ?? 1;
return Pulse((host.value ?? 0) + delta);
},
);
final observer = Cell.observe(
source: counter.cell,
effect: (Pulse pulse) => print('Counter: ${pulse.payload}'),
);
counter.update(5); // prints: Counter: 5
observer.stop();
}
evolve returning null rejects the update. Omit evolve to treat update as a direct assignment.
Runnable demos live in example/. Start with example/state_demo.dart.
Core operators #
You can build most application graphs from these factories. None of them require configuring Receptor, TestCell, Context, or Synapses.
| Factory | Use when | |
|---|---|---|
| 1 | Cell.state |
Persistent mutable state |
| 2 | Cell.ingress |
Manual emit / ingest of external events |
| 3 | Cell.observe |
Side effects; start / stop |
| 4 | Cell.derive |
Pure projection of one source |
| 5 | Cell.debounce |
Emit after a silence window |
| 6 | Cell.distinct |
Skip equal consecutive payloads |
| 7 | Cell.throttle |
Cap emission frequency |
| 8 | Cell.synthesis |
Aggregate several sources |
| 9 | Cell.asyncMap |
Map each value to a Future (concurrency, latestOnly, exhaust) |
| 10 | Cell.hub |
Route by Pulse.type |
| 11 | Cell.switchMap |
Follow the latest inner cell |
| 12 | Cell.fromFuture / Cell.fromStream |
Bridge dart:async |
| 13 | Cell.sanitized |
Redact before egress |
| 14 | Cell.open |
Manual topology (emit / link) |
| 15 | Cell.transaction |
Multi-cell buffered writes |
| 16 | Cell.txApply |
Staged apply + compensation |
Also implemented, outside that numbered set: Cell.valve (predicate gate) and Cell.apply / cell.command(...) (audited mutations with receipts and Saga compensation). Fan-in of several sources is Cell.synthesis (or combinators in cell_flow).
Learning order: get data in → hold state → react → shape streams → go async → combine → isolate writes. Operators 1–4 are enough for a first app.
How much you need to know #
Layers are optional, not a reading list.
- Operators — intended default for application code.
- Pipelines and propagation — custom
Receptor/Instruction, andSynapses+PropagationPolicy, when a factory’s default is not enough. - Validation and authority —
TestCellandContext. Off by default (TestCell.allowAll,Context.system). - Internals —
Nucleus,Cell.governed,Cell.fromNucleus, lifecycle policies. For extending the framework or high-integrity nodes.
A deputy is a proxy, not a copy: cell == cell.deputy() is true. Rules on a deputy can only narrow what the principal already allows.
See ARCHITECTURE.md for the design rationale.
Documentation #
| Document | What it is |
|---|---|
| HowTo-Start.md | Walkthrough of the core concepts |
| HowTo-16_Essential_Operators.md | Operator reference and learning path |
| FEATURES.md | Source-checked feature catalog |
| ARCHITECTURE.md | Why the pieces are shaped this way |
| TEST_VERIFICATION.md | Unit-test inventory, measured coverage, and how to run the suite |
| HowTo-TestCell.md | Validation rules |
| HowTo-Synapses.md | Linking, filters, propagation |
| HowTo-Receptor.md | Transformation pipelines |
| HowTo-Instruction.md | Instruction stages |
| HowTo-Transaction.md | Buffered multi-cell writes |
| HowTo-TransactionOnApply.md | Staged apply + compensation |
| HowTo-Advanced.md | Index of optional governance machinery |
| benchmark/README.md | Benchmark suite, pass criteria, and the feature-accounted comparison story |
Guides use HowTo-*.md (hyphens). Generate API docs with dart doc . and open doc/api/index.html.
If a guide and the source disagree, the source is current.
Ecosystem #
| Package | Delivery | Adds |
|---|---|---|
| cell (this) | Now | Nodes, pulses, operators, governance, transactions |
| cell_flow | Now | 100+ instruction factories on Flow, plus fluent chaining (mapTo, asyncExpand, zip, …) |
| cell_tissue | Now | Reactive collections (list / map / set / queue) |
Flutter has no dedicated widgets here. Bind with Cell.observe (or an adapter) and drive setState or your existing state library.
Status #
Stable on pub.dev (1.1.0). Public APIs for cells, pulses, operators, transactions, and the integrity-gated apply/txApply command model are exercised by a passing unit-test suite.
Release verification:
cell1174/1174,cell_flow1091/1091,cell_tissue362/362 unit tests pass.dart analyze libreports no issues; the test files carry a few pre-existing informational lints.dart doc .completes with zero warnings;doc/apiis generated.- The benchmark suite's 60 tracked results pass the 15% regression gate (
benchmark/compare.dart). Context,PulseContext, andSensitivitylet you attach classification, actor, and purpose. They do not implement or certify GDPR, HIPAA, PCI-DSS, or any other regulation.Context.describe('…')stores text; it is not a legal basis or an audit log.
Feedback and issues are useful at this stage.
dart analyze lib
dart test
dart format .
dart doc .
License #
MIT or Apache-2.0. See LICENSE.
Authors #
Lee Man Hoi Simon. See AUTHORS for copyright holders.