evolve abstract method

Pulse evolve({
  1. Pulse? pulse,
  2. String? step,
  3. covariant PulseContext? context,
})

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 context is 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

Pulse evolve({Pulse? pulse, String? step, covariant PulseContext? context});