@lostgradient/weft 0.2.0

package/dist/core/payload-size.d.ts

@@ -0,0 +1,78 @@
+import { WeftError } from './weft-error.ts';
+/**
+ * The kind of payload being size-checked at the codec boundary. Used in the
+ * {@link PayloadSizeExceededError} message so operators can tell which
+ * admission point rejected the value.
+ */
+export type PayloadKind = 'workflow input' | 'signal payload' | 'activity result';
+/**
+ * Thrown at admission when a payload's serialized (codec-encoded) size exceeds
+ * the operator-configured {@link PayloadSizePolicy.maxBytes}. The rejection
+ * happens before any storage write, so an oversized value is never newly
+ * persisted. The measured size is the codec-encoded byte length of the bare
+ * value, before any storage-layer compression or record-envelope wrapping.
+ *
+ * This is a terminal admission failure, not a transient one: re-running the
+ * producing operation cannot make the result smaller, so it should not be
+ * retried.
+ *
+ * Its `code` (`'PayloadSizeExceededError'`) is part of the public
+ * {@link WeftErrorCode} union. Catch it with `instanceof` or by comparing
+ * `error.code === 'PayloadSizeExceededError'`.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, PayloadSizeExceededError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine({ payloadSize: { maxBytes: 64 } });
+ * engine.register(workflow({ name: 'echo' }).execute(async function* (_ctx, input) { return input; }));
+ *
+ * try {
+ *   await engine.start('echo', 'x'.repeat(1024));
+ * } catch (err) {
+ *   if (err instanceof PayloadSizeExceededError) {
+ *     console.error(`${err.payloadKind} too large: ${String(err.serializedBytes)} > ${String(err.maxBytes)}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class PayloadSizeExceededError extends WeftError<'PayloadSizeExceededError'> {
+    /** Which admission point rejected the payload. */
+    readonly payloadKind: PayloadKind;
+    /** The payload's actual serialized byte length. */
+    readonly serializedBytes: number;
+    /** The configured maximum serialized byte length. */
+    readonly maxBytes: number;
+    constructor(payloadKind: PayloadKind, serializedBytes: number, maxBytes: number);
+}
+/**
+ * Reject a payload whose serialized size exceeds `limit`, before it is written.
+ *
+ * Size is measured as `encode(value).byteLength` — the codec-encoded byte
+ * length of the bare value, before any storage-layer compression or
+ * record-envelope wrapping. A payload exactly at `limit` is allowed; one byte
+ * larger throws {@link PayloadSizeExceededError}. When `limit` is `null` the
+ * cap is disabled and the function returns immediately without encoding, so the
+ * unconfigured path costs nothing.
+ *
+ * @param value - The payload to measure.
+ * @param limit - The maximum serialized byte length, or `null` to disable.
+ * @param payloadKind - Which admission point is validating, for the error message.
+ */
+export declare function assertPayloadWithinLimit(value: unknown, limit: number | null, payloadKind: PayloadKind): void;
+/**
+ * Encode a payload once, enforce the size cap on the result, and return the
+ * encoded bytes for reuse by the caller's write — avoiding a second `encode`
+ * at call sites that persist the exact value they measured.
+ *
+ * Behaves like {@link assertPayloadWithinLimit} on the size check (a value
+ * exactly at `limit` is allowed; one byte larger throws), but always encodes
+ * (there is no `null` short-circuit) because the caller needs the bytes
+ * regardless of whether the cap is enabled.
+ *
+ * @param value - The payload to encode and measure.
+ * @param limit - The maximum serialized byte length, or `null` to skip the cap.
+ * @param payloadKind - Which admission point is validating, for the error message.
+ * @returns The codec-encoded bytes, guaranteed within `limit` when `limit` is set.
+ */
+export declare function encodePayloadWithinLimit(value: unknown, limit: number | null, payloadKind: PayloadKind): Uint8Array;

package/dist/core/payload-size.js

