evolve method

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

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

@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);
}