@graphrefly/graphrefly 0.27.0 → 0.28.0

package/dist/{index-BPVt8kqc.d.ts → index-cByzxQIC.d.cts}

@@ -1,8 +1,9 @@
-import { T as ToObservableOptions, t as toObservable } from './observable-BgGUwcqp.js';
+import { T as ToObservableOptions, t as toObservable } from './observable-glXQoGj2.cjs';
 import { OnModuleInit, OnModuleDestroy, ExecutionContext, CanActivate, DynamicModule } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
-import { a as Graph, G as GraphOptions, s as GraphPersistSnapshot } from './graph-CCwGKLCm.js';
-import { A as Actor, N as Node } from './node-BmerH3kS.js';
+import { G as Graph, d as GraphPersistSnapshot } from './graph-D48Qw9Cg.cjs';
+import { A as Actor } from './node-Cc1TniY8.cjs';
+import { C as CqrsOptions, a as CqrsGraph, E as EventStoreAdapter } from './index-CEXXwWVH.cjs';
 
 /** Class constructor key for decorator registries and Nest `ModuleRef.get()`. */
 type DecoratorHostConstructor = abstract new (...args: unknown[]) => unknown;
@@ -192,7 +193,7 @@ declare function GraphCron(expr: string): (value: DecoratorBoundMethod, context:
  * }
  * ```
  */
-declare function CommandHandler$1(cqrsName: string, commandName: string): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+declare function CommandHandler(cqrsName: string, commandName: string): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
 /**
  * Subscribe a method to CQRS event stream DATA — replaces `@EventsHandler()` from `@nestjs/cqrs`.
  *
@@ -256,7 +257,7 @@ declare function QueryHandler(cqrsName: string, projectionName: string): (value:
  * }
  * ```
  */
