@q1k-oss/btree-workflows 0.0.1

package/src/composites/parallel.ts

@@ -0,0 +1,157 @@
+/**
+ * Parallel composite node
+ * Executes all children concurrently (truly concurrent, not sequential)
+ */
+
+import { CompositeNode } from "../base-node.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  NodeStatus,
+} from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+/**
+ * Execution strategy for parallel node
+ */
+export type ParallelStrategy =
+  | "strict" // All children must succeed
+  | "any"; // At least one child must succeed
+
+export interface ParallelConfiguration extends NodeConfiguration {
+  /**
+   * Execution strategy
+   * - 'strict': All children must succeed (default)
+   * - 'any': At least one child must succeed
+   */
+  strategy?: ParallelStrategy;
+
+  /**
+   * Optional: Number of children that must succeed (overrides strategy)
+   */
+  successThreshold?: number;
+
+  /**
+   * Optional: Number of children that must fail before parallel fails
+   */
+  failureThreshold?: number;
+}
+
+export class Parallel extends CompositeNode {
+  private strategy: ParallelStrategy;
+  private successThreshold?: number;
+  private failureThreshold?: number;
+
+  constructor(config: ParallelConfiguration) {
+    super(config);
+    this.strategy = config.strategy ?? "strict";
+    this.successThreshold = config.successThreshold;
+    this.failureThreshold = config.failureThreshold;
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    this.log(
+      `Ticking with ${this._children.length} children (strategy: ${this.strategy})`,
+    );
+
+    if (this._children.length === 0) {
+      return NodeStatus.SUCCESS;
+    }
+
+    // Only tick children that haven't completed yet (IDLE or RUNNING)
+    // Children that are SUCCESS or FAILURE should keep their status
+    const childrenToTick = this._children.filter((child) => {
+      const status = child.status();
+      return status === NodeStatus.IDLE || status === NodeStatus.RUNNING;
+    });
+
+    this.log(
+      `Ticking ${childrenToTick.length}/${this._children.length} children (others completed)`,
+    );
+
+    // Check for cancellation before concurrent execution
+    checkSignal(context.signal);
+
+    // Tick active children concurrently using Promise.all
+    if (childrenToTick.length > 0) {
+      await Promise.all(childrenToTick.map((child) => child.tick(context)));
+    }
+
+    // Collect all statuses (from both ticked and already-completed children)
+    const allStatuses = this._children.map((child) => child.status());
+
+    // Check if any child is still running
+    const hasRunning = allStatuses.some(
+      (status) => status === NodeStatus.RUNNING,
+    );
+    if (hasRunning) {
+      this.log("At least one child returned RUNNING");
+      return NodeStatus.RUNNING;
+    }
+
+    // All children completed - count successes and failures
+    const successes = allStatuses.filter(
+      (status) => status === NodeStatus.SUCCESS,
+    ).length;
+    const failures = allStatuses.filter(
+      (status) => status === NodeStatus.FAILURE,
+    ).length;
+
+    this.log(`Results - Successes: ${successes}, Failures: ${failures}`);
+
+    // Check threshold-based completion first (if configured)
+    if (
+      this.successThreshold !== undefined &&
+      successes >= this.successThreshold
+    ) {
+      this.log(
+        `Success threshold met: ${successes}/${this.successThreshold} -> SUCCESS`,
+      );
+      return NodeStatus.SUCCESS;
+    }
+
+    if (
+      this.failureThreshold !== undefined &&
+      failures >= this.failureThreshold
+    ) {
+      this.log(
+        `Failure threshold met: ${failures}/${this.failureThreshold} -> FAILURE`,
+      );
+      return NodeStatus.FAILURE;
+    }
+
+    // Apply strategy
+    if (this.strategy === "strict") {
+      // All must succeed
+      const finalStatus =
+        successes === this._children.length
+          ? NodeStatus.SUCCESS
+          : NodeStatus.FAILURE;
+      this.log(
+        `Strategy 'strict': ${successes}/${this._children.length} succeeded -> ${finalStatus}`,
+      );
+      return finalStatus;
+    } else {
+      // Any (at least one must succeed)
+      const finalStatus =
+        successes > 0 ? NodeStatus.SUCCESS : NodeStatus.FAILURE;
+      this.log(`Strategy 'any': ${successes} succeeded -> ${finalStatus}`);
+      return finalStatus;
+    }
+  }
+
+  protected onHalt(): void {
+    this.log("Halting parallel execution");
+    // Halt all running children
+    for (const child of this._children) {
+      if (child.status() === NodeStatus.RUNNING) {
+        child.halt();
+      }
+    }
+  }
+
+  protected onReset(): void {
+    this.log("Resetting parallel state");
+    // Reset handled by parent class
+  }
+}

