@vibe-lang/runtime 0.2.5

package/src/runtime/async/dependencies.ts

@@ -0,0 +1,276 @@
+/**
+ * Dependency detection for async operations.
+ * Scans expressions for variable references and builds execution waves.
+ */
+
+import type * as AST from '../../ast';
+import type { AsyncOperation, AsyncWave, ContextEntry } from '../types';
+
+/**
+ * Extracts all variable names referenced in an expression.
+ * Used to detect dependencies between async operations.
+ */
+export function getReferencedVariables(expr: AST.Expression): string[] {
+  const variables: string[] = [];
+
+  function visit(node: AST.Expression): void {
+    switch (node.type) {
+      case 'Identifier':
+        variables.push(node.name);
+        break;
+
+      case 'BinaryExpression':
+        visit(node.left);
+        visit(node.right);
+        break;
+
+      case 'UnaryExpression':
+        visit(node.operand);
+        break;
+
+      case 'CallExpression':
+        visit(node.callee);
+        node.arguments.forEach(visit);
+        break;
+
+      case 'MemberExpression':
+        visit(node.object);
+        break;
+
+      case 'IndexExpression':
+        visit(node.object);
+        visit(node.index);
+        break;
+
+      case 'SliceExpression':
+        visit(node.object);
+        if (node.start) visit(node.start);
+        if (node.end) visit(node.end);
+        break;
+
+      case 'ArrayLiteral':
+        node.elements.forEach(visit);
+        break;
+
+      case 'ObjectLiteral':
+        node.properties.forEach((prop) => visit(prop.value));
+        break;
+
+      case 'RangeExpression':
+        visit(node.start);
+        visit(node.end);
+        break;
+
+      case 'AssignmentExpression':
+        visit(node.value);
+        break;
+
+      case 'VibeExpression':
+        visit(node.prompt);
+        if (node.model) visit(node.model);
+        break;
+
+      case 'TsBlock':
+        // TsBlock params are variable references
+        variables.push(...node.params);
+        break;
+
+      case 'TemplateLiteral':
+        // Extract variables from template interpolations like {varName}
+        const matches = node.value.matchAll(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g);
+        for (const match of matches) {
+          variables.push(match[1]);
+        }
+        break;
+
+      // Literals don't reference variables
+      case 'StringLiteral':
+      case 'NumberLiteral':
+      case 'BooleanLiteral':
+      case 'NullLiteral':
+        break;
+    }
+  }
+
+  visit(expr);
+  return [...new Set(variables)]; // Remove duplicates
+}
+
+/**
+ * Detects which async operations the given expression depends on.
+ * Returns the IDs of async operations that must complete before this expression can be evaluated.
+ */
+export function detectAsyncDependencies(
+  expr: AST.Expression,
+  asyncVarToOpId: Map<string, string>,
+  pendingAsyncIds: Set<string>
+): string[] {
+  const referencedVars = getReferencedVariables(expr);
+  const dependencies: string[] = [];
+
+  for (const varName of referencedVars) {
+    const opId = asyncVarToOpId.get(varName);
+    if (opId && pendingAsyncIds.has(opId)) {
+      dependencies.push(opId);
+    }
+  }
+
+  return dependencies;
+}
+
+/**
+ * Builds execution waves from a list of async operations.
+ * Operations with no pending dependencies go in the same wave.
+ * Uses topological sort to determine execution order.
+ */
+export function buildExecutionWaves(
+  operations: AsyncOperation[],
+  contextSnapshot: ContextEntry[]
+): AsyncWave[] {
+  const waves: AsyncWave[] = [];
+  const remaining = new Set(operations.map((op) => op.id));
+  const completed = new Set<string>();
+
+  // Map from operation ID to operation
+  const opById = new Map(operations.map((op) => [op.id, op]));
+
+  // Map from variable name to operation ID
+  const varToOp = new Map<string, string>();
+  for (const op of operations) {
+    if (op.variableName) {
+      varToOp.set(op.variableName, op.id);
+    }
+  }
+
+  let waveId = 0;
+  while (remaining.size > 0) {
+    const waveOps: string[] = [];
+
+    for (const opId of remaining) {
+      const op = opById.get(opId)!;
+
+      // Check if all dependencies are completed (or not in our operation set)
+      const depsReady = op.dependencies.every((depVar) => {
+        const depOpId = varToOp.get(depVar);
+        return !depOpId || completed.has(depOpId) || !remaining.has(depOpId);
+      });
+
+      if (depsReady) {
+        waveOps.push(opId);
+      }
+    }
+
+    if (waveOps.length === 0 && remaining.size > 0) {
+      // Circular dependency detected - should be caught at semantic analysis
+      throw new Error('Circular dependency detected in async operations');
+    }
+
+    // Create the wave
+    const wave: AsyncWave = {
+      id: waveId,
+      operationIds: waveOps,
+      contextSnapshot: [...contextSnapshot], // Copy context at wave creation
+      startTime: 0, // Will be set when wave executes
+    };
+    waves.push(wave);
+
+    // Mark operations as completed for next iteration
+    for (const opId of waveOps) {
+      remaining.delete(opId);
+      completed.add(opId);
+    }
+
+    waveId++;
+  }
+
+  return waves;
+}
+
+/**
+ * Gets variable names that an instruction references.
+ * Used to check if an instruction needs to await pending async operations.
+ */
+export function getInstructionDependencies(
+  instruction: { op: string; [key: string]: unknown },
+  asyncVarToOpId: Map<string, string>,
+  pendingAsyncIds: Set<string>
+): string[] {
+  const dependencies: string[] = [];
+
+  // Check expression-based instructions
+  if ('expr' in instruction && instruction.expr) {
+    const expr = instruction.expr as AST.Expression;
+    const deps = detectAsyncDependencies(expr, asyncVarToOpId, pendingAsyncIds);
+    dependencies.push(...deps);
+  }
+
+  // Check statement-based instructions
+  if ('stmt' in instruction && instruction.stmt) {
+    const stmt = instruction.stmt as AST.Statement;
+    const stmtDeps = getStatementDependencies(stmt, asyncVarToOpId, pendingAsyncIds);
+    dependencies.push(...stmtDeps);
+  }
+
+  return [...new Set(dependencies)];
+}
+
+/**
+ * Gets async operation IDs that a statement depends on.
+ */
+function getStatementDependencies(
+  stmt: AST.Statement,
+  asyncVarToOpId: Map<string, string>,
+  pendingAsyncIds: Set<string>
+): string[] {
+  const dependencies: string[] = [];
+
+  switch (stmt.type) {
+    case 'LetDeclaration':
+    case 'ConstDeclaration':
+      if (stmt.initializer) {
+        dependencies.push(...detectAsyncDependencies(stmt.initializer, asyncVarToOpId, pendingAsyncIds));
+      }
+      break;
+
+    case 'DestructuringDeclaration':
+      dependencies.push(...detectAsyncDependencies(stmt.initializer, asyncVarToOpId, pendingAsyncIds));
+      break;
+
+    case 'ExpressionStatement':
+      dependencies.push(...detectAsyncDependencies(stmt.expression, asyncVarToOpId, pendingAsyncIds));
+      break;
+
+    case 'IfStatement':
+      dependencies.push(...detectAsyncDependencies(stmt.condition, asyncVarToOpId, pendingAsyncIds));
+      break;
+
+    case 'WhileStatement':
+      dependencies.push(...detectAsyncDependencies(stmt.condition, asyncVarToOpId, pendingAsyncIds));
+      break;
+
+    case 'ForInStatement':
+      dependencies.push(...detectAsyncDependencies(stmt.iterable, asyncVarToOpId, pendingAsyncIds));
+      break;
+
+    case 'ReturnStatement':
+      if (stmt.value) {
+        dependencies.push(...detectAsyncDependencies(stmt.value, asyncVarToOpId, pendingAsyncIds));
+      }
+      break;
+
+    case 'AsyncStatement':
+      dependencies.push(...detectAsyncDependencies(stmt.expression, asyncVarToOpId, pendingAsyncIds));
+      break;
+
+    // Declarations that don't have expression dependencies
+    case 'ImportDeclaration':
+    case 'ExportDeclaration':
+    case 'ModelDeclaration':
+    case 'FunctionDeclaration':
+    case 'ToolDeclaration':
+    case 'BlockStatement':
+      break;
+  }
+
+  return dependencies;
+}

