octaflow 0.38.0 → 0.40.0

package/README.md

@@ -214,6 +214,8 @@ next to what your steps actually do.
 | ↩️ | **Saga compensation** — run rollback handlers in reverse order on failure |
 | 🚑 | **Crash recovery** — a step whose worker died is re-queued while its attempt budget lasts |
 | 💓 | **Heartbeats** — a long step proves it is alive, so a dead one is caught in seconds, not minutes |
+| 📌 | **Step checkpoints** — `ctx.checkpoint`: a step keeps what it has done so far (`save`), and the attempt after a crash reads it (`value`) and goes on from there; written only by the attempt that owns the step |
+| ⏭️ | **Continue later** — a handler throws `continueStep(afterMs)` to stop now and run again in a new invocation, without spending an attempt: work in slices on a host with a hard request ceiling, going on from `ctx.checkpoint` |
 | 🔭 | **Observability** — lifecycle events (run history), per-step spans, and `createMeterObserver` turning the events into OpenTelemetry-style metrics — all pluggable, all structural |
 | 📄 | **Workflow documents** (`octaflow/document`) — a workflow as JSON: a template a tenant saves or a model drafts, checked by a compiler (types, expressions, bounded waits, roles, no outward step without a person's approval) and run on one registration per kind, with no deploy per template. See [Workflow documents](#workflow-documents) |
 | 🤖 | **The model layer** — AI steps with token and cost capture, quotas, the model decider, agents that end by choosing an exit, case loops, managed providers and model runners: [`@octabits-io/models`](../models/README.md) (`./octaflow` is its binding to this engine; it was `octaflow/ai` until 0.36) |
@@ -263,8 +265,9 @@ decimals (`decimal(input.amount)`) as types of their own.
 | `repeat` | its steps pass after pass while a condition holds, up to a cap — one step of one run |
 | `flow` | groups steps, or runs another document (`ref`, pinned to a revision) as a sub-workflow |
 
-A host adds its own kinds; a kind can check its own params, name the expressions it keeps
-(`reads`), or stand for several steps (`expand`). Policy is reviewed between revisions:
+A host adds its own kinds; a kind can check its own params (`check`, whose issues are `params`
+unless one says `approval_before_impact` — an agent kind given an outward tool set, say), name
+the expressions it keeps (`reads`), or stand for several steps (`expand`). Policy is reviewed between revisions:
 `reviewWorkflowRevision` lists what changed in it, and `checkPublication` wants someone other
 than the author to approve a change. The format and its decisions are in
 [docs/workflow-documents.md](./docs/workflow-documents.md).

package/dist/{core-COMWflJl.js → core-ut8VZ0sU.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-//#region src/core/retry.ts
+// src/core/retry.ts
 /**
 * Realm-safe marker for an explicit retryability decision. `Symbol.for` so a
 * duplicated copy of this module still reads markers set by the other copy.
@@ -133,8 +133,30 @@ function isRetryableError(error) {
 	if (message.includes("503") || message.includes("service unavailable")) return true;
 	return false;
 }
-//#endregion
-//#region src/core/defineStep.ts
+const CONTINUE = Symbol.for("octaflow.continue");
+/**
+* Throw this from a handler to stop now and run again later, without spending
+* an attempt: the engine puts the step back to `pending` and re-queues it
+* after `afterMs`. For a handler that works in slices of wall-clock time — a
+* host with a hard request ceiling — and keeps its progress in
+* `ctx.checkpoint`, so the next run goes on from there. Nothing caps how
+* often a step continues; the handler's own limits must.
+*/
+function continueStep(afterMs = 0, message = "the step continues in its next slice") {
+	const error = new Error(message);
+	Object.defineProperty(error, CONTINUE, {
+		value: Math.max(0, afterMs),
+		enumerable: false
+	});
+	return error;
+}
+/** The delay a {@link continueStep} error asks for, or `undefined` for any other error. */
+function continuationOf(error) {
+	if (typeof error !== "object" || error === null) return void 0;
+	const afterMs = error[CONTINUE];
+	return typeof afterMs === "number" ? afterMs : void 0;
+}
+// src/core/defineStep.ts
 /**
 * `z.object({})` typed as the empty-record schema. Zod infers `{}` for an empty object schema,
 * but we want `Record<string, never>` for input/output-less steps — hence the bridge cast.
@@ -172,11 +194,15 @@ function defineStep(config) {
 	const toStepError = (error) => {
 		const message = error instanceof Error ? error.message : "Unknown step error";
 		const marked = explicitRetryability(error);
+		const retryable = marked ?? (isRetryable ? isRetryable(error) : isRetryableError(error));
+		const retryableFrom = marked !== void 0 ? "explicit" : isRetryable ? "predicate" : "heuristic";
+		const continueAfterMs = continuationOf(error);
 		return {
 			key: "step_error",
 			message,
-			retryable: marked ?? (isRetryable ? isRetryable(error) : isRetryableError(error)),
-			retryableFrom: marked !== void 0 ? "explicit" : isRetryable ? "predicate" : "heuristic"
+			retryable,
+			retryableFrom,
+			...continueAfterMs !== void 0 && { continueAfterMs }
 		};
 	};
 	/**
@@ -224,6 +250,7 @@ function defineStep(config) {
 				deps: parsedDeps,
 				signal: ctx.signal,
 				heartbeat: ctx.heartbeat,
+				checkpoint: ctx.checkpoint,
 				context: ctx.context
 			}
 		};
@@ -525,8 +552,7 @@ function buildWorkflow(config) {
 		}
 	};
 }
-//#endregion
-//#region src/core/decision.ts
+// 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.
@@ -743,8 +769,7 @@ function defineDecisionOutcomeStep(config) {
 		}
 	});
 }
-//#endregion
-//#region src/core/public-view.ts
+// src/core/public-view.ts
 /**
 * Public wire view of a workflow — the projection every HTTP consumer was
 * hand-writing.
@@ -881,5 +906,4 @@ function toPublicWorkflow(workflow) {
 		completedAt: workflow.completedAt
 	};
 }
-//#endregion
-export { nonRetryableError as C, markRetryable as S, 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 };
+export { isRetryableError as C, retryableError as E, explicitRetryability as S, nonRetryableError as T, defineStep as _, WORKFLOW_STATUS_SCHEMA as a, continuationOf 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, markRetryable as w, continueStep as x, defineWaitStep as y };

package/dist/{dispatcher-jbFVHfdm.d.ts → dispatcher-BnlAJuu3.d.ts}

@@ -1,5 +1,4 @@
-import { Tt as Result, ft as WorkflowId, rt as StepId, wt as FlowErrorShape } from "./index-BlwtmRJP.js";
-//#region src/core/logger.d.ts
+import { Et as Result, Tt as FlowErrorShape, it as StepId, pt as WorkflowId } from "./index-BBO5BGS8.js";
 type LogAttributes = Record<string, unknown>;
 interface Logger {
   info(message: string, attributes?: LogAttributes): void;
@@ -7,8 +6,6 @@ interface Logger {
   error(message: string, error?: Error, attributes?: LogAttributes): void;
 }
 declare const noopLogger: Logger;
-//#endregion
-//#region src/core/dispatcher.d.ts
 /**
  * What a step job is for. A queue carries two kinds of work for a step, and
  * they differ only in this field:
@@ -69,5 +66,4 @@ interface Dispatcher {
    */
   enqueueStepIn?(handle: unknown, payload: DispatchStepPayload, options?: EnqueueOptions): Promise<Result<void, FlowErrorShape>>;
 }
-//#endregion
 export { LogAttributes as a, EnqueueOptions as i, DispatchStepPayload as n, Logger as o, Dispatcher as r, noopLogger as s, DispatchKind as t };

package/dist/document/index.d.ts

@@ -1,7 +1,6 @@
-import { H as FlowError, Q as StepExecutionContext, Tt as Result, W as RetryPolicy, dt as WorkflowDefinition, ft as WorkflowId, it as StepPolicy, nt as StepHandlerRegistry } from "../index-BlwtmRJP.js";
-import { f as WorkflowStore } from "../store-BPHVI_a3.js";
+import { $ as StepExecutionContext, Et as Result, H as FlowError, W as RetryPolicy, at as StepPolicy, ft as WorkflowDefinition, pt as WorkflowId, rt as StepHandlerRegistry } from "../index-BBO5BGS8.js";
+import { f as WorkflowStore } from "../store-oCpqAuTT.js";
 import { z } from "zod";
-//#region src/document/schema.d.ts
 /** A schema of the subset, or one the checker derived. `{}` is "anything". */
 type JsonSchema = {
   type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null' | 'duration' | 'decimal';
@@ -29,8 +28,6 @@ export declare function checkSchemaSubset(schema: unknown, path: string): Pathed
  * Cached by the schema's text, so a document's steps share one validator each.
  */
 export declare function zodFor(schema: JsonSchema): z.ZodType;
-//#endregion
-//#region src/document/format.d.ts
 export declare const WORKFLOW_DOCUMENT_FORMAT: 'octaflow.workflow';
 export declare const WORKFLOW_DOCUMENT_VERSION: 1;
 interface DocumentStep {
@@ -48,6 +45,14 @@ interface DocumentStep {
   onFailure?: 'fail' | {
     output: Record<string, unknown>;
   };
+  /**
+   * For `map` only: what an item whose run is cancelled counts as — an item withdrawn on purpose
+   * (`cancelWorkflow` on its run). The stand-in takes its slot of `items` and the map goes on with
+   * the others. Without it a cancelled item fails the map; an item whose run *fails* fails it either way.
+   */
+  itemOnCancel?: {
+    output: Record<string, unknown>;
+  };
   retry?: {
     maxAttempts: number;
     backoff?: 'fixed' | 'exponential';
@@ -92,8 +97,6 @@ export declare const workflowDocumentSchema: z.ZodObject<{
 }, z.core.$strict>;
 type WorkflowDocument = z.infer<typeof workflowDocumentSchema>;
 type DocumentRole = z.infer<typeof roleSchema>;
-//#endregion
-//#region src/document/kinds.d.ts
 /** Who acts in a step of this kind; a step's `role` must allow it. */
 type KindActor = 'agent' | 'person' | 'system';
 /**
@@ -132,6 +135,8 @@ type KindCheck = (args: {
 }) => Array<{
   path: string;
   message: string;
+  /** Default `params`; `approval_before_impact` for a step that would act outward with no person's approval. */
+  code?: 'params' | 'approval_before_impact';
 }>;
 interface KindHandlerArgs<TParams, TContext> {
   /** The step's params, every binding resolved, parsed by the kind's schema. */
@@ -229,8 +234,6 @@ export declare const subflowKind: WorkflowKind<unknown>;
  */
 export declare const decideKind: WorkflowKind<unknown>;
 export declare const coreKinds: readonly WorkflowKind[];
-//#endregion
-//#region src/document/compile.d.ts
 interface CompileIssue extends PathedIssue {
   code: CompileIssueCode;
 }
@@ -287,8 +290,6 @@ interface InvalidWorkflowDocumentError {
   issues: CompileIssue[];
 }
 export declare function compileWorkflowDocument(raw: unknown, kinds: readonly WorkflowKind<any>[], options?: CompileOptions): Result<CompiledWorkflow, InvalidWorkflowDocumentError>;
-//#endregion
-//#region src/document/runtime.d.ts
 /**
  * The spec of a document step, from its record's input — what a model resolver
  * reads to pick the model for a step's `role` (`spec.params.role`). Null for a
@@ -340,8 +341,6 @@ export declare function resumeDocumentStep(engine: ResumableEngine, compiled: Pi
 export declare function resumeWaitingStep(engine: ResumableEngine, store: WorkflowStore, workflowId: WorkflowId, stepKey: string, answer: Record<string, unknown>): Promise<Result<void, ResumeDocumentStepError>>;
 /** The run's result, from its document's `result` expressions over the steps' outputs. */
 export declare function documentResult(store: WorkflowStore, compiled: Pick<CompiledWorkflow, 'result'>, workflowId: WorkflowId): Promise<Record<string, unknown> | null>;
-//#endregion
-//#region src/document/expr.d.ts
 type Expr = {
   kind: 'literal';
   value: string | number | boolean | null;
@@ -384,8 +383,6 @@ interface CheckResult {
  * that never fit. "Anything" passes, since it might.
  */
 export declare function checkExpr(e: Expr, scope: Record<string, JsonSchema>): CheckResult;
-//#endregion
-//#region src/document/duration.d.ts
 /** A duration as an expression value: tagged, so it never passes for a number. */
 interface Duration {
   readonly $duration: number;
@@ -394,8 +391,6 @@ export declare function duration(ms: number): Duration;
 export declare function isDuration(value: unknown): value is Duration;
 /** An ISO 8601 duration (`P2D`, `PT4H30M`) in ms, or null when it isn't one this format accepts. */
 export declare function parseIsoDuration(text: string): number | null;
-//#endregion
-//#region src/document/decimal.d.ts
 /** A decimal as an expression value: tagged, so it never passes for a number or a string. */
 interface Decimal {
   readonly $decimal: string;
@@ -404,8 +399,6 @@ export declare const DIVISION_SCALE = 9;
 export declare function isDecimal(value: unknown): value is Decimal;
 /** A decimal from a decimal string or a finite number; null for anything else. */
 export declare function toDecimal(value: unknown): Decimal | null;
-//#endregion
-//#region src/document/policy.d.ts
 /** One piece of policy, by where it sits in the document. */
 interface PolicyItem {
   path: string;
@@ -467,5 +460,4 @@ export declare function checkPublication(review: RevisionReview, people: {
   author: string;
   approvedBy: readonly string[];
 }): Result<void, PublicationRefused>;
-//#endregion
 export type { CheckResult, CompileIssue, CompileIssueCode, CompileOptions, CompiledStepSpec, CompiledWorkflow, Decimal, DocumentRole, DocumentStep, Duration, Expr, InvalidWorkflowDocumentError, JsonSchema, KindActor, KindCheck, KindConfig, KindEffect, KindHandlerArgs, KindOutput, PathedIssue, PolicyChange, PolicyItem, PublicationRefused, ResumeDocumentStepError, RevisionReview, WaitingDocumentStep, WorkflowDocument, WorkflowKind };

package/dist/document/index.js

@@ -1,7 +1,7 @@
-import { n as ok, t as err } from "../result-CG_l7xQm.js";
-import { b as explicitRetryability, x as isRetryableError } from "../core-COMWflJl.js";
+import { n as ok, t as err } from "../result-CxvNy9B6.js";
+import { C as isRetryableError, S as explicitRetryability, b as continuationOf } from "../core-ut8VZ0sU.js";
 import { z } from "zod";
-//#region src/document/duration.ts
+// src/document/duration.ts
 function duration(ms) {
 	return { $duration: ms };
 }
@@ -25,8 +25,7 @@ const DURATION_UNITS = {
 	hours: HOUR,
 	minutes: MINUTE
 };
-//#endregion
-//#region src/document/decimal.ts
+// src/document/decimal.ts
 const DIVISION_SCALE = 9;
 const PATTERN = /^(-)?(\d+)(?:\.(\d+))?$/;
 function scaled(d) {
@@ -109,8 +108,7 @@ function decimalCompare(a, b) {
 	const [x, y] = align(scaled(a), scaled(b));
 	return x < y ? -1 : x > y ? 1 : 0;
 }
-//#endregion
-//#region src/document/schema.ts
+// src/document/schema.ts
 const TYPES = /* @__PURE__ */ new Set([
 	"object",
 	"string",
@@ -290,8 +288,7 @@ function assignable(actual, expected) {
 	if (expected.type === "array" && actual.items && expected.items) return assignable(actual.items, expected.items);
 	return true;
 }
-//#endregion
-//#region src/document/expr.ts
+// src/document/expr.ts
 var ExprSyntaxError = class extends Error {};
 const KEYWORDS = /* @__PURE__ */ new Set([
 	"if",
@@ -853,8 +850,7 @@ function check(e, scope, errors) {
 		}
 	}
 }
-//#endregion
-//#region src/document/format.ts
+// src/document/format.ts
 const WORKFLOW_DOCUMENT_FORMAT = "octaflow.workflow";
 const WORKFLOW_DOCUMENT_VERSION = 1;
 const keySchema = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]*$/, "a key starts with a letter and holds letters, digits, \"_\" and \"-\"");
@@ -871,6 +867,7 @@ const documentStepSchema = z.lazy(() => z.strictObject({
 	timeout: z.string().optional(),
 	onTimeout: standIn.optional(),
 	onFailure: standIn.optional(),
+	itemOnCancel: z.strictObject({ output: z.record(z.string(), z.unknown()) }).optional(),
 	retry: z.strictObject({
 		maxAttempts: z.number().int().min(1).max(20),
 		backoff: z.enum(["fixed", "exponential"]).optional(),
@@ -903,8 +900,7 @@ const workflowDocumentSchema = z.strictObject({
 	/** Positions and other presentation; the compiler never reads it. */
 	ui: z.record(z.string(), z.unknown()).optional()
 });
-//#endregion
-//#region src/document/compile.ts
+// src/document/compile.ts
 /** The key under which a compiled step's spec rides in its static input. */
 const SPEC_KEY = "$workflowDocument";
 /** The step type a kind runs under; a merge (`join: "any"`) is its own type, since the join is the type's. */
@@ -995,6 +991,7 @@ function compileWorkflowDocument(raw, kinds, options = {}) {
 					"timeout",
 					"onTimeout",
 					"onFailure",
+					"itemOnCancel",
 					"retry",
 					"join"
 				]) if (step[field] !== void 0) issue("shape", `${path}.${field}`, `a flow has no ${field}; set it on the steps inside`);
@@ -1011,6 +1008,7 @@ function compileWorkflowDocument(raw, kinds, options = {}) {
 			}
 			if (step.steps !== void 0 && step.kind !== "map" && step.kind !== "repeat") issue("shape", `${path}.steps`, "only a flow, a map and a repeat have steps");
 			if (step.ref !== void 0) issue("shape", `${path}.ref`, "only a flow refers to another document");
+			if (step.itemOnCancel !== void 0 && step.kind !== "map") issue("shape", `${path}.itemOnCancel`, "only a map has items to withdraw");
 			flat.set(key, {
 				key,
 				path,
@@ -1182,18 +1180,24 @@ function compileWorkflowDocument(raw, kinds, options = {}) {
 				refChain: options.refChain
 			});
 			if (!body) return null;
+			const itemOutput = bodyOutput(body);
+			const itemOnCancel = f.step.itemOnCancel;
+			if (itemOnCancel !== void 0) checkStandIn(itemOnCancel.output, itemOutput, `${f.path}.itemOnCancel.output`, issue);
 			return {
 				output: {
 					type: "object",
 					required: ["items"],
 					properties: { items: {
 						type: "array",
-						items: bodyOutput(body)
+						items: itemOutput
 					} }
 				},
 				policy: {
 					childType: stepTypeOf("map.item"),
-					childInput: { $body: body.definition }
+					childInput: {
+						$body: body.definition,
+						...itemOnCancel !== void 0 ? { $itemOnCancel: itemOnCancel } : {}
+					}
 				}
 			};
 		}
@@ -1339,7 +1343,7 @@ function compileWorkflowDocument(raw, kinds, options = {}) {
 					}
 				}
 			});
-			for (const i of found) issue("params", `${f.path}.params${i.path ? `.${i.path}` : ""}`, i.message);
+			for (const i of found) issue(i.code ?? "params", `${f.path}.params${i.path ? `.${i.path}` : ""}`, i.message);
 		}
 		for (const g of guardOf.get(key)) {
 			const r = checkExpr(g.expr, scope);
@@ -1517,8 +1521,7 @@ function checkStandIn(output, schema, path, issue) {
 	const r = zodFor(schema).safeParse(output);
 	if (!r.success) for (const i of r.error.issues) issue("schema", `${path}${i.path.length ? `.${i.path.join(".")}` : ""}`, `the stand-in doesn't fit the step's output: ${i.message}`);
 }
-//#endregion
-//#region src/document/kinds.ts
+// src/document/kinds.ts
 const KIND = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
 function defineKind(config) {
 	if (!KIND.test(config.kind)) throw new Error(`Kind "${config.kind}": a kind name is lower case, dotted (mail.send)`);
@@ -1749,8 +1752,7 @@ const coreKinds = [
 	subflowKind,
 	decideKind
 ];
-//#endregion
-//#region src/document/runtime.ts
+// src/document/runtime.ts
 const parsedExprs = /* @__PURE__ */ new Map();
 function expr(src) {
 	let e = parsedExprs.get(src);
@@ -1821,11 +1823,13 @@ const nonRetryable = (message) => err({
 */
 function thrown(error) {
 	const marked = explicitRetryability(error);
+	const continueAfterMs = continuationOf(error);
 	return err({
 		key: "step_error",
 		message: error instanceof Error ? error.message : String(error),
 		retryable: marked ?? isRetryableError(error),
-		retryableFrom: marked !== void 0 ? "explicit" : "heuristic"
+		retryableFrom: marked !== void 0 ? "explicit" : "heuristic",
+		...continueAfterMs !== void 0 && { continueAfterMs }
 	});
 }
 /**
@@ -1906,7 +1910,10 @@ function registerWorkflowKinds(registry, kinds) {
 				index: ctx.stepInput.index,
 				with: given
 			});
-		}, { stepPolicy: (stepInput) => ({ subWorkflowDefinition: stepInput.$body }) });
+		}, { stepPolicy: (stepInput) => ({
+			subWorkflowDefinition: stepInput.$body,
+			...stepInput.$itemOnCancel !== void 0 ? { onCancelled: stepInput.$itemOnCancel } : {}
+		}) });
 		for (const join of ["all", "any"]) registry.register(stepTypeOf(kind.kind, join), handler, {
 			condition,
 			join,
@@ -2019,8 +2026,7 @@ async function documentResult(store, compiled, workflowId) {
 	};
 	return Object.fromEntries(Object.entries(compiled.result).map(([name, src]) => [name, evaluate(expr(src), scope)]));
 }
-//#endregion
-//#region src/document/policy.ts
+// src/document/policy.ts
 /**
 * The policy in a set of steps (a document's, a body's, a case move's):
 *
@@ -2165,5 +2171,4 @@ function checkPublication(review, people) {
 		}
 	};
 }
-//#endregion
 export { DIVISION_SCALE, ExprSyntaxError, SPEC_KEY, WORKFLOW_DOCUMENT_FORMAT, WORKFLOW_DOCUMENT_VERSION, checkExpr, checkPublication, checkSchemaSubset, compileWorkflowDocument, coreKinds, decideKind, defineKind, describeWaitingStep, diffPolicy, documentResult, documentStepSchema, documentStepSpec, duration, evaluate, eventWaitKind, humanApproveKind, humanTaskKind, isDecimal, isDuration, mapKind, parseExpr, parseIsoDuration, registerWorkflowKinds, repeatKind, resolveParams, resumeDocumentStep, resumeWaitingStep, reviewRevision, reviewWorkflowRevision, roleSchema, sleepKind, stepTypeOf, stepsPolicy, subflowKind, toDecimal, workflowDocumentSchema, workflowPolicy, zodFor };

package/dist/drizzle/index.d.ts

@@ -1,4 +1,3 @@
-//#region src/drizzle/index.d.ts
 /**
  * `flow_workflow` — one row per run. `partition_key` is the engine's scoping
  * column: the store is bound to one partition and every query filters by it.
@@ -169,5 +168,4 @@ export declare const flowStepLeaseColumns: {
   acquiredAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>>;
   /** A lease past this instant is reaped on the next acquire. */
   expiresAt: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>;
-};
-//#endregion
+};

package/dist/drizzle/index.js

@@ -1,5 +1,5 @@
 import { bigint, bigserial, doublePrecision, integer, jsonb, text, timestamp } from "drizzle-orm/pg-core";
-//#region src/drizzle/index.ts
+// src/drizzle/index.ts
 /**
 * `octaflow/drizzle` — the engine's tables as Drizzle column sets.
 *
@@ -195,5 +195,4 @@ const flowStepLeaseColumns = {
 	/** A lease past this instant is reaped on the next acquire. */
 	expiresAt: timestamptz("expires_at").notNull()
 };
-//#endregion
 export { flowRateBucketColumns, flowStepEventColumns, flowStepLeaseColumns, flowWorkflowColumns, flowWorkflowStepColumns };

package/dist/{gate-BBZK5OgY.js → gate-BcjK7FoL.js}

@@ -1,4 +1,4 @@
-//#region src/core/store.ts
+// src/core/store.ts
 /**
 * The step statuses a step can still be settled from — by `completeStep` or
 * `failStep`. Every other status is final for those two writes: a step that
@@ -10,8 +10,7 @@ const UNSETTLED_STEP_STATUSES = [
 	"waiting",
 	"mapping"
 ];
-//#endregion
-//#region src/core/gate.ts
+// src/core/gate.ts
 /**
 * The rule keys a request is held to, in the order they are checked: the
 * step's type, then each resource it declares, without repeats. The shipped
@@ -118,5 +117,4 @@ function createInMemoryStepGate(config = {}) {
 		};
 	} };
 }
-//#endregion
 export { gateRuleKeys as n, UNSETTLED_STEP_STATUSES as r, createInMemoryStepGate as t };

package/dist/{index-BlwtmRJP.d.ts → index-BBO5BGS8.d.ts}

@@ -1,5 +1,4 @@
 import { z } from "zod";
-//#region src/core/result.d.ts
 interface FlowErrorShape {
   key: string;
   message: string;
@@ -13,8 +12,6 @@ type Result<T = void, E extends FlowErrorShape = FlowErrorShape> = {
 };
 declare const ok: <T>(value: T) => Result<T, never>;
 declare const err: <E extends FlowErrorShape>(error: E) => Result<never, E>;
-//#endregion
-//#region src/core/readiness.d.ts
 /**
  * How a step's dependencies gate it.
  *
@@ -55,8 +52,6 @@ interface ReadinessPlan {
  * @param joinOf the join rule for a step type, from its registration
  */
 declare function computeReadiness(steps: StepRecord[], joinOf: (stepType: string) => JoinRule): ReadinessPlan;
-//#endregion
-//#region src/core/types.d.ts
 /** Workflow / step identifiers. Numeric to match common bigserial-backed stores. */
 type WorkflowId = number;
 type StepId = number;
@@ -163,9 +158,23 @@ interface StepExecutionContext<TContext = unknown> {
    * `true`.
    */
   heartbeat: () => Promise<boolean>;
+  /**
+   * What an earlier attempt of this step kept (`value`, null on the first), and
+   * how this attempt keeps its own (`save`, which replaces it). For a handler
+   * that does several things that cost or change something — an agent's tool
+   * calls — so a retry after a crash picks up where the last attempt got to.
+   * `save` resolves `false` when nothing was written: the step is no longer this
+   * attempt's, or the store keeps no checkpoints.
+   */
+  checkpoint?: StepCheckpoint;
   /** Host-provided per-step context. */
   context: TContext;
 }
+/** See {@link StepExecutionContext.checkpoint}. */
+interface StepCheckpoint {
+  readonly value: unknown;
+  save(value: unknown): Promise<boolean>;
+}
 interface StepError extends FlowErrorShape {
   key: 'step_error';
   message: string;
@@ -177,6 +186,8 @@ interface StepError extends FlowErrorShape {
    * the engine's `defaultRetryable` may override those, and only those.
    */
   retryableFrom?: 'explicit' | 'predicate' | 'heuristic';
+  /** The handler threw `continueStep`: not a failure — run the step again after this many ms, without spending an attempt. */
+  continueAfterMs?: number;
 }
 type StepHandler<TContext = unknown> = (ctx: StepExecutionContext<TContext>) => Promise<Result<Record<string, unknown>, StepError>>;
 /** Context for a step's compensation handler — the execution context plus the step's own output. */
@@ -350,6 +361,15 @@ interface StepPolicy {
   waitTimeoutMs?: number;
   onTimeout?: WaitTimeoutPolicy;
   onFailure?: StepFailurePolicy;
+  /**
+   * For a step that runs a sub-workflow (a map item among them): what it completes with when that run is
+   * cancelled — `cancelWorkflow` on the child — instead of failing. The step keeps "Sub-workflow cancelled"
+   * on its `error`, and a map counts the stand-in in the item's slot. A child that *fails* still fails the
+   * step as `onFailure` says.
+   */
+  onCancelled?: {
+    output: Record<string, unknown>;
+  };
   retry?: RetryPolicy;
   /** This step starts a child workflow from this definition: the handler returns its input. */
   subWorkflowDefinition?: WorkflowDefinition;
@@ -478,8 +498,6 @@ interface WorkflowStepRunningError extends FlowErrorShape {
  * reject a start with a domain-specific error key the engine just passes through.
  */
 type FlowError = WorkflowNotFoundError | InvalidWorkflowDefinitionError | StepHandlerNotFoundError | WorkflowNotRetryableError | WorkflowStepRunningError | StepError | FlowErrorShape;
-//#endregion
-//#region src/core/defineStep.d.ts
 /**
  * A type-safe step definition with Zod validation schemas, parameterized by the
  * host `TContext`. Created by `defineStep()`, consumed by `buildWorkflow()`.
@@ -565,6 +583,8 @@ interface TypedStepContext<TInput extends Record<string, unknown>, TDeps extends
    * re-queued as dead). See `heartbeatTimeoutMs`.
    */
   heartbeat: () => Promise<boolean>;
+  /** What an earlier attempt kept, and how this one keeps its own — see `StepExecutionContext.checkpoint`. */
+  checkpoint?: StepCheckpoint;
   context: TContext;
 }
 interface DefineStepConfig<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, TDeps extends Record<string, TypedStep<any, any, any, TContext>>, TContext, TJoin extends JoinRule = 'all'> {
@@ -861,8 +881,6 @@ interface BuildWorkflowConfig<TInput extends Record<string, unknown>, TSteps ext
  * that every dependency key references a real step.
  */
 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. */
@@ -1037,8 +1055,6 @@ declare function defineDecisionOutcomeStep<Q extends DecisionQuestions, TDecisio
   /** 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';
 declare const STEP_DISPLAY_STATUS_SCHEMA: z.ZodEnum<{
@@ -1165,5 +1181,4 @@ declare function toPublicStep(step: StepRecord): PublicWorkflowStep;
  * `idempotencyKey`, `parentWorkflowId`/`parentStepId`, and `metadata`.
  */
 declare function toPublicWorkflow(workflow: WorkflowWithSteps): PublicWorkflow;
-//#endregion
-export { StepFailurePolicy as $, StepOutput as A, defineWaitStep as B, defineDecisionOutcomeStep as C, isTerminalStepStatus as Ct, resolveDecision as D, ok as Dt, functionDecider as E, err as Et, buildWorkflow as F, StartOptions as G, FlowError as H, defineMapStep as I, StepConditionHandler as J, StepCompensateHandler as K, defineSleepStep as L, TypedStepContext as M, TypedWorkflow as N, DefineStepConfig as O, WorkflowOutput as P, StepExecutionContext as Q, defineStep as R, DecisionStep as S, computeReadiness as St, defineDecisionStep as T, Result as Tt, InvalidWorkflowDefinitionError as U, DelayedStep as V, RetryPolicy as W, StepDelay as X, StepDefinition as Y, StepError as Z, DecisionOutput as _, WorkflowStepRunningError as _t, STEP_DISPLAY_STATUS as a, StepRecord as at, DecisionResponse as b, PlannedSkip as bt, WORKFLOW_STATUS_SCHEMA as c, StepStatus as ct, toPublicWorkflow as d, WorkflowDefinition as dt, StepHandler as et, Decider as f, WorkflowId as ft, DecisionOutcome as g, WorkflowStatus as gt, DecisionChoices as h, WorkflowRecord as ht, PublicWorkflowStep as i, StepPolicy as it, TypedStep as j, StepDeps as k, toDisplayStepStatus as l, WaitTimeoutPolicy as lt, DecisionAnswers as m, WorkflowNotRetryableError as mt, PUBLIC_WORKFLOW_STEP_SCHEMA as n, StepHandlerRegistry as nt, STEP_DISPLAY_STATUS_SCHEMA as o, StepRegistration as ot, DecisionAnswer as p, WorkflowNotFoundError as pt, StepCompensationContext as q, PublicWorkflow as r, StepId as rt, StepDisplayStatus as s, StepRepeat as st, PUBLIC_WORKFLOW_SCHEMA as t, StepHandlerNotFoundError as tt, toPublicStep as u, WorkflowCreatedResult as ut, DecisionQuestions as v, WorkflowWithSteps as vt, defineDecisionReviewStep as w, FlowErrorShape as wt, DecisionReview as x, ReadinessPlan as xt, DecisionRequest as y, JoinRule as yt, defineSubWorkflowStep as z };
+export { StepExecutionContext as $, StepOutput as A, defineWaitStep as B, defineDecisionOutcomeStep as C, computeReadiness as Ct, resolveDecision as D, err as Dt, functionDecider as E, Result as Et, buildWorkflow as F, StartOptions as G, FlowError as H, defineMapStep as I, StepCompensationContext as J, StepCheckpoint as K, defineSleepStep as L, TypedStepContext as M, TypedWorkflow as N, DefineStepConfig as O, ok as Ot, WorkflowOutput as P, StepError as Q, defineStep as R, DecisionStep as S, ReadinessPlan as St, defineDecisionStep as T, FlowErrorShape as Tt, InvalidWorkflowDefinitionError as U, DelayedStep as V, RetryPolicy as W, StepDefinition as X, StepConditionHandler as Y, StepDelay as Z, DecisionOutput as _, WorkflowStatus as _t, STEP_DISPLAY_STATUS as a, StepPolicy as at, DecisionResponse as b, JoinRule as bt, WORKFLOW_STATUS_SCHEMA as c, StepRepeat as ct, toPublicWorkflow as d, WorkflowCreatedResult as dt, StepFailurePolicy as et, Decider as f, WorkflowDefinition as ft, DecisionOutcome as g, WorkflowRecord as gt, DecisionChoices as h, WorkflowNotRetryableError as ht, PublicWorkflowStep as i, StepId as it, TypedStep as j, StepDeps as k, toDisplayStepStatus as l, StepStatus as lt, DecisionAnswers as m, WorkflowNotFoundError as mt, PUBLIC_WORKFLOW_STEP_SCHEMA as n, StepHandlerNotFoundError as nt, STEP_DISPLAY_STATUS_SCHEMA as o, StepRecord as ot, DecisionAnswer as p, WorkflowId as pt, StepCompensateHandler as q, PublicWorkflow as r, StepHandlerRegistry as rt, StepDisplayStatus as s, StepRegistration as st, PUBLIC_WORKFLOW_SCHEMA as t, StepHandler as tt, toPublicStep as u, WaitTimeoutPolicy as ut, DecisionQuestions as v, WorkflowStepRunningError as vt, defineDecisionReviewStep as w, isTerminalStepStatus as wt, DecisionReview as x, PlannedSkip as xt, DecisionRequest as y, WorkflowWithSteps as yt, defineSubWorkflowStep as z };

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-import { $ as StepFailurePolicy, A as StepOutput, B as defineWaitStep, C as defineDecisionOutcomeStep, Ct as isTerminalStepStatus, D as resolveDecision, Dt as ok, E as functionDecider, Et as err, F as buildWorkflow, G as StartOptions, H as FlowError, I as defineMapStep, J as StepConditionHandler, K as StepCompensateHandler, L as defineSleepStep, M as TypedStepContext, N as TypedWorkflow, O as DefineStepConfig, P as WorkflowOutput, Q as StepExecutionContext, R as defineStep, S as DecisionStep, St as computeReadiness, T as defineDecisionStep, Tt as Result, U as InvalidWorkflowDefinitionError, V as DelayedStep, W as RetryPolicy, X as StepDelay, Y as StepDefinition, Z as StepError, _ as DecisionOutput, _t as WorkflowStepRunningError, a as STEP_DISPLAY_STATUS, at as StepRecord, b as DecisionResponse, bt as PlannedSkip, c as WORKFLOW_STATUS_SCHEMA, ct as StepStatus, d as toPublicWorkflow, dt as WorkflowDefinition, et as StepHandler, f as Decider, ft as WorkflowId, g as DecisionOutcome, gt as WorkflowStatus, h as DecisionChoices, ht as WorkflowRecord, i as PublicWorkflowStep, it as StepPolicy, j as TypedStep, k as StepDeps, l as toDisplayStepStatus, lt as WaitTimeoutPolicy, m as DecisionAnswers, mt as WorkflowNotRetryableError, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as StepHandlerRegistry, o as STEP_DISPLAY_STATUS_SCHEMA, ot as StepRegistration, p as DecisionAnswer, pt as WorkflowNotFoundError, q as StepCompensationContext, r as PublicWorkflow, rt as StepId, s as StepDisplayStatus, st as StepRepeat, t as PUBLIC_WORKFLOW_SCHEMA, tt as StepHandlerNotFoundError, u as toPublicStep, ut as WorkflowCreatedResult, v as DecisionQuestions, vt as WorkflowWithSteps, w as defineDecisionReviewStep, wt as FlowErrorShape, x as DecisionReview, xt as ReadinessPlan, y as DecisionRequest, yt as JoinRule, z as defineSubWorkflowStep } from "./index-BlwtmRJP.js";
-import { a as LogAttributes, i as EnqueueOptions, n as DispatchStepPayload, o as Logger, r as Dispatcher, s as noopLogger, t as DispatchKind } from "./dispatcher-jbFVHfdm.js";
-import { a as CreatedWorkflow, c as ListWorkflowsFilters, d as UNSETTLED_STEP_STATUSES, f as WorkflowStore, i as CreateWorkflowStep, l as ReopenWorkflowParams, n as CompleteStepParams, o as FailStepParams, p as WorkflowTreeFilter, r as CreateWorkflowParams, s as FinishWorkflowParams, t as AddChildStep, u as TransactionalScope } from "./store-BPHVI_a3.js";
-import { C as gateRuleKeys, S as createInMemoryStepGate, _ 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, 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, x as StepGateRequest, y as StepGate } from "./observability-BgUtESlj.js";
-//#region src/core/hooks.d.ts
+import { $ as StepExecutionContext, A as StepOutput, B as defineWaitStep, C as defineDecisionOutcomeStep, Ct as computeReadiness, D as resolveDecision, Dt as err, E as functionDecider, Et as Result, F as buildWorkflow, G as StartOptions, H as FlowError, I as defineMapStep, J as StepCompensationContext, K as StepCheckpoint, L as defineSleepStep, M as TypedStepContext, N as TypedWorkflow, O as DefineStepConfig, Ot as ok, P as WorkflowOutput, Q as StepError, R as defineStep, S as DecisionStep, St as ReadinessPlan, T as defineDecisionStep, Tt as FlowErrorShape, U as InvalidWorkflowDefinitionError, V as DelayedStep, W as RetryPolicy, X as StepDefinition, Y as StepConditionHandler, Z as StepDelay, _ as DecisionOutput, _t as WorkflowStatus, a as STEP_DISPLAY_STATUS, at as StepPolicy, b as DecisionResponse, bt as JoinRule, c as WORKFLOW_STATUS_SCHEMA, ct as StepRepeat, d as toPublicWorkflow, dt as WorkflowCreatedResult, et as StepFailurePolicy, f as Decider, ft as WorkflowDefinition, g as DecisionOutcome, gt as WorkflowRecord, h as DecisionChoices, ht as WorkflowNotRetryableError, i as PublicWorkflowStep, it as StepId, j as TypedStep, k as StepDeps, l as toDisplayStepStatus, lt as StepStatus, m as DecisionAnswers, mt as WorkflowNotFoundError, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as StepHandlerNotFoundError, o as STEP_DISPLAY_STATUS_SCHEMA, ot as StepRecord, p as DecisionAnswer, pt as WorkflowId, q as StepCompensateHandler, r as PublicWorkflow, rt as StepHandlerRegistry, s as StepDisplayStatus, st as StepRegistration, t as PUBLIC_WORKFLOW_SCHEMA, tt as StepHandler, u as toPublicStep, ut as WaitTimeoutPolicy, v as DecisionQuestions, vt as WorkflowStepRunningError, w as defineDecisionReviewStep, wt as isTerminalStepStatus, x as DecisionReview, xt as PlannedSkip, y as DecisionRequest, yt as WorkflowWithSteps, z as defineSubWorkflowStep } from "./index-BBO5BGS8.js";
+import { a as LogAttributes, i as EnqueueOptions, n as DispatchStepPayload, o as Logger, r as Dispatcher, s as noopLogger, t as DispatchKind } from "./dispatcher-BnlAJuu3.js";
+import { a as CreatedWorkflow, c as ListWorkflowsFilters, d as UNSETTLED_STEP_STATUSES, f as WorkflowStore, i as CreateWorkflowStep, l as ReopenWorkflowParams, n as CompleteStepParams, o as FailStepParams, p as WorkflowTreeFilter, r as CreateWorkflowParams, s as FinishWorkflowParams, t as AddChildStep, u as TransactionalScope } from "./store-oCpqAuTT.js";
+import { C as gateRuleKeys, S as createInMemoryStepGate, _ 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, 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, x as StepGateRequest, y as StepGate } from "./observability-C-wtcDDo.js";
 export interface BeforeStartArgs {
   definition: WorkflowDefinition;
   input: Record<string, unknown>;
@@ -55,16 +54,12 @@ export interface WorkflowHooks<TContext = unknown> {
   /** Runs once when a workflow reaches `completed` (e.g. daily usage rollup). */
   onWorkflowCompleted?(args: WorkflowCompletedArgs): Promise<void>;
 }
-//#endregion
-//#region src/core/registry.d.ts
 /**
  * Creates an in-memory step handler registry.
  * Populate it at application startup (e.g. by registering every workflow's steps).
  * Each registration carries the handler plus its optional retry/timeout policy.
  */
 export declare function createStepHandlerRegistry<TContext = unknown>(): StepHandlerRegistry<TContext>;
-//#endregion
-//#region src/core/retry.d.ts
 /**
  * Tag an error with an explicit retryability decision, overriding both the
  * step predicate and the message heuristic. Returns the same error, so it can
@@ -105,8 +100,17 @@ export declare function explicitRetryability(error: unknown): boolean | undefine
  * `defaultRetryable` when the answer matters.
  */
 export declare function isRetryableError(error: unknown): boolean;
-//#endregion
-//#region src/core/engine.d.ts
+/**
+ * Throw this from a handler to stop now and run again later, without spending
+ * an attempt: the engine puts the step back to `pending` and re-queues it
+ * after `afterMs`. For a handler that works in slices of wall-clock time — a
+ * host with a hard request ceiling — and keeps its progress in
+ * `ctx.checkpoint`, so the next run goes on from there. Nothing caps how
+ * often a step continues; the handler's own limits must.
+ */
+export declare function continueStep(afterMs?: number, message?: string): Error;
+/** The delay a {@link continueStep} error asks for, or `undefined` for any other error. */
+export declare function continuationOf(error: unknown): number | undefined;
 export interface WorkflowEngineConfig {
   /** The dispatcher's per-step expiry, in seconds. Used by the stuck-step sweeper. Default 600. */
   stepExpirySeconds?: number;
@@ -205,8 +209,6 @@ export declare function createWorkflowEngine<TContext = unknown>(deps: WorkflowE
   }) => Promise<Result<WorkflowWithSteps[], FlowError>>;
 };
 export type WorkflowEngine<TContext = unknown> = ReturnType<typeof createWorkflowEngine<TContext>>;
-//#endregion
-//#region src/core/in-memory-store.d.ts
 /**
  * Reference `WorkflowStore` backed by plain Maps. Intended for tests and single-
  * process experimentation — NOT durable. Partition-scoped at construction to
@@ -220,5 +222,4 @@ export declare function createInMemoryWorkflowStore(partitionKey?: string): Work
     steps: StepRecord[];
   };
 };
-//#endregion
-export { AddChildStep, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, Decider, DecisionAnswer, DecisionAnswers, DecisionChoices, DecisionOutcome, DecisionOutput, DecisionQuestions, DecisionRequest, DecisionResponse, DecisionReview, DecisionStep, DefineStepConfig, DelayedStep, 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, StepDelay, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepFailurePolicy, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepPolicy, StepRecord, StepRegistration, StepRepeat, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, UNSETTLED_STEP_STATUSES, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCreatedResult, WorkflowDefinition, 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, gateRuleKeys, isTerminalStepStatus, noopLogger, noopObserver, noopTracer, ok, resolveDecision, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { AddChildStep, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, Decider, DecisionAnswer, DecisionAnswers, DecisionChoices, DecisionOutcome, DecisionOutput, DecisionQuestions, DecisionRequest, DecisionResponse, DecisionReview, DecisionStep, DefineStepConfig, DelayedStep, 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, StepCheckpoint, StepCompensateHandler, StepCompensationContext, StepConditionHandler, StepDefinition, StepDelay, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepFailurePolicy, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepPolicy, StepRecord, StepRegistration, StepRepeat, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, UNSETTLED_STEP_STATUSES, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCreatedResult, WorkflowDefinition, 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, gateRuleKeys, isTerminalStepStatus, noopLogger, noopObserver, noopTracer, ok, resolveDecision, toDisplayStepStatus, toPublicStep, toPublicWorkflow };

package/dist/index.js

@@ -1,14 +1,13 @@
-import { n as ok, t as err } from "./result-CG_l7xQm.js";
-import { n as gateRuleKeys, r as UNSETTLED_STEP_STATUSES, t as createInMemoryStepGate } from "./gate-BBZK5OgY.js";
-import { C as nonRetryableError, S as markRetryable, _ 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-COMWflJl.js";
-//#region src/core/logger.ts
+import { n as ok, t as err } from "./result-CxvNy9B6.js";
+import { n as gateRuleKeys, r as UNSETTLED_STEP_STATUSES, t as createInMemoryStepGate } from "./gate-BcjK7FoL.js";
+import { C as isRetryableError, E as retryableError, S as explicitRetryability, T as nonRetryableError, _ as defineStep, a as WORKFLOW_STATUS_SCHEMA, b as continuationOf, 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 markRetryable, x as continueStep, y as defineWaitStep } from "./core-ut8VZ0sU.js";
+// src/core/logger.ts
 const noopLogger = {
 	info() {},
 	warn() {},
 	error() {}
 };
-//#endregion
-//#region src/core/readiness.ts
+// src/core/readiness.ts
 /** Statuses a step can no longer move out of on its own. */
 const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
 	"completed",
@@ -74,8 +73,7 @@ function computeReadiness(steps, joinOf) {
 		skip
 	};
 }
-//#endregion
-//#region src/core/observability.ts
+// src/core/observability.ts
 const noopObserver = { record() {} };
 function createRecordingObserver() {
 	const events = [];
@@ -199,8 +197,7 @@ function createRecordingTracer() {
 		}
 	};
 }
-//#endregion
-//#region src/core/registry.ts
+// src/core/registry.ts
 /**
 * Creates an in-memory step handler registry.
 * Populate it at application startup (e.g. by registering every workflow's steps).
@@ -244,8 +241,7 @@ function createStepHandlerRegistry() {
 		}
 	};
 }
-//#endregion
-//#region src/core/engine.ts
+// src/core/engine.ts
 /**
 * Run a handler under an optional wall-clock timeout. On expiry the abort signal
 * is fired (cooperative handlers stop) and a retryable timeout error is returned —
@@ -476,6 +472,7 @@ function createWorkflowEngine(deps) {
 			waitTimeoutMs: own.waitTimeoutMs ?? registration?.timeoutMs,
 			onTimeout: own.onTimeout ?? registration?.onTimeout ?? "fail",
 			onFailure: own.onFailure ?? registration?.onFailure ?? "fail",
+			onCancelled: own.onCancelled,
 			retry: own.retry ?? registration?.retry,
 			subWorkflowDefinition: own.subWorkflowDefinition ?? registration?.subWorkflowDefinition,
 			childType: own.childType ?? registration?.childType,
@@ -765,6 +762,39 @@ function createWorkflowEngine(deps) {
 	function start(workflow, input, options) {
 		return startWorkflow(workflow.definition, workflow.inputSchema.parse(input), options);
 	}
+	/**
+	* A handler yielded with `continueStep`: hand the step back without spending
+	* the attempt and run it again after `afterMs`. The release is fenced by the
+	* claim, so a superseded invocation re-queues nothing.
+	*/
+	async function continueLater(workflow, step, attemptNo, afterMs) {
+		const workflowId = workflow.id;
+		if (!await store.releaseStep(step.id, attemptNo)) {
+			logger.warn("Discarding the continuation of a superseded step", {
+				workflowId,
+				stepId: step.id,
+				stepKey: step.key,
+				attempt: attemptNo
+			});
+			return;
+		}
+		logger.info("Step continues later", {
+			workflowId,
+			stepId: step.id,
+			stepKey: step.key,
+			afterMs
+		});
+		const re = await dispatcher.enqueueStep({
+			workflowId,
+			stepId: step.id,
+			stepKey: step.key,
+			stepType: step.type
+		}, { startAfterSeconds: Math.ceil(afterMs / 1e3) });
+		if (!re.ok) await failOrDefault(workflowId, step, `the step could not be queued to continue: ${re.error.message}`, {
+			workflowType: workflow.type,
+			attempt: attemptNo
+		});
+	}
 	async function executeStep(workflowId, stepId) {
 		const workflow = await store.getWorkflow(workflowId);
 		if (!workflow) return {
@@ -956,6 +986,10 @@ function createWorkflowEngine(deps) {
 					dependencyOutputs,
 					signal: abort.signal,
 					heartbeat: heartbeat.beat,
+					checkpoint: {
+						value: step.metadata?.checkpoint ?? null,
+						save: (value) => store.saveStepCheckpoint ? store.saveStepCheckpoint(stepId, attemptNo, value) : Promise.resolve(false)
+					},
 					context
 				};
 				const guard = registration.condition ? await registration.condition(ctx) : void 0;
@@ -1063,6 +1097,13 @@ function createWorkflowEngine(deps) {
 						value: void 0
 					};
 				}
+				if (handlerResult.error.continueAfterMs !== void 0) {
+					await continueLater(workflow, step, attemptNo, handlerResult.error.continueAfterMs);
+					return {
+						ok: true,
+						value: void 0
+					};
+				}
 				if ((handlerResult.error.retryableFrom === "heuristic" && defaultRetryable !== void 0 ? defaultRetryable : handlerResult.error.retryable) && attemptNo < maxAttempts) {
 					const delaySeconds = backoffDelaySeconds(retry, attemptNo);
 					logger.info("Retrying step", {
@@ -1115,6 +1156,14 @@ function createWorkflowEngine(deps) {
 					value: void 0
 				};
 			} catch (error) {
+				const afterMs = continuationOf(error);
+				if (afterMs !== void 0 && !heartbeat.lost) {
+					await continueLater(workflow, step, attemptNo, afterMs);
+					return {
+						ok: true,
+						value: void 0
+					};
+				}
 				const message = error instanceof Error ? error.message : "Unknown step execution error";
 				logger.error("Step execution threw", error instanceof Error ? error : new Error(message), {
 					workflowId,
@@ -1531,6 +1580,25 @@ function createWorkflowEngine(deps) {
 				else await onStepCompleted(child.parentWorkflowId, child.parentStepId, done);
 			} else if (parentStep.parentStepId != null) await onChildCompleted(child.parentWorkflowId, parentStep, output);
 			else await onStepCompleted(child.parentWorkflowId, child.parentStepId, output);
+		} else if (child.status === "cancelled" && policyOf(parentStep).onCancelled) {
+			const message = "Sub-workflow cancelled";
+			const standIn = policyOf(parentStep).onCancelled.output;
+			const announce = () => emit({
+				type: "step.defaulted",
+				workflowId: child.parentWorkflowId,
+				stepId: parentStep.id,
+				stepKey: parentStep.key,
+				stepType: parentStep.type,
+				error: message
+			});
+			if (parentStep.parentStepId != null) await onChildCompleted(child.parentWorkflowId, parentStep, standIn, {
+				error: message,
+				announce
+			});
+			else await onStepCompleted(child.parentWorkflowId, child.parentStepId, standIn, {
+				error: message,
+				announce
+			});
 		} else await failOrDefault(child.parentWorkflowId, parentStep, `Sub-workflow ${child.status}${child.error ? `: ${child.error}` : ""}`);
 		logger.info("Bridged sub-workflow to parent step", {
 			childWorkflowId,
@@ -2092,8 +2160,7 @@ function createWorkflowEngine(deps) {
 		listWorkflows
 	};
 }
-//#endregion
-//#region src/core/in-memory-store.ts
+// src/core/in-memory-store.ts
 /**
 * Reference `WorkflowStore` backed by plain Maps. Intended for tests and single-
 * process experimentation — NOT durable. Partition-scoped at construction to
@@ -2190,6 +2257,15 @@ function createInMemoryWorkflowStore(partitionKey = "default") {
 		s.attempts += 1;
 		return true;
 	}
+	async function saveStepCheckpoint(stepId, attempt, value) {
+		const s = steps.get(stepId);
+		if (!s || s.status !== "running" || s.attempts !== attempt) return false;
+		s.metadata = {
+			...s.metadata ?? {},
+			checkpoint: clone(value)
+		};
+		return true;
+	}
 	async function heartbeatStep(stepId, at) {
 		const s = steps.get(stepId);
 		if (!s || s.status !== "running") return false;
@@ -2198,6 +2274,14 @@ function createInMemoryWorkflowStore(partitionKey = "default") {
 		s.heartbeatAt = at;
 		return true;
 	}
+	async function releaseStep(stepId, attempt) {
+		const s = steps.get(stepId);
+		if (!s || s.status !== "running" || s.attempts !== attempt) return false;
+		s.status = "pending";
+		s.attempts -= 1;
+		s.heartbeatAt = null;
+		return true;
+	}
 	async function markStepPending(stepId) {
 		const s = steps.get(stepId);
 		if (s) s.status = "pending";
@@ -2386,7 +2470,9 @@ function createInMemoryWorkflowStore(partitionKey = "default") {
 		listSteps,
 		markStepRunning,
 		heartbeatStep,
+		saveStepCheckpoint,
 		markStepPending,
+		releaseStep,
 		markStepWaiting,
 		markStepMapping,
 		markStepCompensating,
@@ -2414,5 +2500,4 @@ function createInMemoryWorkflowStore(partitionKey = "default") {
 		}
 	};
 }
-//#endregion
-export { PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, UNSETTLED_STEP_STATUSES, WORKFLOW_STATUS_SCHEMA, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createInMemoryWorkflowStore, createMeterObserver, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineDecisionOutcomeStep, defineDecisionReviewStep, defineDecisionStep, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, functionDecider, gateRuleKeys, isRetryableError, isTerminalStepStatus, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, resolveDecision, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, UNSETTLED_STEP_STATUSES, WORKFLOW_STATUS_SCHEMA, buildWorkflow, combineObservers, computeReadiness, continuationOf, continueStep, createInMemoryStepGate, createInMemoryWorkflowStore, createMeterObserver, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineDecisionOutcomeStep, defineDecisionReviewStep, defineDecisionStep, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, functionDecider, gateRuleKeys, isRetryableError, isTerminalStepStatus, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, resolveDecision, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };

package/dist/{observability-BgUtESlj.d.ts → observability-C-wtcDDo.d.ts}

@@ -1,5 +1,4 @@
-import { ft as WorkflowId, rt as StepId } from "./index-BlwtmRJP.js";
-//#region src/core/gate.d.ts
+import { it as StepId, pt as WorkflowId } from "./index-BBO5BGS8.js";
 interface StepGateRequest {
   partitionKey: string;
   workflowId: WorkflowId;
@@ -77,8 +76,6 @@ interface InMemoryStepGateConfig {
  * for multi-worker concurrency control.
  */
 declare function createInMemoryStepGate(config?: InMemoryStepGateConfig): StepGate;
-//#endregion
-//#region src/core/observability.d.ts
 /** 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`. */
@@ -199,5 +196,4 @@ interface RecordingTracer extends FlowTracer {
   readonly spans: RecordedSpan[];
 }
 declare function createRecordingTracer(): RecordingTracer;
-//#endregion
 export { gateRuleKeys as C, createInMemoryStepGate as S, 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, 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, StepGateRequest as x, StepGate as y };

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

@@ -1,8 +1,7 @@
-import "../index-BlwtmRJP.js";
-import { o as Logger, r as Dispatcher } from "../dispatcher-jbFVHfdm.js";
+import "../index-BBO5BGS8.js";
+import { o as Logger, r as Dispatcher } from "../dispatcher-BnlAJuu3.js";
 import { z } from "zod";
 import { PgBoss, Schedule } from "pg-boss";
-//#region src/pg-boss/payload.d.ts
 /**
  * The wire payload for a step job. It is the flow-core `DispatchStepPayload`
  * plus the `partitionKey` — the worker needs the partition to reconstruct a
@@ -64,8 +63,6 @@ export interface StartJobContext extends WireStartPayload {
 }
 /** Resolve the per-delivery idempotency key. Explicit key wins over a prefix. */
 export declare function resolveStartIdempotencyKey(payload: WireStartPayload, jobId: string): string | undefined;
-//#endregion
-//#region src/pg-boss/queue.d.ts
 /**
  * Create the step queue and its dead-letter queue if they do not exist. Call
  * once at startup; the dispatcher also runs it from `prepare` and lazily on a
@@ -146,8 +143,6 @@ export declare function createPgBossDlqWorker(deps: PgBossDlqWorkerDeps): {
   start: (onDlq: DlqProcessor) => Promise<void>;
   stop: () => Promise<void>;
 };
-//#endregion
-//#region src/pg-boss/scheduler.d.ts
 /** Create the start queue (idempotent). */
 export declare function ensureStartQueue(boss: PgBoss, queueName: string): Promise<void>;
 export interface PgBossSchedulerDeps {
@@ -221,5 +216,4 @@ export interface PgBossStartWorkerDeps {
 export declare function createPgBossStartWorker(deps: PgBossStartWorkerDeps): {
   start: (process: StartJobProcessor) => Promise<void>;
   stop: () => Promise<void>;
-};
-//#endregion
+};

package/dist/pg-boss/index.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-//#region src/pg-boss/payload.ts
+// src/pg-boss/payload.ts
 /**
 * The wire payload for a step job. It is the flow-core `DispatchStepPayload`
 * plus the `partitionKey` — the worker needs the partition to reconstruct a
@@ -51,8 +51,7 @@ function resolveStartIdempotencyKey(payload, jobId) {
 	if (payload.idempotencyKey !== void 0) return payload.idempotencyKey;
 	if (payload.idempotencyKeyPrefix !== void 0) return `${payload.idempotencyKeyPrefix}:${jobId}`;
 }
-//#endregion
-//#region src/pg-boss/queue.ts
+// src/pg-boss/queue.ts
 function dlqName(queueName) {
 	return `${queueName}-dlq`;
 }
@@ -323,8 +322,7 @@ function createPgBossDlqWorker(deps) {
 		stop
 	};
 }
-//#endregion
-//#region src/pg-boss/scheduler.ts
+// src/pg-boss/scheduler.ts
 /** Create the start queue (idempotent). */
 async function ensureStartQueue(boss, queueName) {
 	try {
@@ -432,5 +430,4 @@ function createPgBossStartWorker(deps) {
 		stop
 	};
 }
-//#endregion
 export { DEFAULT_STEP_QUEUE_CONFIG, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue, resolveStartIdempotencyKey };

package/dist/postgres/index.d.ts

@@ -1,8 +1,7 @@
-import { ft as WorkflowId } from "../index-BlwtmRJP.js";
-import { f as WorkflowStore } from "../store-BPHVI_a3.js";
-import { g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-BgUtESlj.js";
+import { pt as WorkflowId } from "../index-BBO5BGS8.js";
+import { f as WorkflowStore } from "../store-oCpqAuTT.js";
+import { g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-C-wtcDDo.js";
 import { Pool } from "pg";
-//#region src/postgres/ddl.d.ts
 /**
  * Schema for the Postgres WorkflowStore adapter. Two tables mirror flow-core's
  * record shapes. Apply once at deploy time (or call `applySchema`).
@@ -15,8 +14,6 @@ export declare function flowStoreDdl(schema?: string): string;
 export declare const FLOW_STORE_DDL: string;
 /** `CREATE SCHEMA IF NOT EXISTS` line for non-default schemas; empty for 'public'. */
 export declare function createSchemaDdl(schema: string): string;
-//#endregion
-//#region src/postgres/executor.d.ts
 /** Minimal query result shape the adapters consume (a structural subset of `pg`'s `QueryResult`). */
 export interface SqlResult<R> {
   rows: R[];
@@ -103,8 +100,6 @@ export declare function pgliteExecutor(db: PgliteDatabaseLike): SqlExecutor;
  * its `transaction` method (a `pg` `Pool` has none).
  */
 export declare function toExecutor(db: Pool | SqlExecutor): SqlExecutor;
-//#endregion
-//#region src/postgres/store.d.ts
 export interface PgWorkflowStoreDeps {
   pool: Pool;
   /** Partition this store instance is bound to (e.g. a tenant id). */
@@ -141,8 +136,6 @@ export declare function createWorkflowStore(deps: WorkflowStoreDeps): WorkflowSt
 export declare function createPgWorkflowStore(deps: PgWorkflowStoreDeps): WorkflowStore;
 /** Convenience: apply the flow-store schema to a database. */
 export declare function applySchema(pool: Pool, ddl: string): Promise<void>;
-//#endregion
-//#region src/postgres/gate.d.ts
 /** DDL for the gate's two tables. Apply once at deploy time (or via `applySchema`). */
 export declare function flowGateDdl(opts?: {
   schema?: string;
@@ -189,8 +182,6 @@ export declare function createStepGate(config: StepGateConfig): StepGate;
  * Level Security should build an executor and call {@link createStepGate}.
  */
 export declare function createPgStepGate(config: PgStepGateConfig): StepGate;
-//#endregion
-//#region src/postgres/event-sink.d.ts
 /**
  * DDL for the append-only run-history table. Apply once at deploy time (alongside
  * `flowStoreDdl`), or call `applySchema(pool, flowEventDdl())`.
@@ -244,5 +235,4 @@ export declare function readFlowEvents(db: Pool | SqlExecutor, params: {
   workflowId: WorkflowId;
   partitionKey: string;
   schema?: string;
-}): Promise<FlowEvent[]>;
-//#endregion
+}): Promise<FlowEvent[]>;

package/dist/postgres/index.js

@@ -1,6 +1,6 @@
-import { n as gateRuleKeys, r as UNSETTLED_STEP_STATUSES } from "../gate-BBZK5OgY.js";
-import "../core-COMWflJl.js";
-//#region src/postgres/ddl.ts
+import { n as gateRuleKeys, r as UNSETTLED_STEP_STATUSES } from "../gate-BcjK7FoL.js";
+import "../core-ut8VZ0sU.js";
+// src/postgres/ddl.ts
 /**
 * Schema for the Postgres WorkflowStore adapter. Two tables mirror flow-core's
 * record shapes. Apply once at deploy time (or call `applySchema`).
@@ -80,8 +80,7 @@ const FLOW_STORE_DDL = flowStoreDdl();
 function createSchemaDdl(schema) {
 	return schema === "public" ? "" : `CREATE SCHEMA IF NOT EXISTS ${schema};\n\n`;
 }
-//#endregion
-//#region src/postgres/executor.ts
+// src/postgres/executor.ts
 /**
 * Build a {@link SqlExecutor} over a `pg` {@link Pool}: top-level queries run on
 * the pool (autocommit); `transaction` checks out a client and wraps `fn` in
@@ -195,8 +194,7 @@ function pgliteExecutor(db) {
 function toExecutor(db) {
 	return "transaction" in db ? db : poolExecutor(db);
 }
-//#endregion
-//#region src/postgres/store.ts
+// src/postgres/store.ts
 const iso = (v) => v == null ? null : v instanceof Date ? v.toISOString() : v;
 function mapWorkflow(r) {
 	return {
@@ -322,6 +320,15 @@ function createWorkflowStore(deps) {
 			partitionKey
 		])).rowCount ?? 0) > 0;
 	}
+	async function saveStepCheckpoint(stepId, attempt, value) {
+		return ((await exec.query(`UPDATE ${STEP} SET metadata = jsonb_set(COALESCE(metadata, '{}'::jsonb), '{checkpoint}', $2::text::jsonb)
+        WHERE id = $1 AND partition_key = $3 AND status = 'running' AND attempts = $4`, [
+			stepId,
+			JSON.stringify(value ?? null, (_k, v) => typeof v === "string" ? v.replaceAll("\0", "") : v),
+			partitionKey,
+			attempt
+		])).rowCount ?? 0) > 0;
+	}
 	async function heartbeatStep(stepId, at) {
 		return ((await exec.query(`UPDATE ${STEP} s SET heartbeat_at = $2
          FROM ${WF} w
@@ -334,6 +341,14 @@ function createWorkflowStore(deps) {
 			partitionKey
 		])).rowCount ?? 0) > 0;
 	}
+	async function releaseStep(stepId, attempt) {
+		return ((await exec.query(`UPDATE ${STEP} SET status = 'pending', attempts = attempts - 1, heartbeat_at = NULL
+        WHERE id = $1 AND partition_key = $2 AND status = 'running' AND attempts = $3`, [
+			stepId,
+			partitionKey,
+			attempt
+		])).rowCount ?? 0) > 0;
+	}
 	async function markStepPending(stepId) {
 		await exec.query(`UPDATE ${STEP} SET status = 'pending' WHERE id = $1 AND partition_key = $2`, [stepId, partitionKey]);
 	}
@@ -569,7 +584,9 @@ function createWorkflowStore(deps) {
 		listSteps,
 		markStepRunning,
 		heartbeatStep,
+		saveStepCheckpoint,
 		markStepPending,
+		releaseStep,
 		markStepWaiting,
 		markStepMapping,
 		markStepCompensating,
@@ -609,8 +626,7 @@ function createPgWorkflowStore(deps) {
 async function applySchema(pool, ddl) {
 	await pool.query(ddl);
 }
-//#endregion
-//#region src/postgres/gate.ts
+// src/postgres/gate.ts
 const DEFAULT_RATE_TABLE = "flow_rate_bucket";
 const DEFAULT_LEASE_TABLE = "flow_step_lease";
 /** DDL for the gate's two tables. Apply once at deploy time (or via `applySchema`). */
@@ -768,8 +784,7 @@ function createPgStepGate(config) {
 		...rest
 	});
 }
-//#endregion
-//#region src/postgres/event-sink.ts
+// src/postgres/event-sink.ts
 /**
 * DDL for the append-only run-history table. Apply once at deploy time (alongside
 * `flowStoreDdl`), or call `applySchema(pool, flowEventDdl())`.
@@ -868,5 +883,4 @@ async function readFlowEvents(db, params) {
 		error: r.error ?? void 0
 	}));
 }
-//#endregion
 export { FLOW_EVENT_DDL, FLOW_GATE_DDL, FLOW_STORE_DDL, applySchema, createEventSink, createPgEventSink, createPgStepGate, createPgWorkflowStore, createSchemaDdl, createStepGate, createWorkflowStore, flowEventDdl, flowGateDdl, flowStoreDdl, pgliteExecutor, poolExecutor, postgresJsExecutor, readFlowEvents, toExecutor };

package/dist/{result-CG_l7xQm.js → result-CxvNy9B6.js}

@@ -1,4 +1,4 @@
-//#region src/core/result.ts
+// src/core/result.ts
 const ok = (value) => ({
 	ok: true,
 	value
@@ -7,5 +7,4 @@ const err = (error) => ({
 	ok: false,
 	error
 });
-//#endregion
 export { ok as n, err as t };

package/dist/{store-BPHVI_a3.d.ts → store-oCpqAuTT.d.ts}

@@ -1,5 +1,4 @@
-import { at as StepRecord, ft as WorkflowId, gt as WorkflowStatus, ht as WorkflowRecord, rt as StepId, vt as WorkflowWithSteps } from "./index-BlwtmRJP.js";
-//#region src/core/store.d.ts
+import { _t as WorkflowStatus, gt as WorkflowRecord, it as StepId, ot as StepRecord, pt as WorkflowId, yt as WorkflowWithSteps } from "./index-BBO5BGS8.js";
 interface CreateWorkflowStep {
   key: string;
   type: string;
@@ -171,6 +170,16 @@ interface WorkflowStore {
   markStepRunning(stepId: StepId, startedAt: string): Promise<boolean>;
   /** Reset a step to `pending` for a scheduled retry (leaves `attempts` as-is). */
   markStepPending(stepId: StepId): Promise<void>;
+  /**
+   * Hand a running step back to `pending` **without spending the attempt** — a
+   * handler that continues later (`continueStep`): `attempts` goes back by one,
+   * and the heartbeat is cleared. Returns whether it wrote.
+   *
+   * Implementations MUST write only while the step is `running` on `attempt`
+   * (one conditional statement), like `saveStepCheckpoint`: a worker the sweeper
+   * gave up on must not hand back a step another attempt now runs.
+   */
+  releaseStep(stepId: StepId, attempt: number): Promise<boolean>;
   /**
    * Stamp `heartbeatAt` on a step whose handler is still working, and report
    * whether that step is still the caller's to run.
@@ -188,6 +197,18 @@ interface WorkflowStore {
    * they own it. One statement, not a read-then-write: the sweeper races it.
    */
   heartbeatStep(stepId: StepId, at: string): Promise<boolean>;
+  /**
+   * Keep what a running step has done so far, for the next attempt of the same
+   * step: `value` (JSON) under `metadata.checkpoint`, replacing the last one.
+   * Returns whether it was written.
+   *
+   * Implementations MUST write only while the step is `running` **and** still on
+   * `attempt` (its `attempts` counter) — one conditional statement — so a worker
+   * the sweeper has given up on cannot overwrite what the attempt that replaced
+   * it keeps. Optional: a store without it gives steps a checkpoint that never
+   * saves, and they start over on a retry as before.
+   */
+  saveStepCheckpoint?(stepId: StepId, attempt: number, value: unknown): Promise<boolean>;
   /**
    * Flip a ready step to `waiting` — it suspends until `resumeStep` (waitForEvent)
    * or a sub-workflow child settles. `waitingAt` is stamped on `startedAt`: it is
@@ -276,5 +297,4 @@ interface WorkflowStore {
    */
   findStuckSteps(workflowId: WorkflowId, cutoff: string): Promise<StepRecord[]>;
 }
-//#endregion
 export { CreatedWorkflow as a, ListWorkflowsFilters as c, UNSETTLED_STEP_STATUSES as d, WorkflowStore as f, CreateWorkflowStep as i, ReopenWorkflowParams as l, CompleteStepParams as n, FailStepParams as o, WorkflowTreeFilter as p, CreateWorkflowParams as r, FinishWorkflowParams as s, AddChildStep as t, TransactionalScope as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Durable DAG workflow engine: Zod-typed steps over Postgres + pg-boss. The model layer is @octabits-io/models.",
   "license": "MIT",
   "type": "module",
@@ -80,7 +80,7 @@
     }
   },
   "devDependencies": {
-    "@electric-sql/pglite": "0.5.10",
+    "@electric-sql/pglite": "0.5.12",
     "@testcontainers/postgresql": "^12.2.1",
     "@types/node": "^26.6.5",
     "@types/pg": "^8.23.1",

package/skills/add-a-case-loop/SKILL.md

@@ -61,7 +61,7 @@ export const caseLoop = defineCaseLoop({
   manager: {
     system: 'You decide the next move, one at a time, by calling exactly one decision tool. …',
     prompt: (ctx, result, facts) => caseFile(ctx.workflowInput, result, facts),
-    tools: (ctx) => readOnlyTools(ctx),            // the manager looks things up; moves do the work
+    tools: (ctx) => readOnlyTools(ctx),            // agentTool('reads', tool({ … })) each — moves do the work
     resources: ['llm'],
     retry: { maxAttempts: 3 },
   },
@@ -129,7 +129,7 @@ and "closes the case as stuck when the manager cannot decide".
 
 - [ ] Every exit has a `why`; every non-move exit has a closer
 - [ ] The policy is in `refuse` and reads facts from the store, not from the model's words
-- [ ] The manager's tools only read
+- [ ] The manager's tools only read (`agentTool('reads', …)`); an `outward` one is refused without `propose`
 - [ ] Every outward step waits for a person and sends exactly what they released
 - [ ] `startMove` passes the `caseId:moveNo` idempotency key
 - [ ] The manager's model goes through the disclosure gate