@kalphq/core 0.1.0

package/src/engine/primitives/math.ts

@@ -0,0 +1,173 @@
+/**
+ * Deterministic math primitive.
+ *
+ * Provides deterministic random number generation and standard math operations.
+ *
+ * @module
+ */
+
+import type { ExecutionLog } from "@/engine/execution-log";
+import type { KalpMath } from "@kalphq/sdk";
+import type { ExecutionContext } from "@/engine/types";
+
+/**
+ * Creates a math primitive that emits events to the execution log.
+ *
+ * @param log - The execution log for event emission.
+ * @param execCtx - Optional execution context for event identity.
+ * @returns A {@link KalpMath} instance.
+ */
+export function createMathPrimitive(
+  log: ExecutionLog,
+  execCtx?: ExecutionContext,
+): KalpMath {
+  const ids = {
+    executionId: execCtx?.executionId ?? "",
+    traceId: execCtx?.traceId ?? "",
+    threadId: execCtx?.threadId ?? "",
+  };
+
+  // Simple seeded random for deterministic behavior
+  let seed = execCtx?.executionId.split("").reduce((a, c) => a + c.charCodeAt(0), 0) ?? Date.now();
+
+  return {
+    /**
+     * Deterministic pseudo-random number generator.
+     * Seeded by the execution runId (ULID) for replay consistency.
+     */
+    random(): number {
+      const timestamp = Date.now();
+      seed = (seed * 9301 + 49297) % 233280;
+      const result = seed / 233280;
+      void log.emit({
+        type: "primitive.invoked",
+        name: "math.random",
+        params: undefined,
+        result,
+        ...ids,
+        timestamp,
+      });
+      return result;
+    },
+
+    /** Round down to nearest integer. */
+    floor(x: number): number {
+      const result = Math.floor(x);
+      const timestamp = Date.now();
+      void log.emit({
+        type: "primitive.invoked",
+        name: "math.floor",
+        params: x,
+        result,
+        ...ids,
+        timestamp,
+      });
+      return result;
+    },
+
+    /** Round up to nearest integer. */
+    ceil(x: number): number {
+      const result = Math.ceil(x);
+      const timestamp = Date.now();
+      void log.emit({
+        type: "primitive.invoked",
+        name: "math.ceil",
+        params: x,
+        result,
+        ...ids,
+        timestamp,
+      });
+      return result;
+    },
+
+    /** Round to nearest integer. */
+    round(x: number): number {
+      const result = Math.round(x);
+      const timestamp = Date.now();
+      void log.emit({
+        type: "primitive.invoked",
+        name: "math.round",
+        params: x,
+        result,
+        ...ids,
+        timestamp,
+      });
+      return result;
+    },
+
+    /** Return smallest of provided values. */
+    min(...values: number[]): number {
+      const result = Math.min(...values);
+      const timestamp = Date.now();
+      void log.emit({
+        type: "primitive.invoked",
+        name: "math.min",
+        params: values,
+        result,
+        ...ids,
+        timestamp,
+      });
+      return result;
+    },
+
+    /** Return largest of provided values. */
+    max(...values: number[]): number {
+      const result = Math.max(...values);
+      const timestamp = Date.now();
+      void log.emit({
+        type: "primitive.invoked",
+        name: "math.max",
+        params: values,
+        result,
+        ...ids,
+        timestamp,
+      });
+      return result;
+    },
+
+    /** Return absolute value. */
+    abs(x: number): number {
+      const result = Math.abs(x);
+      const timestamp = Date.now();
+      void log.emit({
+        type: "primitive.invoked",
+        name: "math.abs",
+        params: x,
+        result,
+        ...ids,
+        timestamp,
+      });
+      return result;
+    },
+
+    /** Return base to the power of exponent. */
+    pow(base: number, exponent: number): number {
+      const result = Math.pow(base, exponent);
+      const timestamp = Date.now();
+      void log.emit({
+        type: "primitive.invoked",
+        name: "math.pow",
+        params: { base, exponent },
+        result,
+        ...ids,
+        timestamp,
+      });
+      return result;
+    },
+
+    /** Return square root. */
+    sqrt(x: number): number {
+      const result = Math.sqrt(x);
+      const timestamp = Date.now();
+      void log.emit({
+        type: "primitive.invoked",
+        name: "math.sqrt",
+        params: x,
+        result,
+        ...ids,
+        timestamp,
+      });
+      return result;
+    },
+  };
+}

package/src/engine/primitives/mcp.ts