package/src/composites/reactive-sequence.schema.ts

@@ -0,0 +1,19 @@
+/**
+ * ReactiveSequence composite configuration schema
+ */
+
+import { z } from "zod";
+import { nodeConfigurationSchema } from "../schemas/base.schema.js";
+
+/**
+ * Schema for ReactiveSequence composite configuration
+ * Uses base schema only (no additional properties)
+ */
+export const reactiveSequenceConfigurationSchema = nodeConfigurationSchema;
+
+/**
+ * Validated ReactiveSequence configuration type
+ */
+export type ValidatedReactiveSequenceConfiguration = z.infer<
+  typeof reactiveSequenceConfigurationSchema
+>;

package/src/composites/reactive-sequence.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Tests for ReactiveSequence node
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { FailureNode, SuccessNode } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { ReactiveSequence } from "./reactive-sequence.js";
+
+describe("ReactiveSequence", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  describe("Basic Functionality", () => {
+    it("should execute children in order", async () => {
+      const seq = new ReactiveSequence({ id: "seq1" });
+      const child1 = new SuccessNode({ id: "child1" });
+      const child2 = new SuccessNode({ id: "child2" });
+      const child3 = new SuccessNode({ id: "child3" });
+
+      seq.addChildren([child1, child2, child3]);
+
+      const result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+    });
+
+    it("should fail fast on first failure", async () => {
+      const seq = new ReactiveSequence({ id: "seq1" });
+      const child1 = new SuccessNode({ id: "child1" });
+      const child2 = new FailureNode({ id: "child2" });
+      const child3 = new SuccessNode({ id: "child3" });
+
+      seq.addChildren([child1, child2, child3]);
+
+      const result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.FAILURE);
+      expect(child3.status()).toBe(NodeStatus.IDLE); // Never executed
+    });
+  });
+
+  describe("Reactive Behavior", () => {
+    it("should restart from beginning each tick", async () => {
+      const seq = new ReactiveSequence({ id: "seq1" });
+
+      // Track ticks for each child
+      let child1Ticks = 0;
+      let child2Ticks = 0;
+
+      class CountingSuccess extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          if (this.id === "child1") child1Ticks++;
+          if (this.id === "child2") child2Ticks++;
+          return await superTick(context);
+        }
+      }
+
+      const child1 = new CountingSuccess({ id: "child1" });
+      const child2 = new CountingSuccess({ id: "child2" });
+
+      // Child3 runs first time, succeeds second time
+      let child3TickCount = 0;
+      class TwoTickNode extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          child3TickCount++;
+          if (child3TickCount === 1) {
+            this._status = NodeStatus.RUNNING;
+            return NodeStatus.RUNNING;
+          }
+          return await superTick(context);
+        }
+      }
+      const child3 = new TwoTickNode({ id: "child3" });
+
+      seq.addChildren([child1, child2, child3]);
+
+      // First tick: child1, child2 succeed, child3 returns RUNNING
+      let result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+      expect(child1Ticks).toBe(1);
+      expect(child2Ticks).toBe(1);
+      expect(child3TickCount).toBe(1);
+
+      // Second tick: should restart from child1 (reactive behavior)
+      result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+      expect(child1Ticks).toBe(2); // Re-executed
+      expect(child2Ticks).toBe(2); // Re-executed
+      expect(child3TickCount).toBe(2);
+    });
+
+    it("should re-evaluate conditions that might change", async () => {
+      const seq = new ReactiveSequence({ id: "seq1" });
+
+      // Condition that checks blackboard value
+      let conditionTicks = 0;
+      class CheckValueCondition extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          conditionTicks++;
+          const value = context.blackboard.get("shouldContinue");
+          this._status = value ? NodeStatus.SUCCESS : NodeStatus.FAILURE;
+          return this._status;
+        }
+      }
+
+      const condition = new CheckValueCondition({ id: "condition" });
+
+      // Action that stays running
+      let actionTicks = 0;
+      class RunningAction extends SuccessNode {
+        async tick(_context: TemporalContext): Promise<NodeStatus> {
+          actionTicks++;
+          this._status = NodeStatus.RUNNING;
+          return NodeStatus.RUNNING;
+        }
+      }
+      const action = new RunningAction({ id: "action" });
+
+      seq.addChildren([condition, action]);
+
+      // First tick: condition true, action runs
+      blackboard.set("shouldContinue", true);
+      let result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+      expect(conditionTicks).toBe(1);
+      expect(actionTicks).toBe(1);
+
+      // Second tick: condition still true, both re-evaluated
+      result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+      expect(conditionTicks).toBe(2); // Condition re-checked
+      expect(actionTicks).toBe(2);
+
+      // Third tick: condition becomes false, sequence fails
+      blackboard.set("shouldContinue", false);
+      result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.FAILURE);
+      expect(conditionTicks).toBe(3); // Condition re-checked again
+      expect(actionTicks).toBe(2); // Action not ticked (condition failed)
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle empty children array", async () => {
+      const seq = new ReactiveSequence({ id: "seq1" });
+      const result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+    });
+
+    it("should handle single child", async () => {
+      const seq = new ReactiveSequence({ id: "seq1" });
+      const child = new SuccessNode({ id: "child1" });
+      seq.addChild(child);
+
+      const result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+    });
+  });
+});

