Pulse<P> class abstract interface

A reactive signal — the fundamental unit of communication in the framework.

A Pulse is an immutable message that carries data, provenance, and governance metadata through the reactive graph. It's the signal that cells emit and observe — the "currency" of the switching fabric.

When to use

• Communication: Most of the time, you don't create pulses directly. Cells do it for you:
  • Cell.ingress wraps external events in pulses.
  • Cell.state emits pulses when state changes.
  • Cell.derive transforms pulses into new pulses.
• Manual Injection: When you do need to create one, use the simple factory:

final pulse = Pulse('Hello, World!');

What a pulse carries

• payload: the actual data (the signal's content).
• type: a semantic classification for routing and filtering. It is commonly a String tag, but may be any object (such as an enum).
• priority: urgency (0‑100, higher = more urgent).
• context: provenance — who sent it, why, with what clearance.
• trace: a breadcrumb trail of transformations.
• policy: lifecycle constraints (TTL, hop limit).

How it works

Pulses are immutable — you can't change one. To "update" a pulse, you evolve it, creating a new pulse that links back to the original. This is how the framework preserves causal history without duplicating data.

Non‑obvious: a pulse is governed if it has a Context or Policy

A pulse is considered isGoverned if it was created with a non‑default PulseContext and/or a PulseEphemeralPolicy. This triggers additional validation, lifecycle management, and auditing behaviours during propagation.

Non‑obvious: pulses are flyweights

The framework uses a flyweight pattern internally. An evolved pulse doesn't copy its parent's payload — it inherits it by walking up the parent chain. This means you can have deep causal chains with minimal memory overhead.

Non‑obvious: pulses carry their own governance

A pulse can challenge a receptor before revealing its payload. This is the reciprocal handshake — the pulse and receptor validate each other before any data is exchanged. Use shell to send a pulse to untrusted code.

Example: Creating and Evolving a Pulse

final root = Pulse<int>(42, type: 'counter');
final evolved = root
  .withStep('validation')
  .withStep('transformation');

print(evolved.payload); // 42 (inherited)
print(evolved.trace); // ['validation', 'transformation']
print(evolved.type); // 'counter' (inherited)

See also:

• Pulse.governed – for pulses with explicit governance.
• EvolvedPulse – the causal chain created by evolve.
• CollectivePulse – a flat bundle of pulses.
• PulseShell – a defensive proxy for untrusted receivers.