@q1k-oss/btree-workflows 0.0.1

package/src/decorators/precondition.test.ts

@@ -0,0 +1,351 @@
+/**
+ * Tests for Precondition decorator
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { ConfigurationError } from "../errors.js";
+import { FailureNode, SuccessNode } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { Precondition } from "./precondition.js";
+
+describe("Precondition", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should execute child when precondition succeeds", async () => {
+    const precond = new Precondition({ id: "precond1" });
+
+    let childExecuted = false;
+    class TrackedChild extends SuccessNode {
+      tick(context: TemporalContext) {
+        childExecuted = true;
+        return super.tick(context);
+      }
+    }
+
+    precond.setChild(new TrackedChild({ id: "child" }));
+    precond.addPrecondition(new SuccessNode({ id: "condition" }));
+
+    const result = await precond.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(childExecuted).toBe(true);
+  });
+
+  it("should fail if required precondition not met", async () => {
+    const precond = new Precondition({ id: "precond1" });
+
+    precond.setChild(new SuccessNode({ id: "child" }));
+    precond.addPrecondition(
+      new FailureNode({ id: "condition" }),
+      undefined,
+      true,
+    );
+
+    const result = await precond.tick(context);
+    expect(result).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should run resolver on precondition failure", async () => {
+    const precond = new Precondition({ id: "precond1" });
+
+    let resolverExecuted = false;
+    class TrackedResolver extends SuccessNode {
+      tick(context: TemporalContext) {
+        const superTick = super.tick.bind(this);
+        return (async () => {
+          resolverExecuted = true;
+          // Fix the condition
+          context.blackboard.set("conditionMet", true);
+          return await superTick(context);
+        })();
+      }
+    }
+
+    // Condition checks blackboard
+    class BlackboardCondition extends SuccessNode {
+      tick(context: TemporalContext) {
+        const self = this;
+        return (async () => {
+          const met = context.blackboard.get("conditionMet");
+          self._status = met ? NodeStatus.SUCCESS : NodeStatus.FAILURE;
+          return self._status;
+        })();
+      }
+    }
+
+    precond.setChild(new SuccessNode({ id: "child" }));
+    precond.addPrecondition(
+      new BlackboardCondition({ id: "condition" }),
+      new TrackedResolver({ id: "resolver" }),
+      true,
+    );
+
+    const result = await precond.tick(context);
+    expect(resolverExecuted).toBe(true);
+    expect(result).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should skip optional preconditions", async () => {
+    const precond = new Precondition({ id: "precond1" });
+
+    let childExecuted = false;
+    class TrackedChild extends SuccessNode {
+      tick(context: TemporalContext) {
+        childExecuted = true;
+        return super.tick(context);
+      }
+    }
+
+    precond.setChild(new TrackedChild({ id: "child" }));
+    precond.addPrecondition(
+      new FailureNode({ id: "condition" }),
+      undefined,
+      false,
+    ); // Optional
+
+    const result = await precond.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(childExecuted).toBe(true);
+  });
+
+  it("should check multiple preconditions", async () => {
+    const precond = new Precondition({ id: "precond1" });
+
+    precond.setChild(new SuccessNode({ id: "child" }));
+    precond.addPrecondition(new SuccessNode({ id: "cond1" }));
+    precond.addPrecondition(new SuccessNode({ id: "cond2" }));
+    precond.addPrecondition(new SuccessNode({ id: "cond3" }));
+
+    const result = await precond.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should fail on first failed required precondition", async () => {
+    const precond = new Precondition({ id: "precond1" });
+
+    let cond3Checked = false;
+    class Cond3 extends SuccessNode {
+      tick(context: TemporalContext) {
+        const superTick = super.tick.bind(this);
+        return (async () => {
+          cond3Checked = true;
+          return await superTick(context);
+        })();
+      }
+    }
+
+    precond.setChild(new SuccessNode({ id: "child" }));
+    precond.addPrecondition(new SuccessNode({ id: "cond1" }));
+    precond.addPrecondition(new FailureNode({ id: "cond2" })); // Fails here
+    precond.addPrecondition(new Cond3({ id: "cond3" }));
+
+    const result = await precond.tick(context);
+    expect(result).toBe(NodeStatus.FAILURE);
+    expect(cond3Checked).toBe(false); // Should not reach cond3
+  });
+
+  it("should propagate RUNNING from precondition", async () => {
+    const precond = new Precondition({ id: "precond1" });
+
+    let tickCount = 0;
+    class RunningCondition extends SuccessNode {
+      tick(_context: TemporalContext) {
+        const self = this;
+        return (async () => {
+          tickCount++;
+          self._status =
+            tickCount < 2 ? NodeStatus.RUNNING : NodeStatus.SUCCESS;
+          return self._status;
+        })();
+      }
+    }
+
+    precond.setChild(new SuccessNode({ id: "child" }));
+    precond.addPrecondition(new RunningCondition({ id: "condition" }));
+
+    let result = await precond.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+
+    result = await precond.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should propagate ConfigurationError if no child", async () => {
+    const precond = new Precondition({ id: "precond1" });
+    precond.addPrecondition(new SuccessNode({ id: "condition" }));
+
+    try {
+      await precond.tick(context);
+      throw new Error("Expected tick to throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConfigurationError);
+      expect((error as ConfigurationError).message).toContain(
+        "Precondition requires a child",
+      );
+    }
+  });
+
+  describe("Multi-tick child execution - FIXED BEHAVIOR", () => {
+    it(
+      "should check precondition ONCE and not re-check while child is RUNNING",
+      async () => {
+        let conditionTickCount = 0;
+        let childTickCount = 0;
+
+        // Condition that counts how many times it's checked
+        class CountingCondition extends SuccessNode {
+          tick(_context: TemporalContext) {
+            const self = this;
+            return (async () => {
+              conditionTickCount++;
+              console.log(`[CountingCondition] Tick #${conditionTickCount}`);
+              self._status = NodeStatus.SUCCESS;
+              return NodeStatus.SUCCESS;
+            })();
+          }
+        }
+
+        // Child that returns RUNNING for first 2 ticks, then SUCCESS
+        class MultiTickChild extends SuccessNode {
+          tick(context: TemporalContext) {
+            const self = this;
+            const superTick = super.tick.bind(this);
+            return (async () => {
+              childTickCount++;
+              console.log(`[MultiTickChild] Tick #${childTickCount}`);
+
+              if (childTickCount < 3) {
+                self._status = NodeStatus.RUNNING;
+                return NodeStatus.RUNNING;
+              }
+
+              return await superTick(context); // SUCCESS on tick 3
+            })();
+          }
+        }
+
+        const condition = new CountingCondition({ id: "counting-condition" });
+        const child = new MultiTickChild({ id: "multi-tick-child" });
+        const precondition = new Precondition({
+          id: "test-precondition",
+          name: "test-precondition",
+        });
+
+        precondition.setChild(child);
+        precondition.addPrecondition(condition);
+
+        // Tick 1: Should check condition, then execute child (returns RUNNING)
+        const status1 = await precondition.tick(context);
+        expect(status1).toBe(NodeStatus.RUNNING);
+        expect(conditionTickCount).toBe(1); // Condition checked once
+        expect(childTickCount).toBe(1); // Child executed once
+
+        // Tick 2: ✅ FIXED: Should NOT re-check condition, just execute child (returns RUNNING)
+        const status2 = await precondition.tick(context);
+        expect(status2).toBe(NodeStatus.RUNNING);
+        expect(conditionTickCount).toBe(1); // ✅ Still 1! Not re-checked
+        expect(childTickCount).toBe(2); // Child executed again
+
+        // Tick 3: ✅ FIXED: Should NOT re-check condition, just execute child (returns SUCCESS)
+        const status3 = await precondition.tick(context);
+        expect(status3).toBe(NodeStatus.SUCCESS);
+        expect(conditionTickCount).toBe(1); // ✅ Still 1! Not re-checked
+        expect(childTickCount).toBe(3); // Child completes
+
+        // Summary: Condition was checked only 1 time (on first tick)
+        // This confirms the precondition is NOT re-evaluated on subsequent ticks
+        console.log(
+          "\n✅ FIXED: Precondition checked only 1 time, not re-checked during child execution",
+        );
+      },
+    );
+
+    it(
+      "should NOT be affected if precondition changes while child is RUNNING (safe behavior)",
+      async () => {
+        let childTickCount = 0;
+        let conditionShouldSucceed = true;
+
+        // Condition that succeeds initially, then fails on subsequent ticks
+        class ChangeableCondition extends SuccessNode {
+          tick(_context: TemporalContext) {
+            const self = this;
+            return (async () => {
+              const result = conditionShouldSucceed
+                ? NodeStatus.SUCCESS
+                : NodeStatus.FAILURE;
+              console.log(`[ChangeableCondition] Returning: ${result}`);
+              self._status = result;
+              return result;
+            })();
+          }
+        }
+
+        // Child that takes 3 ticks to complete
+        class SlowChild extends SuccessNode {
+          tick(context: TemporalContext) {
+            const self = this;
+            const superTick = super.tick.bind(this);
+            return (async () => {
+              childTickCount++;
+              console.log(`[SlowChild] Tick #${childTickCount}`);
+
+              if (childTickCount < 3) {
+                self._status = NodeStatus.RUNNING;
+                return NodeStatus.RUNNING;
+              }
+
+              return await superTick(context); // SUCCESS on tick 3
+            })();
+          }
+        }
+
+        const condition = new ChangeableCondition({
+          id: "changeable-condition",
+        });
+        const child = new SlowChild({ id: "slow-child" });
+        const precondition = new Precondition({
+          id: "test-precondition",
+          name: "test-precondition",
+        });
+
+        precondition.setChild(child);
+        precondition.addPrecondition(condition);
+
+        // Tick 1: Precondition passes, child returns RUNNING
+        const status1 = await precondition.tick(context);
+        expect(status1).toBe(NodeStatus.RUNNING);
+        expect(childTickCount).toBe(1);
+
+        // Change condition to fail
+        conditionShouldSucceed = false;
+
+        // Tick 2: ✅ FIXED: Precondition is NOT re-checked, child continues
+        const status2 = await precondition.tick(context);
+        expect(status2).toBe(NodeStatus.RUNNING); // ✅ Still RUNNING!
+        expect(childTickCount).toBe(2); // ✅ Child continues executing
+
+        // Tick 3: ✅ FIXED: Child completes successfully despite precondition now failing
+        const status3 = await precondition.tick(context);
+        expect(status3).toBe(NodeStatus.SUCCESS); // ✅ Child completes!
+        expect(childTickCount).toBe(3); // Child executed all 3 ticks
+
+        // This demonstrates the fix: child execution is NOT interrupted
+        // even though the precondition would now fail if re-checked
+        console.log(
+          "\n✅ SAFE: Child execution continues uninterrupted despite precondition change",
+        );
+      },
+    );
+  });
+});

package/src/decorators/precondition.ts

@@ -0,0 +1,139 @@
+/**
+ * Precondition decorator - Check/resolve preconditions before executing child
+ */
+
+import { DecoratorNode } 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";
+
+export interface PreconditionEntry {
+  condition: TreeNode;
+  resolver?: TreeNode;
+  required: boolean;
+}
+
+/**
+ * Precondition checks preconditions before executing the main child.
+ * If preconditions fail, attempts to resolve them using resolvers.
+ * Useful for ensuring prerequisites are met before executing actions.
+ */
+export class Precondition extends DecoratorNode {
+  private preconditions: PreconditionEntry[] = [];
+  private preconditionsChecked: boolean = false;
+
+  /**
+   * Add a precondition to check before main execution
+   */
+  addPrecondition(
+    condition: TreeNode,
+    resolver?: TreeNode,
+    required: boolean = true,
+  ): void {
+    this.preconditions.push({ condition, resolver, required });
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError("Precondition requires a child");
+    }
+
+    // Only check preconditions if not already verified
+    if (!this.preconditionsChecked) {
+      // Check all preconditions
+      for (let i = 0; i < this.preconditions.length; i++) {
+        checkSignal(context.signal);
+        const precond = this.preconditions[i];
+        if (!precond) {
+          continue;
+        }
+
+        this.log(
+          `Checking precondition ${i + 1}/${this.preconditions.length}`,
+        );
+        const conditionResult = await precond.condition.tick(context);
+
+        if (conditionResult === NodeStatus.RUNNING) {
+          this.log(`Precondition ${i + 1} is running`);
+          this._status = NodeStatus.RUNNING;
+          return NodeStatus.RUNNING;
+        }
+
+        if (conditionResult === NodeStatus.FAILURE) {
+          this.log(`Precondition ${i + 1} failed`);
+
+          // Try resolver if available
+          if (precond.resolver) {
+            this.log(`Attempting to resolve precondition ${i + 1}`);
+            const resolverResult = await precond.resolver.tick(context);
+
+            if (resolverResult === NodeStatus.RUNNING) {
+              this.log(`Resolver ${i + 1} is running`);
+              this._status = NodeStatus.RUNNING;
+              return NodeStatus.RUNNING;
+            }
+
+            if (resolverResult === NodeStatus.SUCCESS) {
+              this.log(`Precondition ${i + 1} resolved successfully`);
+              // Re-check condition after resolution
+              const recheckResult = await precond.condition.tick(context);
+              if (recheckResult !== NodeStatus.SUCCESS) {
+                if (precond.required) {
+                  this.log(
+                    `Precondition ${i + 1} still not met after resolution`,
+                  );
+                  this._status = NodeStatus.FAILURE;
+                  return NodeStatus.FAILURE;
+                } else {
+                  this.log(`Optional precondition ${i + 1} skipped`);
+                }
+              }
+            } else if (precond.required) {
+              this.log(`Failed to resolve required precondition ${i + 1}`);
+              this._status = NodeStatus.FAILURE;
+              return NodeStatus.FAILURE;
+            }
+          } else if (precond.required) {
+            this.log(`Required precondition ${i + 1} not met (no resolver)`);
+            this._status = NodeStatus.FAILURE;
+            return NodeStatus.FAILURE;
+          } else {
+            this.log(`Optional precondition ${i + 1} skipped`);
+          }
+        }
+      }
+
+      // Mark preconditions as checked once all pass
+      this.preconditionsChecked = true;
+      this.log("All preconditions met - executing main child");
+    } else {
+      this.log("Preconditions already verified - continuing child execution");
+    }
+
+    // Execute child
+    checkSignal(context.signal);
+    const result = await this.child.tick(context);
+    this._status = result;
+
+    // Reset flag when child completes
+    if (result !== NodeStatus.RUNNING) {
+      this.log("Child completed - resetting precondition check flag");
+      this.preconditionsChecked = false;
+    }
+
+    return result;
+  }
+
+  protected onHalt(): void {
+    this.log("Halting - resetting precondition check flag");
+    this.preconditionsChecked = false;
+    super.onHalt();
+  }
+
+  protected onReset(): void {
+    this.log("Resetting - clearing precondition check flag");
+    this.preconditionsChecked = false;
+  }
+}

