octaflow 0.27.0 → 0.28.0

package/README.md

@@ -203,6 +203,7 @@ next to what your steps actually do.
 | 🎯 | **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 |
@@ -327,7 +328,7 @@ Full docs — concepts, every feature, production wiring and the API reference
 | [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 |

package/dist/ai/index.d.ts

@@ -1,6 +1,6 @@
-import { A as TypedStep, H as RetryPolicy, M as TypedWorkflow, _t as FlowErrorShape, f as Decider, j as TypedStepContext, vt as Result } from "../index-BGmJYvTt.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-BGOHvR37.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";

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

@@ -1,4 +1,4 @@
-import { $ as StepId, _t as FlowErrorShape, ot as WorkflowId, vt as Result } from "./index-BGmJYvTt.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-BGOHvR37.d.ts → hooks-BV-Vany9.d.ts}

@@ -1,4 +1,4 @@
-import { $ as StepId, U as StartOptions, _t as FlowErrorShape, at as WorkflowDefinition, et as StepRecord, lt as WorkflowRecord, ot as WorkflowId, vt as Result } from "./index-BGmJYvTt.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-BGmJYvTt.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
 /**
@@ -993,4 +1006,4 @@ declare function toPublicStep(step: StepRecord): PublicWorkflowStep;
  */
 declare function toPublicWorkflow(workflow: WorkflowWithSteps): PublicWorkflow;
 //#endregion
-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 _, FlowErrorShape as _t, STEP_DISPLAY_STATUS as a, WorkflowDefinition as at, DecisionResponse as b, ok as bt, WORKFLOW_STATUS_SCHEMA as c, WorkflowNotRetryableError as ct, toPublicWorkflow as d, WorkflowWithSteps as dt, StepRecord as et, Decider as f, JoinRule as ft, DecisionOutcome as g, isTerminalStepStatus as gt, DecisionChoices as h, computeReadiness as ht, PublicWorkflowStep as i, WorkflowCreatedResult as it, TypedStepContext as j, StepOutput as k, toDisplayStepStatus as l, WorkflowRecord as lt, DecisionAnswers as m, ReadinessPlan as mt, PUBLIC_WORKFLOW_STEP_SCHEMA as n, StepStatus as nt, STEP_DISPLAY_STATUS_SCHEMA as o, WorkflowId as ot, DecisionAnswer as p, PlannedSkip 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, Result as vt, defineDecisionReviewStep as w, DecisionReview as x, DecisionRequest as y, err as yt, defineWaitStep 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 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 FlowErrorShape, a as STEP_DISPLAY_STATUS, at as WorkflowDefinition, b as DecisionResponse, bt as ok, c as WORKFLOW_STATUS_SCHEMA, ct as WorkflowNotRetryableError, d as toPublicWorkflow, dt as WorkflowWithSteps, et as StepRecord, f as Decider, ft as JoinRule, g as DecisionOutcome, gt as isTerminalStepStatus, h as DecisionChoices, ht as computeReadiness, i as PublicWorkflowStep, it as WorkflowCreatedResult, j as TypedStepContext, k as StepOutput, l as toDisplayStepStatus, lt as WorkflowRecord, m as DecisionAnswers, mt as ReadinessPlan, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as StepStatus, o as STEP_DISPLAY_STATUS_SCHEMA, ot as WorkflowId, p as DecisionAnswer, pt as PlannedSkip, 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 Result, w as defineDecisionReviewStep, x as DecisionReview, y as DecisionRequest, yt as err, z as defineWaitStep } from "./index-BGmJYvTt.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-C-jfi2DX.js";
-import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-Bzkqq0Ax.js";
-import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-BGOHvR37.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, 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, WorkflowStore, 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 };
+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

@@ -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() {

package/dist/{observability-C-jfi2DX.d.ts → observability-DRUJOpiQ.d.ts}

@@ -1,4 +1,4 @@
-import { $ as StepId, dt as WorkflowWithSteps, et as StepRecord, lt as WorkflowRecord, ot as WorkflowId, ut as WorkflowStatus } from "./index-BGmJYvTt.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-BGmJYvTt.js";
+import "../index-B8SvtiYn.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { r as Dispatcher } from "../dispatcher-Bzkqq0Ax.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 { ot as WorkflowId } from "../index-BGmJYvTt.js";
-import { N as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-C-jfi2DX.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.27.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",