pg-workflows 0.6.1 → 0.7.1

package/README.md

@@ -51,7 +51,8 @@ If you need enterprise-grade features like distributed tracing, complex DAG sche
 - **Built-in Retries** - Automatic retries with exponential backoff at the workflow level.
 - **Configurable Timeouts** - Set workflow-level and step-level timeouts to prevent runaway executions.
 - **Progress Tracking** - Monitor workflow completion percentage, completed steps, and total steps in real-time.
-- **Input Validation** - Define schemas with Zod for type-safe, validated workflow inputs.
+- **Input Validation** - Define schemas with any [Standard Schema](https://github.com/standard-schema/standard-schema)-compliant library (Zod, Valibot, ArkType, etc.) for type-safe, validated workflow inputs.
+- **Idempotent starts** - Optional `idempotencyKey` on `startWorkflow()` so duplicate API calls or retries return the same run instead of enqueueing another job.
 - **Built on pg-boss** - Leverages the battle-tested [pg-boss](https://github.com/timgit/pg-boss) job queue for reliable task scheduling. pg-boss is bundled as a dependency - no separate install or configuration needed.
 
 ---
@@ -151,6 +152,8 @@ const run = await engine.startWorkflow({
   workflowId: 'send-welcome-email',
   resourceId: 'user-123',
   input: { email: 'user@example.com' },
+  // Optional: same key returns the existing run (deduplicates double-submits / retries)
+  idempotencyKey: 'welcome:user-123',
 });
 
 // Send an event to resume the waiting workflow
@@ -357,8 +360,8 @@ const myWorkflow = workflow(
     // Your workflow logic here
   },
   {
-    inputSchema: z.object({ /* ... */ }),
-    timeout: 60000, // milliseconds
+    inputSchema: mySchema,  // any Standard Schema-compliant schema
+    timeout: 60000,          // milliseconds
     retries: 3,
   }
 );
@@ -426,6 +429,29 @@ const { items } = await engine.getRuns({
 });
 ```
 
+### Idempotency key
+
+Pass an optional `idempotencyKey` to `startWorkflow()` when the same logical start might be requested more than once (user double-clicks, API retries, or at-least-once webhooks). The engine stores the key on the run; a second `startWorkflow` with the **same** key returns the **existing** run and does **not** enqueue a second job.
+
+Keys are **globally unique** in the database (up to 256 characters), not scoped per workflow or resource. Prefer stable, namespaced strings so different workflows never collide—for example `send-welcome-email:order-123` instead of a bare order id.
+
+```typescript
+const run = await engine.startWorkflow({
+  workflowId: 'send-welcome-email',
+  input: { email: 'user@example.com' },
+  idempotencyKey: 'send-welcome-email:checkout-session_cs_abc123',
+});
+
+// Idempotent: returns the same run and run.id as above
+const again = await engine.startWorkflow({
+  workflowId: 'send-welcome-email',
+  input: { email: 'other@example.com' }, // ignored for deduplication — existing run wins
+  idempotencyKey: 'send-welcome-email:checkout-session_cs_abc123',
+});
+```
+
+The returned `WorkflowRun` includes `idempotencyKey` (or `null` if omitted).
+
 ### Pause and Resume
 
 Manually pause a workflow and resume it later:
@@ -476,6 +502,96 @@ await engine.fastForwardWorkflow({
 | `step.poll()` | Writes `data` as the poll result and triggers resolution |
 | `step.pause()` | Delegates to `resumeWorkflow()` |
 
+### Input Validation
+
+pg-workflows supports any [Standard Schema](https://github.com/standard-schema/standard-schema)-compliant validation library for `inputSchema`. This means you can use Zod, Valibot, ArkType, or any library that implements the Standard Schema spec. When a schema is provided, the workflow input is validated before execution and the handler's `input` parameter is fully typed.
+
+#### With Zod
+
+```typescript
+import { workflow } from 'pg-workflows';
+import { z } from 'zod';
+
+const myWorkflow = workflow(
+  'user-onboarding',
+  async ({ step, input }) => {
+    // input is typed as { email: string; name: string }
+    await step.run('send-welcome', async () => {
+      return await sendEmail(input.email, `Welcome, ${input.name}!`);
+    });
+  },
+  {
+    inputSchema: z.object({
+      email: z.string().email(),
+      name: z.string(),
+    }),
+  }
+);
+```
+
+#### With Valibot
+
+```typescript
+import { workflow } from 'pg-workflows';
+import * as v from 'valibot';
+
+const myWorkflow = workflow(
+  'user-onboarding',
+  async ({ step, input }) => {
+    // input is typed as { email: string; name: string }
+    await step.run('send-welcome', async () => {
+      return await sendEmail(input.email, `Welcome, ${input.name}!`);
+    });
+  },
+  {
+    inputSchema: v.object({
+      email: v.pipe(v.string(), v.email()),
+      name: v.string(),
+    }),
+  }
+);
+```
+
+#### Without a Schema
+
+When no `inputSchema` is provided, input is not validated and `input` is typed as `unknown`. This is because the engine has no guarantee about the shape of the data — it passes through whatever was provided to `startWorkflow()`. You are responsible for narrowing the type yourself, either with a type assertion or runtime checks:
+
+```typescript
+import { workflow } from 'pg-workflows';
+
+const myWorkflow = workflow(
+  'process-order',
+  async ({ step, input }) => {
+    // Option 1: Type assertion — you trust the caller
+    const { orderId, amount } = input as { orderId: string; amount: number };
+
+    await step.run('charge', async () => {
+      return await chargeOrder(orderId, amount);
+    });
+  }
+);
+
+const myDefensiveWorkflow = workflow(
+  'process-order-safe',
+  async ({ step, input }) => {
+    // Option 2: Runtime checks — you verify before using
+    if (typeof input !== 'object' || input === null) {
+      throw new Error('Expected input to be an object');
+    }
+    const { orderId, amount } = input as Record<string, unknown>;
+    if (typeof orderId !== 'string' || typeof amount !== 'number') {
+      throw new Error('Invalid input shape');
+    }
+
+    await step.run('charge', async () => {
+      return await chargeOrder(orderId, amount);
+    });
+  }
+);
+```
+
+Using an `inputSchema` is recommended — it validates input at the engine boundary before your handler runs, and gives you full type inference with no manual work.
+
 ---
 
 ## Examples
@@ -618,7 +734,7 @@ When `boss` is omitted, pg-boss is created automatically with an isolated schema
 | `start(asEngine?, options?)` | Start the engine and workers |
 | `stop()` | Stop the engine gracefully |
 | `registerWorkflow(definition)` | Register a workflow definition |
-| `startWorkflow({ workflowId, resourceId?, input, options? })` | Start a new workflow run. `resourceId` optionally ties the run to an external entity (see [Resource ID](#resource-id)). |
+| `startWorkflow({ workflowId, resourceId?, input, idempotencyKey?, options? })` | Start a new workflow run. `resourceId` optionally ties the run to an external entity (see [Resource ID](#resource-id)). `idempotencyKey` optionally deduplicates starts (see [Idempotency key](#idempotency-key)). |
 | `pauseWorkflow({ runId, resourceId? })` | Pause a running workflow |
 | `resumeWorkflow({ runId, resourceId?, options? })` | Resume a paused workflow |
 | `cancelWorkflow({ runId, resourceId? })` | Cancel a workflow |
@@ -699,7 +815,7 @@ enum WorkflowStatus {
 
 The engine automatically runs migrations on startup to create the required tables:
 
-- `workflow_runs` - Stores workflow execution state, step results, and timeline in the `public` schema. The optional `resource_id` column (indexed) associates each run with an external entity in your application. See [Resource ID](#resource-id).
+- `workflow_runs` - Stores workflow execution state, step results, and timeline in the `public` schema. The optional `resource_id` column (indexed) associates each run with an external entity in your application. See [Resource ID](#resource-id). The optional `idempotency_key` column has a unique partial index for [idempotent starts](#idempotency-key).
 - `pgboss_v12_pgworkflow.*` - pg-boss job queue tables for reliable task scheduling (isolated schema to avoid conflicts)
 
 ---
@@ -726,7 +842,7 @@ npm install pg-workflows pg
 - Node.js >= 18.0.0
 - PostgreSQL >= 10
 - `pg` >= 8.0.0 (peer dependency)
-- `zod` >= 3.0.0 (optional peer dependency, needed only if using `inputSchema`)
+- A [Standard Schema](https://github.com/standard-schema/standard-schema)-compliant validation library (Zod, Valibot, ArkType, etc.) if using `inputSchema`
 
 ## Acknowledgments
 

package/dist/index.cjs

@@ -99,11 +99,13 @@ class WorkflowEngineError extends Error {
   workflowId;
   runId;
   cause;
-  constructor(message, workflowId, runId, cause = undefined) {
+  issues;
+  constructor(message, workflowId, runId, cause = undefined, issues) {
     super(message);
     this.workflowId = workflowId;
     this.runId = runId;
     this.cause = cause;
+    this.issues = issues;
     this.name = "WorkflowEngineError";
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, WorkflowEngineError);
@@ -240,17 +242,17 @@ function parseWorkflowHandler(handler) {
 }
 
 // src/db/migration.ts
+var MIGRATION_LOCK_ID = 738291645;
+var CURRENT_SCHEMA_VERSION = 2;
 async function runMigrations(db) {
-  const tableExistsResult = await db.executeSql(`
-    SELECT EXISTS (
-      SELECT FROM information_schema.tables 
-      WHERE table_schema = 'public' 
-      AND table_name = 'workflow_runs'
-    );
-  `, []);
-  if (!tableExistsResult.rows[0]?.exists) {
-    await db.executeSql(`
-      CREATE TABLE workflow_runs (
+  if (await isSchemaUpToDate(db)) {
+    return;
+  }
+  const currentVersion = await getCurrentVersion(db);
+  const commands = [];
+  if (currentVersion < 1) {
+    commands.push(`
+      CREATE TABLE IF NOT EXISTS workflow_runs (
         id varchar(32) PRIMARY KEY NOT NULL,
         created_at timestamp with time zone DEFAULT now() NOT NULL,
         updated_at timestamp with time zone DEFAULT now() NOT NULL,
@@ -269,25 +271,66 @@ async function runMigrations(db) {
         retry_count integer DEFAULT 0 NOT NULL,
         max_retries integer DEFAULT 0 NOT NULL,
         job_id varchar(256)
-      );
-    `, []);
-    await db.executeSql(`
-      CREATE INDEX workflow_runs_created_at_idx ON workflow_runs USING btree (created_at);
-      CREATE INDEX workflow_runs_resource_id_created_at_idx ON workflow_runs USING btree (resource_id, created_at DESC);
-      CREATE INDEX workflow_runs_status_created_at_idx ON workflow_runs USING btree (status, created_at DESC);
-      CREATE INDEX workflow_runs_workflow_id_created_at_idx ON workflow_runs USING btree (workflow_id, created_at DESC);
-      CREATE INDEX workflow_runs_resource_id_workflow_id_created_at_idx ON workflow_runs USING btree (resource_id, workflow_id, created_at DESC);
-    `, []);
+      )
+    `);
+    commands.push(`
+      CREATE INDEX IF NOT EXISTS workflow_runs_created_at_idx ON workflow_runs USING btree (created_at)
+    `);
+    commands.push(`
+      CREATE INDEX IF NOT EXISTS workflow_runs_resource_id_created_at_idx ON workflow_runs USING btree (resource_id, created_at DESC)
+    `);
+    commands.push(`
+      CREATE INDEX IF NOT EXISTS workflow_runs_status_created_at_idx ON workflow_runs USING btree (status, created_at DESC)
+    `);
+    commands.push(`
+      CREATE INDEX IF NOT EXISTS workflow_runs_workflow_id_created_at_idx ON workflow_runs USING btree (workflow_id, created_at DESC)
+    `);
+    commands.push(`
+      CREATE INDEX IF NOT EXISTS workflow_runs_resource_id_workflow_id_created_at_idx ON workflow_runs USING btree (resource_id, workflow_id, created_at DESC)
+    `);
+  }
+  if (currentVersion < 2) {
+    commands.push("DROP INDEX IF EXISTS workflow_runs_workflow_id_idx");
+    commands.push("DROP INDEX IF EXISTS workflow_runs_resource_id_idx");
+    commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS idempotency_key varchar(256)");
+    commands.push(`
+      CREATE UNIQUE INDEX IF NOT EXISTS workflow_runs_idempotency_key_idx ON workflow_runs (idempotency_key) WHERE idempotency_key IS NOT NULL
+    `);
+  }
+  if (currentVersion === 0) {
+    commands.push(`INSERT INTO workflow_schema_version (version) VALUES (${CURRENT_SCHEMA_VERSION})`);
   } else {
-    await db.executeSql(`
-      DROP INDEX IF EXISTS workflow_runs_workflow_id_idx;
-      DROP INDEX IF EXISTS workflow_runs_resource_id_idx;
-      CREATE INDEX IF NOT EXISTS workflow_runs_created_at_idx ON workflow_runs USING btree (created_at);
-      CREATE INDEX IF NOT EXISTS workflow_runs_resource_id_created_at_idx ON workflow_runs USING btree (resource_id, created_at DESC);
-      CREATE INDEX IF NOT EXISTS workflow_runs_status_created_at_idx ON workflow_runs USING btree (status, created_at DESC);
-      CREATE INDEX IF NOT EXISTS workflow_runs_workflow_id_created_at_idx ON workflow_runs USING btree (workflow_id, created_at DESC);
-      CREATE INDEX IF NOT EXISTS workflow_runs_resource_id_workflow_id_created_at_idx ON workflow_runs USING btree (resource_id, workflow_id, created_at DESC);
-      `, []);
+    commands.push(`UPDATE workflow_schema_version SET version = ${CURRENT_SCHEMA_VERSION}`);
+  }
+  if (commands.length === 0) {
+    return;
+  }
+  const sql = [
+    "BEGIN",
+    "SET LOCAL lock_timeout = '30s'",
+    "SET LOCAL idle_in_transaction_session_timeout = '30s'",
+    `SELECT pg_advisory_xact_lock(${MIGRATION_LOCK_ID})`,
+    "CREATE TABLE IF NOT EXISTS workflow_schema_version (version integer NOT NULL)",
+    ...commands,
+    "COMMIT"
+  ].join(`;
+`);
+  await db.executeSql(sql, []);
+}
+async function isSchemaUpToDate(db) {
+  try {
+    const result = await db.executeSql("SELECT version FROM workflow_schema_version LIMIT 1", []);
+    return (result.rows[0]?.version ?? 0) >= CURRENT_SCHEMA_VERSION;
+  } catch {
+    return false;
+  }
+}
+async function getCurrentVersion(db) {
+  try {
+    const result = await db.executeSql("SELECT version FROM workflow_schema_version LIMIT 1", []);
+    return result.rows[0]?.version ?? 0;
+  } catch {
+    return 0;
   }
 }
 
@@ -315,7 +358,8 @@ function mapRowToWorkflowRun(row) {
     timeoutAt: row.timeout_at ? new Date(row.timeout_at) : null,
     retryCount: row.retry_count,
     maxRetries: row.max_retries,
-    jobId: row.job_id
+    jobId: row.job_id,
+    idempotencyKey: row.idempotency_key
   };
 }
 async function insertWorkflowRun({
@@ -325,7 +369,8 @@ async function insertWorkflowRun({
   status,
   input,
   maxRetries,
-  timeoutAt
+  timeoutAt,
+  idempotencyKey
 }, db) {
   const runId = generateKSUID("run");
   const now = new Date;
@@ -341,9 +386,11 @@ async function insertWorkflowRun({
       created_at,
       updated_at,
       timeline,
-      retry_count
+      retry_count,
+      idempotency_key
     )
-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+    ON CONFLICT (idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
     RETURNING *`, [
     runId,
     resourceId ?? null,
@@ -356,13 +403,19 @@ async function insertWorkflowRun({
     now,
     now,
     "{}",
-    0
+    0,
+    idempotencyKey ?? null
+  ]);
+  if (result.rows[0]) {
+    return { run: mapRowToWorkflowRun(result.rows[0]), created: true };
+  }
+  const existing = await db.executeSql("SELECT * FROM workflow_runs WHERE idempotency_key = $1", [
+    idempotencyKey
   ]);
-  const insertedRun = result.rows[0];
-  if (!insertedRun) {
-    throw new Error("Failed to insert workflow run");
+  if (!existing.rows[0]) {
+    throw new Error(`Idempotency conflict: existing run not found for key "${idempotencyKey}"`);
   }
-  return mapRowToWorkflowRun(insertedRun);
+  return { run: mapRowToWorkflowRun(existing.rows[0]), created: false };
 }
 async function getWorkflowRun({
   runId,
@@ -682,6 +735,7 @@ class WorkflowEngine {
     resourceId,
     workflowId,
     input,
+    idempotencyKey,
     options
   }) {
     if (!this._started) {
@@ -697,33 +751,36 @@ class WorkflowEngine {
       throw new WorkflowEngineError(`Workflow ${workflowId} has no steps`, workflowId);
     }
     if (workflow2.inputSchema) {
-      const result = workflow2.inputSchema.safeParse(input);
-      if (!result.success) {
-        throw new WorkflowEngineError(result.error.message, workflowId);
+      const result = await workflow2.inputSchema["~standard"].validate(input);
+      if (result.issues) {
+        throw new WorkflowEngineError(JSON.stringify(result.issues), workflowId, undefined, undefined, result.issues);
       }
     }
     const initialStepId = workflow2.steps[0]?.id ?? "__start__";
     const run = await withPostgresTransaction(this.boss.getDb(), async (_db) => {
       const timeoutAt = options?.timeout ? new Date(Date.now() + options.timeout) : workflow2.timeout ? new Date(Date.now() + workflow2.timeout) : null;
-      const insertedRun = await insertWorkflowRun({
+      const { run: insertedRun, created } = await insertWorkflowRun({
         resourceId,
         workflowId,
         currentStepId: initialStepId,
         status: "running" /* RUNNING */,
         input,
         maxRetries: options?.retries ?? workflow2.retries ?? 0,
-        timeoutAt
+        timeoutAt,
+        idempotencyKey
       }, _db);
-      const job = {
-        runId: insertedRun.id,
-        resourceId,
-        workflowId,
-        input
-      };
-      await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
-        startAfter: new Date,
-        expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds
-      });
+      if (created) {
+        const job = {
+          runId: insertedRun.id,
+          resourceId,
+          workflowId,
+          input
+        };
+        await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
+          startAfter: new Date,
+          expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds
+        });
+      }
       return insertedRun;
     }, this.pool);
     this.logger.log("Started workflow run", {
@@ -1423,5 +1480,5 @@ ${error.stack}` : String(error)
   }
 }
 
-//# debugId=12BE08AB4C2E4D0564756E2164756E21
+//# debugId=644364C840A9480364756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { StandardSchemaV1 } from "@standard-schema/spec";
 type WorkflowRun = {
 	id: string;
 	createdAt: Date;
@@ -18,6 +18,7 @@ type WorkflowRun = {
 	retryCount: number;
 	maxRetries: number;
 	jobId: string | null;
+	idempotencyKey: string | null;
 };
 type DurationObject = {
 	weeks?: number;
@@ -44,8 +45,8 @@ declare enum StepType {
 	DELAY = "delay",
 	POLL = "poll"
 }
-type InputParameters = z.ZodTypeAny;
-type InferInputParameters<P extends InputParameters> = P extends z.ZodTypeAny ? z.infer<P> : never;
+type InputParameters = StandardSchemaV1;
+type InferInputParameters<P extends InputParameters> = StandardSchemaV1.InferOutput<P>;
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
@@ -109,12 +110,10 @@ type WorkflowContext<
 	timeline: Record<string, unknown>;
 	logger: WorkflowLogger;
 };
-type WorkflowDefinition<
-	TInput extends InputParameters = InputParameters,
-	TStep extends StepBaseContext = StepBaseContext
-> = {
+type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	id: string;
-	handler: (context: WorkflowContext<TInput, TStep>) => Promise<unknown>;
+	/** Widest context avoids contravariance when collecting definitions; `workflow()` still types the handler narrowly. */
+	handler: (context: WorkflowContext<InputParameters, StepBaseContext>) => Promise<unknown>;
 	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
@@ -127,10 +126,7 @@ type StepInternalDefinition = {
 	loop: boolean;
 	isDynamic: boolean;
 };
-type WorkflowInternalDefinition<
-	TInput extends InputParameters = InputParameters,
-	TStep extends StepBaseContext = StepBaseContext
-> = WorkflowDefinition<TInput, TStep> & {
+type WorkflowInternalDefinition<TInput extends InputParameters = InputParameters> = WorkflowDefinition<TInput> & {
 	steps: StepInternalDefinition[];
 };
 /**
@@ -138,7 +134,7 @@ type WorkflowInternalDefinition<
 * TStepExt is the accumulated step extension from all plugins (step = StepContext & TStepExt).
 */
 interface WorkflowFactory<TStepExt = object> {
-	(id: string, handler: (context: WorkflowContext<InputParameters, StepBaseContext & TStepExt>) => Promise<unknown>, options?: WorkflowOptions<InputParameters>): WorkflowDefinition<InputParameters, StepBaseContext & TStepExt>;
+	<I extends InputParameters = InputParameters>(id: string, handler: (context: WorkflowContext<I, StepBaseContext & TStepExt>) => Promise<unknown>, options?: WorkflowOptions<I>): WorkflowDefinition<I>;
 	use<TNewExt>(plugin: WorkflowPlugin<StepBaseContext & TStepExt, TNewExt>): WorkflowFactory<TStepExt & TNewExt>;
 }
 type WorkflowRunProgress = WorkflowRun & {
@@ -186,13 +182,14 @@ declare class WorkflowEngine {
 		batchSize?: number;
 	}): Promise<void>;
 	stop(): Promise<void>;
-	registerWorkflow<TStep extends StepBaseContext>(definition: WorkflowDefinition<InputParameters, TStep>): Promise<WorkflowEngine>;
+	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
-	startWorkflow({ resourceId, workflowId, input, options }: {
+	startWorkflow({ resourceId, workflowId, input, idempotencyKey, options }: {
 		resourceId?: string;
 		workflowId: string;
 		input: unknown;
+		idempotencyKey?: string;
 		options?: {
 			timeout?: number;
 			retries?: number;
@@ -278,11 +275,13 @@ declare class WorkflowEngine {
 		hasPrev: boolean;
 	}>;
 }
+import { StandardSchemaV1 as StandardSchemaV12 } from "@standard-schema/spec";
 declare class WorkflowEngineError extends Error {
 	readonly workflowId?: string | undefined;
 	readonly runId?: string | undefined;
 	readonly cause: Error | undefined;
-	constructor(message: string, workflowId?: string | undefined, runId?: string | undefined, cause?: Error | undefined);
+	readonly issues?: StandardSchemaV12.FailureResult["issues"] | undefined;
+	constructor(message: string, workflowId?: string | undefined, runId?: string | undefined, cause?: Error | undefined, issues?: StandardSchemaV12.FailureResult["issues"] | undefined);
 }
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { StandardSchemaV1 } from "@standard-schema/spec";
 type WorkflowRun = {
 	id: string;
 	createdAt: Date;
@@ -18,6 +18,7 @@ type WorkflowRun = {
 	retryCount: number;
 	maxRetries: number;
 	jobId: string | null;
+	idempotencyKey: string | null;
 };
 type DurationObject = {
 	weeks?: number;
@@ -44,8 +45,8 @@ declare enum StepType {
 	DELAY = "delay",
 	POLL = "poll"
 }
-type InputParameters = z.ZodTypeAny;
-type InferInputParameters<P extends InputParameters> = P extends z.ZodTypeAny ? z.infer<P> : never;
+type InputParameters = StandardSchemaV1;
+type InferInputParameters<P extends InputParameters> = StandardSchemaV1.InferOutput<P>;
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
@@ -109,12 +110,10 @@ type WorkflowContext<
 	timeline: Record<string, unknown>;
 	logger: WorkflowLogger;
 };
-type WorkflowDefinition<
-	TInput extends InputParameters = InputParameters,
-	TStep extends StepBaseContext = StepBaseContext
-> = {
+type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	id: string;
-	handler: (context: WorkflowContext<TInput, TStep>) => Promise<unknown>;
+	/** Widest context avoids contravariance when collecting definitions; `workflow()` still types the handler narrowly. */
+	handler: (context: WorkflowContext<InputParameters, StepBaseContext>) => Promise<unknown>;
 	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
@@ -127,10 +126,7 @@ type StepInternalDefinition = {
 	loop: boolean;
 	isDynamic: boolean;
 };
-type WorkflowInternalDefinition<
-	TInput extends InputParameters = InputParameters,
-	TStep extends StepBaseContext = StepBaseContext
-> = WorkflowDefinition<TInput, TStep> & {
+type WorkflowInternalDefinition<TInput extends InputParameters = InputParameters> = WorkflowDefinition<TInput> & {
 	steps: StepInternalDefinition[];
 };
 /**
@@ -138,7 +134,7 @@ type WorkflowInternalDefinition<
 * TStepExt is the accumulated step extension from all plugins (step = StepContext & TStepExt).
 */
 interface WorkflowFactory<TStepExt = object> {
-	(id: string, handler: (context: WorkflowContext<InputParameters, StepBaseContext & TStepExt>) => Promise<unknown>, options?: WorkflowOptions<InputParameters>): WorkflowDefinition<InputParameters, StepBaseContext & TStepExt>;
+	<I extends InputParameters = InputParameters>(id: string, handler: (context: WorkflowContext<I, StepBaseContext & TStepExt>) => Promise<unknown>, options?: WorkflowOptions<I>): WorkflowDefinition<I>;
 	use<TNewExt>(plugin: WorkflowPlugin<StepBaseContext & TStepExt, TNewExt>): WorkflowFactory<TStepExt & TNewExt>;
 }
 type WorkflowRunProgress = WorkflowRun & {
@@ -186,13 +182,14 @@ declare class WorkflowEngine {
 		batchSize?: number;
 	}): Promise<void>;
 	stop(): Promise<void>;
-	registerWorkflow<TStep extends StepBaseContext>(definition: WorkflowDefinition<InputParameters, TStep>): Promise<WorkflowEngine>;
+	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
-	startWorkflow({ resourceId, workflowId, input, options }: {
+	startWorkflow({ resourceId, workflowId, input, idempotencyKey, options }: {
 		resourceId?: string;
 		workflowId: string;
 		input: unknown;
+		idempotencyKey?: string;
 		options?: {
 			timeout?: number;
 			retries?: number;
@@ -278,11 +275,13 @@ declare class WorkflowEngine {
 		hasPrev: boolean;
 	}>;
 }
+import { StandardSchemaV1 as StandardSchemaV12 } from "@standard-schema/spec";
 declare class WorkflowEngineError extends Error {
 	readonly workflowId?: string | undefined;
 	readonly runId?: string | undefined;
 	readonly cause: Error | undefined;
-	constructor(message: string, workflowId?: string | undefined, runId?: string | undefined, cause?: Error | undefined);
+	readonly issues?: StandardSchemaV12.FailureResult["issues"] | undefined;
+	constructor(message: string, workflowId?: string | undefined, runId?: string | undefined, cause?: Error | undefined, issues?: StandardSchemaV12.FailureResult["issues"] | undefined);
 }
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);