evolve method
Creates a derived version of this pulse for the next processing stage.
When to use
- Next Stage Evolution: Use this when you need to change a pulse's context (authority, reason, priority) or add a trace step without losing its causal history.
- Adding a step to the causal trace.
- Updating a pulse's provenance context.
- Preserving causal history across transformations.
- Annotating a signal's journey through the graph.
How it works
You provide a new pulse (to append), a step description, and/or a
new context. The new pulse links back to this one via EvolvedPulse.parent,
preserving the history.
Causal Integrity (Enhanced Logic)
To maintain strict provenance, the framework enforces Contextual Lineage:
- If a new
contextis provided, it must be a direct descendant of the current pulse's context (context.parent == this.context). - An exception is made if the current pulse is in the
PulseContext.system(root) context, which is permitted to evolve into any specialized context. - Attempting to "jump" a pulse to an unrelated context will trigger an AssertionError.
Parameters:
pulse: An optional pulse to append to the chain.step: A descriptive string added to the trace log.context: A new PulseContext. Must be a descendant of the current context to satisfy causal integrity requirements.
Returns:
A new Pulse with the causal lineage preserved.
Example
final root = Pulse<int>(42);
// Evolution within the same context tree
final childContext = root.context.evolve(reason: 'processing');
final evolved = root.evolve(step: 'sanitization', context: childContext);
Implementation
@override
Pulse evolve({Pulse? pulse, String? step, covariant PulseContext? context}) {
// 1. Validate that the call is meaningful
assert(
pulse != null || step != null || context != null,
'Pulse.evolve requires at least `pulse` or `step` or `context` not null.',
);
// 2. Validate internal invariants (Example: Ensure we aren't evolving a pulse with itself)
assert(
!identical(this, pulse),
'A pulse cannot evolve using itself as the delta provider.',
);
// Ensure the new context is a legitimate descendant. Runtime check —
// an `assert` would evaporate in release builds and leave the lineage
// gate unenforced.
if (context != null &&
this.context != PulseContext.system &&
context._parent != this.context) {
throw StateError(
'Causal Integrity Violation: The new context must be evolved from the current pulse context.',
);
}
if (pulse != null) {
if (pulse is PulseBase) {
return pulse._asEvolvedFrom(this, step: step, context: context);
}
return _EvolvedPulse(
context: context,
step: step,
pulse: pulse as PulseBase,
parent: this);
}
return _Pulse<P>(context: context, step: step, parent: this);
}