@@ -0,0 +1,59 @@
+/**
+ * Model Context Protocol (MCP) primitive.
+ *
+ * Provides access to MCP servers configured in the project.
+ *
+ * @module
+ */
+
+import type { ExecutionLog } from "@/engine/execution-log";
+import type { KalpMcp } from "@kalphq/sdk";
+import type { ExecutionContext } from "@/engine/types";
+
+/**
+ * Creates an MCP primitive that emits events to the execution log.
+ *
+ * @param log - The execution log for event emission.
+ * @param execCtx - Optional execution context for event identity.
+ * @returns A {@link KalpMcp} instance.
+ */
+export function createMcpPrimitive(
+  log: ExecutionLog,
+  execCtx?: ExecutionContext,
+): KalpMcp {
+  const ids = {
+    executionId: execCtx?.executionId ?? "",
+    traceId: execCtx?.traceId ?? "",
+    threadId: execCtx?.threadId ?? "",
+  };
+
+  // Return a Proxy that dynamically handles MCP server calls
+  return new Proxy({} as KalpMcp, {
+    get(_target, serverName: string) {
+      // Return a Proxy for the server's tools
+      return new Proxy(
+        {},
+        {
+          get(_target, toolName: string) {
+            // Return the tool function
+            return async (input: unknown): Promise<unknown> => {
+              const timestamp = Date.now();
+              void log.emit({
+                type: "primitive.invoked",
+                name: "mcp." + serverName + "." + toolName,
+                params: input,
+                result: undefined,
+                ...ids,
+                timestamp,
+              });
+
+              // TODO: Implement actual MCP server connection
+              // For now, return a stub response
+              return { error: "MCP not implemented in core yet" };
+            };
+          },
+        },
+      );
+    },
+  });
+}

package/src/engine/primitives/storage.ts

@@ -0,0 +1,91 @@
+/**
+ * Storage primitive — intercepted key-value state with event emission.
+ *
+ * Every read/write is logged to the execution log. The actual storage
+ * is delegated to the {@link StateStore}.
+ *
+ * @module
+ */
+
+import type { StoragePrimitive } from "@kalphq/sdk";
+import type { StateStore } from "@/adapters/interfaces";
+import type { ExecutionLog } from "@/engine/execution-log";
+import type { ExecutionContext } from "@/engine/types";
+
+/**
+ * Creates an intercepted storage primitive that emits events for every operation.
+ *
+ * @param stateStore - The state sub-store for KV operations.
+ * @param log - The execution log for event emission.
+ * @param execCtx - The current execution context (identity for events).
+ * @returns A {@link StoragePrimitive} matching the SDK's storage API.
+ */
+export function createStoragePrimitive(
+  stateStore: StateStore,
+  log: ExecutionLog,
+  execCtx?: ExecutionContext,
+): StoragePrimitive {
+  const ids = {
+    executionId: execCtx?.executionId ?? "",
+    traceId: execCtx?.traceId ?? "",
+    threadId: execCtx?.threadId ?? "",
+  };
+
+  return {
+    async get<T = unknown>(key: string): Promise<T | null> {
+      const value = (await stateStore.get(key)) as T | null;
+      await log.emit({
+        type: "state.read",
+        key,
+        value,
+        ...ids,
+        timestamp: Date.now(),
+      });
+      return value;
+    },
+
+    async put(key: string, value: unknown): Promise<void> {
+      await stateStore.set(key, value);
+      await log.emit({
+        type: "state.write",
+        key,
+        value,
+        ...ids,
+        timestamp: Date.now(),
+      });
+    },
+
+    async delete(key: string): Promise<void> {
+      await stateStore.delete(key);
+      await log.emit({
+        type: "state.write",
+        key,
+        value: undefined,
+        ...ids,
+        timestamp: Date.now(),
+      });
+    },
+
+    async increment(key: string, amount: number = 1): Promise<number> {
+      const newValue = await stateStore.increment(key, amount);
+      await log.emit({
+        type: "state.write",
+        key,
+        value: newValue,
+        ...ids,
+        timestamp: Date.now(),
+      });
+      return newValue;
+    },
+
+    async transaction<T>(
+      callback: (tx: any) => Promise<T>,
+      _options?: any,
+    ): Promise<T> {
+      // Basic transaction wrapping (without full interceptor for tx context yet)
+      return stateStore.transaction(async (tx) => {
+        return callback(tx as any);
+      });
+    },
+  };
+}

package/src/engine/reactor.ts

