@lostgradient/weft 0.2.0

package/dist/core/updates.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Synchronous update request/response coordination.
+ *
+ * Manages the lifecycle of workflow updates with idempotency support,
+ * timeout-based waiting, and automatic cleanup of expired responses.
+ *
+ * @module updates
+ */
+import type { BatchOperation, Storage } from '../storage/interface';
+import type { WorkflowStatus } from './types';
+import { WeftError } from './weft-error.ts';
+export interface UpdateRequest {
+    updateId: string;
+    workflowId: string;
+    name: string;
+    payload: unknown;
+    idempotencyKey?: string | undefined;
+    createdAt: number;
+}
+export interface UpdateResponse {
+    updateId: string;
+    result?: unknown;
+    error?: string | undefined;
+    createdAt: number;
+}
+export interface UpdateRequestOptions {
+    idempotencyKey?: string;
+    timeout?: number;
+}
+/**
+ * Thrown by the engine when an update sent via `engine.update` or
+ * `handle.update` does not receive a response within the configured timeout.
+ * Read `updateId` to identify the stalled update.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, UpdateTimeoutError, update } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'paused' }).execute(async function* () {
+ *     await new Promise(() => {}); // workflow never resolves on its own
+ *   }),
+ * );
+ * const handle = await engine.start('paused', null);
+ * const proceed = update<void, void>('proceed');
+ * try {
+ *   await handle.update(proceed, undefined, { timeout: 100 });
+ * } catch (err) {
+ *   if (err instanceof UpdateTimeoutError) {
+ *     console.error('update timed out:', err.updateId);
+ *   }
+ * }
+ * ```
+ */
+export declare class UpdateTimeoutError extends WeftError<'UpdateTimeoutError'> {
+    readonly updateId: string;
+    constructor(updateId: string, timeout: number);
+}
+/**
+ * Thrown when an update is rejected by its pre-acceptance validator — before
+ * the payload is durably written or the workflow observes it. Inspect
+ * `updateName` to see which update was rejected and `issues` for the
+ * structured validation messages.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, UpdateValidationError, update } from '@lostgradient/weft';
+ *
+ * const setAge = update<{ age: number }, void>('setAge');
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'guarded' }).execute(async function* (ctx) {
+ *     ctx.onUpdate(setAge, () => undefined, {
+ *       validator: (v): unknown => {
+ *         const age = (v as Record<string, unknown>)['age'];
+ *         if (typeof age !== 'number' || age < 0) {
+ *           return { issues: [{ message: 'age must be a non-negative number' }] };
+ *         }
+ *         return undefined;
+ *       },
+ *     });
+ *     await new Promise(() => {}); // park forever
+ *   }),
+ * );
+ * const handle = await engine.start('guarded', null);
+ * try {
+ *   await handle.update(setAge, { age: -1 });
+ * } catch (err) {
+ *   if (err instanceof UpdateValidationError) {
+ *     console.error(err.issues[0]?.message); // 'age must be a non-negative number'
+ *   }
+ * }
+ * ```
+ */
+export declare class UpdateValidationError extends WeftError<'UpdateValidationError'> {
+    readonly updateName: string;
+    /**
+     * Structured validation issues from the pre-acceptance validator. Each issue
+     * carries a human-readable `message` and an optional RFC 6901 JSON Pointer
+     * `path` indicating which field in the update payload failed validation.
+     */
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: string;
+    }>;
+    constructor(updateName: string, issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: string;
+    }>);
+}
+/**
+ * Thrown when an update is sent to a workflow that is already in a terminal
+ * state (completed, failed, cancelled, or timed-out). Check `workflowId` and
+ * `status` to understand which workflow rejected the update.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, WorkflowTerminalError, update } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'quick' }).execute(async function* () { return 'done'; }));
+ *
+ * const handle = await engine.start('quick', null);
+ * await handle.result();
+ * const anything = update<void, void>('anything');
+ * try {
+ *   await handle.update(anything);
+ * } catch (err) {
+ *   if (err instanceof WorkflowTerminalError) {
+ *     console.error('workflow', err.workflowId, 'is', err.status);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowTerminalError extends WeftError<'WorkflowTerminalError'> {
+    readonly workflowId: string;
+    readonly status: WorkflowStatus;
+    constructor(workflowId: string, status: WorkflowStatus);
+}
+/**
+ * Manages the lifecycle of synchronous workflow updates: persisting requests,
+ * checking idempotency, building response batch operations, and polling for
+ * results. Used internally by the {@link Engine}; callers interact through
+ * `engine.update` or `handle.update` rather than the coordinator directly.
+ *
+ * @example
+ * ```ts
+ * import { UpdateCoordinator } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const storage = new MemoryStorage();
+ * const coordinator = new UpdateCoordinator(storage);
+ * const updateId = await coordinator.createRequest('wf-1', 'increment', { by: 1 });
+ * console.log(updateId); // UUID string
+ * ```
+ */
+export declare class UpdateCoordinator {
+    #private;
+    constructor(storage: Storage);
+    /** Create and persist an update request. Returns the update ID. */
+    createRequest(workflowId: string, name: string, payload: unknown, options?: UpdateRequestOptions): Promise<string>;
+    /** Check idempotency: if this key was already processed, return the existing response. */
+    checkIdempotency(workflowId: string, idempotencyKey: string): Promise<UpdateResponse | null>;
+    /** Get pending update requests for a workflow, sorted FIFO by creation time. */
+    getPendingUpdates(workflowId: string): Promise<UpdateRequest[]>;
+    /** Build batch operations for persisting an update response (to be included in checkpoint batch). */
+    buildResponseOperations(updateId: string, workflowId: string, result: unknown, error?: string, idempotencyKey?: string): BatchOperation[];
+    /** Delete a pending update request that will never be observed. */
+    deleteRequest(workflowId: string, updateId: string): Promise<void>;
+    /**
+     * Atomically check whether a response exists and conditionally delete the
+     * request. Returns the response if the workflow already consumed this update,
+     * or null if the request was deleted before a consumer won the race.
+     */
+    deleteRequestIfUnconsumed(workflowId: string, updateId: string): Promise<UpdateResponse | null>;
+    /** Retrieve a stored response by update ID. */
+    getResponse(updateId: string): Promise<UpdateResponse | null>;
+    /** Wait for an update response with timeout. Uses polling. */
+    waitForResponse(updateId: string, timeout: number): Promise<UpdateResponse>;
+    /** Clean up expired responses and their orphaned idempotency mappings. */
+    cleanupExpiredResponses(ttlMs?: number): Promise<number>;
+}