@@ -0,0 +1,27 @@
+import { encode } from "./codec.js";
+import { WeftError } from "./weft-error.js";
+
+export class PayloadSizeExceededError extends WeftError {
+  payloadKind;
+  serializedBytes;
+  maxBytes;
+  constructor(payloadKind, serializedBytes, maxBytes) {
+    super("PayloadSizeExceededError", `${payloadKind} exceeds the configured maximum serialized size: ${String(serializedBytes)} bytes > ${String(maxBytes)} byte limit.`);
+    this.payloadKind = payloadKind;
+    this.serializedBytes = serializedBytes;
+    this.maxBytes = maxBytes;
+  }
+}
+export function assertPayloadWithinLimit(value, limit, payloadKind) {
+  if (limit === null)
+    return;
+  const serializedBytes = encode(value).byteLength;
+  if (serializedBytes > limit)
+    throw new PayloadSizeExceededError(payloadKind, serializedBytes, limit);
+}
+export function encodePayloadWithinLimit(value, limit, payloadKind) {
+  const encoded = encode(value);
+  if (limit !== null && encoded.byteLength > limit)
+    throw new PayloadSizeExceededError(payloadKind, encoded.byteLength, limit);
+  return encoded;
+}

package/dist/core/persisted-data-incompatible-error.d.ts

@@ -0,0 +1,48 @@
+import { WeftError } from './weft-error.ts';
+/**
+ * Thrown by {@link Engine.create} (and other storage-opening entry points) when
+ * a persisted Weft database carries a schema version older than the engine
+ * understands. Pre-MVP Weft does not migrate persisted data — bumping
+ * {@link CURRENT_PERSISTED_DATA_SCHEMA_VERSION} intentionally invalidates older
+ * databases so the failure surfaces deterministically at boot, before any
+ * workflow attempts replay.
+ *
+ * Inspect `foundVersion` to see what the storage advertised and `expectedVersion`
+ * to see what this engine requires. Resolve by deleting the database (acceptable
+ * pre-MVP) or by starting from fresh storage.
+ *
+ * @example
+ * ```ts
+ * import { Engine, PersistedDataIncompatibleError } from '@lostgradient/weft';
+ *
+ * try {
+ *   await Engine.create({});
+ * } catch (error) {
+ *   if (error instanceof PersistedDataIncompatibleError) {
+ *     console.error(
+ *       `expected schema ${error.expectedVersion}, found ${error.foundVersion ?? 'pre-versioned'}`,
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare class PersistedDataIncompatibleError extends WeftError<'PersistedDataIncompatibleError'> {
+    readonly foundVersion: number | null;
+    readonly expectedVersion: number;
+    constructor(foundVersion: number | null, expectedVersion: number);
+}
+/**
+ * Bumped to `1` by the workflow-builder refactor (Phase 3). Pre-MVP databases
+ * have no version key recorded — `assertCompatiblePersistedDataVersion` treats
+ * the absence of the key on an otherwise non-empty database as
+ * `pre-versioned`, which is incompatible. Fresh databases get the current
+ * version written on first open.
+ */
+export declare const CURRENT_PERSISTED_DATA_SCHEMA_VERSION = 1;
+/**
+ * Storage key holding the persisted-data schema version (encoded as the UTF-8
+ * digits of an integer). Kept under a `weft:` prefix so it cannot collide with
+ * the public `wf:` / `op:` / `schedule:` / etc. layouts in
+ * `src/storage/interface.ts#KEYS`.
+ */
+export declare const PERSISTED_DATA_SCHEMA_VERSION_KEY = "weft:schema-version";

package/dist/core/persisted-data-incompatible-error.js

@@ -0,0 +1,12 @@
+import { WeftError } from "./weft-error.js";
+
+export class PersistedDataIncompatibleError extends WeftError {
+  foundVersion;
+  expectedVersion;
+  constructor(foundVersion, expectedVersion) {
+    super("PersistedDataIncompatibleError", `Persisted workflow data was written by an older Weft version (schema ${foundVersion === null ? "pre-versioned" : `v${foundVersion}`}, current v${expectedVersion}) and is incompatible with the workflow-builder refactor. Delete the database or start fresh.`);
+    this.foundVersion = foundVersion;
+    this.expectedVersion = expectedVersion;
+  }
+}
+export const CURRENT_PERSISTED_DATA_SCHEMA_VERSION = 1, PERSISTED_DATA_SCHEMA_VERSION_KEY = "weft:schema-version";

