@lostgradient/weft 0.2.0

package/dist/client/http-operations.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP catalog transport for {@link HttpClient}.
+ *
+ * Posts JSON-RPC requests to the client's own `${baseUrl}/jsonrpc` endpoint
+ * using the client's configured headers. Unlike the CLI's
+ * {@link httpJsonRpcTransport}, this transport does not consult on-disk CLI
+ * profiles or run lockfiles — a programmatic {@link HttpClient} is constructed
+ * with an explicit `baseUrl` and headers, so connection resolution would be
+ * wrong here.
+ *
+ * @module client/http-operations
+ */
+import type { CatalogTransport } from '../cli/operation-client-runtime.ts';
+/**
+ * Build a {@link CatalogTransport} that dispatches catalog operations as
+ * JSON-RPC requests to a remote Weft server at `${baseUrl}/jsonrpc`.
+ *
+ * A JSON-RPC error envelope is surfaced as an {@link HttpClientError} so faults
+ * reach callers through the same error type the ergonomic HTTP methods use.
+ *
+ * The JSON-RPC endpoint always responds with HTTP 200 — even for operation
+ * faults — so the status for `HttpClientError` is taken from
+ * `error.data.httpStatus` in the envelope rather than `response.status`.
+ * Transport-level errors (405 Method Not Allowed, 415 Unsupported Media Type,
+ * 413 Payload Too Large, auth short-circuits) return non-JSON bodies;
+ * `response.json()` is wrapped in a try/catch to surface those as
+ * `HttpClientError` rather than a raw `SyntaxError`.
+ */
+export declare function httpClientCatalogTransport(baseUrl: string, headers: Record<string, string>): CatalogTransport;

package/dist/client/http-operations.js

@@ -0,0 +1,36 @@
+import { isFaultCode } from "../core/fault-code.js";
+import { HttpClientError } from "./http-request.js";
+function isJsonRpcFailure(value) {
+  return typeof value === "object" && value !== null && "error" in value && typeof value.error === "object" && value.error !== null && "message" in value.error && typeof value.error.message === "string";
+}
+function isJsonRpcSuccess(value) {
+  return typeof value === "object" && value !== null && "result" in value;
+}
+export function httpClientCatalogTransport(baseUrl, headers) {
+  const endpoint = `${baseUrl}/jsonrpc`;
+  return async (operationName, input) => {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { ...headers, "content-type": "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        method: operationName,
+        params: input,
+        id: operationName
+      })
+    });
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new HttpClientError(response.status, response.statusText || `HTTP ${response.status} from ${endpoint}`);
+    }
+    if (isJsonRpcFailure(body)) {
+      const { message, data } = body.error, httpStatus = typeof data?.httpStatus === "number" ? data.httpStatus : response.status, faultCode = isFaultCode(data?.weftCode) ? data.weftCode : void 0;
+      throw new HttpClientError(httpStatus, message, { faultCode });
+    }
+    if (isJsonRpcSuccess(body))
+      return body.result;
+    throw new HttpClientError(response.status, `Invalid JSON-RPC response from ${endpoint}`);
+  };
+}

package/dist/client/http-request.d.ts

