@cascade-flow/worker 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# @cascadeflow/worker
+
+Distributed step-level workflow execution with queue-based processing.
+
+## Installation
+
+The worker requires a backend implementation to persist workflow state. Install the worker along with your chosen backend:
+
+### With Filesystem Backend (Recommended for Development)
+
+```bash
+npm install @cascadeflow/worker @cascadeflow/backend-filesystem
+```
+
+### With PostgreSQL Backend (Production)
+
+```bash
+npm install @cascadeflow/worker @cascadeflow/backend-postgres
+```
+
+## Usage
+
+### CLI
+
+```bash
+cf worker start [--mode unified|executor|scheduler] [--concurrency n]
+```
+
+### Programmatic
+
+```typescript
+import { StepWorker } from "@cascade-flow/worker";
+import { FileSystemBackend } from "@cascade-flow/backend-filesystem";
+
+const worker = new StepWorker(new FileSystemBackend("./.runs"), {
+  mode: "unified",
+  concurrency: 5,
+  pollInterval: 1000,
+});
+
+await worker.start();
+```
+
+**Note:** Worker automatically discovers workflows with support for nested step groups. Steps can be organized in arbitrary directory hierarchies (e.g., `steps/data-processing/extract/fetch-data/step.ts`). Step IDs in the registry will reflect the full path.
+
+## Architecture
+
+**Events-as-queue pattern with 4 concurrent loops:**
+
+1. **Executor** - Claims & executes scheduled steps
+2. **Scheduler** - Schedules ready steps, detects completion
+3. **Heartbeat** - Proves worker liveness (5s interval)
+4. **Reclamation** - Reclaims steps from crashed workers (30s threshold)
+
+## Modes
+
+- **Unified** (default) - All 4 loops in one process
+- **Executor** - Execute + heartbeat only (needs separate scheduler)
+- **Scheduler** - Schedule + reclamation only (needs separate executors)
+
+## Timeouts
+
+**Step execution (3-tier fallback):**
+1. `defineStep({ timeoutMs })` - Highest priority
+2. `submit({ timeout })` - Workflow-wide default
+3. `300000ms` (5 min) - System default
+
+**Worker health monitoring:**
+- Stale threshold (default 30s) - Detects crashed workers via missing heartbeats
+
+## Failure Recovery
+
+- **Worker crash** → Stale heartbeat → Step reclaimed → Rescheduled
+- **Step timeout** → `StepFailed` event → Retry with delay (if configured)
+- **Terminal failure** → Scheduler stops scheduling → `WorkflowFailed`
+
+## API
+
+```typescript
+interface StepWorkerOptions {
+  workerId?: string;
+  mode?: "unified" | "executor" | "scheduler";
+  concurrency?: number;
+  pollInterval?: number;
+  heartbeatInterval?: number;
+  staleThreshold?: number;
+  schedulerInterval?: number;
+  shutdownTimeout?: number;
+  workflowsDir?: string;
+  baseDir?: string;
+}
+
+class StepWorker {
+  constructor(backend?: Backend, options?: StepWorkerOptions);
+  async start(): Promise<void>;
+  async stop(): Promise<void>;
+  getStats(): StepWorkerStats;
+}
+```

package/dist/execution/dependency-resolver.d.ts

@@ -0,0 +1,20 @@
+import type { Backend } from "@cascade-flow/backend-interface";
+import { type LoadedStep } from "@cascade-flow/runner";
+/**
+ * Check if all dependencies for a step are satisfied
+ * Returns true if the step can be scheduled
+ */
+export declare function checkDependenciesSatisfied(step: LoadedStep, backend: Backend, workflowSlug: string, runId: string): Promise<boolean>;
+/**
+ * Load outputs from all dependencies
+ * Returns a map of dependency alias to output value
+ */
+export declare function loadDependencyOutputs(step: LoadedStep, backend: Backend, workflowSlug: string, runId: string): Promise<Record<string, any>>;
+/**
+ * Find all steps that depend on a given step
+ * @param targetStepId - The stepId (unique identifier) to find dependents for
+ * @param allSteps - All steps in the workflow
+ * @param requiredOnly - If true, only return steps with required dependencies
+ */
+export declare function findDependentSteps(targetStepId: string, allSteps: LoadedStep[], requiredOnly?: boolean): LoadedStep[];
+//# sourceMappingURL=dependency-resolver.d.ts.map

package/dist/execution/dependency-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-resolver.d.ts","sourceRoot":"","sources":["../../src/execution/dependency-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAE/D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvD;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CA+BlB;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAoC9B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,UAAU,EAAE,EACtB,YAAY,GAAE,OAAe,GAC5B,UAAU,EAAE,CAed"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { StepWorker } from "./step-worker.ts";
+export type { StepWorkerOptions, StepWorkerStats, WorkerMode } from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}