txApply static method

ApplyTransactionScope txApply([
  1. TxApplyOptions options = const TxApplyOptions()
])

An Atomic Evolution Sequencer that executes multiple state mutations within a single coordinated transaction.

When to use:

  • Multi-Cell Consistency: Updating multiple cells (e.g., a balance and ledger) where partial updates would break graph integrity.
  • Performance Optimization: Batching high-frequency updates to prevent redundant downstream "churn" or multiple UI repaints.
  • Cyclic Dependency Guards: Coordinating updates that might otherwise trigger race conditions if executed in isolation.

How it works:

txApply opens a "Transaction Frame." All updates performed within the scope are staged. Only when the scope completes successfully are the changes committed and propagated through the reactive graph. If an error occurs, the staged pulses are discarded (rolled back).

Parameters:

  • options: Configuration including the action closure, security context, conflict policy, and whether to wait for stabilization.

Returns:

An ApplyTransactionScope result indicating success, timing, and forensic metadata for the committed batch.

See Also:

  • Cell.state: The primary target for transactional updates.
  • TransactionOptions: For advanced isolation and locking controls.
  • Example: See example/atomic_multi_update.dart for a walkthrough of bank transfer logic and multi-node consistency.

AI Agent Guide

Layer: Cell — this is a graph node. Not an operator (Flow), not a book (Tissue). When to use: The BRD says two retained facts move together or not at all, or an external act can fail after a local write — participants are Tissue books, with apply + compensate. When NOT to use: one book with no undo (an ordinary Tissue write from Cell.observe); never wrap riskOf (policy is pure). Live signature: Cell.txApply([TxApplyOptions options = const TxApplyOptions()]) → ApplyTransactionScope — pinned at cell: 1.1.0 Do NOT confuse with: Cell.transaction (coordinates ValueCell, not Tissue). Guide: HowTo-Mitose-Cell.md §3.4 "Cell.txApply — the only atomic commit, on Tissue" (#cell-txapply) Example: example/atomic_multi_update.dart Cross-layer: the books written inside the commands are cell_tissue collections. Minimal compilable example

final counter = Cell.state<int>(initial: 0);
final tx = Cell.txApply();
await tx.execute(participants: [counter.cell], body: (scope) {
  counter.update(5); // staged — committed when execute completes
});
print(counter.cell.value);

Implementation

static ApplyTransactionScope txApply([
  TxApplyOptions options = const TxApplyOptions(),
]) =>
    _txApply(options);