@graphrefly/graphrefly 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -1490,13 +1490,13 @@ declare namespace messaging {
  * Phase 2 operator names (for example `gate`, `forEach`).
  */
 
-type StepRef = string | Node<unknown>;
+type StepRef$1 = string | Node<unknown>;
 type OrchestrationMeta = {
     orchestration?: true;
     orchestration_type?: string;
 };
 type OrchestrationStepOptions = Omit<NodeOptions, "describeKind" | "name" | "meta"> & {
-    deps?: ReadonlyArray<StepRef>;
+    deps?: ReadonlyArray<StepRef$1>;
     meta?: Record<string, unknown> & OrchestrationMeta;
 };
 type BranchResult<T> = {
@@ -1510,7 +1510,7 @@ type SensorControls<T> = {
     complete(): void;
 };
 type LoopOptions = Omit<OrchestrationStepOptions, "deps"> & {
-    iterations?: number | StepRef;
+    iterations?: number | StepRef$1;
 };
 type WaitOptions = Omit<OrchestrationStepOptions, "deps">;
 type SubPipelineBuilder = (sub: Graph) => void;
@@ -1525,32 +1525,32 @@ declare function task<T>(graph: Graph, name: string, run: NodeFn<T>, opts?: Orch
 /**
  * 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>>;
+declare function branch<T>(graph: Graph, name: string, source: StepRef$1, predicate: (value: T) => boolean, opts?: Omit<OrchestrationStepOptions, "deps">): Node<BranchResult<T>>;
 /**
  * Forwards source values only while `control` is truthy.
  */
-declare function gate<T>(graph: Graph, name: string, source: StepRef, control: StepRef, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+declare function gate<T>(graph: Graph, name: string, source: StepRef$1, control: StepRef$1, opts?: Omit<OrchestrationStepOptions, "deps">): Node<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>;
+declare function approval<T>(graph: Graph, name: string, source: StepRef$1, approver: StepRef$1, opts?: ApprovalOptions): Node<T>;
 /**
  * Registers a workflow side-effect step. The step remains graph-observable and forwards messages.
  */
-declare function forEach<T>(graph: Graph, name: string, source: StepRef, run: (value: T, actions: NodeActions) => void, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+declare function forEach<T>(graph: Graph, name: string, source: StepRef$1, run: (value: T, actions: NodeActions) => void, opts?: Omit<OrchestrationStepOptions, "deps">): Node<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;
+    [K in keyof T]: StepRef$1;
 }, 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>;
+declare function loop<T>(graph: Graph, name: string, source: StepRef$1, iterate: (value: T, iteration: number, actions: NodeActions) => T, opts?: LoopOptions): Node<T>;
 /**
  * Mounts and returns a child workflow graph.
  */
@@ -1564,18 +1564,17 @@ declare function sensor<T>(graph: Graph, name: string, initial?: T, opts?: Omit<
 /**
  * Registers a delayed-forwarding step (value-level wait).
  */
-declare function wait<T>(graph: Graph, name: string, source: StepRef, ms: number, opts?: WaitOptions): Node<T>;
+declare function wait<T>(graph: Graph, name: string, source: StepRef$1, ms: number, opts?: WaitOptions): Node<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>;
+declare function onFailure<T>(graph: Graph, name: string, source: StepRef$1, recover: (err: unknown, actions: NodeActions) => T, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
 
 type orchestration_ApprovalOptions = ApprovalOptions;
 type orchestration_BranchResult<T> = BranchResult<T>;
 type orchestration_LoopOptions = LoopOptions;
 type orchestration_OrchestrationStepOptions = OrchestrationStepOptions;
 type orchestration_SensorControls<T> = SensorControls<T>;
-type orchestration_StepRef = StepRef;
 type orchestration_SubPipelineBuilder = SubPipelineBuilder;
 type orchestration_WaitOptions = WaitOptions;
 declare const orchestration_approval: typeof approval;
@@ -1591,7 +1590,182 @@ declare const orchestration_subPipeline: typeof subPipeline;
 declare const orchestration_task: typeof task;
 declare const orchestration_wait: typeof wait;
 declare namespace orchestration {
-  export { type orchestration_ApprovalOptions as ApprovalOptions, type orchestration_BranchResult as BranchResult, type orchestration_LoopOptions as LoopOptions, type orchestration_OrchestrationStepOptions as OrchestrationStepOptions, type orchestration_SensorControls as SensorControls, type orchestration_StepRef as StepRef, type orchestration_SubPipelineBuilder as SubPipelineBuilder, type orchestration_WaitOptions as WaitOptions, orchestration_approval as approval, orchestration_branch as branch, orchestration_forEach as forEach, orchestration_gate as gate, orchestration_join as join, orchestration_loop as loop, orchestration_onFailure as onFailure, orchestration_pipeline as pipeline, orchestration_sensor as sensor, orchestration_subPipeline as subPipeline, orchestration_task as task, orchestration_wait as wait };
+  export { type orchestration_ApprovalOptions as ApprovalOptions, type orchestration_BranchResult as BranchResult, type orchestration_LoopOptions as LoopOptions, type orchestration_OrchestrationStepOptions as OrchestrationStepOptions, type orchestration_SensorControls as SensorControls, type StepRef$1 as StepRef, type orchestration_SubPipelineBuilder as SubPipelineBuilder, type orchestration_WaitOptions as WaitOptions, orchestration_approval as approval, orchestration_branch as branch, orchestration_forEach as forEach, orchestration_gate as gate, orchestration_join as join, orchestration_loop as loop, orchestration_onFailure as onFailure, orchestration_pipeline as pipeline, orchestration_sensor as sensor, orchestration_subPipeline as subPipeline, orchestration_task as task, orchestration_wait as wait };
+}
+
+/**
+ * Reduction primitives (roadmap §8.1).
+ *
+ * Composable building blocks for taking heterogeneous massive inputs and producing
+ * prioritized, auditable, human-actionable output. Each primitive is either a Graph
+ * factory or a Node factory, built on top of core + extra primitives.
+ *
+ * @module
+ */
+
+type StepRef = string | Node<unknown>;
+/** A single routing rule for {@link stratify}. */
+type StratifyRule<T> = {
+    /** Branch name (used as node name under `branch/<name>`). */
+    name: string;
+    /** Classifier: returns `true` if the value belongs to this branch. */
+    classify: (value: T) => boolean;
+    /** Optional operator chain applied to the branch after classification. */
+    ops?: (n: Node<T>) => Node;
+};
+/** Options for {@link stratify}. */
+type StratifyOptions = GraphOptions & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Route input to different reduction branches based on classifier functions.
+ *
+ * Each branch gets an independent operator chain. Rules are reactive — update
+ * the `"rules"` state node to rewrite classification at runtime. Rule updates
+ * affect **future items only** (streaming classification, not retroactive).
+ *
+ * Branch nodes are structural — created at construction time and persist for
+ * the graph's lifetime. If a rule name is removed from the rules array, the
+ * corresponding branch silently drops items (classifier not found). To tear
+ * down a dead branch, call `graph.remove("branch/<name>")`.
+ *
+ * @param name - Graph name.
+ * @param source - Input node (registered externally or will be added as `"source"`).
+ * @param rules - Initial routing rules.
+ * @param opts - Optional graph/meta options.
+ * @returns Graph with `"source"`, `"rules"`, and `"branch/<name>"` nodes.
+ *
+ * @category patterns
+ */
+declare function stratify<T>(name: string, source: Node<T>, rules: ReadonlyArray<StratifyRule<T>>, opts?: StratifyOptions): Graph;
+/** A named stage for {@link funnel}. */
+type FunnelStage = {
+    /** Stage name (mounted as subgraph). */
+    name: string;
+    /** Builder: receives a sub-graph, should add an `"input"` and `"output"` node. */
+    build: (sub: Graph) => void;
+};
+/** Options for {@link funnel}. */
+type FunnelOptions = GraphOptions & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Multi-source merge with sequential reduction stages.
+ *
+ * Sources are merged into a single stream. Each stage is a named subgraph
+ * (mounted via `graph.mount()`). Stages connect linearly:
+ * `merged → stage[0].input → stage[0].output → stage[1].input → ...`
+ *
+ * @param name - Graph name.
+ * @param sources - Input nodes to merge.
+ * @param stages - Sequential reduction stages.
+ * @param opts - Optional graph/meta options.
+ * @returns Graph with `"merged"` and mounted stage subgraphs.
+ *
+ * @category patterns
+ */
+declare function funnel<T>(name: string, sources: ReadonlyArray<Node<T>>, stages: ReadonlyArray<FunnelStage>, opts?: FunnelOptions): Graph;
+/** Options for {@link feedback}. */
+type FeedbackOptions = {
+    /** Maximum feedback iterations before stopping (default: 10). */
+    maxIterations?: number;
+    /** Optional budget gate node path for cost-bounded iteration. */
+    budgetNode?: StepRef;
+    meta?: Record<string, unknown>;
+};
+/**
+ * Introduce a bounded reactive cycle into an existing graph.
+ *
+ * When `condition` emits a non-null DATA value, the feedback effect routes it
+ * back to the `reentry` state node — creating a cycle. Bounded by
+ * `maxIterations` (default 10). The counter node (`__feedback_<condition>`)
+ * is the source of truth — reset it to 0 to allow more iterations.
+ *
+ * To remove the feedback cycle, call `graph.remove("__feedback_<condition>")`.
+ *
+ * @param graph - Existing graph to augment with a feedback cycle.
+ * @param condition - Path to a node whose DATA triggers feedback.
+ * @param reentry - Path to a state node that receives the feedback value.
+ * @param opts - Iteration bounds and metadata.
+ * @returns The same graph (mutated with feedback nodes added).
+ *
+ * @category patterns
+ */
+declare function feedback(graph: Graph, condition: string, reentry: string, opts?: FeedbackOptions): Graph;
+/** A reactive constraint for {@link budgetGate}. */
+type BudgetConstraint<T = unknown> = {
+    /** Constraint node whose value is checked. */
+    node: Node<T>;
+    /** Returns `true` when the constraint is satisfied (budget available). */
+    check: (value: T) => boolean;
+};
+/** Options for {@link budgetGate}. */
+type BudgetGateOptions = Omit<NodeOptions, "describeKind" | "name" | "meta"> & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Pass-through that respects reactive constraint nodes.
+ *
+ * DATA flows through when all constraints are satisfied. When any constraint
+ * is exceeded, PAUSE is sent upstream and DATA is buffered. When constraints
+ * relax, RESUME is sent and buffered DATA flushes.
+ *
+ * @param source - Input node.
+ * @param constraints - Reactive constraint checks.
+ * @param opts - Optional node options.
+ * @returns Gated node.
+ *
+ * @category patterns
+ */
+declare function budgetGate<T>(source: Node<T>, constraints: ReadonlyArray<BudgetConstraint>, opts?: BudgetGateOptions): Node<T>;
+/** A scored item with full breakdown. */
+type ScoredItem<T = unknown> = {
+    /** Original value. */
+    value: T;
+    /** Final weighted score. */
+    score: number;
+    /** Per-signal breakdown: signal index → weighted contribution. */
+    breakdown: number[];
+};
+/** Options for {@link scorer}. */
+type ScorerOptions = Omit<NodeOptions, "describeKind" | "name" | "meta"> & {
+    meta?: Record<string, unknown>;
+    /** Custom scoring function per signal. Default: identity (signal value IS the score). */
+    scoreFns?: ReadonlyArray<(value: unknown) => number>;
+};
+/**
+ * Reactive multi-signal scoring with live weights.
+ *
+ * Each source emits items to score. Weights are reactive state nodes that
+ * LLM or human can adjust live. Output is sorted scored items with full
+ * breakdown.
+ *
+ * @param sources - Signal nodes (each emits a numeric score dimension).
+ * @param weights - Reactive weight nodes (one per source).
+ * @param opts - Optional node/meta options.
+ * @returns Node emitting scored output.
+ *
+ * @category patterns
+ */
+declare function scorer(sources: ReadonlyArray<Node<number>>, weights: ReadonlyArray<Node<number>>, opts?: ScorerOptions): Node<ScoredItem<number[]>>;
+
+type reduction_BudgetConstraint<T = unknown> = BudgetConstraint<T>;
+type reduction_BudgetGateOptions = BudgetGateOptions;
+type reduction_FeedbackOptions = FeedbackOptions;
+type reduction_FunnelOptions = FunnelOptions;
+type reduction_FunnelStage = FunnelStage;
+type reduction_ScoredItem<T = unknown> = ScoredItem<T>;
+type reduction_ScorerOptions = ScorerOptions;
+type reduction_StepRef = StepRef;
+type reduction_StratifyOptions = StratifyOptions;
+type reduction_StratifyRule<T> = StratifyRule<T>;
+declare const reduction_budgetGate: typeof budgetGate;
+declare const reduction_feedback: typeof feedback;
+declare const reduction_funnel: typeof funnel;
+declare const reduction_scorer: typeof scorer;
+declare const reduction_stratify: typeof stratify;
+declare namespace reduction {
+  export { type reduction_BudgetConstraint as BudgetConstraint, type reduction_BudgetGateOptions as BudgetGateOptions, type reduction_FeedbackOptions as FeedbackOptions, type reduction_FunnelOptions as FunnelOptions, type reduction_FunnelStage as FunnelStage, type reduction_ScoredItem as ScoredItem, type reduction_ScorerOptions as ScorerOptions, type reduction_StepRef as StepRef, type reduction_StratifyOptions as StratifyOptions, type reduction_StratifyRule as StratifyRule, reduction_budgetGate as budgetGate, reduction_feedback as feedback, reduction_funnel as funnel, reduction_scorer as scorer, reduction_stratify as stratify };
 }
 
 /**
@@ -1603,8 +1777,9 @@ declare const index_cqrs: typeof cqrs;
 declare const index_memory: typeof memory;
 declare const index_messaging: typeof messaging;
 declare const index_orchestration: typeof orchestration;
+declare const index_reduction: typeof reduction;
 declare namespace index {
-  export { index_ai as ai, index_cqrs as cqrs, demoShell$1 as demoShell, index$b as layout, index_memory as memory, index_messaging as messaging, index_orchestration as orchestration };
+  export { index_ai as ai, index_cqrs as cqrs, demoShell$1 as demoShell, index$b as layout, index_memory as memory, index_messaging as messaging, index_orchestration as orchestration, index_reduction as reduction };
 }
 
 /**
@@ -1612,4 +1787,4 @@ declare namespace index {
  */
 declare const version = "0.0.0";
 
-export { Actor, AutoCheckpointAdapter, DistillBundle, Extraction, Graph, GraphAutoCheckpointHandle, GraphAutoCheckpointOptions, GraphOptions, Node, NodeActions, NodeFn, NodeInput, NodeOptions, ReactiveListSnapshot, ReactiveLogSnapshot, ReactiveMapSnapshot, ai, index$1 as compat, cqrs, demoShell$1 as demoShell, index$9 as jotai, index$b as layout, memory, messaging, index$8 as nanostores, index$a as nestjs, orchestration, index as patterns, index$7 as react, index$6 as signals, index$5 as solid, index$4 as svelte, version, index$3 as vue, index$2 as zustand };
+export { Actor, AutoCheckpointAdapter, DistillBundle, Extraction, Graph, GraphAutoCheckpointHandle, GraphAutoCheckpointOptions, GraphOptions, Node, NodeActions, NodeFn, NodeInput, NodeOptions, ReactiveListSnapshot, ReactiveLogSnapshot, ReactiveMapSnapshot, ai, index$1 as compat, cqrs, demoShell$1 as demoShell, index$9 as jotai, index$b as layout, memory, messaging, index$8 as nanostores, index$a as nestjs, orchestration, index as patterns, index$7 as react, reduction, index$6 as signals, index$5 as solid, index$4 as svelte, version, index$3 as vue, index$2 as zustand };

package/dist/index.d.ts

@@ -1490,13 +1490,13 @@ declare namespace messaging {
  * Phase 2 operator names (for example `gate`, `forEach`).
  */
 
-type StepRef = string | Node<unknown>;
+type StepRef$1 = string | Node<unknown>;
 type OrchestrationMeta = {
     orchestration?: true;
     orchestration_type?: string;
 };
 type OrchestrationStepOptions = Omit<NodeOptions, "describeKind" | "name" | "meta"> & {
-    deps?: ReadonlyArray<StepRef>;
+    deps?: ReadonlyArray<StepRef$1>;
     meta?: Record<string, unknown> & OrchestrationMeta;
 };
 type BranchResult<T> = {
@@ -1510,7 +1510,7 @@ type SensorControls<T> = {
     complete(): void;
 };
 type LoopOptions = Omit<OrchestrationStepOptions, "deps"> & {
-    iterations?: number | StepRef;
+    iterations?: number | StepRef$1;
 };
 type WaitOptions = Omit<OrchestrationStepOptions, "deps">;
 type SubPipelineBuilder = (sub: Graph) => void;
@@ -1525,32 +1525,32 @@ declare function task<T>(graph: Graph, name: string, run: NodeFn<T>, opts?: Orch
 /**
  * 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>>;
+declare function branch<T>(graph: Graph, name: string, source: StepRef$1, predicate: (value: T) => boolean, opts?: Omit<OrchestrationStepOptions, "deps">): Node<BranchResult<T>>;
 /**
  * Forwards source values only while `control` is truthy.
  */
-declare function gate<T>(graph: Graph, name: string, source: StepRef, control: StepRef, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+declare function gate<T>(graph: Graph, name: string, source: StepRef$1, control: StepRef$1, opts?: Omit<OrchestrationStepOptions, "deps">): Node<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>;
+declare function approval<T>(graph: Graph, name: string, source: StepRef$1, approver: StepRef$1, opts?: ApprovalOptions): Node<T>;
 /**
  * Registers a workflow side-effect step. The step remains graph-observable and forwards messages.
  */
-declare function forEach<T>(graph: Graph, name: string, source: StepRef, run: (value: T, actions: NodeActions) => void, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+declare function forEach<T>(graph: Graph, name: string, source: StepRef$1, run: (value: T, actions: NodeActions) => void, opts?: Omit<OrchestrationStepOptions, "deps">): Node<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;
+    [K in keyof T]: StepRef$1;
 }, 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>;
+declare function loop<T>(graph: Graph, name: string, source: StepRef$1, iterate: (value: T, iteration: number, actions: NodeActions) => T, opts?: LoopOptions): Node<T>;
 /**
  * Mounts and returns a child workflow graph.
  */
@@ -1564,18 +1564,17 @@ declare function sensor<T>(graph: Graph, name: string, initial?: T, opts?: Omit<
 /**
  * Registers a delayed-forwarding step (value-level wait).
  */
-declare function wait<T>(graph: Graph, name: string, source: StepRef, ms: number, opts?: WaitOptions): Node<T>;
+declare function wait<T>(graph: Graph, name: string, source: StepRef$1, ms: number, opts?: WaitOptions): Node<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>;
+declare function onFailure<T>(graph: Graph, name: string, source: StepRef$1, recover: (err: unknown, actions: NodeActions) => T, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
 
 type orchestration_ApprovalOptions = ApprovalOptions;
 type orchestration_BranchResult<T> = BranchResult<T>;
 type orchestration_LoopOptions = LoopOptions;
 type orchestration_OrchestrationStepOptions = OrchestrationStepOptions;
 type orchestration_SensorControls<T> = SensorControls<T>;
-type orchestration_StepRef = StepRef;
 type orchestration_SubPipelineBuilder = SubPipelineBuilder;
 type orchestration_WaitOptions = WaitOptions;
 declare const orchestration_approval: typeof approval;
@@ -1591,7 +1590,182 @@ declare const orchestration_subPipeline: typeof subPipeline;
 declare const orchestration_task: typeof task;
 declare const orchestration_wait: typeof wait;
 declare namespace orchestration {
-  export { type orchestration_ApprovalOptions as ApprovalOptions, type orchestration_BranchResult as BranchResult, type orchestration_LoopOptions as LoopOptions, type orchestration_OrchestrationStepOptions as OrchestrationStepOptions, type orchestration_SensorControls as SensorControls, type orchestration_StepRef as StepRef, type orchestration_SubPipelineBuilder as SubPipelineBuilder, type orchestration_WaitOptions as WaitOptions, orchestration_approval as approval, orchestration_branch as branch, orchestration_forEach as forEach, orchestration_gate as gate, orchestration_join as join, orchestration_loop as loop, orchestration_onFailure as onFailure, orchestration_pipeline as pipeline, orchestration_sensor as sensor, orchestration_subPipeline as subPipeline, orchestration_task as task, orchestration_wait as wait };
+  export { type orchestration_ApprovalOptions as ApprovalOptions, type orchestration_BranchResult as BranchResult, type orchestration_LoopOptions as LoopOptions, type orchestration_OrchestrationStepOptions as OrchestrationStepOptions, type orchestration_SensorControls as SensorControls, type StepRef$1 as StepRef, type orchestration_SubPipelineBuilder as SubPipelineBuilder, type orchestration_WaitOptions as WaitOptions, orchestration_approval as approval, orchestration_branch as branch, orchestration_forEach as forEach, orchestration_gate as gate, orchestration_join as join, orchestration_loop as loop, orchestration_onFailure as onFailure, orchestration_pipeline as pipeline, orchestration_sensor as sensor, orchestration_subPipeline as subPipeline, orchestration_task as task, orchestration_wait as wait };
+}
+
+/**
+ * Reduction primitives (roadmap §8.1).
+ *
+ * Composable building blocks for taking heterogeneous massive inputs and producing
+ * prioritized, auditable, human-actionable output. Each primitive is either a Graph
+ * factory or a Node factory, built on top of core + extra primitives.
+ *
+ * @module
+ */
+
+type StepRef = string | Node<unknown>;
+/** A single routing rule for {@link stratify}. */
+type StratifyRule<T> = {
+    /** Branch name (used as node name under `branch/<name>`). */
+    name: string;
+    /** Classifier: returns `true` if the value belongs to this branch. */
+    classify: (value: T) => boolean;
+    /** Optional operator chain applied to the branch after classification. */
+    ops?: (n: Node<T>) => Node;
+};
+/** Options for {@link stratify}. */
+type StratifyOptions = GraphOptions & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Route input to different reduction branches based on classifier functions.
+ *
+ * Each branch gets an independent operator chain. Rules are reactive — update
+ * the `"rules"` state node to rewrite classification at runtime. Rule updates
+ * affect **future items only** (streaming classification, not retroactive).
+ *
+ * Branch nodes are structural — created at construction time and persist for
+ * the graph's lifetime. If a rule name is removed from the rules array, the
+ * corresponding branch silently drops items (classifier not found). To tear
+ * down a dead branch, call `graph.remove("branch/<name>")`.
+ *
+ * @param name - Graph name.
+ * @param source - Input node (registered externally or will be added as `"source"`).
+ * @param rules - Initial routing rules.
+ * @param opts - Optional graph/meta options.
+ * @returns Graph with `"source"`, `"rules"`, and `"branch/<name>"` nodes.
+ *
+ * @category patterns
+ */
+declare function stratify<T>(name: string, source: Node<T>, rules: ReadonlyArray<StratifyRule<T>>, opts?: StratifyOptions): Graph;
+/** A named stage for {@link funnel}. */
+type FunnelStage = {
+    /** Stage name (mounted as subgraph). */
+    name: string;
+    /** Builder: receives a sub-graph, should add an `"input"` and `"output"` node. */
+    build: (sub: Graph) => void;
+};
+/** Options for {@link funnel}. */
+type FunnelOptions = GraphOptions & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Multi-source merge with sequential reduction stages.
+ *
+ * Sources are merged into a single stream. Each stage is a named subgraph
+ * (mounted via `graph.mount()`). Stages connect linearly:
+ * `merged → stage[0].input → stage[0].output → stage[1].input → ...`
+ *
+ * @param name - Graph name.
+ * @param sources - Input nodes to merge.
+ * @param stages - Sequential reduction stages.
+ * @param opts - Optional graph/meta options.
+ * @returns Graph with `"merged"` and mounted stage subgraphs.
+ *
+ * @category patterns
+ */
+declare function funnel<T>(name: string, sources: ReadonlyArray<Node<T>>, stages: ReadonlyArray<FunnelStage>, opts?: FunnelOptions): Graph;
+/** Options for {@link feedback}. */
+type FeedbackOptions = {
+    /** Maximum feedback iterations before stopping (default: 10). */
+    maxIterations?: number;
+    /** Optional budget gate node path for cost-bounded iteration. */
+    budgetNode?: StepRef;
+    meta?: Record<string, unknown>;
+};
+/**
+ * Introduce a bounded reactive cycle into an existing graph.
+ *
+ * When `condition` emits a non-null DATA value, the feedback effect routes it
+ * back to the `reentry` state node — creating a cycle. Bounded by
+ * `maxIterations` (default 10). The counter node (`__feedback_<condition>`)
+ * is the source of truth — reset it to 0 to allow more iterations.
+ *
+ * To remove the feedback cycle, call `graph.remove("__feedback_<condition>")`.
+ *
+ * @param graph - Existing graph to augment with a feedback cycle.
+ * @param condition - Path to a node whose DATA triggers feedback.
+ * @param reentry - Path to a state node that receives the feedback value.
+ * @param opts - Iteration bounds and metadata.
+ * @returns The same graph (mutated with feedback nodes added).
+ *
+ * @category patterns
+ */
+declare function feedback(graph: Graph, condition: string, reentry: string, opts?: FeedbackOptions): Graph;
+/** A reactive constraint for {@link budgetGate}. */
+type BudgetConstraint<T = unknown> = {
+    /** Constraint node whose value is checked. */
+    node: Node<T>;
+    /** Returns `true` when the constraint is satisfied (budget available). */
+    check: (value: T) => boolean;
+};
+/** Options for {@link budgetGate}. */
+type BudgetGateOptions = Omit<NodeOptions, "describeKind" | "name" | "meta"> & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Pass-through that respects reactive constraint nodes.
+ *
+ * DATA flows through when all constraints are satisfied. When any constraint
+ * is exceeded, PAUSE is sent upstream and DATA is buffered. When constraints
+ * relax, RESUME is sent and buffered DATA flushes.
+ *
+ * @param source - Input node.
+ * @param constraints - Reactive constraint checks.
+ * @param opts - Optional node options.
+ * @returns Gated node.
+ *
+ * @category patterns
+ */
+declare function budgetGate<T>(source: Node<T>, constraints: ReadonlyArray<BudgetConstraint>, opts?: BudgetGateOptions): Node<T>;
+/** A scored item with full breakdown. */
+type ScoredItem<T = unknown> = {
+    /** Original value. */
+    value: T;
+    /** Final weighted score. */
+    score: number;
+    /** Per-signal breakdown: signal index → weighted contribution. */
+    breakdown: number[];
+};
+/** Options for {@link scorer}. */
+type ScorerOptions = Omit<NodeOptions, "describeKind" | "name" | "meta"> & {
+    meta?: Record<string, unknown>;
+    /** Custom scoring function per signal. Default: identity (signal value IS the score). */
+    scoreFns?: ReadonlyArray<(value: unknown) => number>;
+};
+/**
+ * Reactive multi-signal scoring with live weights.
+ *
+ * Each source emits items to score. Weights are reactive state nodes that
+ * LLM or human can adjust live. Output is sorted scored items with full
+ * breakdown.
+ *
+ * @param sources - Signal nodes (each emits a numeric score dimension).
+ * @param weights - Reactive weight nodes (one per source).
+ * @param opts - Optional node/meta options.
+ * @returns Node emitting scored output.
+ *
+ * @category patterns
+ */
+declare function scorer(sources: ReadonlyArray<Node<number>>, weights: ReadonlyArray<Node<number>>, opts?: ScorerOptions): Node<ScoredItem<number[]>>;
+
+type reduction_BudgetConstraint<T = unknown> = BudgetConstraint<T>;
+type reduction_BudgetGateOptions = BudgetGateOptions;
+type reduction_FeedbackOptions = FeedbackOptions;
+type reduction_FunnelOptions = FunnelOptions;
+type reduction_FunnelStage = FunnelStage;
+type reduction_ScoredItem<T = unknown> = ScoredItem<T>;
+type reduction_ScorerOptions = ScorerOptions;
+type reduction_StepRef = StepRef;
+type reduction_StratifyOptions = StratifyOptions;
+type reduction_StratifyRule<T> = StratifyRule<T>;
+declare const reduction_budgetGate: typeof budgetGate;
+declare const reduction_feedback: typeof feedback;
+declare const reduction_funnel: typeof funnel;
+declare const reduction_scorer: typeof scorer;
+declare const reduction_stratify: typeof stratify;
+declare namespace reduction {
+  export { type reduction_BudgetConstraint as BudgetConstraint, type reduction_BudgetGateOptions as BudgetGateOptions, type reduction_FeedbackOptions as FeedbackOptions, type reduction_FunnelOptions as FunnelOptions, type reduction_FunnelStage as FunnelStage, type reduction_ScoredItem as ScoredItem, type reduction_ScorerOptions as ScorerOptions, type reduction_StepRef as StepRef, type reduction_StratifyOptions as StratifyOptions, type reduction_StratifyRule as StratifyRule, reduction_budgetGate as budgetGate, reduction_feedback as feedback, reduction_funnel as funnel, reduction_scorer as scorer, reduction_stratify as stratify };
 }
 
 /**
@@ -1603,8 +1777,9 @@ declare const index_cqrs: typeof cqrs;
 declare const index_memory: typeof memory;
 declare const index_messaging: typeof messaging;
 declare const index_orchestration: typeof orchestration;
+declare const index_reduction: typeof reduction;
 declare namespace index {
-  export { index_ai as ai, index_cqrs as cqrs, demoShell$1 as demoShell, index$b as layout, index_memory as memory, index_messaging as messaging, index_orchestration as orchestration };
+  export { index_ai as ai, index_cqrs as cqrs, demoShell$1 as demoShell, index$b as layout, index_memory as memory, index_messaging as messaging, index_orchestration as orchestration, index_reduction as reduction };
 }
 
 /**
@@ -1612,4 +1787,4 @@ declare namespace index {
  */
 declare const version = "0.0.0";
 
-export { Actor, AutoCheckpointAdapter, DistillBundle, Extraction, Graph, GraphAutoCheckpointHandle, GraphAutoCheckpointOptions, GraphOptions, Node, NodeActions, NodeFn, NodeInput, NodeOptions, ReactiveListSnapshot, ReactiveLogSnapshot, ReactiveMapSnapshot, ai, index$1 as compat, cqrs, demoShell$1 as demoShell, index$9 as jotai, index$b as layout, memory, messaging, index$8 as nanostores, index$a as nestjs, orchestration, index as patterns, index$7 as react, index$6 as signals, index$5 as solid, index$4 as svelte, version, index$3 as vue, index$2 as zustand };
+export { Actor, AutoCheckpointAdapter, DistillBundle, Extraction, Graph, GraphAutoCheckpointHandle, GraphAutoCheckpointOptions, GraphOptions, Node, NodeActions, NodeFn, NodeInput, NodeOptions, ReactiveListSnapshot, ReactiveLogSnapshot, ReactiveMapSnapshot, ai, index$1 as compat, cqrs, demoShell$1 as demoShell, index$9 as jotai, index$b as layout, memory, messaging, index$8 as nanostores, index$a as nestjs, orchestration, index as patterns, index$7 as react, reduction, index$6 as signals, index$5 as solid, index$4 as svelte, version, index$3 as vue, index$2 as zustand };