@q1k-oss/btree-workflows 0.0.1

package/src/decorators/delay.test.ts

@@ -0,0 +1,261 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { MockAction } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { Delay } from "./delay.js";
+
+describe("Delay", () => {
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    context = {
+      blackboard: new ScopedBlackboard(),
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should throw error if delayMs is negative", () => {
+    expect(() => new Delay({ id: "test", delayMs: -100 })).toThrow(
+      "test: Delay must be non-negative (got -100)",
+    );
+  });
+
+  it("should throw ConfigurationError if no child is set", async () => {
+    const delay = new Delay({ id: "test-delay", delayMs: 100 });
+    await expect(delay.tick(context)).rejects.toThrow("test-delay: Decorator must have a child");
+  });
+
+  it("should execute child immediately when delayMs is 0", async () => {
+    const delay = new Delay({ id: "test-delay", delayMs: 0 });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    delay.setChild(child);
+
+    const status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+    expect(child.status()).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should delay child execution", async () => {
+    const delayMs = 50;
+    const delay = new Delay({ id: "test-delay", delayMs });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    delay.setChild(child);
+
+    const startTime = Date.now();
+
+    // First tick - should be delaying
+    let status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+    expect(child.status()).toBe(NodeStatus.IDLE); // Child not executed yet
+
+    // Tick while still delaying
+    status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+    expect(Date.now() - startTime).toBeLessThan(delayMs);
+
+    // Wait for delay to complete
+    await new Promise((resolve) => setTimeout(resolve, delayMs + 10));
+
+    // Next tick should execute child
+    status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+    expect(child.status()).toBe(NodeStatus.SUCCESS);
+    expect(Date.now() - startTime).toBeGreaterThanOrEqual(delayMs);
+  });
+
+  it("should pass through child status after delay", async () => {
+    const delay = new Delay({ id: "test-delay", delayMs: 30 });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.FAILURE,
+    });
+
+    delay.setChild(child);
+
+    // Wait through delay
+    await delay.tick(context);
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    const status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.FAILURE);
+    expect(delay.status()).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should handle RUNNING child after delay", async () => {
+    const delay = new Delay({ id: "test-delay", delayMs: 30 });
+    let tickCount = 0;
+    const child = new MockAction({ id: "child" });
+    child.tick = async (_ctx) => {
+      tickCount++;
+      if (tickCount < 3) {
+        (child as any)._status = NodeStatus.RUNNING;
+        return NodeStatus.RUNNING;
+      }
+      (child as any)._status = NodeStatus.SUCCESS;
+      return NodeStatus.SUCCESS;
+    };
+
+    delay.setChild(child);
+
+    // Wait through delay
+    await delay.tick(context);
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    // Child starts executing
+    let status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+    // Child has been ticked (verified by child status check)
+
+    // Child still running
+    status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+
+    // Child completes
+    status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should reset delay state on halt", async () => {
+    const delay = new Delay({ id: "test-delay", delayMs: 100 });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    delay.setChild(child);
+
+    // Start delay
+    await delay.tick(context);
+    expect((delay as any).delayStartTime).not.toBeNull();
+
+    // Halt
+    delay.halt();
+
+    expect(delay.status()).toBe(NodeStatus.IDLE);
+    expect((delay as any).delayStartTime).toBeNull();
+  });
+
+  it("should reset delay state on reset", async () => {
+    const delay = new Delay({ id: "test-delay", delayMs: 30 });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    delay.setChild(child);
+
+    // Complete execution
+    await delay.tick(context);
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    await delay.tick(context);
+
+    // Child has been ticked (verified by child status check)
+
+    // Reset
+    delay.reset();
+
+    expect(delay.status()).toBe(NodeStatus.IDLE);
+    expect((delay as any).delayStartTime).toBeNull();
+  });
+
+  it("should track remaining delay time correctly", async () => {
+    const delayMs = 100;
+    const delay = new Delay({ id: "test-delay", delayMs });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    delay.setChild(child);
+
+    // Start delay
+    await delay.tick(context);
+
+    // Check multiple times during delay
+    for (let i = 0; i < 3; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      const status = await delay.tick(context);
+      expect(status).toBe(NodeStatus.RUNNING);
+
+      // Verify delay is being tracked (can check logs)
+      const delayStartTime = (delay as any).delayStartTime;
+      if (!delayStartTime) {
+        throw new Error("delayStartTime not found");
+      }
+      const elapsed = Date.now() - delayStartTime;
+      expect(elapsed).toBeLessThan(delayMs);
+    }
+
+    // Wait for completion
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    const finalStatus = await delay.tick(context);
+    expect(finalStatus).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should only start child execution once", async () => {
+    const delay = new Delay({ id: "test-delay", delayMs: 30 });
+    let tickCount = 0;
+
+    const child = new MockAction({ id: "child" });
+    const originalTick = child.tick.bind(child);
+    child.tick = (ctx) => {
+      tickCount++;
+      return originalTick(ctx);
+    };
+
+    delay.setChild(child);
+
+    // Wait through delay
+    await delay.tick(context);
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    // First tick after delay
+    await delay.tick(context);
+    expect(tickCount).toBe(1);
+    // Child has been ticked (verified by child status check)
+
+    // Subsequent ticks start new delay cycles (return RUNNING without ticking child)
+    await delay.tick(context);
+    await delay.tick(context);
+    expect(tickCount).toBe(1); // Child only ticked once (subsequent ticks are delaying)
+  });
+
+  it("should handle multiple executions correctly", async () => {
+    const delay = new Delay({ id: "test-delay", delayMs: 30 });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    delay.setChild(child);
+
+    // First execution
+    await delay.tick(context);
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    let status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+
+    // Reset for second execution
+    delay.reset();
+    child.reset();
+
+    // Second execution should also delay
+    const startTime = Date.now();
+    status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    status = await delay.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+    expect(Date.now() - startTime).toBeGreaterThanOrEqual(30);
+  });
+});