@@ -0,0 +1,308 @@
+/**
+ * Orchestration Reactor — the Kalp v2 event-sourced execution engine.
+ *
+ * The reactor is **infrastructure-agnostic**. It receives events, processes
+ * tasks from an internal queue, and delegates all IO to adapter interfaces.
+ * When the queue is empty, control returns to the host adapter (Durable Object,
+ * Node process, test harness, etc.) which waits for the next external event.
+ *
+ * Key invariants:
+ * - The reactor never imports Cloudflare, Node, or any platform API.
+ * - Every operation emits structured events to the {@link ExecutionLog}.
+ * - Handler execution is sandboxed via intercepted primitives.
+ * - `actions.run` is an intent + suspend, not a direct call.
+ *
+ * @module
+ */
+
+import type { IRGraph, IRNodeId } from "@kalphq/sdk";
+import type {
+  PersistenceAdapter,
+  SchedulerAdapter,
+} from "@/adapters/interfaces";
+import type {
+  ExecutionTask,
+  RuntimeEvent,
+  HandlerModule,
+} from "@/engine/types";
+import type { RuntimeProviders } from "@/engine/context-builder";
+import { ExecutionLog } from "@/engine/execution-log";
+import { buildHandlerContext } from "@/engine/context-builder";
+
+/**
+ * The Kalp v2 Orchestration Reactor.
+ *
+ * Processes external events by looking up the corresponding IR entry,
+ * executing the handler chain, and emitting structured events for every
+ * operation. The reactor is portable — it works in Durable Objects, Node,
+ * or any environment that provides the adapter interfaces.
+ */
+export class OrchestrationReactor {
+  /** The execution log (single source of truth). */
+  public readonly log: ExecutionLog;
+  /** The IR graph (structural index only). */
+  public readonly ir: IRGraph;
+
+  /** Internal task queue. */
+  private queue: ExecutionTask[] = [];
+  /** Bundled handler modules keyed by moduleRef. */
+  private bundles: Map<string, HandlerModule>;
+  /** Composite persistence adapter (state, events, idempotency, threads). */
+  private persistence: PersistenceAdapter;
+  /** Scheduler adapter (alarms). */
+  private scheduler: SchedulerAdapter;
+  /** External providers (ai, auth, memory, vault). */
+  private providers: RuntimeProviders;
+  /** Result of the last completed handler. */
+  private lastResult: unknown = undefined;
+  /** Opaque thread identifier (set by adapter via RuntimeEvent.threadId). */
+  private threadId: string = "";
+
+  /**
+   * Creates a new reactor instance.
+   *
+   * @param ir - The compiled IR graph.
+   * @param bundles - Map from moduleRef to bundled handler module.
+   * @param persistence - Persistence adapter for state and event log.
+   * @param scheduler - Scheduler adapter for deferred wake-ups.
+   * @param providers - External providers for ai, auth, memory, vault.
+   */
+  constructor(
+    ir: IRGraph,
+    bundles: Map<string, HandlerModule>,
+    persistence: PersistenceAdapter,
+    scheduler: SchedulerAdapter,
+    providers: RuntimeProviders,
+  ) {
+    this.ir = ir;
+    this.bundles = bundles;
+    this.persistence = persistence;
+    this.scheduler = scheduler;
+    this.providers = providers;
+    this.log = new ExecutionLog(persistence.events);
+  }
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // Public API (called by host adapter)
+  // ──────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Handles an external event by resolving the IR entry and processing
+   * the handler chain until the queue is empty.
+   *
+   * @param event - The external runtime event.
+   * @returns The result of the last completed handler.
+   * @throws If no entry exists for the event type.
+   */
+  async handleEvent(event: RuntimeEvent): Promise<unknown> {
+    const entryId = this.ir.entries[event.type];
+    if (!entryId) {
+      throw new Error(`No entry for event: ${event.type}`);
+    }
+
+    // Set thread identity from adapter (opaque — Core never parses it)
+    if (event.threadId) {
+      this.threadId = event.threadId;
+    }
+
+    const traceId = crypto.randomUUID();
+
+    await this.log.emit({
+      type: "node.started",
+      nodeId: entryId,
+      executionId: "",
+      traceId,
+      threadId: this.threadId,
+      timestamp: Date.now(),
+    });
+
+    this.queue.push({ nodeId: entryId, context: event.payload });
+    await this.processUntilIdle();
+
+    return this.lastResult;
+  }
+
+  /**
+   * Drains the task queue. Called internally after handleEvent and recursively
+   * after actions.run dispatches. When the queue is empty, control returns to
+   * the host adapter.
+   */
+  async processUntilIdle(): Promise<void> {
+    while (this.queue.length > 0) {
+      const task = this.queue.shift()!;
+      await this.processTask(task);
+    }
+  }
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // Internal task processing
+  // ──────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Processes a single task from the queue.
+   *
+   * - **Entry nodes**: traverse sequential edges to find the handler.
+   * - **Handler nodes**: build context, execute handler, emit events.
+   */
+  private async processTask(task: ExecutionTask): Promise<void> {
+    const node = this.ir.nodes[task.nodeId];
+    if (!node) {
+      await this.log.emit({
+        type: "error",
+        nodeId: task.nodeId,
+        error: `Node "${task.nodeId}" not found in IR.`,
+        executionId: "",
+        traceId: "",
+        threadId: this.threadId,
+        timestamp: Date.now(),
+      });
+      return;
+    }
+
+    switch (node.kind) {
+      case "entry": {
+        // Entry nodes are pass-through — enqueue successors
+        this.enqueueSuccessors(task.nodeId, task.context);
+        break;
+      }
+
+      case "handler": {
+        const executionId = crypto.randomUUID();
+
+        await this.log.emit({
+          type: "node.started",
+          nodeId: node.id,
+          executionId,
+          traceId: "",
+          threadId: this.threadId,
+          timestamp: Date.now(),
+        });
+
+        const handlerModule = this.bundles.get(node.moduleRef);
+        if (!handlerModule) {
+          await this.log.emit({
+            type: "error",
+            nodeId: node.id,
+            error: `Handler module "${node.moduleRef}" not found in bundles.`,
+            executionId,
+            traceId: "",
+            threadId: this.threadId,
+            timestamp: Date.now(),
+          });
+          return;
+        }
+
+        // Build intercepted context with dispatch callback
+        const dispatch = this.createDispatch();
+        const ctx = buildHandlerContext(
+          this.log,
+          this.persistence.state,
+          this.scheduler,
+          dispatch,
+          this.providers,
+          { 
+            executionId, 
+            traceId: "", 
+            threadId: this.threadId,
+            untrackedIOCount: 0,
+            untrackedIOByType: { network: 0, timer: 0, fs: 0, unknown: 0 },
+            hasUntrustedPlugins: false
+          },
+        );
+
+        // Execute handler in sandboxed context
+        try {
+          const result = await handlerModule.default(ctx, task.context);
+
+          await this.log.emit({
+            type: "node.completed",
+            nodeId: node.id,
+            result,
+            executionId,
+            traceId: "",
+            threadId: this.threadId,
+            timestamp: Date.now(),
+          });
+
+          this.lastResult = result;
+
+          // If this task was dispatched by actions.run, resolve the caller's promise
+          if (task.resolve) {
+            task.resolve(result);
+          }
+
+          // Continue to sequential successors
+          this.enqueueSuccessors(task.nodeId, {
+            ...(task.context as object),
+            result,
+          });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          await this.log.emit({
+            type: "error",
+            nodeId: node.id,
+            error: message,
+            executionId,
+            traceId: "",
+            threadId: this.threadId,
+            timestamp: Date.now(),
+          });
+
+          // Re-throw to let the host adapter handle it
+          throw err;
+        }
+        break;
+      }
+    }
+  }
+
+  /**
+   * Enqueues all successor nodes connected by outgoing edges from the given node.
+   *
+   * @param nodeId - The source node ID.
+   * @param context - The context to pass to successor tasks.
+   */
+  private enqueueSuccessors(nodeId: IRNodeId, context: unknown): void {
+    const outEdges = this.ir.edges.filter((e) => e.from === nodeId);
+    for (const edge of outEdges) {
+      this.queue.push({ nodeId: edge.to, context });
+    }
+  }
+
+  /**
+   * Creates a dispatch function for actions.run.
+   *
+   * When a handler calls `actions.run(step, input)`, this function:
+   * 1. Looks up the handler node by moduleRef in the IR.
+   * 2. Creates a task with a resolve callback.
+   * 3. Returns a Promise that resolves when the task completes.
+   */
+  private createDispatch(): (
+    moduleRef: string,
+    input: unknown,
+  ) => Promise<unknown> {
+    return (moduleRef: string, input: unknown): Promise<unknown> => {
+      // O(1) lookup via handlerIndex (built by compiler)
+      const handlerNodeId = this.ir.handlerIndex[moduleRef] as
+        | IRNodeId
+        | undefined;
+
+      if (!handlerNodeId) {
+        return Promise.reject(
+          new Error(
+            `Cannot dispatch: handler "${moduleRef}" not found in IR. ` +
+              `Ensure it is statically imported at the top level.`,
+          ),
+        );
+      }
+
+      return new Promise<unknown>((resolve) => {
+        this.queue.push({
+          nodeId: handlerNodeId,
+          context: input,
+          resolve,
+        });
+      });
+    };
+  }
+}