@bratsos/workflow-engine 0.0.11 → 0.2.0

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

@@ -0,0 +1,264 @@
+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
+ *
+ * A complete in-memory implementation of AICallLogger for testing.
+ * Tracks all AI calls with full cost/token tracking and topic-based aggregation.
+ *
+ * @example
+ * ```typescript
+ * import { InMemoryAICallLogger } from '@bratsos/workflow-engine/testing';
+ *
+ * const aiLogger = new InMemoryAICallLogger();
+ * // Use in tests...
+ * aiLogger.clear(); // Reset between tests
+ * ```
+ */
+
+declare class InMemoryAICallLogger implements AICallLogger {
+    private calls;
+    private recordedBatches;
+    /**
+     * Log a single AI call (fire and forget)
+     */
+    logCall(call: CreateAICallInput): void;
+    /**
+     * Log batch results (for recording batch API results)
+     */
+    logBatchResults(batchId: string, results: CreateAICallInput[]): Promise<void>;
+    /**
+     * Get aggregated stats for a topic prefix
+     */
+    getStats(topicPrefix: string): Promise<AIHelperStats>;
+    /**
+     * Check if batch results are already recorded
+     */
+    isRecorded(batchId: string): Promise<boolean>;
+    /**
+     * Clear all data - useful between tests
+     */
+    clear(): void;
+    /**
+     * Get all calls for inspection
+     */
+    getAllCalls(): AICallRecord[];
+    /**
+     * Get calls by topic for inspection
+     */
+    getCallsByTopic(topic: string): AICallRecord[];
+    /**
+     * Get calls by topic prefix for inspection
+     */
+    getCallsByTopicPrefix(prefix: string): AICallRecord[];
+    /**
+     * Get calls by model for inspection
+     */
+    getCallsByModel(modelKey: string): AICallRecord[];
+    /**
+     * Get calls by call type for inspection
+     */
+    getCallsByType(callType: string): AICallRecord[];
+    /**
+     * Get total cost across all calls
+     */
+    getTotalCost(): number;
+    /**
+     * Get total tokens across all calls
+     */
+    getTotalTokens(): {
+        input: number;
+        output: number;
+    };
+    /**
+     * Get call count
+     */
+    getCallCount(): number;
+    /**
+     * Get all recorded batch IDs
+     */
+    getRecordedBatchIds(): string[];
+    /**
+     * Get the last call made (useful for assertions)
+     */
+    getLastCall(): AICallRecord | null;
+    /**
+     * Assert a call was made with specific properties
+     */
+    hasCallMatching(predicate: (call: AICallRecord) => boolean): boolean;
+}
+
+/**
+ * In-Memory Job Queue
+ *
+ * A complete in-memory implementation of JobQueue for testing.
+ * Supports priority ordering, locking, and stale job recovery.
+ *
+ * @example
+ * ```typescript
+ * import { InMemoryJobQueue } from '@bratsos/workflow-engine/testing';
+ *
+ * const jobQueue = new InMemoryJobQueue();
+ * // Use in tests...
+ * jobQueue.clear(); // Reset between tests
+ * ```
+ */
+
+declare class InMemoryJobQueue implements JobQueue {
+    private jobs;
+    private workerId;
+    private defaultMaxAttempts;
+    constructor(workerId?: string);
+    enqueue(options: EnqueueJobInput): Promise<string>;
+    enqueueParallel(jobs: EnqueueJobInput[]): Promise<string[]>;
+    dequeue(): Promise<DequeueResult | null>;
+    complete(jobId: string): Promise<void>;
+    suspend(jobId: string, nextPollAt: Date): Promise<void>;
+    fail(jobId: string, error: string, shouldRetry?: boolean): Promise<void>;
+    getSuspendedJobsReadyToPoll(): Promise<Array<{
+        jobId: string;
+        stageId: string;
+        workflowRunId: string;
+    }>>;
+    releaseStaleJobs(staleThresholdMs?: number): Promise<number>;
+    /**
+     * Clear all jobs - useful between tests
+     */
+    clear(): void;
+    /**
+     * Get all jobs for inspection
+     */
+    getAllJobs(): JobRecord[];
+    /**
+     * Get jobs by status for inspection
+     */
+    getJobsByStatus(status: JobStatus): JobRecord[];
+    /**
+     * Get a specific job by ID
+     */
+    getJob(jobId: string): JobRecord | null;
+    /**
+     * Get the worker ID for this queue instance
+     */
+    getWorkerId(): string;
+    /**
+     * Set max attempts for new jobs
+     */
+    setDefaultMaxAttempts(maxAttempts: number): void;
+    /**
+     * Simulate a worker crash by releasing a job's lock without completing it
+     */
+    simulateCrash(jobId: string): void;
+    /**
+     * Move a suspended job back to pending (for manual resume testing)
+     */
+    resumeJob(jobId: string): void;
+    /**
+     * Set lockedAt for testing stale job scenarios
+     */
+    setJobLockedAt(jobId: string, lockedAt: Date): void;
+    /**
+     * Set nextPollAt for testing suspended job polling
+     */
+    setJobNextPollAt(jobId: string, nextPollAt: Date | null): void;
+}
+
+/**
+ * In-Memory Workflow Persistence
+ *
+ * A complete in-memory implementation of WorkflowPersistence for testing.
+ * All data is stored in Maps and lost when the instance is garbage collected.
+ *
+ * @example
+ * ```typescript
+ * import { InMemoryWorkflowPersistence } from '@bratsos/workflow-engine/testing';
+ *
+ * const persistence = new InMemoryWorkflowPersistence();
+ * // Use in tests...
+ * persistence.clear(); // Reset between tests
+ * ```
+ */
+
+declare class InMemoryWorkflowPersistence implements WorkflowPersistence {
+    private runs;
+    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>;
+    getRunStatus(id: string): Promise<WorkflowStatus | null>;
+    getRunsByStatus(status: WorkflowStatus): Promise<WorkflowRunRecord[]>;
+    claimPendingRun(id: string): Promise<boolean>;
+    claimNextPendingRun(): Promise<WorkflowRunRecord | null>;
+    createStage(data: CreateStageInput): Promise<WorkflowStageRecord>;
+    upsertStage(data: UpsertStageInput): Promise<WorkflowStageRecord>;
+    updateStage(id: string, data: UpdateStageInput): Promise<void>;
+    updateStageByRunAndStageId(workflowRunId: string, stageId: string, data: UpdateStageInput): Promise<void>;
+    getStage(runId: string, stageId: string): Promise<WorkflowStageRecord | null>;
+    getStageById(id: string): Promise<WorkflowStageRecord | null>;
+    getStagesByRun(runId: string, options?: {
+        status?: WorkflowStageStatus;
+        orderBy?: "asc" | "desc";
+    }): Promise<WorkflowStageRecord[]>;
+    getSuspendedStages(beforeDate: Date): Promise<WorkflowStageRecord[]>;
+    getFirstSuspendedStageReadyToResume(runId: string): Promise<WorkflowStageRecord | null>;
+    getFirstFailedStage(runId: string): Promise<WorkflowStageRecord | null>;
+    getLastCompletedStage(runId: string): Promise<WorkflowStageRecord | null>;
+    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>;
+    deleteArtifact(runId: string, key: string): Promise<void>;
+    listArtifacts(runId: string): Promise<WorkflowArtifactRecord[]>;
+    getStageIdForArtifact(runId: string, stageId: string): Promise<string | null>;
+    saveStageOutput(runId: string, workflowType: string, stageId: string, output: unknown): Promise<string>;
+    /**
+     * Clear all data - useful between tests
+     */
+    clear(): void;
+    /**
+     * Get all runs for inspection
+     */
+    getAllRuns(): WorkflowRunRecord[];
+    /**
+     * Get all stages for inspection
+     */
+    getAllStages(): WorkflowStageRecord[];
+    /**
+     * Get all logs for inspection
+     */
+    getAllLogs(): WorkflowLogRecord[];
+    /**
+     * Get all artifacts for inspection
+     */
+    getAllArtifacts(): WorkflowArtifactRecord[];
+}
+
+export { InMemoryAICallLogger, InMemoryJobQueue, InMemoryWorkflowPersistence };