octaflow 0.26.0 → 0.28.0

package/README.md

@@ -200,8 +200,10 @@ next to what your steps actually do.
 | 🔁 | **Retry & timeout** — per-step `maxAttempts`, fixed/exponential backoff, wall-clock timeout |
 | 💤 | **Durable sleep** — hold a step in the queue for N ms (survives restarts) |
 | 🔀 | **Conditional branching** — `when` guards skip a step and its branch; `join: 'any'` converges |
+| 🎯 | **Decisions** — typed choices with a confidence from a swappable decider (a function, a model, your own); below a threshold a person settles it |
 | ⏳ | **Deadlines** — a budget on a suspended step (fail, or continue with a stand-in answer) and on a whole run |
 | ♻️ | **Retry a failed run** — `retryWorkflow` resumes from the failure point; completed steps keep their output |
+| 🧹 | **Delete the runs about a record** — `purgeWorkflows({ entityRef })` cancels and deletes them with their sub-workflow runs and steps, for an erasure or a deleted record; refuses only while a step is executing |
 | 🚦 | **Concurrency & rate limiting** — per-step-type caps and token buckets via a pluggable gate |
 | ⏰ | **Cron / scheduled starts** — fire workflows on a schedule (pg-boss) |
 | 🔑 | **Start idempotency** — a dedup key collapses double-clicks / overlapping ticks |