package/dist/core/registry-snapshot.d.ts

@@ -0,0 +1,69 @@
+import type { Engine } from './engine.ts';
+import { WeftError } from './weft-error.ts';
+/**
+ * Current registry contract version. Future incompatible changes to the
+ * snapshot shape must bump this number; the codegen CLI rejects unknown
+ * versions with a clear upgrade message.
+ */
+export declare const REGISTRY_VERSION = 1;
+/** Metadata reported per workflow in a registry snapshot. */
+export type RegistryWorkflowEntry = {
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    description?: string;
+    tags?: ReadonlyArray<string>;
+};
+/**
+ * Metadata reported per activity in a registry snapshot.
+ *
+ * `tags` is intentionally omitted: the registry feeds `weft codegen`, which
+ * models activities as TypeScript function signatures. Tags are catalog
+ * metadata for documentation/observability surfaces and don't appear on a
+ * function type. Workflows include tags because the workflow registry
+ * augmentation point (`WorkflowRegistry`) is an interface where extra
+ * metadata can be attached structurally; activity names are now typed
+ * per-workflow via the builder's `.activities({...})` step, so there is no
+ * global activity-type registry to attach metadata to.
+ */
+export type RegistryActivityEntry = {
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    /** Engine assigns a default queue when none is specified, so this is always populated. */
+    queue: string;
+    description?: string;
+};
+/**
+ * Snapshot of every locally-registered workflow and activity, suitable for
+ * serialization as the `GET /v1/registry` response body.
+ */
+export type RegistrySnapshot = {
+    registryVersion: 1;
+    workflows: Record<string, RegistryWorkflowEntry>;
+    activities: Record<string, RegistryActivityEntry>;
+};
+/**
+ * Thrown when a registered workflow or activity schema cannot be converted
+ * to JSON Schema. Carries the offending entity name and direction so
+ * server-side observability (logs and telemetry) and non-HTTP callers
+ * (the in-process MCP builder, programmatic users of `buildRegistrySnapshot`)
+ * can identify which registration is broken. The HTTP REST binding
+ * deliberately masks this on the wire as a generic `500 / Internal server
+ * error` so a misbehaving registration cannot leak schema layout to clients
+ * that only have `system:read`.
+ */
+export declare class RegistrySchemaConversionError extends WeftError<'RegistrySchemaConversionError'> {
+    readonly entityKind: 'workflow' | 'activity';
+    readonly entityName: string;
+    readonly direction: 'inputSchema' | 'outputSchema';
+    constructor(entityKind: 'workflow' | 'activity', entityName: string, direction: 'inputSchema' | 'outputSchema', cause: unknown);
+}
+/**
+ * Build a registry snapshot from an engine's locally-registered workflows
+ * and activities. Remote-only activities (those advertised by a remote
+ * worker but never registered with the local engine) are excluded by
+ * construction — `engine.listActivityDefinitions()` is the only source.
+ *
+ * Throws {@link RegistrySchemaConversionError} if any registered schema
+ * fails JSON Schema conversion.
+ */
+export declare function buildRegistrySnapshot(engine: Engine): RegistrySnapshot;

package/dist/core/registry-snapshot.js

