octaflow 0.25.0 → 0.27.0

package/README.md

@@ -200,6 +200,7 @@ next to what your steps actually do.
 | 🔁 | **Retry & timeout** — per-step `maxAttempts`, fixed/exponential backoff, wall-clock timeout |
 | 💤 | **Durable sleep** — hold a step in the queue for N ms (survives restarts) |
 | 🔀 | **Conditional branching** — `when` guards skip a step and its branch; `join: 'any'` converges |
+| 🎯 | **Decisions** — typed choices with a confidence from a swappable decider (a function, a model, your own); below a threshold a person settles it |
 | ⏳ | **Deadlines** — a budget on a suspended step (fail, or continue with a stand-in answer) and on a whole run |
 | ♻️ | **Retry a failed run** — `retryWorkflow` resumes from the failure point; completed steps keep their output |
 | 🚦 | **Concurrency & rate limiting** — per-step-type caps and token buckets via a pluggable gate |
@@ -295,6 +296,10 @@ export const flowStepLease = pgTable('flow_step_lease', flowStepLeaseColumns, (t
 ]);
 ```
 
+The names are yours: the store's `ON CONFLICT` clauses target column lists, never a
+constraint by name, so what must match is each index's columns and its partial `WHERE`,
+not what you call it.
+
 The store stays plain SQL, bound to the `schema` you hand `createPgWorkflowStore`,
 `createPgStepGate` and `createPgEventSink` — and, for the gate, to the `tables` names — so
 declare the tables under the same schema and names. A test in the package holds every column
@@ -317,6 +322,7 @@ Full docs — concepts, every feature, production wiring and the API reference
 | [Retry & timeout](https://octaflow.octabits.io/core/retry-and-timeout/) | attempt budgets, backoff, and how a failure is classified |
 | [Fan-out & map](https://octaflow.octabits.io/core/fan-out-and-map/) | one child step per item of a runtime list |
 | [Branching](https://octaflow.octabits.io/core/branching/) | `when` guards and join rules — if/else over a static DAG |
+| [Decisions](https://octaflow.octabits.io/core/decisions/) | typed choices with a confidence, a swappable decider, a person below the threshold |
 | [Signals](https://octaflow.octabits.io/core/signals/) · [Sub-workflows](https://octaflow.octabits.io/core/sub-workflows/) · [Saga](https://octaflow.octabits.io/core/saga-compensation/) | suspend, nest, and roll back |
 | [Deadlines](https://octaflow.octabits.io/core/deadlines/) | budgets for a suspended step and for a whole run |
 | [Heartbeats](https://octaflow.octabits.io/core/heartbeats/) | liveness for long steps, and interrupting one that was cancelled |
@@ -351,8 +357,9 @@ Runnable, focused examples live in [`examples/`](./examples) — see [`examples/
 | 14 | `14-live-progress.ts` | `FlowObserver` → SSE fan-out (build your own dashboard) |
 | 15 | `15-conditional-branching.ts` | `when` guards + a `join: 'any'` convergence |
 | 16 | `16-deadlines-and-retry.ts` | wait deadlines, run deadlines, `retryWorkflow`, heartbeats |
+| 17 | `17-decisions.ts` | a decision step, a review below the threshold, branches on the outcome |
 
-The in-memory examples (01–11, 14–16) share a small driver, [`examples/runtime.ts`](./examples/runtime.ts),
+The in-memory examples (01–11, 14–17) share a small driver, [`examples/runtime.ts`](./examples/runtime.ts),
 that builds an engine over the in-memory store and an in-process queue you drain.
 
 ---

package/dist/ai/index.d.ts

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

package/dist/ai/index.js

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

package/dist/ai/providers/index.d.ts

