@bratsos/workflow-engine 0.1.0 → 0.2.1

package/dist/stage-BPw7m9Wx.d.ts

@@ -0,0 +1,144 @@
+import { z } from 'zod';
+
+/**
+ * Core type definitions for Workflow System v2
+ *
+ * See WORKFLOW_SYSTEM_PROPOSAL.md for full architectural details
+ */
+
+interface ProgressUpdate {
+    stageId: string;
+    stageName: string;
+    progress: number;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface StageMetrics {
+    startTime: number;
+    endTime: number;
+    duration: number;
+    itemsProcessed?: number;
+    itemsProduced?: number;
+    aiCalls?: number;
+    totalTokens?: number;
+    totalCost?: number;
+}
+interface EmbeddingResult {
+    id: string;
+    content: string;
+    embedding: number[];
+    similarity?: number;
+    metadata?: Record<string, unknown>;
+}
+interface EmbeddingInfo {
+    model: string;
+    dimensions: number;
+    results: EmbeddingResult[];
+    totalProcessed?: number;
+    averageSimilarity?: number;
+}
+interface StageResult<TOutput> {
+    output: TOutput;
+    metrics: StageMetrics;
+    artifacts?: Record<string, unknown>;
+    embeddings?: EmbeddingInfo;
+}
+declare const SuspendedStateSchema: z.ZodObject<{
+    batchId: z.ZodString;
+    statusUrl: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    submittedAt: z.ZodString;
+    pollInterval: z.ZodNumber;
+    maxWaitTime: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+interface SuspendedResult {
+    suspended: true;
+    state: z.infer<typeof SuspendedStateSchema>;
+    pollConfig: {
+        pollInterval: number;
+        maxWaitTime: number;
+        nextPollAt: Date;
+    };
+    metrics: StageMetrics;
+}
+interface CompletionCheckResult<TOutput> {
+    ready: boolean;
+    output?: TOutput;
+    error?: string;
+    nextCheckIn?: number;
+    metrics?: StageMetrics;
+    embeddings?: EmbeddingInfo;
+}
+type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
+type StageMode = "sync" | "async-batch";
+
+/**
+ * Stage interface and context definitions
+ *
+ * Stages are the building blocks of workflows. Each stage:
+ * - Has strongly-typed input, output, and config schemas (Zod)
+ * - Can be sync or async-batch
+ * - Has access to AI helper, storage, and logging via context
+ * - Can suspend workflow for long-running batch operations
+ */
+
+interface StageContext<TInput, TConfig, TWorkflowContext = Record<string, unknown>> {
+    workflowRunId: string;
+    stageId: string;
+    stageNumber: number;
+    stageName: string;
+    /** Database record ID for this stage execution (for logging to persistence) */
+    stageRecordId?: string;
+    input: TInput;
+    config: TConfig;
+    resumeState?: z.infer<typeof SuspendedStateSchema>;
+    onProgress: (update: ProgressUpdate) => void;
+    onLog: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void;
+    log: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void;
+    storage: StageStorage;
+    workflowContext: Partial<TWorkflowContext>;
+}
+interface StageStorage {
+    save<T>(key: string, data: T): Promise<void>;
+    load<T>(key: string): Promise<T>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    getStageKey(stageId: string, suffix?: string): string;
+}
+/**
+ * Context passed to checkCompletion for async-batch stages.
+ * Includes identification info so stages don't need to store it in metadata.
+ */
+interface CheckCompletionContext<TConfig> {
+    workflowRunId: string;
+    stageId: string;
+    /** Database record ID for this stage execution (for logging to persistence) */
+    stageRecordId?: string;
+    config: TConfig;
+    onLog: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void;
+    log: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void;
+    storage: StageStorage;
+}
+interface Stage<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, TConfig extends z.ZodTypeAny, TWorkflowContext = Record<string, unknown>> {
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Optional: List of stage IDs that this stage depends on.
+     * The workflow builder will validate that all dependencies are present
+     * in the workflow before this stage is executed.
+     *
+     * Example: dependencies: ["data-extraction", "guidelines"]
+     */
+    dependencies?: string[];
+    inputSchema: TInput;
+    outputSchema: TOutput;
+    configSchema: TConfig;
+    execute: (context: StageContext<z.infer<TInput>, z.infer<TConfig>, TWorkflowContext>) => Promise<StageResult<z.infer<TOutput>> | SuspendedResult>;
+    checkCompletion?: (suspendedState: z.infer<typeof SuspendedStateSchema>, context: CheckCompletionContext<z.infer<TConfig>>) => Promise<CompletionCheckResult<z.infer<TOutput>>>;
+    mode?: StageMode;
+    estimateCost?: (input: z.infer<TInput>, config: z.infer<TConfig>) => number;
+}
+
+export { type CheckCompletionContext as C, type LogLevel as L, type Stage as S, type StageResult as a, type StageContext as b, SuspendedStateSchema as c, type CompletionCheckResult as d };

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { A as AICallLogger, C as CreateAICallInput, a as AIHelperStats, b as AICallRecord, J as JobQueue, E as EnqueueJobInput, D as DequeueResult, c as JobRecord, d as JobStatus, W as WorkflowPersistence, e as CreateRunInput, f as WorkflowRunRecord, U as UpdateRunInput, g as WorkflowStatus, h as CreateStageInput, i as WorkflowStageRecord, j as UpsertStageInput, k as UpdateStageInput, l as WorkflowStageStatus, m as CreateLogInput, S as SaveArtifactInput, n as WorkflowArtifactRecord, o as WorkflowLogRecord } from '../interface-Cv22wvLG.js';
+import { A as AICallLogger, g as CreateAICallInput, h as AIHelperStats, i as AICallRecord, J as JobQueue, E as EnqueueJobInput, D as DequeueResult, j as JobRecord, k as JobStatus, l as WorkflowPersistence, a as CreateRunInput, W as WorkflowRunRecord, U as UpdateRunInput, m as WorkflowStatus, b as CreateStageInput, c as WorkflowStageRecord, d as UpsertStageInput, e as UpdateStageInput, n as WorkflowStageStatus, f as CreateLogInput, C as CreateOutboxEventInput, O as OutboxRecord, o as SaveArtifactInput, p as WorkflowArtifactRecord, q as WorkflowLogRecord } from '../interface-MMqhfQQK.js';
 
 /**
  * In-Memory AI Call Logger
@@ -184,8 +184,14 @@ declare class InMemoryWorkflowPersistence implements WorkflowPersistence {
     private stages;
     private logs;
     private artifacts;
+    private outbox;
+    private idempotencyKeys;
+    private idempotencyInProgress;
+    private outboxSequences;
     private stageKey;
     private artifactKey;
+    private idempotencyCompositeKey;
+    withTransaction<T>(fn: (tx: WorkflowPersistence) => Promise<T>): Promise<T>;
     createRun(data: CreateRunInput): Promise<WorkflowRunRecord>;
     updateRun(id: string, data: UpdateRunInput): Promise<void>;
     getRun(id: string): Promise<WorkflowRunRecord | null>;
@@ -210,6 +216,22 @@ declare class InMemoryWorkflowPersistence implements WorkflowPersistence {
     getLastCompletedStageBefore(runId: string, executionGroup: number): Promise<WorkflowStageRecord | null>;
     deleteStage(id: string): Promise<void>;
     createLog(data: CreateLogInput): Promise<void>;
+    appendOutboxEvents(events: CreateOutboxEventInput[]): Promise<void>;
+    getUnpublishedOutboxEvents(limit?: number): Promise<OutboxRecord[]>;
+    markOutboxEventsPublished(ids: string[]): Promise<void>;
+    incrementOutboxRetryCount(id: string): Promise<number>;
+    moveOutboxEventToDLQ(id: string): Promise<void>;
+    replayDLQEvents(maxEvents: number): Promise<number>;
+    acquireIdempotencyKey(key: string, commandType: string): Promise<{
+        status: "acquired";
+    } | {
+        status: "replay";
+        result: unknown;
+    } | {
+        status: "in_progress";
+    }>;
+    completeIdempotencyKey(key: string, commandType: string, result: unknown): Promise<void>;
+    releaseIdempotencyKey(key: string, commandType: string): Promise<void>;
     saveArtifact(data: SaveArtifactInput): Promise<void>;
     loadArtifact(runId: string, key: string): Promise<unknown>;
     hasArtifact(runId: string, key: string): Promise<boolean>;

package/dist/testing/index.js

@@ -1,6 +1,6 @@
+import { StaleVersionError } from '../chunk-SPXBCZLB.js';
 import { randomUUID } from 'crypto';
 
-// src/testing/in-memory-ai-logger.ts
 var InMemoryAICallLogger = class {
   calls = /* @__PURE__ */ new Map();
   recordedBatches = /* @__PURE__ */ new Set();
@@ -190,6 +190,7 @@ var InMemoryJobQueue = class {
       createdAt: now,
       updatedAt: now,
       workflowRunId: options.workflowRunId,
+      workflowId: options.workflowId,
       stageId: options.stageId,
       status: "PENDING",
       priority: options.priority ?? 5,
@@ -240,9 +241,11 @@ var InMemoryJobQueue = class {
     return {
       jobId: job.id,
       workflowRunId: job.workflowRunId,
+      workflowId: job.workflowId,
       stageId: job.stageId,
       priority: job.priority,
       attempt: job.attempt,
+      maxAttempts: job.maxAttempts,
       payload: job.payload
     };
   }
@@ -426,6 +429,10 @@ var InMemoryWorkflowPersistence = class {
   stages = /* @__PURE__ */ new Map();
   logs = /* @__PURE__ */ new Map();
   artifacts = /* @__PURE__ */ new Map();
+  outbox = [];
+  idempotencyKeys = /* @__PURE__ */ new Map();
+  idempotencyInProgress = /* @__PURE__ */ new Set();
+  outboxSequences = /* @__PURE__ */ new Map();
   // Helper to generate composite keys for stages
   stageKey(runId, stageId) {
     return `${runId}:${stageId}`;
@@ -434,6 +441,12 @@ var InMemoryWorkflowPersistence = class {
   artifactKey(runId, key) {
     return `${runId}:${key}`;
   }
+  idempotencyCompositeKey(commandType, key) {
+    return `${commandType}:${key}`;
+  }
+  async withTransaction(fn) {
+    return fn(this);
+  }
   // ============================================================================
   // WorkflowRun Operations
   // ============================================================================
@@ -443,6 +456,7 @@ var InMemoryWorkflowPersistence = class {
       id: data.id ?? randomUUID(),
       createdAt: now,
       updatedAt: now,
+      version: 1,
       workflowId: data.workflowId,
       workflowName: data.workflowName,
       workflowType: data.workflowType,
@@ -465,10 +479,20 @@ var InMemoryWorkflowPersistence = class {
     if (!run) {
       throw new Error(`WorkflowRun not found: ${id}`);
     }
+    if (data.expectedVersion !== void 0 && run.version !== data.expectedVersion) {
+      throw new StaleVersionError(
+        "WorkflowRun",
+        id,
+        data.expectedVersion,
+        run.version
+      );
+    }
+    const { expectedVersion: _, ...rest } = data;
     const updated = {
       ...run,
-      ...data,
-      updatedAt: /* @__PURE__ */ new Date()
+      ...rest,
+      updatedAt: /* @__PURE__ */ new Date(),
+      version: run.version + 1
     };
     this.runs.set(id, updated);
   }
@@ -492,7 +516,8 @@ var InMemoryWorkflowPersistence = class {
       ...run,
       status: "RUNNING",
       startedAt: /* @__PURE__ */ new Date(),
-      updatedAt: /* @__PURE__ */ new Date()
+      updatedAt: /* @__PURE__ */ new Date(),
+      version: run.version + 1
     };
     this.runs.set(id, updated);
     return true;
@@ -516,7 +541,8 @@ var InMemoryWorkflowPersistence = class {
       ...currentRun,
       status: "RUNNING",
       startedAt: /* @__PURE__ */ new Date(),
-      updatedAt: /* @__PURE__ */ new Date()
+      updatedAt: /* @__PURE__ */ new Date(),
+      version: currentRun.version + 1
     };
     this.runs.set(claimed.id, claimed);
     return { ...claimed };
@@ -531,6 +557,7 @@ var InMemoryWorkflowPersistence = class {
       id,
       createdAt: now,
       updatedAt: now,
+      version: 1,
       workflowRunId: data.workflowRunId,
       stageId: data.stageId,
       stageName: data.stageName,
@@ -563,7 +590,8 @@ var InMemoryWorkflowPersistence = class {
       const updated = {
         ...existing,
         ...data.update,
-        updatedAt: /* @__PURE__ */ new Date()
+        updatedAt: /* @__PURE__ */ new Date(),
+        version: existing.version + 1
       };
       this.stages.set(existing.id, updated);
       this.stages.set(key, updated);
@@ -577,10 +605,20 @@ var InMemoryWorkflowPersistence = class {
     if (!stage) {
       throw new Error(`WorkflowStage not found: ${id}`);
     }
+    if (data.expectedVersion !== void 0 && stage.version !== data.expectedVersion) {
+      throw new StaleVersionError(
+        "WorkflowStage",
+        id,
+        data.expectedVersion,
+        stage.version
+      );
+    }
+    const { expectedVersion: _, ...rest } = data;
     const updated = {
       ...stage,
-      ...data,
-      updatedAt: /* @__PURE__ */ new Date()
+      ...rest,
+      updatedAt: /* @__PURE__ */ new Date(),
+      version: stage.version + 1
     };
     this.stages.set(id, updated);
     this.stages.set(this.stageKey(stage.workflowRunId, stage.stageId), updated);
@@ -591,10 +629,20 @@ var InMemoryWorkflowPersistence = class {
     if (!stage) {
       throw new Error(`WorkflowStage not found: ${workflowRunId}/${stageId}`);
     }
+    if (data.expectedVersion !== void 0 && stage.version !== data.expectedVersion) {
+      throw new StaleVersionError(
+        "WorkflowStage",
+        `${workflowRunId}/${stageId}`,
+        data.expectedVersion,
+        stage.version
+      );
+    }
+    const { expectedVersion: _, ...rest } = data;
     const updated = {
       ...stage,
-      ...data,
-      updatedAt: /* @__PURE__ */ new Date()
+      ...rest,
+      updatedAt: /* @__PURE__ */ new Date(),
+      version: stage.version + 1
     };
     this.stages.set(stage.id, updated);
     this.stages.set(key, updated);
@@ -626,9 +674,12 @@ var InMemoryWorkflowPersistence = class {
     return stages.map((s) => ({ ...s }));
   }
   async getSuspendedStages(beforeDate) {
-    return Array.from(this.stages.values()).filter(
-      (s) => s.status === "SUSPENDED" && s.nextPollAt && s.nextPollAt <= beforeDate && this.stages.get(s.id) === s
-    ).map((s) => ({ ...s }));
+    const seenIds = /* @__PURE__ */ new Set();
+    return Array.from(this.stages.values()).filter((s) => {
+      if (seenIds.has(s.id)) return false;
+      seenIds.add(s.id);
+      return s.status === "SUSPENDED" && s.nextPollAt !== null && s.nextPollAt <= beforeDate;
+    }).map((s) => ({ ...s }));
   }
   async getFirstSuspendedStageReadyToResume(runId) {
     const stages = await this.getStagesByRun(runId, { status: "SUSPENDED" });
@@ -678,6 +729,94 @@ var InMemoryWorkflowPersistence = class {
     this.logs.set(record.id, record);
   }
   // ============================================================================
+  // Outbox Operations
+  // ============================================================================
+  async appendOutboxEvents(events) {
+    for (const event of events) {
+      const currentSeq = this.outboxSequences.get(event.workflowRunId) ?? 0;
+      const nextSeq = currentSeq + 1;
+      this.outboxSequences.set(event.workflowRunId, nextSeq);
+      const record = {
+        id: randomUUID(),
+        workflowRunId: event.workflowRunId,
+        sequence: nextSeq,
+        eventType: event.eventType,
+        payload: event.payload,
+        causationId: event.causationId,
+        occurredAt: event.occurredAt,
+        publishedAt: null,
+        retryCount: 0,
+        dlqAt: null
+      };
+      this.outbox.push(record);
+    }
+  }
+  async getUnpublishedOutboxEvents(limit) {
+    const effectiveLimit = limit ?? 100;
+    return this.outbox.filter((r) => r.publishedAt === null && r.dlqAt === null).sort((a, b) => {
+      const runCmp = a.workflowRunId.localeCompare(b.workflowRunId);
+      if (runCmp !== 0) return runCmp;
+      return a.sequence - b.sequence;
+    }).slice(0, effectiveLimit).map((r) => ({ ...r }));
+  }
+  async markOutboxEventsPublished(ids) {
+    const idSet = new Set(ids);
+    for (const record of this.outbox) {
+      if (idSet.has(record.id)) {
+        record.publishedAt = /* @__PURE__ */ new Date();
+      }
+    }
+  }
+  async incrementOutboxRetryCount(id) {
+    const record = this.outbox.find((r) => r.id === id);
+    if (!record) throw new Error(`Outbox event not found: ${id}`);
+    record.retryCount++;
+    return record.retryCount;
+  }
+  async moveOutboxEventToDLQ(id) {
+    const record = this.outbox.find((r) => r.id === id);
+    if (!record) throw new Error(`Outbox event not found: ${id}`);
+    record.dlqAt = /* @__PURE__ */ new Date();
+  }
+  async replayDLQEvents(maxEvents) {
+    const dlqEvents = this.outbox.filter((r) => r.dlqAt !== null).slice(0, maxEvents);
+    for (const record of dlqEvents) {
+      record.dlqAt = null;
+      record.retryCount = 0;
+    }
+    return dlqEvents.length;
+  }
+  // ============================================================================
+  // Idempotency Operations
+  // ============================================================================
+  async acquireIdempotencyKey(key, commandType) {
+    const compositeKey = this.idempotencyCompositeKey(commandType, key);
+    const record = this.idempotencyKeys.get(compositeKey);
+    if (record) {
+      return { status: "replay", result: record.result };
+    }
+    if (this.idempotencyInProgress.has(compositeKey)) {
+      return { status: "in_progress" };
+    }
+    this.idempotencyInProgress.add(compositeKey);
+    return { status: "acquired" };
+  }
+  async completeIdempotencyKey(key, commandType, result) {
+    const compositeKey = this.idempotencyCompositeKey(commandType, key);
+    this.idempotencyInProgress.delete(compositeKey);
+    this.idempotencyKeys.set(compositeKey, {
+      key,
+      commandType,
+      result,
+      createdAt: /* @__PURE__ */ new Date()
+    });
+  }
+  async releaseIdempotencyKey(key, commandType) {
+    this.idempotencyInProgress.delete(
+      this.idempotencyCompositeKey(commandType, key)
+    );
+  }
+  // ============================================================================
   // WorkflowArtifact Operations
   // ============================================================================
   async saveArtifact(data) {
@@ -745,6 +884,10 @@ var InMemoryWorkflowPersistence = class {
     this.stages.clear();
     this.logs.clear();
     this.artifacts.clear();
+    this.outbox = [];
+    this.idempotencyKeys.clear();
+    this.idempotencyInProgress.clear();
+    this.outboxSequences.clear();
   }
   /**
    * Get all runs for inspection