octaflow 0.36.0 → 0.37.0

package/README.md

@@ -215,8 +215,59 @@ next to what your steps actually do.
 | 🚑 | **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 |
 | 🔭 | **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) |
-| 🧱 | **Pluggable everything** — `WorkflowStore`, `Dispatcher`, `StepGate`, `FlowObserver`, hooks |
+| 🏁 | **Settled once** — a step's completion and a run's finish are conditional writes: an event racing its deadline, two last parallel steps, a cancel racing the last completion — one wins, and only the winner emits, compensates and runs hooks |
+| 🧱 | **Pluggable everything** — `WorkflowStore` (its settling writes return whether they won), `Dispatcher`, `StepGate`, `FlowObserver`, hooks |
+
+## Workflow documents
+
+`octaflow/document` holds a workflow as **data**: a person, a template catalog or a model writes
+a JSON document, `compileWorkflowDocument` checks it and returns the `WorkflowDefinition` the
+engine runs, or every finding with the path it is about. Behaviour stays in code: a document
+picks, wires and fills **kinds** a host registered once (`defineKind`), and each step carries its
+spec in its own input, so a template saved a minute ago runs on a worker that has never seen it.
+
+```ts
+import { compileWorkflowDocument, coreKinds, defineKind, registerWorkflowKinds, resumeDocumentStep } from 'octaflow/document';
+
+const mailSend = defineKind({
+  kind: 'mail.send',
+  params: { to: z.string(), subject: z.string(), body: z.string() },
+  effect: 'outward', // the compiler refuses a document where no person's approval stands before it
+  output: z.object({ messageId: z.string() }),
+  handler: async ({ params }) => ({ messageId: await mail.send(params) }),
+});
+const kinds = [...coreKinds, mailSend];
+registerWorkflowKinds(registry, kinds); // once, at startup
+
+const compiled = compileWorkflowDocument(templateJson, kinds);
+if (!compiled.ok) return compiled.error.issues; // [{ code, path: 'steps.send.params.body', message }]
+await engine.startWorkflow(compiled.value.definition, compiled.value.inputSchema.parse(input));
+// later, a person answers a waiting step — checked against what it declared first
+await resumeDocumentStep(engine, compiled.value, workflowId, 'approve', { decision: 'approve', value: edited });
+```
+
+Steps with dependencies (`after`, and every step an expression reads), `when` guards, `join`,
+`flow` to group steps or run another document by `ref`; declared types are a JSON Schema subset;
+expressions are total and side-effect free, with durations (`days(input.days)`) and exact
+decimals (`decimal(input.amount)`) as types of their own.
+
+| Core kind | What it does |
+|---|---|
+| `sleep` | a durable wait, timed from the run's input or an earlier step |
+| `event.wait` | suspends until something outside resumes it |
+| `human.task` / `human.approve` | a person's work; an approval, which an outward step must have before it |
+| `decide` | a rule table: the first rule that holds gives the answer |
+| `map` | its steps once per item, each item a run of its 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:
+`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-YqnPwR-v.js → core-COMWflJl.js}

@@ -1,112 +1,4 @@
 import { z } from "zod";
-//#region 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
-* gates look up their `concurrency` and `rateLimit` rules by these keys, so a
-* rule keyed `'llm:local'` holds every step that names that resource, whatever
-* its type, and a rule keyed by a type still holds that type alone. A custom
-* gate that wants the same vocabulary calls this.
-*/
-function gateRuleKeys(req) {
-	const keys = [req.stepType];
-	for (const resource of req.resources ?? []) if (!keys.includes(resource)) keys.push(resource);
-	return keys;
-}
-/**
-* A per-process {@link StepGate}: concurrency caps (held slots) plus token-bucket
-* rate limits (throughput), each keyed by a step type or by a resource a step
-* declares ({@link gateRuleKeys}). Both are optional; a step none of whose keys
-* has a rule is always admitted, and a step with several keys must pass every
-* rule among them.
-*
-* Concurrency is reserved first, then the rate tokens — so a rate denial does not
-* waste a concurrency slot, and a denial by a later rule gives back what earlier
-* ones granted. Good for single-worker deployments; swap in a shared-store gate
-* for multi-worker concurrency control.
-*/
-function createInMemoryStepGate(config = {}) {
-	const now = config.now ?? (() => Date.now());
-	const concurrencyRetry = Math.max(1, config.concurrencyRetrySeconds ?? 1);
-	const running = /* @__PURE__ */ new Map();
-	const buckets = /* @__PURE__ */ new Map();
-	const capacityOf = (rule) => rule.burst ?? Math.max(1, Math.ceil(rule.perSecond));
-	function rateCheck(key) {
-		const rule = config.rateLimit?.[key];
-		if (!rule) return { ok: true };
-		const capacity = capacityOf(rule);
-		const tNow = now();
-		let b = buckets.get(key);
-		if (!b) {
-			b = {
-				tokens: capacity,
-				updatedMs: tNow
-			};
-			buckets.set(key, b);
-		}
-		const elapsedSec = Math.max(0, (tNow - b.updatedMs) / 1e3);
-		b.tokens = Math.min(capacity, b.tokens + elapsedSec * rule.perSecond);
-		b.updatedMs = tNow;
-		if (b.tokens >= 1) {
-			b.tokens -= 1;
-			return { ok: true };
-		}
-		const needed = 1 - b.tokens;
-		return {
-			ok: false,
-			retryAfterSeconds: Math.max(1, Math.ceil(needed / rule.perSecond))
-		};
-	}
-	/** Give back a token a denied request had already taken from an earlier bucket. */
-	function refund(key) {
-		const rule = config.rateLimit?.[key];
-		const b = buckets.get(key);
-		if (rule && b) b.tokens = Math.min(capacityOf(rule), b.tokens + 1);
-	}
-	return { async acquire(req) {
-		const keys = gateRuleKeys(req);
-		const held = [];
-		let released = false;
-		const release = () => {
-			if (released) return;
-			released = true;
-			for (const key of held) running.set(key, Math.max(0, (running.get(key) ?? 1) - 1));
-		};
-		for (const key of keys) {
-			const cRule = config.concurrency?.[key];
-			if (!cRule) continue;
-			const current = running.get(key) ?? 0;
-			if (current >= cRule.maxConcurrent) {
-				release();
-				return {
-					admitted: false,
-					retryAfterSeconds: concurrencyRetry
-				};
-			}
-			running.set(key, current + 1);
-			held.push(key);
-		}
-		const taken = [];
-		for (const key of keys) {
-			if (!config.rateLimit?.[key]) continue;
-			const rate = rateCheck(key);
-			if (!rate.ok) {
-				for (const t of taken) refund(t);
-				release();
-				return {
-					admitted: false,
-					retryAfterSeconds: rate.retryAfterSeconds
-				};
-			}
-			taken.push(key);
-		}
-		return {
-			admitted: true,
-			release
-		};
-	} };
-}
-//#endregion
 //#region src/core/retry.ts
 /**
 * Realm-safe marker for an explicit retryability decision. `Symbol.for` so a
@@ -990,4 +882,4 @@ function toPublicWorkflow(workflow) {
 	};
 }
 //#endregion
-export { nonRetryableError as C, gateRuleKeys as E, markRetryable as S, createInMemoryStepGate 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 };
+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 };

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

@@ -1,4 +1,4 @@
-import { St as Result, lt as WorkflowId, nt as StepId, xt as FlowErrorShape } from "./index-DZUO24Rz.js";
+import { Tt as Result, ft as WorkflowId, rt as StepId, wt as FlowErrorShape } from "./index-BlwtmRJP.js";
 //#region src/core/logger.d.ts
 type LogAttributes = Record<string, unknown>;
 interface Logger {

package/dist/document/index.d.ts

@@ -0,0 +1,471 @@
+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 { 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';
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  enum?: ReadonlyArray<string | number | boolean>;
+  format?: string;
+  [keyword: string]: unknown;
+};
+/** A finding with the JSON path it is about. */
+interface PathedIssue {
+  path: string;
+  message: string;
+}
+/**
+ * Whether a declared schema stays inside the subset. Everything the launch
+ * form, the review card and the checker would have to understand is listed;
+ * anything else (`$ref`, `oneOf`, `patternProperties`, …) is refused with its path.
+ */
+export declare function checkSchemaSubset(schema: unknown, path: string): PathedIssue[];
+/**
+ * The validator for a subset schema. `format: "decimal"` (money, exact numbers)
+ * is checked here, since JSON Schema has no such format; Zod builds the rest.
+ * 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 {
+  kind: string;
+  label?: string;
+  after?: string[];
+  when?: string;
+  join?: 'all' | 'any';
+  params?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+  timeout?: string;
+  onTimeout?: 'fail' | {
+    output: Record<string, unknown>;
+  };
+  onFailure?: 'fail' | {
+    output: Record<string, unknown>;
+  };
+  retry?: {
+    maxAttempts: number;
+    backoff?: 'fixed' | 'exponential';
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+  };
+  /** For `flow`, `map` and `repeat`: the steps it groups, or runs per item, or per pass. */
+  steps?: Record<string, DocumentStep>;
+  /** For `flow` only: another document to run as a sub-workflow, pinned to a revision. */
+  ref?: {
+    id: string;
+    revision: number;
+  };
+}
+export declare const documentStepSchema: z.ZodType<DocumentStep>;
+export declare const roleSchema: z.ZodObject<{
+  id: z.ZodString;
+  label: z.ZodString;
+  may: z.ZodArray<z.ZodEnum<{
+    agent: "agent";
+    person: "person";
+  }>>;
+}, z.core.$strict>;
+export declare const workflowDocumentSchema: z.ZodObject<{
+  format: z.ZodLiteral<"octaflow.workflow">;
+  version: z.ZodLiteral<1>;
+  id: z.ZodString;
+  revision: z.ZodNumber;
+  name: z.ZodString;
+  input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  roles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    may: z.ZodArray<z.ZodEnum<{
+      agent: "agent";
+      person: "person";
+    }>>;
+  }, z.core.$strict>>>;
+  steps: z.ZodRecord<z.ZodString, z.ZodType<DocumentStep, unknown, z.core.$ZodTypeInternals<DocumentStep, unknown>>>;
+  result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  ui: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, 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';
+/**
+ * What a step of this kind does to the world. `outward` — a mail, a payment, a
+ * post — needs a person's approval on every path to it, and the compiler
+ * refuses a document where it hasn't one.
+ */
+type KindEffect = 'none' | 'internal' | 'outward';
+/** How a kind's output type is known. */
+type KindOutput =
+/** The step declares it (`output`), required. */
+'declared' |
+/** The step may declare it; otherwise any object. */
+'declared-optional' |
+/** Fixed by the kind. */
+z.ZodType |
+/** Derived from the types of the step's params, as the compiler resolved them. */
+((args: {
+  paramTypes: Record<string, JsonSchema>;
+  params: Record<string, unknown>;
+}) => JsonSchema);
+/**
+ * A kind's own static checks, beyond its params schema: what a kind carries
+ * that only it understands — the policy rules of an agent's exits, say. Paths
+ * are relative to the step's params.
+ */
+type KindCheck = (args: {
+  params: Record<string, unknown>;
+  /** The types the step's expressions see: `input`, `steps`. */
+  scope: Record<string, JsonSchema>;
+  /** Check an expression under the step's scope plus any names the kind adds. */
+  checkExpr: (src: string, extra?: Record<string, JsonSchema>) => {
+    type: JsonSchema;
+    errors: string[];
+  };
+}) => Array<{
+  path: string;
+  message: string;
+}>;
+interface KindHandlerArgs<TParams, TContext> {
+  /** The step's params, every binding resolved, parsed by the kind's schema. */
+  params: TParams;
+  /** The step's output type: what the handler's result is validated against. */
+  output: JsonSchema;
+  stepKey: string;
+  /** What the step's expressions see — `input`, `steps` — for a kind that evaluates expressions of its own. */
+  scope: Record<string, unknown>;
+  ctx: StepExecutionContext<TContext>;
+}
+interface WorkflowKind<TContext = unknown> {
+  readonly kind: string;
+  readonly params: z.ZodObject<z.ZodRawShape>;
+  readonly actor: KindActor;
+  readonly effect: KindEffect;
+  /** A person's approval: it is what makes an outward step downstream of it allowed. */
+  readonly approval: boolean;
+  /** Suspends until the host resumes it (a person, an answer from outside). */
+  readonly wait: boolean;
+  /** A durable sleep: the delay in ms from params resolved against the run's input. */
+  readonly sleep?: (params: Record<string, unknown>) => number;
+  readonly output: KindOutput;
+  readonly check?: KindCheck;
+  /** A kind with a body the compiler compiles (`map`, `repeat`, a `flow` by ref) — core kinds only. */
+  readonly structural?: 'map' | 'repeat' | 'subflow';
+  /**
+   * A kind that stands for several steps: the compiler replaces the step with
+   * these, as it does a flow's — the ones that wait for none of the others
+   * start, carrying the step's `after` and `when`. One of them should keep the
+   * step's key, so `steps.<key>` still reads what the step stands for.
+   */
+  readonly expand?: (key: string, step: DocumentStep) => Record<string, DocumentStep>;
+  /**
+   * The expressions a kind keeps in its params as text (a rule's `when`, a
+   * policy's `refuse`). What they read is what the step waits for, as with
+   * bindings — so the compiler asks.
+   */
+  readonly reads?: (params: Record<string, unknown>) => string[];
+  readonly handler?: (args: KindHandlerArgs<Record<string, unknown>, TContext>) => Promise<Record<string, unknown>>;
+  readonly retry?: RetryPolicy;
+  readonly heartbeatTimeoutMs?: number;
+  readonly resources?: readonly string[];
+}
+interface KindConfig<TParams extends z.ZodRawShape, TContext> {
+  kind: string;
+  params: TParams;
+  actor?: KindActor;
+  effect?: KindEffect;
+  approval?: boolean;
+  wait?: boolean;
+  sleep?: (params: z.infer<z.ZodObject<TParams>>) => number;
+  output: KindOutput;
+  check?: KindCheck;
+  /** @internal */
+  structural?: 'map' | 'repeat' | 'subflow';
+  expand?: (key: string, step: DocumentStep) => Record<string, DocumentStep>;
+  reads?: (params: Record<string, unknown>) => string[];
+  handler?: (args: KindHandlerArgs<z.infer<z.ZodObject<TParams>>, TContext>) => Promise<Record<string, unknown>>;
+  retry?: RetryPolicy;
+  heartbeatTimeoutMs?: number;
+  resources?: readonly string[];
+}
+export declare function defineKind<TParams extends z.ZodRawShape, TContext = unknown>(config: KindConfig<TParams, TContext>): WorkflowKind<TContext>;
+/** A durable sleep. `for` is an ISO 8601 duration or an expression over the run's input. */
+export declare const sleepKind: WorkflowKind<unknown>;
+/** Suspends until something outside resumes it with an event — a customer's reply, a webhook. */
+export declare const eventWaitKind: WorkflowKind<unknown>;
+/** A person does a piece of work and hands back what the step declares. */
+export declare const humanTaskKind: WorkflowKind<unknown>;
+/**
+ * A person approves or rejects `subject`, and may hand back an edited version
+ * of it as `value`. An outward step reads the approved value, never the draft.
+ */
+export declare const humanApproveKind: WorkflowKind<unknown>;
+/**
+ * Runs its `steps` once per item of `over`, each item as a sub-workflow of its
+ * own; the body reads `input.item`, `input.index` and `input.with` (values the
+ * step passes in). Outputs `{ items }`, one body output per item, in order.
+ */
+export declare const mapKind: WorkflowKind<unknown>;
+/**
+ * Runs its `steps` as a pass, then again while `while` holds — an expression
+ * over `last` (the pass's output, by step) and `pass` — up to `max` passes. One
+ * step of one run, however many passes. The body reads `input.pass`,
+ * `input.last` and `input.with`. Outputs `{ passes, last }`.
+ */
+export declare const repeatKind: WorkflowKind<unknown>;
+/** A `flow` by `ref`: the referenced document as a sub-workflow, its `input` the step's. Outputs the child's steps' outputs. */
+export declare const subflowKind: WorkflowKind<unknown>;
+/**
+ * A deterministic decision: the first rule whose `when` holds gives the answer,
+ * `otherwise` when none does. Outputs the answer's fields and `rule` — which one
+ * decided, -1 for `otherwise`. A policy written down, not a model's guess.
+ */
+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;
+}
+type CompileIssueCode = 'shape' | 'schema' | 'unknown_kind' | 'params' | 'expression' | 'graph' | 'unbounded_wait' | 'role' | 'approval_before_impact';
+/** What a compiled step carries in its static input: everything the generic handler needs to run it. */
+interface CompiledStepSpec {
+  kind: string;
+  params: Record<string, unknown>;
+  when?: string;
+  output: JsonSchema;
+  /** The engine policies the step sets for itself — deadline, stand-ins, retry, the body it starts. */
+  policy: Omit<StepPolicy, 'repeat'>;
+  /** For a `repeat` step: the cap and the expression (over `last` and `pass`) that asks for another pass. */
+  repeat?: {
+    max: number;
+    while: string;
+  };
+}
+interface CompileOptions {
+  /**
+   * The documents a `flow` may refer to by `ref: { id, revision }`. Return the
+   * document, or undefined when there is none. A run is pinned to the revision
+   * named, so a ref names one.
+   */
+  documents?: (ref: {
+    id: string;
+    revision: number;
+  }) => unknown;
+  /** @internal — a body's input is derived by the compiler, not declared; the subset check is for declared types. */
+  derivedInput?: boolean;
+  /** @internal — the documents being compiled above this one, against a ref cycle. */
+  refChain?: string[];
+}
+/** The key under which a compiled step's spec rides in its static input. */
+export declare const SPEC_KEY: '$workflowDocument';
+interface CompiledWorkflow {
+  /** `<id>@<revision>`: a run is pinned to the revision it started on. */
+  type: string;
+  definition: WorkflowDefinition;
+  inputSchema: z.ZodType<Record<string, unknown>>;
+  /** Each step's spec, by key — what a host reads to resume a waiting step. */
+  steps: Record<string, CompiledStepSpec>;
+  /** The run's result, as expressions over the steps' outputs. */
+  result: Record<string, string>;
+  /** Findings that don't stop the document, e.g. a merge that will skip with a guarded branch. */
+  warnings: CompileIssue[];
+}
+/** The step type a kind runs under; a merge (`join: "any"`) is its own type, since the join is the type's. */
+export declare function stepTypeOf(kind: string, join?: 'all' | 'any'): string;
+/** A document that doesn't compile: every finding, each with the path it is about. */
+interface InvalidWorkflowDocumentError {
+  key: 'invalid_workflow_document';
+  message: string;
+  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
+ * step that isn't a document's.
+ */
+export declare function documentStepSpec(step: {
+  input: Record<string, unknown> | null;
+}): CompiledStepSpec | null;
+/** A step's params with every binding (`{ "$": … }`, `{ "$t": … }`) resolved against a scope. */
+export declare function resolveParams(value: unknown, scope: Record<string, unknown>): unknown;
+/**
+ * Register every kind on an engine's registry: each under two step types, one
+ * per join rule. Call once at startup with the same kinds the documents were
+ * compiled against.
+ */
+export declare function registerWorkflowKinds<TContext>(registry: StepHandlerRegistry<TContext>, kinds: readonly WorkflowKind<TContext>[]): void;
+interface WaitingDocumentStep {
+  key: string;
+  kind: string;
+  /** The params as the step sees them now: the subject of an approval, the instructions of a task. */
+  params: Record<string, unknown>;
+  /** What the answer must look like. */
+  output: CompiledStepSpec['output'];
+}
+/** A waiting step of a document run, its params resolved — what a review card or a task form shows. */
+export declare function describeWaitingStep(store: WorkflowStore, workflowId: WorkflowId, stepKey: string): Promise<WaitingDocumentStep | null>;
+interface ResumableEngine {
+  resumeStep(workflowId: WorkflowId, stepKey: string, payload?: Record<string, unknown>): Promise<Result<void, FlowError>>;
+}
+type ResumeDocumentStepError = FlowError | {
+  key: 'invalid_answer';
+  message: string;
+  issues: Array<{
+    path: string;
+    message: string;
+  }>;
+};
+/**
+ * Answer a waiting step, checked against what it declared first: an answer the
+ * step can't use is refused here, with its issues, rather than accepted and
+ * failing the steps that read it.
+ */
+export declare function resumeDocumentStep(engine: ResumableEngine, compiled: Pick<CompiledWorkflow, 'steps'>, workflowId: WorkflowId, stepKey: string, answer: Record<string, unknown>): Promise<Result<void, ResumeDocumentStepError>>;
+/**
+ * Answer a waiting step by its own record: the spec rides in the step's input,
+ * so this needs no compiled document — what a host uses for steps inside a
+ * map item, a repeat pass or a referenced flow, which run as child workflows.
+ */
+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;
+} | {
+  kind: 'list';
+  items: Expr[];
+} | {
+  kind: 'path';
+  segments: string[];
+} | {
+  kind: 'call';
+  name: string;
+  args: Expr[];
+} | {
+  kind: 'unary';
+  op: 'not' | '-';
+  operand: Expr;
+} | {
+  kind: 'binary';
+  op: BinaryOp;
+  left: Expr;
+  right: Expr;
+} | {
+  kind: 'if';
+  cond: Expr;
+  then: Expr;
+  else: Expr;
+};
+type BinaryOp = 'and' | 'or' | '=' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | '+' | '-' | '*' | '/';
+export declare class ExprSyntaxError extends Error {}
+export declare function parseExpr(src: string): Expr;
+export declare function evaluate(e: Expr, scope: Record<string, unknown>): unknown;
+interface CheckResult {
+  type: JsonSchema;
+  errors: string[];
+}
+/**
+ * The type of an expression under a scope of typed names (`input`, `steps`, …),
+ * and what is wrong with it: a path that cannot exist, an operation on types
+ * 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;
+}
+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;
+}
+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;
+  value: unknown;
+}
+interface PolicyChange {
+  path: string;
+  change: 'added' | 'removed' | 'changed';
+  before?: unknown;
+  after?: unknown;
+}
+/**
+ * The policy in a set of steps (a document's, a body's, a case move's):
+ *
+ * - every approval step — who approves, after what, under which guard, how long, what silence means;
+ * - the guard and the bound params of every outward step — when it acts, and on what;
+ * - every `refuse` rule on an agent's exits;
+ * - every rule table of a `decide` step;
+ * - the cap of every `repeat`.
+ *
+ * Bodies (flows, maps, repeats) are walked; a referenced document is its own
+ * revision and is reviewed on its own.
+ */
+export declare function stepsPolicy(steps: Record<string, DocumentStep>, prefix: string, kinds: readonly WorkflowKind<any>[]): PolicyItem[];
+/** The policy of a workflow document: its roles' bounds and its steps'. */
+export declare function workflowPolicy(doc: WorkflowDocument, kinds: readonly WorkflowKind<any>[]): PolicyItem[];
+export declare function diffPolicy(before: PolicyItem[], after: PolicyItem[]): PolicyChange[];
+interface RevisionReview {
+  /** `<id>@<revision>` of what is published now, or null for a first publication. */
+  from: string | null;
+  to: string;
+  changes: PolicyChange[];
+  /** True when the policy changed — a first publication with any policy in it included. */
+  needsSecondApproval: boolean;
+}
+/** What a revision changes in policy against the one published before it (or none). */
+export declare function reviewRevision(published: {
+  id: string;
+  revision: number;
+  policy: PolicyItem[];
+} | null, next: {
+  id: string;
+  revision: number;
+  policy: PolicyItem[];
+}): RevisionReview;
+/** Review a workflow document's new revision. */
+export declare function reviewWorkflowRevision(published: WorkflowDocument | null, next: WorkflowDocument, kinds: readonly WorkflowKind<any>[]): RevisionReview;
+interface PublicationRefused {
+  key: 'second_approval_required';
+  message: string;
+  changes: PolicyChange[];
+}
+/**
+ * Whether a revision may be published: when its policy changed, someone other
+ * than its author has approved it. The host decides who may approve and keeps
+ * the approvals; this holds them to the rule.
+ */
+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 };