EvolvedPulse class abstract interface

An immutable signal derived from a previous pulse through a transformation step — a causal link in the signal's journey.

An EvolvedPulse is what you get when you call evolve on any pulse. It carries a reference to its parent, preserving the signal's lineage without duplicating data. This is how the framework builds causal chains while keeping memory usage low.

When to use

Causal Traceability: You never implement this interface. It's returned by evolve. Use it when you need to trace a signal's transformation history — for debugging, auditing, or explainability.
Tracing a signal's journey through the reactive graph.
Debugging or auditing the evolution of a pulse.
Building causal chains for explainability (XAI).
Preserving provenance across transformation steps.
Understanding which transformations were applied to a signal.

How it works

Each evolved pulse links back to its parent — the pulse it came from.
The trace property accumulates steps from all ancestors.
The root always points to the original pulse that started the chain.
The payload is inherited from the root — evolved pulses don't duplicate it.

Non‑obvious: evolution is not mutation

EvolvedPulse is immutable. When you call evolve, you get a new pulse that points to the old one. The old pulse is still there — unchanged, available for reference — which is why you can trace the entire lineage without copying data.

Example

final root = Pulse<int>(42);
final evolved = root.evolve(step: 'validation');
print(evolved is EvolvedPulse); // true
print(evolved.parent); // root
print(evolved.trace); // ['validation']

Properties

context → PulseContext: The operational tier and security authority under which this pulse propagates.
no setterinherited
first → Pulse: The first element.
no setterinherited
hashCode → int: The hash code for this object.
no setterinherited
isComposite → bool: Indicates whether this pulse is a multi-message bundle (a collection).
no setterinherited
isEmpty → bool: Whether this collection has no elements.
no setterinherited
isGoverned → bool: Indicates whether this pulse is subject to explicit governance.
no setterinherited
isInvalidated → bool: Indicates whether this message has reached its terminal lifecycle state.
no setterinherited
isNotEmpty → bool: Whether this collection has at least one element.
no setterinherited
iterator → Iterator<Pulse>: Returns an iterator over the sub‑pulses in this pulse.
no setterinherited
last → Pulse: The last element.
no setterinherited
length → int: The number of elements in this Iterable.
no setterinherited
parent → Pulse: The immediate causal ancestor of this pulse in the processing chain.
no setter
payload → P?: The terminal data result of the evolution chain.
no setteroverride
policy → PulseEphemeralPolicy?: The lifecycle governance policy for this pulse.
no setterinherited
priority → int: The execution priority of this pulse (0‑100, higher = more urgent).
no setterinherited
root → Pulse: The primordial ancestor that initiated this pulse's causal lineage.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
shell → PulseShell<P, Receptor<Cell>>: Returns a Defensive Proxy of this pulse for untrusted receivers.
no setterinherited
single → Pulse: Checks that this iterable has only one element, and returns that element.
no setterinherited
source → Cell?: The cell that originally emitted this pulse's lineage.
no setterinherited
timestamp → DateTime: The exact moment this pulse was synthesised.
no setterinherited
trace → List<String>: An ordered sequence of steps documenting the signal's journey.
no setterinherited
type → dynamic: A semantic identifier representing the category or intent of the pulse.
no setterinherited
unmodifiable → Pulse: Returns a read‑only projection of this pulse, ensuring structural and payload-level finality for the current propagation hop.
no setterinherited

Methods

