@pgflow/client 0.0.0-update-supabase-ba45e13a-20251119080026 → 0.0.0-worker-management-a4f969d1-20251208095931

package/CHANGELOG.md

@@ -1,10 +1,43 @@
 # @pgflow/client
 
-## 0.0.0-update-supabase-ba45e13a-20251119080026
+## 0.0.0-worker-management-a4f969d1-20251208095931
+
+### Patch Changes
+
+- Updated dependencies [0b84bb0]
+- Updated dependencies [90276ce]
+  - @pgflow/core@0.0.0-worker-management-a4f969d1-20251208095931
+  - @pgflow/dsl@0.0.0-worker-management-a4f969d1-20251208095931
+
+## 0.9.1
+
+### Patch Changes
+
+- Updated dependencies [992a86b]
+  - @pgflow/dsl@0.9.1
+  - @pgflow/core@0.9.1
+
+## 0.9.0
+
+### Patch Changes
+
+- @pgflow/core@0.9.0
+- @pgflow/dsl@0.9.0
+
+## 0.8.1
+
+### Patch Changes
+
+- f1d3c32: Fix incorrect Supabase CLI version requirement from 2.34.3 to 2.50.3. CLI 2.50.3 is the first version to include pgmq 1.5.0+, which is required for pgflow 0.8.0+.
+- Updated dependencies [f1d3c32]
+  - @pgflow/core@0.8.1
+  - @pgflow/dsl@0.8.1
+
+## 0.8.0
 
 ### Minor Changes
 
-- 3d8b13b: BREAKING CHANGE: pgflow 0.8.0 requires pgmq 1.5.0+, PostgreSQL 17, and Supabase CLI 2.34.3+
+- 7380237: BREAKING CHANGE: pgflow 0.8.0 requires pgmq 1.5.0+, PostgreSQL 17, and Supabase CLI 2.50.3+
 
   This version modernizes infrastructure dependencies and will NOT work with pgmq 1.4.x or earlier. The migration includes a compatibility check that aborts with a clear error message if requirements are not met.
 
@@ -12,9 +45,9 @@
 
   - pgmq 1.5.0 or higher (previously supported 1.4.x)
   - PostgreSQL 17 (from 15)
-  - Supabase CLI 2.34.3 or higher (includes pgmq 1.5.0+)
+  - Supabase CLI 2.50.3 or higher (includes pgmq 1.5.0+)
 
-  **For Supabase users:** Upgrade your Supabase CLI to 2.34.3+ which includes pgmq 1.5.0 by default.
+  **For Supabase users:** Upgrade your Supabase CLI to 2.50.3+ which includes pgmq 1.5.0 by default.
 
   **For self-hosted users:** Upgrade pgmq to 1.5.0+ and PostgreSQL to 17 before upgrading pgflow.
 
@@ -22,9 +55,9 @@
 
 ### Patch Changes
 
-- Updated dependencies [3d8b13b]
-  - @pgflow/core@0.0.0-update-supabase-ba45e13a-20251119080026
-  - @pgflow/dsl@0.0.0-update-supabase-ba45e13a-20251119080026
+- Updated dependencies [7380237]
+  - @pgflow/core@0.8.0
+  - @pgflow/dsl@0.8.0
 
 ## 0.7.3
 

package/README.md

@@ -230,7 +230,7 @@ When using with `@pgflow/dsl`, you get full type safety:
 import { Flow } from '@pgflow/dsl';
 
 // Define your flow
-const AnalyzeWebsite = new Flow<{ url: string }>({ slug: 'analyze_website' })
+const AnalyzeWebsite = new Flow<{ url: string }>({ slug: 'analyzeWebsite' })
   .step({ slug: 'scrape' }, async (input) => ({ content: 'html...' }))
   .step({ slug: 'analyze' }, async (input) => ({ sentiment: 0.8 }));
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgflow/client",
-  "version": "0.7.3",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "type": "module",
   "scripts": {
@@ -44,9 +44,8 @@
     "@pgflow/dsl": "workspace:*",
     "@types/uuid": "^10.0.0",
     "postgres": "^3.4.5",
-    "supabase": "^2.34.3",
     "terser": "^5.43.0",
     "vite-plugin-dts": "~3.8.1",
     "vitest": "1.3.1"
   }