package/src/decorators/repeat.schema.ts

@@ -0,0 +1,21 @@
+/**
+ * Repeat decorator configuration schema
+ */
+
+import { z } from "zod";
+import { createNodeSchema, validations } from "../schemas/base.schema.js";
+
+/**
+ * Schema for Repeat decorator configuration
+ * Validates that numCycles is a positive integer
+ */
+export const repeatConfigurationSchema = createNodeSchema("Repeat", {
+  numCycles: validations.positiveInteger("numCycles"),
+});
+
+/**
+ * Validated Repeat configuration type
+ */
+export type ValidatedRepeatConfiguration = z.infer<
+  typeof repeatConfigurationSchema
+>;

package/src/decorators/repeat.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Tests for Repeat decorator
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { ConfigurationError } from "../errors.js";
+import { SuccessNode } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { Repeat } from "./repeat.js";
+
+describe("Repeat", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should execute child exactly N times", async () => {
+    const repeat = new Repeat({ id: "repeat1", numCycles: 3 });
+
+    let tickCount = 0;
+    class CountingNode extends SuccessNode {
+      tick(context: TemporalContext) {
+        tickCount++;
+        return super.tick(context);
+      }
+    }
+
+    repeat.setChild(new CountingNode({ id: "child" }));
+
+    // First 2 ticks return RUNNING
+    let result = await repeat.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+    expect(tickCount).toBe(1);
+
+    result = await repeat.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+    expect(tickCount).toBe(2);
+
+    // Third tick returns SUCCESS
+    result = await repeat.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(tickCount).toBe(3);
+  });
+
+  it("should fail on child failure", async () => {
+    const repeat = new Repeat({ id: "repeat1", numCycles: 5 });
+
+    let tickCount = 0;
+    class FailOnThird extends SuccessNode {
+      tick(context: TemporalContext) {
+        const self = this;
+        const superTick = super.tick.bind(this);
+        return (async () => {
+          tickCount++;
+          if (tickCount === 3) {
+            self._status = NodeStatus.FAILURE;
+            return NodeStatus.FAILURE;
+          }
+          return await superTick(context);
+        })();
+      }
+    }
+
+    repeat.setChild(new FailOnThird({ id: "child" }));
+
+    await repeat.tick(context); // Cycle 1
+    await repeat.tick(context); // Cycle 2
+    const result = await repeat.tick(context); // Cycle 3 fails
+
+    expect(result).toBe(NodeStatus.FAILURE);
+    expect(tickCount).toBe(3);
+  });
+
+  it("should reset child between cycles", async () => {
+    const repeat = new Repeat({ id: "repeat1", numCycles: 3 });
+
+    let resetCount = 0;
+    class ResetTracker extends SuccessNode {
+      reset(): void {
+        resetCount++;
+        super.reset();
+      }
+    }
+
+    repeat.setChild(new ResetTracker({ id: "child" }));
+
+    await repeat.tick(context); // Cycle 1, reset after
+    await repeat.tick(context); // Cycle 2, reset after
+    await repeat.tick(context); // Cycle 3, completes
+
+    expect(resetCount).toBe(2); // Reset after cycles 1 and 2
+  });
+
+  it("should handle RUNNING state", async () => {
+    const repeat = new Repeat({ id: "repeat1", numCycles: 2 });
+
+    let tickCount = 0;
+    class TwoTickNode extends SuccessNode {
+      tick(context: TemporalContext) {
+        const self = this;
+        const superTick = super.tick.bind(this);
+        return (async () => {
+          tickCount++;
+          if (tickCount % 2 === 1) {
+            // Odd ticks return RUNNING
+            self._status = NodeStatus.RUNNING;
+            return NodeStatus.RUNNING;
+          }
+          return await superTick(context);
+        })();
+      }
+    }
+
+    repeat.setChild(new TwoTickNode({ id: "child" }));
+
+    // Cycle 1: tick 1 (RUNNING), tick 2 (SUCCESS)
+    let result = await repeat.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+    result = await repeat.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING); // Still more cycles
+
+    // Cycle 2: tick 3 (RUNNING), tick 4 (SUCCESS)
+    result = await repeat.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+    result = await repeat.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+
+    expect(tickCount).toBe(4);
+  });
+
+  it("should reset cycle count on completion", async () => {
+    const repeat = new Repeat({ id: "repeat1", numCycles: 2 });
+
+    let firstRunTicks = 0;
+    let secondRunTicks = 0;
+    let inSecondRun = false;
+
+    class CountingNode extends SuccessNode {
+      tick(context: TemporalContext) {
+        const superTick = super.tick.bind(this);
+        return (async () => {
+          if (inSecondRun) {
+            secondRunTicks++;
+          } else {
+            firstRunTicks++;
+          }
+          return await superTick(context);
+        })();
+      }
+    }
+
+    repeat.setChild(new CountingNode({ id: "child" }));
+
+    // First run
+    await repeat.tick(context);
+    await repeat.tick(context);
+    expect(firstRunTicks).toBe(2);
+
+    // Second run
+    inSecondRun = true;
+    await repeat.tick(context);
+    await repeat.tick(context);
+    expect(secondRunTicks).toBe(2);
+  });
+
+  it("should propagate ConfigurationError if no child", async () => {
+    const repeat = new Repeat({ id: "repeat1", numCycles: 1 });
+
+    try {
+      await repeat.tick(context);
+      throw new Error("Expected tick to throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConfigurationError);
+      expect((error as ConfigurationError).message).toContain(
+        "Repeat requires a child",
+      );
+    }
+  });
+});