any(bool test(Pulse element)) → bool: Checks whether any element of this iterable satisfies test.
inherited
attach(dynamic context) → Pulse: Available on Pulse, provided by the PulseExtension extension
Returns a new version of this pulse with updated context metadata.
attach(dynamic context) → Iterable<Pulse>: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Returns a new collection of pulses, each with the provided context metadata attached.
batch() → Pulse: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Aggregates multiple signals into a single, flat CollectivePulse.
cast<R>() → Iterable<R>: A view of this iterable as an iterable of R instances.
inherited
cast<T>() → Pulse<T>: Available on Pulse, provided by the PulseExtension extension
Re-casts the pulse payload to type T while maintaining causal history.
compareTo(Pulse other) → int: Compares this pulse with another to determine relative execution precedence.
inherited
contains(Object? element) → bool: Whether the collection contains an element equal to element.
inherited
elementAt(int index) → Pulse: Returns the indexth element.
inherited
every(bool test(Pulse element)) → bool: Checks whether every element of this iterable satisfies test.
inherited
evolve({Pulse? pulse, String? step, covariant PulseContext? context}) → Pulse: Creates a derived version of this pulse for the next processing stage.
inherited
expand<T>(Iterable<T> toElements(Pulse element)) → Iterable<T>: Expands each element of this Iterable into zero or more elements.
inherited
firstWhere(bool test(Pulse element), {Pulse orElse()?}) → Pulse: The first element that satisfies the given predicate test.
inherited
flatten() → Iterable<Pulse>: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Recursively flattens any nested CollectivePulse structures into a sequence of simple pulses.
fold<T>(T initialValue, T combine(T previousValue, Pulse element)) → T: Reduces a collection to a single value by iteratively combining each element of the collection with an existing value
inherited
followedBy(Iterable<Pulse> other) → Iterable<Pulse>: Creates the lazy concatenation of this iterable and other.
inherited
forEach(void action(Pulse element)) → void: Invokes action on each element of this iterable in iteration order.
inherited
join([String separator = ""]) → String: Converts each element to a String and concatenates the strings.
inherited
lastWhere(bool test(Pulse element), {Pulse orElse()?}) → Pulse: The last element that satisfies the given predicate test.
inherited
lineage<T>(LineageArgument arg) → List<T>: Traverses the causal chain from the root ancestor to this pulse to reconstruct a historical timeline of values.
inherited
map<T>(T toElement(Pulse e)) → Iterable<T>: The current elements of this iterable modified by toElement.
inherited
map<T>(T mapper(P payload)) → Pulse<T>: Available on Pulse, provided by the PulseExtension extension
Transforms the payload of this pulse into a new type T while preserving its causal history.
mapEach<T>(T mapper(dynamic payload)) → Iterable<Pulse<T>>: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Transforms the payload of every pulse in the collection while preserving their individual causal traces.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
reduce(Pulse combine(Pulse value, Pulse element)) → Pulse: Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
inherited
scrutinize(covariant Receptor<Cell> receptor, List? positionalArguments, [Map<Symbol, dynamic>? namedArguments]) → dynamic: Challenges a receptor to prove it has the authority to see this pulse.
inherited
singleWhere(bool test(Pulse element), {Pulse orElse()?}) → Pulse: The single element that satisfies test.
inherited
skip(int count) → Iterable<Pulse>: Creates an Iterable that provides all but the first count elements.
inherited
skipWhile(bool test(Pulse element)) → Iterable<Pulse>: Creates an Iterable that skips leading elements while test is satisfied.
inherited
take(int count) → Iterable<Pulse>: Creates a lazy iterable of the count first elements of this iterable.
inherited
takeWhile(bool test(Pulse element)) → Iterable<Pulse>: Creates a lazy iterable of the leading elements satisfying test.
inherited
tap(void action(P payload)) → Pulse: Available on Pulse, provided by the PulseExtension extension
Executes a side-effect action using the current payload and returns this pulse instance.
toList({bool growable = true}) → List<Pulse>: Creates a List containing the elements of this Iterable.
inherited
toSet() → Set<Pulse>: Creates a Set containing the same elements as this iterable.
inherited
toString() → String: A string representation of this object.
inherited
where(bool test(Pulse element)) → Iterable<Pulse>: Creates a new lazy Iterable with all elements that satisfy the predicate test.
inherited
whereType<T>() → Iterable<R>: Creates a new lazy Iterable with all elements that have type T.
inherited
withStep(String step) → Iterable<Pulse>: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Appends a diagnostic stage to the causal trace of every pulse in this collection.
withStep(String step) → Pulse: Appends a diagnostic stage to the pulse's causal trace without branching the causal chain.
inherited

Operators

operator +(covariant Pulse other) → Pulse: Combines this pulse and other into a composite CollectivePulse.
inherited
operator ==(Object other) → bool: The equality operator.
inherited

EvolvedPulse<P> class abstract interface