Mitosis
Formerly the Cell Framework. One reactive graph. Three layers. Zero broken causal chains.
Mitosis is a reactive application framework for Dart that treats state, events, and their causal history as one coherent, observable graph. It is an umbrella monorepo built from three layers — Cell, Flow, and Tissue — with a growing ecosystem of companion packages (Flutter bindings and more) — that scale from a single reactive value to a fully governed application body without ever dropping the forensic trail.
Mitosis is designed for systems where why something happened matters as much as what happened: financial and transaction-heavy software, security-sensitive services, audit-bound enterprise applications, real-time coordination, and increasingly, autonomous and multi-agent systems.
New — the Mitose pipeline. The
guide/directory ships an AI-executable orchestration script that practices Precision Software Engineering: a stated design requirement is carried into running behavior, recorded, explicit, bounded, checkable, traceable, and verifiable. It runs step-by-step with one human decision at each gate, or in autonomous mode (“Mitose autonomous”) where the user opts in once after the BRD exists and the agent runs the rest of the pipeline unattended with every decision tagged and reported. See Precision Software Engineering and The Mitose Pipeline.
Table of Contents
- Why the name "Mitosis"?
- The Three Pillars
- Precision Software Engineering
- AI-assisted coding
- The Mitose Pipeline
- Repository Layout
- Architecture Philosophy
- Design Principles
- Quick Start
- Development Commands
- Documentation Map
- Project Status & Cadence
- Vision & Roadmap
- Honest Caveats
- Contributing
- License
- Authors
- Links
🧬 Why the name "Mitosis"?
In biology, mitosis is the process by which a cell divides into two daughter cells, each carrying a complete, faithful copy of the parent's DNA. Nothing is lost; every new state inherits a lineage.
That is exactly the contract this framework enforces for software state:
- every change is a Pulse — an immutable message carrying value, provenance, and context;
- every propagation preserves the causal chain — you can always ask who, why, under which authority, and what happened downstream;
- every layer built on top — Flow, Tissue, and beyond — inherits the same DNA (validation, governance, traceability) rather than re-inventing it.
The project was previously known as the Cell Framework. The rename to Mitosis reflects the move from "a reactive state library" to a broader ambition: a causally intelligible runtime for composing complex reactive systems.
The name is also a promise about the project itself: mitosis keeps dividing. The ecosystem is still growing — three layers today, and more will come online as the framework matures.
🧱 The Three Pillars
Mitosis is organized into three specialized layers. Each layer is a separate package with a single, well-scoped responsibility — and each depends on the layer below it.
| Layer | Package | Version | Biological Analogue | Responsibility |
|---|---|---|---|---|
| Core | cell | 2.1.0 |
The cell | Reactive primitives (Cell, Pulse, Receptor, Nucleus, Synapses), validation gates (TestCell), authority context (Context), deputies, transactions, the causal integrity engine, Causal Replay (effect journals, hash-chained ledgers, replay engine, what-if forks, governance replay, cell-replay CLI), and Pulse serialization (encodePulse / decodePulse, strict & lenient modes). |
| Orchestration | cell_flow | 1.2.0 |
The nervous system | 100+ Rx-shaped operators (map, filter, debounce, throttle, switchMap, mergeMap, zip, retry, bufferCount, …) as FlowInstructions compiled into the same Cell graph — no translation layer; ships an official Agent Skill (skills/cell-flow-operators/). |
| Application | cell_tissue | 1.2.0 |
The body | Governed reactive collections (TissueList, TissueSet, TissueMap, TissueQueue, TissueValue) with validation, read-only views, deputies, capacity/backpressure, async mutations, and Tissue serialization (encodeTissue / decodeTissue, per-shape fromJson factories). |
Key insight: the graph, locks, validation, and provenance live in cell. Flow only decides which pulses leave and when. Tissue decides where they are recorded and under which invariants. The layers compose without duplicating governance.
Transactions are foundation, not add-on. Cell.transaction (buffered multi-cell atomic commits) and Cell.txApply (staged commands with Saga compensation and rollback) ship in the core cell package. Flow pipelines and Tissue collections inherit them because they run on the same graph — a feature set most reactive frameworks do not offer.
Beyond the pillars
The umbrella ships additional packages alongside the three layers:
| Package | Version | Role |
|---|---|---|
| cell_flutter | 1.0.0 |
Flutter widget bindings (CellBuilder, CellSelector, CellValueBuilder, CellListener, error boundary, hooks layer, and a full test surface in package:cell_flutter/testing.dart). |
| cell_flutter_persistence | 0.1.0 |
Durable state for cell_flutter: CellPersistenceAdapter, SharedPreferences/in-memory adapters, PersistedCell. |
| cell_flutter_router | 0.1.0 |
go_router bridge: route state as a reactive cell (CellRouterState, CellRouterStateMirror, CellRouterScope, useCellRouter). |
| cell_flutter_audit | 0.1.0 |
Audit trail UI for the ApplyReceipt ledger: AuditTrailView, AuditTrailController, AuditTrailExporter, AuditEntryTile. |
| cell_flutter_devtools | 0.1.0 |
DevTools extension: the live ApplyReceipt ledger as a filterable timeline inside Flutter DevTools. |
| cell_flutter_lints | 0.1.0 |
Custom lint rules guarding the cell_flutter anti-patterns. |
🌱 Still dividing. Like the biological process it is named after, Mitosis keeps growing. These layers are the foundation — more layers will come online as the ecosystem matures.
🎯 Precision Software Engineering
Precision Software Engineering is to software what precision engineering is to a part. A stated design requirement is carried into running behavior. Every step is recorded, explicit, bounded, checkable, traceable, and verifiable. A later change, expansion, or update follows the same path, so the cycle is predictable.
Precision is not perfection. The word is borrowed from machining, where precision does not mean flawless; it means a tolerance is specified and then measured against. Mitosis does not promise bug-free software. No framework can, because defects also come from wrong requirements, ambiguous wording, and the environment. The aim is that defects are harder to introduce, easier to find, and never anonymous: when something goes wrong, you can say what was asked, where it was placed, under whose authority it changed, and what evidence says it works.
The Mitose pipeline is the working expression of that idea. It has six components and no seventh; three properties follow from them:
| Quality | What makes it true here |
|---|---|
| Recorded | The BRD, the WalkThrough, the Demo header, and the ledger are the record. A chat is not. |
| Explicit | Permanent identifiers, a parameter register, a seam sentence, a layer map. |
| Bounded | Placement rules, Real-desk deferrals, one stem per desk. Invented fields are marked. |
| Checkable | The constraint, provenance, and boundary groups fail the suite. A stated rule is not enough. |
| Traceable | Impact, coverage, and evidence are traced by permanent identifier. Unknown is treated as affected. |
| Verifiable | One ledger line per identifier, from an executed test. Reading the code is not Verified. |
| Changeable | A numbered change file. The requirements difference is confirmed first. An old acceptance does not survive. |
| Expandable and updatable | A new requirement is a new identifier. An amended one keeps its identifier. The same gates run again. |
| Predictable | The same path, the same gates, and the same fail-closed groups on every build and every later change. |
How Mitose differs from other AI-assisted coding
Most AI-assisted coding, including vibe coding, treats a prompt as sufficient intent and a plausible run as sufficient acceptance. That loop is fast, and it is a reasonable way to explore a sketch. It is not a procedure for a requirement that must later be audited, changed, or shown to match what was asked. Mitose 2 uses the same kind of model. It does not use it the same way.
| Aspect | Typical AI-assisted coding, including vibe coding | Mitose 2 |
|---|---|---|
| Source of intent | A chat prompt, revised until the output looks right | A Business Requirements Document. A prompt is not the artifact |
| When code is written | As soon as the prompt can generate | Only after the WalkThrough is accepted |
| Placement | Chosen by the model, or by taste in the prompt | Chosen by the Cell, Flow, and Tissue guides |
| Constraints | Stated in the prompt, if at all | Grepped and executed. A broken rule fails the suite |
| Validation | Added if a failure is noticed | Sits at the boundary, or is explicitly deferred |
| What counts as done | The program appears to do the thing | One ledger line per requirement, from an executed test |
| Change | A further prompt, which may rewrite the requirement | A numbered change file. An old acceptance does not survive |
| Invented facts | Thresholds and rules appear in the code and are then treated as given | Invented fields are marked. A missing parameter stays Blocked |
| Suitable for | A sketch, a spike, a first look at an idea | A requirement that must be traced, changed under control, and shown to match what was asked |
Vibe coding optimises for a fast first running version. Mitose 2 optimises for a small, measurable, attributable gap. A team may use the first to find the requirement, and the second once the requirement is worth keeping.
🧫 The Mitose Pipeline
From a business requirement to a Mitosis solution, with an AI prompt agent as the operator.
The umbrella repository ships the Mitose pipeline 2.2 in guide/: a set of AI-executable scripts with two run modes — the interactive step-by-step mode, and the opt-in autonomous mode in which the agent runs the pipeline to the end without interruption. A user provides a business requirement, and an AI prompt agent follows guide/HowTo-Mitose.md to build a solution on the three pillars — Cell (core), Flow (orchestration), and Tissue (application) — and to write the project documents that go with it, including a residual ledger of executed evidence.
⚠️ Honest scope. The AI-executable scripts in
guide/are agentic tooling, not a validated code-generation service. Output quality depends on the model (best to select a model which is built for agentic coding), the uploaded guide files, and the quality of the BRD. Treat every generated BRD, WalkThrough, Demo, ARCHITECTURE, and FEATURES as a first draft, and review it against the layer HowTos and live pub.dev APIs before relying on it.
Designed for AI coding agents
The framework itself is designed to be operated by an AI coding agent, and the
AI-facing API discovery surface is built in throughout cell, cell_flow,
and cell_tissue. Every top public symbol carries a machine-readable
### AI Agent Guide block — layer, when to use / when NOT to use, a pinned
Live signature:, sibling disambiguation, a guide pointer, and a minimal
compilable example — and each package ships a verification surface around
those blocks:
| Surface | What it gives the agent |
|---|---|
lib/doc/api_chooser.dart |
A generated, pub.dev-rendered "BRD sentence → factory / operator / book" decision matrix. |
tool/ai_preflight.dart |
A one-line check that every Live signature: pin matches the resolved package version. |
tool/generate_ai_examples.dart + test/ai_guide_examples_test.dart |
Every doc-comment example is compiled (dart analyze) and executed in CI. |
test/seam_test.dart |
The Mitose seam rules (TestCell vs TestTissue; no Tissue writes inside instructions) fail the package's own suite. |
tool/ai_failure_log.dart + tool/ai_failure_log.jsonl |
Structured AI failure records feeding the LEDGER "Did you try this?" feedback loop. |
The point: an agent can reliably architect — pick the right layer,
factory, operator, and seam — and generate code that compiles against the
live API instead of guessing from memory. The normative spec is
packages/cell/CONTRIBUTING-AI-DOC.md;
each package README opens with its own "AI agents start here" section.
How it runs (step-by-step)
The agent follows the pipeline in order, with one human decision at each gate:
- BRD gate (B1) — a Business Requirements Document must exist before anything else. The user can upload a filled
<stem>-BRD.md, fill the offline template, take the guided interview, or paste a short requirement for the agent to draft. - WalkThrough — the agent follows
WalkThrough-AI-Generator.md, consulting the layer HowTos, and writes<stem>-WalkThrough.md. A short comprehension check (C1) is offered before acceptance. Skipping is allowed. - Demo — only after acceptance, the agent generates
<stem>-Demo.dartand<stem>-test.darttogether. Decision logic stays importable.Cell.txApplyon Tissue is the atomic commit;Cell.transactionis not used. - Assessment — the agent revisits the WalkThrough against the Dart file and fills Demo Assessment (§5.12) and Recommendations. It then offers three choices for any recommendation: as a Change (CHANGE path), in place, or skip.
- Residual ledger — on request, the agent writes
<stem>-LEDGER.mdfrom theLEDGERlines printed by the test file’s BRD group. Verified requires an executed run. Blocked rows carry a mitigation plan. - ARCHITECTURE & FEATURES — offered last and generated only on request, from the running Demo and the filled WalkThrough. They must not treat a Blocked or Unverified row as handled.
Autonomous mode
After a filled BRD exists, the user can opt in once at gate A1 — say “Mitose autonomous” — and the agent runs the rest of the pipeline to the end without interruption or further input:
- Every later gate becomes a recorded automatic decision. Open questions, thresholds, and rule precedence are decided by the agent and tagged
[AI DECIDED — autonomous]; residual acceptance is recorded as a delegation, never as the user’s own approval. - The comprehension check is skipped. The agent ensures a Dart runtime, adds
package:cell,package:cell_flow, andpackage:cell_tissue, implements the WalkThrough in full, and writes and tests a Demo that covers every testable BRD requirement ID. - Guardrails stay in force: autonomy starts only after the BRD exists, never applies to change mode, never overwrites an existing file, never marks a row Verified without an executed run, and stops and reports instead of asking when a required script or HowTo cannot be read. The final report lists every autonomous decision.
What the pipeline produces
<stem>-BRD.md
<stem>-WalkThrough.md
<stem>-Demo.dart
<stem>-test.dart
<stem>-LEDGER.md
<stem>-COMPREHENSION.md
<stem>-ARCHITECTURE.md
<stem>-FEATURES.md
<stem>-CHANGE-<nnn>.md (change mode only)
Every generated file carries Version: MAJOR.MINOR.PATCH and Supersedes: in its name plate. Later steps resolve only the latest version.
The guide scripts
| Script | Role |
|---|---|
HowTo-Mitose.md |
Orchestration 2.2 — runs the whole pipeline, step-by-step or autonomous (§15). |
HowTo-Mitose-Cell.md |
Where a requirement lands in the Cell layer. |
HowTo-Mitose-Flow.md |
Where a requirement lands in the Flow layer. |
HowTo-Mitose-Tissue.md |
Where a requirement lands in the Tissue layer. |
BRD-AI-Interview.md |
Guided interview that writes <stem>-BRD.md. |
Business_Requirements_Document.md |
Offline BRD template 2.0. |
WalkThrough-AI-Generator.md |
Generates <stem>-WalkThrough.md. |
LEDGER-AI-Generator.md |
Generates <stem>-LEDGER.md from the test report. |
COMPREHENSION-AI-Generator.md |
Comprehension checks and decision log. |
CHANGE-AI-Generator.md |
Change mode; writes <stem>-CHANGE-<nnn>.md. |
ARCHITECTURE-AI-Generator.md |
Generates <stem>-ARCHITECTURE.md. |
FEATURES-AI-Generator.md |
Generates <stem>-FEATURES.md. |
Every document-generation step follows the individual generator named directly by HowTo-Mitose.md (pipeline v2.2 removed the separate master generator). This applies in both step-by-step and autonomous mode — a document produced without following its named generator is invalid (Rule 25).
Start the pipeline by opening guide/HowTo-Mitose.md with an AI prompt agent, or by saying “Mitose” / “run Mitose” in chat. For an existing solution say “Mitose change”. Once a filled <stem>-BRD.md exists, say “Mitose autonomous” to opt in once and run the rest of the pipeline unattended.
Start in one paste
If your AI chat tool does not auto-load the repository, paste this and replace the last line:
Read guide/HowTo-Mitose.md and run the Mitose pipeline.
The repository is the cell workspace.
My business requirement is: <paste your requirement here>
In an agentic IDE (Copilot, Codex, Cursor, …), just open the repository and say “Mitose” — AGENTS.md tells the agent what to do.
Try a sample BRD
example/BRD/ ships ready-made BRDs from different industries. Read them to get familiar with the BRD format, or hand one to the agent to run the whole pipeline right away. Add “Mitose autonomous” to run the rest unattended once the sample BRD is in place.
Read guide/HowTo-Mitose.md and run the Mitose pipeline.
Use example/BRD/airport_baggage_handling-BRD.md as the BRD.
📦 Repository Layout
cell/ # Umbrella monorepo: "Mitosis"
├── guide/ # Mitose pipeline — AI-executable orchestration scripts
│ ├── HowTo-Mitose.md # Pipeline orchestration: BRD → WalkThrough → Demo → ARCHITECTURE/FEATURES
│ ├── HowTo-Mitose-Cell.md # Cell layer placement rules
│ ├── HowTo-Mitose-Flow.md # Flow layer placement rules
│ ├── HowTo-Mitose-Tissue.md # Tissue layer placement rules
│ ├── BRD-AI-Interview.md # Guided BRD interview
│ ├── Business_Requirements_Document.md
│ ├── WalkThrough-AI-Generator.md
│ ├── LEDGER-AI-Generator.md
│ ├── COMPREHENSION-AI-Generator.md
│ ├── CHANGE-AI-Generator.md
│ ├── ARCHITECTURE-AI-Generator.md
│ └── FEATURES-AI-Generator.md
├── packages/
│ ├── cell/ # Core layer — reactive primitives, causal integrity & Causal Replay
│ │ ├── lib/ # cell.dart, pulse, receptor, nucleus, synapses, replay/…
│ │ ├── example/ # Runnable demos (state, asyncMap, transaction, replay forensics…)
│ │ ├── guide/ # HowTo-*.md learning path (incl. HowTo-Causal-Replay.md)
│ │ ├── benchmark/ # Micro/macro/memory suite, baseline.json, 15% regression gate
│ │ └── test/
│ ├── cell_flow/ # Orchestration layer — 100+ Flow operators
│ │ ├── lib/ # flow.dart, flow_core, fluent_operator, instruction/
│ │ ├── example/ # Search, checkout, ICU alarm, batching demos…
│ │ ├── guide/
│ │ ├── benchmark/ # Per-operator cost pins, baseline.json, 15% regression gate
│ │ └── test/
│ ├── cell_tissue/ # Application layer — reactive collections
│ │ ├── lib/ # tissue_list, tissue_map, tissue_queue, …
│ │ ├── example/ # Flow + Tissue seam demos (payments, dispatch, grid)
│ │ ├── guide/
│ │ ├── benchmark/ # Per-shape mutation/propagation suite, baseline.json, 15% regression gate
│ │ └── test/
│ ├── cell_flutter/ # Flutter bindings — widgets, hooks, testing surface
│ │ ├── lib/ # cell_flutter.dart, hooks.dart, testing.dart
│ │ ├── example/ # Async search + production_app dogfooding app
│ │ │ │ # + migration/ (Riverpod / BLoC / Cell reference apps)
│ │ ├── guide/ # Widget/hooks/migration guides
│ │ ├── benchmark/ # ValueListenableBuilder / Riverpod / Bloc comparisons
│ ├── cell_flutter_persistence/ # Durable state adapters for cell_flutter
│ ├── cell_flutter_router/ # go_router bridge for cell_flutter
│ ├── cell_flutter_audit/ # Audit trail widgets over ApplyReceipts
│ ├── cell_flutter_devtools/ # DevTools extension (ledger timeline)
│ ├── cell_flutter_devtools_extension/ # Extension web app source (publish_to: none)
│ ├── cell_flutter_lints/ # custom_lint rules for cell_flutter anti-patterns
│ ├── mitose_flutter/ # Repository-private (publish_to: none) — kept out of version control
│ ├── cell_mind/ # Workspace member — repository-private (kept out of version control)
│ └── cell_organ/ # Workspace-private (publish_to: none)
├── demo/ # Standalone Flutter web demos
│ └── audit_trail/ # Live "Audit Trail" demo — apply receipts, TestCell gate, txApply undo
├── example/ # Umbrella demos — (Cell) instruction-side editions
│ ├── card-auth-pipeline(Cell)-* # stock-operator FlowInstructionChain
│ ├── grid-demand-response(Cell)-* # custom GridDecisionInstruction
│ ├── ride-hail-dispatch(Cell)-* # custom MatchDecisionInstruction
│ ├── *-BRD.md # BRD companions for the (Cell) demos
│ └── BRD/ # Sample BRDs by industry — learn the format, or run Mitose right away
├── DEMO_GUIDE-Mitosis.md # Mitosis demo guide (decision-side learning path)
├── melos.yaml # Monorepo scripts (analyze, test, format, build)
├── pubspec.yaml # Dart workspace definition (pub workspaces)
├── CHANGELOG.md
├── AGENTS.md # AI-agent instructions — the "Mitose" trigger
├── AUTHORS
└── LICENSE
The repository is managed with Melos on top of Dart's native pub workspaces.
🏗️ Architecture Philosophy
Mitosis uses a biological metaphor to separate concerns while keeping a strict forensic trail:
┌──────────────────────────────────────────────────────────────────────┐
│ APPLICATION LAYER (Tissue) The "Body" │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ TissueList │ │ TissueSet │ │ TissueMap │ │
│ │ (Ordered) │ │ (Unique) │ │ (Key-Value) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ TissueQueue │ │ TissueValue │ Governed collections: │
│ │ (FIFO/bound) │ │ (Scalar) │ observable · validated · │
│ └──────────────┘ └──────────────┘ deputy-able · thread-safe │
├──────────────────────────────────────────────────────────────────────┤
│ ORCHESTRATION LAYER (Flow) The "Nervous System" │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ 90+ operators: map, filter, debounce, throttle, asyncMap, │ │
│ │ switchMap, mergeMap, concatMap, exhaustMap, zip, combineLatestWith│
│ │ groupBy, bufferCount, retry, timeout, sample, scan, … │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ Decides WHICH pulses leave and WHEN — nothing more. │
├──────────────────────────────────────────────────────────────────────┤
│ CORE LAYER (Cell) The "Cell / DNA" │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Cell, Pulse, Receptor, Synapses, Nucleus, TestCell, Context, │ │
│ │ Deputy, Modifiable, transactions, causal integrity engine │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ Owns the graph, the locks, the validation, and the provenance. │
└──────────────────────────────────────────────────────────────────────┘
▲ ▲
└──────────── one graph · one causal trail · one DNA ────────┘
One DNA across all three layers. The same graph, locks, validation, and provenance are shared by Cell, Flow, and Tissue — every layer you build on top inherits the same causal guarantees instead of re-inventing them.
🧭 Design Principles
These are the non-negotiables that shape every package in the monorepo:
- Progressive disclosure. A counter app needs only
Cell.state. You should not have to learnNucleus,TestCell, orSynapsesuntil you need them. Defaults are pass-through and allow-all. - Causal integrity. Every state transition travels as an immutable
Pulsethat carries what changed, what caused it, and the context/authority under which it occurred. The trail is a property of the graph, not a logging afterthought. - Governance as a gate, not a callback. Validation (
TestCell,TestTissue) is enforced by the graph before a mutation commits — it cannot be forgotten. - Deputies narrow authority. Share restricted, read-only, or ephemeral views of the same data (
deputy,unmodifiable) without copying it. A deputy can only narrow what the principal allows — never widen it. - Forensic traceability. Pulses, provenance, and context make systems auditable and reconstructable — a chain of computation you can inspect, not just a final value.
- Biological scaling. Each layer is a scale of composition, not a feature silo. Higher layers inherit the DNA of lower layers instead of replacing it.
🚀 Quick Start
Prerequisites
- Dart SDK:
>=3.5.0 <4.0.0. - Melos: install globally to manage the monorepo:
dart pub global activate melos
Using from pub.dev
The umbrella package re-exports all three layers in one import:
dependencies:
mitosis: ^3.1.0
import 'package:mitosis/mitosis.dart';
Prefer the individual layers when you want fine-grained dependencies:
dependencies:
cell: ^2.1.0
cell_flow: ^1.2.0
cell_tissue: ^1.2.0
cell_flutter: ^1.1.0 # Flutter apps
ℹ️ These are the stable versions on pub.dev —
mitosis3.1.0together withcell2.1.0,cell_flow1.2.0,cell_tissue1.2.0, and thecell_flutterfamily (cell_flutter1.1.0;cell_flutter_persistence,cell_flutter_router,cell_flutter_lints,cell_flutter_audit,cell_flutter_devtools0.1.0).
Each layer package ships an official Agent Skill for AI coding
agents — install them with dart run skills@ get cell,
dart run skills@ get cell_flow, or dart run skills@ get cell_tissue.
The skill carries the factory/operator/book-picking rules and the
generated API-chooser matrix, versioned with the package.
The workspace setup below is only needed for contributors working on the framework itself.
Workspace Setup
# 1. Clone the repository
git clone https://github.com/simon-m-lee/cell.git
cd cell
# 2. Bootstrap the workspace (install dependencies + cross-link local packages)
melos bootstrap
# 3. Verify everything is healthy
melos analyze
melos test
Hello Mitosis — all three layers in one flow
The canonical pattern: Flow decides. Tissue records. The observer is the only glue.
import 'package:cell_flow/cell_flow.dart'; // Cell + Flow operators
import 'package:cell_tissue/cell_tissue.dart'; // Tissue collections
Future<void> main() async {
// 1. CELL — events enter the graph through an ingress
final commands = Cell.ingress<String>();
// 2. FLOW — orchestration: normalize, gate, deduplicate, debounce
final accepted = commands.cell
.map<String, String>(project: (c) => c.trim())
.filter<String>(test: (c) => c.isNotEmpty)
.distinct<String>()
.debounce<String>(duration: const Duration(milliseconds: 150));
// 3. TISSUE — application state: a governed, observable collection
final ledger = TissueList.of(<String>[]);
Cell.observe(
source: accepted.cell,
effect: (Pulse pulse) => ledger.add('ACCEPTED: ${pulse.payload}'),
);
await commands.emitAsync(' deploy mitosis ');
await commands.emitAsync(' deploy mitosis '); // distinct + debounce
await Future<void>.delayed(const Duration(milliseconds: 200));
print(ledger); // [ACCEPTED: deploy mitosis]
}
Each package's README has deeper walkthroughs:
packages/cell/guide/HowTo-Start.md— core conceptspackages/cell_flow/guide/HowTo-Start.md— 15-minute pipeline tutorialpackages/cell_tissue/README.md— collections, deputies, and the Flow + Tissue seam
🛠️ Development Commands
Melos scripts run across every package in the workspace:
| Task | Command | Description |
|---|---|---|
| Analyze | melos analyze |
Static analysis on all packages |
| Test | melos test |
Run all package test suites |
| Format | melos format |
Format the entire codebase |
| Build | melos build |
Regenerate generated code (build_runner) |
Single-package workflows are also supported, e.g.:
cd packages/cell_flow
dart test
dart run example/stability_search_demo.dart
📚 Documentation Map
| Document | What it is |
|---|---|
| packages/cell/README.md | Core layer: operators, governance, deputies, transactions, Causal Replay |
| packages/cell_flow/README.md | Orchestration layer: full operator catalog, patterns, testing |
| packages/cell_tissue/README.md | Application layer: collections, validation, Flow + Tissue seam |
| DEMO_GUIDE-Mitosis.md | Mitosis demo guide — the (Cell) instruction-side learning path |
| guide/HowTo-Mitose.md | Mitose pipeline orchestration — AI-executable script: BRD → WalkThrough → Demo → ARCHITECTURE/FEATURES |
| guide/HowTo-Mitose-Cell.md · Flow · Tissue | Layer placement guides the Mitose pipeline consults |
| guide/BRD-AI-Interview.md · BRD template | BRD interview script and offline template |
| guide/WalkThrough-AI-Generator.md · LEDGER · COMPREHENSION · CHANGE · ARCHITECTURE · FEATURES | Document generators: WalkThrough, ledger, comprehension, change, ARCHITECTURE, FEATURES |
| example/BRD/ | Sample BRDs by industry — learn the BRD format, or run the Mitose pipeline right away |
| CHANGELOG.md | Umbrella release history |
If a guide and the source disagree, the source is current.
📌 Project Status & Cadence
| Package | Version | Status |
|---|---|---|
mitosis |
3.1.0 |
Stable — on pub.dev |
cell |
2.1.0 |
Stable — on pub.dev (Causal Replay + Pulse serialization) |
cell_flow |
1.2.0 |
Stable — on pub.dev |
cell_tissue |
1.2.0 |
Stable — on pub.dev (Tissue serialization) |
cell_flutter |
1.1.0 |
Stable — on pub.dev |
cell_flutter_persistence |
0.1.0 |
New — on pub.dev |
cell_flutter_router |
0.1.0 |
New — on pub.dev |
cell_flutter_lints |
0.1.0 |
New — on pub.dev |
cell_flutter_audit |
0.1.0 |
New — on pub.dev |
cell_flutter_devtools |
0.1.0 |
New — on pub.dev |
Mitosis is the umbrella codename for the release line. It is not part of any package's SemVer string. The stable release line is cell 2.1.0, cell_flow 1.2.0, cell_tissue 1.2.0, the cell_flutter family (1.1.0 / 0.1.0), and mitosis 3.1.0 — these are the versions dart pub add resolves from pub.dev.
The umbrella version is independent of the Mitose pipeline version. The Mitose pipeline (guide/HowTo-Mitose.md, currently v2.2) and the mitosis package each carry their own SemVer. The umbrella version changes when the umbrella's own contents change — packages added to or removed from the set, re-export changes, or umbrella-level documentation — and the pipeline version changes when the pipeline changes. The two do not track each other: pipeline releases can happen without an umbrella release, and umbrella releases can carry package additions (such as the cell_flutter family) that are unrelated to the pipeline.
Umbrella 3.0.0 (MAJOR). This release bumps the umbrella's dependency floor to cell 2.0.0. The umbrella's own source is unchanged, but the bump is MAJOR because mitosis re-exports package:cell/cell.dart: the breaking change in cell 2.0.0 — Cell.asyncMap, Cell.fromFuture, Cell.fromStream, Cell.debounce, and Cell.throttle now require an EffectJournal — is therefore a breaking change for mitosis consumers who use those re-exported symbols. Code that compiled against mitosis 2.2.1 (which resolved cell 1.1.x) will not compile against 3.0.0. A dependency-floor change that exposes breaking changes through the package's own public surface is a MAJOR bump even when the package itself carries no code changes. This bump is driven by the package set, not by the Mitose pipeline.
Umbrella 3.1.0 (MINOR). This release bumps the dependency floors to cell 2.1.0, cell_flow 1.2.0, and cell_tissue 1.2.0, and publishes the umbrella against the new package set (including the cell_flutter 1.1.0 line and the new audit/devtools companions). The bump is MINOR because everything added since 3.0.0 — pulse serialization, tissue serialization, and the layer packages' Agent Skills — is additive through the umbrella's re-exported surface; no symbol that worked under 3.0.0 changes meaning or disappears. This bump is driven by the package set, not by the Mitose pipeline.
🔭 Vision & Roadmap
Mitosis is not aiming to be "another state-management library". The ambition is a layered platform for causally intelligible reactive systems — where application behavior is composable, traceable, governable, and explainable from the same graph.
The Mitose pipeline in guide/ is the first agentic workflow shipped with the project — an AI prompt agent turns a business requirement into a Cell + Flow + Tissue solution and its full document set. It is how this umbrella repository is meant to be operated day to day.
Target domains
Mitosis pays for itself first in systems where the causal trail is a requirement, not a nicety:
- 💳 Payments & fintech — holds, captures, invariants (
available + held + captured == constant) - 🏥 Safety-critical telemetry — alarm pipelines, sensor fusion, escalation logic
- ⚡ Energy & real-time grids — demand response, shed/restore decisions, audit logs
- 🚗 Mobility & dispatch — matching, surge control, trip logs
- 🔐 Security-sensitive services — authority tiers, redaction, restricted deputies
- 🤖 Agents & automation — tool-call graphs with traceable intent and effect
🧾 Honest Caveats
The stable release line on pub.dev is mitosis 3.1.0 with cell 2.1.0, cell_flow 1.2.0, and cell_tissue 1.2.0, plus the Flutter family (cell_flutter 1.1.0; cell_flutter_persistence, cell_flutter_router, cell_flutter_lints, cell_flutter_audit, and cell_flutter_devtools 0.1.0). Some things to know before you bet production on it:
- The Mitose pipeline is agentic tooling, not a validated code-generation service — see The Mitose Pipeline. Output quality depends on the model (best to select a model which is built for agentic coding), the uploaded guide files, and the quality of the BRD. Treat every generated BRD, WalkThrough, Demo, ARCHITECTURE, and FEATURES as a first draft, and review it against the layer HowTos and live pub.dev APIs before relying on it.
- New layers and packages may still appear. The umbrella keeps growing: the
cell_flutterfamily shipped in the2.0.0line, and repository-private members (cell_mind, …) carry their own pre-release or unpublished status. The umbrella version moves with the package set, not with the Mitose pipeline. Contextmetadata is not a compliance certification.Context.describe(...)stores classification, actor, and purpose text; it does not implement or certify GDPR, HIPAA, PCI-DSS, or any other regulation.- The framework is deliberately layered. For a couple of flags or a single form, plain Dart or a lightweight notifier may be the better tool. Mitosis earns its complexity at scale.
🤝 Contributing
Contributions are welcome across all layers:
- Fork the repository and create a topic branch.
- Run
melos analyzeandmelos testlocally. - Add tests for new behavior.
- Submit a pull request with a clear description.
See the individual package READMEs for package-specific conventions.
📄 License
Dual-licensed under either of:
- MIT License
- Apache License, Version 2.0
See the LICENSE file for full text. Operator names follow ReactiveX vocabulary; implementations are original.
👤 Authors
Lee Man Hoi Simon — see AUTHORS for copyright holders.
🔗 Links
- 🏠 Repository: github.com/simon-m-lee/cell
- 🐛 Issues: github.com/simon-m-lee/cell/issues
- 📦 pub.dev: cell · cell_flow · cell_tissue · cell_flutter · cell_flutter_persistence · cell_flutter_router · cell_flutter_audit · cell_flutter_devtools · cell_flutter_lints
- 📖 Core layer: packages/cell
- 🔀 Orchestration layer: packages/cell_flow
- 🧩 Application layer: packages/cell_tissue
- 📱 Flutter bindings: packages/cell_flutter
- 🛠 DevTools extension source: packages/cell_flutter_devtools_extension
- 🎬 Live audit demo: demo/audit_trail · deployed at simon-m-lee.github.io/cell/audit-trail
Mitosis — reactive state that remembers how it got there.
Libraries
- mitosis Walkthroughs
- 🧬 Mitosis — the unified reactive framework for Dart.
Walkthroughs
DEMO_GUIDE-Mitosis.md (Mitosis Edition)