@@ -66,7 +66,7 @@ export interface LazyEmbeddingModelMeta {
  * next call rather than cached.
  */
 export declare function createLazyEmbeddingModel(meta: LazyEmbeddingModelMeta, load: () => Promise<EmbeddingModelV4>): EmbeddingModelV4;
-export type AiProviderConfigErrorKey = 'ai_residency_undeclared' | 'ai_residency_invalid' | 'ai_base_url_invalid' | 'ai_model_required' | 'ai_embedding_dimensions_invalid';
+export type AiProviderConfigErrorKey = 'ai_residency_undeclared' | 'ai_residency_invalid' | 'ai_base_url_invalid' | 'ai_model_required' | 'ai_model_undeclared' | 'ai_embedding_dimensions_invalid';
 /**
  * A provider configuration that cannot work. Thrown before any SDK is loaded
  * or any request is made: it is a deployment mistake, found at wiring time.
@@ -143,4 +143,66 @@ export interface OpenAiCompatibleEmbeddingProvider {
 export declare function createOpenAiCompatibleModelProvider(config: OpenAiCompatibleModelProviderConfig): Promise<OpenAiCompatibleModelProvider>;
 /** An embedding model on an OpenAI-compatible endpoint, with its declared width. */
 export declare function createOpenAiCompatibleEmbeddingProvider(config: OpenAiCompatibleEmbeddingProviderConfig): Promise<OpenAiCompatibleEmbeddingProvider>;
+export interface OpenAiCompatibleGatewayModel {
+  /** Where the gateway sends this alias. Validated like an endpoint's residency. */
+  residency: AiEndpointResidency;
+}
+/**
+ * `residency` is where the gateway itself runs, usually `{ region: 'self-hosted' }`.
+ * It decides whether plain http is acceptable for the hop to the gateway; where a
+ * call ends up is the alias's residency in `models`.
+ */
+export interface OpenAiCompatibleGatewayConfig extends OpenAiCompatibleEndpointConfig {
+  /** Every alias this deployment may call, keyed by the model name the gateway knows. */
+  models: Record<string, OpenAiCompatibleGatewayModel>;
+  /** As for {@link OpenAiCompatibleModelProviderConfig.structuredOutputs}. */
+  structuredOutputs?: boolean;
+  /** As for {@link OpenAiCompatibleModelProviderConfig.includeUsage}. */
+  includeUsage?: boolean;
+}
+export interface GatewayCallOptions {
+  /**
+   * Sent as the request body's `metadata`, which LiteLLM keeps in its spend log,
+   * so a call there can be matched to the host's own record: a workflow id, a
+   * scope key. It leaves the house as written and is never redacted: put ids
+   * here, never content. Added innermost, so a disclosure gate wrapped around the
+   * model neither digests nor redacts it.
+   */
+  metadata?: Record<string, string>;
+}
+export interface OpenAiCompatibleGatewayProvider {
+  providerId: OpenAiCompatibleProviderId;
+  /** Where the gateway itself runs. */
+  residency: AiEndpointResidency;
+  /** Every declared alias with its validated residency: what a settings page or a subprocessor annex lists. */
+  models: Readonly<Record<string, AiEndpointResidency>>;
+  /** The residency of one alias. Throws `ai_model_undeclared` for an alias the declaration does not name. */
+  residencyOf(alias: string): AiEndpointResidency;
+  /** A Chat Completions model for a declared alias, wrapped for refusal detection. */
+  languageModel(alias: string, options?: GatewayCallOptions): LanguageModelV4;
+}
+/**
+ * A model gateway — LiteLLM, or any router with the OpenAI-compatible API — as
+ * refusal-aware models, one per declared alias, each with the residency of
+ * where the gateway sends it.
+ *
+ * ```ts
+ * const gateway = await createOpenAiCompatibleGatewayProvider({
+ *   baseUrl: 'http://litellm.ai.svc:4000/v1',
+ *   apiKey: process.env.LITELLM_KEY,
+ *   residency: { region: 'self-hosted' },
+ *   models: {
+ *     'approval-confidential': { residency: { region: 'self-hosted' } },
+ *     'approval-public': { residency: { region: 'eu', legalName: 'Example Inference GmbH', country: 'DE' } },
+ *   },
+ * });
+ * const model = gateway.languageModel('approval-confidential', { metadata: { workflowId } });
+ * ```
+ *
+ * The declaration is what the gateway is configured to do, stated by the
+ * deployment: this provider cannot see the gateway's routing, and a fallback
+ * the gateway adds on its own breaks the declaration silently. Keep the two
+ * in the same review.
+ */
+export declare function createOpenAiCompatibleGatewayProvider(config: OpenAiCompatibleGatewayConfig): Promise<OpenAiCompatibleGatewayProvider>;
 //#endregion

package/dist/ai/providers/index.js

@@ -1,5 +1,6 @@
 import { r as createRefusalAwareModel } from "../../refusal-BsL2HPDb.js";
 import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, t as AI_PROVIDERS } from "../../provider-registry-BRwjC6_3.js";
