CausalityZone class

Provides causal context propagation through Dart Zones.

The core insight: Dart Zones carry arbitrary metadata that survives across await boundaries, Future.then() chains, StreamController callbacks, and any other standard async mechanism — without requiring any changes to the async code itself.

Usage

// In a gesture handler:
CausalityZone.run('user_tapped_login', () async {
  await authService.login(email); // Zone context survives this await
  stateManager.update(result);    // Zone context still readable
});

// Anywhere downstream:
final context = CausalityZone.currentContext();
print(context?.originDescription); // "user_tapped_login"

What breaks Zone propagation

• Isolates: Zone context does NOT cross isolate boundaries (use ReceivePort bridge with manual context threading).
• Platform channels: Native callbacks do NOT carry Zone context.
• C FFI: Does not propagate Zones.

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

createContext(String description) → CausalityContext

Creates and returns a new CausalityContext without forking a Zone.

currentContext() → CausalityContext?

Returns the CausalityContext for the current execution context, or null if not running inside a CausalityZone.run call.

run<T>(String description, T fn()) → T

Runs fn inside a new Zone that carries a CausalityContext.