@q1k-oss/btree-workflows 0.0.1

package/src/composites/conditional.test.ts

@@ -0,0 +1,309 @@
+/**
+ * Tests for Conditional node
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { FailureNode, RunningNode, SuccessNode } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { Conditional } from "./conditional.js";
+
+describe("Conditional", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  describe("If-Then Logic", () => {
+    it("should execute then branch when condition succeeds", async () => {
+      const conditional = new Conditional({ id: "cond1" });
+      const condition = new SuccessNode({ id: "condition" });
+      const thenBranch = new SuccessNode({ id: "then" });
+
+      conditional.addChild(condition);
+      conditional.addChild(thenBranch);
+
+      const result = await conditional.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+      expect(thenBranch.status()).toBe(NodeStatus.SUCCESS);
+    });
+
+    it("should return then branch status", async () => {
+      const conditional = new Conditional({ id: "cond1" });
+      const condition = new SuccessNode({ id: "condition" });
+      const thenBranch = new FailureNode({ id: "then" });
+
+      conditional.addChild(condition);
+      conditional.addChild(thenBranch);
+
+      const result = await conditional.tick(context);
+      expect(result).toBe(NodeStatus.FAILURE);
+    });
+  });
+
+  describe("If-Else Logic", () => {
+    it("should execute else branch when condition fails", async () => {
+      const conditional = new Conditional({ id: "cond1" });
+      const condition = new FailureNode({ id: "condition" });
+      const thenBranch = new SuccessNode({ id: "then" });
+      const elseBranch = new SuccessNode({ id: "else" });
+
+      conditional.addChild(condition);
+      conditional.addChild(thenBranch);
+      conditional.addChild(elseBranch);
+
+      const result = await conditional.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+      expect(thenBranch.status()).toBe(NodeStatus.IDLE); // Not executed
+      expect(elseBranch.status()).toBe(NodeStatus.SUCCESS);
+    });
+
+    it("should return else branch status", async () => {
+      const conditional = new Conditional({ id: "cond1" });
+      const condition = new FailureNode({ id: "condition" });
+      const thenBranch = new SuccessNode({ id: "then" });
+      const elseBranch = new FailureNode({ id: "else" });
+
+      conditional.addChild(condition);
+      conditional.addChild(thenBranch);
+      conditional.addChild(elseBranch);
+
+      const result = await conditional.tick(context);
+      expect(result).toBe(NodeStatus.FAILURE);
+    });
+
+    it(
+      "should return FAILURE when condition fails and no else branch",
+      async () => {
+        const conditional = new Conditional({ id: "cond1" });
+        const condition = new FailureNode({ id: "condition" });
+        const thenBranch = new SuccessNode({ id: "then" });
+
+        conditional.addChild(condition);
+        conditional.addChild(thenBranch);
+
+        const result = await conditional.tick(context);
+        expect(result).toBe(NodeStatus.FAILURE);
+        expect(thenBranch.status()).toBe(NodeStatus.IDLE);
+      },
+    );
+  });
+
+  describe("RUNNING State", () => {
+    it("should return RUNNING when condition is running", async () => {
+      const conditional = new Conditional({ id: "cond1" });
+      const condition = new RunningNode({ id: "condition" });
+      const thenBranch = new SuccessNode({ id: "then" });
+
+      conditional.addChild(condition);
+      conditional.addChild(thenBranch);
+
+      const result = await conditional.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+      expect(thenBranch.status()).toBe(NodeStatus.IDLE); // Not executed
+    });
+
+    it("should return RUNNING when then branch is running", async () => {
+      const conditional = new Conditional({ id: "cond1" });
+      const condition = new SuccessNode({ id: "condition" });
+      const thenBranch = new RunningNode({ id: "then" });
+
+      conditional.addChild(condition);
+      conditional.addChild(thenBranch);
+
+      const result = await conditional.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+    });
+
+    it("should return RUNNING when else branch is running", async () => {
+      const conditional = new Conditional({ id: "cond1" });
+      const condition = new FailureNode({ id: "condition" });
+      const thenBranch = new SuccessNode({ id: "then" });
+      const elseBranch = new RunningNode({ id: "else" });
+
+      conditional.addChild(condition);
+      conditional.addChild(thenBranch);
+      conditional.addChild(elseBranch);
+
+      const result = await conditional.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should enforce maximum 3 children", () => {
+      const conditional = new Conditional({ id: "cond1" });
+      conditional.addChild(new SuccessNode({ id: "child1" }));
+      conditional.addChild(new SuccessNode({ id: "child2" }));
+      conditional.addChild(new SuccessNode({ id: "child3" }));
+
+      expect(() => {
+        conditional.addChild(new SuccessNode({ id: "child4" }));
+      }).toThrow("Conditional can have maximum 3 children");
+    });
+
+    it("should return FAILURE without condition", async () => {
+      const conditional = new Conditional({ id: "cond1" });
+
+      const status = await conditional.tick(context);
+      expect(status).toBe(NodeStatus.FAILURE);
+    });
+
+    it("should return FAILURE without then branch", async () => {
+      const conditional = new Conditional({ id: "cond1" });
+      conditional.addChild(new SuccessNode({ id: "condition" }));
+
+      const status = await conditional.tick(context);
+      expect(status).toBe(NodeStatus.FAILURE);
+    });
+  });
+
+  describe("Multi-tick branch execution - FIXED BEHAVIOR", () => {
+    it(
+      "should check condition ONCE and not re-check while branch is RUNNING",
+      async () => {
+        let conditionTickCount = 0;
+        let branchTickCount = 0;
+
+        // Condition that counts how many times it's checked
+        class CountingCondition extends SuccessNode {
+          async tick(_context: TemporalContext): Promise<NodeStatus> {
+            conditionTickCount++;
+            console.log(`[CountingCondition] Tick #${conditionTickCount}`);
+            this._status = NodeStatus.SUCCESS;
+            return NodeStatus.SUCCESS;
+          }
+        }
+
+        // Branch that returns RUNNING for first 2 ticks, then SUCCESS
+        class MultiTickBranch extends SuccessNode {
+          async tick(context: TemporalContext): Promise<NodeStatus> {
+            const superTick = super.tick.bind(this);
+            branchTickCount++;
+            console.log(`[MultiTickBranch] Tick #${branchTickCount}`);
+
+            if (branchTickCount < 3) {
+              this._status = NodeStatus.RUNNING;
+              return NodeStatus.RUNNING;
+            }
+
+            return await superTick(context); // SUCCESS on tick 3
+          }
+        }
+
+        const condition = new CountingCondition({ id: "counting-condition" });
+        const thenBranch = new MultiTickBranch({ id: "multi-tick-branch" });
+        const conditional = new Conditional({
+          id: "test-conditional",
+          name: "test-conditional",
+        });
+
+        conditional.addChild(condition);
+        conditional.addChild(thenBranch);
+
+        // Tick 1: Should check condition, then execute branch (returns RUNNING)
+        const status1 = await conditional.tick(context);
+        expect(status1).toBe(NodeStatus.RUNNING);
+        expect(conditionTickCount).toBe(1); // Condition checked once
+        expect(branchTickCount).toBe(1); // Branch executed once
+
+        // Tick 2: FIXED: Should NOT re-check condition, just execute branch (returns RUNNING)
+        const status2 = await conditional.tick(context);
+        expect(status2).toBe(NodeStatus.RUNNING);
+        expect(conditionTickCount).toBe(1); // Still 1! Not re-checked
+        expect(branchTickCount).toBe(2); // Branch executed again
+
+        // Tick 3: FIXED: Should NOT re-check condition, just execute branch (returns SUCCESS)
+        const status3 = await conditional.tick(context);
+        expect(status3).toBe(NodeStatus.SUCCESS);
+        expect(conditionTickCount).toBe(1); // Still 1! Not re-checked
+        expect(branchTickCount).toBe(3); // Branch completes
+
+        // Summary: Condition was checked only 1 time (on first tick)
+        // This confirms the condition is NOT re-evaluated on subsequent ticks
+        console.log(
+          "\n✅ FIXED: Condition checked only 1 time, not re-checked during branch execution",
+        );
+      },
+    );
+
+    it(
+      "should NOT be affected if condition changes while branch is RUNNING",
+      async () => {
+        let branchTickCount = 0;
+        let conditionShouldSucceed = true;
+
+        // Condition that succeeds initially, then fails on subsequent ticks
+        class ChangeableCondition extends SuccessNode {
+          async tick(_context: TemporalContext): Promise<NodeStatus> {
+            const result = conditionShouldSucceed
+              ? NodeStatus.SUCCESS
+              : NodeStatus.FAILURE;
+            console.log(`[ChangeableCondition] Returning: ${result}`);
+            this._status = result;
+            return result;
+          }
+        }
+
+        // Branch that takes 3 ticks to complete
+        class SlowBranch extends SuccessNode {
+          async tick(context: TemporalContext): Promise<NodeStatus> {
+            const superTick = super.tick.bind(this);
+            branchTickCount++;
+            console.log(`[SlowBranch] Tick #${branchTickCount}`);
+
+            if (branchTickCount < 3) {
+              this._status = NodeStatus.RUNNING;
+              return NodeStatus.RUNNING;
+            }
+
+            return await superTick(context); // SUCCESS on tick 3
+          }
+        }
+
+        const condition = new ChangeableCondition({
+          id: "changeable-condition",
+        });
+        const thenBranch = new SlowBranch({ id: "slow-branch" });
+        const conditional = new Conditional({
+          id: "test-conditional",
+          name: "test-conditional",
+        });
+
+        conditional.addChild(condition);
+        conditional.addChild(thenBranch);
+
+        // Tick 1: Condition passes, branch returns RUNNING
+        const status1 = await conditional.tick(context);
+        expect(status1).toBe(NodeStatus.RUNNING);
+        expect(branchTickCount).toBe(1);
+
+        // Change condition to fail
+        conditionShouldSucceed = false;
+
+        // Tick 2: FIXED: Condition is NOT re-checked, branch continues
+        const status2 = await conditional.tick(context);
+        expect(status2).toBe(NodeStatus.RUNNING); // Still RUNNING!
+        expect(branchTickCount).toBe(2); // Branch continues executing
+
+        // Tick 3: FIXED: Branch completes successfully despite condition now failing
+        const status3 = await conditional.tick(context);
+        expect(status3).toBe(NodeStatus.SUCCESS); // Branch completes!
+        expect(branchTickCount).toBe(3); // Branch executed all 3 ticks
+
+        // This demonstrates the fix: branch execution is NOT interrupted
+        // even though the condition would now fail if re-checked
+        console.log(
+          "\n✅ SAFE: Branch execution continues uninterrupted despite condition change",
+        );
+      },
+    );
+  });
+});

package/src/composites/conditional.ts

@@ -0,0 +1,129 @@
+/**
+ * Conditional node - If-then-else logic for behavior trees
+ */
+
+import { CompositeNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import { type TemporalContext, NodeStatus, type TreeNode } from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+/**
+ * Conditional implements if-then-else logic.
+ * Structure:
+ * - First child = condition
+ * - Second child = then branch
+ * - Third child (optional) = else branch
+ */
+export class Conditional extends CompositeNode {
+  private condition?: TreeNode;
+  private thenBranch?: TreeNode;
+  private elseBranch?: TreeNode;
+  private conditionEvaluated: boolean = false;
+  private selectedBranch?: TreeNode;
+
+  /**
+   * Override addChild to enforce conditional structure
+   */
+  addChild(child: TreeNode): void {
+    if (!this.condition) {
+      this.condition = child;
+      this._children.push(child);
+      child.parent = this;
+    } else if (!this.thenBranch) {
+      this.thenBranch = child;
+      this._children.push(child);
+      child.parent = this;
+    } else if (!this.elseBranch) {
+      this.elseBranch = child;
+      this._children.push(child);
+      child.parent = this;
+    } else {
+      throw new ConfigurationError(
+        "Conditional can have maximum 3 children (condition, then, else)",
+      );
+    }
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    // Check for cancellation before processing conditional
+    checkSignal(context.signal);
+
+    if (!this.condition) {
+      throw new Error("Conditional requires at least a condition child");
+    }
+
+    if (!this.thenBranch) {
+      throw new Error(
+        "Conditional requires at least condition and then branch",
+      );
+    }
+
+    // Only evaluate condition if not already evaluated
+    if (!this.conditionEvaluated) {
+      this.log("Evaluating condition");
+      const conditionStatus = await this.condition.tick(context);
+
+      switch (conditionStatus) {
+        case NodeStatus.SUCCESS:
+          this.log("Condition succeeded - will execute then branch");
+          this.selectedBranch = this.thenBranch;
+          this.conditionEvaluated = true;
+          break;
+
+        case NodeStatus.FAILURE:
+          if (this.elseBranch) {
+            this.log("Condition failed - will execute else branch");
+            this.selectedBranch = this.elseBranch;
+            this.conditionEvaluated = true;
+          } else {
+            this.log("Condition failed - no else branch, returning FAILURE");
+            this._status = NodeStatus.FAILURE;
+            return NodeStatus.FAILURE;
+          }
+          break;
+
+        case NodeStatus.RUNNING:
+          this.log("Condition is running");
+          this._status = NodeStatus.RUNNING;
+          return NodeStatus.RUNNING;
+
+        default:
+          throw new Error(
+            `Unexpected status from condition: ${conditionStatus}`,
+          );
+      }
+    } else {
+      this.log("Condition already evaluated - continuing branch execution");
+    }
+
+    // Execute selected branch
+    if (!this.selectedBranch) {
+      throw new Error("No branch selected for execution");
+    }
+
+    const branchStatus = await this.selectedBranch.tick(context);
+    this._status = branchStatus;
+
+    // Reset flag when branch completes
+    if (branchStatus !== NodeStatus.RUNNING) {
+      this.log("Branch completed - resetting condition check flag");
+      this.conditionEvaluated = false;
+      this.selectedBranch = undefined;
+    }
+
+    return branchStatus;
+  }
+
+  protected onHalt(): void {
+    this.log("Halting - resetting condition check flag");
+    this.conditionEvaluated = false;
+    this.selectedBranch = undefined;
+    super.onHalt();
+  }
+
+  protected onReset(): void {
+    this.log("Resetting - clearing condition check flag");
+    this.conditionEvaluated = false;
+    this.selectedBranch = undefined;
+  }
+}

package/src/composites/for-each.schema.ts

@@ -0,0 +1,23 @@
+/**
+ * ForEach composite configuration schema
+ */
+
+import { z } from "zod";
+import { createNodeSchema, validations } from "../schemas/base.schema.js";
+
+/**
+ * Schema for ForEach composite configuration
+ * Validates collection and item keys
+ */
+export const forEachConfigurationSchema = createNodeSchema("ForEach", {
+  collectionKey: validations.blackboardKey,
+  itemKey: validations.blackboardKey,
+  indexKey: validations.blackboardKey.optional(),
+});
+
+/**
+ * Validated ForEach configuration type
+ */
+export type ValidatedForEachConfiguration = z.infer<
+  typeof forEachConfigurationSchema
+>;