package/src/decorators/delay.ts

@@ -0,0 +1,140 @@
+/**
+ * Delay decorator node
+ * Waits for a specified duration before executing the child
+ *
+ * In Temporal workflows: Uses sleep() for deterministic delays
+ * In standalone mode: Uses Date.now() polling for multi-tick behavior
+ */
+
+import { sleep } from "@temporalio/workflow";
+import { DecoratorNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  NodeStatus,
+} from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+export interface DelayConfiguration extends NodeConfiguration {
+  /**
+   * Delay duration in milliseconds
+   */
+  delayMs: number;
+}
+
+export class Delay extends DecoratorNode {
+  private delayMs: number;
+  private delayStartTime: number | null = null;
+  private useTemporalAPI: boolean | null = null;  // Cached detection result
+
+  constructor(config: DelayConfiguration) {
+    super(config);
+    this.delayMs = config.delayMs;
+
+    if (this.delayMs < 0) {
+      throw new ConfigurationError(
+        `${this.name}: Delay must be non-negative (got ${this.delayMs})`,
+      );
+    }
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError(`${this.name}: Decorator must have a child`);
+    }
+
+    // If delay is 0, just execute the child immediately
+    if (this.delayMs === 0) {
+      return await this.child.tick(context);
+    }
+
+    // Try Temporal API on first execution only
+    if (this.useTemporalAPI === null) {
+      try {
+        this.log(`Starting delay of ${this.delayMs}ms`);
+        await sleep(this.delayMs);
+
+        // Success - we're in a Temporal workflow
+        this.useTemporalAPI = true;
+        this.log("Delay completed, executing child");
+
+        checkSignal(context.signal);
+        const childStatus = await this.child.tick(context);
+        this._status = childStatus;
+        return childStatus;
+
+      } catch (err) {
+        // Not in Temporal workflow - use standalone polling
+        this.useTemporalAPI = false;
+        // Fall through to polling implementation below
+      }
+    }
+
+    // Use Temporal API (we know we're in a workflow)
+    if (this.useTemporalAPI === true) {
+      this.log(`Starting delay of ${this.delayMs}ms`);
+      await sleep(this.delayMs);
+      this.log("Delay completed, executing child");
+
+      checkSignal(context.signal);
+      const childStatus = await this.child.tick(context);
+      this._status = childStatus;
+      return childStatus;
+    }
+
+    // Standalone polling implementation (multi-tick)
+    // If child is already running from a previous tick, execute it immediately
+    if (this.child.status() === NodeStatus.RUNNING) {
+      checkSignal(context.signal);
+      const childStatus = await this.child.tick(context);
+
+      if (childStatus !== NodeStatus.RUNNING) {
+        // Child completed - reset delay timer for next cycle
+        this.delayStartTime = null;
+      }
+
+      this._status = childStatus;
+      return childStatus;
+    }
+
+    // Start delay if not started
+    if (this.delayStartTime === null) {
+      this.delayStartTime = Date.now();
+      this.log(`Starting delay of ${this.delayMs}ms`);
+    }
+
+    const elapsed = Date.now() - this.delayStartTime;
+
+    if (elapsed < this.delayMs) {
+      // Still delaying
+      this._status = NodeStatus.RUNNING;
+      return NodeStatus.RUNNING;
+    }
+
+    // Delay completed - execute child
+    this.log("Delay completed, executing child");
+
+    checkSignal(context.signal);
+    const childStatus = await this.child.tick(context);
+
+    if (childStatus !== NodeStatus.RUNNING) {
+      // Child completed - reset delay timer for next cycle
+      this.delayStartTime = null;
+    }
+
+    this._status = childStatus;
+    return childStatus;
+  }
+
+  protected onHalt(): void {
+    this.delayStartTime = null;
+  }
+
+  protected onReset(): void {
+    this.delayStartTime = null;
+    this.useTemporalAPI = null;  // Re-detect on next execution
+  }
+}