package/src/composites/reactive-sequence.ts

@@ -0,0 +1,85 @@
+/**
+ * ReactiveSequence node - Restarts from beginning each tick
+ * Responds to condition changes during execution
+ */
+
+import { ConfigurationError } from "../errors.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+import { Sequence } from "./sequence.js";
+
+/**
+ * ReactiveSequence restarts from the beginning on each tick.
+ * Unlike regular Sequence which remembers its position, ReactiveSequence
+ * re-evaluates all children from the start, making it responsive to
+ * conditions that might change between ticks.
+ *
+ * Use cases:
+ * - Real-time monitoring where conditions might change
+ * - Safety-critical checks that must be re-evaluated
+ * - Guard conditions that need constant verification
+ */
+export class ReactiveSequence extends Sequence {
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    this.log("Ticking (reactive - always starts from beginning)");
+
+    if (this._children.length === 0) {
+      return NodeStatus.SUCCESS;
+    }
+
+    // Always start from child 0 (reactive behavior)
+    // Don't use currentChildIndex from parent Sequence
+    for (let i = 0; i < this._children.length; i++) {
+      // Check for cancellation before ticking each child
+      checkSignal(context.signal);
+
+      const child = this._children[i];
+      if (!child) {
+        throw new ConfigurationError(`Child at index ${i} is undefined`);
+      }
+
+      this.log(`Ticking child ${i}: ${child.name}`);
+      const childStatus = await child.tick(context);
+
+      switch (childStatus) {
+        case NodeStatus.SUCCESS:
+          this.log(`Child ${child.name} succeeded`);
+          // Continue to next child
+          break;
+
+        case NodeStatus.FAILURE:
+          this.log(`Child ${child.name} failed - sequence fails`);
+          this._status = NodeStatus.FAILURE;
+          return NodeStatus.FAILURE;
+
+        case NodeStatus.RUNNING:
+          this.log(`Child ${child.name} is running`);
+          this._status = NodeStatus.RUNNING;
+          // Return RUNNING but don't save position - will restart next tick
+          return NodeStatus.RUNNING;
+
+        default:
+          throw new Error(`Unexpected status from child: ${childStatus}`);
+      }
+    }
+
+    // All children succeeded
+    this.log("All children succeeded");
+    this._status = NodeStatus.SUCCESS;
+    return NodeStatus.SUCCESS;
+  }
+
+  /**
+   * Override to prevent parent Sequence from resetting currentChildIndex
+   * (ReactiveSequence doesn't use currentChildIndex)
+   */
+  protected onReset(): void {
+    // Call BaseNode reset (skip Sequence reset)
+    this._status = NodeStatus.IDLE;
+
+    // Reset all children
+    for (const child of this._children) {
+      child.reset();
+    }
+  }
+}

package/src/composites/recovery.schema.ts

@@ -0,0 +1,19 @@
+/**
+ * Recovery composite configuration schema
+ */
+
+import { z } from "zod";
+import { nodeConfigurationSchema } from "../schemas/base.schema.js";
+
+/**
+ * Schema for Recovery composite configuration
+ * Uses base schema only - try/catch/finally logic is in child structure
+ */
+export const recoveryConfigurationSchema = nodeConfigurationSchema;
+
+/**
+ * Validated Recovery configuration type
+ */
+export type ValidatedRecoveryConfiguration = z.infer<
+  typeof recoveryConfigurationSchema
+>;