@q1k-oss/btree-workflows 0.0.1 → 0.0.2

package/src/composites/parallel.ts

@@ -1,157 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * 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

@@ -1,170 +0,0 @@
-/**
- * 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

@@ -1,85 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * 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
->;