@@ -0,0 +1,101 @@
+import { type FaultCode } from '../core/fault-code.ts';
+import type { FailureCategory } from '../core/types/identity.ts';
+import { WeftError } from '../core/weft-error.ts';
+import type { WebSocketFactory } from './event-stream-transport.ts';
+/**
+ * Configuration for the HTTP client.
+ *
+ * @example
+ * ```ts
+ * import { HttpClient, type HttpClientOptions } from '@lostgradient/weft';
+ *
+ * const options: HttpClientOptions = {
+ *   baseUrl: 'http://localhost:3000',
+ *   headers: { 'X-API-Key': 'my-secret-key' },
+ * };
+ * const client = new HttpClient(options);
+ * ```
+ */
+export interface HttpClientOptions {
+    /**
+     * Base URL of the Weft server (e.g. `http://localhost:3000`). Defaults to
+     * `WEFT_ADDR`, then the `~/.weft/config` profile, then `http://localhost:7233`
+     * when omitted.
+     */
+    baseUrl?: string;
+    /**
+     * Bearer token sent as `Authorization: Bearer <token>`. Defaults to
+     * `WEFT_TOKEN` or the profile token when omitted. An explicit
+     * `headers.Authorization` always wins; pass an empty string to suppress a
+     * resolved token entirely.
+     */
+    token?: string;
+    /** Optional headers to include on every request (e.g. auth tokens). */
+    headers?: Record<string, string>;
+    /**
+     * Override the WebSocket constructor used for live event streaming
+     * (`tail()` / push-based `handle.addEventListener`). Production omits this and
+     * the global `WebSocket` is used; tests inject a fake to drive the
+     * subscription protocol without a real socket.
+     */
+    webSocketFactory?: WebSocketFactory;
+}
+/**
+ * Resolve {@link HttpClientOptions} into the concrete `baseUrl` and request
+ * headers an {@link HttpClient} uses. With no `baseUrl`/`token`, the server
+ * address and bearer token come from {@link resolveConnection} (explicit
+ * options, then `WEFT_ADDR`/`WEFT_TOKEN`, then the `~/.weft/config` profile,
+ * then `http://localhost:7233`). The CLI-only run lockfile is never consulted.
+ * A caller-supplied `headers.Authorization` always takes precedence over a
+ * resolved token; pass an empty `token` to suppress a resolved token entirely.
+ */
+export declare function resolveHttpClientConnection(options: HttpClientOptions): {
+    baseUrl: string;
+    headers: Record<string, string>;
+};
+/**
+ * Error thrown when the server returns a non-2xx response.
+ *
+ * When the server sends a structured fault body (`{ error: { code, message } }`),
+ * the wire fault `code` is surfaced as {@link HttpClientError.faultCode} and a
+ * derived {@link HttpClientError.category} so callers can branch programmatically
+ * instead of string-matching `message`. Both are `undefined` when the body is a
+ * plain `{ error: string }` or carries no recognized code.
+ *
+ * @example
+ * ```ts
+ * import { HttpClient, HttpClientError } from '@lostgradient/weft';
+ *
+ * const client = new HttpClient({ baseUrl: 'http://localhost:3000' });
+ * try {
+ *   await client.cancel('nonexistent-id');
+ * } catch (err) {
+ *   if (err instanceof HttpClientError) {
+ *     if (err.faultCode === 'NotFound') {
+ *       // handle a missing resource specifically
+ *     } else if (err.category === 'resource') {
+ *       // back off on rate limits and capacity faults
+ *     }
+ *     console.error('HTTP', err.status, err.faultCode ?? err.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class HttpClientError extends WeftError<'HttpClientError'> {
+    /** HTTP status code of the failed response. */
+    readonly status: number;
+    /**
+     * The server's stable wire fault code, when the response carried a structured
+     * fault body. `undefined` for plain-string error bodies or unrecognized codes.
+     */
+    readonly faultCode?: FaultCode | undefined;
+    /**
+     * The {@link FailureCategory} derived from {@link faultCode}. Derived, not
+     * carried on the wire; `undefined` when `faultCode` is `undefined`.
+     */
+    readonly category?: FailureCategory | undefined;
+    constructor(status: number, message: string, options?: {
+        faultCode?: FaultCode | undefined;
+    });
+}
+export declare function request<T>(baseUrl: string, path: string, baseHeaders: Record<string, string>, options?: RequestInit): Promise<T>;

package/dist/client/http-request.js

