octaflow 0.15.0 → 0.16.0

package/README.md

@@ -9,7 +9,8 @@
 **Durable workflows for TypeScript that run on the Postgres you already have.**
 
 Declare a DAG of Zod-typed steps. The engine runs each step as soon as its dependencies
-complete, persists every transition, retries failures, and resumes after a crash. There is
+complete, persists every transition, retries failures, and picks up where it left off after a
+restart. There is
 no workflow server to operate, no control plane, and no vendor — it's a library you import,
 not a platform you adopt.
 
@@ -241,7 +242,8 @@ Full docs — concepts, every feature, production wiring and the API reference
 | [Fan-out & map](https://octabits-io.github.io/octaflow/core/fan-out-and-map/) | one child step per item of a runtime list |
 | [Signals](https://octabits-io.github.io/octaflow/core/signals/) · [Sub-workflows](https://octabits-io.github.io/octaflow/core/sub-workflows/) · [Saga](https://octabits-io.github.io/octaflow/core/saga-compensation/) | suspend, nest, and roll back |
 | [Postgres & pg-boss](https://octabits-io.github.io/octaflow/running/postgres-and-pg-boss/) | production wiring, workers, DLQ, cron |
-| [Observability](https://octabits-io.github.io/octaflow/running/observability/) | lifecycle events and spans |
+| [Cancellation & recovery](https://octabits-io.github.io/octaflow/running/cancellation-and-recovery/) | cancelling a run, and sweeping steps a crash left behind |
+| [Observability](https://octabits-io.github.io/octaflow/running/observability/) · [Live progress](https://octabits-io.github.io/octaflow/running/live-progress/) | lifecycle events, spans, and streaming them to a browser |
 | [The AI add-on](https://octabits-io.github.io/octaflow/extending/ai/) | token/cost capture, quota, usage rollups |
 | [Extending](https://octabits-io.github.io/octaflow/extending/interfaces/) | custom stores, dispatchers and gates |
 | [API reference](https://octabits-io.github.io/octaflow/reference/api/) | every export, by entry point |
@@ -267,6 +269,7 @@ Runnable, focused examples live in [`examples/`](./examples) — see [`examples/
 | 11 | `11-observability.ts` | observer events + tracer spans |
 | 12 | `12-postgres-pgboss-production.ts` | full pg store + gate + event sink + pg-boss + cron |
 | 13 | `13-ai-workflow.ts` | AI add-on (instrumented model + cost) |
+| 14 | `14-live-progress.ts` | `FlowObserver` → SSE fan-out (build your own dashboard) |
 
 The in-memory examples (01–11) share a small driver, [`examples/runtime.ts`](./examples/runtime.ts),
 that builds an engine over the in-memory store and an in-process queue you drain.

package/dist/dispatcher-pgboss/index.d.ts

@@ -29,8 +29,15 @@ declare const DEFAULT_STEP_QUEUE_CONFIG: Required<StepQueueConfig>;
 /**
  * The wire payload for a scheduled (or ad-hoc) workflow **start**. Carries the
  * partition plus what `engine.startWorkflow` needs; the host resolves `workflowType`
- * to a definition. `idempotencyKey` is forwarded to the start so overlapping
- * cron ticks don't double-start.
+ * to a definition.
+ *
+ * Two mutually exclusive ways to ask for start idempotency, because a cron schedule
+ * stores its payload **once** and pg-boss redelivers that same payload on every tick:
+ *
+ * - `idempotencyKeyPrefix` — the usual choice. The start worker appends the job id,
+ *   so each tick gets a distinct key while a redelivery of the *same* tick reuses it.
+ * - `idempotencyKey` — used verbatim. On a schedule this means "start exactly one
+ *   workflow, ever"; every later tick returns the first one.
  */
 declare const WIRE_START_PAYLOAD_SCHEMA: z.ZodObject<{
   partitionKey: z.ZodString;
@@ -38,8 +45,22 @@ declare const WIRE_START_PAYLOAD_SCHEMA: z.ZodObject<{
   input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   entityRef: z.ZodOptional<z.ZodString>;
   idempotencyKey: z.ZodOptional<z.ZodString>;
+  idempotencyKeyPrefix: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type WireStartPayload = z.infer<typeof WIRE_START_PAYLOAD_SCHEMA>;
+/**
+ * What a {@link WireStartPayload} becomes at delivery time: the same fields, plus the
+ * pg-boss job id and the **resolved** `idempotencyKey` to hand `engine.startWorkflow`.
+ *
+ * `idempotencyKey` is verbatim when the payload set one, `${idempotencyKeyPrefix}:${jobId}`
+ * when it set a prefix, and `undefined` when it set neither.
+ */
+interface StartJobContext extends WireStartPayload {
+  /** pg-boss job id — unique per cron tick, stable across that job's retries. */
+  jobId: string;
+}
+/** Resolve the per-delivery idempotency key. Explicit key wins over a prefix. */
+declare function resolveStartIdempotencyKey(payload: WireStartPayload, jobId: string): string | undefined;
 //#endregion
 //#region src/dispatcher-pgboss/queue.d.ts
 /**
@@ -136,7 +157,20 @@ interface ScheduleStartInput {
   workflowType: string;
   input?: Record<string, unknown>;
   entityRef?: string;
-  /** Forwarded to the start so overlapping ticks don't double-start. */
+  /**
+   * Per-tick start idempotency. The start worker resolves this to
+   * `${idempotencyKeyPrefix}:${jobId}`, so each cron tick gets a distinct key while a
+   * redelivery of the same tick reuses it — the usual thing you want on a schedule.
+   */
+  idempotencyKeyPrefix?: string;
+  /**
+   * Verbatim start idempotency key.
+   *
+   * A schedule stores its payload **once**, so this same key rides every tick — and
+   * start keys never expire. On a cron schedule that means **exactly one workflow,
+   * ever**; every later tick returns the first one. That is occasionally what you
+   * want ("run this once and never again"); if it isn't, use `idempotencyKeyPrefix`.
+   */
   idempotencyKey?: string;
   /** Optional IANA time zone (default UTC). */
   tz?: string;
@@ -150,8 +184,20 @@ declare function createPgBossScheduler(deps: PgBossSchedulerDeps): {
   /** List the schedules registered on this queue. */
   list(): Promise<import("pg-boss").Schedule[]>;
 };
-/** Invoked for each start job — typically resolves the type and calls `engine.startWorkflow`. */
-type StartJobProcessor = (payload: WireStartPayload) => Promise<void>;
+/**
+ * Invoked for each start job — typically resolves the type and calls `engine.startWorkflow`.
+ *
+ * The context's `idempotencyKey` is already resolved for **this delivery** (see
+ * {@link resolveStartIdempotencyKey}), so forwarding it is the right default:
+ *
+ * ```ts
+ * await starter.start(async (job) => {
+ *   const wf = workflowsByType[job.workflowType];
+ *   await engine.startWorkflow(wf.definition, job.input, { idempotencyKey: job.idempotencyKey });
+ * });
+ * ```
+ */
+type StartJobProcessor = (payload: StartJobContext) => Promise<void>;
 interface PgBossStartWorkerDeps {
   boss: PgBoss;
   queueName: string;
@@ -167,4 +213,4 @@ declare function createPgBossStartWorker(deps: PgBossStartWorkerDeps): {
   stop: () => Promise<void>;
 };
 //#endregion
-export { DEFAULT_STEP_QUEUE_CONFIG, DlqProcessor, PgBossDispatcherDeps, PgBossDlqWorkerDeps, PgBossSchedulerDeps, PgBossStartWorkerDeps, PgBossStepWorkerDeps, PgBossStepWorkerOptions, ScheduleStartInput, StartJobProcessor, StepJobProcessor, StepQueueConfig, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, WireStartPayload, WireStepPayload, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue };
+export { DEFAULT_STEP_QUEUE_CONFIG, DlqProcessor, PgBossDispatcherDeps, PgBossDlqWorkerDeps, PgBossSchedulerDeps, PgBossStartWorkerDeps, PgBossStepWorkerDeps, PgBossStepWorkerOptions, ScheduleStartInput, StartJobContext, StartJobProcessor, StepJobProcessor, StepQueueConfig, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, WireStartPayload, WireStepPayload, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue, resolveStartIdempotencyKey };

package/dist/dispatcher-pgboss/index.js

@@ -20,16 +20,31 @@ const DEFAULT_STEP_QUEUE_CONFIG = {
 /**
 * The wire payload for a scheduled (or ad-hoc) workflow **start**. Carries the
 * partition plus what `engine.startWorkflow` needs; the host resolves `workflowType`
-* to a definition. `idempotencyKey` is forwarded to the start so overlapping
-* cron ticks don't double-start.
+* to a definition.
+*
+* Two mutually exclusive ways to ask for start idempotency, because a cron schedule
+* stores its payload **once** and pg-boss redelivers that same payload on every tick:
+*
+* - `idempotencyKeyPrefix` — the usual choice. The start worker appends the job id,
+*   so each tick gets a distinct key while a redelivery of the *same* tick reuses it.
+* - `idempotencyKey` — used verbatim. On a schedule this means "start exactly one
+*   workflow, ever"; every later tick returns the first one.
 */
 const WIRE_START_PAYLOAD_SCHEMA = z.object({
 	partitionKey: z.string().min(1),
 	workflowType: z.string().min(1),
 	input: z.record(z.string(), z.unknown()).default({}),
 	entityRef: z.string().optional(),
-	idempotencyKey: z.string().optional()
+	/** Verbatim dedup key — collapses *every* delivery, including future cron ticks. */
+	idempotencyKey: z.string().optional(),
+	/** Per-tick dedup: the start worker resolves this to `${prefix}:${jobId}`. */
+	idempotencyKeyPrefix: z.string().optional()
 });
+/** Resolve the per-delivery idempotency key. Explicit key wins over a prefix. */
+function resolveStartIdempotencyKey(payload, jobId) {
+	if (payload.idempotencyKey !== void 0) return payload.idempotencyKey;
+	if (payload.idempotencyKeyPrefix !== void 0) return `${payload.idempotencyKeyPrefix}:${jobId}`;
+}
 //#endregion
 //#region src/dispatcher-pgboss/queue.ts
 function dlqName(queueName) {
@@ -275,7 +290,8 @@ function createPgBossScheduler(deps) {
 				workflowType: input.workflowType,
 				input: input.input ?? {},
 				entityRef: input.entityRef,
-				idempotencyKey: input.idempotencyKey
+				idempotencyKey: input.idempotencyKey,
+				idempotencyKeyPrefix: input.idempotencyKeyPrefix
 			};
 			await boss.schedule(queueName, input.cron, payload, {
 				key: input.key,
@@ -309,7 +325,11 @@ function createPgBossStartWorker(deps) {
 					logger?.error("Invalid start payload", void 0, { jobId: job.id });
 					continue;
 				}
-				await process(parsed.data);
+				await process({
+					...parsed.data,
+					jobId: job.id,
+					idempotencyKey: resolveStartIdempotencyKey(parsed.data, job.id)
+				});
 			}
 		});
 	}
@@ -325,4 +345,4 @@ function createPgBossStartWorker(deps) {
 	};
 }
 //#endregion
-export { DEFAULT_STEP_QUEUE_CONFIG, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue };
+export { DEFAULT_STEP_QUEUE_CONFIG, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue, resolveStartIdempotencyKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Durable DAG workflow engine: Zod-typed steps over Postgres + pg-boss, with an optional AI add-on (token/cost/quota). Layered single package.",
   "license": "MIT",
   "type": "module",