@@ -321,11 +323,12 @@ Full docs — concepts, every feature, production wiring and the API reference
 | [Retry & timeout](https://octaflow.octabits.io/core/retry-and-timeout/) | attempt budgets, backoff, and how a failure is classified |
 | [Fan-out & map](https://octaflow.octabits.io/core/fan-out-and-map/) | one child step per item of a runtime list |
 | [Branching](https://octaflow.octabits.io/core/branching/) | `when` guards and join rules — if/else over a static DAG |
+| [Decisions](https://octaflow.octabits.io/core/decisions/) | typed choices with a confidence, a swappable decider, a person below the threshold |
 | [Signals](https://octaflow.octabits.io/core/signals/) · [Sub-workflows](https://octaflow.octabits.io/core/sub-workflows/) · [Saga](https://octaflow.octabits.io/core/saga-compensation/) | suspend, nest, and roll back |
 | [Deadlines](https://octaflow.octabits.io/core/deadlines/) | budgets for a suspended step and for a whole run |
 | [Heartbeats](https://octaflow.octabits.io/core/heartbeats/) | liveness for long steps, and interrupting one that was cancelled |
 | [Postgres & pg-boss](https://octaflow.octabits.io/running/postgres-and-pg-boss/) | production wiring, workers, DLQ, cron |
-| [Cancellation & recovery](https://octaflow.octabits.io/running/cancellation-and-recovery/) | cancelling a run, sweeping steps a crash left behind, and retrying a failed run |
+| [Cancellation & recovery](https://octaflow.octabits.io/running/cancellation-and-recovery/) | cancelling a run, sweeping steps a crash left behind, retrying a failed run, and deleting the runs about a record |
 | [Observability](https://octaflow.octabits.io/running/observability/) · [Live progress](https://octaflow.octabits.io/running/live-progress/) | lifecycle events, spans, and streaming them to a browser |
 | [The AI add-on](https://octaflow.octabits.io/extending/ai/) | token/cost capture, quota, usage rollups |
 | [Extending](https://octaflow.octabits.io/extending/interfaces/) | custom stores, dispatchers and gates |
@@ -355,8 +358,9 @@ Runnable, focused examples live in [`examples/`](./examples) — see [`examples/
 | 14 | `14-live-progress.ts` | `FlowObserver` → SSE fan-out (build your own dashboard) |
 | 15 | `15-conditional-branching.ts` | `when` guards + a `join: 'any'` convergence |
 | 16 | `16-deadlines-and-retry.ts` | wait deadlines, run deadlines, `retryWorkflow`, heartbeats |
+| 17 | `17-decisions.ts` | a decision step, a review below the threshold, branches on the outcome |
 
-The in-memory examples (01–11, 14–16) share a small driver, [`examples/runtime.ts`](./examples/runtime.ts),
+The in-memory examples (01–11, 14–17) 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/ai/index.d.ts

@@ -1,6 +1,6 @@
-import { E as RetryPolicy, g as TypedWorkflow, h as TypedStepContext, m as TypedStep, nt as Result, tt as FlowErrorShape } from "../index-BURAYZui.js";
+import { A as TypedStep, H as RetryPolicy, M as TypedWorkflow, f as Decider, j as TypedStepContext, vt as FlowErrorShape, yt as Result } from "../index-B8SvtiYn.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-BdxIcc92.js";
+import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-BV-Vany9.js";
 import { C as isSubprocessorResidency, S as embeddingDimensionsFor, _ as EmbeddingProviderMeta, a as AiProcessingRegion, b as OpenAiCompatibleProviderId, c as AiProviderModelOption, d as AiVendorResidency, f as DEFAULT_AI_PROVIDER, g as EmbeddingProviderId, h as EMBEDDING_PROVIDER_IDS, i as AiEndpointResidency, l as AiResidencyError, m as EMBEDDING_PROVIDERS, n as AI_PROVIDER_IDS, o as AiProviderId, p as DEFAULT_EMBEDDING_PROVIDER, r as AiEndpointRegion, s as AiProviderMeta, t as AI_PROVIDERS, u as AiResidencyResult, v as OPENAI_COMPATIBLE_PROVIDER, w as resolveEndpointResidency, x as OpenAiCompatibleProviderMeta, y as OPENAI_COMPATIBLE_PROVIDER_ID } from "../provider-registry-BvXBqJDR.js";
 import { z } from "zod";
 import { EmbeddingModelV4, LanguageModelV4, SharedV4ProviderMetadata } from "@ai-sdk/provider";
@@ -148,6 +148,31 @@ export declare function buildAiWorkflow<TInput extends Record<string, unknown>,
   steps: TSteps;
 }): TypedWorkflow<TInput, AiContext<THost>>;
 //#endregion
+//#region src/ai/model-decider.d.ts
+export interface ModelDeciderOptions {
+  /**
+   * The model to ask. Omitted: the step's `ctx.context.model`, which the AI
+   * hooks instrument for token usage and cost. Pass a model wrapped by your
+   * disclosure gate either way — the decision input leaves the process.
+   */
+  model?: LanguageModelV4;
+  /** Recorded on every decision. Default `model:<modelId>` of the model that ran. */
+  id?: string;
+  /** Prepended to the request's own instructions. */
+  system?: string;
+  /** Passed to the AI SDK. Default 0 — the step's retry policy owns retries. */
+  maxRetries?: number;
+}
+/**
+ * A decider over a language model with structured output: the options become
+ * an enum the model must choose from, and the model states its confidence.
+ *
+ * `calibrated` is `false` — a language model's stated confidence is not a
+ * probability you can set a threshold against with any precision. Treat its
+ * threshold as a policy knob and check it against what reviewers overrule.
+ */
+export declare function createModelDecider<THost = unknown>(options?: ModelDeciderOptions): Decider<AiContext<THost>>;
+//#endregion
 //#region src/ai/hooks.d.ts
 export interface AiModelResolver<THost = unknown> {
   /** Resolve the base (uninstrumented) model for a step. */

package/dist/ai/index.js

@@ -1,7 +1,8 @@
-import { S as ok, b as noopLogger, f as defineStep, l as buildWorkflow, x as err } from "../core-DNWPwFaE.js";
+import { D as ok, E as err, T as noopLogger, _ as defineStep, m as buildWorkflow } from "../core-C9h3-KFr.js";
 import { a as readRefusalDetails, i as isAiRefusalError, n as REFUSAL_FINISH_REASON, r as createRefusalAwareModel, t as AiRefusalError } from "../refusal-BsL2HPDb.js";
 import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, i as DEFAULT_EMBEDDING_PROVIDER, l as embeddingDimensionsFor, n as AI_PROVIDER_IDS, o as EMBEDDING_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, s as OPENAI_COMPATIBLE_PROVIDER, t as AI_PROVIDERS, u as isSubprocessorResidency } from "../provider-registry-BRwjC6_3.js";
-import { wrapEmbeddingModel, wrapLanguageModel } from "ai";
+import { z } from "zod";
+import { Output, generateText, wrapEmbeddingModel, wrapLanguageModel } from "ai";
 //#region src/ai/instrumented-model.ts
 function createUsageAccumulator() {
 	const total = {
@@ -318,6 +319,53 @@ function buildAiWorkflow(config) {
 	return buildWorkflow(config);
 }
 //#endregion
+//#region src/ai/model-decider.ts
+const DEFAULT_SYSTEM = [
+	"You classify the input by answering each question with exactly one of its options.",
+	"For each answer give a confidence between 0 and 1: the probability that the option is right.",
+	"Use a low confidence when the input is ambiguous or the options do not fit it well. Keep reasons to one sentence."
+].join(" ");
+function responseSchema(questions) {
+	return z.object(Object.fromEntries(Object.entries(questions).map(([key, options]) => [key, z.object({
+		choice: z.enum(options),
+		confidence: z.number().min(0).max(1),
+		reason: z.string()
+	})])));
+}
+function prompt(request) {
+	return `Questions:\n${Object.entries(request.questions).map(([key, options]) => `- ${key}: ${options.join(" | ")}`).join("\n")}\n\nInput:\n${JSON.stringify(request.input, null, 2)}`;
+}
+/**
+* A decider over a language model with structured output: the options become
+* an enum the model must choose from, and the model states its confidence.
+*
+* `calibrated` is `false` — a language model's stated confidence is not a
+* probability you can set a threshold against with any precision. Treat its
+* threshold as a policy knob and check it against what reviewers overrule.
+*/
+function createModelDecider(options = {}) {
+	return {
+		id: options.id ?? (options.model ? `model:${options.model.modelId}` : "model"),
+		calibrated: false,
+		async decide(request, context) {
+			const model = options.model ?? context.model;
+			const system = [options.system ?? DEFAULT_SYSTEM, request.instructions].filter(Boolean).join("\n\n");
+			const { output } = await generateText({
+				model,
+				system,
+				prompt: prompt(request),
+				output: Output.object({ schema: responseSchema(request.questions) }),
+				maxRetries: options.maxRetries ?? 0,
+				abortSignal: request.signal
+			});
+			return {
+				answers: output,
+				decider: options.id ?? `model:${model.modelId}`
+			};
+		}
+	};
+}
+//#endregion
 //#region src/ai/hooks.ts
 /**
 * Wire the AI behaviors (model instrumentation, token/cost capture, quota,
@@ -662,4 +710,4 @@ function thinkingSettingsFor(providerId, modelId, opts) {
 	return { temperature: opts.temperature };
 }
 //#endregion
-export { AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_PRICING, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, REFUSAL_FINISH_REASON, ZERO_MODEL_PRICING, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createRefusalAwareModel, createUsageAccumulator, defineAiStep, embeddingDimensionsFor, estimateCostMicros, isAiRefusalError, isSubprocessorResidency, readRefusalDetails, resolveEndpointResidency, supportsAdaptiveThinking, supportsToolSearch, thinkingSettingsFor };
+export { AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_PRICING, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, REFUSAL_FINISH_REASON, ZERO_MODEL_PRICING, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createModelDecider, createRefusalAwareModel, createUsageAccumulator, defineAiStep, embeddingDimensionsFor, estimateCostMicros, isAiRefusalError, isSubprocessorResidency, readRefusalDetails, resolveEndpointResidency, supportsAdaptiveThinking, supportsToolSearch, thinkingSettingsFor };

package/dist/{core-DNWPwFaE.js → core-C9h3-KFr.js}

@@ -515,6 +515,222 @@ function buildWorkflow(config) {
 	};
 }
 //#endregion
+//#region src/core/decision.ts
+/**
+* A decider over a plain function: every answer has confidence 1, so it never
+* asks for review. For rules you can state, and for tests.
+*/
+function functionDecider(id, decide) {
+	return {
+		id: `function:${id}`,
+		calibrated: true,
+		async decide(request, context) {
+			const choices = await decide(request, context);
+			return { answers: Object.fromEntries(Object.entries(choices).map(([key, choice]) => [key, {
+				choice,
+				confidence: 1
+			}])) };
+		}
+	};
+}
+function answerSchema(options) {
+	const option = z.enum(options);
+	return z.object({
+		choice: option,
+		confidence: z.number().min(0).max(1),
+		distribution: z.partialRecord(option, z.number().min(0).max(1)).optional(),
+		reason: z.string().optional()
+	});
+}
+function decisionOutputSchema(questions) {
+	const keys = Object.keys(questions);
+	return z.object({
+		answers: z.object(Object.fromEntries(Object.entries(questions).map(([key, options]) => [key, answerSchema(options)]))),
+		decider: z.string(),
+		calibrated: z.boolean(),
+		review: z.array(z.enum(keys))
+	});
+}
+function decisionReviewSchema(questions) {
+	return z.object({
+		answers: z.object(Object.fromEntries(Object.entries(questions).map(([key, options]) => [key, z.enum(options).optional()]))).strict(),
+		reviewer: z.string().optional()
+	});
+}
+function decisionOutcomeSchema(questions) {
+	const entries = Object.entries(questions);
+	return z.object({
+		choices: z.object(Object.fromEntries(entries.map(([key, options]) => [key, z.enum(options)]))),
+		decidedBy: z.object(Object.fromEntries(entries.map(([key]) => [key, z.enum(["decider", "person"])]))),
+		decider: z.string(),
+		reviewer: z.string().optional()
+	});
+}
+const emptyInputSchema = z.object({});
+/**
+* Hold a decider's response to the questions: every question answered, every
+* choice one of its options. A decider that breaks this is broken, not flaky —
+* the error is not retried.
+*/
+function checkResponse(type, questions, decider, response) {
+	const answers = {};
+	for (const [key, options] of Object.entries(questions)) {
+		const answer = response.answers[key];
+		if (!answer) throw nonRetryableError(`[${type}] decider '${decider}' gave no answer to '${key}'`);
+		if (!options.includes(answer.choice)) throw nonRetryableError(`[${type}] decider '${decider}' answered '${key}' with '${answer.choice}', not one of: ${options.join(", ")}`);
+		if (!(answer.confidence >= 0 && answer.confidence <= 1)) throw nonRetryableError(`[${type}] decider '${decider}' gave '${key}' a confidence of ${answer.confidence}, outside [0, 1]`);
+		answers[key] = answer;
+	}
+	return answers;
+}
+/**
+* Define a **decision** step: the decider answers each question with one of
+* its options and a confidence; the output is typed by the options and
+* validated against them, so a dependent can branch on it with a plain `when`.
+*
+* ```ts
+* const triage = defineDecisionStep({
+*   type: 'mail:triage',
+*   workflowInputSchema: input,
+*   dependencies: { parseMail },
+*   questions: {
+*     tone: ['aggressive', 'friendly'],
+*     audience: ['invoicing', 'customer-support', 'tech-support'],
+*   },
+*   input: (ctx) => ctx.deps.parseMail,
+*   decider: createModelDecider(),
+*   threshold: 0.8,
+* });
+* ```
+*
+* Questions under `threshold` land in `output.review`; pair the step with
+* {@link defineDecisionReviewStep} and {@link defineDecisionOutcomeStep} to have
+* a person settle them.
+*/
+function defineDecisionStep(config) {
+	const { type, questions, decider, threshold } = config;
+	const keys = Object.keys(questions);
+	if (keys.length === 0) throw new Error(`[${type}] a decision needs at least one question`);
+	for (const [key, options] of Object.entries(questions)) if (new Set(options).size !== options.length) throw new Error(`[${type}] question '${key}' repeats an option`);
+	const thresholdOf = (key) => typeof threshold === "number" ? threshold : threshold?.[key];
+	return {
+		...defineStep({
+			type,
+			workflowInputSchema: config.workflowInputSchema,
+			outputSchema: decisionOutputSchema(questions),
+			dependencies: config.dependencies,
+			when: config.when,
+			join: config.join,
+			retry: config.retry,
+			isRetryable: config.isRetryable,
+			timeoutMs: config.timeoutMs,
+			handler: async (ctx) => {
+				const response = await decider.decide({
+					questions,
+					input: await config.input(ctx),
+					instructions: config.instructions,
+					signal: ctx.signal
+				}, ctx.context);
+				const deciderId = response.decider ?? decider.id;
+				const answers = checkResponse(type, questions, deciderId, response);
+				const review = keys.filter((key) => {
+					const t = thresholdOf(key);
+					return t !== void 0 && answers[key].confidence < t;
+				});
+				return {
+					answers,
+					decider: deciderId,
+					calibrated: decider.calibrated,
+					review
+				};
+			}
+		}),
+		questions
+	};
+}
+/** The single entry of a one-step dependency map, or a definition-time error. */
+function soleEntry(type, role, map) {
+	const entries = Object.entries(map);
+	if (entries.length !== 1) throw new Error(`[${type}] '${role}' takes exactly one step, keyed by its step key — got ${entries.length}`);
+	return entries[0];
+}
+/**
+* Define the **review** of a decision: a wait step that suspends only when the
+* decision flagged a question, until `engine.resumeStep` delivers a
+* {@link DecisionReview} — the options a person chose. When nothing was
+* flagged the step is skipped.
+*
+* `onTimeout: 'accept'` settles an expired review by keeping the decider's
+* answers; the default `'fail'` ends the run.
+*/
+function defineDecisionReviewStep(config) {
+	const [key, decision] = soleEntry(config.type, "decision", config.decision);
+	return defineStep({
+		type: config.type,
+		workflowInputSchema: emptyInputSchema,
+		outputSchema: decisionReviewSchema(decision.questions),
+		dependencies: config.decision,
+		waitForEvent: true,
+		timeoutMs: config.timeoutMs,
+		onTimeout: config.onTimeout === "accept" ? { output: { answers: {} } } : "fail",
+		when: (ctx) => ctx.deps[key].review.length > 0,
+		handler: async () => ({ answers: {} })
+	});
+}
+/**
+* Merge a decision with its review: a person's choice wins where they made
+* one, the decider's stands everywhere else. Also what
+* {@link defineDecisionOutcomeStep} runs.
+*/
+function resolveDecision(decision, review) {
+	const choices = {};
+	const decidedBy = {};
+	for (const [key, answer] of Object.entries(decision.answers)) {
+		const chosen = (review?.answers)?.[key];
+		choices[key] = chosen ?? answer.choice;
+		decidedBy[key] = chosen === void 0 ? "decider" : "person";
+	}
+	return {
+		choices,
+		decidedBy,
+		decider: decision.decider,
+		...review?.reviewer !== void 0 ? { reviewer: review.reviewer } : {}
+	};
+}
+/**
+* Define the **outcome** of a decision: one step that waits for the review
+* when there is one, runs straight after the decision when there is not, and
+* outputs the settled {@link DecisionOutcome}. Branch on it downstream:
+*
+* ```ts
+* const invoicing = defineStep({
+*   dependencies: { outcome },
+*   when: (ctx) => ctx.deps.outcome.choices.audience === 'invoicing',
+*   // …
+* });
+* ```
+*/
+function defineDecisionOutcomeStep(config) {
+	const [decisionKey, decision] = soleEntry(config.type, "decision", config.decision);
+	const [reviewKey] = soleEntry(config.type, "review", config.review);
+	return defineStep({
+		type: config.type,
+		workflowInputSchema: emptyInputSchema,
+		outputSchema: decisionOutcomeSchema(decision.questions),
+		dependencies: {
+			...config.decision,
+			...config.review
+		},
+		join: "any",
+		handler: async (ctx) => {
+			const deps = ctx.deps;
+			const decided = deps[decisionKey];
+			if (!decided) throw nonRetryableError(`[${config.type}] decision '${decisionKey}' has no output`);
+			return resolveDecision(decided, deps[reviewKey]);
+		}
+	});
+}
+//#endregion
 //#region src/core/public-view.ts
 /**
 * Public wire view of a workflow — the projection every HTTP consumer was
@@ -653,4 +869,4 @@ function toPublicWorkflow(workflow) {
 	};
 }
 //#endregion
-export { ok as S, markRetryable as _, WORKFLOW_STATUS_SCHEMA as a, noopLogger as b, toPublicWorkflow as c, defineSleepStep as d, defineStep as f, isRetryableError as g, explicitRetryability as h, STEP_DISPLAY_STATUS_SCHEMA as i, buildWorkflow as l, defineWaitStep as m, PUBLIC_WORKFLOW_STEP_SCHEMA as n, toDisplayStepStatus as o, defineSubWorkflowStep as p, STEP_DISPLAY_STATUS as r, toPublicStep as s, PUBLIC_WORKFLOW_SCHEMA as t, defineMapStep as u, nonRetryableError as v, err as x, retryableError as y };
+export { nonRetryableError as C, ok as D, err as E, markRetryable as S, noopLogger as T, defineStep as _, WORKFLOW_STATUS_SCHEMA as a, explicitRetryability as b, toPublicWorkflow as c, defineDecisionStep as d, functionDecider as f, defineSleepStep as g, defineMapStep as h, STEP_DISPLAY_STATUS_SCHEMA as i, defineDecisionOutcomeStep as l, buildWorkflow as m, PUBLIC_WORKFLOW_STEP_SCHEMA as n, toDisplayStepStatus as o, resolveDecision as p, STEP_DISPLAY_STATUS as r, toPublicStep as s, PUBLIC_WORKFLOW_SCHEMA as t, defineDecisionReviewStep as u, defineSubWorkflowStep as v, retryableError as w, isRetryableError as x, defineWaitStep as y };

package/dist/{dispatcher-g7Ct0J6w.d.ts → dispatcher-B4haXU4w.d.ts}

@@ -1,4 +1,4 @@
-import { L as StepId, W as WorkflowId, nt as Result, tt as FlowErrorShape } from "./index-BURAYZui.js";
+import { $ as StepId, ot as WorkflowId, vt as FlowErrorShape, yt as Result } from "./index-B8SvtiYn.js";
 //#region src/core/dispatcher.d.ts
 /**
  * What a step job is for. A queue carries two kinds of work for a step, and

package/dist/{hooks-BdxIcc92.d.ts → hooks-BV-Vany9.d.ts}

@@ -1,4 +1,4 @@
-import { D as StartOptions, L as StepId, R as StepRecord, U as WorkflowDefinition, W as WorkflowId, nt as Result, q as WorkflowRecord, tt as FlowErrorShape } from "./index-BURAYZui.js";
+import { $ as StepId, U as StartOptions, at as WorkflowDefinition, et as StepRecord, lt as WorkflowRecord, ot as WorkflowId, vt as FlowErrorShape, yt as Result } from "./index-B8SvtiYn.js";
 //#region src/core/hooks.d.ts
 interface BeforeStartArgs {
   definition: WorkflowDefinition;

package/dist/{index-BURAYZui.d.ts → index-B8SvtiYn.d.ts}

@@ -373,12 +373,25 @@ interface WorkflowNotRetryableError extends FlowErrorShape {
   key: 'workflow_not_retryable';
   status: WorkflowStatus;
 }
+/**
+ * `purgeWorkflows` refused: a step of one of the runs is executing right now (a worker
+ * holds it, or a compensation handler is running). Nothing was cancelled or deleted.
+ */
+interface WorkflowStepRunningError extends FlowErrorShape {
+  key: 'workflow_step_running';
+  /** The steps that are executing, by run. */
+  running: Array<{
+    workflowId: WorkflowId;
+    stepKey: string;
+    status: StepStatus;
+  }>;
+}
 /**
  * Engine error type. The named members cover flow-core's own failures; the
  * bare `FlowErrorShape` arm lets hooks (e.g. an AI quota guard in `onBeforeStart`)
  * reject a start with a domain-specific error key the engine just passes through.
  */
-type FlowError = WorkflowNotFoundError | InvalidWorkflowDefinitionError | StepHandlerNotFoundError | WorkflowNotRetryableError | StepError | FlowErrorShape;
+type FlowError = WorkflowNotFoundError | InvalidWorkflowDefinitionError | StepHandlerNotFoundError | WorkflowNotRetryableError | WorkflowStepRunningError | StepError | FlowErrorShape;
 //#endregion
 //#region src/core/defineStep.d.ts
 /**
@@ -695,6 +708,176 @@ interface BuildWorkflowConfig<TInput extends Record<string, unknown>, TSteps ext
  */
 declare function buildWorkflow<TInput extends Record<string, unknown>, TContext = unknown, TSteps extends Record<string, TypedStep<any, any, any, TContext>> = {}>(config: BuildWorkflowConfig<TInput, TSteps, TContext>): TypedWorkflow<TInput, TContext>;
 //#endregion
+//#region src/core/decision.d.ts
+/** The questions a decision answers: each key names a question, each value its options. */
+type DecisionQuestions = Readonly<Record<string, readonly [string, ...string[]]>>;
+/** One answer: the chosen option, how sure the decider is, and optionally why. */
+interface DecisionAnswer<TOption extends string = string> {
+  choice: TOption;
+  /** Probability in [0, 1] that `choice` is right. Only meaningful as a probability when the decider is `calibrated`. */
+  confidence: number;
+  /** The probability per option, where the decider gives one. */
+  distribution?: Partial<Record<TOption, number>>;
+  /** A short reason, where the decider gives one — shown to a reviewer, never parsed. */
+  reason?: string;
+}
+/** The answers to a set of questions, typed by their options. */
+type DecisionAnswers<Q extends DecisionQuestions> = { [K in keyof Q]: DecisionAnswer<Q[K][number]>; };
+/** The chosen option per question. */
+type DecisionChoices<Q extends DecisionQuestions> = { [K in keyof Q]: Q[K][number]; };
+/** What a decider is asked. */
+interface DecisionRequest {
+  questions: DecisionQuestions;
+  /** The state to decide on — a data structure, not a prompt. */
+  input: unknown;
+  /** Optional guidance for the decider; a function decider may ignore it. */
+  instructions?: string;
+  signal?: AbortSignal;
+}
+/** What a decider answers: one answer per question. */
+interface DecisionResponse {
+  answers: Record<string, DecisionAnswer>;
+  /** Overrides the decider's `id` for this answer — e.g. the model that actually ran. */
+  decider?: string;
+}
+/**
+ * Anything that can answer a decision. `calibrated` is the decider's claim
+ * that its confidences are probabilities — true for a deterministic function
+ * (always 1) or a model trained for it, false for a language model asked to
+ * state its own confidence. The step records it on every output, so a reader
+ * of the run knows how much a threshold meant.
+ */
+interface Decider<TContext = unknown> {
+  /** Recorded on every output — e.g. `function:rules` or `model:mistral-large`. */
+  readonly id: string;
+  readonly calibrated: boolean;
+  decide(request: DecisionRequest, context: TContext): Promise<DecisionResponse>;
+}
+/**
+ * A decider over a plain function: every answer has confidence 1, so it never
+ * asks for review. For rules you can state, and for tests.
+ */
+declare function functionDecider<TContext = unknown>(id: string, decide: (request: DecisionRequest, context: TContext) => Record<string, string> | Promise<Record<string, string>>): Decider<TContext>;
+/** What a decision step outputs. */
+type DecisionOutput<Q extends DecisionQuestions> = {
+  answers: DecisionAnswers<Q>;
+  /** The decider's `id`. */
+  decider: string;
+  /** The decider's `calibrated` claim. */
+  calibrated: boolean;
+  /** The questions answered below their threshold — empty when none need a person. */
+  review: Array<keyof Q & string>;
+};
+/** A decision step: a `TypedStep` that also carries its questions, for the review and outcome steps. */
+type DecisionStep<Q extends DecisionQuestions, TInput extends Record<string, unknown> = Record<string, unknown>, TDeps extends Record<string, TypedStep<any, any, any, TContext>> = {}, TContext = unknown> = TypedStep<TInput, DecisionOutput<Q>, TDeps, TContext> & {
+  readonly questions: Q;
+};
+/** Reviewing a decision: the options a person chose, for any subset of its questions. */
+type DecisionReview<Q extends DecisionQuestions> = {
+  answers: Partial<DecisionChoices<Q>>;
+  /** Who reviewed — recorded on the outcome. */
+  reviewer?: string;
+};
+/** The settled decision: one option per question, and who chose it. */
+type DecisionOutcome<Q extends DecisionQuestions> = {
+  choices: DecisionChoices<Q>;
+  decidedBy: { [K in keyof Q]: 'decider' | 'person'; };
+  decider: string;
+  reviewer?: string;
+};
+interface DefineDecisionStepConfig<Q extends DecisionQuestions, TInput extends Record<string, unknown>, TContext, TDeps extends Record<string, TypedStep<any, any, any, TContext>>, TJoin extends JoinRule> {
+  type: string;
+  workflowInputSchema: z.ZodType<TInput>;
+  dependencies?: TDeps;
+  /** The questions, each with its options — write them inline so their literals are kept. */
+  questions: Q;
+  /** The state the decider sees, built from the validated input and dependencies. */
+  input: (ctx: TypedStepContext<TInput, TDeps, TContext, TJoin>) => unknown;
+  /** Guidance passed to the decider. */
+  instructions?: string;
+  decider: Decider<TContext>;
+  /**
+   * Below this confidence a question is flagged for review — one number for
+   * every question, or one per question (a question left out is never
+   * flagged). Omitted: nothing is flagged.
+   */
+  threshold?: number | Partial<Record<keyof Q, number>>;
+  /** Guard — see `defineStep`. */
+  when?: (ctx: TypedStepContext<TInput, TDeps, TContext, TJoin>) => boolean | Promise<boolean>;
+  /** Join rule — see `defineStep`. */
+  join?: TJoin;
+  retry?: RetryPolicy;
+  isRetryable?: (error: unknown) => boolean;
+  timeoutMs?: number;
+}
+/**
+ * Define a **decision** step: the decider answers each question with one of
+ * its options and a confidence; the output is typed by the options and
+ * validated against them, so a dependent can branch on it with a plain `when`.
+ *
+ * ```ts
+ * const triage = defineDecisionStep({
+ *   type: 'mail:triage',
+ *   workflowInputSchema: input,
+ *   dependencies: { parseMail },
+ *   questions: {
+ *     tone: ['aggressive', 'friendly'],
+ *     audience: ['invoicing', 'customer-support', 'tech-support'],
+ *   },
+ *   input: (ctx) => ctx.deps.parseMail,
+ *   decider: createModelDecider(),
+ *   threshold: 0.8,
+ * });
+ * ```
+ *
+ * Questions under `threshold` land in `output.review`; pair the step with
+ * {@link defineDecisionReviewStep} and {@link defineDecisionOutcomeStep} to have
+ * a person settle them.
+ */
+declare function defineDecisionStep<const Q extends DecisionQuestions, TInput extends Record<string, unknown>, TContext = unknown, TDeps extends Record<string, TypedStep<any, any, any, TContext>> = {}, TJoin extends JoinRule = 'all'>(config: DefineDecisionStepConfig<Q, TInput, TContext, TDeps, TJoin>): DecisionStep<Q, TInput, TDeps, TContext>;
+/**
+ * Define the **review** of a decision: a wait step that suspends only when the
+ * decision flagged a question, until `engine.resumeStep` delivers a
+ * {@link DecisionReview} — the options a person chose. When nothing was
+ * flagged the step is skipped.
+ *
+ * `onTimeout: 'accept'` settles an expired review by keeping the decider's
+ * answers; the default `'fail'` ends the run.
+ */
+declare function defineDecisionReviewStep<Q extends DecisionQuestions, TKey extends string, TContext = unknown>(config: {
+  type: string;
+  /** The decision under review, keyed by its step key: `{ triage }`. */
+  decision: { [K in TKey]: DecisionStep<Q, any, any, TContext>; };
+  timeoutMs?: number;
+  onTimeout?: 'fail' | 'accept';
+}): TypedStep<Record<string, never>, DecisionReview<Q>, { [K in TKey]: DecisionStep<Q, any, any, TContext>; }, TContext>;
+/**
+ * Merge a decision with its review: a person's choice wins where they made
+ * one, the decider's stands everywhere else. Also what
+ * {@link defineDecisionOutcomeStep} runs.
+ */
+declare function resolveDecision<Q extends DecisionQuestions>(decision: DecisionOutput<Q>, review?: DecisionReview<Q>): DecisionOutcome<Q>;
+/**
+ * Define the **outcome** of a decision: one step that waits for the review
+ * when there is one, runs straight after the decision when there is not, and
+ * outputs the settled {@link DecisionOutcome}. Branch on it downstream:
+ *
+ * ```ts
+ * const invoicing = defineStep({
+ *   dependencies: { outcome },
+ *   when: (ctx) => ctx.deps.outcome.choices.audience === 'invoicing',
+ *   // …
+ * });
+ * ```
+ */
+declare function defineDecisionOutcomeStep<Q extends DecisionQuestions, TDecisionKey extends string, TReviewKey extends string, TContext = unknown>(config: {
+  type: string;
+  /** The decision, keyed by its step key: `{ triage }`. */
+  decision: { [K in TDecisionKey]: DecisionStep<Q, any, any, TContext>; };
+  /** Its review, keyed by its step key: `{ triageReview }`. */
+  review: { [K in TReviewKey]: TypedStep<any, DecisionReview<Q>, any, TContext>; };
+}): TypedStep<Record<string, never>, DecisionOutcome<Q>, { [K in TDecisionKey]: DecisionStep<Q, any, any, TContext>; } & { [K in TReviewKey]: TypedStep<any, DecisionReview<Q>, any, TContext>; }, TContext>;
+//#endregion
 //#region src/core/public-view.d.ts
 /** The five states a UI renders. Suspensions display as in-flight. */
 type StepDisplayStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
@@ -823,4 +1006,4 @@ declare function toPublicStep(step: StepRecord): PublicWorkflowStep;
  */
 declare function toPublicWorkflow(workflow: WorkflowWithSteps): PublicWorkflow;
 //#endregion
-export { computeReadiness as $, StepConditionHandler as A, StepStatus as B, defineWaitStep as C, StartOptions as D, RetryPolicy as E, StepHandlerNotFoundError as F, WorkflowNotFoundError as G, WorkflowCreatedResult as H, StepHandlerRegistry as I, WorkflowStatus as J, WorkflowNotRetryableError as K, StepId as L, StepError as M, StepExecutionContext as N, StepCompensateHandler as O, StepHandler as P, ReadinessPlan as Q, StepRecord as R, defineSubWorkflowStep as S, InvalidWorkflowDefinitionError as T, WorkflowDefinition as U, WaitTimeoutPolicy as V, WorkflowId as W, JoinRule as X, WorkflowWithSteps as Y, PlannedSkip as Z, WorkflowOutput as _, STEP_DISPLAY_STATUS as a, defineSleepStep as b, WORKFLOW_STATUS_SCHEMA as c, toPublicWorkflow as d, isTerminalStepStatus as et, StepDeps as f, TypedWorkflow as g, TypedStepContext as h, PublicWorkflowStep as i, ok as it, StepDefinition as j, StepCompensationContext as k, toDisplayStepStatus as l, TypedStep as m, PUBLIC_WORKFLOW_STEP_SCHEMA as n, Result as nt, STEP_DISPLAY_STATUS_SCHEMA as o, StepOutput as p, WorkflowRecord as q, PublicWorkflow as r, err as rt, StepDisplayStatus as s, PUBLIC_WORKFLOW_SCHEMA as t, FlowErrorShape as tt, toPublicStep as u, buildWorkflow as v, FlowError as w, defineStep as x, defineMapStep as y, StepRegistration as z };
+export { StepId as $, TypedStep as A, FlowError as B, defineDecisionOutcomeStep as C, resolveDecision as D, functionDecider as E, defineMapStep as F, StepCompensationContext as G, RetryPolicy as H, defineSleepStep as I, StepError as J, StepConditionHandler as K, defineStep as L, TypedWorkflow as M, WorkflowOutput as N, StepDeps as O, buildWorkflow as P, StepHandlerRegistry as Q, defineSubWorkflowStep as R, DecisionStep as S, defineDecisionStep as T, StartOptions as U, InvalidWorkflowDefinitionError as V, StepCompensateHandler as W, StepHandler as X, StepExecutionContext as Y, StepHandlerNotFoundError as Z, DecisionOutput as _, isTerminalStepStatus as _t, STEP_DISPLAY_STATUS as a, WorkflowDefinition as at, DecisionResponse as b, err as bt, WORKFLOW_STATUS_SCHEMA as c, WorkflowNotRetryableError as ct, toPublicWorkflow as d, WorkflowStepRunningError as dt, StepRecord as et, Decider as f, WorkflowWithSteps as ft, DecisionOutcome as g, computeReadiness as gt, DecisionChoices as h, ReadinessPlan as ht, PublicWorkflowStep as i, WorkflowCreatedResult as it, TypedStepContext as j, StepOutput as k, toDisplayStepStatus as l, WorkflowRecord as lt, DecisionAnswers as m, PlannedSkip as mt, PUBLIC_WORKFLOW_STEP_SCHEMA as n, StepStatus as nt, STEP_DISPLAY_STATUS_SCHEMA as o, WorkflowId as ot, DecisionAnswer as p, JoinRule as pt, StepDefinition as q, PublicWorkflow as r, WaitTimeoutPolicy as rt, StepDisplayStatus as s, WorkflowNotFoundError as st, PUBLIC_WORKFLOW_SCHEMA as t, StepRegistration as tt, toPublicStep as u, WorkflowStatus as ut, DecisionQuestions as v, FlowErrorShape as vt, defineDecisionReviewStep as w, DecisionReview as x, ok as xt, DecisionRequest as y, Result as yt, defineWaitStep as z };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { $ as computeReadiness, A as StepConditionHandler, B as StepStatus, C as defineWaitStep, D as StartOptions, E as RetryPolicy, F as StepHandlerNotFoundError, G as WorkflowNotFoundError, H as WorkflowCreatedResult, I as StepHandlerRegistry, J as WorkflowStatus, K as WorkflowNotRetryableError, L as StepId, M as StepError, N as StepExecutionContext, O as StepCompensateHandler, P as StepHandler, Q as ReadinessPlan, R as StepRecord, S as defineSubWorkflowStep, T as InvalidWorkflowDefinitionError, U as WorkflowDefinition, V as WaitTimeoutPolicy, W as WorkflowId, X as JoinRule, Y as WorkflowWithSteps, Z as PlannedSkip, _ as WorkflowOutput, a as STEP_DISPLAY_STATUS, b as defineSleepStep, c as WORKFLOW_STATUS_SCHEMA, d as toPublicWorkflow, et as isTerminalStepStatus, f as StepDeps, g as TypedWorkflow, h as TypedStepContext, i as PublicWorkflowStep, it as ok, j as StepDefinition, k as StepCompensationContext, l as toDisplayStepStatus, m as TypedStep, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as Result, o as STEP_DISPLAY_STATUS_SCHEMA, p as StepOutput, q as WorkflowRecord, r as PublicWorkflow, rt as err, s as StepDisplayStatus, t as PUBLIC_WORKFLOW_SCHEMA, tt as FlowErrorShape, u as toPublicStep, v as buildWorkflow, w as FlowError, x as defineStep, y as defineMapStep, z as StepRegistration } from "./index-BURAYZui.js";
+import { $ as StepId, A as TypedStep, B as FlowError, C as defineDecisionOutcomeStep, D as resolveDecision, E as functionDecider, F as defineMapStep, G as StepCompensationContext, H as RetryPolicy, I as defineSleepStep, J as StepError, K as StepConditionHandler, L as defineStep, M as TypedWorkflow, N as WorkflowOutput, O as StepDeps, P as buildWorkflow, Q as StepHandlerRegistry, R as defineSubWorkflowStep, S as DecisionStep, T as defineDecisionStep, U as StartOptions, V as InvalidWorkflowDefinitionError, W as StepCompensateHandler, X as StepHandler, Y as StepExecutionContext, Z as StepHandlerNotFoundError, _ as DecisionOutput, _t as isTerminalStepStatus, a as STEP_DISPLAY_STATUS, at as WorkflowDefinition, b as DecisionResponse, bt as err, c as WORKFLOW_STATUS_SCHEMA, ct as WorkflowNotRetryableError, d as toPublicWorkflow, dt as WorkflowStepRunningError, et as StepRecord, f as Decider, ft as WorkflowWithSteps, g as DecisionOutcome, gt as computeReadiness, h as DecisionChoices, ht as ReadinessPlan, i as PublicWorkflowStep, it as WorkflowCreatedResult, j as TypedStepContext, k as StepOutput, l as toDisplayStepStatus, lt as WorkflowRecord, m as DecisionAnswers, mt as PlannedSkip, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as StepStatus, o as STEP_DISPLAY_STATUS_SCHEMA, ot as WorkflowId, p as DecisionAnswer, pt as JoinRule, q as StepDefinition, r as PublicWorkflow, rt as WaitTimeoutPolicy, s as StepDisplayStatus, st as WorkflowNotFoundError, t as PUBLIC_WORKFLOW_SCHEMA, tt as StepRegistration, u as toPublicStep, ut as WorkflowStatus, v as DecisionQuestions, vt as FlowErrorShape, w as defineDecisionReviewStep, x as DecisionReview, xt as ok, y as DecisionRequest, yt as Result, z as defineWaitStep } from "./index-B8SvtiYn.js";
 import { n as Logger, r as noopLogger, t as LogAttributes } from "./logger-BCus3AOa.js";
-import { A as ListWorkflowsFilters, C as AddChildStep, D as CreatedWorkflow, E as CreateWorkflowStep, M as TransactionalScope, N as WorkflowStore, O as FailStepParams, S as createInMemoryStepGate, T as CreateWorkflowParams, _ as InMemoryStepGateConfig, a as FlowSpan, b as StepGateDecision, c as RecordingObserver, d as createMeterObserver, f as createRecordingObserver, g as ConcurrencyRule, h as noopTracer, i as FlowObserver, j as ReopenWorkflowParams, k as FinishWorkflowParams, l as RecordingTracer, m as noopObserver, n as FlowEventType, o as FlowTracer, p as createRecordingTracer, r as FlowMeter, s as RecordedSpan, t as FlowEvent, u as combineObservers, v as RateRule, w as CompleteStepParams, x as StepGateRequest, y as StepGate } from "./observability-3wVqt3tZ.js";
-import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-g7Ct0J6w.js";
-import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-BdxIcc92.js";
+import { A as ListWorkflowsFilters, C as AddChildStep, D as CreatedWorkflow, E as CreateWorkflowStep, M as TransactionalScope, N as WorkflowStore, O as FailStepParams, P as WorkflowTreeFilter, S as createInMemoryStepGate, T as CreateWorkflowParams, _ as InMemoryStepGateConfig, a as FlowSpan, b as StepGateDecision, c as RecordingObserver, d as createMeterObserver, f as createRecordingObserver, g as ConcurrencyRule, h as noopTracer, i as FlowObserver, j as ReopenWorkflowParams, k as FinishWorkflowParams, l as RecordingTracer, m as noopObserver, n as FlowEventType, o as FlowTracer, p as createRecordingTracer, r as FlowMeter, s as RecordedSpan, t as FlowEvent, u as combineObservers, v as RateRule, w as CompleteStepParams, x as StepGateRequest, y as StepGate } from "./observability-DRUJOpiQ.js";
+import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-B4haXU4w.js";
+import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-BV-Vany9.js";
 //#region src/core/registry.d.ts
 /**
  * Creates an in-memory step handler registry.
@@ -114,6 +114,11 @@ export interface RecoverySweepResult {
   /** Workflows failed for outliving `StartOptions.timeoutMs`. */
   expiredWorkflows: number;
 }
+/** What `purgeWorkflows` deleted. */
+export interface PurgeWorkflowsResult {
+  /** Every run deleted, the sub-workflow runs below the matching ones included, ascending. */
+  workflowIds: WorkflowId[];
+}
 /** What `retryWorkflow` put back in flight. */
 export interface RetryWorkflowResult {
   workflowId: WorkflowId;
@@ -137,6 +142,7 @@ export declare function createWorkflowEngine<TContext = unknown>(deps: WorkflowE
   recoverStuckWorkflows: () => Promise<RecoverySweepResult>;
   retryWorkflow: (workflowId: WorkflowId) => Promise<Result<RetryWorkflowResult, FlowError>>;
   cancelWorkflow: (workflowId: WorkflowId) => Promise<Result<void, FlowError>>;
+  purgeWorkflows: (filter: WorkflowTreeFilter) => Promise<Result<PurgeWorkflowsResult, FlowError>>;
   getWorkflowStatus: (workflowId: WorkflowId) => Promise<Result<WorkflowWithSteps, FlowError>>;
   listWorkflows: (filters?: {
     status?: WorkflowStatus;
@@ -162,4 +168,4 @@ export declare function createInMemoryWorkflowStore(partitionKey?: string): Work
   };
 };
 //#endregion
-export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, DispatchKind, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowMeter, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, JoinRule, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PlannedSkip, PublicWorkflow, PublicWorkflowStep, RateRule, ReadinessPlan, RecordedSpan, RecordingObserver, RecordingTracer, ReopenWorkflowParams, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepConditionHandler, StepDefinition, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowNotRetryableError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStore, WorkflowWithSteps, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createMeterObserver, createRecordingObserver, createRecordingTracer, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, isTerminalStepStatus, noopLogger, noopObserver, noopTracer, ok, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, Decider, DecisionAnswer, DecisionAnswers, DecisionChoices, DecisionOutcome, DecisionOutput, DecisionQuestions, DecisionRequest, DecisionResponse, DecisionReview, DecisionStep, DispatchKind, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowMeter, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, JoinRule, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PlannedSkip, PublicWorkflow, PublicWorkflowStep, RateRule, ReadinessPlan, RecordedSpan, RecordingObserver, RecordingTracer, ReopenWorkflowParams, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepConditionHandler, StepDefinition, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowNotRetryableError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStepRunningError, WorkflowStore, WorkflowTreeFilter, WorkflowWithSteps, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createMeterObserver, createRecordingObserver, createRecordingTracer, defineDecisionOutcomeStep, defineDecisionReviewStep, defineDecisionStep, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, functionDecider, isTerminalStepStatus, noopLogger, noopObserver, noopTracer, ok, resolveDecision, toDisplayStepStatus, toPublicStep, toPublicWorkflow };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { S as ok, _ as markRetryable, a as WORKFLOW_STATUS_SCHEMA, b as noopLogger, c as toPublicWorkflow, d as defineSleepStep, f as defineStep, g as isRetryableError, h as explicitRetryability, i as STEP_DISPLAY_STATUS_SCHEMA, l as buildWorkflow, m as defineWaitStep, n as PUBLIC_WORKFLOW_STEP_SCHEMA, o as toDisplayStepStatus, p as defineSubWorkflowStep, r as STEP_DISPLAY_STATUS, s as toPublicStep, t as PUBLIC_WORKFLOW_SCHEMA, u as defineMapStep, v as nonRetryableError, x as err, y as retryableError } from "./core-DNWPwFaE.js";
+import { C as nonRetryableError, D as ok, E as err, S as markRetryable, T as noopLogger, _ as defineStep, a as WORKFLOW_STATUS_SCHEMA, b as explicitRetryability, c as toPublicWorkflow, d as defineDecisionStep, f as functionDecider, g as defineSleepStep, h as defineMapStep, i as STEP_DISPLAY_STATUS_SCHEMA, l as defineDecisionOutcomeStep, m as buildWorkflow, n as PUBLIC_WORKFLOW_STEP_SCHEMA, o as toDisplayStepStatus, p as resolveDecision, r as STEP_DISPLAY_STATUS, s as toPublicStep, t as PUBLIC_WORKFLOW_SCHEMA, u as defineDecisionReviewStep, v as defineSubWorkflowStep, w as retryableError, x as isRetryableError, y as defineWaitStep } from "./core-C9h3-KFr.js";
 //#region src/core/readiness.ts
 /** Statuses a step can no longer move out of on its own. */
 const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
@@ -1715,6 +1715,60 @@ function createWorkflowEngine(deps) {
 			value: void 0
 		};
 	}
+	/**
+	* Delete every run about one entity — the runs whose `entityRef` matches and every
+	* sub-workflow run below them — with all of their steps: what a model was given and
+	* what it said goes with them. For erasing a person, or deleting the record the runs
+	* were about.
+	*
+	* Refuses with `workflow_step_running` while any of those runs has a step executing
+	* (`running`, or `compensating`): a worker is inside its handler, and deleting the run
+	* under it would let it write about something that no longer exists. Nothing is
+	* cancelled or deleted then; try again once the step settles. A run that only *waits*
+	* — for a person (`waiting`), a sleep, a sub-workflow, queued work — does not stop it.
+	*
+	* Otherwise every active run is cancelled first, parents before children, exactly as
+	* `cancelWorkflow` would (a matching sub-workflow run whose parent is not being purged
+	* fails the parent's step), and then all of them are deleted. Whatever was still queued
+	* for them — a step job, a wait deadline, a `resumeStep` — finds no run and ends in
+	* `workflow_not_found`; nothing is written back. `workflow.cancelled` and then
+	* `workflow.purged` are emitted per run.
+	*
+	* Runs, not history: rows a host wrote elsewhere keyed by the run id (an event sink's
+	* `flow_step_event`, a ledger entry, a usage rollup) are the host's to keep or delete —
+	* the ids come back for that.
+	*/
+	async function purgeWorkflows(filter) {
+		const tree = await store.listWorkflowTree(filter);
+		if (tree.length === 0) return {
+			ok: true,
+			value: { workflowIds: [] }
+		};
+		const running = tree.flatMap((w) => w.steps.filter((s) => s.status === "running" || s.status === "compensating").map((s) => ({
+			workflowId: w.id,
+			stepKey: s.key,
+			status: s.status
+		})));
+		if (running.length > 0) return {
+			ok: false,
+			error: {
+				key: "workflow_step_running",
+				running,
+				message: `A step is executing in ${[...new Set(running.map((r) => r.workflowId))].map((id) => `run ${id}`).join(", ")}; try again once it settles`
+			}
+		};
+		for (const w of tree) if (w.status === "pending" || w.status === "running") await cancelWorkflow(w.id);
+		const workflowIds = await store.deleteWorkflows(filter);
+		logger.info("Workflows purged", { count: workflowIds.length });
+		for (const workflowId of workflowIds) emit({
+			type: "workflow.purged",
+			workflowId
+		});
+		return {
+			ok: true,
+			value: { workflowIds }
+		};
+	}
 	async function getWorkflowStatus(workflowId) {
 		const workflow = await store.getWorkflow(workflowId);
 		if (!workflow) return {
@@ -1945,6 +1999,7 @@ function createWorkflowEngine(deps) {
 		recoverStuckWorkflows,
 		retryWorkflow,
 		cancelWorkflow,
+		purgeWorkflows,
 		getWorkflowStatus,
 		listWorkflows
 	};
@@ -2190,6 +2245,35 @@ function createInMemoryWorkflowStore(partitionKey = "default") {
 			steps: stepsOf(w.id).map(clone)
 		}));
 	}
+	/** The runs about the entity and every sub-workflow run below them, ascending by id. */
+	function treeOf(filter) {
+		const ids = /* @__PURE__ */ new Set();
+		for (const w of workflows.values()) if (w.entityRef === filter.entityRef) ids.add(w.id);
+		let grew = ids.size > 0;
+		while (grew) {
+			grew = false;
+			for (const w of workflows.values()) if (w.parentWorkflowId != null && ids.has(w.parentWorkflowId) && !ids.has(w.id)) {
+				ids.add(w.id);
+				grew = true;
+			}
+		}
+		return Array.from(ids, (id) => workflows.get(id)).sort((a, b) => a.id - b.id);
+	}
+	async function listWorkflowTree(filter) {
+		return treeOf(filter).map((w) => ({
+			...clone(w),
+			steps: stepsOf(w.id).map(clone)
+		}));
+	}
+	async function deleteWorkflows(filter) {
+		const doomed = treeOf(filter);
+		for (const w of doomed) {
+			for (const s of stepsOf(w.id)) steps.delete(s.id);
+			workflows.delete(w.id);
+			if (w.idempotencyKey != null && byIdempotency.get(w.idempotencyKey) === w.id) byIdempotency.delete(w.idempotencyKey);
+		}
+		return doomed.map((w) => w.id);
+	}
 	async function listRunningWorkflows() {
 		return Array.from(workflows.values()).filter((w) => w.status === "running").map(clone);
 	}
@@ -2222,6 +2306,8 @@ function createInMemoryWorkflowStore(partitionKey = "default") {
 		skipPendingSteps,
 		finishWorkflow,
 		listWorkflows,
+		listWorkflowTree,
+		deleteWorkflows,
 		listRunningWorkflows,
 		findStuckSteps,
 		_dump() {
@@ -2233,4 +2319,4 @@ function createInMemoryWorkflowStore(partitionKey = "default") {
 	};
 }
 //#endregion
-export { PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, WORKFLOW_STATUS_SCHEMA, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createInMemoryWorkflowStore, createMeterObserver, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, isRetryableError, isTerminalStepStatus, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, WORKFLOW_STATUS_SCHEMA, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createInMemoryWorkflowStore, createMeterObserver, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineDecisionOutcomeStep, defineDecisionReviewStep, defineDecisionStep, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, functionDecider, isRetryableError, isTerminalStepStatus, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, resolveDecision, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };

package/dist/{observability-3wVqt3tZ.d.ts → observability-DRUJOpiQ.d.ts}

@@ -1,4 +1,4 @@
-import { J as WorkflowStatus, L as StepId, R as StepRecord, W as WorkflowId, Y as WorkflowWithSteps, q as WorkflowRecord } from "./index-BURAYZui.js";
+import { $ as StepId, et as StepRecord, ft as WorkflowWithSteps, lt as WorkflowRecord, ot as WorkflowId, ut as WorkflowStatus } from "./index-B8SvtiYn.js";
 //#region src/core/store.d.ts
 interface CreateWorkflowStep {
   key: string;
@@ -75,6 +75,15 @@ interface ListWorkflowsFilters {
   entityRef?: string;
   limit?: number;
 }
+/**
+ * The runs {@link WorkflowStore.listWorkflowTree} and {@link WorkflowStore.deleteWorkflows}
+ * address: every run of the store's partition whose `entityRef` matches, **plus every
+ * sub-workflow run below them**, at any depth — a child run carries its parent's id, not
+ * its entity, so it would otherwise be missed.
+ */
+interface WorkflowTreeFilter {
+  entityRef: string;
+}
 /**
  * A store bound to an open transaction, plus an opaque handle a capable
  * {@link Dispatcher} can join so a job and the state change that produced it
@@ -197,6 +206,22 @@ interface WorkflowStore {
   reopenWorkflow(params: ReopenWorkflowParams): Promise<void>;
   /** List workflows (with their steps) for status/dashboard reads. */
   listWorkflows(filters: ListWorkflowsFilters): Promise<WorkflowWithSteps[]>;
+  /**
+   * Every run the filter addresses (see {@link WorkflowTreeFilter}), with its steps,
+   * ordered by id — so a parent always comes before its children. No limit: the engine
+   * reads this to decide whether the whole set may go, and a page would hide a run.
+   */
+  listWorkflowTree(filter: WorkflowTreeFilter): Promise<WorkflowWithSteps[]>;
+  /**
+   * Delete every run the filter addresses, with all of their steps (map children
+   * included), and return the ids of the runs deleted, ascending.
+   *
+   * Implementations MUST delete the runs and their steps together — one statement or
+   * one transaction — so no step row outlives its run, whatever foreign keys the host
+   * declared. Nothing is checked here: whether a run may go is the engine's question
+   * (`purgeWorkflows`), asked before it calls this.
+   */
+  deleteWorkflows(filter: WorkflowTreeFilter): Promise<WorkflowId[]>;
   /** All workflows currently in `running` state (for the stuck-step sweeper). */
   listRunningWorkflows(): Promise<WorkflowRecord[]>;
   /**
@@ -275,7 +300,12 @@ declare function createInMemoryStepGate(config?: InMemoryStepGateConfig): StepGa
 /** Lifecycle event types the engine emits at every workflow/step transition. */
 type FlowEventType = 'workflow.started' | 'workflow.completed' | 'workflow.failed' | 'workflow.cancelled' |
 /** A `failed` workflow was put back in flight by `retryWorkflow`. */
-'workflow.retried' | 'step.started' | 'step.completed' | 'step.failed' | 'step.retrying' | 'step.skipped' | 'step.waiting' | 'step.resumed' |
+'workflow.retried' |
+/**
+ * The run was deleted by `purgeWorkflows`, with its steps. Emitted after the delete,
+ * once per run; nothing about the run can be read any more.
+ */
+'workflow.purged' | 'step.started' | 'step.completed' | 'step.failed' | 'step.retrying' | 'step.skipped' | 'step.waiting' | 'step.resumed' |
 /**
  * A suspended step's wait budget elapsed. Always followed by the event for
  * what the policy did — `step.failed`, or `step.completed` for `{ output }`.
@@ -381,4 +411,4 @@ interface RecordingTracer extends FlowTracer {
 }
 declare function createRecordingTracer(): RecordingTracer;
 //#endregion
-export { ListWorkflowsFilters as A, AddChildStep as C, CreatedWorkflow as D, CreateWorkflowStep as E, TransactionalScope as M, WorkflowStore as N, FailStepParams as O, createInMemoryStepGate as S, CreateWorkflowParams as T, InMemoryStepGateConfig as _, FlowSpan as a, StepGateDecision as b, RecordingObserver as c, createMeterObserver as d, createRecordingObserver as f, ConcurrencyRule as g, noopTracer as h, FlowObserver as i, ReopenWorkflowParams as j, FinishWorkflowParams as k, RecordingTracer as l, noopObserver as m, FlowEventType as n, FlowTracer as o, createRecordingTracer as p, FlowMeter as r, RecordedSpan as s, FlowEvent as t, combineObservers as u, RateRule as v, CompleteStepParams as w, StepGateRequest as x, StepGate as y };
+export { ListWorkflowsFilters as A, AddChildStep as C, CreatedWorkflow as D, CreateWorkflowStep as E, TransactionalScope as M, WorkflowStore as N, FailStepParams as O, WorkflowTreeFilter as P, createInMemoryStepGate as S, CreateWorkflowParams as T, InMemoryStepGateConfig as _, FlowSpan as a, StepGateDecision as b, RecordingObserver as c, createMeterObserver as d, createRecordingObserver as f, ConcurrencyRule as g, noopTracer as h, FlowObserver as i, ReopenWorkflowParams as j, FinishWorkflowParams as k, RecordingTracer as l, noopObserver as m, FlowEventType as n, FlowTracer as o, createRecordingTracer as p, FlowMeter as r, RecordedSpan as s, FlowEvent as t, combineObservers as u, RateRule as v, CompleteStepParams as w, StepGateRequest as x, StepGate as y };

package/dist/pg-boss/index.d.ts

@@ -1,6 +1,6 @@
-import "../index-BURAYZui.js";
+import "../index-B8SvtiYn.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { r as Dispatcher } from "../dispatcher-g7Ct0J6w.js";
+import { r as Dispatcher } from "../dispatcher-B4haXU4w.js";
 import { z } from "zod";
 import { PgBoss } from "pg-boss";
 //#region src/pg-boss/payload.d.ts

package/dist/postgres/index.d.ts

@@ -1,5 +1,5 @@
-import { W as WorkflowId } from "../index-BURAYZui.js";
-import { N as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-3wVqt3tZ.js";
+import { ot as WorkflowId } from "../index-B8SvtiYn.js";
+import { N as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-DRUJOpiQ.js";
 import { Pool } from "pg";
 //#region src/postgres/ddl.d.ts
 /**

package/dist/postgres/index.js

@@ -410,9 +410,12 @@ function createWorkflowStore(deps) {
 		}
 		args.push(filters.limit ?? 50);
 		const limitIdx = args.length;
-		const wfRes = await exec.query(`SELECT * FROM ${WF} WHERE ${conds.join(" AND ")} ORDER BY id DESC LIMIT $${limitIdx}`, args);
-		if (wfRes.rows.length === 0) return [];
-		const ids = wfRes.rows.map((r) => Number(r.id));
+		return withSteps((await exec.query(`SELECT * FROM ${WF} WHERE ${conds.join(" AND ")} ORDER BY id DESC LIMIT $${limitIdx}`, args)).rows);
+	}
+	/** Attach each run's steps in one query. */
+	async function withSteps(rows) {
+		if (rows.length === 0) return [];
+		const ids = rows.map((r) => Number(r.id));
 		const stepRes = await exec.query(`SELECT * FROM ${STEP} WHERE workflow_id = ANY($1::bigint[]) AND partition_key = $2 ORDER BY id`, [ids, partitionKey]);
 		const stepsByWf = /* @__PURE__ */ new Map();
 		for (const row of stepRes.rows) {
@@ -421,11 +424,33 @@ function createWorkflowStore(deps) {
 			list.push(s);
 			stepsByWf.set(s.workflowId, list);
 		}
-		return wfRes.rows.map((r) => ({
+		return rows.map((r) => ({
 			...mapWorkflow(r),
 			steps: stepsByWf.get(Number(r.id)) ?? []
 		}));
 	}
+	/**
+	* The runs about the entity and every sub-workflow run below them, as a recursive CTE
+	* over `parent_workflow_id` (`$1` partition, `$2` entity). Shared by the read and the
+	* delete so the two can never address different sets.
+	*/
+	const TREE = `tree(id) AS (
+      SELECT id FROM ${WF} WHERE partition_key = $1 AND entity_ref = $2
+      UNION
+      SELECT c.id FROM ${WF} c JOIN tree t ON c.parent_workflow_id = t.id WHERE c.partition_key = $1
+    )`;
+	async function listWorkflowTree(filter) {
+		return withSteps((await exec.query(`WITH RECURSIVE ${TREE}
+       SELECT w.* FROM ${WF} w JOIN tree t ON t.id = w.id WHERE w.partition_key = $1 ORDER BY w.id`, [partitionKey, filter.entityRef])).rows);
+	}
+	async function deleteWorkflows(filter) {
+		return (await exec.query(`WITH RECURSIVE ${TREE},
+       gone_steps AS (
+         DELETE FROM ${STEP} s USING tree t WHERE s.workflow_id = t.id AND s.partition_key = $1
+       )
+       DELETE FROM ${WF} w USING tree t WHERE w.id = t.id AND w.partition_key = $1
+       RETURNING w.id`, [partitionKey, filter.entityRef])).rows.map((r) => Number(r.id)).sort((a, b) => a - b);
+	}
 	async function listRunningWorkflows() {
 		return (await exec.query(`SELECT * FROM ${WF} WHERE partition_key = $1 AND status = 'running'`, [partitionKey])).rows.map(mapWorkflow);
 	}
@@ -482,6 +507,8 @@ function createWorkflowStore(deps) {
 		skipPendingSteps,
 		finishWorkflow,
 		listWorkflows,
+		listWorkflowTree,
+		deleteWorkflows,
 		listRunningWorkflows,
 		findStuckSteps
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.26.0",
+  "version": "0.28.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",
@@ -116,18 +116,18 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^4.0.69",
-    "@ai-sdk/mistral": "^4.0.55",
-    "@ai-sdk/openai": "^4.0.82",
-    "@ai-sdk/openai-compatible": "^3.0.60",
-    "@ai-sdk/provider": "^4.0.20",
+    "@ai-sdk/anthropic": "^4.0.71",
+    "@ai-sdk/mistral": "^4.0.56",
+    "@ai-sdk/openai": "^4.0.83",
+    "@ai-sdk/openai-compatible": "^3.0.62",
+    "@ai-sdk/provider": "^4.0.21",
     "@testcontainers/postgresql": "^12.2.0",
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.4",
     "@types/pg": "^8.23.1",
-    "ai": "^7.0.123",
+    "ai": "^7.0.127",
     "drizzle-orm": "^0.45.3",
     "pg": "^8.23.1",
-    "pg-boss": "^12.35.0",
+    "pg-boss": "^12.35.1",
     "testcontainers": "^12.2.0",
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",