@@ -0,0 +1,73 @@
+import { resolveConnection } from "../connection.js";
+import { failureCategoryForFaultCode, isFaultCode } from "../core/fault-code.js";
+import { WeftError } from "../core/weft-error.js";
+export function resolveHttpClientConnection(options) {
+  const connection = resolveConnection({
+    includeRunLockfile: !1,
+    ...options.baseUrl !== void 0 ? { server: options.baseUrl } : {},
+    ...options.token !== void 0 ? { token: options.token } : {}
+  }), baseUrl = connection.server.toString().replace(/\/+$/, ""), headers = new Headers(options.headers);
+  if (connection.token !== void 0 && connection.token !== "" && !headers.has("Authorization"))
+    headers.set("Authorization", `Bearer ${connection.token}`);
+  return { baseUrl, headers: Object.fromEntries(headers.entries()) };
+}
+
+export class HttpClientError extends WeftError {
+  status;
+  faultCode;
+  category;
+  constructor(status, message, options) {
+    super("HttpClientError", message);
+    this.status = status;
+    this.faultCode = options?.faultCode;
+    this.category = options?.faultCode === void 0 ? void 0 : failureCategoryForFaultCode(options.faultCode);
+  }
+}
+function buildRequestHeaders(baseHeaders, options) {
+  const headers = new Headers(baseHeaders);
+  if (options?.headers) {
+    const extra = new Headers(options.headers);
+    for (const [key, value] of extra)
+      headers.set(key, value);
+  }
+  if (options?.body && !headers.has("Content-Type"))
+    headers.set("Content-Type", "application/json");
+  return headers;
+}
+function isFlatErrorBody(value) {
+  return value !== null && typeof value === "object" && typeof value.error === "string";
+}
+function isStructuredErrorBody(value) {
+  if (value === null || typeof value !== "object")
+    return !1;
+  const error = value.error;
+  if (error === null || typeof error !== "object")
+    return !1;
+  return typeof error.message === "string";
+}
+async function parseErrorBody(response) {
+  try {
+    const body = await response.json();
+    if (isStructuredErrorBody(body)) {
+      const { code, message } = body.error;
+      return isFaultCode(code) ? { message, faultCode: code } : { message };
+    }
+    if (isFlatErrorBody(body) && body.error)
+      return { message: body.error };
+    return { message: response.statusText };
+  } catch {
+    return { message: response.statusText };
+  }
+}
+export async function request(baseUrl, path, baseHeaders, options) {
+  const headers = buildRequestHeaders(baseHeaders, options), response = await fetch(`${baseUrl}/v1${path}`, { ...options, headers });
+  if (response.status === 404 && (!options?.method || options.method === "GET"))
+    return null;
+  if (!response.ok) {
+    const { message, faultCode } = await parseErrorBody(response);
+    throw new HttpClientError(response.status, message, { faultCode });
+  }
+  if (response.status === 204)
+    return;
+  return response.json();
+}

package/dist/client/http-schedule-handle.d.ts

@@ -0,0 +1,5 @@
+import { ScheduleHandleDelegation } from './handle-delegation.ts';
+import type { HttpClient } from './http-client.ts';
+export declare class HttpScheduleHandle extends ScheduleHandleDelegation<HttpClient> {
+    [Symbol.dispose](): void;
+}

package/dist/client/http-schedule-handle.js

@@ -0,0 +1,5 @@
+import { ScheduleHandleDelegation } from "./handle-delegation.js";
+
+export class HttpScheduleHandle extends ScheduleHandleDelegation {
+  [Symbol.dispose]() {}
+}

package/dist/client/in-process-operations.d.ts