package/dist/core/updates.js

@@ -0,0 +1,141 @@
+import { sleep } from "../runtime/portable.js";
+import { KEYS } from "../storage/interface.js";
+import { decode, encode } from "./codec.js";
+import { WeftError } from "./weft-error.js";
+
+export class UpdateTimeoutError extends WeftError {
+  updateId;
+  constructor(updateId, timeout) {
+    super("UpdateTimeoutError", `Update ${updateId} timed out after ${timeout}ms`);
+    this.updateId = updateId;
+  }
+}
+
+export class UpdateValidationError extends WeftError {
+  updateName;
+  issues;
+  constructor(updateName, issues) {
+    const summary = issues.map((i) => i.message).join("; ");
+    super("UpdateValidationError", `Update "${updateName}" rejected by validator: ${summary}`);
+    this.updateName = updateName;
+    this.issues = issues;
+  }
+}
+
+export class WorkflowTerminalError extends WeftError {
+  workflowId;
+  status;
+  constructor(workflowId, status) {
+    super("WorkflowTerminalError", `Cannot send update to workflow "${workflowId}": workflow is in terminal state "${status}"`);
+    this.workflowId = workflowId;
+    this.status = status;
+  }
+}
+const POLL_INTERVAL_MS = 50, DEFAULT_CLEANUP_TTL_MS = 300000;
+
+export class UpdateCoordinator {
+  #storage;
+  constructor(storage) {
+    this.#storage = storage;
+  }
+  async createRequest(workflowId, name, payload, options) {
+    const updateId = crypto.randomUUID(), request = {
+      updateId,
+      workflowId,
+      name,
+      payload,
+      createdAt: Date.now()
+    };
+    if (options?.idempotencyKey !== void 0)
+      request.idempotencyKey = options.idempotencyKey;
+    const key = KEYS.update(workflowId, updateId);
+    await this.#storage.put(key, encode(request));
+    return updateId;
+  }
+  async checkIdempotency(workflowId, idempotencyKey) {
+    const key = KEYS.updateIdempotency(workflowId, idempotencyKey), raw = await this.#storage.get(key);
+    if (!raw)
+      return null;
+    const mapping = decode(raw);
+    return this.getResponse(mapping.updateId);
+  }
+  async getPendingUpdates(workflowId) {
+    const prefix = KEYS.updatePrefix(workflowId), results = [];
+    for await (const [, value] of this.#storage.scan(prefix))
+      results.push(decode(value));
+    return results.toSorted((a, b) => a.createdAt - b.createdAt || (a.updateId < b.updateId ? -1 : a.updateId > b.updateId ? 1 : 0));
+  }
+  buildResponseOperations(updateId, workflowId, result, error, idempotencyKey) {
+    const response = {
+      updateId,
+      result,
+      createdAt: Date.now()
+    };
+    if (error !== void 0)
+      response.error = error;
+    const operations = [
+      { type: "delete", key: KEYS.update(workflowId, updateId) },
+      { type: "put", key: KEYS.updateResponse(updateId), value: encode(response) }
+    ];
+    if (idempotencyKey !== void 0)
+      operations.push({
+        type: "put",
+        key: KEYS.updateIdempotency(workflowId, idempotencyKey),
+        value: encode({ updateId })
+      });
+    return operations;
+  }
+  async deleteRequest(workflowId, updateId) {
+    await this.#storage.delete(KEYS.update(workflowId, updateId));
+  }
+  async deleteRequestIfUnconsumed(workflowId, updateId) {
+    const existing = await this.getResponse(updateId);
+    if (existing !== null)
+      return existing;
+    await this.deleteRequest(workflowId, updateId);
+    return this.getResponse(updateId);
+  }
+  async getResponse(updateId) {
+    const key = KEYS.updateResponse(updateId), raw = await this.#storage.get(key);
+    if (!raw)
+      return null;
+    return decode(raw);
+  }
+  async waitForResponse(updateId, timeout) {
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const response = await this.getResponse(updateId);
+      if (response)
+        return response;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0)
+        break;
+      await sleep(Math.min(POLL_INTERVAL_MS, remaining));
+    }
+    throw new UpdateTimeoutError(updateId, timeout);
+  }
+  async cleanupExpiredResponses(ttlMs) {
+    const effectiveTtl = ttlMs ?? DEFAULT_CLEANUP_TTL_MS, cutoff = Date.now() - effectiveTtl, expiredResponseKeys = [], expiredUpdateIds = new Set;
+    for await (const [key, value] of this.#storage.scan("upr:")) {
+      const response = decode(value);
+      if (response.createdAt < cutoff) {
+        expiredResponseKeys.push(key);
+        expiredUpdateIds.add(response.updateId);
+      }
+    }
+    if (expiredResponseKeys.length === 0)
+      return 0;
+    const orphanedIdempotencyKeys = [];
+    for await (const [key, value] of this.#storage.scan("upk:")) {
+      const mapping = decode(value);
+      if (expiredUpdateIds.has(mapping.updateId))
+        orphanedIdempotencyKeys.push(key);
+    }
+    const operations = [
+      ...expiredResponseKeys.map((key) => ({ type: "delete", key })),
+      ...orphanedIdempotencyKeys.map((key) => ({ type: "delete", key }))
+    ];
+    await this.#storage.batch(operations);
+    return expiredResponseKeys.length;
+  }
+}