-declare function SagaHandler$1(cqrsName: string, sagaName: string, eventNames: readonly string[]): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
+declare function SagaHandler(cqrsName: string, sagaName: string, eventNames: readonly string[]): (value: DecoratorBoundMethod, context: ClassMethodDecoratorContext) => void;
 
 declare class GraphReflyEventExplorer implements OnModuleInit, OnModuleDestroy {
     private readonly graph;
@@ -579,194 +580,6 @@ declare class GraphReflyGuardImpl implements CanActivate {
  */
 declare function GraphReflyGuard(extractor?: ActorExtractor): GraphReflyGuardImpl;
 
-/**
- * CQRS patterns (roadmap §4.5).
- *
- * Composition layer over reactiveLog (3.2), pipeline/sagas (4.1), event bus (4.2),
- * projections (4.3). Guards (1.5) enforce command/query boundary.
- *
- * - `cqrs(name, opts?)` → `CqrsGraph` — top-level factory
- * - `CqrsGraph.command(name, handler)` — write-only node; guard rejects `observe`
- * - `CqrsGraph.event(name)` — backed by `reactiveLog`; append-only
- * - `CqrsGraph.projection(name, events, reducer, initial)` — read-only derived; guard rejects `write`
- * - `CqrsGraph.saga(name, events, handler)` — event-driven side effects
- */
-
-/**
- * Immutable envelope for events emitted by command handlers.
- *
- * `seq` is a per-graph monotonic counter that provides stable ordering when
- * multiple events share the same `timestampNs` (same wall-clock tick).
- */
-type CqrsEvent<T = unknown> = {
-    type: string;
-    payload: T;
-    /** Wall-clock nanoseconds (via `wallClockNs()`). */
-    timestampNs: number;
-    /** Monotonic sequence within this CqrsGraph instance. */
-    seq: number;
-    /** V0 identity of the event log node at append time (§6.0b). */
-    v0?: {
-        id: string;
-        version: number;
-    };
-};
-/**
- * Opaque replay cursor returned by `loadEvents`. Pass it back to
- * `loadEvents` to resume from the last position.
- */
-type EventStoreCursor = {
-    readonly __brand?: "EventStoreCursor";
-    [key: string]: unknown;
-};
-/**
- * Result of `loadEvents` — events plus an opaque cursor for resumption.
- */
-type LoadEventsResult = {
-    events: CqrsEvent[];
-    cursor: EventStoreCursor | undefined;
-};
-/**
- * Pluggable persistence for CQRS events.
- *
- * **`persist`:** Must be synchronous. Called from the dispatch path inside
- * `batch()`. Adapters that need async I/O should buffer internally and
- * expose a `flush()` method for explicit drain.
- */
-interface EventStoreAdapter {
-    persist(event: CqrsEvent): void;
-    /**
-     * Load persisted events. When `cursor` is provided, returns only events
-     * after that position. The returned `cursor` should be passed to the next
-     * `loadEvents` call for incremental replay.
-     */
-    loadEvents(eventType: string, cursor?: EventStoreCursor): LoadEventsResult | Promise<LoadEventsResult>;
-    /** Optional explicit flush for adapters with async I/O. */
-    flush?(): Promise<void>;
-}
-declare class MemoryEventStore implements EventStoreAdapter {
-    private readonly _store;
-    persist(event: CqrsEvent): void;
-    loadEvents(eventType: string, cursor?: EventStoreCursor): LoadEventsResult;
-    clear(): void;
-}
-type CommandActions = {
-    /** Append an event to a named event log (bypasses event guard). */
-    emit: (eventName: string, payload: unknown) => void;
-};
-/**
- * Command handler receives the dispatch payload and actions to emit events.
- *
- * **Purity:** Handlers should not mutate the payload. Event emission via
- * `actions.emit()` is the only sanctioned side effect.
- */
-type CommandHandler<T = unknown> = (payload: T, actions: CommandActions) => void;
-/**
- * Projection reducer folds events into a read model.
- *
- * **Purity contract:** Reducers MUST be pure — return a new state value
- * without mutating `state` or any event. The `state` parameter is the
- * original `initial` value on every invocation (full event-sourcing replay),
- * so mutation would corrupt future recomputations.
- */
-type ProjectionReducer<TState = unknown, TEvent = unknown> = (state: TState, events: readonly CqrsEvent<TEvent>[]) => TState;
-type SagaHandler<T = unknown> = (event: CqrsEvent<T>) => void;
-type CqrsOptions = {
-    graph?: GraphOptions;
-};
-declare class CqrsGraph extends Graph {
-    private readonly _eventLogs;
-    private readonly _commandHandlers;
-    private readonly _projections;
-    private readonly _sagas;
-    private readonly _keepaliveDisposers;
-    private _eventStore;
-    private _seq;
-    constructor(name: string, opts?: CqrsOptions);
-    destroy(): void;
-    /**
-     * Register a named event stream backed by `reactiveLog`.
-     * Guard denies external `write` — only commands append internally.
-     */
-    event(name: string): Node<readonly CqrsEvent[]>;
-    /** Internal: append to an event log, auto-registering if needed. */
-    private _appendEvent;
-    /**
-     * Register a command with its handler. Guard denies `observe` (write-only).
-     * Use `dispatch(name, payload)` to execute.
-     *
-     * The command node carries dynamic `meta.error` — a reactive companion
-     * that holds the last handler error (or `null` on success).
-     */
-    command<T = unknown>(name: string, handler: CommandHandler<T>): Node<T>;
-    /**
-     * Execute a registered command. Wraps the entire dispatch in `batch()` so
-     * the command node DATA and all emitted events settle atomically.
-     *
-     * If the handler throws, `meta.error` on the command node is set to the
-     * error and the exception is re-thrown.
-     */
-    dispatch<T = unknown>(commandName: string, payload: T): void;
-    /**
-     * Register a read-only projection derived from event streams.
-     * Guard denies `write` — value is computed from events only.
-     *
-     * **Purity contract:** The `reducer` must be a pure function — it receives
-     * the original `initial` on every invocation (full event-sourcing replay).
-     * Never mutate `initial`; always return a new value.
-     */
-    projection<TState>(name: string, eventNames: readonly string[], reducer: ProjectionReducer<TState>, initial: TState): Node<TState>;
-    /**
-     * Register an event-driven side effect. Runs handler for each **new** event
-     * from the specified streams (tracks last-processed entry count per stream).
-     *
-     * The saga node carries dynamic `meta.error` — a reactive companion that
-     * holds the last handler error (or `null` on success). Handler errors do
-     * not propagate out of the saga run (the event cursor still advances so
-     * the same entry is not delivered twice).
-     */
-    saga<T = unknown>(name: string, eventNames: readonly string[], handler: SagaHandler<T>): Node<unknown>;
-    useEventStore(adapter: EventStoreAdapter): void;
-    /**
-     * Replay persisted events through a reducer to rebuild a read model.
-     * Requires an event store adapter wired via `useEventStore()`.
-     */
-    rebuildProjection<TState>(eventNames: readonly string[], reducer: ProjectionReducer<TState>, initial: TState): Promise<TState>;
-}
-/**
- * Create a CQRS graph container.
- *
- * @example
- * ```ts
- * const app = cqrs("orders");
- * app.event("orderPlaced");
- * app.command("placeOrder", (payload, { emit }) => {
- *   emit("orderPlaced", { orderId: payload.id, amount: payload.amount });
- * });
- * app.projection("orderCount", ["orderPlaced"], (_s, events) => events.length, 0);
- * app.dispatch("placeOrder", { id: "1", amount: 100 });
- * ```
- */
-declare function cqrs(name: string, opts?: CqrsOptions): CqrsGraph;
-
-type cqrs$1_CommandActions = CommandActions;
-type cqrs$1_CommandHandler<T = unknown> = CommandHandler<T>;
-type cqrs$1_CqrsEvent<T = unknown> = CqrsEvent<T>;
-type cqrs$1_CqrsGraph = CqrsGraph;
-declare const cqrs$1_CqrsGraph: typeof CqrsGraph;
-type cqrs$1_CqrsOptions = CqrsOptions;
-type cqrs$1_EventStoreAdapter = EventStoreAdapter;
-type cqrs$1_EventStoreCursor = EventStoreCursor;
-type cqrs$1_LoadEventsResult = LoadEventsResult;
-type cqrs$1_MemoryEventStore = MemoryEventStore;
-declare const cqrs$1_MemoryEventStore: typeof MemoryEventStore;
-type cqrs$1_ProjectionReducer<TState = unknown, TEvent = unknown> = ProjectionReducer<TState, TEvent>;
-type cqrs$1_SagaHandler<T = unknown> = SagaHandler<T>;
-declare const cqrs$1_cqrs: typeof cqrs;
-declare namespace cqrs$1 {
-  export { type cqrs$1_CommandActions as CommandActions, type cqrs$1_CommandHandler as CommandHandler, type cqrs$1_CqrsEvent as CqrsEvent, cqrs$1_CqrsGraph as CqrsGraph, type cqrs$1_CqrsOptions as CqrsOptions, type cqrs$1_EventStoreAdapter as EventStoreAdapter, type cqrs$1_EventStoreCursor as EventStoreCursor, type cqrs$1_LoadEventsResult as LoadEventsResult, cqrs$1_MemoryEventStore as MemoryEventStore, type cqrs$1_ProjectionReducer as ProjectionReducer, type cqrs$1_SagaHandler as SagaHandler, cqrs$1_cqrs as cqrs };
-}
-
 interface GraphReflyRootOptions {
     /** Root graph name (default: `"root"`). */
     name?: string;
@@ -884,6 +697,7 @@ type index_ActorExtractor = ActorExtractor;
 declare const index_COMMAND_HANDLERS: typeof COMMAND_HANDLERS;
 declare const index_CQRS_EVENT_HANDLERS: typeof CQRS_EVENT_HANDLERS;
 declare const index_CRON_HANDLERS: typeof CRON_HANDLERS;
+declare const index_CommandHandler: typeof CommandHandler;
 type index_CommandHandlerMeta = CommandHandlerMeta;
 declare const index_EVENT_HANDLERS: typeof EVENT_HANDLERS;
 declare const index_EventHandler: typeof EventHandler;
@@ -921,6 +735,7 @@ declare const index_QUERY_HANDLERS: typeof QUERY_HANDLERS;
 declare const index_QueryHandler: typeof QueryHandler;
 type index_QueryHandlerMeta = QueryHandlerMeta;
 declare const index_SAGA_HANDLERS: typeof SAGA_HANDLERS;
+declare const index_SagaHandler: typeof SagaHandler;
 type index_SagaHandlerMeta = SagaHandlerMeta;
 declare const index_ToObservableOptions: typeof ToObservableOptions;
 declare const index_fromHeader: typeof fromHeader;
@@ -932,7 +747,7 @@ declare const index_observeSSE: typeof observeSSE;
 declare const index_observeSubscription: typeof observeSubscription;
 declare const index_toObservable: typeof toObservable;
 declare namespace index {
-  export { index_ACTOR_KEY as ACTOR_KEY, type index_ActorExtractor as ActorExtractor, index_COMMAND_HANDLERS as COMMAND_HANDLERS, index_CQRS_EVENT_HANDLERS as CQRS_EVENT_HANDLERS, index_CRON_HANDLERS as CRON_HANDLERS, CommandHandler$1 as CommandHandler, type index_CommandHandlerMeta as CommandHandlerMeta, index_EVENT_HANDLERS as EVENT_HANDLERS, index_EventHandler as EventHandler, type index_EventHandlerMeta as EventHandlerMeta, index_GRAPHREFLY_REQUEST_GRAPH as GRAPHREFLY_REQUEST_GRAPH, index_GRAPHREFLY_ROOT_GRAPH as GRAPHREFLY_ROOT_GRAPH, index_GraphCron as GraphCron, type index_GraphCronMeta as GraphCronMeta, index_GraphInterval as GraphInterval, type index_GraphIntervalMeta as GraphIntervalMeta, type index_GraphReflyCqrsOptions as GraphReflyCqrsOptions, index_GraphReflyEventExplorer as GraphReflyEventExplorer, type index_GraphReflyFeatureOptions as GraphReflyFeatureOptions, index_GraphReflyGuard as GraphReflyGuard, index_GraphReflyGuardImpl as GraphReflyGuardImpl, index_GraphReflyModule as GraphReflyModule, type index_GraphReflyRootOptions as GraphReflyRootOptions, index_INTERVAL_HANDLERS as INTERVAL_HANDLERS, index_InjectCqrsGraph as InjectCqrsGraph, index_InjectGraph as InjectGraph, index_InjectNode as InjectNode, index_ObserveGateway as ObserveGateway, type index_ObserveGatewayOptions as ObserveGatewayOptions, type index_ObserveSSEOptions as ObserveSSEOptions, type index_ObserveSubscriptionOptions as ObserveSubscriptionOptions, type index_ObserveWsCommand as ObserveWsCommand, type index_ObserveWsMessage as ObserveWsMessage, index_OnGraphEvent as OnGraphEvent, type index_OnGraphEventMeta as OnGraphEventMeta, index_QUERY_HANDLERS as QUERY_HANDLERS, index_QueryHandler as QueryHandler, type index_QueryHandlerMeta as QueryHandlerMeta, index_SAGA_HANDLERS as SAGA_HANDLERS, SagaHandler$1 as SagaHandler, type index_SagaHandlerMeta as SagaHandlerMeta, index_ToObservableOptions as ToObservableOptions, index_fromHeader as fromHeader, index_fromJwtPayload as fromJwtPayload, index_getActor as getActor, index_getGraphToken as getGraphToken, index_getNodeToken as getNodeToken, index_observeSSE as observeSSE, index_observeSubscription as observeSubscription, index_toObservable as toObservable };
+  export { index_ACTOR_KEY as ACTOR_KEY, type index_ActorExtractor as ActorExtractor, index_COMMAND_HANDLERS as COMMAND_HANDLERS, index_CQRS_EVENT_HANDLERS as CQRS_EVENT_HANDLERS, index_CRON_HANDLERS as CRON_HANDLERS, index_CommandHandler as CommandHandler, type index_CommandHandlerMeta as CommandHandlerMeta, index_EVENT_HANDLERS as EVENT_HANDLERS, index_EventHandler as EventHandler, type index_EventHandlerMeta as EventHandlerMeta, index_GRAPHREFLY_REQUEST_GRAPH as GRAPHREFLY_REQUEST_GRAPH, index_GRAPHREFLY_ROOT_GRAPH as GRAPHREFLY_ROOT_GRAPH, index_GraphCron as GraphCron, type index_GraphCronMeta as GraphCronMeta, index_GraphInterval as GraphInterval, type index_GraphIntervalMeta as GraphIntervalMeta, type index_GraphReflyCqrsOptions as GraphReflyCqrsOptions, index_GraphReflyEventExplorer as GraphReflyEventExplorer, type index_GraphReflyFeatureOptions as GraphReflyFeatureOptions, index_GraphReflyGuard as GraphReflyGuard, index_GraphReflyGuardImpl as GraphReflyGuardImpl, index_GraphReflyModule as GraphReflyModule, type index_GraphReflyRootOptions as GraphReflyRootOptions, index_INTERVAL_HANDLERS as INTERVAL_HANDLERS, index_InjectCqrsGraph as InjectCqrsGraph, index_InjectGraph as InjectGraph, index_InjectNode as InjectNode, index_ObserveGateway as ObserveGateway, type index_ObserveGatewayOptions as ObserveGatewayOptions, type index_ObserveSSEOptions as ObserveSSEOptions, type index_ObserveSubscriptionOptions as ObserveSubscriptionOptions, type index_ObserveWsCommand as ObserveWsCommand, type index_ObserveWsMessage as ObserveWsMessage, index_OnGraphEvent as OnGraphEvent, type index_OnGraphEventMeta as OnGraphEventMeta, index_QUERY_HANDLERS as QUERY_HANDLERS, index_QueryHandler as QueryHandler, type index_QueryHandlerMeta as QueryHandlerMeta, index_SAGA_HANDLERS as SAGA_HANDLERS, index_SagaHandler as SagaHandler, type index_SagaHandlerMeta as SagaHandlerMeta, index_ToObservableOptions as ToObservableOptions, index_fromHeader as fromHeader, index_fromJwtPayload as fromJwtPayload, index_getActor as getActor, index_getGraphToken as getGraphToken, index_getNodeToken as getNodeToken, index_observeSSE as observeSSE, index_observeSubscription as observeSubscription, index_toObservable as toObservable };
 }
 
-export { ACTOR_KEY as A, type ObserveSubscriptionOptions as B, COMMAND_HANDLERS as C, type ObserveWsCommand as D, EVENT_HANDLERS as E, type ObserveWsMessage as F, GRAPHREFLY_REQUEST_GRAPH as G, OnGraphEvent as H, INTERVAL_HANDLERS as I, type OnGraphEventMeta as J, QueryHandler as K, type QueryHandlerMeta as L, SagaHandler$1 as M, type SagaHandlerMeta as N, ObserveGateway as O, fromHeader as P, QUERY_HANDLERS as Q, fromJwtPayload as R, SAGA_HANDLERS as S, getActor as T, getGraphToken as U, getNodeToken as V, observeSSE as W, observeSubscription as X, type ActorExtractor as a, CQRS_EVENT_HANDLERS as b, cqrs$1 as c, CRON_HANDLERS as d, CommandHandler$1 as e, type CommandHandlerMeta as f, EventHandler as g, type EventHandlerMeta as h, index as i, GRAPHREFLY_ROOT_GRAPH as j, GraphCron as k, type GraphCronMeta as l, GraphInterval as m, type GraphIntervalMeta as n, type GraphReflyCqrsOptions as o, GraphReflyEventExplorer as p, type GraphReflyFeatureOptions as q, GraphReflyGuard as r, GraphReflyGuardImpl as s, GraphReflyModule as t, type GraphReflyRootOptions as u, InjectCqrsGraph as v, InjectGraph as w, InjectNode as x, type ObserveGatewayOptions as y, type ObserveSSEOptions as z };
+export { ACTOR_KEY as A, type ObserveWsCommand as B, COMMAND_HANDLERS as C, type ObserveWsMessage as D, EVENT_HANDLERS as E, OnGraphEvent as F, GRAPHREFLY_REQUEST_GRAPH as G, type OnGraphEventMeta as H, INTERVAL_HANDLERS as I, QueryHandler as J, type QueryHandlerMeta as K, SagaHandler as L, type SagaHandlerMeta as M, fromHeader as N, ObserveGateway as O, fromJwtPayload as P, QUERY_HANDLERS as Q, getActor as R, SAGA_HANDLERS as S, getGraphToken as T, getNodeToken as U, observeSSE as V, observeSubscription as W, type ActorExtractor as a, CQRS_EVENT_HANDLERS as b, CRON_HANDLERS as c, CommandHandler as d, type CommandHandlerMeta as e, EventHandler as f, type EventHandlerMeta as g, GRAPHREFLY_ROOT_GRAPH as h, index as i, GraphCron as j, type GraphCronMeta as k, GraphInterval as l, type GraphIntervalMeta as m, type GraphReflyCqrsOptions as n, GraphReflyEventExplorer as o, type GraphReflyFeatureOptions as p, GraphReflyGuard as q, GraphReflyGuardImpl as r, GraphReflyModule as s, type GraphReflyRootOptions as t, InjectCqrsGraph as u, InjectGraph as v, InjectNode as w, type ObserveGatewayOptions as x, type ObserveSSEOptions as y, type ObserveSubscriptionOptions as z };

package/dist/index-dtN7YA2x.d.cts

@@ -0,0 +1,143 @@
+import { a as Node, N as NodeOptions, c as NodeActions } from './node-Cc1TniY8.cjs';
+import { D as DerivedFn } from './sugar-BV0htudb.cjs';
+import { G as Graph, a as GraphOptions } from './graph-D48Qw9Cg.cjs';
+
+/**
+ * Orchestration patterns (roadmap §4.1).
+ *
+ * Domain-layer helpers that build workflow shapes on top of core + extra primitives.
+ * Exported under the `patterns.orchestration` namespace to avoid collisions with
+ * Phase 2 operator names (for example `gate`, `forEach`).
+ */
+
+type StepRef = string | Node<unknown>;
+type OrchestrationMeta = {
+    orchestration?: true;
+    orchestration_type?: string;
+};
+type OrchestrationStepOptions = Omit<NodeOptions<unknown>, "describeKind" | "name" | "meta"> & {
+    deps?: ReadonlyArray<StepRef>;
+    meta?: Record<string, unknown> & OrchestrationMeta;
+};
+type BranchResult<T> = {
+    branch: "then" | "else";
+    value: T;
+};
+type SensorControls<T> = {
+    node: Node<T>;
+    push(value: T): void;
+    error(err: unknown): void;
+    complete(): void;
+};
+type LoopOptions = Omit<OrchestrationStepOptions, "deps"> & {
+    iterations?: number | StepRef;
+};
+type SubPipelineBuilder = (sub: Graph) => void;
+/**
+ * Creates an orchestration graph container.
+ */
+declare function pipeline(name: string, opts?: GraphOptions): Graph;
+/**
+ * Registers a workflow task node.
+ */
+declare function task<T>(graph: Graph, name: string, run: DerivedFn<T>, opts?: OrchestrationStepOptions): Node<T>;
+/**
+ * Emits tagged branch outcomes (`then` / `else`) for each source value.
+ */
+declare function branch<T>(graph: Graph, name: string, source: StepRef, predicate: (value: T) => boolean, opts?: Omit<OrchestrationStepOptions, "deps">): Node<BranchResult<T>>;
+type ApprovalOptions = Omit<OrchestrationStepOptions, "deps"> & {
+    isApproved?: (value: unknown) => boolean;
+};
+/**
+ * Human/LLM approval gate over a source value.
+ */
+declare function approval<T>(graph: Graph, name: string, source: StepRef, approver: StepRef, opts?: ApprovalOptions): Node<T>;
+interface GateOptions {
+    /** Maximum queue size. Oldest values are FIFO-dropped when exceeded. Default: Infinity. */
+    maxPending?: number;
+    /** Start in open mode (auto-approve). Default: false. */
+    startOpen?: boolean;
+    meta?: Record<string, unknown>;
+}
+/** Control surface returned by {@link gate}. */
+interface GateController<T> {
+    /** The output node registered in the graph (subscribe to receive approved values). */
+    node: Node<T>;
+    /** Reactive queue of values waiting for approval. */
+    pending: Node<T[]>;
+    /** Derived count of pending items. */
+    count: Node<number>;
+    /** Whether the gate is currently open (auto-approving). */
+    isOpen: Node<boolean>;
+    /** Approve and forward the next `count` pending values (default: 1). */
+    approve(count?: number): void;
+    /** Reject (discard) the next `count` pending values (default: 1). */
+    reject(count?: number): void;
+    /**
+     * Transform and forward `count` pending values (default: 1).
+     * `fn` receives `(value, index, pending)` — Array.map-style.
+     */
+    modify(fn: (value: T, index: number, pending: readonly T[]) => T, count?: number): void;
+    /** Flush all pending values and auto-approve future values. */
+    open(): void;
+    /** Re-enable manual gating (stop auto-approving). */
+    close(): void;
+}
+/**
+ * Human-in-the-loop gate: queues incoming values from `source` and lets an external
+ * controller {@link GateController.approve approve}, {@link GateController.reject reject},
+ * or {@link GateController.modify modify} them before forwarding downstream.
+ *
+ * Observable surfaces (`pending`, `count`, `isOpen`) are reactive nodes registered in
+ * the graph. The gate output node is also registered.
+ */
+declare function gate<T>(graph: Graph, name: string, source: StepRef, opts?: GateOptions): GateController<T>;
+/**
+ * Registers a join step that emits a tuple of latest dependency values.
+ */
+declare function join<T extends readonly unknown[]>(graph: Graph, name: string, deps: {
+    [K in keyof T]: StepRef;
+}, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+/**
+ * Registers a loop step that applies `iterate` to each source value N times.
+ */
+declare function loop<T>(graph: Graph, name: string, source: StepRef, iterate: (value: T, iteration: number, actions: NodeActions) => T, opts?: LoopOptions): Node<T>;
+/**
+ * Mounts and returns a child workflow graph.
+ */
+declare function subPipeline(graph: Graph, name: string, childOrBuild?: Graph | SubPipelineBuilder, opts?: GraphOptions): Graph;
+/**
+ * Registers a producer-style sensor source and returns imperative controls.
+ */
+declare function sensor<T>(graph: Graph, name: string, initial?: T, opts?: Omit<NodeOptions<unknown>, "name" | "describeKind" | "meta"> & {
+    meta?: Record<string, unknown>;
+}): SensorControls<T>;
+/**
+ * Registers an error-recovery step for a source.
+ */
+declare function onFailure<T>(graph: Graph, name: string, source: StepRef, recover: (err: unknown, actions: NodeActions) => T, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+
+type index_ApprovalOptions = ApprovalOptions;
+type index_BranchResult<T> = BranchResult<T>;
+type index_GateController<T> = GateController<T>;
+type index_GateOptions = GateOptions;
+type index_LoopOptions = LoopOptions;
+type index_OrchestrationStepOptions = OrchestrationStepOptions;
+type index_SensorControls<T> = SensorControls<T>;
+type index_StepRef = StepRef;
+type index_SubPipelineBuilder = SubPipelineBuilder;
+declare const index_approval: typeof approval;
+declare const index_branch: typeof branch;
+declare const index_gate: typeof gate;
+declare const index_join: typeof join;
+declare const index_loop: typeof loop;
+declare const index_onFailure: typeof onFailure;
+declare const index_pipeline: typeof pipeline;
+declare const index_sensor: typeof sensor;
+declare const index_subPipeline: typeof subPipeline;
+declare const index_task: typeof task;
+declare namespace index {
+  export { type index_ApprovalOptions as ApprovalOptions, type index_BranchResult as BranchResult, type index_GateController as GateController, type index_GateOptions as GateOptions, type index_LoopOptions as LoopOptions, type index_OrchestrationStepOptions as OrchestrationStepOptions, type index_SensorControls as SensorControls, type index_StepRef as StepRef, type index_SubPipelineBuilder as SubPipelineBuilder, index_approval as approval, index_branch as branch, index_gate as gate, index_join as join, index_loop as loop, index_onFailure as onFailure, index_pipeline as pipeline, index_sensor as sensor, index_subPipeline as subPipeline, index_task as task };
+}
+
+export { type ApprovalOptions as A, type BranchResult as B, type GateController as G, type LoopOptions as L, type OrchestrationStepOptions as O, type SensorControls as S, type GateOptions as a, type StepRef as b, type SubPipelineBuilder as c, approval as d, branch as e, subPipeline as f, gate as g, index as i, join as j, loop as l, onFailure as o, pipeline as p, sensor as s, task as t };

package/dist/{index-CI3DprxP.d.cts → index-fM6y00vT.d.cts}

@@ -1,6 +1,6 @@
-import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-MQP--J3F.cjs';
-import { N as Node } from './node-BmerH3kS.cjs';
-import { a as Graph } from './graph-DNCrvZSn.cjs';
+import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-CpYb5qLP.cjs';
+import { a as Node } from './node-Cc1TniY8.cjs';
+import { G as Graph } from './graph-D48Qw9Cg.cjs';
 
 /**
  * MeasurementAdapter implementations (roadmap §7.1 — pluggable backends).
@@ -355,6 +355,17 @@ type ReactiveFlowLayoutOptions = {
     obstacles?: Obstacle[];
     /** Minimum slot width (px) below which a slot is discarded rather than squeezed. Default `20`. */
     minSlotWidth?: number;
+    /**
+     * Vertical gap (px) inserted after a hard-break segment (the spacing
+     * between paragraphs). When unset (or explicitly set to `null`), tracks
+     * the current `lineHeight` reactively — one line-height of visible
+     * paragraph gap, matching dense editorial layouts. Set to `0` for
+     * paragraph-preserving layout that reclaims the break line; set larger
+     * (e.g. `2 * lineHeight`) for looser manuscript settings. Reactive —
+     * update via `setParagraphSpacing(n)` or restore to track-lineHeight
+     * mode via `setParagraphSpacing(null)`.
+     */
+    paragraphSpacing?: number | null;
 };
 /** Result bundle from `reactiveFlowLayout`. */
 type ReactiveFlowLayoutBundle = {
@@ -365,6 +376,7 @@ type ReactiveFlowLayoutBundle = {
     setContainer: (c: FlowContainer) => void;
     setColumns: (c: FlowColumns) => void;
     setObstacles: (o: Obstacle[]) => void;
+    setParagraphSpacing: (ps: number | null) => void;
     segments: Node<PreparedSegment[]>;
     flowLines: Node<PositionedLine[]>;
 };
@@ -377,6 +389,17 @@ type FlowLinesResult = {
      *  container couldn't fit all text. */
     cursor: LayoutCursor;
 };
+/** Optional tuning knobs for {@link computeFlowLines}. */
+type ComputeFlowLinesOptions = {
+    /**
+     * Vertical gap (px) inserted after a hard-break segment (the spacing
+     * between paragraphs). Defaults to `lineHeight` — one line-height of
+     * visible paragraph gap, which matches dense editorial layouts. Set to
+     * `0` for paragraph-preserving layout that reclaims the break line;
+     * set larger (e.g. `2 * lineHeight`) for looser manuscript settings.
+     */
+    paragraphSpacing?: number;
+};
 /**
  * Lay out `segments` across N columns, wrapping each line around `obstacles`.
  * Pure function — no reactive wiring. Exported for testing and for consumers
@@ -385,7 +408,7 @@ type FlowLinesResult = {
  * `carveTextLineSlots` guarantees left-to-right-ordered, non-overlapping slots,
  * so this function does not sort them.
  */
-declare function computeFlowLines(segments: PreparedSegment[], container: FlowContainer, columns: FlowColumns, obstacles: Obstacle[], lineHeight: number, minSlotWidth: number): FlowLinesResult;
+declare function computeFlowLines(segments: PreparedSegment[], container: FlowContainer, columns: FlowColumns, obstacles: Obstacle[], lineHeight: number, minSlotWidth: number, opts?: ComputeFlowLinesOptions): FlowLinesResult;
 /**
  * Create a reactive flow-layout graph: N columns of text wrapping around
  * shape obstacles. Re-runs only the dependent derived nodes on any input
@@ -433,6 +456,7 @@ type index_CircleObstacle = CircleObstacle;
 type index_CliMeasureAdapter = CliMeasureAdapter;
 declare const index_CliMeasureAdapter: typeof CliMeasureAdapter;
 type index_CliMeasureAdapterOptions = CliMeasureAdapterOptions;
+type index_ComputeFlowLinesOptions = ComputeFlowLinesOptions;
 type index_ContentBlock = ContentBlock;
 type index_FlowColumns = FlowColumns;
 type index_FlowContainer = FlowContainer;
@@ -485,7 +509,7 @@ declare const index_reactiveFlowLayout: typeof reactiveFlowLayout;
 declare const index_reactiveLayout: typeof reactiveLayout;
 declare const index_rectIntervalForBand: typeof rectIntervalForBand;
 declare namespace index {
-  export { type index_BlockAdapters as BlockAdapters, index_CanvasMeasureAdapter as CanvasMeasureAdapter, type index_CanvasMeasureAdapterOptions as CanvasMeasureAdapterOptions, type index_CanvasModule as CanvasModule, index_CharPosition as CharPosition, type index_CircleObstacle as CircleObstacle, index_CliMeasureAdapter as CliMeasureAdapter, type index_CliMeasureAdapterOptions as CliMeasureAdapterOptions, type index_ContentBlock as ContentBlock, type index_FlowColumns as FlowColumns, type index_FlowContainer as FlowContainer, type index_FlowLinesResult as FlowLinesResult, type index_ImageMeasurer as ImageMeasurer, index_ImageSizeAdapter as ImageSizeAdapter, index_Interval as Interval, index_LayoutCursor as LayoutCursor, index_LayoutLine as LayoutLine, index_LayoutNextLineContext as LayoutNextLineContext, index_LayoutNextLineResult as LayoutNextLineResult, index_LineBreaksResult as LineBreaksResult, type index_MeasuredBlock as MeasuredBlock, index_MeasurementAdapter as MeasurementAdapter, index_NodeCanvasMeasureAdapter as NodeCanvasMeasureAdapter, type index_Obstacle as Obstacle, type index_PositionedBlock as PositionedBlock, type index_PositionedLine as PositionedLine, index_PrecomputedAdapter as PrecomputedAdapter, type index_PrecomputedAdapterOptions as PrecomputedAdapterOptions, index_PreparedSegment as PreparedSegment, type index_ReactiveBlockLayoutBundle as ReactiveBlockLayoutBundle, type index_ReactiveBlockLayoutOptions as ReactiveBlockLayoutOptions, type index_ReactiveFlowLayoutBundle as ReactiveFlowLayoutBundle, type index_ReactiveFlowLayoutOptions as ReactiveFlowLayoutOptions, index_ReactiveLayoutBundle as ReactiveLayoutBundle, index_ReactiveLayoutOptions as ReactiveLayoutOptions, type index_RectObstacle as RectObstacle, index_SegmentBreakKind as SegmentBreakKind, index_SegmentMeasureStats as SegmentMeasureStats, index_SvgBoundsAdapter as SvgBoundsAdapter, type index_SvgMeasurer as SvgMeasurer, index_analyzeAndMeasure as analyzeAndMeasure, index_carveTextLineSlots as carveTextLineSlots, index_circleIntervalForBand as circleIntervalForBand, index_computeBlockFlow as computeBlockFlow, index_computeCharPositions as computeCharPositions, index_computeFlowLines as computeFlowLines, index_computeLineBreaks as computeLineBreaks, index_computeTotalHeight as computeTotalHeight, index_layoutNextLine as layoutNextLine, index_measureBlock as measureBlock, index_measureBlocks as measureBlocks, index_reactiveBlockLayout as reactiveBlockLayout, index_reactiveFlowLayout as reactiveFlowLayout, index_reactiveLayout as reactiveLayout, index_rectIntervalForBand as rectIntervalForBand };
+  export { type index_BlockAdapters as BlockAdapters, index_CanvasMeasureAdapter as CanvasMeasureAdapter, type index_CanvasMeasureAdapterOptions as CanvasMeasureAdapterOptions, type index_CanvasModule as CanvasModule, index_CharPosition as CharPosition, type index_CircleObstacle as CircleObstacle, index_CliMeasureAdapter as CliMeasureAdapter, type index_CliMeasureAdapterOptions as CliMeasureAdapterOptions, type index_ComputeFlowLinesOptions as ComputeFlowLinesOptions, type index_ContentBlock as ContentBlock, type index_FlowColumns as FlowColumns, type index_FlowContainer as FlowContainer, type index_FlowLinesResult as FlowLinesResult, type index_ImageMeasurer as ImageMeasurer, index_ImageSizeAdapter as ImageSizeAdapter, index_Interval as Interval, index_LayoutCursor as LayoutCursor, index_LayoutLine as LayoutLine, index_LayoutNextLineContext as LayoutNextLineContext, index_LayoutNextLineResult as LayoutNextLineResult, index_LineBreaksResult as LineBreaksResult, type index_MeasuredBlock as MeasuredBlock, index_MeasurementAdapter as MeasurementAdapter, index_NodeCanvasMeasureAdapter as NodeCanvasMeasureAdapter, type index_Obstacle as Obstacle, type index_PositionedBlock as PositionedBlock, type index_PositionedLine as PositionedLine, index_PrecomputedAdapter as PrecomputedAdapter, type index_PrecomputedAdapterOptions as PrecomputedAdapterOptions, index_PreparedSegment as PreparedSegment, type index_ReactiveBlockLayoutBundle as ReactiveBlockLayoutBundle, type index_ReactiveBlockLayoutOptions as ReactiveBlockLayoutOptions, type index_ReactiveFlowLayoutBundle as ReactiveFlowLayoutBundle, type index_ReactiveFlowLayoutOptions as ReactiveFlowLayoutOptions, index_ReactiveLayoutBundle as ReactiveLayoutBundle, index_ReactiveLayoutOptions as ReactiveLayoutOptions, type index_RectObstacle as RectObstacle, index_SegmentBreakKind as SegmentBreakKind, index_SegmentMeasureStats as SegmentMeasureStats, index_SvgBoundsAdapter as SvgBoundsAdapter, type index_SvgMeasurer as SvgMeasurer, index_analyzeAndMeasure as analyzeAndMeasure, index_carveTextLineSlots as carveTextLineSlots, index_circleIntervalForBand as circleIntervalForBand, index_computeBlockFlow as computeBlockFlow, index_computeCharPositions as computeCharPositions, index_computeFlowLines as computeFlowLines, index_computeLineBreaks as computeLineBreaks, index_computeTotalHeight as computeTotalHeight, index_layoutNextLine as layoutNextLine, index_measureBlock as measureBlock, index_measureBlocks as measureBlocks, index_reactiveBlockLayout as reactiveBlockLayout, index_reactiveFlowLayout as reactiveFlowLayout, index_reactiveLayout as reactiveLayout, index_rectIntervalForBand as rectIntervalForBand };
 }
 
-export { rectIntervalForBand as A, type BlockAdapters as B, CanvasMeasureAdapter as C, type FlowColumns as F, type ImageMeasurer as I, type MeasuredBlock as M, NodeCanvasMeasureAdapter as N, type Obstacle as O, type PositionedBlock as P, type ReactiveBlockLayoutBundle as R, SvgBoundsAdapter as S, type CanvasMeasureAdapterOptions as a, type CanvasModule as b, type CircleObstacle as c, CliMeasureAdapter as d, type CliMeasureAdapterOptions as e, type ContentBlock as f, type FlowContainer as g, type FlowLinesResult as h, index as i, ImageSizeAdapter as j, type PositionedLine as k, PrecomputedAdapter as l, type PrecomputedAdapterOptions as m, type ReactiveBlockLayoutOptions as n, type ReactiveFlowLayoutBundle as o, type ReactiveFlowLayoutOptions as p, type RectObstacle as q, type SvgMeasurer as r, circleIntervalForBand as s, computeBlockFlow as t, computeFlowLines as u, computeTotalHeight as v, measureBlock as w, measureBlocks as x, reactiveBlockLayout as y, reactiveFlowLayout as z };
+export { reactiveFlowLayout as A, type BlockAdapters as B, CanvasMeasureAdapter as C, rectIntervalForBand as D, type FlowColumns as F, type ImageMeasurer as I, type MeasuredBlock as M, NodeCanvasMeasureAdapter as N, type Obstacle as O, type PositionedBlock as P, type ReactiveBlockLayoutBundle as R, SvgBoundsAdapter as S, type CanvasMeasureAdapterOptions as a, type CanvasModule as b, type CircleObstacle as c, CliMeasureAdapter as d, type CliMeasureAdapterOptions as e, type ComputeFlowLinesOptions as f, type ContentBlock as g, type FlowContainer as h, index as i, type FlowLinesResult as j, ImageSizeAdapter as k, type PositionedLine as l, PrecomputedAdapter as m, type PrecomputedAdapterOptions as n, type ReactiveBlockLayoutOptions as o, type ReactiveFlowLayoutBundle as p, type ReactiveFlowLayoutOptions as q, type RectObstacle as r, type SvgMeasurer as s, circleIntervalForBand as t, computeBlockFlow as u, computeFlowLines as v, computeTotalHeight as w, measureBlock as x, measureBlocks as y, reactiveBlockLayout as z };