IngressHandle<I> typedef

IngressHandle<I> = ({Cell cell, bool Function(I input) emit, Future<bool> Function(I input) emitAsync, Future<void> Function(Pulse<I> pulse, {bool serializedCompletion}) ingest})

A management handle for an Input Gateway, providing a controlled interface for injecting external imperative stimuli into the reactive graph.

In the Cell architecture, an IngressHandle serves as the Imperative-to-Reactive Bridge. It provides the primary mechanism for non-reactive components—such as UI event handlers, hardware sensors, or network callbacks—to initiate state transitions within a synchronized, Scene-Driven Ontology.

When to use

You get this from Cell.ingress. Use it when you need to inject external events (like button clicks, WebSocket messages, or sensor readings) into the reactive graph.

How it works

The handle wraps a cell and provides three ways to send data:

  • emit: synchronous, immediate update.
  • emitAsync: asynchronous, lock-protected update.
  • ingest: full Pulse injection with provenance.

Type Parameters:

  • I: The raw input data type accepted by this gateway.

Implementation

typedef IngressHandle<I> = ({
  /// The source node ("cell") that anchors this entry point to the graph.
  Cell cell,

  /// Emits a raw stimulus into the reactive graph at **Native Speed**.
  ///
  /// This is the most common way to bridge imperative code (like UI events)
  /// into the reactive fabric. The handle automatically wraps the [input]
  /// in a [Pulse] and initiates the **Ingress Phase**.
  ///
  /// Returns `true` if the signal successfully passed the **Integrity Gate**.
  bool Function(I input) emit,

  /// Asynchronously emits a stimulus, ensuring **Serialized Transformation**
  /// through the node's **Conactive Lock**.
  ///
  /// Use this when you need to ensure that the update respects the system's
  /// atomic boundaries, preventing race conditions in high-concurrency scenes.
  Future<bool> Function(I input) emitAsync,

  /// The **Primary Ingress Handle** for direct **Signal Orchestration**.
  ///
  /// Unlike [emit], which takes raw data, [ingest] accepts a fully-formed
  /// [Pulse]. Use this when you need to provide specific **Provenance**
  /// (like a custom `justification` or `traceId`).
  Future<void> Function(Pulse<I> pulse, {bool serializedCompletion}) ingest
});