package/src/decorators/force-result.schema.ts

@@ -0,0 +1,32 @@
+/**
+ * ForceSuccess and ForceFailure decorator configuration schemas
+ */
+
+import { z } from "zod";
+import { nodeConfigurationSchema } from "../schemas/base.schema.js";
+
+/**
+ * Schema for ForceSuccess decorator configuration
+ * Uses base schema only (no additional properties)
+ */
+export const forceSuccessConfigurationSchema = nodeConfigurationSchema;
+
+/**
+ * Schema for ForceFailure decorator configuration
+ * Uses base schema only (no additional properties)
+ */
+export const forceFailureConfigurationSchema = nodeConfigurationSchema;
+
+/**
+ * Validated ForceSuccess configuration type
+ */
+export type ValidatedForceSuccessConfiguration = z.infer<
+  typeof forceSuccessConfigurationSchema
+>;
+
+/**
+ * Validated ForceFailure configuration type
+ */
+export type ValidatedForceFailureConfiguration = z.infer<
+  typeof forceFailureConfigurationSchema
+>;

package/src/decorators/force-result.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Tests for ForceSuccess and ForceFailure decorators
+ */
+
+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 { ForceFailure, ForceSuccess } from "./force-result.js";
+
+describe("ForceSuccess", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should return SUCCESS when child succeeds", async () => {
+    const force = new ForceSuccess({ id: "force1" });
+    force.setChild(new SuccessNode({ id: "child" }));
+
+    const result = await force.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should return SUCCESS when child fails", async () => {
+    const force = new ForceSuccess({ id: "force1" });
+    force.setChild(new FailureNode({ id: "child" }));
+
+    const result = await force.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should return RUNNING when child is running", async () => {
+    const force = new ForceSuccess({ id: "force1" });
+    force.setChild(new RunningNode({ id: "child" }));
+
+    const result = await force.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+    expect(force.status()).toBe(NodeStatus.RUNNING);
+  });
+
+  it("should still tick child for side effects", async () => {
+    const force = new ForceSuccess({ id: "force1" });
+
+    let childTicked = false;
+    class SideEffectNode extends FailureNode {
+      tick(context: TemporalContext) {
+        childTicked = true;
+        return super.tick(context);
+      }
+    }
+
+    force.setChild(new SideEffectNode({ id: "child" }));
+
+    await force.tick(context);
+    expect(childTicked).toBe(true);
+  });
+
+  it("should throw ConfigurationError if no child", async () => {
+    const force = new ForceSuccess({ id: "force1" });
+
+    await expect(force.tick(context)).rejects.toThrow("ForceSuccess requires a child");
+  });
+});
+
+describe("ForceFailure", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should return FAILURE when child succeeds", async () => {
+    const force = new ForceFailure({ id: "force1" });
+    force.setChild(new SuccessNode({ id: "child" }));
+
+    const result = await force.tick(context);
+    expect(result).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should return FAILURE when child fails", async () => {
+    const force = new ForceFailure({ id: "force1" });
+    force.setChild(new FailureNode({ id: "child" }));
+
+    const result = await force.tick(context);
+    expect(result).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should return RUNNING when child is running", async () => {
+    const force = new ForceFailure({ id: "force1" });
+    force.setChild(new RunningNode({ id: "child" }));
+
+    const result = await force.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+    expect(force.status()).toBe(NodeStatus.RUNNING);
+  });
+
+  it("should still tick child for side effects", async () => {
+    const force = new ForceFailure({ id: "force1" });
+
+    let childTicked = false;
+    class SideEffectNode extends SuccessNode {
+      tick(context: TemporalContext) {
+        childTicked = true;
+        return super.tick(context);
+      }
+    }
+
+    force.setChild(new SideEffectNode({ id: "child" }));
+
+    await force.tick(context);
+    expect(childTicked).toBe(true);
+  });
+
+  it("should throw ConfigurationError if no child", async () => {
+    const force = new ForceFailure({ id: "force1" });
+
+    await expect(force.tick(context)).rejects.toThrow("ForceFailure requires a child");
+  });
+});