@@ -0,0 +1,70 @@
+import { definitionSchemaToJsonSchema } from "./types/definition-schema-to-json.js";
+import { WeftError } from "./weft-error.js";
+export const REGISTRY_VERSION = 1;
+
+export class RegistrySchemaConversionError extends WeftError {
+  entityKind;
+  entityName;
+  direction;
+  constructor(entityKind, entityName, direction, cause) {
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    super("RegistrySchemaConversionError", `Failed to convert ${direction} for ${entityKind} "${entityName}": ${causeMessage}`, { cause });
+    this.entityKind = entityKind;
+    this.entityName = entityName;
+    this.direction = direction;
+  }
+}
+export function buildRegistrySnapshot(engine) {
+  const workflowDefinitions = engine.listWorkflowDefinitions(), activityDefinitions = engine.listActivityDefinitions(), sortedWorkflows = workflowDefinitions.toSorted((a, b) => {
+    if (a.type < b.type)
+      return -1;
+    if (a.type > b.type)
+      return 1;
+    return 0;
+  }), sortedActivities = activityDefinitions.toSorted((a, b) => {
+    if (a.name < b.name)
+      return -1;
+    if (a.name > b.name)
+      return 1;
+    return 0;
+  }), workflows = Object.create(null);
+  for (const definition of sortedWorkflows)
+    workflows[definition.type] = buildWorkflowEntry(definition);
+  const activities = Object.create(null);
+  for (const metadata of sortedActivities)
+    activities[metadata.name] = buildActivityEntry(metadata);
+  return {
+    registryVersion: REGISTRY_VERSION,
+    workflows,
+    activities
+  };
+}
+function buildWorkflowEntry(definition) {
+  const entry = {};
+  if (definition.inputSchema !== void 0)
+    entry.inputSchema = convertSchema("workflow", definition.type, "inputSchema", definition.inputSchema);
+  if (definition.outputSchema !== void 0)
+    entry.outputSchema = convertSchema("workflow", definition.type, "outputSchema", definition.outputSchema);
+  if (definition.description !== void 0)
+    entry.description = definition.description;
+  if (definition.tags.length > 0)
+    entry.tags = [...definition.tags];
+  return entry;
+}
+function buildActivityEntry(metadata) {
+  const entry = { queue: metadata.queue };
+  if (metadata.inputSchema !== void 0)
+    entry.inputSchema = convertSchema("activity", metadata.name, "inputSchema", metadata.inputSchema);
+  if (metadata.outputSchema !== void 0)
+    entry.outputSchema = convertSchema("activity", metadata.name, "outputSchema", metadata.outputSchema);
+  if (metadata.description !== void 0)
+    entry.description = metadata.description;
+  return entry;
+}
+function convertSchema(entityKind, entityName, field, schema) {
+  try {
+    return definitionSchemaToJsonSchema(schema, field === "inputSchema" ? "input" : "output");
+  } catch (cause) {
+    throw new RegistrySchemaConversionError(entityKind, entityName, field, cause);
+  }
+}

package/dist/core/review/events.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Fired by {@link ReviewCoordinator} when a new human review request is
+ * persisted. Carries the `workflowId`, `reviewId`, `reviewType`, and the list
+ * of requested `reviewers`. Subscribe to this event to notify reviewers via
+ * email, webhook, or ticketing system.
+ *
+ * @example Route review notifications to a webhook
+ * ```ts
+ * import { ReviewRequestedEvent } from '@lostgradient/weft';
+ *
+ * const target = new EventTarget();
+ *
+ * target.addEventListener(ReviewRequestedEvent.type, (e) => {
+ *   const event = e as ReviewRequestedEvent;
+ *   console.log(`Review ${event.reviewId} requested for workflow ${event.workflowId}`);
+ *   console.log('Reviewers:', event.reviewers);
+ * });
+ * ```
+ */
+export declare class ReviewRequestedEvent extends Event {
+    static readonly type: "human-review:requested";
+    readonly workflowId: string;
+    readonly reviewId: string;
+    readonly reviewType: string;
+    readonly reviewers: string[];
+    constructor(workflowId: string, reviewId: string, reviewType: string, reviewers: string[]);
+}
+/**
+ * Fired by {@link ReviewCoordinator} when a reviewer submits a decision.
+ * Carries the `reviewId`, `decision` string, `reviewer` identifier, and the
+ * time elapsed since the review was created. Use this to close tickets, record
+ * audit logs, or trigger downstream workflow steps.
+ *
+ * @example Record review decisions in an audit log
+ * ```ts
+ * import { ReviewCompletedEvent } from '@lostgradient/weft';
+ *
+ * const target = new EventTarget();
+ *
+ * target.addEventListener(ReviewCompletedEvent.type, (e) => {
+ *   const event = e as ReviewCompletedEvent;
+ *   console.log(`Review ${event.reviewId}: '${event.decision}' by ${event.reviewer} in ${event.duration}ms`);
+ * });
+ * ```
+ */
+export declare class ReviewCompletedEvent extends Event {
+    static readonly type: "human-review:completed";
+    readonly workflowId: string;
+    readonly reviewId: string;
+    readonly decision: string;
+    readonly reviewer: string;
+    readonly duration: number;
+    constructor(workflowId: string, reviewId: string, decision: string, reviewer: string, duration: number);
+}
+/**
+ * Record mapping each review-related event name to its typed Event subclass.
+ * Use as the type parameter for `TypedEventTarget` to get type-safe listeners
+ * on engine-level review events.
+ *
+ * @example
+ * ```ts
+ * import type { TypedEventTarget, WeftReviewEventMap } from '@lostgradient/weft';
+ *
+ * declare const target: TypedEventTarget<WeftReviewEventMap>;
+ * target.addEventListener('human-review:requested', (event) => {
+ *   console.log(event.reviewId, event.reviewers);
+ * });
+ * ```
+ */
+export type WeftReviewEventMap = {
+    'human-review:requested': ReviewRequestedEvent;
+    'human-review:completed': ReviewCompletedEvent;
+};