@@ -0,0 +1,30 @@
+/**
+ * In-process catalog transport for {@link LocalClient}.
+ *
+ * The generated catalog client ({@link createWeftClient}) speaks JSON-RPC over
+ * HTTP by default. For the embedded library client there is no server to talk
+ * to, so this module supplies a {@link CatalogTransport} that routes the exact
+ * same operation calls straight through the shared `executeOperation` pipeline
+ * against a local {@link Engine}.
+ *
+ * This is the seam that lets `LocalClient` and `HttpClient` expose one
+ * generated low-level surface — `client.operations.<op>` / `client.call(op,
+ * input)` — covering every catalog operation, not just the curated ergonomic
+ * methods, while still routing local calls to the in-process engine.
+ *
+ * @module client/in-process-operations
+ */
+import type { CatalogTransport } from '../cli/operation-client-runtime.ts';
+import type { Engine } from '../core/engine.ts';
+/**
+ * Build a {@link CatalogTransport} that dispatches catalog operations against
+ * an in-process {@link Engine}.
+ *
+ * The registry and trusted principal are constructed once and reused across
+ * calls. Operations run with `transport: 'jsonRpcHttp'` so input/output
+ * validation and unknown-key handling match the remote JSON-RPC path exactly.
+ * A failed dispatch throws with the fault message, mirroring the HTTP
+ * transport's `throw new Error(result.error.message)` contract so both clients
+ * surface operation faults the same way.
+ */
+export declare function inProcessCatalogTransport(engine: Engine): CatalogTransport;

package/dist/client/in-process-operations.js

@@ -0,0 +1,17 @@
+import { executeOperation } from "../server/operation-catalog.js";
+import { principalFromStdioLocal } from "../server/principal.js";
+import { createLiveOperationRegistry } from "../server/rest-bindings.js";
+export function inProcessCatalogTransport(engine) {
+  const registry = createLiveOperationRegistry(), principal = principalFromStdioLocal();
+  return async (operationName, input) => {
+    const result = await executeOperation(operationName, input, {
+      principal,
+      engine,
+      transport: "jsonRpcHttp",
+      registry
+    });
+    if (!result.ok)
+      throw Error(result.fault.message);
+    return result.value;
+  };
+}

package/dist/client/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * HTTP client for a remote Weft server. Communicates over the REST API
+ * exposed by {@link handleRequest}.
+ *
+ * Implements the same {@link WeftClient} interface as {@link LocalClient},
+ * so switching from server mode to library mode is a constructor change.
+ *
+ * @module client/index
+ */
+export type { WorkflowEventTail } from './event-tail.ts';
+export { HttpClient } from './http-client.ts';
+export { HttpClientError } from './http-request.ts';
+export type { HttpClientOptions } from './http-request.ts';
+export type { ClientHandle, ClientScheduleHandle, UpdateResult, WeftClient, WeftClientActivity, } from './interface.ts';
+export type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';

package/dist/client/index.js

@@ -0,0 +1,2 @@
+export { HttpClient } from "./http-client.js";
+export { HttpClientError } from "./http-request.js";