package/src/decorators/force-result.ts

@@ -0,0 +1,63 @@
+/**
+ * ForceSuccess and ForceFailure decorators
+ * Always return specific result regardless of child
+ */
+
+import { DecoratorNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+/**
+ * ForceSuccess always returns SUCCESS regardless of child result.
+ * Useful for ensuring a branch always succeeds.
+ */
+export class ForceSuccess extends DecoratorNode {
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError("ForceSuccess requires a child");
+    }
+
+    // Tick child and check status
+    const childStatus = await this.child.tick(context);
+
+    // Propagate RUNNING status - only force result when child completes
+    if (childStatus === NodeStatus.RUNNING) {
+      this._status = NodeStatus.RUNNING;
+      return NodeStatus.RUNNING;
+    }
+
+    // Force SUCCESS regardless of child result (SUCCESS or FAILURE)
+    this._status = NodeStatus.SUCCESS;
+    return NodeStatus.SUCCESS;
+  }
+}
+
+/**
+ * ForceFailure always returns FAILURE regardless of child result.
+ * Useful for negation or testing.
+ */
+export class ForceFailure extends DecoratorNode {
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError("ForceFailure requires a child");
+    }
+
+    // Tick child and check status
+    const childStatus = await this.child.tick(context);
+
+    // Propagate RUNNING status - only force result when child completes
+    if (childStatus === NodeStatus.RUNNING) {
+      this._status = NodeStatus.RUNNING;
+      return NodeStatus.RUNNING;
+    }
+
+    // Force FAILURE regardless of child result (SUCCESS or FAILURE)
+    this._status = NodeStatus.FAILURE;
+    return NodeStatus.FAILURE;
+  }
+}

package/src/decorators/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Export all decorator nodes
+ */
+
+export { Delay } from "./delay.js";
+export { ForceFailure, ForceSuccess } from "./force-result.js";
+export { Invert } from "./invert.js";
+export { KeepRunningUntilFailure } from "./keep-running.js";
+export { Precondition } from "./precondition.js";
+export { Repeat } from "./repeat.js";
+export { RunOnce } from "./run-once.js";
+export { SoftAssert } from "./soft-assert.js";
+export { Timeout } from "./timeout.js";

package/src/decorators/invert.schema.ts

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