apply abstract method

dynamic apply(
  1. Function function, {
  2. List? positionalArguments,
  3. Map<Symbol, dynamic>? namedArguments,
  4. ApplyTransactionScope? tx,
  5. Function? compensate,
  6. List? compensatePositional,
  7. Map<Symbol, dynamic>? compensateNamed,
  8. Cell? compensateCell,
})

Executes a State Transition or arbitrary logic via the Command Pattern gateway.

apply serves as the primary enforcement mechanism for a Cell, bridging the gap between compile-time governance and runtime Integrity Gate validation.

When to use

  • Somatic State Transitions: When you need to perform direct mutations or execute business logic that is whitelisted in modifiable.
  • Transaction Orchestration: When performing multiple, related updates that must succeed or fail as a single atomic unit using an ApplyTransactionScope.
  • Compensating Transactions: Defining reversal logic (compensate) for SAGA-like patterns or complex state recovery.
  • Dynamic Command Injection: Executing logic that is determined at runtime but must still pass through the node's security perimeter.

How it works

  1. Capability Scrutiny: The method verifies if the provided function is present in the modifiable manifest.
  2. Integrity Gate Validation: The request triggers a Reciprocal Handshake with the cell's TestCell. The intent is evaluated against the node's security invariants and administrative mandates.
  3. Causal Anchor: A new internal stimulus is synthesized, carrying the Causal Provenance (trace ID, timestamp, and operational context).
  4. Execution & Propagation: If authorized, the function is executed within the requested tx scope. The result is then broadcast through the Egress Gateway to all downstream receptors.
  5. Compensate Registration: If a compensate function is provided, it is registered to be invoked if the transaction fails or requires rollback.

Non‑obvious

  • Short-Circuit Rejection: If the Integrity Gate rejects the action, the method returns null immediately without triggering any reactive waves.
  • Transaction Isolation: Operations within an ApplyTransactionScope prevent "Glitch" states by ensuring downstream observers only see the final, committed transition.
  • Flyweight Strategy: The framework utilizes Record-based storage for command metadata to minimize heap pressure during high-frequency mutations.
  • Causal Lineage: Even failed attempts are recorded in the system audit log (if enabled), preserving the trace of the rejected stimulus.
// Define a whitelisted mutation
void increment(int amount) => value += amount;

// Execute via the Command Pattern gateway
final result = myCell.apply(
  increment,
  positionalArguments: [5],
  compensate: (int amount) => value -= amount,
);

if (result == null) {
  print('Action rejected by Integrity Gate');
}

Parameters:

  • function: The Command Anchor. A reference to the whitelisted function to be executed.
  • positionalArguments: Optional arguments passed to the function by index.
  • namedArguments: Optional arguments passed to the function by Symbol keys.
  • tx: The Transaction Scope. An optional handle to group multiple operations into an atomic wave.
  • compensate: The Reversal Logic. A function executed if the transaction needs to be rolled back.
  • compensatePositional: Arguments for the compensation function.
  • compensateNamed: Named arguments for the compensation function.
  • compensateCell: An optional target cell for the compensation logic.

Returns:

The result of the executed function if authorized and validated; otherwise null.

See Also:

  • Example: See example/atomic_multi_update.dart for a walkthrough of bank transfer logic and multi-node consistency.

Implementation

dynamic apply(
  Function function, {
  List? positionalArguments,
  Map<Symbol, dynamic>? namedArguments,
  ApplyTransactionScope? tx,
  Function? compensate,
  List? compensatePositional,
  Map<Symbol, dynamic>? compensateNamed,
  Cell? compensateCell,
});