package/dist/client/interface.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Shared client interface for Weft. Both {@link LocalClient} and
+ * {@link HttpClient} implement this contract so switching between
+ * library mode and server mode is a constructor change, not an API change.
+ *
+ * @module client/interface
+ */
+import type { CatalogOperationName, CatalogOperationTypes, WeftClient as CatalogOperations } from '../cli/generated/operation-client.generated.ts';
+import type { StoredStreamChunk } from '../core/context.ts';
+import type { TypedEventTarget, WeftEventMap } from '../core/events.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { WorkflowEventTail } from './event-tail.ts';
+import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';
+/**
+ * A reference to a workflow that provides convenience methods.
+ *
+ * Extends {@link TypedEventTarget} so callers can observe workflow lifecycle
+ * events with the same `addEventListener` / `removeEventListener` API in both
+ * library mode (events flow through `EventTarget` directly) and server mode
+ * (events are bridged over WebSocket).
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, MemoryStorage, LocalClient, type WorkflowCompletedEvent } from '@lostgradient/weft';
+ * import type { ClientHandle } from '@lostgradient/weft/client';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ *
+ * const client = new LocalClient(engine);
+ * const handle: ClientHandle = await client.start('ping', null);
+ * handle.addEventListener('workflow:completed', (e) => {
+ *   console.log('completed', (e as WorkflowCompletedEvent).result);
+ * });
+ * const result = await handle.result();
+ * console.log(result); // 'pong'
+ * ```
+ *
+ * The `TResult` parameter carries the workflow's output type. It defaults to
+ * `unknown`, so untyped (string-name) call sites are unaffected. When a
+ * project augments {@link WorkflowRegistry} (typically via `weft codegen`),
+ * the typed `start` overload returns `ClientHandle<WorkflowOutput<...>>` and
+ * `result()` is narrowed to that workflow's output.
+ *
+ * The narrowing is a compile-time projection of the registered output schema,
+ * exactly as `engine.start` returns a typed `WorkflowHandle<TOutput>` over a
+ * runtime handle whose `result()` is structurally `Promise<unknown>`. The
+ * concrete handles (`LocalHandle`, `HttpHandle`) stay non-generic; the static
+ * type reflects the schema the project opted into via codegen, not an extra
+ * runtime guarantee.
+ */
+export interface ClientHandle<TResult = unknown> extends TypedEventTarget<WeftEventMap>, Disposable {
+    /** The workflow's unique identifier. */
+    readonly id: string;
+    /** Resolves when the workflow completes (or rejects on failure). */
+    result(): Promise<TResult>;
+    /** Cancel this workflow. */
+    cancel(): Promise<void>;
+    /** Send a named signal with an optional payload. */
+    signal(name: SignalDefinition): Promise<void>;
+    signal<TInput>(name: SignalDefinition<TInput>, payload: TInput, options?: SignalDeliveryOptions): Promise<void>;
+    signal(name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
+    /** Submit a synchronous update and return the handler's result. */
+    update<TOutput>(name: UpdateDefinition<void, TOutput>, payload?: void, options?: {
+        timeout?: number;
+    }): Promise<TOutput>;
+    update<TInput, TOutput>(name: UpdateDefinition<TInput, TOutput>, payload: TInput, options?: {
+        timeout?: number;
+    }): Promise<TOutput>;
+    update(name: string, payload?: unknown, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    /** Query a named read-only accessor on the running workflow. */
+    query<TOutput>(name: QueryDefinition<void, TOutput>): Promise<TOutput>;
+    query<TInput, TOutput>(name: QueryDefinition<TInput, TOutput>, input: TInput): Promise<TOutput>;
+    query(name: string, input?: unknown): Promise<unknown>;
+    /** Get search attributes for this workflow. */
+    getAttributes(): Promise<Record<string, SearchAttributeValue> | null>;
+    /** Set search attributes on this workflow (merge semantics). */
+    setAttributes(attributes: Record<string, SearchAttributeValue>): Promise<void>;
+    /** Add free-form tags to this workflow. */
+    addTags(...tags: string[]): Promise<void>;
+    /** Remove free-form tags from this workflow. */
+    removeTags(...tags: string[]): Promise<void>;
+    /**
+     * Open a live, push-based tail of this workflow's events. Async-iterate the
+     * returned {@link WorkflowEventTail} to consume events as they happen. In
+     * server mode this rides the WebSocket watch channel (no polling); in library
+     * mode it bridges the engine's event stream directly.
+     */
+    tail(): WorkflowEventTail;
+    /**
+     * Resolves once this handle's live event subscription is connected, opening
+     * it if necessary. Await this after attaching `addEventListener` listeners
+     * and before triggering work whose events you intend to observe, so nothing
+     * is missed in the window before the underlying transport connects. In
+     * library mode it resolves immediately — engine events are already live.
+     */
+    whenConnected(): Promise<void>;
+}
+/**
+ * A reference to a recurring schedule that provides convenience methods.
+ *
+ * Mirrors the core {@link ScheduleHandle} surface without leaking the engine
+ * implementation type into the transport-neutral client contract.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, MemoryStorage, LocalClient } from '@lostgradient/weft';
+ * import type { ClientScheduleHandle } from '@lostgradient/weft/client';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * engine.register(workflow({ name: 'report' }).execute(async function* () { return 'sent'; }));
+ *
+ * const client = new LocalClient(engine);
+ * const handle: ClientScheduleHandle = await client.schedule('report', {}, '0 9 * * 1');
+ * await handle.pause();
+ * console.log(handle.id);
+ * ```
+ */
+export interface ClientScheduleHandle extends Disposable {
+    /** The schedule's unique identifier. */
+    readonly id: string;
+    /** Pause this schedule. */
+    pause(): Promise<void>;
+    /** Resume this schedule. */
+    resume(): Promise<void>;
+    /** Cancel this schedule. */
+    cancel(): Promise<void>;
+    /** Update the schedule's recurrence specification (cron string or interval spec). */
+    update(newSpec: string | ScheduleSpec): Promise<void>;
+    /** Read the latest persisted summary for this schedule. */
+    describe(): Promise<ScheduleSummary | null>;
+}
+/** Result of a coordinated update request. */
+export type UpdateResult = {
+    updateId: string;
+    result?: unknown;
+    error?: string;
+} | null;
+/**
+ * Out-of-band ("async") activity completion surface, shared by every client.
+ *
+ * An activity that called `ActivityContext.completeAsync()` parks its workflow
+ * until an external system resolves it by the durable task token announced on
+ * the engine's `activity:async-pending` event. Library mode calls the engine
+ * directly; server mode POSTs to `/v1/activities/{complete,fail}`. After a
+ * restart, wait for recovery to settle first — a completion racing `recoverAll()`
+ * consumes the single-use token before re-adoption and strands the workflow. The
+ * token is a deterministic identifier, not a secret (see `completeAsync`).
+ *
+ * @example
+ * ```ts
+ * import { Engine, LocalClient, type WeftClientActivity } from '@lostgradient/weft';
+ *
+ * const activity: WeftClientActivity = new LocalClient(new Engine()).activity;
+ * // `token` comes from the engine's `activity:async-pending` event:
+ * // await activity.complete(token, { approved: true });
+ * void activity;
+ * ```
+ */
+export interface WeftClientActivity {
+    /** Complete a deferred activity by token, resuming its workflow with `result` (optional; omitted/`undefined` resumes with `undefined`). */
+    complete(token: string, result?: unknown): Promise<void>;
+    /** Fail a deferred activity by token; the error is thrown into its workflow. */
+    completeExceptionally(token: string, error: unknown): Promise<void>;
+}
+/**
+ * Operations shared by both in-process and HTTP clients.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, MemoryStorage, LocalClient, type WeftClient } from '@lostgradient/weft';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * engine.register(workflow({ name: 'my-workflow' }).execute(async function* () { return 42; }));
+ * const client: WeftClient = new LocalClient(engine);
+ * const handle = await client.start('my-workflow', { input: 42 });
+ * const result = await handle.result();
+ * console.log(result); // 42
+ * ```
+ */
+export interface WeftClient {
+    /**
+     * Start a new workflow and return a handle to it.
+     *
+     * When the {@link WorkflowRegistry} is augmented (e.g. via `weft codegen`),
+     * the workflow name narrows `input` to that workflow's input type and the
+     * returned handle's `result()` to its output type. Without augmentation the
+     * permissive string-name overload applies, so the client stays usable with
+     * plain string names and no hard dependency on codegen.
+     */
+    start<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, options?: StartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    start<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, options?: StartOptions): Promise<ClientHandle>;
+    /**
+     * Register a recurring schedule (cron string or interval spec) and return a
+     * handle to it.
+     *
+     * Like {@link WeftClient.start}, the workflow name narrows `input` to the
+     * registered workflow's input type when the {@link WorkflowRegistry} is
+     * augmented; otherwise the string-name overload applies.
+     */
+    schedule<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
+    schedule<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
+    /** Get the full persisted state of a workflow, or `null` if not found. */
+    get(id: string): Promise<WorkflowState | null>;
+    /** Get the current summary of a recurring schedule, or `null` if not found. */
+    getSchedule(id: string): Promise<ScheduleSummary | null>;
+    /** List workflows with optional filtering and pagination. */
+    list<const TAttributeKeys extends readonly AttributeFilterKey[] = readonly AttributeFilterKey[]>(filter?: TypedListFilter<TAttributeKeys>): Promise<PaginatedResult<WorkflowSummary>>;
+    /** List recurring schedules with optional filtering and pagination. */
+    listSchedules(filter?: ScheduleFilter): Promise<PaginatedResult<ScheduleSummary>>;
+    /** Cancel a running workflow. */
+    cancel(id: string): Promise<void>;
+    /** Pause a recurring schedule. */
+    pauseSchedule(id: string): Promise<void>;
+    /** Resume a recurring schedule. */
+    resumeSchedule(id: string): Promise<void>;
+    /** Cancel a recurring schedule. */
+    cancelSchedule(id: string): Promise<void>;
+    /** Update a recurring schedule's recurrence specification (cron string or interval spec). */
+    updateSchedule(id: string, newSpec: string | ScheduleSpec): Promise<void>;
+    /** Send a named signal to a workflow. */
+    signal(id: string, name: SignalDefinition): Promise<void>;
+    signal<TInput>(id: string, name: SignalDefinition<TInput>, payload: TInput, options?: SignalDeliveryOptions): Promise<void>;
+    signal(id: string, name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
+    /** Query a named read-only accessor on a running workflow. */
+    query<TOutput>(id: string, name: QueryDefinition<void, TOutput>): Promise<TOutput>;
+    query<TInput, TOutput>(id: string, name: QueryDefinition<TInput, TOutput>, input: TInput): Promise<TOutput>;
+    query(id: string, name: string, input?: unknown): Promise<unknown>;
+    /** Submit a synchronous update to a running workflow. */
+    update<TOutput>(id: string, name: UpdateDefinition<void, TOutput>, payload?: void, options?: {
+        timeout?: number;
+    }): Promise<TOutput>;
+    update<TInput, TOutput>(id: string, name: UpdateDefinition<TInput, TOutput>, payload: TInput, options?: {
+        timeout?: number;
+    }): Promise<TOutput>;
+    update(id: string, name: string, payload?: unknown, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    /** Out-of-band ("async") activity completion by task token. See {@link WeftClientActivity}. */
+    readonly activity: WeftClientActivity;
+    /** Resume a failed or timed-out workflow. */
+    resume(id: string): Promise<ClientHandle>;
+    /** Recover all interrupted workflows. */
+    recoverAll(): Promise<ClientHandle[]>;
+    /** Force-timeout a workflow. */
+    timeout(id: string): Promise<void>;
+    /** Get search attributes for a workflow. */
+    getAttributes(id: string): Promise<Record<string, SearchAttributeValue> | null>;
+    /** Set search attributes on a workflow. */
+    setAttributes(id: string, attributes: Record<string, SearchAttributeValue>): Promise<void>;
+    /** Add free-form tags to a workflow. */
+    addTags(id: string, ...tags: string[]): Promise<void>;
+    /** Remove free-form tags from a workflow. */
+    removeTags(id: string, ...tags: string[]): Promise<void>;
+    /** Get the event history for a workflow. */
+    getEvents(id: string): Promise<WorkflowEvent[]>;
+    /**
+     * Open a live, push-based tail of a workflow's events. Async-iterate the
+     * returned {@link WorkflowEventTail} to consume events as they happen. In
+     * server mode this rides the per-workflow `/v1/workflows/:id/watch` WebSocket
+     * channel (replacing the old 2-second poll); in library mode it bridges the
+     * engine's event stream directly. Both transports deliver the same
+     * {@link WorkflowEvent} records and terminate cleanly on completion or close.
+     */
+    tail(id: string): WorkflowEventTail;
+    /**
+     * Get the structured execution timeline for a workflow.
+     * Returns `[]` when the workflow is missing or has no retained timeline entries.
+     */
+    getTimeline(id: string): Promise<WorkflowTimelineEntry[]>;
+    /** Reconstruct workflow state at a historical checkpoint step. */
+    replayTo(id: string, step: number): Promise<WorkflowReplay | null>;
+    /** List human review requests, optionally filtering by status or workflow metadata. */
+    listReviews(filter?: ReviewListFilter): Promise<ReviewListEntry[]>;
+    /** Submit a decision for a pending review. */
+    submitReview(reviewId: string, options: SubmitReviewOptions): Promise<void>;
+    /** Read stream chunks back from storage for a completed stream operation. */
+    getStreamChunks(workflowId: string, key: string, options?: {
+        after?: number;
+    }): Promise<StoredStreamChunk[]>;
+    /** Fork a workflow from its latest or a historical checkpoint. */
+    fork(id: string, options?: ForkOptions): Promise<ClientHandle>;
+    /** Get the configured workflow retention policies and next sweep time. */
+    getRetentionOverview(): Promise<RetentionOverview>;
+    /** Purge matching terminal workflows. */
+    purge(filter?: ListFilter): Promise<PurgeResult>;
+    /** Cancel all running or pending workflows that match a filter. */
+    cancelAll(filter: ListFilter): Promise<BulkCancelResult>;
+    /** Signal all running or pending workflows that match a filter. */
+    signalAll(filter: ListFilter, name: string, payload?: unknown): Promise<BulkSignalResult>;
+    /** Delete all matching terminal workflows. */
+    deleteAll(filter: ListFilter): Promise<BulkDeleteResult>;
+    /** Add tags to all workflows that match a filter. */
+    tagAll(filter: ListFilter, tags: string[]): Promise<BulkTagResult>;
+    /** Remove tags from all workflows that match a filter. */
+    untagAll(filter: ListFilter, tags: string[]): Promise<BulkTagResult>;
+    /** Submit a coordinated update and wait for the result. */
+    submitCoordinatedUpdate(id: string, name: string, payload?: unknown, options?: {
+        timeout?: number;
+        idempotencyKey?: string;
+    }): Promise<CoordinatedUpdateResult>;
+    /** Retrieve the result of a previously submitted coordinated update. */
+    getUpdateResult(updateId: string): Promise<UpdateResult>;
+    /**
+     * Typed low-level accessor for the full operation catalog.
+     *
+     * Every catalog operation is reachable as `client.operations['weft.<op>']`,
+     * including server operations the ergonomic surface does not curate (workers,
+     * task queues, task diagnostics, system metrics/registry, checkpoints). New
+     * catalog operations appear here automatically when the snapshot regenerates,
+     * so the client never drifts behind the server.
+     *
+     * @example
+     * ```ts
+     * import { workflow, Engine, MemoryStorage, LocalClient } from '@lostgradient/weft';
+     *
+     * await using engine = new Engine({ storage: new MemoryStorage() });
+     * engine.register(workflow({ name: 'noop' }).execute(async function* () {}));
+     * const client = new LocalClient(engine);
+     * const metrics = await client.operations['weft.system.metrics']({});
+     * void metrics;
+     * ```
+     */
+    readonly operations: CatalogOperations;
+    /**
+     * Invoke a single catalog operation by name, with its input and output typed
+     * from the generated catalog. Equivalent to `client.operations[name](input)`
+     * but ergonomic when the operation name is known dynamically.
+     */
+    call<Name extends CatalogOperationName>(name: Name, input: CatalogOperationTypes[Name]['input']): Promise<CatalogOperationTypes[Name]['output']>;
+}