package/src/runtime/async/executor.ts

@@ -0,0 +1,293 @@
+/**
+ * Async execution engine.
+ * Executes async operations in waves with throttling.
+ */
+
+import type { RuntimeState, AsyncOperation, AsyncWave, VibeValue, VibeError, ContextEntry } from '../types';
+import { createVibeValue, createVibeError } from '../types';
+
+/**
+ * Simple semaphore for limiting concurrent operations.
+ */
+class Semaphore {
+  private permits: number;
+  private waiting: Array<() => void> = [];
+
+  constructor(permits: number) {
+    this.permits = permits;
+  }
+
+  async acquire(): Promise<void> {
+    if (this.permits > 0) {
+      this.permits--;
+      return;
+    }
+
+    return new Promise((resolve) => {
+      this.waiting.push(resolve);
+    });
+  }
+
+  release(): void {
+    const next = this.waiting.shift();
+    if (next) {
+      next();
+    } else {
+      this.permits++;
+    }
+  }
+}
+
+/**
+ * Result of executing an async operation.
+ */
+export interface AsyncExecutionResult {
+  operationId: string;
+  result?: VibeValue;
+  error?: VibeError;
+}
+
+/**
+ * Executor function type for running a single async operation.
+ * This will be provided by the runtime to handle different operation types.
+ */
+export type AsyncOperationExecutor = (
+  operation: AsyncOperation,
+  contextSnapshot: ContextEntry[]
+) => Promise<VibeValue>;
+
+/**
+ * Executes all operations in a wave with parallelism throttling.
+ * Returns the results of all operations.
+ */
+export async function executeWave(
+  wave: AsyncWave,
+  operations: Map<string, AsyncOperation>,
+  executor: AsyncOperationExecutor,
+  maxParallel: number
+): Promise<AsyncExecutionResult[]> {
+  const semaphore = new Semaphore(maxParallel);
+  const startTime = Date.now();
+
+  // Update wave start time
+  wave.startTime = startTime;
+
+  const results = await Promise.all(
+    wave.operationIds.map(async (opId) => {
+      const operation = operations.get(opId);
+      if (!operation) {
+        return {
+          operationId: opId,
+          error: {
+            message: `Operation ${opId} not found`,
+            type: 'InternalError',
+            location: null,
+          },
+        };
+      }
+
+      await semaphore.acquire();
+
+      try {
+        // Update operation status
+        operation.status = 'running';
+        operation.startTime = Date.now();
+
+        // Execute the operation
+        const result = await executor(operation, wave.contextSnapshot);
+
+        // Update operation with result
+        operation.status = 'completed';
+        operation.endTime = Date.now();
+        operation.result = result;
+
+        return { operationId: opId, result };
+      } catch (err) {
+        // Handle exceptions (these crash the program per design)
+        const error: VibeError = {
+          message: err instanceof Error ? err.message : String(err),
+          type: err instanceof Error ? err.constructor.name : 'Error',
+          location: null,
+          stack: err instanceof Error ? err.stack : undefined,
+        };
+
+        operation.status = 'failed';
+        operation.endTime = Date.now();
+        operation.error = error;
+
+        return { operationId: opId, error };
+      } finally {
+        semaphore.release();
+      }
+    })
+  );
+
+  wave.endTime = Date.now();
+  return results;
+}
+
+/**
+ * Awaits specific async operations by their IDs.
+ * Returns when all specified operations are complete.
+ */
+export async function awaitOperations(
+  operationIds: string[],
+  operations: Map<string, AsyncOperation>
+): Promise<Map<string, VibeValue>> {
+  const results = new Map<string, VibeValue>();
+
+  for (const opId of operationIds) {
+    const operation = operations.get(opId);
+    if (!operation) {
+      results.set(opId, createVibeError(`Operation ${opId} not found`));
+      continue;
+    }
+
+    // If operation has a promise, wait for it
+    if (operation.promise) {
+      try {
+        const result = await operation.promise;
+        results.set(opId, result);
+      } catch (err) {
+        results.set(opId, createVibeError(err instanceof Error ? err : String(err)));
+      }
+    } else if (operation.result) {
+      // Already completed
+      results.set(opId, operation.result);
+    } else if (operation.error) {
+      // Already failed
+      results.set(opId, createVibeError(operation.error.message));
+    } else {
+      // Operation not started yet - this shouldn't happen
+      results.set(opId, createVibeError(`Operation ${opId} has not started`));
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Awaits all pending async operations in the state.
+ * Used at block boundaries and before sync instructions that need async results.
+ */
+export async function awaitAllPending(
+  state: RuntimeState
+): Promise<Map<string, VibeValue>> {
+  const pendingIds = Array.from(state.pendingAsyncIds);
+  return awaitOperations(pendingIds, state.asyncOperations);
+}
+
+/**
+ * Awaits async operations that a variable depends on.
+ * Used for implicit await when a variable's value is needed.
+ */
+export async function awaitVariable(
+  variableName: string,
+  state: RuntimeState
+): Promise<VibeValue | null> {
+  const opId = state.asyncVarToOpId.get(variableName);
+  if (!opId) {
+    return null; // Not an async variable
+  }
+
+  if (!state.pendingAsyncIds.has(opId)) {
+    // Already completed
+    const operation = state.asyncOperations.get(opId);
+    return operation?.result ?? null;
+  }
+
+  const results = await awaitOperations([opId], state.asyncOperations);
+  return results.get(opId) ?? null;
+}
+
+/**
+ * Generates a unique async operation ID.
+ * Note: Caller is responsible for incrementing state.nextAsyncId.
+ */
+export function generateAsyncId(state: RuntimeState): string {
+  return `async-${String(state.nextAsyncId).padStart(6, '0')}`;
+}
+
+/**
+ * Registers a new async operation in the state.
+ */
+export function registerAsyncOperation(
+  state: RuntimeState,
+  operation: Omit<AsyncOperation, 'id' | 'waveId'>
+): AsyncOperation {
+  const id = generateAsyncId(state);
+  const fullOperation: AsyncOperation = {
+    ...operation,
+    id,
+    waveId: state.currentWaveId,
+  };
+
+  state.asyncOperations.set(id, fullOperation);
+  state.pendingAsyncIds.add(id);
+
+  if (operation.variableName) {
+    state.asyncVarToOpId.set(operation.variableName, id);
+  }
+
+  return fullOperation;
+}
+
+/**
+ * Marks an async operation as complete and removes from pending.
+ */
+export function completeAsyncOperation(
+  state: RuntimeState,
+  operationId: string,
+  result: VibeValue
+): void {
+  const operation = state.asyncOperations.get(operationId);
+  if (operation) {
+    operation.status = 'completed';
+    operation.endTime = Date.now();
+    operation.result = result;
+  }
+  state.pendingAsyncIds.delete(operationId);
+}
+
+/**
+ * Marks an async operation as failed and removes from pending.
+ */
+export function failAsyncOperation(
+  state: RuntimeState,
+  operationId: string,
+  error: VibeError
+): void {
+  const operation = state.asyncOperations.get(operationId);
+  if (operation) {
+    operation.status = 'failed';
+    operation.endTime = Date.now();
+    operation.error = error;
+  }
+  state.pendingAsyncIds.delete(operationId);
+}
+
+/**
+ * Checks if any async operations are still pending.
+ */
+export function hasPendingAsync(state: RuntimeState): boolean {
+  return state.pendingAsyncIds.size > 0;
+}
+
+/**
+ * Gets the IDs of pending async operations that a list of variables depend on.
+ */
+export function getPendingDependencies(
+  variableNames: string[],
+  state: RuntimeState
+): string[] {
+  const deps: string[] = [];
+
+  for (const varName of variableNames) {
+    const opId = state.asyncVarToOpId.get(varName);
+    if (opId && state.pendingAsyncIds.has(opId)) {
+      deps.push(opId);
+    }
+  }
+
+  return deps;
+}

package/src/runtime/async/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Async execution module for parallel operations.
+ *
+ * This module provides:
+ * - Dependency detection for async operations
+ * - Wave-based execution with throttling
+ * - Async operation scheduling helpers
+ * - Utilities for managing async operation state
+ */
+
+// Dependency detection
+export {
+  getReferencedVariables,
+  detectAsyncDependencies,
+  buildExecutionWaves,
+  getInstructionDependencies,
+} from './dependencies';
+
+// Execution engine
+export {
+  executeWave,
+  awaitOperations,
+  awaitAllPending,
+  awaitVariable,
+  generateAsyncId,
+  registerAsyncOperation,
+  completeAsyncOperation,
+  failAsyncOperation,
+  hasPendingAsync,
+  getPendingDependencies,
+} from './executor';
+
+// Scheduling helpers
+export {
+  scheduleAsyncOperation,
+  clearAsyncContext,
+  isInAsyncContext,
+  createAsyncVibeError,
+  startAsyncOperation,
+} from './scheduling';
+
+export type { AsyncExecutionResult, AsyncOperationExecutor } from './executor';
+export type { AsyncOperationDetails } from './scheduling';