package/dist/core/versioning.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Workflow version comparison and checkpoint migration.
+ *
+ * Provides utilities for detecting version mismatches between stored
+ * and registered workflow definitions, running checkpoint migrations,
+ * and building atomic batch operations for version updates.
+ *
+ * @module versioning
+ */
+import type { BatchOperation } from '../storage/interface.ts';
+import { WeftError } from './weft-error.ts';
+import type { WorkflowVersionDiff } from './workflow-version-tuple.ts';
+/** Default version string assigned when no version is specified. */
+export declare const DEFAULT_WORKFLOW_VERSION = "0.0.0";
+export type VersionCompatibility = 'compatible' | 'needs-migration' | 'incompatible';
+/**
+ * Compare a stored workflow version with the currently registered version.
+ *
+ * - `"compatible"` — versions match; no action needed.
+ * - `"needs-migration"` — versions differ and a migration function is available.
+ * - `"incompatible"` — versions differ and no migration is available; the engine
+ *   will throw a {@link VersionMismatchError} instead of resuming silently.
+ *
+ * @example
+ * ```ts
+ * import { checkVersionCompatibility } from '@lostgradient/weft';
+ *
+ * console.log(checkVersionCompatibility('1.0.0', '1.0.0', false)); // 'compatible'
+ * console.log(checkVersionCompatibility('1.0.0', '2.0.0', true));  // 'needs-migration'
+ * console.log(checkVersionCompatibility('1.0.0', '2.0.0', false)); // 'incompatible'
+ * ```
+ */
+export declare function checkVersionCompatibility(storedVersion: string, registeredVersion: string, hasMigration: boolean): VersionCompatibility;
+/**
+ * Run a migration function on checkpoint data, transforming it from one
+ * version to another.
+ *
+ * The caller is responsible for serializing the result back to bytes if needed.
+ *
+ * @example
+ * ```ts
+ * import { migrateCheckpoint } from '@lostgradient/weft';
+ *
+ * const oldData = { step: 0, locals: { counter: 1 }, version: '1.0.0' };
+ * const migrated = migrateCheckpoint(oldData, '1.0.0', '2.0.0', (data) => {
+ *   const d = data as typeof oldData;
+ *   return { ...d, locals: { ...d.locals, newField: 'default' } };
+ * });
+ * void migrated;
+ * ```
+ */
+export declare function migrateCheckpoint(checkpointData: unknown, fromVersion: string, _toVersion: string, migrate: (checkpoint: unknown, fromVersion: string) => unknown): unknown;
+/**
+ * Build batch operations that atomically update the checkpoint and workflow
+ * state after a successful migration.
+ *
+ * The returned operations are suitable for passing to `Storage.batch()`.
+ */
+export declare function buildVersionUpdateOperations(workflowId: string, newCheckpointBytes: Uint8Array, _newVersion: string, workflowStateBytes: Uint8Array): BatchOperation[];
+/** Description of a single field-level difference between checkpoint shapes. */
+export type FieldDiff = {
+    field: string;
+    change: 'added';
+    newType: string;
+} | {
+    field: string;
+    change: 'removed';
+    oldType: string;
+} | {
+    field: string;
+    change: 'type-changed';
+    oldType: string;
+    newType: string;
+};
+/** Shape descriptor: maps field names to their type names (e.g., `"string"`, `"object"`). */
+export type ShapeDescriptor = Record<string, string>;
+/**
+ * Compare two checkpoint shape descriptors and return the field-level diffs.
+ *
+ * Returns an empty array when the shapes are identical.
+ *
+ * @example
+ * ```ts
+ * import { diffCheckpointShapes } from '@lostgradient/weft';
+ *
+ * const diffs = diffCheckpointShapes(
+ *   { userId: 'string', count: 'number' },
+ *   { userId: 'string', count: 'number', newField: 'boolean' },
+ * );
+ * console.log(diffs.length);        // 1
+ * console.log(diffs[0]?.change);    // 'added'
+ * console.log(diffs[0]?.field);     // 'newField'
+ * ```
+ */
+export declare function diffCheckpointShapes(oldShape: ShapeDescriptor, newShape: ShapeDescriptor): FieldDiff[];
+/**
+ * Infer a shape descriptor from an arbitrary value by walking its top-level keys
+ * and recording the `typeof` of each value.
+ *
+ * @example
+ * ```ts
+ * import { inferShape } from '@lostgradient/weft';
+ *
+ * const shape = inferShape({ userId: 'abc', count: 42, active: true });
+ * console.log(shape['userId']); // 'string'
+ * console.log(shape['count']);  // 'number'
+ * console.log(shape['active']); // 'boolean'
+ * ```
+ */
+export declare function inferShape(value: unknown): ShapeDescriptor;
+/** Options for providing shape information to VersionMismatchError. */
+export type ShapeDiffOptions = {
+    oldShape: ShapeDescriptor;
+    newShape: ShapeDescriptor;
+};
+/**
+ * Thrown when a workflow's stored version does not match its registered
+ * version and no migration path is available or the migration failed.
+ *
+ * When shape information is provided, the error message includes a
+ * field-level diff describing exactly which fields changed.
+ *
+ * When version tuple information is provided, the error message includes a
+ * summary of which workflow, agent, or tool versions changed.
+ *
+ * @example
+ * ```ts
+ * import { VersionMismatchError } from '@lostgradient/weft';
+ *
+ * try {
+ *   throw new VersionMismatchError(
+ *     'wf-123',
+ *     'orderWorkflow',
+ *     '1.0.0',
+ *     '2.0.0',
+ *   );
+ * } catch (err) {
+ *   if (err instanceof VersionMismatchError) {
+ *     console.log(err.storedVersion);     // '1.0.0'
+ *     console.log(err.registeredVersion); // '2.0.0'
+ *   }
+ * }
+ * ```
+ */
+export declare class VersionMismatchError extends WeftError<'VersionMismatchError'> {
+    readonly workflowId: string;
+    readonly storedVersion: string;
+    readonly registeredVersion: string;
+    readonly workflowType: string;
+    readonly fieldDiffs: FieldDiff[] | undefined;
+    readonly versionDiff: WorkflowVersionDiff | undefined;
+    constructor(workflowId: string, workflowType: string, storedVersion: string, registeredVersion: string, shapeDiff?: ShapeDiffOptions, versionDiff?: WorkflowVersionDiff);
+}

