TestCell<C extends Cell> class Testing & Validation

The central validation gate for a Cell – it decides what's allowed.

Every reactive node has a TestCell that governs four kinds of actions:

• State changes (the core validation)
• Function execution (TestActionRule)
• Linking (TestLinkRule)
• Pulse processing (TestPulseRule)

You compose individual rules into a single policy using the + operator.

When to use

Most of the time you don't need to build a TestCell from scratch. Start with one of the predefined policies:

• allowAll – the default, no restrictions.
• readOnly – blocks mutations, allows observation.

To define your own, use the constructor with a simple validation function, then compose with others:

final isPositive = TestCell<int>((value, {host, arguments, user}) => value > 0);
final hasPermission = TestCell<Cell>((_, {host, ...}) => host.context.hasRole('admin'));
final policy = isPositive + hasPermission;

Use TestCell whenever you need to enforce business rules, security boundaries, or data integrity on a cell. The framework uses it internally for every validation, but you can supply your own when creating a cell:

final cell = Cell(testRule: myPolicy);

How it works

• The TestCell is attached to a cell at creation time.
• Every operation (state change, action, link, pulse) passes through the TestCell's validation pipeline.
• The pipeline is a chain of rules; each rule returns true to allow or false to block.
• Rules can be synchronous or asynchronous (FutureOr<bool>).
• The + operator composes rules into a single TestCell that evaluates them in sequence (short‑circuiting on false).

Non‑obvious

• A deputy (created via Cell.deputy) gets its own TestCell, layered on top of the principal's rule. You can narrow permissions, never widen.
• If a rule throws an exception, the framework treats it as a true (pass) when the host is ungoverned, or false (fail) when governed.
• The TestCell is a flyweight – many cells can share the same policy instance without extra memory.

Example: A complete policy

final rangeRule = TestCell<int>((value, ...) => value >= 0 && value <= 100);
final actionRule = TestActionRule<Cell>((action, ...) => action is ReadAction);
final linkRule = TestLinkRule<Cell>((link, ...) => link.context.domains == host.context.domains);
final pulseRule = TestPulseRule<Cell>((pulse, ...) => pulse.priority > 50);

final policy = rangeRule + actionRule + linkRule + pulseRule;

See also:

• TestActionRule for action‑specific validation.
• TestLinkRule for link‑specific validation.
• TestPulseRule for pulse‑specific validation.
• TestRule for the base validation contract.

• HowTo: See guide/HowTo-TestCell.md for a guide on implementing custom validation policies and integrity gates.