+import { wrapLanguageModel } from "ai";
 //#region src/ai/providers/index.ts
 const LLM_LOADERS = {
 	anthropic: async (apiKey, baseURL) => {
@@ -186,5 +187,90 @@ async function createOpenAiCompatibleEmbeddingProvider(config) {
 		embeddingModel: () => provider.embeddingModel(modelId)
 	};
 }
+/** Puts `metadata` into the request body under the provider's own options key, merged over any the call carries. */
+function withGatewayMetadata(model, optionsKey, metadata) {
+	const fixed = { ...metadata };
+	return wrapLanguageModel({
+		model,
+		middleware: {
+			specificationVersion: "v4",
+			transformParams: async ({ params }) => {
+				const own = params.providerOptions?.[optionsKey] ?? {};
+				const existing = own.metadata !== null && typeof own.metadata === "object" && !Array.isArray(own.metadata) ? own.metadata : {};
+				const merged = {
+					...own,
+					metadata: {
+						...existing,
+						...fixed
+					}
+				};
+				return {
+					...params,
+					providerOptions: {
+						...params.providerOptions,
+						[optionsKey]: merged
+					}
+				};
+			}
+		}
+	});
+}
+/**
+* A model gateway — LiteLLM, or any router with the OpenAI-compatible API — as
+* refusal-aware models, one per declared alias, each with the residency of
+* where the gateway sends it.
+*
+* ```ts
+* const gateway = await createOpenAiCompatibleGatewayProvider({
+*   baseUrl: 'http://litellm.ai.svc:4000/v1',
+*   apiKey: process.env.LITELLM_KEY,
+*   residency: { region: 'self-hosted' },
+*   models: {
+*     'approval-confidential': { residency: { region: 'self-hosted' } },
+*     'approval-public': { residency: { region: 'eu', legalName: 'Example Inference GmbH', country: 'DE' } },
+*   },
+* });
+* const model = gateway.languageModel('approval-confidential', { metadata: { workflowId } });
+* ```
+*
+* The declaration is what the gateway is configured to do, stated by the
+* deployment: this provider cannot see the gateway's routing, and a fallback
+* the gateway adds on its own breaks the declaration silently. Keep the two
+* in the same review.
+*/
+async function createOpenAiCompatibleGatewayProvider(config) {
+	const residency = checkEndpoint(config);
+	const declared = config.models;
+	if (declared === null || typeof declared !== "object" || Object.keys(declared).length === 0) throw new AiProviderConfigError("ai_model_required", "a gateway needs at least one declared model alias in models");
+	const models = {};
+	for (const [alias, model] of Object.entries(declared)) {
+		requireModel(alias, "a model alias");
+		const resolved = resolveEndpointResidency(model?.residency);
+		if (!resolved.ok) throw new AiProviderConfigError(resolved.error.key, `model ${JSON.stringify(alias)}: ${resolved.error.message}`);
+		models[alias] = resolved.value;
+	}
+	Object.freeze(models);
+	const provider = await loadOpenAiCompatible(config, {
+		structuredOutputs: config.structuredOutputs,
+		includeUsage: config.includeUsage
+	});
+	const optionsKey = config.name ?? "openai-compatible";
+	const residencyOf = (alias) => {
+		const found = Object.hasOwn(models, alias) ? models[alias] : void 0;
+		if (found === void 0) throw new AiProviderConfigError("ai_model_undeclared", `model ${JSON.stringify(alias)} is not declared for this gateway; declared: ${Object.keys(models).join(", ")}`);
+		return found;
+	};
+	return {
+		providerId: OPENAI_COMPATIBLE_PROVIDER_ID,
+		residency,
+		models,
+		residencyOf,
+		languageModel: (alias, options) => {
+			residencyOf(alias);
+			const chat = provider.chatModel(alias);
+			return createRefusalAwareModel(options?.metadata ? withGatewayMetadata(chat, optionsKey, options.metadata) : chat);
+		}
+	};
+}
 //#endregion
-export { AiProviderConfigError, createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel, createOpenAiCompatibleEmbeddingProvider, createOpenAiCompatibleModelProvider };
+export { AiProviderConfigError, createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel, createOpenAiCompatibleEmbeddingProvider, createOpenAiCompatibleGatewayProvider, createOpenAiCompatibleModelProvider };

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

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

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

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

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

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

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

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

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { $ as computeReadiness, A as StepConditionHandler, B as StepStatus, C as defineWaitStep, D as StartOptions, E as RetryPolicy, F as StepHandlerNotFoundError, G as WorkflowNotFoundError, H as WorkflowCreatedResult, I as StepHandlerRegistry, J as WorkflowStatus, K as WorkflowNotRetryableError, L as StepId, M as StepError, N as StepExecutionContext, O as StepCompensateHandler, P as StepHandler, Q as ReadinessPlan, R as StepRecord, S as defineSubWorkflowStep, T as InvalidWorkflowDefinitionError, U as WorkflowDefinition, V as WaitTimeoutPolicy, W as WorkflowId, X as JoinRule, Y as WorkflowWithSteps, Z as PlannedSkip, _ as WorkflowOutput, a as STEP_DISPLAY_STATUS, b as defineSleepStep, c as WORKFLOW_STATUS_SCHEMA, d as toPublicWorkflow, et as isTerminalStepStatus, f as StepDeps, g as TypedWorkflow, h as TypedStepContext, i as PublicWorkflowStep, it as ok, j as StepDefinition, k as StepCompensationContext, l as toDisplayStepStatus, m as TypedStep, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as Result, o as STEP_DISPLAY_STATUS_SCHEMA, p as StepOutput, q as WorkflowRecord, r as PublicWorkflow, rt as err, s as StepDisplayStatus, t as PUBLIC_WORKFLOW_SCHEMA, tt as FlowErrorShape, u as toPublicStep, v as buildWorkflow, w as FlowError, x as defineStep, y as defineMapStep, z as StepRegistration } from "./index-BURAYZui.js";
+import { $ as StepId, A as TypedStep, B as FlowError, C as defineDecisionOutcomeStep, D as resolveDecision, E as functionDecider, F as defineMapStep, G as StepCompensationContext, H as RetryPolicy, I as defineSleepStep, J as StepError, K as StepConditionHandler, L as defineStep, M as TypedWorkflow, N as WorkflowOutput, O as StepDeps, P as buildWorkflow, Q as StepHandlerRegistry, R as defineSubWorkflowStep, S as DecisionStep, T as defineDecisionStep, U as StartOptions, V as InvalidWorkflowDefinitionError, W as StepCompensateHandler, X as StepHandler, Y as StepExecutionContext, Z as StepHandlerNotFoundError, _ as DecisionOutput, _t as 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 { 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-CR9dEdLW.js";
-import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-g7Ct0J6w.js";
-import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-BdxIcc92.js";
+import { A as ListWorkflowsFilters, C as AddChildStep, D as CreatedWorkflow, E as CreateWorkflowStep, M as TransactionalScope, N as WorkflowStore, O as FailStepParams, 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";
 //#region src/core/registry.d.ts
 /**
  * Creates an in-memory step handler registry.
@@ -162,4 +162,4 @@ export declare function createInMemoryWorkflowStore(partitionKey?: string): Work
   };
 };
 //#endregion
-export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, DispatchKind, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowMeter, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, JoinRule, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PlannedSkip, PublicWorkflow, PublicWorkflowStep, RateRule, ReadinessPlan, RecordedSpan, RecordingObserver, RecordingTracer, ReopenWorkflowParams, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepConditionHandler, StepDefinition, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowNotRetryableError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStore, WorkflowWithSteps, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createMeterObserver, createRecordingObserver, createRecordingTracer, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, isTerminalStepStatus, noopLogger, noopObserver, noopTracer, ok, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, Decider, DecisionAnswer, DecisionAnswers, DecisionChoices, DecisionOutcome, DecisionOutput, DecisionQuestions, DecisionRequest, DecisionResponse, DecisionReview, DecisionStep, DispatchKind, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowMeter, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, JoinRule, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PlannedSkip, PublicWorkflow, PublicWorkflowStep, RateRule, ReadinessPlan, RecordedSpan, RecordingObserver, RecordingTracer, ReopenWorkflowParams, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepConditionHandler, StepDefinition, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowNotRetryableError, WorkflowOutput, WorkflowRecord, WorkflowStatus, 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 };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { S as ok, _ as markRetryable, a as WORKFLOW_STATUS_SCHEMA, b as noopLogger, c as toPublicWorkflow, d as defineSleepStep, f as defineStep, g as isRetryableError, h as explicitRetryability, i as STEP_DISPLAY_STATUS_SCHEMA, l as buildWorkflow, m as defineWaitStep, n as PUBLIC_WORKFLOW_STEP_SCHEMA, o as toDisplayStepStatus, p as defineSubWorkflowStep, r as STEP_DISPLAY_STATUS, s as toPublicStep, t as PUBLIC_WORKFLOW_SCHEMA, u as defineMapStep, v as nonRetryableError, x as err, y as retryableError } from "./core-DNWPwFaE.js";
+import { C as nonRetryableError, D as ok, E as err, S as markRetryable, T as noopLogger, _ as defineStep, a as WORKFLOW_STATUS_SCHEMA, b as explicitRetryability, c as toPublicWorkflow, d as defineDecisionStep, f as functionDecider, g as defineSleepStep, h as defineMapStep, i as STEP_DISPLAY_STATUS_SCHEMA, l as defineDecisionOutcomeStep, m as buildWorkflow, n as PUBLIC_WORKFLOW_STEP_SCHEMA, o as toDisplayStepStatus, p as resolveDecision, r as STEP_DISPLAY_STATUS, s as toPublicStep, t as PUBLIC_WORKFLOW_SCHEMA, u as defineDecisionReviewStep, v as defineSubWorkflowStep, w as retryableError, x as isRetryableError, y as defineWaitStep } from "./core-C9h3-KFr.js";
 //#region src/core/readiness.ts
 /** Statuses a step can no longer move out of on its own. */
 const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
@@ -2233,4 +2233,4 @@ function createInMemoryWorkflowStore(partitionKey = "default") {
 	};
 }
 //#endregion
-export { PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, WORKFLOW_STATUS_SCHEMA, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createInMemoryWorkflowStore, createMeterObserver, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, isRetryableError, isTerminalStepStatus, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, WORKFLOW_STATUS_SCHEMA, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createInMemoryWorkflowStore, createMeterObserver, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineDecisionOutcomeStep, defineDecisionReviewStep, defineDecisionStep, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, functionDecider, isRetryableError, isTerminalStepStatus, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, resolveDecision, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };

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

@@ -1,4 +1,4 @@
-import { J as WorkflowStatus, L as StepId, R as StepRecord, W as WorkflowId, Y as WorkflowWithSteps, q as WorkflowRecord } from "./index-BURAYZui.js";
+import { $ as StepId, dt as WorkflowWithSteps, et as StepRecord, lt as WorkflowRecord, ot as WorkflowId, ut as WorkflowStatus } from "./index-BGmJYvTt.js";
 //#region src/core/store.d.ts
 interface CreateWorkflowStep {
   key: string;
@@ -320,7 +320,7 @@ declare function createRecordingObserver(): RecordingObserver;
  * The slice of a metrics API the engine's meter observer needs. Structural:
  * `@octabits-io/telemetry`'s meter and an OpenTelemetry `Meter`
  * both fit (the SDK's `createCounter`/`createHistogram` need a two-line
- * adapter, the framework's meter none).
+ * adapter).
  */
 interface FlowMeter {
   counter(name: string, options?: {

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

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

package/dist/postgres/index.d.ts

@@ -1,5 +1,5 @@
-import { W as WorkflowId } from "../index-BURAYZui.js";
-import { N as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-CR9dEdLW.js";
+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 { Pool } from "pg";
 //#region src/postgres/ddl.d.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Durable DAG workflow engine: Zod-typed steps over Postgres + pg-boss, with an optional AI add-on (token/cost/quota). Layered single package.",
   "license": "MIT",
   "type": "module",
@@ -116,23 +116,23 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^4.0.52",
-    "@ai-sdk/mistral": "^4.0.42",
-    "@ai-sdk/openai": "^4.0.65",
-    "@ai-sdk/openai-compatible": "^3.0.48",
-    "@ai-sdk/provider": "^4.0.13",
-    "@testcontainers/postgresql": "^12.1.0",
-    "@types/node": "^26.5.1",
+    "@ai-sdk/anthropic": "^4.0.71",
+    "@ai-sdk/mistral": "^4.0.56",
+    "@ai-sdk/openai": "^4.0.83",
+    "@ai-sdk/openai-compatible": "^3.0.62",
+    "@ai-sdk/provider": "^4.0.21",
+    "@testcontainers/postgresql": "^12.2.0",
+    "@types/node": "^26.6.4",
     "@types/pg": "^8.23.1",
-    "ai": "^7.0.97",
-    "drizzle-orm": "^0.45.2",
-    "pg": "^8.23.0",
-    "pg-boss": "^12.30.0",
-    "testcontainers": "^12.1.0",
+    "ai": "^7.0.127",
+    "drizzle-orm": "^0.45.3",
+    "pg": "^8.23.1",
+    "pg-boss": "^12.35.1",
+    "testcontainers": "^12.2.0",
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0",
-    "zod": "^4.6.0"
+    "vitest": "^5.0.3",
+    "zod": "^4.6.5"
   },
   "scripts": {
     "build": "tsdown",