package/dist/core/review/events.js

@@ -0,0 +1,31 @@
+export class ReviewRequestedEvent extends Event {
+  static type = "human-review:requested";
+  workflowId;
+  reviewId;
+  reviewType;
+  reviewers;
+  constructor(workflowId, reviewId, reviewType, reviewers) {
+    super(ReviewRequestedEvent.type);
+    this.workflowId = workflowId;
+    this.reviewId = reviewId;
+    this.reviewType = reviewType;
+    this.reviewers = reviewers;
+  }
+}
+
+export class ReviewCompletedEvent extends Event {
+  static type = "human-review:completed";
+  workflowId;
+  reviewId;
+  decision;
+  reviewer;
+  duration;
+  constructor(workflowId, reviewId, decision, reviewer, duration) {
+    super(ReviewCompletedEvent.type);
+    this.workflowId = workflowId;
+    this.reviewId = reviewId;
+    this.decision = decision;
+    this.reviewer = reviewer;
+    this.duration = duration;
+  }
+}

package/dist/core/review/index.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Human-in-the-loop review protocol.
+ *
+ * Coordinates review requests, decisions, escalation chains,
+ * and partial approval workflows for durable human oversight.
+ *
+ * @module human-review
+ */
+import type { BatchOperation, Storage } from '../../storage/interface.ts';
+import { WeftError } from '../weft-error.ts';
+/**
+ * A persisted human review request. Created by {@link ReviewCoordinator.createReview}
+ * and returned to the workflow once a reviewer submits a decision.
+ *
+ * @example
+ * ```ts
+ * import type { ReviewRequest } from '@lostgradient/weft';
+ *
+ * const request: ReviewRequest = {
+ *   reviewId: 'r-1',
+ *   workflowId: 'wf-1',
+ *   artifact: { text: 'draft' },
+ *   reviewType: 'content',
+ *   reviewers: ['alice@example.com'],
+ *   allowPartial: false,
+ *   createdAt: Date.now(),
+ * };
+ * ```
+ */
+export interface ReviewRequest {
+    reviewId: string;
+    workflowId: string;
+    artifact: unknown;
+    reviewType: string;
+    reviewers: string[];
+    allowPartial: boolean;
+    timeout?: number;
+    webhookUrl?: string;
+    createdAt: number;
+}
+/**
+ * A reviewer's decision payload returned to the workflow from `ctx.review()`.
+ * The `decision` field is the binary outcome; `sectionDecisions` carries
+ * per-section verdicts when `allowPartial` is enabled on the request.
+ */
+export interface ReviewDecision {
+    reviewId: string;
+    decision: 'approved' | 'rejected' | 'needs-changes';
+    reviewer: string;
+    feedback?: string;
+    sectionDecisions?: Record<string, 'approved' | 'rejected'>;
+    timestamp: number;
+}
+/**
+ * One step in a {@link ReviewOptions.escalation} chain. Either reassigns the
+ * pending review to a new owner (`to`) or auto-decides it (`action`) after
+ * `after` milliseconds have elapsed.
+ *
+ * @example
+ * ```ts
+ * import type { EscalationStep } from '@lostgradient/weft';
+ *
+ * const step: EscalationStep = { after: 60_000, to: 'manager@example.com' };
+ * void step;
+ * ```
+ */
+export interface EscalationStep {
+    after: number;
+    to?: string;
+    action?: 'auto-approve' | 'auto-reject';
+    auditReason?: string;
+}
+/**
+ * Base options for creating a review via {@link ReviewCoordinator.createReview}.
+ * The `artifact` carries the payload the reviewer evaluates; the other fields
+ * configure routing, partial approval, escalation chains, and webhook delivery.
+ *
+ * @example
+ * ```ts
+ * import type { ReviewOptions } from '@lostgradient/weft';
+ *
+ * const options: ReviewOptions = {
+ *   artifact: { summary: 'release plan' },
+ *   reviewers: ['alice@example.com'],
+ *   timeout: 60_000,
+ * };
+ * void options;
+ * ```
+ */
+export interface ReviewOptions {
+    artifact: unknown;
+    reviewType?: string;
+    reviewers?: string[];
+    allowPartial?: boolean;
+    timeout?: number;
+    escalation?: EscalationStep[];
+    webhookUrl?: string;
+}
+/**
+ * Options passed to `ctx.review()` inside a workflow generator. Extends
+ * {@link ReviewOptions} with the context-level callback the runtime invokes
+ * when an escalation step fires.
+ *
+ * @example
+ * ```ts
+ * import type { HumanReviewOptions } from '@lostgradient/weft';
+ *
+ * const options: HumanReviewOptions = {
+ *   artifact: 'release plan',
+ *   reviewers: ['alice@example.com'],
+ *   onEscalation: (action) => console.log('escalation:', action),
+ * };
+ * void options;
+ * ```
+ */
+export interface HumanReviewOptions extends ReviewOptions {
+    /** Handler called when an escalation step fires. */
+    onEscalation?: (action: EscalationAction) => void;
+}
+/**
+ * The decision payload returned to the workflow from `ctx.review()`.
+ * Alias for {@link ReviewDecision}.
+ *
+ * @example
+ * ```ts
+ * import type { HumanReviewResult } from '@lostgradient/weft';
+ *
+ * const result: HumanReviewResult = {
+ *   reviewId: 'r-1',
+ *   decision: 'approved',
+ *   reviewer: 'alice@example.com',
+ *   timestamp: Date.now(),
+ * };
+ * void result;
+ * ```
+ */
+export type HumanReviewResult = ReviewDecision;
+/**
+ * The action returned by {@link ReviewCoordinator.checkEscalations} when an
+ * escalation step has fired. Either reassigns the review to a new owner or
+ * auto-decides it with an audit reason.
+ *
+ * @example
+ * ```ts
+ * import type { EscalationAction } from '@lostgradient/weft';
+ *
+ * const action: EscalationAction = { type: 'escalate', to: 'manager@example.com' };
+ * void action;
+ * ```
+ */
+export type EscalationAction = {
+    type: 'escalate';
+    to: string;
+} | {
+    type: 'auto-decide';
+    decision: 'approved' | 'rejected';
+    auditReason: string;
+};
+/**
+ * Thrown when a human review request exceeds its configured `timeout`
+ * milliseconds without receiving a decision. Carries the `reviewId` and the
+ * elapsed time so callers can decide whether to escalate or auto-approve.
+ *
+ * @example Catch a review timeout and escalate
+ * ```ts
+ * import { workflow, ReviewTimeoutError } from '@lostgradient/weft';
+ * import type { Context, WorkflowContext } from '@lostgradient/weft';
+ * import { TestEngine } from '@lostgradient/weft/testing';
+ *
+ * const engine = new TestEngine({ startTime: 0 });
+ * engine.register(
+ *   workflow({ name: 'needs-review' }).execute(async function* (ctx: WorkflowContext) {
+ *     return yield* ctx.review({
+ *       artifact: 'release plan',
+ *       reviewers: ['alice@example.com'],
+ *       timeout: 5_000,
+ *     });
+ *   }),
+ * );
+ * const handle = await engine.start('needs-review', null);
+ * const result = handle.result();
+ * await engine.advanceTime(6_000);
+ *
+ * try {
+ *   await result;
+ * } catch (error) {
+ *   if (error instanceof ReviewTimeoutError) {
+ *     console.warn(`Review ${error.reviewId} timed out after ${error.elapsed}ms`);
+ *   }
+ * }
+ * ```
+ */
+export declare class ReviewTimeoutError extends WeftError<'ReviewTimeoutError'> {
+    readonly reviewId: string;
+    readonly elapsed: number;
+    constructor(reviewId: string, elapsed: number);
+}
+/**
+ * Options for constructing a {@link ReviewCoordinator}. Accepts an optional
+ * `EventTarget` to dispatch {@link ReviewRequestedEvent} on review
+ * creation, and a custom `getNow` clock function for deterministic testing.
+ *
+ * @example Attach an event target and a fixed clock for tests
+ * ```ts
+ * import { ReviewCoordinator, type ReviewCoordinatorOptions } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const storage = new MemoryStorage();
+ * const options: ReviewCoordinatorOptions = {
+ *   eventTarget: new EventTarget(),
+ *   getNow: () => 1_700_000_000_000,
+ * };
+ *
+ * const coordinator = new ReviewCoordinator(storage, options);
+ * ```
+ */
+export interface ReviewCoordinatorOptions {
+    /** When provided, the coordinator dispatches human review events. */
+    eventTarget?: EventTarget;
+    /** Custom time source for testing. Defaults to `Date.now`. */
+    getNow?: () => number;
+}
+/**
+ * Persists human review requests to storage, dispatches
+ * {@link ReviewRequestedEvent} on creation, accepts reviewer decisions,
+ * and checks escalation timeouts. Used by `ctx.review()` inside workflow
+ * generators to pause execution pending a human decision.
+ *
+ * @example Create a review and later submit a decision
+ * ```ts
+ * import { ReviewCoordinator } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const storage = new MemoryStorage();
+ * const coordinator = new ReviewCoordinator(storage);
+ *
+ * const review = await coordinator.createReview('wf-123', {
+ *   artifact: { text: 'Draft email body…' },
+ *   reviewType: 'content',
+ *   reviewers: ['alice@example.com'],
+ * });
+ *
+ * const decision = await coordinator.submitDecision(review.reviewId, {
+ *   decision: 'approved',
+ *   reviewer: 'alice@example.com',
+ * });
+ * console.log(decision.decision); // 'approved'
+ * ```
+ */
+export declare class ReviewCoordinator {
+    #private;
+    constructor(storage: Storage, optionsOrGetNow?: ReviewCoordinatorOptions | (() => number));
+    /** Create a review request and persist it. */
+    createReview(workflowId: string, options: ReviewOptions): Promise<ReviewRequest>;
+    /** Submit a review decision. */
+    submitDecision(reviewId: string, decision: Omit<ReviewDecision, 'reviewId' | 'timestamp'>): Promise<ReviewDecision>;
+    /** Get a pending review. */
+    getReview(workflowId: string, reviewId: string): Promise<ReviewRequest | null>;
+    /** List pending reviews. */
+    listPendingReviews(): Promise<ReviewRequest[]>;
+    /** Build cleanup operations for completed workflow. */
+    cleanupOperations(workflowId: string, reviewId: string): BatchOperation[];
+    /** Check for escalation timeouts. Returns actions to take. */
+    checkEscalations(review: ReviewRequest, escalation: EscalationStep[], now: number): EscalationAction | null;
+}