-}
+}

package/dist/src/browser.d.ts

@@ -0,0 +1,7 @@
+export { PgflowClient } from './lib/PgflowClient.js';
+export { FlowRunStatus, FlowStepStatus } from './lib/types.js';
+export * from './lib/types.js';
+import { PgflowClient } from './lib/PgflowClient.js';
+import type { SupabaseClient } from '@supabase/supabase-js';
+export declare function createClient(supabaseClient: SupabaseClient): PgflowClient<import("pkgs/dsl/dist/dsl.js").AnyFlow>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/src/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC/D,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,wBAAgB,YAAY,CAAC,cAAc,EAAE,cAAc,wDAE1D"}

package/dist/src/browser.js

@@ -0,0 +1,10 @@
+// Browser-specific entry point
+export { PgflowClient } from './lib/PgflowClient.js';
+export { FlowRunStatus, FlowStepStatus } from './lib/types.js';
+export * from './lib/types.js';
+// Import the PgflowClient constructor for the factory
+import { PgflowClient } from './lib/PgflowClient.js';
+// Factory function for creating PgflowClient instances
+export function createClient(supabaseClient) {
+    return new PgflowClient(supabaseClient);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from './lib/types.js';
+export { PgflowClient } from './lib/PgflowClient.js';
+export { FlowRun } from './lib/FlowRun.js';
+export { FlowStep } from './lib/FlowStep.js';
+export type { Unsubscribe } from './lib/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGrD,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7C,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,7 @@
+// Export all types from types.ts
+export * from './lib/types.js';
+// Export main client class
+export { PgflowClient } from './lib/PgflowClient.js';
+// Export FlowRun and FlowStep classes (not just types)
+export { FlowRun } from './lib/FlowRun.js';
+export { FlowStep } from './lib/FlowStep.js';

package/dist/src/lib/FlowRun.d.ts

@@ -0,0 +1,125 @@
+import type { AnyFlow, ExtractFlowInput, ExtractFlowOutput, ExtractFlowSteps } from '@pgflow/dsl';
+import { FlowRunStatus } from './types.js';
+import type { FlowRunState, FlowRunEvents, Unsubscribe, FlowRunBase, FlowRunEvent, StepEvent } from './types.js';
+import { FlowStep } from './FlowStep.js';
+/**
+ * Represents a single execution of a flow
+ */
+export declare class FlowRun<TFlow extends AnyFlow> implements FlowRunBase<FlowRunEvent<TFlow>> {
+    #private;
+    /**
+     * Creates a new FlowRun instance
+     *
+     * @param initialState - Initial state for the run
+     */
+    constructor(initialState: FlowRunState<TFlow>);
+    /**
+     * Get the run ID
+     */
+    get run_id(): string;
+    /**
+     * Get the flow slug
+     */
+    get flow_slug(): string;
+    /**
+     * Get the current status
+     */
+    get status(): FlowRunStatus;
+    /**
+     * Get the started_at timestamp
+     */
+    get started_at(): Date | null;
+    /**
+     * Get the completed_at timestamp
+     */
+    get completed_at(): Date | null;
+    /**
+     * Get the failed_at timestamp
+     */
+    get failed_at(): Date | null;
+    /**
+     * Get the flow input
+     */
+    get input(): ExtractFlowInput<TFlow>;
+    /**
+     * Get the flow output
+     */
+    get output(): ExtractFlowOutput<TFlow> | null;
+    /**
+     * Get the error object
+     */
+    get error(): Error | null;
+    /**
+     * Get the error message
+     */
+    get error_message(): string | null;
+    /**
+     * Get the number of remaining steps
+     */
+    get remaining_steps(): number;
+    /**
+     * Register an event handler for a run event
+     *
+     * @param event - Event type to listen for
+     * @param callback - Callback function to execute when event is emitted
+     * @returns Function to unsubscribe from the event
+     */
+    on<E extends keyof FlowRunEvents<TFlow>>(event: E, callback: FlowRunEvents<TFlow>[E]): Unsubscribe;
+    /**
+     * Get a FlowStep instance for a specific step
+     *
+     * @param stepSlug - Step slug to get
+     * @returns FlowStep instance for the specified step
+     */
+    step<TStepSlug extends keyof ExtractFlowSteps<TFlow> & string>(stepSlug: TStepSlug): FlowStep<TFlow, TStepSlug>;
+    /**
+     * Check if this run has a specific step
+     *
+     * @param stepSlug - Step slug to check
+     * @returns true if the step exists, false otherwise
+     */
+    hasStep(stepSlug: string): boolean;
+    /**
+     * Wait for the run to reach a specific status
+     *
+     * @param targetStatus - The status to wait for
+     * @param options - Optional timeout and abort signal
+     * @returns Promise that resolves with the run instance when the status is reached
+     */
+    waitForStatus(targetStatus: FlowRunStatus.Completed | FlowRunStatus.Failed, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<this>;
+    /**
+     * Apply state from database snapshot (no events emitted)
+     * Used when initializing state from start_flow_with_states() or get_run_with_states()
+     *
+     * @internal This method is only intended for use by PgflowClient.
+     * Applications should not call this directly.
+     */
+    applySnapshot(row: import('@pgflow/core').RunRow): void;
+    /**
+     * Updates the run state based on an event
+     *
+     * @internal This method is only intended for use by PgflowClient and tests.
+     * Applications should not call this directly - state updates should come from
+     * database events through the PgflowClient.
+     *
+     * TODO: After v1.0, make this method private and refactor tests to use PgflowClient
+     * with event emission instead of direct state manipulation.
+     */
+    updateState(event: FlowRunEvent<TFlow>): boolean;
+    /**
+     * Updates a step state based on an event
+     *
+     * @param stepSlug - Step slug to update
+     * @param event - Event data to update the step with
+     * @returns true if the state was updated, false otherwise
+     */
+    updateStepState<TStepSlug extends keyof ExtractFlowSteps<TFlow> & string>(stepSlug: TStepSlug, event: StepEvent<TFlow, TStepSlug>): boolean;
+    /**
+     * Clean up all resources held by this run
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=FlowRun.d.ts.map

package/dist/src/lib/FlowRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlowRun.d.ts","sourceRoot":"","sources":["../../../src/lib/FlowRun.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAkB,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,EAEX,YAAY,EACZ,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;GAEG;AACH,qBAAa,OAAO,CAAC,KAAK,SAAS,OAAO,CACxC,YAAW,WAAW,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;;IAY3C;;;;OAIG;gBACS,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC;IAI7C;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,aAAa,CAE1B;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,IAAI,GAAG,IAAI,CAE5B;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,IAAI,GAAG,IAAI,CAE9B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,IAAI,GAAG,IAAI,CAE3B;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAEnC;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,iBAAiB,CAAC,KAAK,CAAC,GAAG,IAAI,CAE5C;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,KAAK,GAAG,IAAI,CAExB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,GAAG,IAAI,CAEjC;IAED;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;;;;;OAMG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,aAAa,CAAC,KAAK,CAAC,EACrC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAChC,WAAW;IAad;;;;;OAKG;IACH,IAAI,CAAC,SAAS,SAAS,MAAM,gBAAgB,CAAC,KAAK,CAAC,GAAG,MAAM,EAC3D,QAAQ,EAAE,SAAS,GAClB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IA8B7B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKlC;;;;;;OAMG;IACH,aAAa,CACX,YAAY,EAAE,aAAa,CAAC,SAAS,GAAG,aAAa,CAAC,MAAM,EAC5D,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACrD,OAAO,CAAC,IAAI,CAAC;IA+DhB;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,OAAO,cAAc,EAAE,MAAM,GAAG,IAAI;IAavD;;;;;;;;;OASG;IACH,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,OAAO;IAmFhD;;;;;;OAMG;IACH,eAAe,CAAC,SAAS,SAAS,MAAM,gBAAgB,CAAC,KAAK,CAAC,GAAG,MAAM,EACtE,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,GACjC,OAAO;IAyDV;;OAEG;IACH,OAAO,IAAI,IAAI;CAgBhB"}

package/dist/src/lib/FlowRun.js

@@ -0,0 +1,368 @@
+import { createNanoEvents } from 'nanoevents';
+import { FlowRunStatus, FlowStepStatus } from './types.js';
+import { FlowStep } from './FlowStep.js';
+/**
+ * Represents a single execution of a flow
+ */
+export class FlowRun {
+    #state;
+    #events = createNanoEvents();
+    #steps = new Map();
+    #statusPrecedence = {
+        [FlowRunStatus.Started]: 0,
+        [FlowRunStatus.Completed]: 1,
+        [FlowRunStatus.Failed]: 2,
+    };
+    #disposed = false;
+    /**
+     * Creates a new FlowRun instance
+     *
+     * @param initialState - Initial state for the run
+     */
+    constructor(initialState) {
+        this.#state = initialState;
+    }
+    /**
+     * Get the run ID
+     */
+    get run_id() {
+        return this.#state.run_id;
+    }
+    /**
+     * Get the flow slug
+     */
+    get flow_slug() {
+        return this.#state.flow_slug;
+    }
+    /**
+     * Get the current status
+     */
+    get status() {
+        return this.#state.status;
+    }
+    /**
+     * Get the started_at timestamp
+     */
+    get started_at() {
+        return this.#state.started_at;
+    }
+    /**
+     * Get the completed_at timestamp
+     */
+    get completed_at() {
+        return this.#state.completed_at;
+    }
+    /**
+     * Get the failed_at timestamp
+     */
+    get failed_at() {
+        return this.#state.failed_at;
+    }
+    /**
+     * Get the flow input
+     */
+    get input() {
+        return this.#state.input;
+    }
+    /**
+     * Get the flow output
+     */
+    get output() {
+        return this.#state.output;
+    }
+    /**
+     * Get the error object
+     */
+    get error() {
+        return this.#state.error;
+    }
+    /**
+     * Get the error message
+     */
+    get error_message() {
+        return this.#state.error_message;
+    }
+    /**
+     * Get the number of remaining steps
+     */
+    get remaining_steps() {
+        return this.#state.remaining_steps;
+    }
+    /**
+     * Register an event handler for a run event
+     *
+     * @param event - Event type to listen for
+     * @param callback - Callback function to execute when event is emitted
+     * @returns Function to unsubscribe from the event
+     */
+    on(event, callback) {
+        this.#listenerCount++;
+        // Wrap the unsubscribe function to track listener count
+        const unsubscribe = this.#events.on(event, callback);
+        return () => {
+            unsubscribe();
+            this.#listenerCount--;
+            this.#checkAutoDispose();
+        };
+    }
+    /**
+     * Get a FlowStep instance for a specific step
+     *
+     * @param stepSlug - Step slug to get
+     * @returns FlowStep instance for the specified step
+     */
+    step(stepSlug) {
+        // Look up if we already have this step cached
+        const existingStep = this.#steps.get(stepSlug);
+        if (existingStep) {
+            // Safe to cast since we only store steps with matching slugs
+            return existingStep;
+        }
+        // Create a new step instance with default state
+        const step = new FlowStep({
+            run_id: this.run_id,
+            step_slug: stepSlug,
+            status: FlowStepStatus.Created,
+            output: null,
+            error: null,
+            error_message: null,
+            started_at: null,
+            completed_at: null,
+            failed_at: null,
+        });
+        // Cache the step
+        this.#steps.set(stepSlug, step);
+        return step;
+    }
+    /**
+     * Check if this run has a specific step
+     *
+     * @param stepSlug - Step slug to check
+     * @returns true if the step exists, false otherwise
+     */
+    hasStep(stepSlug) {
+        // Check if we have this step cached
+        return this.#steps.has(stepSlug);
+    }
+    /**
+     * Wait for the run to reach a specific status
+     *
+     * @param targetStatus - The status to wait for
+     * @param options - Optional timeout and abort signal
+     * @returns Promise that resolves with the run instance when the status is reached
+     */
+    waitForStatus(targetStatus, options) {
+        const timeoutMs = options?.timeoutMs ?? 5 * 60 * 1000; // Default 5 minutes
+        const { signal } = options || {};
+        // If we already have the target status, resolve immediately
+        if (this.status === targetStatus) {
+            return Promise.resolve(this);
+        }
+        // Otherwise, wait for the status to change
+        return new Promise((resolve, reject) => {
+            let timeoutId;
+            let cleanedUp = false;
+            // Set up timeout if provided
+            if (timeoutMs > 0) {
+                timeoutId = setTimeout(() => {
+                    if (cleanedUp)
+                        return; // Prevent firing if already cleaned up
+                    cleanedUp = true;
+                    unbind();
+                    reject(new Error(`Timeout waiting for run ${this.run_id} to reach status '${targetStatus}'`));
+                }, timeoutMs);
+            }
+            // Set up abort signal if provided
+            let abortCleanup;
+            if (signal) {
+                const abortHandler = () => {
+                    if (cleanedUp)
+                        return; // Prevent double cleanup
+                    cleanedUp = true;
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    unbind();
+                    reject(new Error(`Aborted waiting for run ${this.run_id} to reach status '${targetStatus}'`));
+                };
+                signal.addEventListener('abort', abortHandler);
+                abortCleanup = () => {
+                    signal.removeEventListener('abort', abortHandler);
+                };
+            }
+            // Subscribe to all events
+            const unbind = this.on('*', (event) => {
+                if (event.status === targetStatus) {
+                    if (cleanedUp)
+                        return; // Prevent double cleanup
+                    cleanedUp = true;
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    if (abortCleanup)
+                        abortCleanup();
+                    unbind();
+                    resolve(this);
+                }
+            });
+        });
+    }
+    /**
+     * Apply state from database snapshot (no events emitted)
+     * Used when initializing state from start_flow_with_states() or get_run_with_states()
+     *
+     * @internal This method is only intended for use by PgflowClient.
+     * Applications should not call this directly.
+     */
+    applySnapshot(row) {
+        // Direct state assignment from database row (no event conversion)
+        this.#state.status = row.status;
+        this.#state.input = row.input;
+        this.#state.output = row.output;
+        this.#state.started_at = row.started_at ? new Date(row.started_at) : null;
+        this.#state.completed_at = row.completed_at ? new Date(row.completed_at) : null;
+        this.#state.failed_at = row.failed_at ? new Date(row.failed_at) : null;
+        this.#state.remaining_steps = row.remaining_steps;
+        this.#state.error_message = null; // Database doesn't have error_message for runs
+        this.#state.error = null;
+    }
+    /**
+     * Updates the run state based on an event
+     *
+     * @internal This method is only intended for use by PgflowClient and tests.
+     * Applications should not call this directly - state updates should come from
+     * database events through the PgflowClient.
+     *
+     * TODO: After v1.0, make this method private and refactor tests to use PgflowClient
+     * with event emission instead of direct state manipulation.
+     */
+    updateState(event) {
+        // Validate the event is for this run
+        if (event.run_id !== this.#state.run_id) {
+            return false;
+        }
+        // Check if the event status has higher precedence than current status
+        if (!this.#shouldUpdateStatus(this.#state.status, event.status)) {
+            return false;
+        }
+        // Update state based on event type using narrowing type guards
+        switch (event.status) {
+            case FlowRunStatus.Started:
+                this.#state = {
+                    ...this.#state,
+                    status: FlowRunStatus.Started,
+                    started_at: typeof event.started_at === 'string'
+                        ? new Date(event.started_at)
+                        : new Date(),
+                    remaining_steps: 'remaining_steps' in event
+                        ? Number(event.remaining_steps)
+                        : this.#state.remaining_steps,
+                };
+                this.#events.emit('started', event);
+                break;
+            case FlowRunStatus.Completed:
+                this.#state = {
+                    ...this.#state,
+                    status: FlowRunStatus.Completed,
+                    completed_at: typeof event.completed_at === 'string'
+                        ? new Date(event.completed_at)
+                        : new Date(),
+                    output: event.output,
+                    remaining_steps: 0,
+                };
+                this.#events.emit('completed', event);
+                // Check for auto-dispose
+                this.#checkAutoDispose();
+                break;
+            case FlowRunStatus.Failed:
+                this.#state = {
+                    ...this.#state,
+                    status: FlowRunStatus.Failed,
+                    failed_at: typeof event.failed_at === 'string'
+                        ? new Date(event.failed_at)
+                        : new Date(),
+                    error_message: typeof event.error_message === 'string'
+                        ? event.error_message
+                        : 'Unknown error',
+                    error: new Error(typeof event.error_message === 'string'
+                        ? event.error_message
+                        : 'Unknown error'),
+                };
+                this.#events.emit('failed', event);
+                // Check for auto-dispose
+                this.#checkAutoDispose();
+                break;
+            default: {
+                // Exhaustiveness check - ensures all event statuses are handled
+                event;
+                return false;
+            }
+        }
+        // Also emit to the catch-all listener
+        this.#events.emit('*', event);
+        return true;
+    }
+    /**
+     * Updates a step state based on an event
+     *
+     * @param stepSlug - Step slug to update
+     * @param event - Event data to update the step with
+     * @returns true if the state was updated, false otherwise
+     */
+    updateStepState(stepSlug, event) {
+        const step = this.step(stepSlug);
+        return step.updateState(event);
+    }
+    // Track number of listeners
+    #listenerCount = 0;
+    /**
+     * Checks if auto-dispose should be triggered (when in terminal state with no listeners)
+     */
+    #checkAutoDispose() {
+        // Don't auto-dispose multiple times
+        if (this.#disposed) {
+            return;
+        }
+        // Only auto-dispose in terminal states
+        if (this.status !== FlowRunStatus.Completed &&
+            this.status !== FlowRunStatus.Failed) {
+            return;
+        }
+        // If there are no listeners, auto-dispose
+        if (this.#listenerCount === 0) {
+            this.dispose();
+        }
+    }
+    /**
+     * Determines if a status should be updated based on precedence
+     *
+     * @param currentStatus - Current status
+     * @param newStatus - New status
+     * @returns true if the status should be updated, false otherwise
+     */
+    #shouldUpdateStatus(currentStatus, newStatus) {
+        // Don't allow changes to terminal states
+        if (currentStatus === FlowRunStatus.Completed ||
+            currentStatus === FlowRunStatus.Failed) {
+            return false; // Terminal states should never change
+        }
+        const currentPrecedence = this.#statusPrecedence[currentStatus];
+        const newPrecedence = this.#statusPrecedence[newStatus];
+        // Only allow transitions to higher precedence non-terminal status
+        return newPrecedence > currentPrecedence;
+    }
+    /**
+     * Clean up all resources held by this run
+     */
+    dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        // Clear the map to allow garbage collection of steps
+        this.#steps.clear();
+        // Create a new events object - this effectively clears all listeners
+        // without accessing the private internals of nanoevents
+        this.#events = createNanoEvents();
+        this.#listenerCount = 0;
+        // Mark as disposed
+        this.#disposed = true;
+    }
+}