package/dist/core/versioning.js

@@ -0,0 +1,94 @@
+import { KEYS } from "../storage/interface.js";
+import { WeftError } from "./weft-error.js";
+import { formatWorkflowVersionDiff } from "./workflow-version-tuple.js";
+export const DEFAULT_WORKFLOW_VERSION = "0.0.0";
+export function checkVersionCompatibility(storedVersion, registeredVersion, hasMigration) {
+  if (storedVersion === registeredVersion)
+    return "compatible";
+  return hasMigration ? "needs-migration" : "incompatible";
+}
+export function migrateCheckpoint(checkpointData, fromVersion, _toVersion, migrate) {
+  return migrate(checkpointData, fromVersion);
+}
+export function buildVersionUpdateOperations(workflowId, newCheckpointBytes, _newVersion, workflowStateBytes) {
+  return [
+    { type: "put", key: KEYS.checkpoint(workflowId), value: newCheckpointBytes },
+    { type: "put", key: KEYS.workflow(workflowId), value: workflowStateBytes }
+  ];
+}
+export function diffCheckpointShapes(oldShape, newShape) {
+  const diffs = [], allKeys = new Set([...Object.keys(oldShape), ...Object.keys(newShape)]);
+  for (const key of allKeys) {
+    const inOld = Object.hasOwn(oldShape, key), inNew = Object.hasOwn(newShape, key);
+    if (inOld && !inNew)
+      diffs.push({ field: key, change: "removed", oldType: oldShape[key] });
+    else if (!inOld && inNew)
+      diffs.push({ field: key, change: "added", newType: newShape[key] });
+    else if (inOld && inNew && oldShape[key] !== newShape[key])
+      diffs.push({
+        field: key,
+        change: "type-changed",
+        oldType: oldShape[key],
+        newType: newShape[key]
+      });
+  }
+  return diffs;
+}
+export function inferShape(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return {};
+  const shape = {};
+  for (const [key, val] of Object.entries(value))
+    shape[key] = val === null ? "null" : Array.isArray(val) ? "array" : typeof val;
+  return shape;
+}
+function formatFieldDiffs(diffs) {
+  if (diffs.length === 0)
+    return "";
+  return `
+Checkpoint shape changes:
+${diffs.map((diff) => {
+    switch (diff.change) {
+      case "added":
+        return `  - field \`${diff.field}\` was added (type: ${diff.newType})`;
+      case "removed":
+        return `  - field \`${diff.field}\` was removed (was: ${diff.oldType})`;
+      case "type-changed":
+        return `  - field \`${diff.field}\` changed type: ${diff.oldType} \u2192 ${diff.newType}`;
+    }
+  }).join(`
+`)}`;
+}
+function hasWorkflowVersionDiff(versionDiff) {
+  return versionDiff !== void 0 && (versionDiff.workflowVersion !== void 0 || versionDiff.agentVersion !== void 0 || (versionDiff.toolVersions?.length ?? 0) > 0);
+}
+function createVersionMismatchMessage(parameters) {
+  const { workflowId, workflowType, storedVersion, registeredVersion, fieldDiffs, versionDiff } = parameters;
+  return (storedVersion === registeredVersion && ((fieldDiffs?.length ?? 0) > 0 || hasWorkflowVersionDiff(versionDiff)) ? `Version mismatch for workflow "${workflowType}" (${workflowId}): stored version ${storedVersion} matches registered version ${registeredVersion}, but the persisted state is incompatible with the registered definition` : `Version mismatch for workflow "${workflowType}" (${workflowId}): stored version ${storedVersion} does not match registered version ${registeredVersion}`) + (fieldDiffs && fieldDiffs.length > 0 ? formatFieldDiffs(fieldDiffs) : "") + (versionDiff ? formatWorkflowVersionDiff(versionDiff) : "");
+}
+
+export class VersionMismatchError extends WeftError {
+  workflowId;
+  storedVersion;
+  registeredVersion;
+  workflowType;
+  fieldDiffs;
+  versionDiff;
+  constructor(workflowId, workflowType, storedVersion, registeredVersion, shapeDiff, versionDiff) {
+    const diffs = shapeDiff ? diffCheckpointShapes(shapeDiff.oldShape, shapeDiff.newShape) : void 0;
+    super("VersionMismatchError", createVersionMismatchMessage({
+      workflowId,
+      workflowType,
+      storedVersion,
+      registeredVersion,
+      fieldDiffs: diffs,
+      versionDiff
+    }));
+    this.workflowId = workflowId;
+    this.workflowType = workflowType;
+    this.storedVersion = storedVersion;
+    this.registeredVersion = registeredVersion;
+    this.fieldDiffs = diffs;
+    this.versionDiff = versionDiff;
+  }
+}

package/dist/core/weft-error.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Stable, machine-readable discriminant for every Weft error class that is
+ * part of the public API (re-exported from `@lostgradient/weft`). Each value equals the
+ * throwing class's name and is safe to `switch` on exhaustively. Errors not
+ * exported from `@lostgradient/weft` carry internal codes that are intentionally absent
+ * from this union and may change between releases.
+ *
+ * Prefer comparing `error.code` (or {@link isWeftErrorCode}) over `instanceof`
+ * when an error may have crossed a realm or duplicate-module boundary, where
+ * `instanceof` is unreliable.
+ *
+ * @example
+ * ```ts
+ * import { isWeftError, isWeftErrorCode, type WeftErrorCode } from '@lostgradient/weft';
+ *
+ * function statusFor(error: unknown): number {
+ *   if (isWeftError(error) && isWeftErrorCode(error.code)) {
+ *     const code: WeftErrorCode = error.code;
+ *     return code === 'WorkflowNotFoundError' ? 404 : 400;
+ *   }
+ *   return 500;
+ * }
+ * ```
+ */
+export type WeftErrorCode = 'WorkflowAlreadyExistsError' | 'BulkDeleteRequiresTerminalWorkflowsError' | 'BulkOperationConfirmationError' | 'WorkflowTypeNotRegisteredForRecoveryError' | 'EngineCreateNameMismatchError' | 'EngineDisposedError' | 'WorkflowNotFoundError' | 'WorkflowNotRegisteredError' | 'ActivityResolutionError' | 'PersistedDataIncompatibleError' | 'WorkflowTimeoutError' | 'HttpClientError' | 'WorkerProtocolIncompatibleError' | 'UpdateTimeoutError' | 'UpdateValidationError' | 'WorkflowTerminalError' | 'WorkflowBuilderError' | 'VersionMismatchError' | 'EffectReplayConflictError' | 'ReviewTimeoutError' | 'AtomicStateConflictError' | 'StandardSchemaValidationError' | 'ActivityReconciliationCapabilityError' | 'ActivityReconciliationConflictError' | 'ActivityReconciliationIndeterminateError' | 'AsyncActivityTokenNotFoundError' | 'PayloadSizeExceededError';
+/**
+ * Generic abstract base for all Weft library errors. The `TCode` parameter
+ * makes each subclass's `code` its own literal type; the exported base surface
+ * stays `code: string`, so internal (non-exported) error codes never leak into
+ * the public `.d.ts`.
+ *
+ * Subclasses pass their stable code to `super(...)`; the base assigns both
+ * `this.code` and `this.name` from it, so subclasses never set `this.name`
+ * themselves. `options` forwards `cause` to the `Error` constructor.
+ *
+ * @example
+ * ```ts
+ * import { WeftError } from '@lostgradient/weft';
+ *
+ * function describe(error: unknown): string {
+ *   return error instanceof WeftError ? `${error.code}: ${error.message}` : 'unknown';
+ * }
+ * ```
+ */
+export declare abstract class WeftError<TCode extends string = string> extends Error {
+    /** Stable machine-readable discriminant; equals the subclass name. */
+    readonly code: TCode;
+    constructor(code: TCode, message: string, options?: ErrorOptions);
+}
+/**
+ * Same-realm narrowing: `true` when `value` is a Weft library error instance.
+ * Use this for the common case of catching any Weft error. For comparisons
+ * that may cross a realm or duplicate-module boundary, narrow on
+ * {@link isWeftErrorCode} against `error.code` instead.
+ *
+ * @example
+ * ```ts
+ * import { isWeftError } from '@lostgradient/weft';
+ *
+ * function logFrom(error: unknown): string {
+ *   return isWeftError(error) ? `[${error.code}] ${error.message}` : 'non-weft error';
+ * }
+ * ```
+ */
+export declare function isWeftError(value: unknown): value is WeftError;
+/**
+ * Cross-boundary structural check: `true` when `value` is one of the public
+ * {@link WeftErrorCode} values. Pair with {@link isWeftError} to safely switch
+ * over public codes: `if (isWeftError(e) && isWeftErrorCode(e.code)) { ... }`.
+ *
+ * @example
+ * ```ts
+ * import { isWeftError, isWeftErrorCode } from '@lostgradient/weft';
+ *
+ * function isMissingWorkflow(error: unknown): boolean {
+ *   return isWeftError(error) && isWeftErrorCode(error.code)
+ *     ? error.code === 'WorkflowNotFoundError'
+ *     : false;
+ * }
+ * ```
+ */
+export declare function isWeftErrorCode(value: unknown): value is WeftErrorCode;